# 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，并把脱敏摘要写入审计日志。

## 后端环境变量

```env
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`

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

本地验证命令：

```bash
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`

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

基础 text 消息验证：

```bash
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 配置

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

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

建议后端投递结构：

```json
{
  "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`：

```json
{
  "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 或加密存储中存在 |