fquiz/memory/2026-05-02.md

Work Log - 修复 Docker Flower 容器重启异常（2026-05-02）

• 背景：

  • docker compose ps 显示 fquiz-flower 持续 Restarting。
  • docker compose logs flower 报错：Error: No such command 'flower'.

• 根因：

  • flower 服务命令使用 celery ... flower，但 api 镜像依赖中未安装 flower 包。
  • 同时 docker compose 在解析阶段对 minio-init.command 中的 $MINIO_* 进行了提前插值，导致每次执行出现变量未设置 warning。

• 本次改动（最小闭环）：

  • 文件：api/requirements.txt
    • 新增依赖：flower==2.0.1。
  • 文件：api/pyproject.toml
    • 新增依赖：flower>=2.0.0,<3.0.0，与 requirements 口径一致。
  • 文件：docker-compose.yml
    • minio-init 启动脚本中的变量引用改为 $$MINIO_*，避免 compose 提前展开：
      • "$MINIO_ENDPOINT" -> "$$MINIO_ENDPOINT"
      • "$MINIO_ACCESS_KEY" -> "$$MINIO_ACCESS_KEY"
      • "$MINIO_SECRET_KEY" -> "$$MINIO_SECRET_KEY"
      • "$MINIO_BUCKET" -> "$$MINIO_BUCKET"

• 验证：

  • 执行：docker compose up -d --build flower
  • docker compose ps flower：Up，不再重启。
  • docker compose logs flower：
    • 出现 Visit me at http://0.0.0.0:5555
    • 出现 Connected to redis://redis:6379/0
  • 执行：docker compose logs --since=10m ... | rg "ERROR|Traceback|Exception|No such command|CRITICAL|FATAL|UndefinedColumn|relation \"|failed|denied|permission"
    • 结果：近 10 分钟内无命中。

• 风险与影响：

  • 影响面：api 镜像新增 flower 依赖，镜像体积与构建时长略有增加。
  • 当前运行中的 api/celery-worker/celery-beat/scheduler/web 仍为既有镜像；本次仅重建并替换了 flower。

Work Log - 固定 workflow WEB 端口为 3000（2026-05-02）

• 背景：

  • 发布后 fquiz-web 宿主机端口出现 13000->3000，与 Nginx 固定代理 127.0.0.1:3000 不一致。
  • 根因是 workflow 的 ensure_web_port_available 在 3000 冲突时会自动回退到 13000+ 并写回 .env。

• 本次改动（最小闭环）：

  • 文件：.github/workflows/main.yml
  • 调整 ensure_web_port_available：
    • 每次部署前强制写入 WEB_PORT=3000（存在则覆盖，不存在则追加）。
    • 移除自动回退到 13000+ 逻辑。
    • 若 3000 被其它容器占用，直接输出错误并终止部署。

• 预期效果：

  • workflow 部署后，fquiz-web 宿主机端口稳定为 3000，避免与 Nginx 前端代理端口漂移。

• 风险与影响：

  • 若服务器上已有其他容器占用 3000，本次部署会失败（可预期失败），需先释放端口或手动调整冲突容器。