DevOps 通知平台配置方案

更新时间：2026-06-11

当前结论

通知平台不是前端能力，web 端只展示后端返回的配置状态、变量名和变量说明。真实 webhook、token、签名密钥只能存在于 devops-platform-api 的服务端环境变量、服务器 secret 或后续加密存储中。

当前后端通知 provider 已按以下变量预留：

Provider	适用平台	必需变量	Webhook 变量	当前策略
`wecom`	企业微信	`NOTIFICATION_PROVIDER=wecom`	`WECOM_WEBHOOK_URL`	发送 markdown 发布通知
`feishu`	飞书	`NOTIFICATION_PROVIDER=feishu`	`FEISHU_WEBHOOK_URL`	发送 text 发布通知
`generic`	内部通知网关	`NOTIFICATION_PROVIDER=generic`	`NOTIFICATION_WEBHOOK_URL`	发送结构化 JSON

未配置 provider 或 webhook 时，发布流程不应被阻断；通知节点应显示 skipped/failed，并把脱敏摘要写入审计日志。

后端环境变量

DEVOPS_PUBLIC_URL=https://devops.mrzhan.top

# 任选其一：wecom / feishu / generic
NOTIFICATION_PROVIDER=wecom

# 企业微信机器人
WECOM_WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=replace-with-real-key

# 飞书自定义机器人
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/replace-with-real-token

# 通用内部 webhook
NOTIFICATION_WEBHOOK_URL=https://notification.example.internal/webhook/replace-with-secret

安全要求：

要求	说明
不进前端	web 端只拿变量名、状态和说明，不接收真实 URL
不进 Git	`.env`、服务器 secret、后续 `secrets` 表均不得提交真实 webhook
日志脱敏	任何异常日志、审计摘要和 Agent 上下文都不能包含 webhook 原文
不阻断发布	通知失败只影响通知节点和审计，不回滚 Jenkins 构建结果

企业微信配置

官方参考：https://developer.work.weixin.qq.com/document/path/91770

在企业微信群中添加群机器人。
复制机器人 webhook，保存到服务端环境变量 WECOM_WEBHOOK_URL。
设置 NOTIFICATION_PROVIDER=wecom。
重启 devops-platform-api。
访问 /settings，确认“通知平台”从未配置变成已配置或部分配置。
创建一次测试发布单，检查流程中的通知节点和群内消息。

本地验证命令：

curl -X POST "$WECOM_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d '{"msgtype":"markdown","markdown":{"content":"# DevOps 通知测试\n\n> 项目：devops-platform-web\n> 环境：production\n> 状态：success"}}'

飞书配置

官方参考：https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot

在飞书目标群添加“自定义机器人”。
复制 webhook，保存到服务端环境变量 FEISHU_WEBHOOK_URL。
建议开启安全设置：关键词、IP 白名单或签名校验。
设置 NOTIFICATION_PROVIDER=feishu。
重启 devops-platform-api。
创建测试发布单，检查通知节点和飞书群消息。

基础 text 消息验证：

curl -X POST "$FEISHU_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d '{"msg_type":"text","content":{"text":"DevOps 通知测试：devops-platform-web production success"}}'

如果开启飞书签名校验，需要后端按飞书规则计算 timestamp/sign，再放入请求 body；不要在前端计算或保存签名密钥。

通用 webhook 配置

适合接内部通知网关或消息中转服务：

NOTIFICATION_PROVIDER=generic
NOTIFICATION_WEBHOOK_URL=https://notification.example.internal/webhook/replace-with-secret

建议后端投递结构：

{
  "event": "deploy.succeeded",
  "title": "DevOps 发布成功",
  "run": {
    "id": "run_xxx",
    "projectKey": "devops-platform-web",
    "environment": "production",
    "ref": "master",
    "status": "success",
    "operator": "ops-admin"
  },
  "publicUrl": "https://devops.mrzhan.top"
}

Settings 变量说明契约

/settings 页面已按后端返回字段展示 hover 说明。后端推荐在 GET /settings/integration-config 中为每个变量补充 variableHelp：

{
  "key": "notification",
  "name": "通知平台",
  "status": "partial",
  "required": ["NOTIFICATION_PROVIDER", "WECOM_WEBHOOK_URL"],
  "configured": ["NOTIFICATION_PROVIDER"],
  "missing": ["WECOM_WEBHOOK_URL"],
  "optional": ["FEISHU_WEBHOOK_URL", "NOTIFICATION_WEBHOOK_URL", "DEVOPS_PUBLIC_URL"],
  "variableHelp": {
    "NOTIFICATION_PROVIDER": {
      "description": "通知 provider，可选 wecom、feishu、generic。",
      "example": "wecom",
      "docUrl": "https://developer.work.weixin.qq.com/document/path/91770"
    },
    "WECOM_WEBHOOK_URL": {
      "description": "企业微信群机器人的服务端 webhook，只能保存在后端。",
      "docUrl": "https://developer.work.weixin.qq.com/document/path/91770"
    },
    "FEISHU_WEBHOOK_URL": {
      "description": "飞书自定义机器人的服务端 webhook，只能保存在后端。",
      "docUrl": "https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot"
    },
    "NOTIFICATION_WEBHOOK_URL": {
      "description": "内部通知网关或通用 webhook 的服务端地址。"
    },
    "DEVOPS_PUBLIC_URL": {
      "description": "通知消息里跳转回 DevOps 平台的公开访问地址。"
    }
  }
}

前端兼容字段：

字段	说明
`variableHelp`	推荐格式，支持 description、example、docUrl
`variableDescriptions`	兼容 `变量名 -> 说明字符串` 的简单格式
`variables[]`	兼容 `{ name, description, example, docUrl }` 数组格式

上线检查

检查项	通过标准
`/settings`	只展示变量名、配置状态和后端说明，不展示真实 webhook
发布流程	通知未配置时节点 skipped，不阻断成功发布
审计日志	记录通知投递结果，摘要已脱敏
Agent	只能解释通知 skipped/failed，不输出或猜测 webhook
服务器	真实 webhook 仅在 `.env`、secret manager 或加密存储中存在

6.1 KiB Raw Blame History Unescape Escape