diff --git a/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md b/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md index a569b29..b781f90 100644 --- a/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md +++ b/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md @@ -152,6 +152,28 @@ RESTORE_CONFIRM=YES \ - 管理后台登录 - 管理后台数据列表 +## 监控与告警 + +应用提供两类探针: + +- `/api/health`:进程存活检查,不访问外部依赖。 +- `/api/ready`:流量就绪检查,同时验证 MySQL 和 Redis;任一必需依赖不可用时返回 HTTP 503。 + +建议上游监控系统每 30 秒访问一次 `/api/ready`,连续 3 次失败触发告警。日志采集系统按容器标准输出采集单行 JSON,并至少对以下情况告警: + +- 5 分钟内 HTTP 5xx 比例超过 2%。 +- `/api/ready` 连续失败。 +- AI 请求超时或外部服务错误持续增长。 +- 问答队列持续接近上限或频繁拒绝请求。 +- MySQL、Redis 容器重启或磁盘使用率超过 80%。 +- 定时备份任务失败、校验文件缺失或超过 24 小时没有新备份。 + +用户反馈错误时,优先获取响应头 `X-Request-ID`,再到日志平台检索同一请求 ID。发布完成后执行: + +```bash +BASE_URL=https://qa.huiyushuyuan.cn ./scripts/production_smoke_test.sh +``` + ## 生产待补事项 - 在域名入口或上游反向代理配置 HTTPS 证书。 diff --git a/ai_knowledge_base_v2/development_records/2026-07-10-production-readiness-phase2.md b/ai_knowledge_base_v2/development_records/2026-07-10-production-readiness-phase2.md index 5848adf..5456de5 100644 --- a/ai_knowledge_base_v2/development_records/2026-07-10-production-readiness-phase2.md +++ b/ai_knowledge_base_v2/development_records/2026-07-10-production-readiness-phase2.md @@ -35,3 +35,25 @@ - 备份文件非空、使用安全参数、支持压缩,并提供可执行的恢复与校验流程。 - 管理后台入口继续减少职责,至少提取系统配置定义与对应状态逻辑。 - 全量自动验证、前后端构建、迁移与生产 Compose 检查全部通过。 + +## 实施结果 + +1. `d7d9514`:新增原生 ASGI 请求观测中间件,提供请求 ID 和单行 JSON 访问日志;新增 `/api/ready`,分别检查 MySQL 与 Redis;生产后端容器改用就绪健康检查,网关等待后端健康后启动。 +2. `0bc7679`:备份改为压缩 SQL 和 SHA-256 校验文件,去除默认密码并增加保留策略;新增带显式确认、校验和检查及迁移版本检查的恢复脚本。 +3. `6d164a7`:将系统配置类型、分组、默认值和展示定义从管理后台入口页提取到独立模块,`App.vue` 从约 1660 行降至 1401 行。 +4. `3671275`:兼容 Linux `sha256sum` 和 macOS `shasum`,增加 `--no-tablespaces`,确保最小权限业务账号可完成备份。 +5. `75c5446`:新增生产冒烟脚本,自动检查存活、就绪、用户端、管理后台、后台静态资源和请求 ID。 + +## 验证记录 + +- 后端关键测试扩展为 8 项,全部通过。 +- 使用当前开发 MySQL 真实生成压缩备份及校验文件,再恢复到隔离数据库,恢复后共检查到 13 张表;完成后已删除隔离数据库和临时文件。 +- 构建并启动隔离生产环境,后端 4 个 worker、MySQL、Redis 均健康,网关只暴露统一端口。 +- 生产冒烟脚本全部通过,JSON 日志可被 `jq` 正常解析并包含请求 ID、方法、路径、状态码和耗时。 +- 全程未增加向量数据库、embedding 或向量索引依赖,检索仍遵循已开放知识库范围内的飞书搜索/直读方案。 + +## 后续维护原则 + +- 告警与图表平台属于部署环境能力,可接入现有日志平台或监控平台;应用已经提供结构化日志和存活/就绪信号。 +- 管理后台后续新增或修改某个业务模块时,继续按用户、知识库、Agent、模型、审计页面逐步拆分,避免为追求一次性重构而引入回归。 +- 不得未经评审引入向量数据库;重新评估必须以可量化召回率、延迟或新数据源需求为依据。