BeeX AI Ops Worker 服务化方案与使用说明

1. 为什么要做 AI Ops Worker

BeeX 已经有很多自动化动作：H5 离线包发布、文档发布、文案同步、订单排查、日志分析、CDN 刷新、飞书通知、Git 状态检查。如果这些能力都散落在聊天会话里，团队很快会遇到三个问题：不知道谁能做什么、做完没有审计、换一个会话就丢上下文。

目标一

把能力服务化

不是靠某次对话临时跑命令，而是提供固定 API、固定角色、固定审计。

目标二

按角色分权

飞书不同群、不同应用、不同人员只能调用自己被授权的任务。

目标三

用 Git 做真值

尤其是多语言文案，翻译可以在 App 内改，但最终要由 Worker 同步回 Git。

2. 当前现状

项目	当前值	说明
服务名	`ai-ops-worker`	独立 Node.js / TypeScript 服务，不放在业务服务或管理后台服务里。
代码目录	`/Users/zwp/x/ai-ops-worker`	本地工程目录；远端部署在 `/opt/ai-ops-worker`。
远端机器	`147.139.167.175`	AI Worker 机器，后续建议仅通过 Tailscale、堡垒机或内网网关访问。
端口	`7077`	服务监听端口。对外暴露前必须增加访问控制。
数据库	`ai_ops_worker`	在共享 RDS 上独立建库，作为 BeeX 全局运维库，和业务库、Admin 库分开。
配置文件	`/etc/ai-ops-worker.env`	远端环境变量文件。密钥不进 Git。
systemd	`ai-ops-worker.service`	用于启动、重启、查看日志。
部署流水线	`ai-ops-worker-id / 5122057`	由云效测试并通过阿里云云助手部署；正式变更不应绕过流水线手工覆盖。
Git 监控	递归扫描工作区全部 Git 仓库	轮询是事实来源，GitHub push webhook 用于加速；新仓库无需写死列表。

已经落地的重点是“服务骨架 + 独立库 + API Key + 角色权限 + Job 表 + 审计表 + i18n 同步 Git 的执行器”。这一步先保证架构边界对，后续再往里面加 H5 发布、文档监控、Uptime、订单排查等能力。

3. 总体架构

flowchart TD User["使用者
飞书群 / 运维 / 开发 / 翻译"] --> Entry["调用入口
飞书机器人 / 内部页面 / curl"] Entry --> Worker["ai-ops-worker
Fastify API"] subgraph Auth["认证与授权"] Key["X-AI-Ops-Key"] Role["Role
OWNER / OPS / DEVELOPER / TRANSLATOR / VIEWER"] Cap["Capability
job:read / i18n:sync-git / h5:deploy"] end Worker --> Key Key --> Role Role --> Cap Cap --> JobApi["Job API"] subgraph DB["独立数据库 ai_ops_worker"] Roles["ai_ops_roles"] Keys["ai_ops_api_keys"] Jobs["ai_ops_jobs"] Logs["ai_ops_job_logs"] Audit["ai_ops_audit_logs"] end JobApi --> Jobs JobApi --> Logs JobApi --> Audit subgraph Runner["任务执行器"] GitStatus["GIT_STATUS"] I18nSync["I18N_SYNC_TO_GIT"] SelfCheck["RUN_SELF_CHECK"] FeedbackTriage["APP_FEEDBACK_TRIAGE"] Reserved["H5_PACKAGE_DEPLOY / DOC_SYNC_NOTIFY
预留"] end Jobs --> Runner I18nSync --> AdminApi["Admin API
i18n_copy_entries"] FeedbackTriage --> AppLogs["私有 OSS
反馈日志包"] FeedbackTriage --> Feishu["飞书
故障反馈群"] I18nSync --> Git["Git Repo
beex-app-h5"] GitStatus --> Git SelfCheck --> Host["AI Worker 机器 / 工作区"] Worker --> Response["返回 jobId / 状态 / 日志 / 结果"] Response --> User

关键原则

原则	解释
服务独立	AI Ops Worker 不混入 `beex-service`、`beex-admin-page` 或 `beex-admin-service`，避免运维能力污染业务边界。
数据库独立	使用独立 schema 和独立账号，当前是 `ai_ops_worker`。不按国家或测试/正式命名，内部通过任务 payload/envCode 区分目标环境。
权限独立	每个飞书应用、群机器人、内部页面可以配置不同 API Key，对应不同角色。
任务可审计	每次任务创建、取消、API Key 创建/禁用都进入审计表。
Git 是发布真值	动态编辑的数据如果要长期生效，最终必须同步回 Git，再通过 H5 构建发布。

4. 角色与权限

角色	适用对象	能力	禁止做什么
`OWNER`	系统负责人	全部能力；可创建和禁用 API Key。	不能把 OWNER Key 发到普通群里。
`OPS`	运维机器人、核心运维群	读任务、取消任务、Git 状态、诊断、文档同步、H5 发布、i18n 同步。	不能管理 API Key。
`DEVELOPER`	开发机器人、开发群	读任务、Git 状态、H5 发布、i18n 同步。	不能取消他人任务，不能创建 Key。
`TRANSLATOR`	翻译校对入口	读任务、发起 i18n 同步到 Git。	不能发布 H5，不能执行运维诊断。
`VIEWER`	只读看板	读任务、读 Git 状态。	不能创建执行型任务。

sequenceDiagram autonumber actor Owner as Owner/系统负责人 participant Worker as ai-ops-worker participant DB as ai_ops_worker Owner->>Worker: POST /api/v1/api-keys
keyName=feishu-translator-bot, roleCode=TRANSLATOR Worker->>Worker: 校验 X-AI-Ops-Key 是否有 api-key:manage Worker->>DB: 写入 key_hash、key_name、role_code Worker->>DB: 写入审计 API_KEY_CREATE Worker-->>Owner: 返回 apiKey
只返回一次 Note over Owner,Worker: 原始 API Key 只保存在调用方安全配置里，数据库只存 SHA-256 hash

5. API 使用说明

5.1 健康检查

curl -fsS http://127.0.0.1:7077/health

健康检查不需要 API Key，用于本机、systemd、网关或 Uptime 检查服务是否存活。

5.2 鉴权方式

curl -H "X-AI-Ops-Key: $AI_OPS_KEY" \
  http://127.0.0.1:7077/api/v1/me

也支持 Authorization: Bearer <api-key>，但团队内部统一推荐 X-AI-Ops-Key。

5.3 查询当前身份和能力

curl -H "X-AI-Ops-Key: $AI_OPS_KEY" \
  http://127.0.0.1:7077/api/v1/me

5.4 查询可用任务类型

curl -H "X-AI-Ops-Key: $AI_OPS_KEY" \
  http://127.0.0.1:7077/api/v1/capabilities

5.5 创建任务

curl -X POST http://127.0.0.1:7077/api/v1/jobs \
  -H "Content-Type: application/json" \
  -H "X-AI-Ops-Key: $AI_OPS_KEY" \
  -d '{
    "type": "GIT_STATUS",
    "payload": {
      "repoPath": "/opt/beex-ai-workspace/x/beex-app-h5"
    }
  }'

5.6 查看任务状态与日志

curl -H "X-AI-Ops-Key: $AI_OPS_KEY" \
  http://127.0.0.1:7077/api/v1/jobs/job_xxx

curl -H "X-AI-Ops-Key: $AI_OPS_KEY" \
  http://127.0.0.1:7077/api/v1/jobs/job_xxx/logs

5.7 查看或触发 Git 监控

curl -H "X-AI-Ops-Key: $AI_OPS_KEY" \
  http://127.0.0.1:7077/api/v1/git-monitor/status

curl -X POST -H "X-AI-Ops-Key: $AI_OPS_KEY" \
  http://127.0.0.1:7077/api/v1/git-monitor/scan

POST /webhooks/github/commits 是可选加速入口，会校验 X-Hub-Signature-256 后触发同一套扫描和去重逻辑。

sequenceDiagram autonumber actor Client as 调用方
飞书机器人/内部页面/curl participant Worker as ai-ops-worker API participant Auth as Auth/Capability participant DB as ai_ops_worker participant Runner as JobRunner participant Git as Git/Admin API/系统命令 Client->>Worker: POST /api/v1/jobs Worker->>Auth: 认证 API Key Auth-->>Worker: actor + role Worker->>Auth: 校验 jobType 对应 capability Worker->>DB: INSERT ai_ops_jobs(status=QUEUED) Worker->>DB: INSERT ai_ops_audit_logs(JOB_CREATE) Worker-->>Client: 返回 jobId Worker->>Runner: enqueue() Runner->>DB: 抢占 QUEUED 任务并改为 RUNNING Runner->>DB: 写 job_logs: Starting Runner->>Git: 执行具体任务 Git-->>Runner: stdout/stderr/result Runner->>DB: 写 job_logs Runner->>DB: 更新 SUCCEEDED / FAILED Client->>Worker: GET /api/v1/jobs/{jobId}/logs Worker-->>Client: 返回完整日志

6. 任务类型

任务类型	需要权限	当前状态	用途
`GIT_STATUS`	`git:read`	已实现	查询指定仓库当前分支、HEAD、未提交变更。
`I18N_SYNC_TO_GIT`	`i18n:sync-git`	已实现	从 Admin 文案表读取 App 内翻译修改，更新 H5 仓库 CSV/JSON，并按配置提交 Git。
`RUN_SELF_CHECK`	`ops:diagnose`	已实现	扫描 AI 工作区 Git 仓库状态，后续扩展为服务健康自检。
`APP_FEEDBACK_TRIAGE`	`feedback:triage`	已实现	下载反馈 zip、校验并脱敏，以只读 Codex 分析后输出结构化结论并通知飞书。
`GIT_COMMIT_NOTIFY` / 内置 Git Monitor	`git:read`	已实现	递归发现全部仓库、拉取远端分支、按持久化游标去重，并把新提交通知到飞书。GitHub webhook 只触发即时扫描，轮询仍是事实来源。
`H5_PACKAGE_DEPLOY`	`h5:deploy`	预留	后续接云效或统一发布服务，用来构建/发布 H5 离线包。
`DOC_SYNC_NOTIFY`	`doc:sync`	预留	这个独立 Job 类型仍是预留；文档仓库的新提交已经由通用 Git Monitor 监控并通知，后续只需补“自动发布 PRD 站”等文档专属动作。

6.1 GIT_STATUS 示例

{
  "type": "GIT_STATUS",
  "payload": {
    "repoPath": "/opt/beex-ai-workspace/x/beex-app-h5"
  }
}

6.2 I18N_SYNC_TO_GIT 示例

{
  "type": "I18N_SYNC_TO_GIT",
  "payload": {
    "countryCode": "ID",
    "repoPath": "/opt/beex-ai-workspace/x/beex-app-h5",
    "adminApiBase": "https://admin-api-id-test.beexofficial.com",
    "dryRun": true,
    "pullBefore": true,
    "pushAfter": true,
    "commitMessage": "chore(i18n): sync ID app copy"
  }
}

推荐操作方式：第一次永远先 dryRun=true，看 diffPreview 是否符合预期。确认后再用 dryRun=false 提交和推送。

7. 文案同步闭环

文案的最终真值仍然是 H5 仓库里的 i18n/beex-translations.csv 和构建产物 public/i18n/beex-translations.json。App 内编辑只是为了让翻译人员可以在真实页面上校对文案，改完后由 AI Ops Worker 批量同步回 Git。

sequenceDiagram autonumber actor Dev as 开发 actor Translator as 翻译人员 participant H5 as BeeX H5/App 页面 participant Admin as Admin API
i18n_copy_entries participant Worker as ai-ops-worker participant Repo as beex-app-h5 Git Repo participant Pipeline as H5 构建/发布 Dev->>Repo: 在代码中新增页面文案/默认文案 Dev->>Repo: 运行提取/检查工具
生成或更新 CSV Key Dev->>Pipeline: 构建 H5 Pipeline-->>H5: 新 H5 包展示默认文案 Translator->>H5: 打开 App 内文案编辑模式 Translator->>H5: 点击当前文案并修改 H5->>Admin: 保存 key + locale + text Admin-->>H5: 保存成功，页面立即显示新文案 Translator->>Worker: 发起 I18N_SYNC_TO_GIT dryRun Worker->>Admin: 拉取已修改文案 Worker->>Repo: 更新 i18n CSV/JSON，生成 diffPreview Worker-->>Translator: 返回差异预览 Translator->>Worker: 确认后 dryRun=false Worker->>Repo: git pull --ff-only Worker->>Repo: 写 CSV/JSON + i18n check/export Worker->>Repo: git commit + git push Repo->>Pipeline: 后续触发 H5 构建发布 Pipeline-->>H5: 新包内置正式文案

开发、翻译、AI Worker 的职责

角色	应该做	不应该做
开发	在代码里新增文案、保持页面路径和 key 可追踪、提交代码。	不要在飞书或数据库里手工发明 key。
翻译人员	在 App 真实页面里改当前看到的文案，只关注语言质量。	不能改 key，不能改页面路径，不能发布 H5。
AI Worker	拉取 Admin 文案改动，更新 Git 文件，跑检查，提交记录。	不能自行改业务含义，不绕过 Git 直接改线上包。

文案删除怎么维护

删除文案不应该由翻译人员在 App 内完成。文案是否删除属于代码结构变化，由开发删除页面引用或删除旧 key，再由提取/检查工具识别。Admin 中历史编辑记录可以保留，不能作为页面继续展示的依据。

8. 飞书分权接入

不要一个飞书群里什么都能做。每个群、每个机器人、每个应用都应该只拿到自己角色对应的 API Key。

sequenceDiagram autonumber actor User as 飞书群成员 participant Bot as 飞书应用/机器人 participant Worker as ai-ops-worker participant DB as ai_ops_worker User->>Bot: @AI 文案同步 ID Bot->>Worker: POST /api/v1/jobs
X-AI-Ops-Key=TRANSLATOR Key Worker->>DB: 查 key_hash 对应角色 TRANSLATOR Worker->>Worker: 校验 I18N_SYNC_TO_GIT 需要 i18n:sync-git Worker-->>Bot: 返回 jobId Bot-->>User: 已创建同步任务 User->>Bot: @AI 发布 H5 Bot->>Worker: POST /api/v1/jobs
同一个 TRANSLATOR Key Worker->>Worker: 校验 H5_PACKAGE_DEPLOY 需要 h5:deploy Worker-->>Bot: 403，无权限 Bot-->>User: 当前机器人无发布权限

飞书入口	建议角色	可做的事
翻译校对群	`TRANSLATOR`	同步文案到 Git、查看同步任务结果。
开发协作群	`DEVELOPER`	查 Git、触发 H5 发布、同步文案。
运维告警群	`OPS`	诊断服务、查看任务、取消异常任务、触发发布。
管理者私聊/小群	`OWNER`	创建/禁用 API Key，处理高权限动作。

9. 运维排障

9.1 查看服务状态

ssh root@147.139.167.175
systemctl status ai-ops-worker --no-pager
journalctl -u ai-ops-worker -n 120 --no-pager

9.2 重启服务

systemctl restart ai-ops-worker
curl -fsS http://127.0.0.1:7077/health

9.3 看数据库表

mysql -h "$AI_OPS_DB_HOST" -u "$AI_OPS_DB_USER" -p"$AI_OPS_DB_PASSWORD" \
  ai_ops_worker \
  -e "select job_id, job_type, status, requested_by, created_at from ai_ops_jobs order by created_at desc limit 20;"

9.4 常见问题

现象	优先检查	处理方式
返回 401	API Key 是否正确、是否被禁用。	用 OWNER 查 `/api/v1/api-keys`，必要时重新生成 Key。
返回 403	角色是否有任务需要的 capability。	换对应角色的 Key，不要把 OWNER Key 发到普通群。
任务一直 QUEUED	服务进程是否还活着，JobRunner 是否报错。	看 systemd 日志，重启服务后再观察。
i18n 同步失败	Admin API 是否可访问，H5 repo 是否 dirty，Git 是否能 push。	先 dryRun，看日志里的具体命令和错误。

10. 安全边界

AI Ops Worker 是能执行命令的服务，不能像普通业务接口一样裸露公网。当前阶段建议只允许本机、内网、Tailscale、SSH tunnel 或 API Gateway 白名单访问。

事项	规则
密钥存储	远端只放 `/etc/ai-ops-worker.env`，本地只放 `.secrets`，不进 Git。
API Key	数据库只存 hash，原文只在创建时返回一次。
网络入口	上线前必须有 IP 白名单、Tailscale、网关签名或飞书事件签名校验。
生产动作	正式环境发布、回滚、资金规则、删除数据需要额外确认和审计。
路径限制	任务只能访问 `AI_OPS_WORKSPACE_ROOT` 内部路径，防止传入任意系统路径。

11. 演进计划

阶段	要补的能力	完成标准
阶段 1	文案同步 Git 闭环	翻译在 App 内修改，AI Ops Worker dryRun 预览，确认后 commit/push 到 H5 仓库。
阶段 2	飞书应用接入	不同飞书群使用不同角色 Key，不能越权执行任务。
阶段 3	H5 发布任务	Worker 可以触发云效或内部发布 API，返回 H5 包版本、发布人、发布结果。
阶段 4（通知已完成）	文档仓库监控与发布	`beex-doc` 新提交已由通用 Git Monitor 通知飞书；自动发布 PRD 站仍待接入。
阶段 5	业务排障工具	输入联盟码、订单号、商品链接，即可自动拉点击、转链、三方原始响应、订单、佣金和钱包状态。