chore(deploy): docker 镜像源/restart 策略 + .env 修正 + 文档

- 所有 Dockerfile 加 BASE_REGISTRY build-arg，国内拉不到 docker.io
  时可换 daocloud 等镜像源；compose 透传该 arg
- docker-compose: restart 从 on-failure:3 改 unless-stopped（避免短暂
  崩溃后永久打死）；gpu compose 补齐 healthcheck/restart/mem_limit
- Dockerfile.complete: supervisord 用 %(ENV_*)s 透传环境变量给 backend
  子进程（之前只白名单 2 个，docker run -e 配的变量后端看不到）
- .env.example: 修正 VITE_API_BASE_URL 端口（8000→8483）、
  WHISPER_MODEL_SIZE medium→tiny（首次启动不被大模型下载卡住）、
  补 Docker 部署说明注释
- README: 新增 Docker 部署常见问题 FAQ（镜像源/restart/数据持久化等）
- CLAUDE.md: 勘误（移除不存在的 messaging/i18n/worker_registry 描述，
  修正 events 路径），补 pytest/typecheck 命令

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Dockerfile.complete

@@ -1,5 +1,9 @@
+# BASE_REGISTRY 默认 docker.io；国内拉不到可换镜像源：
+#   docker build --build-arg BASE_REGISTRY=docker.m.daocloud.io -f Dockerfile.complete .
+ARG BASE_REGISTRY=docker.io
+
 # === 阶段1：构建 Backend ===
-FROM python:3.11-slim AS backend-builder
+FROM ${BASE_REGISTRY}/library/python:3.11-slim AS backend-builder
 
 ARG APT_MIRROR=mirrors.tuna.tsinghua.edu.cn
 ARG PIP_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
@@ -28,7 +32,8 @@ COPY ./backend /tmp/backend
 # === 阶段2：构建 Frontend ===
 # Node 18-alpine 跑不动 Tailwind v4 / Vite 6（前者要求 Node 20+，后者推荐 Node 20+），
 # 升到 node:20-alpine。alpine 走 musl，pnpm 会按 lockfile 拉 *-linux-x64-musl native binary。
-FROM node:20-alpine AS frontend-builder
+ARG BASE_REGISTRY=docker.io
+FROM ${BASE_REGISTRY}/library/node:20-alpine AS frontend-builder
 
 # pnpm 版本 pin 到 9 系列：
 # - lockfile (BillNote_frontend/pnpm-lock.yaml) 是 lockfileVersion '9.0'，由 pnpm 9 生成
@@ -50,7 +55,8 @@ ENV DOCKER_BUILD=1
 RUN pnpm run build
 
 # === 阶段3：完整应用镜像 ===
-FROM python:3.11-slim
+ARG BASE_REGISTRY=docker.io
+FROM ${BASE_REGISTRY}/library/python:3.11-slim
 
 ARG APT_MIRROR=mirrors.tuna.tsinghua.edu.cn
 
@@ -85,6 +91,10 @@ RUN rm -rf /etc/nginx/conf.d/default.conf
 COPY ./nginx/default.conf /etc/nginx/conf.d/default.conf
 
 # 创建 supervisor 配置
+# 关键点：supervisord 默认 *不* 把自己的环境变量传给子进程。
+# 在 [supervisord] 块用 environment= 设兜底默认值；在 [program:backend] 用
+# %(ENV_*)s 显式引用，等价于「把 host 通过 docker run -e 或 env_file 传进来的
+# 变量再透传给 python main.py」。漏掉这一步就是用户「改 .env 没反应」的根因。
 RUN mkdir -p /var/log/supervisor
 COPY <<EOF /etc/supervisor/conf.d/supervisord.conf
 [supervisord]
@@ -92,6 +102,7 @@ nodaemon=true
 user=root
 logfile=/var/log/supervisor/supervisord.log
 pidfile=/var/run/supervisord.pid
+environment=BACKEND_PORT="8483",BACKEND_HOST="0.0.0.0",TRANSCRIBER_TYPE="fast-whisper",WHISPER_MODEL_SIZE="tiny",FFMPEG_BIN_PATH="",HF_ENDPOINT="https://hf-mirror.com",STATIC="/static",OUT_DIR="./static/screenshots",DATA_DIR="data",NOTE_OUTPUT_DIR="note_results",IMAGE_BASE_URL="/static/screenshots",ENV="production",GROQ_TRANSCRIBER_MODEL="whisper-large-v3-turbo"
 
 [program:nginx]
 command=nginx -g "daemon off;"
@@ -107,7 +118,7 @@ stdout_logfile=/var/log/supervisor/backend.log
 stderr_logfile=/var/log/supervisor/backend.log
 autorestart=true
 priority=20
-environment=BACKEND_PORT="8483",BACKEND_HOST="0.0.0.0"
+environment=BACKEND_PORT="%(ENV_BACKEND_PORT)s",BACKEND_HOST="%(ENV_BACKEND_HOST)s",TRANSCRIBER_TYPE="%(ENV_TRANSCRIBER_TYPE)s",WHISPER_MODEL_SIZE="%(ENV_WHISPER_MODEL_SIZE)s",FFMPEG_BIN_PATH="%(ENV_FFMPEG_BIN_PATH)s",HF_ENDPOINT="%(ENV_HF_ENDPOINT)s",STATIC="%(ENV_STATIC)s",OUT_DIR="%(ENV_OUT_DIR)s",DATA_DIR="%(ENV_DATA_DIR)s",NOTE_OUTPUT_DIR="%(ENV_NOTE_OUTPUT_DIR)s",IMAGE_BASE_URL="%(ENV_IMAGE_BASE_URL)s",ENV="%(ENV_ENV)s",GROQ_TRANSCRIBER_MODEL="%(ENV_GROQ_TRANSCRIBER_MODEL)s"
 EOF
 
 # 修改 nginx 配置以使用本地 backend
@@ -115,5 +126,9 @@ RUN sed -i 's/proxy_pass http:\/\/backend:8483/proxy_pass http:\/\/127.0.0.1:848
     sed -i 's/proxy_pass http:\/\/frontend:80/proxy_pass http:\/\/127.0.0.1:8080/g' /etc/nginx/conf.d/default.conf
 
 # 启动 supervisor
+# 推荐启动方式（覆盖默认 env）：
+#   docker run -d --name bilinote --env-file .env -p 8080:80 bilinote-aio
+# 单个变量覆盖：
+#   docker run -d -e TRANSCRIBER_TYPE=groq -e WHISPER_MODEL_SIZE=base ...
 EXPOSE 80
 CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]