企业官网建设流程全解析

• 可观测性
• 后端
• 运维
• 前端
• 云原生
• 微服务
• AI Agent

本文基于 packages/App/FeatureSet/Docs/Content/fr/integrations/jira.md（法文版，作为原文骨架）翻译、整理并深度扩充。以下"原文"均指该文件。

导读

本文教你用 OneUptime 内置的 Workflow（工作流）引擎，把 Jira 无缝接入事故响应流程：每次 OneUptime 事故被声明时自动在 Jira 创建工单（issue），事故解决时自动把 Jira 工单过渡到 Done，同时 Jira 端的状态变更也能反向同步回 OneUptime——构成一张完整的双向同步网。你不需要安装任何 Jira 专属插件：OneUptime 通过内置的 API 组件直接调用 Jira REST API，Jira 侧则用自动化规则（Automation）或原生 Webhook 回调 OneUptime。读完本文，你将掌握从凭证存储、事故→工单创建、字段映射、状态回写，到 Jira Data Center 适配与常见错误排查的完整闭环。

原文地址：Jira 集成文档（fr 语言包）
配套阅读：集成总览、Workflow 入门、Workflow 组件

1. 架构总览：两个方向、四段流程

OneUptime 的 Workflow 引擎是一个可视化画布，让你用"触发器 + 组件块"串起自动化逻辑。整个 Jira 集成由两条相对独立的链路组成：

OneUptime Incident → On Create ──► API Post (POST /rest/api/3/issue) ──► Jira issue Jira issue transitioned ──► Automation rule (Send web request) ──► OneUptime Webhook trigger ──► Update One Incident

• 出站（OneUptime → Jira）：事故创建/更新时触发 Workflow，通过 API 组件调用 Jira REST API 创建、评论、过渡工单。
• 入站（Jira → OneUptime）：Jira 自动化规则把工单状态变更以 webhook 形式回调 OneUptime，由 Webhook 触发器接收并更新事故状态。

从源码看，Workflow 引擎的 Webhook 触发器实现在 WebhookTrigger：它暴露一个GET /trigger/:secretkey路由，把收到的请求头、查询参数和请求体原样透传给工作流后续组件；其组件元数据定义在 Webhook.ts（Types 侧），明确标注了request-headers、request-params、request-body三个可注入的入参。这正是文档中"Jira 回调 → Webhook 触发器 → 更新事故"链路的底层支撑。

术语提示：Atlassian 在 Jira Cloud 中不断调整叫法——project（项目）在大量界面中被称为space（空间），issue（工单）被称为work item。新旧租户词汇不一，下文两者都会出现，请以你所见界面为准。

2. 前置条件

在动手之前，请确认以下四项都已就绪：

1. 一个 Jira Cloud 站点（形如https://your-domain.atlassian.net），以及一个用于建票的项目。记下它的项目密钥（project key）——例如OPS-1234中的OPS。
2. 一个能在该项目中建票的 Jira 账号，并为其创建API Token（管理入口：id.atlassian.com → Security → API tokens）。强烈建议使用服务账号（service account）而非个人账号——因为通过该 token 创建的工单，assignee 默认归属 token 持有者。
3. 该项目的自动化规则创建权限（用于入站方向）。
4. 一个 OneUptime 项目，且你拥有创建 Workflow 和全局变量（Global Variables）的权限。

关于 OneUptime 项目的获取：OneUptime 既提供云端托管（Cloud），也支持自托管（self-hosted）。自托管场景下，所有oneuptime.com的 URL 都要替换成你自己的主机地址。

3. 第 1 步：把 Jira 凭证安全地存进全局变量

Jira Cloud 的 REST API 使用Basic Auth：把账号邮箱与 API Token 拼接为email:api_token后整体做 Base64 编码，作为Authorization请求头。OneUptime 的 Workflow 引擎没有硬编码凭证的地方，最佳实践是使用全局变量 + Secret 标记。

3.1 一次性生成 Base64 凭证串

printf '%s' 'you@example.com:your_api_token' | base64

务必使用printf而不是echo：echo会在末尾追加一个换行符，换行符会被一并编码进字符串，导致 Jira 返回401 Unauthorized——而你在粘贴的字符串里完全看不出原因。这是文档点名的头号坑，后续排查章节还会遇到它。

3.2 在 OneUptime 中创建两条全局变量

操作路径：Flux de travail → Variables globales → Créer（即 Workflow → Global Variables → Create）。

之后任何组件都可以直接用Basic {{global.variables.JIRA_AUTH}}作为Authorization请求头，而 token 本身永远不会出现在 Workflow 的画布、配置或运行日志中。参见 Variables 文档。

3.3 关于 Atlassian API Token 的两个隐藏陷阱

这两个问题不会立刻爆发，但会在几个月后反咬一口：

• Token 会过期：Atlassian API Token 的寿命是 1 天到 1 年（默认 1 年），且没有自动续期机制。过期后必须手动去同一页面重新生成，再重新编码进JIRA_AUTH。请把到期日写进日历——当一个运行了几个月的 Workflow 突然开始返回401，十有八九就是这个原因。
• 受限作用域 Token 需要不同的 Base URL：Token 页面除了经典的Create API token，还提供Create API token with scopes（更安全的选项）。但这类 token不指向你的站点，而是指向https://api.atlassian.com/ex/jira/<cloudId>——此时JIRA_URL应改为该值，下面所有路径保持不变地挂在它后面。你的cloudId可以通过访问https://your-domain.atlassian.net/_edge/tenant_info返回的 JSON 拿到。把受限 token 发往your-domain.atlassian.net会直接失败。

3.4 进阶：用 OAuth 2.0 服务账号凭证绕开过期问题

如果你的组织使用 Atlassian 集中式用户管理，还有第三条路：OAuth 2.0 服务账号凭证（Service account credential）。它给你 client id + secret 而非静态 token，Workflow 在每次执行开始时先用这两个值换取短期访问令牌。结构上与文档中 Microsoft Dynamics 365 集成一致：

• 第一个API Post (JSON)块负责拿 token；
• 其后所有块改用Bearer <token>请求头；
• API 基础 URL 为https://api.atlassian.com。

这样一年后无需任何人手动更换任何东西。Atlassian 官方页面提供了精确的换取 token 请求体，照抄即可。

4. 第 2 步：为每个事故自动创建 Jira 工单

这是整条出站链路的核心。我们要在 OneUptime 里新建一个 Workflow，命名为Incidents → Jira。

4.1 配置触发器：On Create Incident

1. 打开Flux de travail → Créer un flux de travail（Workflow → Create Workflow），命名后进入画布（Constructeur / Builder）。
2. 点击虚线块，添加触发器On Create Incident。
3. 在其Select Fields字段中声明你需要发送的列：

{ "_id": true, "title": true, "description": true, "incidentNumber": true, "incidentSeverity": { "name": true } }

4. 保持其Identifier为默认的incident-on-create-1——后续所有组件都通过这个名字引用该触发器的输出。

从源码理解 Select Fields：OneUptime 基于数据库模型驱动 Workflow 触发器的字段选择。Incident 模型的字段结构位于 packages/Common/Models/DatabaseModels/，触发器只会把你在 Select Fields 里勾选的字段注入返回值，因此少勾一个字段，后续组件就拿不到对应的引用（表现为模板变量原样输出或空值）。

4.2 添加 API Post (JSON) 组件

点击Ajouter un composant（添加组件），选API Post (JSON)块，把触发器的Succès / 成功端口连到新块的入口，设置 Identifier 为create-issue：

• URL：{{global.variables.JIRA_URL}}/rest/api/3/issue
• Request Headers：

{ "Authorization": "Basic {{global.variables.JIRA_AUTH}}", "Accept": "application/json" }

• Request Body：

{ "fields": { "project": { "key": "OPS" }, "issuetype": { "name": "Bug" }, "summary": "OneUptime #{{local.components.incident-on-create-1.returnValues.model.incidentNumber}}: {{local.components.incident-on-create-1.returnValues.model.title}}", "labels": ["oneuptime"], "description": { "type": "doc", "version": 1, "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "{{local.components.incident-on-create-1.returnValues.model.description}}" } ] } ] } } }

请把OPS换成你的项目密钥、Bug换成该项目真实存在的工单类型。两者也可以改用 ID 传参——{"id": "10000"}——这是 Atlassian 官方示例的写法，当站点里有两个同名工单类型时务必用 ID。ID 可以从下文 4.5 的createmeta接口拿到。

4.3 理解 Atlassian Document Format（ADF）

上面的 description 之所以长得这么"重"，是因为Jira Cloud v3 API 要求富文本使用 Atlassian Document Format（ADF）——它是一棵文档树，不是普通字符串。上面这段是合法的 ADF 最小文档：一个 paragraph 里包一个 text 节点。

同样的规则适用于environment字段以及任何多行文本自定义字段；单行文本自定义字段则仍然接受普通字符串。

4.4 激活、验证与结果引用

• 在Vue d'ensemble → Modifier le flux de travail（Overview → Edit Workflow）中把状态切到Activé / 启用。
• 声明一个测试事故，打开Exécutions & journaux（Executions & Logs）。
• create-issue块应返回201，响应体包含新工单的id、key、self。

两点操作提示（源自文档）：

• 画布上的修改自动保存，没有 Save 按钮；
• 未启用的 Workflow 完全无法运行——包括手动运行。

新工单的 key 可被后续任何组件引用：

{{local.components.create-issue.returnValues.response-body.key}}

4.5 补充常用字段与字段探测

在fields对象里，几个高频追加项：

与其猜，不如直接问 Jira。用下面两个 curl 调用探测项目真实要求：

# 列出某项目的工单类型 curl -u 'you@example.com:your_api_token' \ 'https://your-domain.atlassian.net/rest/api/3/issue/createmeta/OPS/issuetypes' # 列出某工单类型的全部字段：哪些必填、customfield_NNNNN 的准确 ID curl -u 'you@example.com:your_api_token' \ 'https://your-domain.atlassian.net/rest/api/3/issue/createmeta/OPS/issuetypes/10001'

第二个调用会给出该工单类型接受的全部字段、必填项以及精确的customfield_NNNNN标识。想读取已有工单的字段 ID，用?expand=names参数拉取。

5. 第 3 步：把 OneUptime 事故 ID 存进 Jira

双向同步的两个方向都需要某一侧持有另一侧的标识符。文档明确建议把 ID 存在 Jira 侧，因为 OneUptime 的customFields列是一个扁平的 JSON blob——Workflow 从里面写入一个值会覆盖该事故的全部自定义字段，代价太大。

5.1 方案 A（推荐）：自定义字段

在 Jira 中新建一个短文本自定义字段，命名为OneUptime Incident ID，挂到项目的创建界面（screen）上；用 4.5 的createmeta找到它的 ID，然后在创建工单的请求体里一并提交：

"customfield_10050": "{{local.components.incident-on-create-1.returnValues.model._id}}"

5.2 方案 B（无管理员权限）：标签

没有 Jira 管理员权限时，把 ID 塞进 label。label 不能含空格，而 OneUptime 的 ID 是 UUID，所以oneuptime-<id>是合法 label：

"labels": ["oneuptime", "oneuptime-{{local.components.incident-on-create-1.returnValues.model._id}}"]

代价：入站 Workflow 需要用一个Run Custom JavaScript块从 label 列表里把 ID 抠出来（两到三行代码）。文档的评价是：能拿到自定义字段就用字段，更干净。

5.3 顺手加一个"返回 OneUptime"的链接

在create-issue之后再接一个API Post (JSON)块，指向{{global.variables.JIRA_URL}}/rest/api/3/issue/{{local.components.create-issue.returnValues.response-body.key}}/remotelink，请求体：

{ "globalId": "system=https://oneuptime.com&id={{local.components.incident-on-create-1.returnValues.model._id}}", "object": { "url": "https://oneuptime.com/dashboard/{{local.components.incident-on-create-1.returnValues.model.projectId}}/incidents/{{local.components.incident-on-create-1.returnValues.model._id}}", "title": "OneUptime incident #{{local.components.incident-on-create-1.returnValues.model.incidentNumber}}" } }

这样 Jira 里所有人都能一键跳回 OneUptime 事故页。注意：

• 需要在触发器的Select Fields里追加projectId；
• globalId让这个调用可安全重复执行——Jira 会更新已带该 ID 的链接而不是再插一条；
• 因为更新会清空所有未提交的字段，所以必须始终发送完整的object，不能发局部补丁。

自托管安装请把https://oneuptime.com/dashboard/...换成你自己的仪表盘地址。

6. 第 4 步：事故演变时，评论并过渡工单

这要做成第二个独立 Workflow（命名如Incident updates → Jira），理由是：这个流程失败绝不能阻塞建票流程——两个职责彼此隔离。

1. 添加触发器On Update Incident。
2. 在Listen on里写{"currentIncidentStateId": true}——这样触发器只在状态变化时触发，而不是每次修改都触发。Select Fields里写{"_id": true, "currentIncidentState": {"name": true}}。
3. 添加If / Else块：Input 1为{{local.components.incident-on-update-1.returnValues.model.currentIncidentState.name}}，Operator为==，Input 2为Resolved（或你项目里"已解决"状态的准确名称）。参见 États et sévérités des incidents。

6.1 从"Oui / 是"分支找回 Jira 工单

用第 3 步存的 ID 去 Jira 查询对应工单。用一个 Identifier 为find-issue的API Post (JSON)块：

• URL：{{global.variables.JIRA_URL}}/rest/api/3/search/jql
• Request Body：

{ "jql": "project = OPS AND labels = \"oneuptime-{{local.components.incident-on-update-1.returnValues.model._id}}\"", "maxResults": 1 }

如果第 3 步用的是自定义字段而非 label，JQL 子句相应改为cf[10050] ~ "..."（换成你的字段 ID）。

工单 ID 从此可用{{local.components.find-issue.returnValues.response-body.issues[0].id}}引用——下面所有端点既接受 key 也接受 id。

关于这个端点，文档特别强调三点：

• JQL 放进请求体（POST），不要拼进 URL。查询串里带=的值在离开 Workflow 时会被截断，而 JQL 通篇都是=。
• 查询必须加边界：裸写order by key desc会被400拒绝，所以要带project =这样的收敛条件。
• 必须用/rest/api/3/search/jql：旧端点/rest/api/3/search已废弃并进入生命周期终点，不要再用。

6.2 留评论：单个 API Post 块

指向{{global.variables.JIRA_URL}}/rest/api/3/issue/<id>/comment，body 同样是 ADF 格式（和 description 一样）：

{ "body": { "type": "doc", "version": 1, "content": [ { "type": "paragraph", "content": [{ "type": "text", "text": "Resolved in OneUptime." }] } ] } }

6.3 过渡工单：先查后转，两个调用

transition 的 ID 因 Jira workflow 而异，某些看板上甚至因工单而异，所以必须动态查询：

1. API Get (JSON)调{{global.variables.JIRA_URL}}/rest/api/3/issue/<id>/transitions——返回从工单当前状态出发可用的全部 transition，每个带id、name和指向目标状态的to对象。
2. API Post (JSON)调同一个 URL 执行 transition：

{ "transition": { "id": "31" } }

成功的 transition 返回204，无响应体。如果不想在运行时读列表，可以手动对一张处于正确状态的工单调一次接口、把 ID 硬编码进 Workflow——但要记住它绑定了该 Jira workflow，管理员改动 workflow 可能会让硬编码悄悄失效。

7. 入站方向：从 Jira 回到 OneUptime

另一半链路：某人在 Jira 把工单拖到 Done，OneUptime 的事故状态要跟着变。

7.1 先建好接收 Workflow

1. Créer un flux de travail，命名Jira → OneUptime，添加Webhook触发器。
2. 打开该 Workflow 的Paramètres / 设置，复制clé secrète du webhook（webhook 密钥）。你的回调 URL 是：

https://oneuptime.com/workflow/trigger/<webhook secret key>

自托管安装用自己的主机地址。把这条 URL 当密码对待——任何拿到它的人都能启动这个 Workflow；万一泄露，在同一页面重新生成密钥即可。从源码看，该路由正对应 WebhookTrigger.init() 注册的GET /trigger/:secretkey，请求头、参数、body 会原样进入后续组件。

3. 在触发器的出口加一个If / Else，在任何逻辑之前先校验共享密钥：

   • Input 1：{{local.components.webhook-1.returnValues.request-headers.x-oneuptime-secret}}
   • Operator：==
   • Input 2：{{global.variables.JIRA_WEBHOOK_SECRET}}（自己编一个值，存成 Secret 全局变量）

4. 从Oui / 是分支加Update One Incident块：

   • Query：{"_id": "{{local.components.webhook-1.returnValues.request-body.oneuptimeIncidentId}}"}
   • Data (JSON Object)：Jira 侧变更在 OneUptime 侧应产生的效果——通常是状态变更。

移动事故状态需要目标状态的 ID：用Find One Incident State块、查询{"name": "Resolved"}得到{{local.components.incident-state-find-one-1.returnValues.model._id}}，把它写进currentIncidentStateId。

保持该 Workflow 启用。接下来给 Jira 一个可调用它的东西。

7.2 用 Jira 自动化规则发送事件

1. 打开 Jira 项目自动化规则：新租户在Space settings → Automation，旧租户在Project settings → Automation；跨项目规则走Settings → System → Global automation（需要全局Administer Jira权限）。

2. Create rule，触发器选Work item transitioned（旧租户叫Issue transitioned），并设置成进入 Done 状态时触发。

   务必用 transitioned 触发器，不要用 Work item updated：update 触发器会刻意排除状态变更。

3. 添加Send web request动作：

   • Web request URL：上面拿到的 OneUptime webhook URL；
   • HTTP method：POST；
   • Headers：Content-Type/application/json，以及X-OneUptime-Secret/ 你的共享密钥。用Hide选项隐藏密钥值（注意：隐藏对该值不可逆，且规则被导出或复制时隐藏值会丢失）；
   • Web request body：选Custom format，完全自定义载荷：

{ "oneuptimeIncidentId": "{{issue.customfield_10050}}", "issueKey": "{{issue.key}}", "summary": "{{issue.summary}}", "status": "{{issue.status.name}}" }

如果第 3 步用的是 label 而非自定义字段，就发送"labels": "{{issue.labels}}"，然后在 OneUptime 侧用Run Custom JavaScript块提取 ID。

4. 启用规则，把一张测试工单拖到 Done，两侧验证：Jira 的规则审计日志（audit log）和 OneUptime 的Exécutions & journaux。

7.3 依赖此机制前必须知道的五个事实

• 出站端口受限：Send web request 只能访问端口 80、8080、443、6017、8443、8444、7990、8090、8085、8060、8900、9900。OneUptime Cloud 走 443 没问题；自托管部署若监听非常规端口，就无法被这种方式调用。
• 没有请求签名：该动作不提供 HMAC 选项。Atlassian 文档化的做法就是 HTTPS 上加共享密钥请求头——所以接收 Workflow 里那个If / Else 校验是整套安全性的核心。
• 规则执行会计入配额：Jira Cloud 按订阅计划扣减每月成功执行次数——Free 100 次、Standard 1700 次、Premium 1000 × 用户数、Enterprise 无限。繁忙项目的每次 transition 都会消耗配额，量大了要掂量。
• 值不会被自动做 URL 编码：只有发 form-encoded body 时才有影响，上面的 JSON 载荷无此问题。
• Atlassian 会公布出站 IP 段（ip-ranges.atlassian.com）：如果你的 OneUptime 部署在 IP 白名单后面，这些段会变化，应订阅其 feed 而不是固化地址。

7.4 替代方案：Jira 原生 Webhook

Jira 管理员也可以直接在Settings → System → Advanced → WebHooks注册 webhook，选择要投递的事件，并可加一条 JQL 过滤涉及的工单。与自动化规则对比：

• 载荷是 Jira 的，不是你的：包含webhookEvent、issue_event_type_name、完整issue对象，以及changelog（其items数组给出每个被改字段的前后值）。状态变更对应field为status的那条记录。要在 Workflow 里解析它，通常需要Run Custom JavaScript块。
• webhook 可以签名，但 Workflow 验不了：给 webhook 配一个 secret 后，Jira 会发送X-Hub-Signature头（请求体 HMAC）。但签名覆盖的是 Jira 发送的原始字节，而 OneUptime 的 Webhook 触发器交给 Workflow 的是已解析成 JSON 的对象——没有字节可哈希。想认证请求，就用自动化规则 + 共享密钥头的方案。
• URL 必须走 HTTPS 且端口在 Jira 专属列表内（与自动化规则的端口列表不同，80 不在其中）。
• 投递失败最多重试 5 次，间隔 5～15 分钟——所以接收 Workflow 必须容忍同一事件收到两次（幂等）。

另外要注意：应用通过/rest/api/3/webhook注册的 webhook 是另一回事——注册后 30 天不刷新就过期；管理员在界面上注册的则不过期。

8. Jira Data Center 适配

自托管 Jira 的工作方式相同，只有几处替换。Jira Server 已于 2024 年 2 月结束支持、不再有补丁——自托管请把 Data Center 当作目标版本。

于是创建工单的块变成对/rest/api/2/issue的POST：

{ "fields": { "project": { "key": "OPS" }, "issuetype": { "name": "Bug" }, "summary": "OneUptime #123: Checkout is down", "description": "Plain text goes straight in here." } }

——没有文档树，建模更简单。

8.1 其余差异清单

• Personal access tokens：自 Jira Core / Jira Software 8.14、Jira Service Management 4.15 起可用。默认 365 天过期，到期前 5 天界面会标注Expires soon。Data Center 仍支持用户名+密码的 Basic auth，但几次失败登录会触发 CAPTCHA，把账号彻底挡在 REST API 之外、直到有人在浏览器里人工解锁——这不是发现拼写错误的好方式，请优先用 token。
• 自动化已内建：自 Jira Data Center 10.0 起内置；此前是独立插件 Automation for Jira。其出站请求默认超时 3000 ms，可用属性outgoing.webhook.timeout.ms调整。
• Webhooks：在Administration → System → Advanced → WebHooks注册，支持 JQL 过滤。务必把过滤器收窄：Jira 会在触发事件的执行线程上对每个已注册 webhook 求值 JQL，十几个宽泛过滤器会拖慢触发它们的用户操作。
• Data Center 10.0 起 webhook 投递是异步的，没有同步选项——事件可能乱序到达，接收 Workflow 要做到幂等。
• Jira 10 移除了 webhook URL 变量里的$——${issue.id}变成{issue.id}——并把 webhook REST 资源从/rest/webhooks/1.0/webhook移到/rest/jira-webhook/1.0/webhooks。

9. 同样的套路搬到 Alert（告警）

上面全部围绕 Incident（事故）展开，因为这是最常见的场景，但Alert（告警）的用法一模一样——只换记录类型，其他不动：

注意：一个 Workflow 只能有一个触发器，所以 Incident 和 Alert 各需一个 Workflow。如果两者要做完全相同的处理，把 Jira 那一半建成一个 Workflow，再用Execute Workflow组件从两边调用它。

10. 排障手册

先打开Exécutions & journaux里失败的块：Jira 返回的 JSON 响应体会精确指出它拒绝了什么，API 组件会把响应体保留在response-body里供你检视。

11. 延伸阅读

• Vue d'ensemble des intégrations（集成总览） —— 出入站模式与认证速查表
• Microsoft Dynamics 365 集成 —— 同样的双向构造用在 Dynamics 上
• Workflow 概述 与 创建 Workflow —— 画布、Identifier、激活机制
• Workflow 组件 —— API 块、If / Else 与 OneUptime 数据组件
• Workflow 变量 —— Secret 管理，以及从上一块读取输出
• Workflow 配置与安全 —— webhook 安全与出站网络访问
• ServiceNow 与 PagerDuty —— 同样的出站模式用在其他工具上

仓库内实现参考

• 法语原文文档：packages/App/FeatureSet/Docs/Content/fr/integrations/jira.md
• Webhook 触发器实现：packages/Common/Server/Types/Workflow/Components/Webhook.ts
• Webhook 组件元数据：packages/Common/Types/Workflow/Components/Webhook.ts
• Workflow 更新/触发 API：packages/App/FeatureSet/Workflow/API/Workflow.ts
• Workflow 组件文档目录：packages/App/FeatureSet/Workflow/Docs/ComponentDocumentation/

• 可观测性
• 后端
• 运维
• 前端
• 云原生
• 微服务
• AI Agent