慧行引擎踩坑记录 (Pitfalls & Lessons Learned)

原则: 前事不忘，后事之师。所有遇到的错误、异常、非预期行为，无论大小，必须在此记录。 触发条件: 遇到任何报错、警告、配置失败、逻辑卡点时，立即更新此文档，然后再尝试解决。 负责人: 所有开发者 (一龙、二龙、三龙...)

---

2026-03-18: Docker 部署与构建问题

坑 #1: Windows 路径与 Docker 兼容性问题

• 现象: 在 Windows 本地开发时，Docker Compose 构建失败，报错路径错误或权限不足。
• 原因: Windows 的路径分隔符 (\) 与 Linux (/) 不同，且 Docker Desktop 对文件挂载的处理与原生 Linux 不同。
• 解决:
  • 生产/测试环境统一使用 Ubuntu 服务器。
  • 开发时尽量避免依赖本地文件挂载，优先使用 Docker Volume。
  • 所有部署脚本必须在 Linux 环境下测试通过。
• 教训: 不再在 Windows 上进行 Docker 最终构建测试。远程 Ubuntu 服务器作为唯一的开发/测试/演示环境。

坑 #2: package.json 缺失导致构建失败

• 现象: docker compose up -d --build 报错：npm error enoent Could not read package.json。
• 原因: backend 目录下确实缺少 package.json 文件（之前开发时遗漏，或 Git 提交时漏掉）。
• 解决:
  1. 在 backend/ 目录补全 package.json。
  2. 确保 .dockerignore 没有错误地忽略该文件。
• 教训: 创建“环境预检脚本”，在 docker compose up 前自动检查关键文件 (package.json, Dockerfile, .env) 是否存在。

坑 #3: 数据库连接超时 (ECONNREFUSED)

• 现象: API 容器启动时报错 connect ECONNREFUSED 172.19.0.3:5432，然后不断重试。
• 原因: PostgreSQL 容器启动较慢，API 容器先启动并尝试连接，此时 DB 尚未准备好。
• 解决:
  • Docker Compose 的 depends_on 只能保证启动顺序，不能保证服务就绪。
  • 代码中增加重试机制 (TypeORM 已自带重试)。
  • 或者使用 wait-for-it.sh 脚本等待 DB 端口就绪。
• 教训: 生产环境部署时，需预留足够的 DB 启动等待时间，或优化健康检查 (healthcheck)。

坑 #4: 宝塔面板 Docker 插件报错 KeyError: 'Labels'

• 现象: 宝塔面板 [Docker 管理器] 显示错误，无法查看镜像列表。
• 原因: 宝塔面板版本 Bug，解析 Docker 镜像信息时缺少 Labels 字段。
• 解决: 忽略此错误。直接使用命令行 docker compose 操作，不依赖宝塔面板。
• 教训: 生产环境尽量使用原生 CLI 工具，减少对有 Bug 的 GUI 面板的依赖。

---

2026-03-17: 代码与架构设计

坑 #5: 实体类字段缺失

• 现象: 种子脚本插入 budget 字段时报错 column "budget" does not exist。
• 原因: 数据库表结构未同步，TypeORM 的 synchronize: true 在某些情况下未生效。
• 解决: 手动重启 API 容器触发同步，或手动执行 Migration。
• 教训: 字段变更后，必须显式检查数据库表结构，不能盲目信任自动同步。

---

待办：自动化检查

• 创建 pre-flight-check.sh 脚本，在部署前自动检查：
  • Docker 是否运行
  • 关键文件是否存在
  • 端口是否被占用
  • 磁盘空间是否充足

---

持续更新中...