## 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`，本次部署会失败（可预期失败），需先释放端口或手动调整冲突容器。 ## Work Log - 移除 scheduler 服务并统一任务调度为 API 直连 Celery（2026-05-02） - 背景： - 用户明确要求“去掉 scheduler”。 - 当前仓库默认调度本就为 `celery_direct`，`scheduler` 仅作为可选分支与独立容器存在。 - 本次改动（最小闭环）： - 后端任务派发收敛为直连 Celery： - `api/app/services/elevation_service.py` - 删除 `dispatch_mode` 分支与 `_enqueue_via_scheduler_api` 转发实现。 - 保留单一路径：`apply_elevation_for_line_job.delay(job_id)`。 - `api/app/api/v1/elevation.py` - 删除 `dispatchMode` 查询参数透传。 - 后端路由与配置清理： - `api/app/api/router.py` - 移除 `scheduler` 路由注册。 - `api/app/core/config.py` - 删除 `scheduler_api_token` / `scheduler_default_queue` / `scheduler_api_base_url` 及其 `resolved_*` 属性。 - 保留 `scheduler_expire_interval_seconds` 作为 Celery Beat 定时任务间隔配置。 - 删除 scheduler 相关源文件： - `api/app/api/v1/scheduler.py` - `api/app/services/scheduler_service.py` - `api/app/schemas/scheduler.py` - `api/app/scheduler_main.py` - 运行与部署配置同步： - `docker-compose.yml` - 删除 `scheduler` 服务。 - 删除 `api` / `celery-worker` / `celery-beat` 的 `SCHEDULER_API_BASE_URL`、`SCHEDULER_API_TOKEN`、`SCHEDULER_DEFAULT_QUEUE`。 - `.env.example` - 删除 `SCHEDULER_API_BASE_URL`、`SCHEDULER_API_TOKEN`、`SCHEDULER_DEFAULT_QUEUE`、`SCHEDULER_PORT`。 - `.github/workflows/main.yml` - 删除生产 compose 模板中的 `scheduler` 服务块。 - 删除部署模板与默认 `.env` 中的 `SCHEDULER_API_*` / `SCHEDULER_PORT`。 - 删除故障诊断日志中的 `fquiz-scheduler`。 - 长期记忆更新： - `MEMORY.md` - 将“调度与监控口径”更新为“API 直连 Celery，不再保留 scheduler 服务”。 - 验证： - 语法检查通过： - `python3 -m py_compile api/app/api/router.py api/app/api/v1/elevation.py api/app/services/elevation_service.py api/app/core/config.py` - 关键残留检查： - `rg -n "scheduler_main|services/scheduler_service|api/v1/scheduler|SCHEDULER_API_BASE_URL|SCHEDULER_API_TOKEN|SCHEDULER_DEFAULT_QUEUE|scheduler_api|fquiz-scheduler|SCHEDULER_PORT|resolved_scheduler_" .` - 仅命中文档历史记录，不再命中运行代码与部署配置。 - 风险与影响： - 影响范围：任务调度入口、部署编排与环境模板。 - 行为变化：不再支持 `dispatchMode=scheduler_api` 与独立 scheduler HTTP 网关调用。 - 保持不变：默认任务链路（API 直连 Celery）与 Flower 监控链路。 ## Work Log - 切换部署入口到 deploy 目录并删除根 docker-compose.yml（2026-05-02） - 背景： - 用户要求将部署结构统一到 `deploy/dev-deploy` 与 `deploy/pro-deploy`，并删除根目录 `docker-compose.yml`。 - 本次改动： - 新增目录结构： - `deploy/dev-deploy/{compose.yml,.env,.env.dev}` - `deploy/pro-deploy/{compose.yml,.env,.env.prod}` - 本地开发入口切换： - `package.json` 的 `docker:up/down/logs` 改为显式使用 `deploy/dev-deploy/compose.yml` + `deploy/dev-deploy/.env`。 - `README.md` Docker 部署说明改为基于 `deploy/dev-deploy`。 - `AGENTS.md` 根脚本说明改为指向 `deploy/dev-deploy`。 - 部署流水线切换： - `.github/workflows/main.yml` 改为使用 `deploy/pro-deploy` 结构进行生产部署（不再依赖根 compose）。 - 长期记忆口径更新： - `MEMORY.md` 中 Docker 命令口径改为 `deploy/dev-deploy` 方案。 - 删除： - 根目录 `docker-compose.yml`。 - 验证： - 目录校验：`find deploy -maxdepth 3 -type f | sort` 命中 dev/pro 全套文件。 - 入口校验：`rg` 检查脚本/文档，已无根 compose 作为默认入口。 - 风险与影响： - 旧习惯直接执行 `docker compose up -d`（仓库根目录）将失效，必须改为显式 `-f deploy/.../compose.yml`。 - workflow 远端部署改为写入并使用 `deploy/pro-deploy`，对旧服务器目录结构有一次性迁移要求。 ## Work Log - 移除 deploy 中的 nginx 服务（2026-05-02） - 背景： - 用户确认原工程不需要 nginx 服务，仅需保留 deploy 双目录与 compose/env 结构。 - 本次改动： - 删除 `deploy/dev-deploy/compose.yml` 与 `deploy/pro-deploy/compose.yml` 中的 `nginx` 服务定义。 - 删除 `deploy/dev-deploy/.env` 与 `deploy/pro-deploy/.env` 中 `NGINX_*` 变量。 - 删除 `deploy/dev-deploy/nginx/` 与 `deploy/pro-deploy/nginx/` 目录。 - 更新 `.github/workflows/main.yml`，移除 nginx 相关生成、变量与日志采集逻辑。 - 验证： - `docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml config` -> 通过。 - `docker compose --env-file deploy/pro-deploy/.env -f deploy/pro-deploy/compose.yml config` -> 通过。 - 风险与影响： - 部署后不再提供内置反向代理与 HTTPS 终止能力，如需网关需由外部 LB/Nginx/Ingress 承接。 ## Work Log - deploy 目录统一托管组件配置与数据挂载（2026-05-02） - 背景： - 用户目标是将各组件配置与数据文件集中挂载到 `deploy` 目录，便于统一管理；`nginx` 仅为示例并非必需。 - 本次改动： - `deploy/dev-deploy/compose.yml` 与 `deploy/pro-deploy/compose.yml` 改为目录挂载： - DB：`./data/postgres -> /var/lib/postgresql/data` - Redis：`./data/redis -> /data` - MinIO：`./data/minio -> /data` - API/Worker/Beat：`./data/app -> /app/data` - Celery Beat 调度文件持久化： - `--schedule=/app/data/celery/beat-schedule` - 删除命名卷定义，改为显式 bind mount。 - 新增目录骨架（含 `.gitkeep`）： - `deploy/dev-deploy/data/{postgres,redis,minio,app/celery}` - `deploy/pro-deploy/data/{postgres,redis,minio,app/celery}` - 验证： - `docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml config` -> 通过。 - `docker compose --env-file deploy/pro-deploy/.env -f deploy/pro-deploy/compose.yml config` -> 通过。 - 风险与影响： - 宿主机目录权限需允许容器读写（尤其 PostgreSQL/Redis/MinIO）。 - 生产环境若采用只读部署目录，需单独放开 `deploy/*/data/**` 写权限。 ## Work Log - dev-deploy 环境注入文件更名（2026-05-02） - 背景： - `dev-deploy` 使用 `.env.prod` 命名语义不清晰。 - 本次改动： - 将 `deploy/dev-deploy/.env.prod` 重命名为 `deploy/dev-deploy/.env.dev`。 - 将 `deploy/dev-deploy/compose.yml` 中 `env_file` 引用同步改为 `.env.dev`。 - 将 `README.md` 中相关命令与说明同步改为 `.env.dev`。 - 验证： - `docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml config` -> 通过。 - 风险与影响： - 本地若仍保留旧文件名 `.env.prod`，将不再被 dev compose 自动读取。 ## Work Log - 系统日志页面样式优化（2026-05-02） - 背景： - Issue [FL-170] 要求“参考菜单管理页面，调整系统日志页面样式和布局”。 - 本次改动（最小闭环）： - 文件：`web/src/app/admin/syslog/page.tsx` - 对齐 `menus` 页面风格，保持日志查询与筛选逻辑不变，仅调整 UI 布局： - 页面容器从 `Space` 改为 `div.space-y-6`，与后台管理页一致。 - 加载态改为居中 `Spin`（`min-h-[240px]`）。 - 未登录/无权限态改为与菜单页一致的 `main + Link` 布局与按钮样式。 - 筛选区改为 `Form inline`（动作、用户ID、查询/重置筛选）。 - 错误提示统一为 `Alert message + description`。 - 列表分页补充 `showTotal`，信息文案统一。 - 验证： - 差异检查：`git diff -- web/src/app/admin/syslog/page.tsx`。 - 尝试运行类型检查（未安装依赖，不做编译）： - `npm --workspace web exec tsc --noEmit --pretty false` - 当前环境报错 `EROFS`（npm 缓存目录只读），未执行到项目级类型检查。 - 风险与影响： - 影响范围仅 `syslog` 页面前端展示层。 - 接口请求、权限判断、筛选参数、分页逻辑保持不变。 ## Work Log - 用户管理页面布局样式对齐菜单管理（2026-05-02） - 背景： - Issue `FL-167` 要求“参考菜单管理页面，调整用户管理页面样式和布局”。 - `web/src/app/admin/users/page.tsx` 原为“用户检索卡 + 用户列表卡”双卡结构，和菜单管理页不一致。 - 本次改动（最小闭环）： - 文件：`web/src/app/admin/users/page.tsx` - 将用户管理主内容收敛为单卡布局（标题“用户列表”）： - 将筛选区合并进列表卡顶部，使用 `Form layout="inline"`。 - 筛选项统一为“关键词 + 状态 + 搜索 + 重置筛选”。 - 统一反馈样式： - 错误提示改为 closable `Alert`，并使用 `pre` 保留换行。 - 成功提示改为 closable `Alert`。 - 空状态文案改为“未找到符合筛选条件的用户。”。 - 统一加载与权限态样式： - 加载态调整为 `Spin tip="用户数据加载中..."` + `min-h-[240px]`。 - 未登录/无权限态改为 `p + Link` 样式，和菜单管理页一致。 - 分页与间距细节对齐： - 增加 `pageSizeOptions: [10, 20, 50, 100]`。 - 表格增加 `className="mt-4"`，统一筛选区与表格间距。 - 风险与影响： - 影响面仅 `web/src/app/admin/users/page.tsx` 前端展示层，不涉及后端接口、权限和数据结构。 ## Work Log - 参数管理页面样式与布局对齐菜单管理（2026-05-02） - 背景： - 需求 `FL-169` 要求参考菜单管理页面，优化参数管理页面的样式和布局一致性。 - 本次改动： - 修改 `web/src/app/admin/system-params/page.tsx`： - 页面主结构改为与菜单管理页一致的卡片容器 + `Form inline` 筛选区 + 表格区布局。 - 筛选区增加“重置筛选”按钮，关键词与状态筛选排布与菜单管理页一致。 - 表格增加分页、空态文案与动态纵向滚动高度（随视口和容器变化自适应）。 - 操作列删除交互由 `Modal.confirm` 调整为 `Popconfirm`，与菜单管理页操作风格对齐。 - 登录态与无权限态改为与菜单管理页一致的居中文案 + 返回首页样式。 - 保持原有参数 CRUD 逻辑与接口不变，仅调整页面展示和交互布局。 - 验证： - 按任务要求未执行编译/安装类检查；通过代码 diff 人工核对改动范围仅在参数管理页。 - 风险与影响： - 影响范围仅前端参数管理页 UI 展示，不涉及后端接口或数据结构变更。 ## Work Log - 角色管理页面对齐菜单管理布局（2026-05-02） - 背景： - Issue `FL-168` 要求“参考菜单管理页面，调整角色管理页面样式和布局”。 - 本次改动（最小闭环）： - 文件：`web/src/app/admin/roles/page.tsx` - 对齐菜单管理页布局风格： - 页面容器改为 `space-y-6`，错误提示改为可换行 `Alert + pre`。 - 登录态缺失/无权限态改为与菜单页一致的居中文案 + 返回首页按钮样式。 - 筛选区改为 `Form inline`（关键词 + 重置筛选）。 - 表格区域新增视口自适应纵向滚动高度计算（`ResizeObserver + resize`），并开启 `loading` 态。 - 新建/编辑弹窗表单改为 `Row/Col` 栅格布局，字段排布与菜单页一致风格。 - 保持业务逻辑不变： - 角色加载、创建、编辑、删除接口与字段未改动。 - 角色菜单绑定能力保持原样。 - 验证： - 本次按要求未执行编译/构建检查；已人工核对变更仅落在目标文件。 - 风险与影响： - 影响范围仅前端角色管理页面展示层；接口契约与数据结构无变更。 ## Work Log - 修复 Worker 监控 Flower 401（2026-05-02） - 背景： - Issue `FL-171` 报告 “worker 监控页面 401（flower error 401: Unauthorized）”。 - 根因： - `deploy/dev-deploy/.env.dev` 中 `FLOWER_API_BASE_URL` 误配为 `http://flower:5556`，与 `flower` 容器实际监听端口 `5555` 不一致。 - `deploy/*/compose.yml` 的 `flower` 服务环境变量 `FLOWER_BASIC_AUTH` 未设置默认值，若运行时未注入该变量，容器内可能读取为空，导致 API 侧按旧凭据访问时出现 401。 - 本次改动（最小闭环）： - 文件：`deploy/dev-deploy/.env.dev` - `FLOWER_API_BASE_URL` 从 `http://flower:5556` 修正为 `http://flower:5555`。 - 文件：`deploy/dev-deploy/compose.yml` - `flower.environment.FLOWER_BASIC_AUTH` 调整为 `${FLOWER_BASIC_AUTH:-admin:admin}`，与命令参数默认值一致。 - 文件：`deploy/pro-deploy/compose.yml` - `flower.environment.FLOWER_BASIC_AUTH` 调整为 `${FLOWER_BASIC_AUTH:-admin:change_me}`，避免环境变量缺失时鉴权源不一致。 - 验证： - 配置一致性检查： - `FLOWER_API_BASE_URL`（dev/pro/env.example）全部指向容器内 `http://flower:5555`。 - `flower` 服务命令参数与容器环境变量 `FLOWER_BASIC_AUTH` 已对齐默认回退策略。 - 风险与影响： - 影响面仅部署配置与环境模板，不涉及业务代码逻辑。 - 若生产实际使用了外部注入的 `FLOWER_BASIC_AUTH`，该值仍会覆盖默认值，不改变既有安全策略。 ## Work Log - 文件管理上传进度可视化（2026-05-02） - 背景： - Issue `FL-172` 要求“文件管理页面上传时可见上传进度”。 - 现状为 `fetch` 上传文件，浏览器原生 `fetch` 无可靠上传进度回调，用户无法看到实时进度。 - 本次改动（最小闭环）： - 文件：`web/src/app/admin/files/page.tsx` - 上传请求由 `fetchWithAuth` 改为 `XMLHttpRequest`（仅上传接口），接入 `xhr.upload.onprogress` 实时计算百分比。 - 新增上传状态：`uploadProgress`、`uploadFileName`。 - 上传按钮下方新增进度展示区：文件名 + 百分比 + `Progress` 进度条。 - 新增 XHR 错误解析函数，优先读取后端 `detail` 字段，失败时回退 `HTTP `。 - 401 场景下自动调用 `refreshAccessToken` 后重试一次上传，保持与现有鉴权刷新逻辑一致。 - 文件：`web/src/components/auth-provider.tsx` - 新增 `getAccessToken()`，用于读取最新 token（避免异步刷新后闭包持有旧 token）。 - 验证： - 按任务要求未执行编译/安装/构建检查； - 通过 `git diff` 人工核对： - 改动范围仅限上述两个前端文件； - 文件管理页已接入上传百分比显示与进度条 UI。 - 风险与影响： - 影响范围仅文件管理上传链路与认证上下文类型定义，不涉及后端接口契约变更。 - 上传改为 XHR 后仍保留 `withCredentials + Bearer token`，与现有认证模式兼容。 ## 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`，本次部署会失败（可预期失败），需先释放端口或手动调整冲突容器。 ## Work Log - 移除 scheduler 服务并统一任务调度为 API 直连 Celery（2026-05-02） - 背景： - 用户明确要求“去掉 scheduler”。 - 当前仓库默认调度本就为 `celery_direct`，`scheduler` 仅作为可选分支与独立容器存在。 - 本次改动（最小闭环）： - 后端任务派发收敛为直连 Celery： - `api/app/services/elevation_service.py` - 删除 `dispatch_mode` 分支与 `_enqueue_via_scheduler_api` 转发实现。 - 保留单一路径：`apply_elevation_for_line_job.delay(job_id)`。 - `api/app/api/v1/elevation.py` - 删除 `dispatchMode` 查询参数透传。 - 后端路由与配置清理： - `api/app/api/router.py` - 移除 `scheduler` 路由注册。 - `api/app/core/config.py` - 删除 `scheduler_api_token` / `scheduler_default_queue` / `scheduler_api_base_url` 及其 `resolved_*` 属性。 - 保留 `scheduler_expire_interval_seconds` 作为 Celery Beat 定时任务间隔配置。 - 删除 scheduler 相关源文件： - `api/app/api/v1/scheduler.py` - `api/app/services/scheduler_service.py` - `api/app/schemas/scheduler.py` - `api/app/scheduler_main.py` - 运行与部署配置同步： - `docker-compose.yml` - 删除 `scheduler` 服务。 - 删除 `api` / `celery-worker` / `celery-beat` 的 `SCHEDULER_API_BASE_URL`、`SCHEDULER_API_TOKEN`、`SCHEDULER_DEFAULT_QUEUE`。 - `.env.example` - 删除 `SCHEDULER_API_BASE_URL`、`SCHEDULER_API_TOKEN`、`SCHEDULER_DEFAULT_QUEUE`、`SCHEDULER_PORT`。 - `.github/workflows/main.yml` - 删除生产 compose 模板中的 `scheduler` 服务块。 - 删除部署模板与默认 `.env` 中的 `SCHEDULER_API_*` / `SCHEDULER_PORT`。 - 删除故障诊断日志中的 `fquiz-scheduler`。 - 长期记忆更新： - `MEMORY.md` - 将“调度与监控口径”更新为“API 直连 Celery，不再保留 scheduler 服务”。 - 验证： - 语法检查通过： - `python3 -m py_compile api/app/api/router.py api/app/api/v1/elevation.py api/app/services/elevation_service.py api/app/core/config.py` - 关键残留检查： - `rg -n "scheduler_main|services/scheduler_service|api/v1/scheduler|SCHEDULER_API_BASE_URL|SCHEDULER_API_TOKEN|SCHEDULER_DEFAULT_QUEUE|scheduler_api|fquiz-scheduler|SCHEDULER_PORT|resolved_scheduler_" .` - 仅命中文档历史记录，不再命中运行代码与部署配置。 - 风险与影响： - 影响范围：任务调度入口、部署编排与环境模板。 - 行为变化：不再支持 `dispatchMode=scheduler_api` 与独立 scheduler HTTP 网关调用。 - 保持不变：默认任务链路（API 直连 Celery）与 Flower 监控链路。 ## Work Log - 切换部署入口到 deploy 目录并删除根 docker-compose.yml（2026-05-02） - 背景： - 用户要求将部署结构统一到 `deploy/dev-deploy` 与 `deploy/pro-deploy`，并删除根目录 `docker-compose.yml`。 - 本次改动： - 新增目录结构： - `deploy/dev-deploy/{compose.yml,.env,.env.dev}` - `deploy/pro-deploy/{compose.yml,.env,.env.prod}` - 本地开发入口切换： - `package.json` 的 `docker:up/down/logs` 改为显式使用 `deploy/dev-deploy/compose.yml` + `deploy/dev-deploy/.env`。 - `README.md` Docker 部署说明改为基于 `deploy/dev-deploy`。 - `AGENTS.md` 根脚本说明改为指向 `deploy/dev-deploy`。 - 部署流水线切换： - `.github/workflows/main.yml` 改为使用 `deploy/pro-deploy` 结构进行生产部署（不再依赖根 compose）。 - 长期记忆口径更新： - `MEMORY.md` 中 Docker 命令口径改为 `deploy/dev-deploy` 方案。 - 删除： - 根目录 `docker-compose.yml`。 - 验证： - 目录校验：`find deploy -maxdepth 3 -type f | sort` 命中 dev/pro 全套文件。 - 入口校验：`rg` 检查脚本/文档，已无根 compose 作为默认入口。 - 风险与影响： - 旧习惯直接执行 `docker compose up -d`（仓库根目录）将失效，必须改为显式 `-f deploy/.../compose.yml`。 - workflow 远端部署改为写入并使用 `deploy/pro-deploy`，对旧服务器目录结构有一次性迁移要求。 ## Work Log - 移除 deploy 中的 nginx 服务（2026-05-02） - 背景： - 用户确认原工程不需要 nginx 服务，仅需保留 deploy 双目录与 compose/env 结构。 - 本次改动： - 删除 `deploy/dev-deploy/compose.yml` 与 `deploy/pro-deploy/compose.yml` 中的 `nginx` 服务定义。 - 删除 `deploy/dev-deploy/.env` 与 `deploy/pro-deploy/.env` 中 `NGINX_*` 变量。 - 删除 `deploy/dev-deploy/nginx/` 与 `deploy/pro-deploy/nginx/` 目录。 - 更新 `.github/workflows/main.yml`，移除 nginx 相关生成、变量与日志采集逻辑。 - 验证： - `docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml config` -> 通过。 - `docker compose --env-file deploy/pro-deploy/.env -f deploy/pro-deploy/compose.yml config` -> 通过。 - 风险与影响： - 部署后不再提供内置反向代理与 HTTPS 终止能力，如需网关需由外部 LB/Nginx/Ingress 承接。 ## Work Log - deploy 目录统一托管组件配置与数据挂载（2026-05-02） - 背景： - 用户目标是将各组件配置与数据文件集中挂载到 `deploy` 目录，便于统一管理；`nginx` 仅为示例并非必需。 - 本次改动： - `deploy/dev-deploy/compose.yml` 与 `deploy/pro-deploy/compose.yml` 改为目录挂载： - DB：`./data/postgres -> /var/lib/postgresql/data` - Redis：`./data/redis -> /data` - MinIO：`./data/minio -> /data` - API/Worker/Beat：`./data/app -> /app/data` - Celery Beat 调度文件持久化： - `--schedule=/app/data/celery/beat-schedule` - 删除命名卷定义，改为显式 bind mount。 - 新增目录骨架（含 `.gitkeep`）： - `deploy/dev-deploy/data/{postgres,redis,minio,app/celery}` - `deploy/pro-deploy/data/{postgres,redis,minio,app/celery}` - 验证： - `docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml config` -> 通过。 - `docker compose --env-file deploy/pro-deploy/.env -f deploy/pro-deploy/compose.yml config` -> 通过。 - 风险与影响： - 宿主机目录权限需允许容器读写（尤其 PostgreSQL/Redis/MinIO）。 - 生产环境若采用只读部署目录，需单独放开 `deploy/*/data/**` 写权限。 ## Work Log - dev-deploy 环境注入文件更名（2026-05-02） - 背景： - `dev-deploy` 使用 `.env.prod` 命名语义不清晰。 - 本次改动： - 将 `deploy/dev-deploy/.env.prod` 重命名为 `deploy/dev-deploy/.env.dev`。 - 将 `deploy/dev-deploy/compose.yml` 中 `env_file` 引用同步改为 `.env.dev`。 - 将 `README.md` 中相关命令与说明同步改为 `.env.dev`。 - 验证： - `docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml config` -> 通过。 - 风险与影响： - 本地若仍保留旧文件名 `.env.prod`，将不再被 dev compose 自动读取。 ## Work Log - 直接更新 users 管理员账号（2026-05-02） - 背景： - 用户要求将 users 表中的管理员账号改为： - `user_id=admin` - `username=管理员` - 密码更新为 `tiandiyisuren`。 - 执行过程（仅数据库数据变更，无代码改动）： - 先检查 `public.users` 表结构与外键引用，确认 `user_roles.user_id -> users.user_id` 为外键，且约束不带 `ON UPDATE CASCADE`。 - 因此未采用直接 `UPDATE users.user_id`（会触发外键失败），改为单事务迁移： 1. 临时改写旧用户 email（规避唯一键冲突）。 2. 插入新用户行（`user_id=admin`，`username=管理员`，密码为 Argon2 哈希）。 3. 将 `user_roles.user_id` 从旧值迁移到 `admin`。 4. 删除旧用户行。 - 密码哈希通过运行中的 `fquiz-api` 容器使用 Argon2 生成，保持与后端鉴权逻辑一致。 - 验证： - `SELECT user_id,email,username,status FROM public.users;` -> 仅剩 1 条：`admin / admin@example.com / 管理员 / ENABLED`。 - `SELECT user_id, role_id FROM public.user_roles;` -> 角色绑定已迁移为 `admin`。 - `password_hash` 前缀校验：`$argon2id$...`。 - 风险与影响： - 影响面：`users` 与 `user_roles` 的标识数据。 - 登录标识变化：后端 JWT 的 `sub` 将从旧 user_id 变为 `admin`；历史会话令牌若仍在使用，可能需要重新登录。 - 本次未改动 `email`，仍为 `admin@example.com`。