Agentic BI — 03-20 运维与修复¶
前端构建问题修复¶
问题现象¶
Dad 反馈开发站点报错：
根因分析¶
构建产物错误:
- dist/assets/index-*.js 中包含 require("@logto/react")
- CommonJS 语法在浏览器环境不支持
- 构建工具未正确处理依赖转换
技术细节澄清¶
require("util") 问题:
虽然 bundle 中也出现了 require("util")，但该调用位于 try/catch 检测逻辑内，不会导致浏览器实际报错。真正的问题是 Logto React 组件的 require 调用。
解决方案¶
重新构建策略: - 重新运行前端构建流程 - 确保产物使用 ES import 语法 - 验证所有第三方依赖正确转换
后端服务配置¶
服务启动问题¶
现象:
- 系统设置页面打不开
- /api/system-config 和 /api/config 请求失败
- 聊天功能不可用
根因与解决¶
后端未运行: - FastAPI 服务进程异常退出 - 缺少进程管理和自动重启机制
PM2 托管方案:
服务管理优化¶
PM2 的优势: - 自动重启机制 - 进程监控和日志管理 - 零停机时间重载 - 资源使用统计
模型配置问题¶
配置缺失现象¶
Dad 反馈：模型似乎没有正确配置，系统响应异常。
配置文件检查¶
配置路径验证: - 检查 YAML 配置文件存在性 - 验证各 Agent 模型分配 - 确认 Azure OpenAI 密钥配置
默认配置恢复:
数据持久化状态¶
Session 管理检查¶
多轮对话数据: - 验证 session 存储机制 - 检查上下文保持能力 - 确认对话历史完整性
技能注册状态¶
技能系统验证: - 保险专属技能可用性 - 技能参数传递正确性 - DuckDB 数据表访问状态
系统健康检查¶
API 接口测试¶
核心接口验证:
GET /api/system-config - 系统配置查询
GET /api/config - 模型配置查询
PUT /api/config - 模型配置更新
POST /api/chat - 聊天接口
GET /api/eventstream - SSE 推理链
前端功能测试¶
UI 组件验证: - 登录认证流程 - 聊天界面响应 - 推理链展示 - 配置页面访问 - 图表渲染功能
运维经验总结¶
前端构建规范¶
- 依赖管理: 确保第三方包兼容浏览器环境
- 构建验证: 本地测试构建产物，避免线上报错
- 错误监控: 浏览器控制台错误应纳入监控
后端服务管理¶
- 进程守护: 使用 PM2 等工具确保服务可用性
- 配置管理: 配置文件变更需要重启验证
- 健康检查: 定期验证核心接口可用性
问题排查流程¶
- 前端错误: 浏览器控制台 → 构建产物 → 依赖分析
- 后端错误: 服务状态 → 日志分析 → 配置检查
- 集成问题: 接口测试 → 数据流追踪 → 端到端验证
维护最佳实践¶
- 监控覆盖: 关键功能应有自动监控
- 回滚准备: 保留上一版本的快速回滚能力
- 文档更新: 运维问题和解决方案应记录在案
修复时间线¶
| 时间节点 | 问题类型 | 解决方案 | 负责人 |
|---|---|---|---|
| 发现阶段 | 前端构建错误 | 重新构建产物 | bot |
| 发现阶段 | 后端服务停止 | PM2 托管启动 | bot |
| 验证阶段 | 模型配置检查 | 配置文件恢复 | bot |
| 测试阶段 | 端到端验证 | 功能全面测试 | bot |
系统稳定性评估¶
当前状态¶
服务层面: - ✅ 前端构建产物正常 - ✅ 后端服务稳定运行 - ✅ 数据库连接正常 - ✅ 认证服务可用
功能层面: - ✅ 多轮对话正常 - ✅ 推理链展示正常 - ✅ 图表生成正常 - ✅ 配置页面正常
风险点识别¶
- 单点故障: PM2 托管减少但未消除
- 配置漂移: 手动配置变更缺少版本控制
- 依赖更新: 第三方包更新可能引入新问题
改进方向¶
- 自动化部署: 减少手动操作引入的错误
- 配置管理: 引入配置即代码（Infrastructure as Code）
- 监控报警: 主动发现问题而非被动响应
这次运维修复展现了项目从开发期到运维期的关键转变，通过系统化的问题排查和修复流程，确保了 Agentic BI 的持续稳定运行。