# 生产上线优化第二批计划与实施记录

## 范围

第一批已解决直接阻断上线的功能、安全和生产部署问题。第二批继续完成以下内容：

1. 可观测性：结构化访问日志、请求 ID、异常关联、数据库与 Redis 就绪检查、容器健康检查。
2. 可恢复性：完善数据库备份脚本，新增恢复脚本、备份校验和操作文档，避免“有备份但无法恢复”。
3. 可维护性：继续拆分管理后台超大入口文件和后端高复杂度职责，保持功能行为不变。
4. 持续验证：扩展自动化测试与发布检查，覆盖健康检查、日志中间件、备份脚本和生产配置。

## 知识库检索架构决策

本项目明确不使用向量数据库，也不在本阶段引入 embedding、向量索引或向量检索服务。

当前适用方案：

- 检索范围只包含后台已开放的知识库。
- 后端通过飞书搜索接口或飞书节点直读获取内容。
- 在限定知识库范围内完成关键词匹配、片段选择和排序，再交给 Agent 组织回答。
- MySQL 保存业务配置、会话和审计数据，Redis 负责缓存、限流、队列和安全状态。

不引入向量数据库的原因：当前知识范围、检索方式和准确性要求可以由定向搜索与飞书直读满足；增加向量数据库会引入额外的数据同步、切片、重建索引、权限一致性、部署和运维成本，而当前没有对应收益。

只有在以下条件出现时才重新评估，且必须先修改决策文档再实现：

- 知识规模增长后，定向搜索无法满足召回准确率或延迟要求。
- 大量非飞书来源的非结构化文档需要统一语义检索。
- 已有可量化测试证明关键词/直读方案无法满足业务验收标准。

## 验收条件

- 每个请求具有请求 ID，访问日志为单行 JSON，错误日志可按请求 ID 关联。
- `/api/health` 只表示进程存活，`/api/ready` 校验数据库与 Redis；生产容器使用就绪接口作为健康检查。
- 备份文件非空、使用安全参数、支持压缩，并提供可执行的恢复与校验流程。
- 管理后台入口继续减少职责，至少提取系统配置定义与对应状态逻辑。
- 全量自动验证、前后端构建、迁移与生产 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、模型、审计页面逐步拆分，避免为追求一次性重构而引入回归。
- 不得未经评审引入向量数据库；重新评估必须以可量化召回率、延迟或新数据源需求为依据。
