一、项目背景
为规范生产环境发布行为，避免在非允许时间段进行生产代码或项目 delay 更新，本项目基于 云效流水线人工卡点 + Webhook + 时间策略判断，实现一套自动化的发布治理机制。
系统遵循以下原则：
- ✅ 允许上线时间：自动通过人工卡点
- ⛔ 禁止上线时间：强制人工介入并精准通知执行人
- 📜 所有决策可审计、可追溯
二、整体方案概述
当云效流水线运行至 人工卡点（WAITING 状态） 时，流水线通过 Webhook 将事件推送至本服务。本服务统一负责：
- 解析流水线上下文
- 判断是否处于允许上线时间
- 自动审批或阻断发布
- 通过飞书精准通知执行人
- 输出结构化 JSON 日志，供日志平台采集分析
该方案 不侵入流水线原有逻辑，仅需配置人工卡点与 Webhook 即可接入。
三、系统工作流程
云效流水线↓
人工卡点（WAITING）↓
Webhook 通知↓
解析任务与执行人信息↓
上线时间规则判定↓
├─ 允许上线时间 → 自动通过人工卡点
│
└─ 禁止上线时间 → 阻断发布 + 飞书 @ 执行人
四、上线时间治理规则
以下时间段 禁止生产环境代码发布及项目 delay 更新：
| 星期 | 禁止上线时间 |
|---|---|
| 周一 ～ 周四 | 20:30 之后（含） |
| 周五 | 18:30 之后（含） |
| 周六 | 全天 |
| 周日 | 全天 |
处于上述时间段时：
- 系统不会自动通过人工卡点
- 必须人工确认或在允许时间段内重新操作
五、人工卡点处理逻辑
1. 允许上线时间
- 系统自动调用云效接口
- 人工卡点自动通过（PASS）
- 流水线继续执行
- 自动审批行为写入日志
2. 禁止上线时间
- 系统不调用任何审批接口
- 根据执行人信息发送飞书通知
- 精准 @ 当前执行人
- 明确提示当前为非上线时间
- 阻断原因及通知结果写入日志
六、执行人映射机制（user.json）
系统通过本地 user.json 文件维护 云效执行人姓名 → 飞书 user_id 的映射关系，用于飞书精准 @ 通知。
示例：
[{"name": "张三","user_id": "id-1111"},{"name": "李四","user_id": "id-22222"}
]
说明：
name：云效 Webhook 中的executorNameuser_id：飞书用户 ID（用于 @）
若未找到对应映射关系，系统将记录告警日志，不进行飞书通知，避免 silent failure。
七、日志与审计
系统采用 JSON 结构化日志，记录所有关键决策与行为，包括：
- Webhook 接收
- 人工卡点命中
- 上线时间规则判定
- 自动审批行为
- 发布阻断与飞书通知
日志可直接接入：
- 阿里云 SLS
- ELK（Elasticsearch / Logstash / Kibana）
- Loki 等日志系统
所有发布放行与阻断行为 均可追溯、可审计。
八、方案特点
- 🧭 发布规则明确：时间策略清晰可控
- ⚡ 自动化程度高：减少人工审批成本
- 👤 责任到人：非上线时间精准提醒执行人
- 🔌 无侵入式接入：不影响现有流水线结构
- 📈 易扩展：可扩展节假日、白名单、双人审批等能力
九、总结
本项目通过人工卡点与时间策略结合，实现了一套 自动化、可控、可审计 的生产发布治理机制，在保证发布效率的同时，强化了生产环境的稳定性与发布规范性。
十、项目结构
ReleaseGatekeeper/
├── app.py # Webhook 服务入口
├── time_rule.py # 上线时间规则
├── approve.py # 云效人工卡点审批
├── feishu.py # 飞书通知
├── user_loader.py # user.json 加载
├── json_logger.py # JSON 结构化日志
├── user.json # 执行人映射
├── requirements.txt
└── README.md