把 Sentry 告警接入 ONES 缺陷流程，动手开发前需要先确认三类条件：Sentry 项目是否具备 servicehooks 功能与项目写权限、可订阅哪些事件；ONES 目标租户的 API 版本、凭据类型与 Scope 是否覆盖建单所需范围；以及事件到缺陷的字段映射与去重规则。本文按自建对接方案展开，Sentry 侧依据其项目 Service Hook 接口文档，ONES 侧依据开放平台 REST API v2 与凭据文档；CN 部署下的具体建单端点与端到端写入尚待核验，文中给出的核对表、映射模板与验证清单用于试点前准备。
要点总览（TL;DR）
- 接入前先确认 Sentry 侧两件事：目标租户是否具备 servicehooks 功能、注册账户是否拥有项目写权限；不能默认所有账户都能调用 Service Hook 接口。
- ONES 侧确认 API 版本、凭据类型与 Scope：开放平台提供 REST API v2，凭据分个人 OAuth 与组织凭据，组织凭据文档标注 ONES 6.2.18 及以上。
- 字段映射以事件标识或指纹作为关联键，用于判断重复告警；合并策略属于待验证设计，需在试点中确定。
- 这是自建接收服务方案，Sentry 与 ONES 之间没有现成原生插件，CN 部署下的建单端点与端到端写入须按目标部署文档核验。
- 上线前用少量真实告警按顺序验证：注册 Hook、接收推送、创建缺陷、重复合并、凭据恢复、失败重放，并记录租户版本与端点来源。
Sentry与ONES之间要打通哪条数据链路
这条链路是单向的：Sentry 作为应用错误与异常监控工具，在项目级产生告警事件；项目 Service Hook 把事件以出站推送的方式发到自建接收服务；接收服务再以入站调用方式请求 ONES 开放接口创建缺陷，并把缺陷标识回写到关联记录中。整条链路中，Sentry 负责发现异常，ONES 负责承载可追踪的缺陷工作项，中间的事件转换由接收服务完成。
| 环节 | 系统 | 动作 | 数据方向 |
|---|---|---|---|
| 事件产生 | Sentry 项目 | 告警触发，形成事件载荷 | 项目内 |
| 事件推送 | Sentry Service Hook | 按订阅事件向接收服务推送 | 出站 |
| 事件转换 | 自建接收服务 | 解析事件、映射字段、判断重复 | 内部处理 |
| 缺陷创建 | ONES 开放接口 | 以凭据调用接口创建缺陷 | 入站调用 |
| 关联回写 | 接收服务 | 保存事件标识与缺陷标识的关联键 | 内部存储 |
需要明确方案边界：Sentry 与 ONES 之间没有现成的原生插件，接收服务、字段映射、去重与重试都需要自行开发。Sentry 文档证实了项目 Service Hook 注册接口的存在，ONES 文档证实了开放平台 REST API v2 与凭据体系，但两者组合后的端到端写入尚未验证。国内开放平台入口与 COM 文档体系不能仅凭名称视为同一套接口契约，具体 HTTP 路径、参数与返回值必须按目标部署文档核对。
Sentry侧要确认的事件与账户条件
Sentry 提供项目 Service Hook 注册接口，可订阅文档指定的事件。这里的关键词是“文档指定”：可订阅事件的范围以目标项目对应的接口文档为准，接入前应把候选事件逐项列出并与文档比对，确认告警事件是否在可订阅清单内，再决定订阅哪些。不要先按业务设想确定事件类型，再假设接口支持。
该接口要求 servicehooks 功能与项目写权限。这意味着两件事需要分别核对：一是租户层面是否开放了 servicehooks 功能，二是执行注册操作的身份是否具备目标项目的写权限。不能默认所有 Sentry 账户都能使用此接口，需先核对租户可用功能与所选告警机制。若功能未开放或权限不足，注册请求会在第一步失败，后续映射设计无从验证。
接入前可按以下清单逐项确认：
- 功能开关：目标租户是否具备 servicehooks 能力，由谁确认并留痕。
- 项目权限：注册 Service Hook 的账户是否拥有目标项目写权限。
- 事件范围：从接口文档摘出可订阅事件清单，标注本次需要订阅的条目。
- 告警机制：实际可用的告警触发方式属于待确认项，需在试点中观察，不能当作已证实能力。
- 接收地址：接收服务的回调地址是否可从 Sentry 侧访问，是否具备基本的来源校验手段。
ONES侧要确认的凭据、Scope与版本前提
ONES 开放平台提供 REST API v2，用于应用开发和系统集成，目标租户必须支持对应 API 版本。接收服务调用建单接口前，先确认租户的 API 版本可用，再选择凭据类型。开放平台文档区分个人 OAuth 凭据和组织凭据，二者代表的身份与作用范围不同：个人凭据绑定具体用户，组织凭据面向组织级集成。选择哪种取决于缺陷的创建者归属与后续责任流转方式，这一判断应在设计阶段定下，避免上线后更换身份导致历史缺陷归属混乱。
组织凭据能力在文档中标注为 ONES 6.2.18 及以上，实施前需确认实际版本、管理角色及授权范围。认证方式使用 Bearer Token，接口路径示例为 /openapi/v2/，该路径只是版本前缀示例，并非创建工作项的完整接口地址，完整端点须按目标部署文档获取。
| 核对项 | 需要确认的内容 | 不确认的后果 |
|---|---|---|
| API 版本 | 目标租户支持 REST API v2 | 请求路径与返回结构不匹配 |
| 凭据类型 | 个人 OAuth 凭据或组织凭据 | 缺陷创建者归属与预期不符 |
| 版本条件 | 组织凭据需 ONES 6.2.18 及以上 | 凭据能力不可用 |
| Scope 范围 | 覆盖建单所需的工作项写入范围 | 鉴权通过但操作被拒 |
| 端点来源 | 按目标部署文档核对完整地址 | 调用错误接口 |
凭据生命周期有两个容易踩空的点。其一，改变凭据 Scope 不会自动改变已发出的 Token，需重新授权使新范围生效，只改配置却继续使用旧授权会持续报权限错误。其二，个人 Token 刷新会产生新的访问和刷新令牌，旧令牌失效，自行实现的连接器需保存并使用新令牌。接收服务应把令牌存储与刷新逻辑做成独立模块，并在刷新失败时进入告警而非静默重试。
事件到缺陷的字段映射与去重规则怎么定
映射表是接收服务的核心配置，建议在编码前先以表格形式定稿，字段名以目标租户实际可用字段为准，不预设。下表给出映射结构模板，左列为 Sentry 事件侧需要提取的信息，右列为 ONES 缺陷侧承载位置，具体字段名在试点时按租户实际字段填写。
| Sentry 事件信息 | ONES 缺陷侧承载 | 处理说明 |
|---|---|---|
| 项目与环境 | 缺陷所属项目、环境标识 | 用于路由到对应团队 |
| 事件标识或指纹 | 外部关联键 | 去重与回写的依据 |
| 告警标题 | 缺陷标题 | 保留可读性，必要时截断 |
| 级别 | 优先级 | 建立级别到优先级的固定对照 |
| 首次与最近发生时间 | 描述中的时间信息 | 区分新问题与复发问题 |
| 事件链接 | 描述中的来源链接 | 便于从缺陷跳回原始事件 |
| 来源标记 | 来源字段或标签 | 标识由 Sentry 自动创建 |
去重规则围绕关联键设计：以事件标识或指纹作为关联键，接收服务在创建缺陷前先查询是否已存在同一关联键的记录，存在则更新发生次数与最近时间，不存在才新建。重复告警合并策略属于待验证设计，例如同一指纹在时间窗口内多次触发是合并为一条缺陷并累加计数，还是按级别拆分，需要在试点中结合团队处理习惯确定，不能直接写成既定规则。
异常、重复与失败重试怎么处理
连接运行阶段的分支处理应在开发前列清，避免上线后靠人工排查。接收服务对重复推送需做幂等判断，同一事件重复到达时只更新已有记录，不重复建单；幂等键建议直接复用关联键，并保留短期去重缓存以应对推送重发。
- 接收失败：接收服务不可用时，Sentry 侧推送会失败，需确认是否支持重发以及重发窗口，必要时在 Sentry 侧保留事件以便人工补推。
- 鉴权失效：Token 过期、刷新或 Scope 变更后，接收服务需重新授权并更新连接器凭据，失败时进入告警队列。
- 写入失败：ONES 接口返回错误时保留原始事件载荷，支持按原载荷重放，重放前先做一次幂等检查。
- 重复推送：按关联键判断，命中则更新计数与时间，未命中才创建。
- 人工兜底：无法自动处理的告警进入人工确认队列，由值班人员决定建单、合并或忽略，并记录处理结果。
上述分支中，Sentry 侧推送失败后的重发机制、ONES 建单接口的错误码含义以及重复告警合并的实际效果，均属于尚未验证的部分，需在试点中观察并记录，不能作为已确认行为写入运行手册。
上线前如何验证这条链路可用
验证按链路顺序推进，每一步都有明确的通过判据，前一步不通过不进入下一步。建议用少量真实告警而非构造数据完成首轮验证，以便同时观察事件载荷的真实结构。
- 注册 Service Hook：在具备 servicehooks 功能与项目写权限的账户下完成注册，判据是注册成功且订阅事件与文档清单一致。
- 接收推送：触发一次真实告警，判据是接收服务收到载荷并能完整解析出映射所需字段。
- 创建缺陷：接收服务以选定凭据调用目标租户接口，判据是缺陷成功创建且创建者、项目、优先级符合映射预期。
- 重复告警：对同一事件重复触发，判据是按规则合并或更新，未产生重复缺陷。
- 凭据恢复：模拟 Token 刷新与 Scope 变更，判据是接收服务能重新授权并恢复写入，无需人工改代码。
- 失败重放：人为制造一次写入失败，判据是原始载荷被保留且重放后成功建单。
验收证据应包含验证日期、目标租户版本、所用凭据类型、完整端点来源以及每步的实际结果。记录端点来源尤其重要，因为国内开放平台入口与 COM 文档体系不能仅凭名称视为同一套接口契约，验收时须注明该端点取自哪份目标部署文档。完成以上验证后，这条从 Sentry 告警到 ONES 缺陷的链路才具备进入小范围试运行的条件。
常见问题
Sentry 侧注册 Service Hook 失败，通常要先排查什么？
先排查两个前置条件：目标租户是否开放了 servicehooks 功能，以及执行注册的账户是否拥有目标项目写权限。这两项缺一都会让注册请求在第一步失败。之后再核对订阅事件是否在接口文档给出的可订阅清单内，以及接收服务回调地址能否从 Sentry 侧访问。
个人 OAuth 凭据和组织凭据该怎么选？
两者代表的身份与作用范围不同。个人凭据绑定具体用户，组织凭据面向组织级集成，选择取决于缺陷创建者归属和后续责任流转方式。若选组织凭据，需确认目标租户版本满足文档标注的 ONES 6.2.18 及以上，并确认管理角色与授权范围。
调整了凭据 Scope，为什么调用仍然报权限错误？
改变凭据 Scope 不会自动改变已发出的 Token，需要重新授权使新范围生效。只改配置却继续使用旧授权，会持续出现鉴权通过但操作被拒的情况。接收服务应把重新授权做成独立流程，并在失败时进入告警。
Token 刷新后连接器需要做什么？
个人 Token 刷新会产生新的访问和刷新令牌，旧令牌随即失效。自行实现的连接器需要保存并使用新令牌，刷新失败时进入告警而非静默重试，避免后续建单请求全部失败。
重复告警合并规则能否在接入前一次定死？
建议先定关联键：以事件标识或指纹判断是否为同一问题。至于同一指纹在时间窗口内多次触发是合并为一条缺陷并累加计数，还是按级别拆分，属于待验证设计，需要结合团队处理习惯在试点中确定，不宜直接写成既定规则。
官方参考资料
- Register a New Service Hook（Sentry）
- ONES Open API v2（ONES）
- Open API Authentication And Authorization（ONES）
