飞书卡片驱动的 GitLab CI/CD 智能发版控制台
在飞书群聊中通过交互式卡片，一键触发、追踪和管理 GitLab 流水线部署
FeishuCardOps 是一款基于飞书交互卡片的 GitLab CI/CD 流水线管理工具。无需打开浏览器、无需登录 GitLab，在飞书群聊中即可完成从选择项目到触发部署的全部操作。
一句话发版： 在群聊中发送 项目名 + 发版，即刻唤醒智能发版控制台。
| 🔒 发版进行中 · 按钮自动锁定 | ✅ 发版完成 · 锁已释放 |
 |
 |
| 主卡状态变为「处理中」，按钮变为灰色🔒 副卡实时追踪当前流水线阶段 |
流水线执行完毕后，主卡自动解锁恢复就绪 副卡显示最终执行结果 🎉 |
| 功能 | 说明 |
|---|---|
| 🏢 多项目管理 | 一个机器人管理多个项目，每个项目可包含多个仓库 |
| 🌿 动态分支发现 | 实时从 GitLab 获取最新分支列表，无需手动维护 |
| 🧩 微服务模块选择 | 针对单仓多服务架构，动态展示 TARGET_MODULE 下拉框 |
| 💬 自然语言触发 | 群聊发送 项目名 + 发版 即可唤醒发版控制台卡片 |
| 🔒 并发锁保护 | 同一仓库同时只能运行一条流水线，防止重复发版 |
| 📊 实时进度追踪 | 主卡 + 副卡架构，独立追踪每条流水线的运行状态与阶段 |
| 📢 全程通知 | 发版开始/结束自动通知群组并 @触发人 |
| ⚡ 全异步架构 | 全链路 httpx.AsyncClient，非阻塞 I/O，极速响应 |
| 🔐 用户权限控制 | 基于飞书 open_id 的 RBAC 权限，按项目/环境粒度管控 |
| ✅ 审批流 | 生产环境发版自动发起审批，审批人通过卡片操作 |
| 📋 发版历史 | 一键查看仓库近期发版记录、状态和操作人 |
用户在飞书群聊发送 "XXX项目发版"
│
▼
┌──────────────────────────┐
│ 飞书开放平台 │
│ (事件订阅 + 卡片回调) │
└──────────┬───────────────┘
│ Webhook
▼
┌──────────────────────────┐ ┌──────────────────┐
│ FeishuCardOps 服务 │──────▶│ GitLab API │
│ FastAPI · :55000 │◀──────│ 分支/流水线/任务 │
└──────────────────────────┘ └──────────────────┘
│
│ 异步轮询 Pipeline 状态
▼
┌──────────────────────────┐
│ 飞书卡片实时更新 │
│ 主卡(控制台) + 副卡(进度) │
└──────────────────────────┘
选项目 → 选仓库 → 选分支 → 选环境 → [选微服务] → 执行触发
│ │
│◀──────── 下拉框即时刷新（缓存加速）──────────────────│
│
┌────────▼────────┐
│ 🔐 权限校验 │
│ ✅ 审批流（可选） │
│ 🔒 按钮上锁 │
│ 📤 副卡弹出追踪 │
│ ⏳ 异步轮询状态 │
│ ✅ 完成后自动解锁 │
└─────────────────┘
- Docker 20.10+ & Docker Compose v2+
- 飞书开放平台企业自建应用
- GitLab Personal Access Token（
api权限）
git clone https://github.com/your-username/FeishuCardOps.git
cd FeishuCardOpscp config.example.yaml config.yaml
vim config.yaml # 填入飞书凭证、GitLab 地址和 Tokendocker compose up -d --buildcurl http://localhost:55000/healthz
# 返回 {"ok": true} 即为正常# ---- 飞书应用凭证 ----
feishu:
app_id: "cli_xxxx" # 飞书 App ID
app_secret: "xxxx" # 飞书 App Secret
verification_token: "xxxx" # 事件订阅验证 Token
# ---- GitLab 配置 ----
gitlab:
base_url: "http://gitlab:port" # GitLab 实例地址
access_token: "glpat-xxxx" # GitLab Access Token
# ---- 项目配置（支持多项目 × 多仓库 × 多环境 × 多模块）----
projects:
- name: "我的项目" # 项目名（同时也是触发词前缀）
environments: ["test", "prod"]
repos:
- name: "后端仓库"
repo: "group/backend"
id: 10 # GitLab Project ID
modules: # 【可选】微服务列表
- "service-user"
- "service-order"
- name: "前端仓库"
repo: "group/frontend"
id: 11permissions:
default_policy: "allow" # 全局默认：allow / deny
rules:
- project: "*" # 匹配所有项目
env: "test"
policy: "allow" # test 环境所有人可操作
- project: "*"
env: "prod"
policy: "deny" # prod 默认拒绝
allow_users: # 白名单
- "ou_xxxx" # 飞书 open_id
# 审批流配置
approval_required:
- project: "*"
env: "prod"
approvers:
- "ou_approver1"
- "ou_approver2"触发流水线时自动传递以下变量给 GitLab CI：
| 变量名 | 说明 | 示例值 |
|---|---|---|
ENV |
部署环境 | test |
DEPLOY_ENV |
部署环境（兼容字段） | prod |
TARGET_MODULE |
微服务模块（仅配置了 modules 时传递） | service-user |
登录 飞书开放平台 → 创建应用 → 记录 App ID / App Secret
应用详情 → 添加能力 → 机器人
| 配置项 | 值 |
|---|---|
| 请求地址 | http://你的服务器:55000/feishu/event |
| 订阅事件 | 接收消息 (im.message.receive_v1) |
| 配置项 | 值 |
|---|---|
| 卡片请求网址 | http://你的服务器:55000/feishu/card |
im:message— 获取与发送消息im:message:send_as_bot— 以应用身份发送消息contact:user.id:readonly— 获取用户 ID
创建版本 → 提交审核 → 管理员审批 → 上线使用
# 查看日志
docker compose logs -f --tail=100
# 重启服务（修改 config.yaml 后）
docker compose restart
# 停止服务
docker compose down
# 重新构建（修改代码后）
docker compose up -d --buildFeishuCardOps/
├── app.py # 入口文件（注册路由、健康检查）
├── core/ # 核心模块
│ ├── config.py # 配置加载
│ ├── feishu_client.py # 飞书 API 客户端（全异步）
│ ├── gitlab_client.py # GitLab API 客户端（全异步）
│ ├── card_builder.py # 卡片构建器（主卡/副卡/历史/审批）
│ ├── permissions.py # RBAC 权限控制
│ └── state.py # 全局内存状态管理
├── routes/ # 路由处理
│ ├── card.py # 卡片回调路由（含权限/审批/历史）
│ └── event.py # 事件订阅路由
├── services/ # 业务服务
│ ├── pipeline.py # 流水线触发与轮询（全异步）
│ ├── history.py # 发版历史记录
│ └── approval.py # 审批流管理
├── config.yaml # 运行时配置（⚠️ 含敏感信息，勿提交 Git）
├── config.example.yaml # 配置模板（含权限和审批示例）
├── requirements.txt # Python 依赖
├── Dockerfile # Docker 镜像构建
├── docker-compose.yml # Docker Compose 编排
└── README.md # 本文档
config.yaml包含敏感凭证，已在.gitignore中排除，请勿提交到 Git- 建议部署在与飞书和 GitLab 同区域的国内服务器，可获得最佳响应速度
- 状态存储在内存中，服务重启后并发锁和历史记录会重置（不影响已在运行的 GitLab 流水线）
- 生产环境建议使用 Nginx 反向代理 + HTTPS
- 权限配置
permissions段可选，不配置则保持向后兼容（所有用户可操作）
-
模块化拆分（core/routes/services） -
全异步改造（httpx.AsyncClient） -
RBAC 用户权限控制 -
审批流（生产发版需审批） -
Pipeline 发版历史记录
- 💽 引入 Redis 持久化与高可用：持久化卡片并发锁、历史记录与审批流水单，支持多副本部署
- 👤 飞书实名制自动解析：调用通讯录 API，自动把历史/审批卡片中的操作人 ID 解析为中文全名
- 📈 运维指标监控 (Prometheus + Grafana)：暴露
/metrics接口，展示发版效率和成功率大盘指标 - ⏪ “救命级”的一键回滚功能：在历史记录卡片中为成功的版本提供「一键回滚」操作支持
MIT © 2025