Self-host compose stack and production stability fixes

docs/deploy.md

@@ -3,9 +3,13 @@
 ## Topology
 
 - 宿主机 nginx：负责 `te.hao.work` 的 TLS、反向代理与大文件上传入口
+- `db` 容器：MySQL 8，数据持久化到 `db-data`
+- `migrate` 容器：一次性执行 Drizzle 迁移，成功后退出
 - `app` 容器：Node 应用，端口 `3000`
 - `media` 容器：Go 媒体服务，端口 `8081`
 - `worker` 容器：Go 媒体归档 worker，共享媒体卷
+- `app-data` 卷：上传视频等本地文件存储
+- `db-data` 卷：MySQL 数据目录
 - `media-data` 卷：录制片段、会话状态、归档成片
 
 ## Required files
@@ -21,13 +25,20 @@ cp .env.example .env
 docker compose up -d --build
 ```
 
+建议在 `.env` 中至少设置：
+
+- `JWT_SECRET`
+- `MYSQL_PASSWORD`
+- `MYSQL_ROOT_PASSWORD`
+- `LLM_API_KEY`
+
 ## nginx
 
 将 `deploy/nginx.te.hao.work.conf` 放到宿主机 nginx 站点目录，确认：
 
 - `ssl_certificate`
 - `ssl_certificate_key`
-- `proxy_pass http://127.0.0.1:3000` 对应前端与业务 API
+- `proxy_pass http://127.0.0.1:3002` 对应前端、业务 API 和 `/uploads/*`
 - `proxy_pass http://127.0.0.1:8081` 对应媒体服务
 
 启用后重载 nginx：
@@ -39,7 +50,7 @@ systemctl reload nginx
 
 ## Health checks
 
-- `curl http://127.0.0.1:3000/api/trpc/auth.me`
+- `curl http://127.0.0.1:3002/api/trpc/auth.me`
 - `curl http://127.0.0.1:8081/media/health`
 
 ## Persistent data
@@ -51,6 +62,8 @@ systemctl reload nginx
 - `public/sessions/<session_id>/recording.webm`
 - `public/sessions/<session_id>/recording.mp4`
 
+应用本地上传文件默认位于 Docker volume `app-data` 下的 `/data/app/storage`。
+
 ## Rollback
 
 1. 保留 `.env` 和 `media-data`

docs/developer-workflow.md

@@ -35,9 +35,20 @@ git commit -m "..."
 3. 再跑 `pnpm test`
 4. 若涉及媒体链路，再跑 `pnpm test:go`
 5. 最后跑 `pnpm test:e2e`
+6. 若当前分支包含部署改动，再执行 `docker compose config` 与基础 smoke check
 
 不要在一半状态下长时间保留“能编译但主流程不可用”的改动。
 
+## Deployment-safe checks
+
+涉及 compose、nginx、数据库或媒体服务调整时，提交前至少确认：
+
+- `docker compose config` 可通过
+- `docker compose ps` 中 `app`、`db`、`media`、`worker` 正常
+- 一次性迁移容器 `migrate` 成功退出
+- `curl -I https://te.hao.work/` 返回 `200`
+- `curl http://127.0.0.1:8081/media/health` 返回 `{"ok":true,...}`
+
 ## Media-related changes
 
 修改录制链路时至少检查：

docs/testing.md

@@ -75,6 +75,24 @@ pnpm test:llm -- "你好，做个自我介绍"
 - 适合验证 `LLM_API_KEY`、`LLM_MODEL` 和网关连通性
 - 不建议纳入 `pnpm verify`，因为它依赖外部网络和真实密钥
 
+## Production smoke checks
+
+部署到宿主机后，建议至少补以下联测：
+
+```bash
+docker compose ps
+curl -I https://te.hao.work/
+curl http://127.0.0.1:8081/media/health
+pnpm test:llm
+```
+
+推荐再增加一轮浏览器级检查：
+
+- 打开 `https://te.hao.work/`
+- 打开 `https://te.hao.work/login`
+- 打开 `https://te.hao.work/recorder`
+- 确认没有 `pageerror` 或首屏 `console.error`
+
 ## Local browser prerequisites
 
 首次运行 Playwright 前执行：

docs/verified-features.md

@@ -1,12 +1,23 @@
 # Verified Features
 
-本文档记录当前已经通过自动化验证或构建验证的项目。更新时间：2026-03-14 21:44 CST。
+本文档记录当前已经通过自动化验证或构建验证的项目。更新时间：2026-03-14 22:24 CST。
 
 ## 最新完整验证记录
 
 - 通过命令：`pnpm verify`
-- 验证时间：2026-03-14 21:44 CST
-- 结果摘要：`pnpm check` 通过，`pnpm test` 通过（69/69），`pnpm test:go` 通过，`pnpm build` 通过，`pnpm test:e2e` 通过（5/5）
+- 验证时间：2026-03-14 22:23 CST
+- 结果摘要：`pnpm check` 通过，`pnpm test` 通过（74/74），`pnpm test:go` 通过，`pnpm build` 通过，`pnpm test:e2e` 通过（5/5）
+
+## 生产部署联测
+
+| 项目 | 验证方式 | 状态 |
+|------|----------|------|
+| `https://te.hao.work/` HTTPS 访问 | `curl -I https://te.hao.work/` | 通过 |
+| 站点 TLS 证书 | Let’s Encrypt ECDSA 证书已签发并由宿主机 nginx 加载 | 通过 |
+| 生产首页、登录页、录制页浏览器打开 | Playwright 访问 `https://te.hao.work/`、`/login`、`/recorder` | 通过 |
+| 生产前端运行时异常检查 | Playwright `pageerror` / `console.error` 检查 | 通过 |
+| 媒体健康检查 | `curl http://127.0.0.1:8081/media/health` | 通过 |
+| compose 自包含服务 | `docker compose ps` 中 `app` / `db` / `media` / `worker` 正常运行，`migrate` 成功退出 | 通过 |
 
 ## 构建与编译通过
 
@@ -32,6 +43,7 @@
 | leaderboard | `pnpm test` | 通过 |
 | tutorial / reminder / notification 路由校验 | `pnpm test` | 通过 |
 | media 工具函数 | `pnpm test` | 通过 |
+| 登录 URL 回退逻辑 | `pnpm test` | 通过 |
 
 ## Go 媒体服务验证
 
@@ -53,6 +65,13 @@
 | 在线录制 | 启动摄像头、开始录制、手动标记、结束归档 | 通过 |
 | 录制结果入库 | 归档完成后视频库可见录制结果 | 通过 |
 
+## LLM 模块验证
+
+| 项目 | 验证方式 | 状态 |
+|------|----------|------|
+| `.env` 中的 `LLM_API_URL` / `LLM_API_KEY` / `LLM_MODEL` | `pnpm test:llm` | 通过 |
+| `https://one.hao.work/v1/chat/completions` 联通性 | `pnpm test:llm` 实际返回文本 | 通过 |
+
 ## 已知非阻断警告
 
 - 测试与开发日志中会出现 `OAUTH_SERVER_URL` 未配置提示；当前 mocked auth 和本地验证链路不依赖真实 OAuth 服务，因此不会导致失败