tennis-training-hub/docs/deploy.md

Deployment Guide

Topology

• 宿主机 nginx：负责 te.hao.work 的 TLS、反向代理与大文件上传入口
• db 容器：MySQL 8，数据持久化到 db-data
• migrate 容器：一次性执行 Drizzle 迁移，成功后退出
• app 容器：Node 应用，端口 3000
• app-worker 容器：Node 后台任务 worker，共享应用卷与数据库
• 宿主机公开调试端口：8302 -> app:3000
• media 容器：Go 媒体服务，端口 8081
• media-worker 容器：Go 媒体归档 worker，共享媒体卷
• app-data 卷：上传视频等本地文件存储
• db-data 卷：MySQL 数据目录
• media-data 卷：录制片段、会话状态、归档成片

Required files

• .env
• docker-compose.yml
• deploy/nginx.te.hao.work.conf

Startup

cp .env.example .env
docker compose up -d --build

建议在 .env 中至少设置：

• JWT_SECRET
• MYSQL_PASSWORD
• MYSQL_ROOT_PASSWORD
• LLM_API_KEY
• APP_PUBLIC_BASE_URL
• LLM_VISION_MODEL

如需启用独立视觉模型端点，再补：

• LLM_VISION_API_URL
• LLM_VISION_API_KEY

nginx

将 deploy/nginx.te.hao.work.conf 放到宿主机 nginx 站点目录，确认：

• ssl_certificate
• ssl_certificate_key
• proxy_pass http://127.0.0.1:3002 对应前端、业务 API 和 /uploads/*
• proxy_pass http://127.0.0.1:8081 对应媒体服务

启用后重载 nginx：

nginx -t
systemctl reload nginx

Health checks

• curl http://127.0.0.1:3002/api/trpc/auth.me
• curl http://te.hao.work:8302/
• curl http://127.0.0.1:8081/media/health
• docker compose exec app-worker node dist/worker.js --help 不适用；应通过 docker compose ps app-worker 确认 worker 常驻

External access links

• 主站 HTTPS：https://te.hao.work/
• 主站公网 4 位端口直连：http://te.hao.work:8302/

Persistent data

媒体数据默认位于 Docker volume media-data 下，目录结构：

• sessions/<session_id>/session.json
• sessions/<session_id>/segments/*.webm
• public/sessions/<session_id>/recording.webm
• public/sessions/<session_id>/recording.mp4

应用本地上传文件默认位于 Docker volume app-data 下的 /data/app/storage。

Rollback

1. 保留 .env 和 media-data
2. 回退 Git 版本
3. 重新执行 docker compose up -d --build

如果只需停止录制链路，可单独关闭 media 与 media-worker，主站业务仍可继续运行；如需暂停训练计划/动作纠正等后台任务，再额外停止 app-worker。