diff --git a/deploy/.env.example b/deploy/.env.example
index d24ae32..ebf972a 100644
--- a/deploy/.env.example
+++ b/deploy/.env.example
@@ -1,6 +1,10 @@
 # 测试环境变量示例。复制为 deploy/.env 后填写。
 # 正式环境口令不得提交进仓库。
 
+# 容器运行 uid/gid：必须与 data/ 目录属主一致（宿主机 `id <用户>` 查看）
+APP_UID=10001
+APP_GID=10001
+
 APP_HOST=0.0.0.0
 APP_PORT=4173
 APP_DB_PATH=/app/data/app.db
diff --git a/deploy/README.md b/deploy/README.md
index b6f0f98..b62e726 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -30,6 +30,8 @@
 git fetch && git checkout release/prod && git pull
 cd deploy
 cp .env.example .env   # 首次；按上面铁律填写
+# .env 必设 APP_UID/APP_GID = data/ 目录属主的 uid/gid（宿主机 `id <用户>`），
+# 否则 SQLite WAL 写库报 readonly
 TAG=$(git rev-parse --short HEAD) ./deploy.sh
 curl -fsS http://127.0.0.1:4173/ >/dev/null && echo healthy
 ```
diff --git a/deploy/compose.yaml b/deploy/compose.yaml
index 6b64423..78ca61c 100644
--- a/deploy/compose.yaml
+++ b/deploy/compose.yaml
@@ -11,6 +11,9 @@ services:
       dockerfile: deploy/Dockerfile
     env_file:
       - .env
+    # 绑定挂载 data/ 时，容器运行 uid 必须与数据目录属主一致（.env 里设
+    # APP_UID/APP_GID，正式与测试环境各自填写，默认镜像内 app=10001）
+    user: "${APP_UID:-10001}:${APP_GID:-10001}"
     ports:
       - "4173:4173"
     volumes: