fix(deploy): stabilize db image source and record api recovery

memory/2026-04-12.md

@@ -44,3 +44,66 @@
 - 触发问题：部署阶段 `docker compose` 报错 `yaml: line 2: mapping values are not allowed in this context`，并伴随 `DRONE_SSH_PREV_COMMAND_EXIT_CODE` 变量告警。
 - 原因：`appleboy/ssh-action` 在 `script_stop: true` 下会插入额外控制逻辑，和脚本中的 heredoc 组合后可能污染生成文件。
 - 处理：移除 workflow 中 `appleboy/ssh-action` 的 `script_stop: true`，保留脚本内 `set -euo pipefail` 作为失败中断机制。
+
+## 追加修正（API 构建超时 + 解析冲突）
+
+- 触发问题：
+  - `pip` 拉取 `files.pythonhosted.org` 频繁 `ReadTimeoutError`。
+  - 在高延迟场景下，解析 `pydantic` 版本链时出现 `ResolutionImpossible`。
+- 处理：
+  - `api/requirements.txt` 新增显式锁定：
+    - `pydantic==2.12.5`
+    - `pydantic-core==2.41.5`
+  - 将 `psycopg[binary]==3.3.3` 改为显式双包：
+    - `psycopg==3.3.3`
+    - `psycopg-binary==3.3.3`
+- 验证：
+  - `docker compose build api --no-cache` 成功。
+  - 日志显示 `pydantic-core-2.41.5` 与 `psycopg-binary-3.3.3` 均成功下载并安装，最终 `fquiz-api  Built`。
+
+## 追加开发（文件管理一期主链）
+
+- 目标：
+  - 在现有 FastAPI + SQLAlchemy + RBAC + Next.js App Router 结构上落地文件管理一期最小闭环。
+  - 支持 VFS / S3 driver 抽象，先打通后台 `/admin/files` 骨架与核心目录操作。
+- 后端改动：
+  - 新增模型：`file_storage_backends`、`file_storage_mounts`、`file_index_entries`（`api/app/models/file_storage.py`）。
+  - `init_db` 增加 `file_storage` 模型加载，保证 `create_all` 生效。
+  - 新增存储驱动层：`VfsStorageDriver`、`S3StorageDriver` 与统一工厂（`api/app/services/storage_driver.py`）。
+  - 新增文件服务：目录列表（带索引同步）、创建目录、删除路径（`api/app/services/file_service.py`）。
+  - 新增 API：`/api/v1/admin/files`、`/directories`、`/delete`（`api/app/api/v1/admin_files.py`）。
+  - 种子数据增加 `file.read`/`file.manage` 权限、`admin.files` 菜单、默认 VFS backend+mount 与 S3 backend 占位配置。
+- 前端改动：
+  - 新增后台页面：`web/src/app/admin/files/page.tsx`。
+  - 提供挂载点切换、面包屑目录浏览、刷新、新建目录、删除。
+  - 增补类型定义 `FileListResponse` 等，并在后台首页新增文件管理入口卡片。
+- 依赖与配置：
+  - `api/requirements.txt` 增加 `boto3==1.40.59`（S3 driver 依赖）。
+  - `.env.example` 增加 `FILE_VFS_ROOT`（默认 `./data/vfs`）。
+- 最小验证：
+  - `python3 -m compileall` 覆盖新增/改动后端文件通过。
+  - `npx eslint`（目标前端文件）通过。
+  - `npx tsc --noEmit`（web）通过。
+- 风险与缺口：
+  - 当前未提供存储后端/挂载点的可视化配置管理，S3 仍需手工写入 backend 配置并启用。
+  - 仅实现目录浏览+建目录+删除，未包含上传、下载、移动、重命名、分享、回收站等完整网盘能力。
+
+## 追加修复（API 容器 unhealthy + Docker Hub 超时）
+
+- 触发问题：
+  - `docker compose up` 阶段 `fquiz-api` 持续 unhealthy（容器反复重启）。
+  - 部署日志中 `db` 拉取 `registry-1.docker.io` 超时（`Client.Timeout exceeded while awaiting headers`）。
+- 根因：
+  - `api/app/services/admin_service.py` 在模块导入期构建 `selectinload(...)` 常量，提前触发 SQLAlchemy mapper 配置；当时 `User.audit_logs -> "AuditLog"` 对应模型尚未注册，导致启动即崩溃。
+  - 生产部署 compose 固定 `postgres:16-alpine`，对 Docker Hub 可达性强依赖。
+- 处理：
+  - `api/app/models/__init__.py` 增加模型模块统一导入，保证关系类可解析。
+  - `api/app/services/admin_service.py` 将 `selectinload(...)` 由模块级常量改为惰性构建，避免导入阶段触发 mapper 配置。
+  - `.github/workflows/main.yml` 部署生成的 `docker-compose.prod.yml` 中 DB 镜像改为可配置：
+    - `image: ${POSTGRES_IMAGE:-docker.m.daocloud.io/library/postgres:16-alpine}`
+    - `.env` 模板新增 `POSTGRES_IMAGE` 默认值。
+- 验证：
+  - 使用镜像源参数重建 API 成功：
+    - `docker compose build api --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple --build-arg PIP_DEFAULT_TIMEOUT=600 --build-arg PIP_RETRIES=30`
+  - `docker compose up -d api` 后状态为 `Up ... (healthy)`。
+  - `curl http://127.0.0.1:8000/health` 返回 `{"status":"ok","service":"fquiz-api","version":"0.1.0"}`。