FDE Wiki

FDE-Runbook-Template

9分钟阅读

MoMoDi FDE Runbook Template (v1.0)

前向部署工程师交付模板
用于 FDE 项目移交、客户自运营交接和故障排查。
原则：能自动化的流程写在代码里，不能自动化的详细写在 Runbook 里。每次故障后更新本文件。

1. 系统概览 (System Identity)

项目内容说明实际填写
客户名称客户的企业/部门官方名称[客户/企业名称]
系统名称本次部署交付的系统名称MoMoDi × [客户名称] 交付系统
FDE 负责人负责本次现场部署的工程师姓名及联系方式[姓名 / 电话 / 飞书]
客户运维接口人客户侧指定的日常运维负责人姓名及联系方式[姓名 / 角色 / 邮箱]
系统上线日期生产环境正式交付运行的日期[YYYY-MM-DD]
Runbook 版本本手册版本，每次变更升级记录v1.0
紧急联系渠道24小时紧急故障响应的电话或即时通信群组[24h 电话 / 应急飞书群]

2. 系统架构与依赖 (Architecture & Dependencies)

2.1 部署组件拓扑

       ┌─────────────┐     ┌────────────────┐     ┌──────────────┐
       │  用户/客户   │──▶  │  m.moments.top │──▶  │   OSS 存储桶  │
       │ (飞书 / Web) │     │   API Gateway  │     │ momodi-xxxxx │
       └─────────────┘     └────────────────┘     └──────────────┘
                                   │
                                   ▼
                           ┌────────────────┐
                           │    AI 引擎服务   │
                           │  (报告/图谱生成) │
                           └────────────────┘

(注：根据实际系统部署结构替换上图，例如增加本地数据库、Redis 缓存或 Graphify 查询引擎节点)

2.2 关键依赖关系

依赖项主要用途健康检查方式 (Health Check)故障兜底方案 (Fallback)
API 网关报告及图谱交付入口请求 /api/health 返回 HTTP 200N/A (单点故障需升级)
云存储 (OSS)静态报告、交互式 HTML 存储执行文件上传 / 读取测试切换至备用云存储 (S3)
LLM 推理 APIAI 报告/图谱生成调用模型 API 响应测试切换至备用模型 / 自建离线模型
Graphify 引擎代码/文档图谱生成及查询命令行运行 graphify query "test"降级为常规正则/向量检索

2.3 部署环境列表

环境访问地址 (URL / IP)主要用途访问限制 / 安全控制
生产环境https://m.moments.top客户生产业务运行公开访问 / HTTPS 强制加密
Staging 环境[Staging IP / URL]预发布测试与 Demo 演示VPN 准入 / 白名单限制
开发环境localhost / Dev Server内部开发与集成验证内部开发网络

3. 日常运维操作 (Daily Operations)

3.1 核心业务流程 (例如：报告生成流程)

  [步骤 1: 需求接入] ──▶ 确认客户交付边界
         │
         ▼
  [步骤 2: AI引擎执行] ──▶ AI 执行数据提取与生成 (~3-8分钟)
         │
         ▼
  [步骤 3: 报告/图谱生成] ──▶ 生成 MBB HTML 或 Graphify 可视化图谱
         │
         ▼
  [步骤 4: 质量审核] ──▶ 检查数据源标注及置信度标签
         │
         ▼
  [步骤 5: 部署分发] ──▶ 上传至 OSS，调用 oss-upload.py 脚本
         │
         ▼
  [步骤 6: 交付给客户] ──▶ 发送 moments.top/api/oss/... 链接

3.2 每日健康巡检 (Daily Health Check)

检查项频率巡检方法预期正常结果
存储可用性每日上传测试文件并读取，然后自动删除上传下载无延迟，状态码 200
API 服务可用性每日curl -I https://m.moments.top/api/health返回 HTTP 200 OK
AI 模型服务每日调用单次标准数据提取测试1分钟内输出完整响应，无超时

3.3 交付数据时效性 (Retention & TTL)

交付类型建议刷新周期触发条件
市场调研报告每季度 / 每月行业发生重大变化或有新报告源发布
Graphify 知识图谱每次 Git 变更自动更新Git Hook 自动触发或代码库有重大重构

4. 故障响应与恢复 (Troubleshooting Playbook)

4.1 故障等级判定 (Severity Tiers)

级别定义描述响应时效 (SLA)通知及升级路径
P0系统完全不可用 / 客户生产阻断15分钟内立即通知技术 Owner，同步给客户接口人
P1部分重要功能失效 / 链接无法访问30分钟内通知 FDE 负责人，通知开发团队排查
P2报告质量问题 / 数据源置信度异常4小时内记录工单，分配给对应分析师或工程师
P3小优化建议 / 文档错误24小时内 (下个工作日)记录入 Backlog，在日常迭代中排期

4.2 常见故障诊断与修复卡片 (Failure Cards)

卡片 A: 交付链接访问 404

  • 可能原因：OSS 路径 Key 错误；文件上传中断；Nginx 转发配置失效。
  • 诊断方法：
    1. 登录 OSS 控制台，检查对应 Key 的文件是否存在。
    2. 运行 curl -I [链接] 查看响应头中的 Server 标识。
  • 修复步骤：
    • 若文件不存在：重新运行 oss-upload.py 上传。
    • 若配置失效：重启 Nginx 服务 sudo systemctl restart nginx。

卡片 B: 报告内容生成超时 (Timeout)

  • 可能原因：LLM API 限制；下游依赖响应过慢；扫描目录过大。
  • 诊断方法：检查服务日志 tail -n 100 /var/log/ai-engine.log 查找 ReadTimeout 或 RateLimit 错误。
  • 修复步骤：
    • 临时：切换 API 路由至备用模型端点。
    • 优化：在 Graphify 运行时增加排除规则，减少单次处理的文件数。

卡片 C: 置信度标签异常 (大量 AMBIGUOUS)

  • 可能原因：源数据质量差、结构混乱或 LLM 推理缺乏上下文。
  • 修复步骤：人工补齐权威数据源；优化 RAG 检索提示词；重新构图。

4.3 故障升级流程图 (Escalation Path)

   [故障发生]
       │
       ▼
   [FDE 负责人响应并排查]
       │
       ├────── (P0级：15分钟未解决) ──▶  [通知技术负责人 + CEO] ──▶ [启动 15min 客户同步机制]
       │
       └────── (P1级：30分钟未解决) ──▶  [分配开发专人排查] ──▶ [24小时内交付修复补丁]

5. 变更与回滚 (Change & Rollback)

5.1 回滚触发指标

  • 执行变更后核心 API 返回 5xx 错误率 > 1%。
  • 升级后生成报告平均时间 > 15 分钟（基线为 5 分钟）。
  • 客户侧反馈重大阻断性问题。

5.2 回滚操作步骤 (Rollback Steps)

  1. 暂停所有当前正在进行的后台写入任务。
  2. 运行回滚脚本，恢复到上一个稳定版本的 Git Tag 或 OSS 备份包： 
    # 示例：回滚 API 网关容器版本
docker-compose down
docker-compose run -d --name gateway-api image:stable-v1.0.0
  3. 运行 Smoke Test 验证核心链路是否恢复。
  4. 确认无误后，发送客户通知模板。

6. 变更记录 (Change Log)

版本日期变更内容说明变更人
v1.0[YYYY-MM-DD]初始版本创建[姓名 / 角色]

关系图谱

反向链接