← 返回文档中心

BeeX App 反馈 AI 分析闭环

用户上传日志后，系统自动完成持久化、私有 OSS 下载、脱敏分析、飞书通知、重试和最终状态回写。

状态：测试与生产均已验收 业务服务：beex-service 分析服务：ai-ops-worker 更新时间：2026-07-21

1. 目标与边界

用户目标
一次提交即可
用户只负责描述问题并上传日志，不需要理解服务、OSS 或 AI 状态。
运维目标
自动给出可执行线索
飞书通知包含严重级别、证据、可能原因、建议动作和是否需要人工介入。
系统边界
AI 不直接改线上
本链路只读分析日志；修复、发布和生产操作仍走独立权限及发布流程。
主接口只做可靠持久化，不在用户请求里同步等待 AI。即使 AI Worker 短时不可用，反馈记录也不会丢失。

2. 总体架构

flowchart LR App["BeeX App / H5"] -->|"申请上传凭证"| Api["BeeX API"] App -->|"上传 zip"| Oss["私有 OSS 日志桶"] App -->|"提交反馈元数据"| Api Api --> Db[("业务数据库 app_log_uploads")] Worker["BeeX Business Worker"] -->|"认领 PENDING / 重试任务"| Db Worker -->|"刷新短时效签名下载 URL"| Oss Worker -->|"创建 APP_FEEDBACK_TRIAGE"| Ai["AI Ops Worker"] Ai -->|"安全下载、解压、脱敏、只读分析"| Oss Ai --> AiDb[("AI Worker 独立数据库")] Ai -->|"结构化结论"| Feishu["飞书故障反馈群"] Worker -->|"轮询任务结果并回写"| Db

业务数据库是反馈生命周期的事实来源；AI Worker 的独立数据库保存分析任务、执行日志和结构化结果，两者不共享业务表。

3. 完整时序

sequenceDiagram autonumber participant U as 用户 App participant API as BeeX API participant OSS as 私有 OSS participant BW as Business Worker participant AI as AI Ops Worker participant FS as 飞书 U->>API: GET /api/v1/app-logs/upload-token API-->>U: OSS 上传地址、对象 Key、临时凭证 U->>OSS: PUT feedback.zip OSS-->>U: 上传成功 U->>API: POST /api/v1/app-logs/feedback API->>API: 写入 PENDING API-->>U: feedbackId BW->>API: 定时认领可执行反馈 BW->>OSS: 生成新的短时效下载签名 BW->>AI: POST /api/v1/jobs (APP_FEEDBACK_TRIAGE) AI->>OSS: 下载 zip AI->>AI: 校验、解压、脱敏、Codex 只读分析 AI->>FS: 发送结构化故障通知 AI-->>BW: 任务 SUCCEEDED / FAILED BW->>API: 回写 COMPLETED 或安排重试

4. 服务职责

组件负责不负责
App / H5收集问题描述、设备元数据和最近日志，打 zip 并上传。不直接调用 AI，不持有永久 OSS 凭证。
BeeX API签发上传参数、校验反馈、持久化生命周期和结果。不在 HTTP 请求内等待 AI 分析。
Business Worker认领任务、刷新签名 URL、分发、轮询、超时和重试。不解析具体日志内容。
AI Ops Worker安全下载、限制解压、脱敏、只读分析、结构化输出和飞书通知。不写业务库，不部署或修改线上服务。
飞书群承接告警、人工判断和后续协作。不是反馈状态的事实数据库。

5. 接口与数据

5.1 App 侧接口

接口用途关键结果
GET /api/v1/app-logs/upload-token申请当前环境的 OSS 上传参数。对象 Key、上传地址、临时授权。
POST /api/v1/app-logs/feedback提交问题描述、日志对象和设备元数据。feedbackId，初始 AI 状态为 PENDING。

5.2 Worker 内部接口

接口调用方用途
POST /api/v1/jobsBusiness Worker以 APP_FEEDBACK_TRIAGE 创建分析任务。
GET /api/v1/jobs/{jobId}Business Worker获取任务状态和结构化分析结果。

5.3 结构化结果

{
  "severity": "LOW | MEDIUM | HIGH | CRITICAL",
  "summary": "问题结论",
  "evidence": ["有出处的日志证据"],
  "likelyCauses": ["可能原因"],
  "recommendedActions": ["建议动作"],
  "needsHuman": true,
  "analyzedFileCount": 5,
  "notificationSent": true
}

证据不足时，AI 必须明确标记 needsHuman=true，不得为追求完整结论而编造根因。

6. 状态与重试

stateDiagram-v2 [*] --> PENDING: 反馈入库 PENDING --> DISPATCHED: AI 任务创建成功 DISPATCHED --> PROCESSING: AI Worker 开始执行 PROCESSING --> COMPLETED: 分析完成并回写 PENDING --> RETRY_WAIT: 分发失败 DISPATCHED --> RETRY_WAIT: 查询超时或任务失败 PROCESSING --> RETRY_WAIT: 可重试异常 RETRY_WAIT --> PENDING: 到达下次重试时间 RETRY_WAIT --> FAILED: 超过最大尝试次数 FAILED --> PENDING: 人工重新触发
机制规则
幂等同一反馈使用确定性任务标识，重复调度不会产生多份有效分析。
签名刷新每次分发前重新生成私有 OSS 下载 URL，避免旧链接过期。
失败重试网络、临时 5xx、超时等进入重试；任务保留错误码、错误信息和尝试次数。
最终态业务表只有收到 AI 任务最终结果后才进入 COMPLETED 或 FAILED。

7. 安全边界

风险控制
日志被公开读取使用私有 OSS 桶；分析时临时签发 GET URL，不把永久密钥下发 App。
恶意 zip限制文件总量、单文件和解压后大小；拒绝路径穿越、链接文件及不支持类型。
敏感数据进入模型分析前按 Token、手机号、邮箱、密钥等规则脱敏，原始包不写入提示词之外的位置。
AI 修改工程或系统Codex 使用只读沙箱；跳过 Git 信任目录检查不等于放开文件写入权限。
角色越权任务要求 FEEDBACK_SERVICE 角色和 feedback:triage 能力。
凭证泄漏密钥只从部署环境注入，不写入 Git、日志、飞书正文或本文档。

8. 监控与排障

现象先检查常见原因
长期停在 PENDINGBusiness Worker 是否运行、任务锁和下次重试时间。Worker 未启用、配置缺失或任务尚未到执行时间。
下载返回 403日志对象是否属于当前环境桶，签名是否刚刷新。跨环境复用 URL、对象不存在或签名过期。
AI 任务立即失败AI Worker job error 和执行日志。压缩包校验失败、Codex 不可用或输入超过限制。
数据库完成但飞书没消息结果里的 notificationSent 和飞书通知配置。机器人未进群、密钥配置错误或接口限流。
结论要求人工介入evidence 和 needsHuman。日志时间窗口不足或缺少能证明根因的关键事件；这是正常安全策略。
排障时不要把测试环境的日志 URL 手工塞给生产反馈。应先调用对应环境的上传接口，再把真实上传结果提交给同一环境。

9. 验收记录

环境反馈 ID结果证据
id-test alg_mru3png0hzsgsbeos1z1 COMPLETED 分析 5 个文件；飞书通知成功；因日志与元数据不完全一致，正确要求人工确认。
id production alg_mru49wv03pehg84hmyud COMPLETED 通过生产上传接口写入生产私有桶；分析 1 个文件；飞书通知成功；业务 Worker 已回写最终态。

9.1 已发布版本

  • 业务服务提交：0387113，测试和生产 API / WA / Worker / Webhook 流水线均已成功。
  • AI Worker 提交：aadfb86，流水线 5122057 已成功。
  • 测试与生产健康检查均为 UP，生产真实上传闭环已完成。

关联说明：AI Ops Worker 服务化方案 · 弱网与缓存方案