119 行
3.2 KiB
Markdown
119 行
3.2 KiB
Markdown
# Tennis Training Hub
|
|
|
|
网球训练管理与分析应用，提供训练计划、姿势分析、实时摄像头分析、在线视频录制与视频库管理。当前版本新增独立 Go 媒体服务，用于处理在线录制、分段上传、实时推流信令和归档回放。
|
|
|
|
## Architecture
|
|
|
|
- `client/`: React 19 + TypeScript + Tailwind CSS 4 + shadcn/ui
|
|
- `server/`: Express + tRPC + Drizzle + MySQL/TiDB，负责业务 API、登录、训练数据与视频库元数据
|
|
- `media/`: Go 媒体服务，负责录制会话、分段上传、WebRTC 信令、关键片段标记与 FFmpeg 归档
|
|
- `docker-compose.yml`: 单机部署编排
|
|
- `deploy/nginx.te.hao.work.conf`: `te.hao.work` 的宿主机 nginx 入口配置
|
|
|
|
## Online Recording
|
|
|
|
在线录制模块采用双链路设计：
|
|
|
|
- 浏览器端 `MediaRecorder` 本地压缩并每 60 秒自动分段上传
|
|
- 浏览器端 `RTCPeerConnection` 同步建立 WebRTC 低延迟推流链路
|
|
- 客户端运动检测自动写入关键片段 marker，也支持手动标记
|
|
- 摄像头中断后自动重连，保留既有分段与会话
|
|
- 服务端 worker 将分段合并归档，并产出 WebM 回放；FFmpeg 可用时额外生成 MP4
|
|
|
|
## Quick Start
|
|
|
|
### Local development
|
|
|
|
```bash
|
|
pnpm install
|
|
cp .env.example .env
|
|
pnpm dev
|
|
```
|
|
|
|
本地开发时：
|
|
|
|
- Node 应用默认运行在 `http://localhost:3000`
|
|
- 若设置 `MEDIA_SERVICE_URL=http://127.0.0.1:8081`，Express 会把 `/media` 代理到 Go 服务
|
|
- Go 媒体服务可单独启动：
|
|
|
|
```bash
|
|
cd media
|
|
go mod tidy
|
|
go run .
|
|
```
|
|
|
|
### Checks
|
|
|
|
```bash
|
|
pnpm check
|
|
pnpm test
|
|
pnpm test:go
|
|
pnpm build
|
|
pnpm test:e2e
|
|
pnpm verify
|
|
|
|
cd media
|
|
go build ./...
|
|
```
|
|
|
|
首次运行浏览器测试前执行：
|
|
|
|
```bash
|
|
pnpm exec playwright install chromium
|
|
```
|
|
|
|
## Production Deployment
|
|
|
|
单机部署推荐：
|
|
|
|
1. 宿主机 nginx 处理 `80/443` 和 TLS
|
|
2. `docker compose up -d --build` 启动 `app + media + worker + db`
|
|
3. nginx 将 `/` 转发到宿主机 `127.0.0.1:3002 -> app:3000`，`/media/` 转发到 `127.0.0.1:8081 -> media:8081`
|
|
4. 如需绕过 nginx 直连调试，也可通过公网 4 位端口访问主站：`http://te.hao.work:8302/`
|
|
|
|
详细步骤见：
|
|
|
|
- `docs/deploy.md`
|
|
- `docs/media-architecture.md`
|
|
- `docs/frontend-recording.md`
|
|
|
|
## Documentation Index
|
|
|
|
- `docs/FEATURES.md`: 当前功能特性与能力边界
|
|
- `docs/testing.md`: 自动测试分层与运行方式
|
|
- `docs/verified-features.md`: 已验证通过的项目清单
|
|
- `docs/developer-workflow.md`: 阶段可中断的开发与本地提交流程
|
|
- `docs/deploy.md`: 部署指南
|
|
- `docs/media-architecture.md`: 媒体服务架构
|
|
- `docs/frontend-recording.md`: 前端录制与移动端适配说明
|
|
|
|
## Environment
|
|
|
|
关键环境变量见 `.env.example`，重点包括：
|
|
|
|
- `DATABASE_URL`
|
|
- `JWT_SECRET`
|
|
- `MYSQL_DATABASE`
|
|
- `MYSQL_USER`
|
|
- `MYSQL_PASSWORD`
|
|
- `MYSQL_ROOT_PASSWORD`
|
|
- `LLM_API_URL`
|
|
- `LLM_API_KEY`
|
|
- `LLM_MODEL`
|
|
- `LOCAL_STORAGE_DIR`
|
|
- `MEDIA_SERVICE_URL`
|
|
- `VITE_MEDIA_BASE_URL`
|
|
|
|
LLM 烟雾测试：
|
|
|
|
```bash
|
|
pnpm test:llm
|
|
pnpm test:llm -- "你好，做个自我介绍"
|
|
```
|
|
|
|
## Notes
|
|
|
|
- 浏览器兼容目标以 Chrome 为主
|
|
- 录制文件优先产出 WebM，MP4 为服务端可选归档产物
|
|
- 存储策略当前为本地卷优先，适合单机 Compose 部署
|