3b83c79036
核心交付：
- 新建 MeetingLifecycleService（6 钩子 + sync.Map 本地 timer + Redis key 双保险 + RescheduleFromRedis）
- 新建 MeetingCleanupTask（启动重建 timer + 每 N 秒扫 host_grace/empty_ttl 兜底 + 4h stale active 回收）
- MediaOrchestrator 新增 ResolveRouterID；HTTPMediaOrchestrator.CreateRouter 入口 sync.Map 幂等防御
- 业务层 JoinRoom 移除 CreateRouter 调用改走 CancelEmptyTTL + ResolveRouterID；LeaveRoom 空房分支改调 OnAllMembersLeft 不再立即销毁
- MeetingSignalService 新增 OnWSDisconnect 实现 ws.MeetingDisconnectHook；OnRoomJoin 追加 host 重连钩子
- ws.handler 定义 MeetingDisconnectHook 接口 + SetMeetingDisconnectHook，解耦 ws→meeting 反向依赖
- config 新增 MeetingConfig{HostGrace=120, EmptyRoomTTL=300, CleanupInterval=30, StaleRoomHours=4}
关键设计决策：
- Redis key TTL = 业务时长 + max(CleanupIntervalSeconds*2, 30s) buffer：避免本地 timer 与
Redis 自动过期同步到期导致 DEL 返回 0 被误判为"已被其他路径处理"而跳过业务逻辑
- Router 幂等双层防御（决策 q2_router_dedup=a2_both）：业务层不重复调 + HTTP 层 sync.Map 命中直接返回
- 普通成员 WS 断开仅清 media 资源不动 participant 表（决策 q1_nonhost_disconnect=a1_keep_current）
E2E 验证：docs/verify/meeting_t8_verify.mjs PASS=20 FAIL=0，覆盖 5 场景：
- S1 host 宽限期过期自动转让（meeting.host.changed + DB host_id 更新）
- S2 宽限期内重连保留身份
- S3 empty_ttl 期内新成员加入复活房间
- S4 empty_ttl 过期 → 房间 Ended + 新 join 被拒
- S5 CreateRoom +1 Router / JoinRoom 不再创建新 Router（通过 media-server /internal/info stats.routers 断言）
media-server：/internal/info 响应追加 stats.routers + routers[] 供 E2E 断言 Router 幂等
文档同步：
- docs/progress/CURRENT_STATUS.md 头部 + 新增 Task 8 交付条目
- docs/plans/2026-04-21-phase2e-2-implementation.plan.md Task 8 标记完成 + 实际产出/决策/验证
- docs/api/frontend/meeting.md 补充 host.changed.auto_reason / room.ended.reason=system_error / 空房 TTL 复活语义 + Task 8 验证记录
- docs/architecture/system-architecture.md meeting 模块职责补充"会议生命周期状态机"
- .cursor/rules/project-context.mdc 追加 Task 8 条目并更新 Phase 2e-2 进度（Task 0-8 ✅）
Made-with: Cursor
EchoChat media-server
EchoChat 多人音视频会议（Phase 2e-2）的 SFU 节点。内部使用 mediasoup 进行 WebRTC 媒体转发，外部用 Fastify 暴露内部 REST API，供 Go backend 调度；与 Go backend 之间使用 X-Internal-Token 鉴权，不直接对公网暴露。
配套文档：
目录结构（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/v1/routers、/transports、/produce、/consume等 9 个内部 REST API 全部落地（58 单元/集成测试，覆盖率 80.89%）。 - Task 7 ✅（2026-04-21）：Go 侧
HTTPMediaOrchestrator通过X-Internal-Token已完整接入本服务的/internal/v1/*；Go↔Node 媒体链路在端到端脚本docs/verify/meeting_t7_verify.mjs中 16/16 PASS，媒体 Router/Transport/Producer/Consumer 生命周期均由 Go 驱动。 - 后续：Task 9（前端 mediasoup-client）接入时若暴露
meeting.consume.resume事件，需由 Go 侧调用本服务POST /internal/v1/consumers/:id/resume（已实现）。Task 10 将新增GET /internal/v1/transports/:id/stats供 Go 定时拉取。