wangchuanli
10db94c162
## 现象
容器跑着跑着页面全部 500，应用日志：
sqlite3.OperationalError: unable to open database file
(db.py:33, conn.execute("PRAGMA journal_mode=WAL"))
## 根因（已最小复现）
数据原本用绑定挂载（./data:/app/data）。Windows + Docker Desktop 的绑定挂载走 9p
（mount 里是 type 9p, aname=drvfs;path=C:\）。9p 本身支持 WAL（新建库能开 WAL），
但**宿主的 Windows 进程打开过这个 WAL 库之后**，容器侧缓存的 -shm 映射就失效，
下一次连接无法重建共享内存文件 → 打不开数据库，且**不会自愈**。
复现：
docker compose -f docker-compose.yml -f docker-compose.hostdir.yml up -d
docker compose exec portal python -c "..." # OK, 1665 条
python manage.py stats # 宿主侧纯读一次
docker compose exec portal python -c "..." # ERR unable to open database file
# 只有 docker compose restart portal 才恢复
## 处理
- docker-compose.yml 改用命名卷 wb_data / wb_logs（容器独占 /app/data）
- 新增 docker-compose.hostdir.yml 叠加层：需要宿主目录时用
docker compose -f docker-compose.yml -f docker-compose.hostdir.yml up -d
（注明**只建议 Linux**；Linux 的 bind mount 与容器同一文件系统，无此问题）
- 数据迁移：docker run --rm -v workbuddy-portal_wb_data:/to -v "$PWD/data":/from:ro \
alpine:3.20 sh -c 'cp -a /from/. /to/'
- 文档同步：DEPLOYMENT 2.4/5.4/第六节全部改为命名卷 + 备份恢复用 docker run；
新增第九节「Windows 绑定挂载的坑」（含复现步骤）；FAQ、USER-GUIDE、README、CHANGELOG 同步
## 验证
- 宿主跑 manage.py stats 与 smoke.py 之后，容器侧仍能正常读写（此前会立刻失效）
- 容器实例 check_live 56/56；离线 smoke 99/99；hostdir 叠加层 config 校验通过
22 行
1.2 KiB
YAML
22 行
1.2 KiB
YAML
# =============================================================================
|
|
# 可选叠加层：把数据 / 日志放到宿主机目录，而不是 Docker 命名卷。
|
|
#
|
|
# docker compose -f docker-compose.yml -f docker-compose.hostdir.yml up -d
|
|
#
|
|
# 好处：`./data/usage.sqlite` 直接可见，备份就是拷目录，宿主机的 manage.py 也能直接读。
|
|
#
|
|
# ⚠️ 只建议在 **Linux 宿主机** 上用（bind mount 与容器是同一个文件系统，
|
|
# SQLite 的 WAL / 文件锁语义正常）。
|
|
#
|
|
# ⚠️ **Windows + Docker Desktop 上不要用**：那里的绑定挂载走 9p（`path=C:\`），
|
|
# 宿主的 Windows 进程一旦访问过这个 WAL 库——哪怕只是 `manage.py status` 这种纯读——
|
|
# 容器侧下一次打开就会 `sqlite3.OperationalError: unable to open database file`，
|
|
# 而且**不会自愈**，必须 `docker compose restart portal`。
|
|
# 复现步骤与原理见 docs/DEPLOYMENT.md「Windows 绑定挂载的坑」。
|
|
# =============================================================================
|
|
services:
|
|
portal:
|
|
volumes:
|
|
- ${WB_HOST_DATA_DIR:-./data}:/app/data
|
|
- ${WB_HOST_LOG_DIR:-./logs}:/app/logs
|