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>

.env.example

@@ -1,12 +1,28 @@
+# =============================================================================
+# BiliNote 环境变量示例
+# Docker 部署：cp .env.example .env，按需修改，然后 docker-compose up --build -d
+#
+# 注意区分两类变量：
+#   1) VITE_* 是【构建时】变量，会被烘进前端 JS bundle。改完必须
+#      docker-compose build frontend && docker-compose up -d 才会生效，
+#      只 docker-compose restart 不行。
+#   2) 其他后端变量是【运行时】变量，改完 docker-compose up -d 即可。
+#
+# 提醒：LLM API key 不要写在这里！请部署完成后，从前端「模型供应商」页面录入，
+#       这些 key 会保存到 SQLite 数据库（./backend/bili_note.db）并随容器持久化。
+# =============================================================================
+
 # 通用端口配置
 BACKEND_PORT=8483 # 后端端口
 FRONTEND_PORT=3015
 BACKEND_HOST=0.0.0.0 # 默认为 0.0.0.0，表示监听所有 IP 地址 不建议动
-APP_PORT= 3015 # docker 部署时用
-# 前端访问后端用 (开发环境使用)
-VITE_API_BASE_URL=http://127.0.0.1:8000
+APP_PORT=3015 # docker 部署时对外暴露端口（浏览器访问的端口）
+
+# 前端访问后端用（开发环境直连；Docker 部署下走 nginx 代理，此值仅作回退）
+VITE_API_BASE_URL=http://127.0.0.1:8483
 VITE_SCREENSHOT_BASE_URL=http://127.0.0.1:8483/static/screenshots
 VITE_FRONTEND_PORT=3015
+
 # 生产环境配置
 ENV=production
 STATIC=/static
@@ -14,11 +30,16 @@ OUT_DIR=./static/screenshots
 NOTE_OUTPUT_DIR=note_results
 IMAGE_BASE_URL=/static/screenshots
 DATA_DIR=data
-# FFMPEG 配置
+
+# FFMPEG 配置（Docker 镜像已内置 ffmpeg，留空即可；自建/桌面端可填绝对路径）
 FFMPEG_BIN_PATH=
 
-# transcriber 相关配置
-TRANSCRIBER_TYPE=fast-whisper # fast-whisper/bcut/kuaishou/mlx-whisper(仅Apple平台)/groq
-WHISPER_MODEL_SIZE=medium
+# 转写器配置
+# TRANSCRIBER_TYPE 可选：fast-whisper / bcut / kuaishou / mlx-whisper(仅 Apple Silicon) / groq
+TRANSCRIBER_TYPE=fast-whisper
+# WHISPER_MODEL_SIZE 默认 tiny (~75MB)，首次启动快；想要更高识别质量可在前端
+# 「音频转写配置」页切到 base/small/medium/large。直接在这里改大尺寸会触发
+# 首次启动下载 ~1.5GB 文件，慢网络或 4GB 内存的容器容易 OOM。
+WHISPER_MODEL_SIZE=tiny
 
 GROQ_TRANSCRIBER_MODEL=whisper-large-v3-turbo # groq提供的faster-whisper 默认为 whisper-large-v3-turbo