Files

bujinyuan 6e2e792db0 feat(phase2e-2): media-server Task 0/1/2 落地 + 代码审查修复

本次提交一次性落盘 Phase 2e-2 的 Task 0（PoC Spike）、Task 1（骨架 + Fastify 5 升级）
和 Task 2（9 个内部 REST API + code-reviewer 审查修复），覆盖 media-server 子项目
从零到可用的全部工作。

【Task 0 - PoC Spike】
- media-server/poc/：Node + mediasoup + fastify-websocket + 前端 mediasoup-client
- Playwright 双 tab 自动化验证 2 人会议：4 transports / 4 producers / 4 consumers / RSS 61MB
- media-server/docs/poc-notes.md 归档 7 项关键坑 + 启动步骤 + Task 1/2/9 复用映射
- 锁定技术栈：mediasoup + fastify + mediasoup-client，不改用 livekit-server

【Task 1 - 骨架 + Fastify 5 升级】
- 依赖版本：mediasoup@3.19.0 + fastify@5.8.5 + fastify-plugin@5.1.0
           + @fastify/sensible@6.0.4 + @fastify/websocket@11.2.0
           + pino@9.3.2 + zod@3.23.8
- src 五件套：app.ts / config.ts / utils/logger.ts / mediasoup/worker.ts
             / middlewares/internal-auth.ts
- /healthz + /readyz + /internal/info 三端点实测通过
- X-Internal-Token 鉴权用 timingSafeEqual 防侧信道
- mediasoup Worker died 指数退避自愈通过 kill -9 验证
- 多阶段 Dockerfile：非 root + curl HEALTHCHECK + 暴露 40000-40199 UDP/TCP
- Fastify 4 → 5 升级：loggerInstance: logger 消灭两个 pino 实例

【Task 2 - 9 个内部 REST API + 审查修复】
接口全部挂 /internal/v1/* 前缀，覆盖 Router/Transport/Producer/Consumer 完整生命周期：
- POST /routers, DELETE /routers/:id
- POST /transports, POST /transports/:id/connect
- POST /producers, DELETE /producers/:id
- POST /consumers, POST /consumers/:id/resume, DELETE /consumers/:id

工程特性：
- zod 手动 parse + 全局 errorHandler（不引入 fastify-type-provider-zod 避免
  zod v4 依赖冲突）
- AppError 统一错误码（NOT_FOUND/CONFLICT/CAN_NOT_CONSUME/ROUTER_LIMIT_EXCEEDED
  /MEDIASOUP_ERROR/VALIDATION_ERROR/UNAUTHORIZED/INTERNAL_ERROR）
- 所有资源用 Map + observer.once('close') 自清理，Consumer 监听 producerclose 级联关闭
- Consumer 强制 paused:true 创建，/resume 独立接口
- Transport direction 强约束：recv 拒 produce、send 拒 consume

code-reviewer 子代理审查"有条件通过"，同步修复：
- M1 _clearXxxMap 新增 src/utils/test-guard.ts#assertTestOnly 守卫（生产误调用抛错）
- M2 新增 src/schemas/rtp.ts 对 rtpParameters / rtpCapabilities 做 codecs 浅层校验
  （mimeType/clockRate/payloadType 必填、codecs ≥1），消除 as unknown as 双跳断言
- m1 connectTransport 改乐观锁：先置位再 await，失败回退
- m2 改读 consumer.producerPaused（更符合 mediasoup 语义）
- m3 producerclose 改为 once（风格一致）
- m5 internal-auth 改为反向白名单 PRIVATE_PATH_PREFIXES = ['/internal/']

验证：
- typecheck / lint 0 错误
- vitest：65 passed / 8 spec 文件
- 覆盖率 stmts 82.87% / branches 75.83% / funcs 91.3% / lines 82.87%
- 9 接口 happy path + 6 类错误路径 curl 手测全部按预期返回

【文档同步】
- CURRENT_STATUS.md +232 行：新增 Task 0/1/2 完整记录 + 代码审查修复章节 + 延后清单
- project-context.mdc：Task 0/1/2 状态同步
- phase2e-2-design.md +20 行：Fastify 5 升级相关决策记录
- phase2e-2-implementation.plan.md +117 行：Task 0/1/2 实际产出 + 修复记录

余下 Minor/Nits（m4/m6~m10/n1~n10）登记至 Task 16 收尾清单一次性清扫。

Made-with: Cursor

2026-04-21 15:31:01 +08:00

4.4 KiB

Raw Blame History

EchoChat media-server

EchoChat 多人音视频会议（Phase 2e-2）的 SFU 节点。内部使用 mediasoup 进行 WebRTC 媒体转发，外部用 Fastify 暴露内部 REST API，供 Go backend 调度；与 Go backend 之间使用 X-Internal-Token 鉴权，不直接对公网暴露。

配套文档：

Phase 2e-2 设计文档

Phase 2e-2 实施计划

mediasoup PoC Spike 记录

目录结构（Task 1 骨架）

media-server/
├── src/
│   ├── app.ts                       # Fastify 入口 + 生命周期
│   ├── config.ts                    # zod 校验的配置加载
│   ├── mediasoup/
│   │   └── worker.ts                # mediasoup Worker 单例 + died 自动重启
│   ├── middlewares/
│   │   └── internal-auth.ts         # X-Internal-Token 鉴权插件
│   └── utils/
│       └── logger.ts                # pino 日志
├── poc/                             # Task 0 PoC 源码（归档，不参与构建）
├── docs/poc-notes.md                # PoC 结论文档
├── Dockerfile                       # 多阶段构建（builder + runtime）
├── .env.example                     # 环境变量模板
├── package.json                     # 锁定 mediasoup@3.19 + fastify@5
├── tsconfig.json / tsconfig.build.json
├── .eslintrc.json / .prettierrc
└── README.md

快速开始

环境要求

Node.js ≥ 20（Fastify 5 要求；Dockerfile 使用 node:20-bookworm-slim）
构建 mediasoup 原生 worker 需要：python3 + make + C++ 编译工具链（本机 macOS 已自带 Xcode CLT；Linux 见 Dockerfile）

本地开发

cd media-server
cp .env.example .env
# 按需调整 MEDIA_INTERNAL_TOKEN / MEDIASOUP_ANNOUNCED_IP
npm install
npm run dev

启动成功后：

# 健康检查（公开，无需鉴权）
curl -s http://127.0.0.1:3300/healthz | jq
# {
#   "ok": true,
#   "service": "media-server",
#   "mediasoupVersion": "3.19.x",
#   "workerPid": 12345,
#   ...
# }

# 内部接口（需带 token）
curl -s -H "X-Internal-Token: $MEDIA_INTERNAL_TOKEN" \
  http://127.0.0.1:3300/internal/info | jq

鉴权校验

未带 token 访问 /internal/* 应返回 401：

curl -i http://127.0.0.1:3300/internal/info
# HTTP/1.1 401 Unauthorized
# {"code":"UNAUTHORIZED","message":"missing or invalid X-Internal-Token"}

常用脚本

命令	说明
`npm run dev`	tsx watch 热重载开发
`npm run build`	产出 `dist/` 供生产使用
`npm run typecheck`	TypeScript 纯类型校验
`npm run lint`	ESLint 检查
`npm run format`	Prettier 格式化
`npm run test`	vitest 单测
`npm start`	运行编译后的 `dist/app.js`（生产）

Docker 构建

docker build -t echochat/media-server:dev -f Dockerfile .
docker run --rm \
  -p 3300:3300 \
  -p 40000-40199:40000-40199/udp \
  -p 40000-40199:40000-40199/tcp \
  -e MEDIA_INTERNAL_TOKEN=dev-internal-token-change-me \
  -e MEDIASOUP_ANNOUNCED_IP=127.0.0.1 \
  echochat/media-server:dev

关键配置说明

完整列表见 .env.example。

变量	缺省	说明
`HTTP_PORT`	`3300`	内部 HTTP 端口，仅供 Go backend 调用
`MEDIA_INTERNAL_TOKEN`	—（必填）	Go 与 Node 之间的共享密钥
`MEDIASOUP_LISTEN_IP`	`0.0.0.0`	Worker 绑定 IP
`MEDIASOUP_ANNOUNCED_IP`	空	对外通告 IP（本机 demo 可留空，走默认 LAN；公网必填服务器公网 IP）
`MEDIASOUP_RTC_MIN_PORT` / `MAX_PORT`	`40000` / `40199`	RTP UDP/TCP 端口范围
`MEDIASOUP_WORKER_LOG_LEVEL`	`warn`	mediasoup worker 自身日志等级
`MEDIASOUP_MAX_ROUTERS`	`200`	单 Worker Router 水位上限

Task 1 验收清单

目录/配置/lint/格式化齐全
/healthz 返回 ok=true + workerPid
/internal/* 校验 X-Internal-Token，非法请求返回 401
Dockerfile 多阶段构建，含非 root 用户 + 健康检查
Worker died 事件自动重启（指数退避，最多 30s）

后续任务

Task 2 起将在此骨架上继续落地：/internal/routers、/transports、/produce、/consume 等 API，以及与 Go backend 的协同。详见实施计划。

4.4 KiB Raw Blame History Unescape Escape