Opik Backend 端点权限RequiredPermissions接入指南从权限枚举到 JAX-RS 资源注解的完整实践【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm导读本文面向 Opik 后端opik-backend的开发者与贡献者系统讲解在v1/priv/私有 API 资源上接入细粒度权限控制的标准流程。你将掌握WorkspaceUserPermission权限枚举的完整结构、RequiredPermissions注解的底层解析与鉴权链路RequiredPermissionsResolver→AuthDynamicFeature→AuthFilter、以及新增或修改资源端点时判断该加权限还是该回退到团队成员认证的决策方法并理解未标注权限即回退这一当前设计约束。一、背景端点权限体系的设计定位Opik 是用于调试、评估与监控 LLM 应用包括 RAG 系统与 Agent 工作流的可观测性平台。后端基于 JAX-RS 构建所有需要工作区级身份与权限校验的端点位于apps/opik-backend/src/main/java/com/comet/opik/api/resources/v1/priv/目录下。该目录下的资源在请求进入业务逻辑之前会统一经过AuthFilter见 AuthFilter.java的身份认证与权限校验。权限控制的基本模型是团队workspace成员身份是认证的底线所有私有端点默认至少要求有效的团队成员会话细粒度权限如DATASET_VIEW、TRACE_DELETE是叠加在成员身份之上的授权约束通过方法级注解RequiredPermissions声明未标注RequiredPermissions的端点会自然回退到仅团队成员身份认证这是当前有意为之的设计并非遗漏。二、权限枚举WorkspaceUserPermission 全量清单权限值的唯一权威来源是 WorkspaceUserPermission.java。它是一组枚举常量每个枚举项通过JsonValue绑定一个字符串值value该字符串才是实际参与鉴权校验的权限标识。当前仓库中定义的完整权限清单如下权限枚举权限字符串值value适用操作WORKSPACE_SETTINGS_CONFIGUREworkspace_settings_configure工作区设置配置AI_PROVIDER_UPDATEai_provider_updateLLM Provider 密钥等更新PROJECT_CREATEproject_create创建项目PROJECT_DATA_VIEWproject_data_view查看项目数据PROJECT_DELETEproject_delete删除项目TRACE_SPAN_THREAD_LOGtrace_span_thread_log写入 trace / span / thread 数据TRACE_SPAN_THREAD_ANNOTATEtrace_span_thread_annotate对 trace / span / thread 进行标注annotationTRACE_DELETEtrace_delete删除 traceONLINE_EVALUATION_RULE_UPDATEonline_evaluation_rule_update更新在线评测规则ALERT_UPDATEalert_update更新告警ORIGINAL_DATA_VIEWoriginal_data_view读取原始非脱敏存储内容DASHBOARD_VIEWdashboard_view查看仪表盘DASHBOARD_CREATEdashboard_create创建仪表盘DASHBOARD_EDITdashboard_edit编辑仪表盘DASHBOARD_DELETEdashboard_delete删除仪表盘EXPERIMENT_VIEWexperiment_view查看实验EXPERIMENT_CREATEexperiment_create创建实验DATASET_VIEWdataset_view查看数据集DATASET_CREATEdataset_create创建数据集DATASET_EDITdataset_edit编辑数据集DATASET_DELETEdataset_delete删除数据集ANNOTATION_QUEUE_VIEWannotation_queue_view查看标注队列ANNOTATION_QUEUE_CREATEannotation_queue_create创建标注队列ANNOTATION_QUEUE_ANNOTATEannotation_queue_annotate在队列上下文中执行标注ANNOTATION_QUEUE_EDITannotation_queue_edit编辑标注队列ANNOTATION_QUEUE_DELETEannotation_queue_delete删除标注队列ANNOTATION_QUEUE_RESULTS_EXPORTannotation_queue_results_export导出标注队列结果PROMPT_VIEWprompt_view查看提示词PromptPROMPT_CREATEprompt_create创建提示词PROMPT_EDITprompt_edit编辑提示词PROMPT_DELETEprompt_delete删除提示词OPTIMIZATION_RUN_VIEWoptimization_run_view查看优化运行OPTIMIZATION_RUN_DELETEoptimization_run_delete删除优化运行OPTIMIZATION_STUDIO_USEoptimization_studio_use使用优化工作室其中ORIGINAL_DATA_VIEW是一个值得注意的跨域权限。正如源码注释所说明的它并不局限于 trace 命名它统一约束所有存储内容的读取脱敏read-time redaction可达范围——包括 traces、spans、threads、experiments、datasets、runner jobs 与 analytics results。因此凡是提供读取原始数据能力的端点都应审视该权限而非机械套用 trace 命名规则。从命名规律看多数实体遵循ENTITY_ACTION的成组结构如DATASET_VIEW/CREATE/EDIT/DELETE但权限的实际映射必须依据端点行为判断不能仅靠命名模式。三、注解机制与鉴权链路RequiredPermissions 是如何生效的3.1 注解定义RequiredPermissions是一个方法级Target(ElementType.METHOD)、运行时保留Retention(RetentionPolicy.RUNTIME)的注解其唯一属性是WorkspaceUserPermission[] value()支持一次声明多个权限见 RequiredPermissions.javaTarget(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) public interface RequiredPermissions { WorkspaceUserPermission[] value(); }3.2 解析与传递注解的解析发生在 JAX-RS 请求匹配完成之后、资源方法被调用之前由三层组件协作完成RequiredPermissionsResolverRequiredPermissionsResolver.java从ResourceInfo中取出当前匹配的资源方法读取RequiredPermissions注解并把枚举数组转换为权限字符串列表WorkspaceUserPermission.getValue()。若方法未标注注解或注解为空则返回空列表。AuthDynamicFeatureAuthDynamicFeature.java作为 JAX-RSDynamicFeature在每个资源匹配后注册请求过滤器将解析出的权限列表写入请求上下文属性auth.requiredPermissions常量REQUIRED_PERMISSIONS_PROPERTY随后调用AuthFilter。AuthFilterAuthFilter.java对匹配/v1/private/.*或/v1/internal/analytics-queries.*的请求统一执行认证。认证通过后把从请求上下文取回的requiredPermissions连同 URI 信息、HTTP 方法一起构建成ContextInfoHolder交给AuthService或 MCP OAuth / Cipx Token 校验路径完成授权判定。这条链路的关键点在于权限声明是声明式的鉴权强制执行是横切cross-cutting的——开发者只需在端点方法上加一个注解认证与授权逻辑便自动生效无需在每个方法内手写权限判断。3.3 多权限与 ORIGINAL_DATA_VIEW 等组合场景由于注解接受权限数组一个端点可以同时声明多个权限约束。同时AuthFilter中对不同令牌类型的分支普通会话 →authService.authenticate、MCP OAuth 令牌 →authService.authorizeOAuth、Cipx 令牌 →cipxTokenValidationService.authenticate都会把同一份requiredPermissions带入授权上下文保证三种认证通道的权限语义一致。四、新增或修改资源端点时的权限评估流程当你在v1/priv/下新增或修改一个 JAX-RS 端点方法时应按下述流程判断是否需要RequiredPermissions注解4.1 步骤 1读取当前权限枚举首先通读 WorkspaceUserPermission.java确认当前仓库已有哪些权限值避免重复造轮子。4.2 步骤 2检查同资源其他方法查看目标资源类中的兄弟方法是否已经使用了RequiredPermissions。例如在 DatasetsResource.java 中DATASET_VIEW、DATASET_CREATE、DATASET_EDIT、DATASET_DELETE分别覆盖了该资源的主要读写删操作。如果同类资源的大部分方法都已声明权限新端点通常也需要声明对应权限。4.3 步骤 3按操作的逻辑语义匹配权限而非命名模式这是整个流程中最关键的一步依据端点实际做什么来匹配权限而不是看方法名像什么读 / 列表 / 按 ID 获取类端点 → 映射该领域实体的view权限如DATASET_VIEW、EXPERIMENT_VIEW创建 / 写入 / 记录类端点 → 映射create、write或log权限如DATASET_CREATE、TRACE_SPAN_THREAD_LOG更新 / 编辑 / 修改类端点 → 映射edit或update权限如DATASET_EDIT、ALERT_UPDATE删除 / 移除 / 清理类端点 → 映射delete权限如DATASET_DELETE、TRACE_DELETE跨领域边界时允许映射到其他实体组的权限。典型例子从标注队列annotation queue上下文中执行标注的端点虽然身处队列资源但实际使用的可能是 trace 层级的标注权限。这一点在 AnnotationQueuesResource.java 中可观察到队列端点与ANNOTATION_QUEUE_ANNOTATE权限的绑定而 trace / span 上的直接标注则由 TracesResource.java 中的TRACE_SPAN_THREAD_ANNOTATE约束。4.4 步骤 4匹配存在时——先沟通再落码如果存在逻辑上匹配的权限不要立即添加注解。正确做法是向用户说明你认为匹配的是哪个权限及其理由在得到用户确认后再添加RequiredPermissions注解。4.5 步骤 5无匹配权限时——回退或新增如果找不到逻辑匹配的权限向用户明确指出哪个资源 / 哪个操作没有匹配的权限说明该端点将回退到团队成员身份认证team-membership authentication询问用户是往枚举中新增一个权限还是接受回退方案。4.6 标准示例一个典型的按 ID 获取数据集端点如下与原文档示例一致GET Path(/{id}) RequiredPermissions(WorkspaceUserPermission.DATASET_VIEW) public Response getDatasetById(PathParam(id) UUID id) { ... }五、当前覆盖范围与设计约束5.1 尚未全面覆盖属预期状态并非所有资源都已定义权限。当前仓库中已使用RequiredPermissions的资源包括均位于apps/opik-backend/src/main/java/com/comet/opik/api/resources/v1/priv/下AgentInsightsJobsResource、AlertResource、AnnotationQueuesResource、AutomationRuleEvaluatorsResourceDashboardsResource、DatasetsResource、ExperimentsResource、LlmProviderApiKeyResource、ManualEvaluationResourceOptimizationsResource、ProjectDashboardsResource、ProjectDatasetsResource、ProjectExperimentsResource、ProjectOptimizationsResourceProjectsResource、PromptResource、RecentActivityResource、ReportsResource、SpansResource、TracesResource、WorkspacesResource其余端点仍依赖团队成员身份认证。原文档明确强调这是预期行为。不要在缺少逻辑匹配权限的情况下投机式地添加权限只有当存在逻辑匹配的WorkspaceUserPermission值或用户确认需要新增权限时才添加注解。5.2 回退路径的底层实现印证未标注注解即回退在源码中得到三重印证RequiredPermissionsResolver在注解缺失或为空时返回List.of()AuthDynamicFeature将空列表写入请求属性AuthFilter读到的requiredPermissions为空列表授权逻辑自然只基于团队成员身份执行而不会施加额外的权限约束。这也意味着任何新增权限必须同时满足两个条件才能真正生效一是枚举中新增WorkspaceUserPermission常量二是目标端点显式标注RequiredPermissions。二者缺一不可。六、实践建议与常见误区不要根据方法名臆测权限。getXxx不总是 view 权限——关键看它对数据做了什么是否触发了脱敏数据的读取、是否写入了存储。跨域操作要选对权限归属。队列上下文中的标注、trace 上的标注、实验中的评估写入等都应回到该操作实际作用于哪个实体来判断权限归属而不是机械套用所在资源类名。尊重回退设计。未标注权限不等于未完成在没有匹配权限时贸然新增枚举值反而可能破坏既有角色的权限语义。新增枚举值必须经过用户确认。多权限声明按需使用。注解支持数组一个端点可以同时要求多个权限但应保持最小化避免过度授权约束。新权限需要端到端验证。新增枚举值后应确认RequiredPermissionsResolver能正确解析出字符串值getValue()并在AuthFilter的授权路径上得到应用。七、进一步阅读权限枚举定义WorkspaceUserPermission.java注解声明与解析RequiredPermissions.java、RequiredPermissionsResolver.java鉴权过滤器与动态注册AuthFilter.java、AuthDynamicFeature.java权限在资源上的实际应用示例DatasetsResource.java、TracesResource.java、AnnotationQueuesResource.java后端整体开发约定AGENTS.md【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
