feat: 展示集成变量说明与流程详情
This commit is contained in:
湛兮
@@ -0,0 +1,166 @@
|
||||
# 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 或加密存储中存在 |
|
||||
Reference in New Issue
Block a user