6e2e792db0
本次提交一次性落盘 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
EchoChat - 音视频会议直播系统
EchoChat 是一套跨端可用、可扩展、可演进的实时音视频会议直播系统。支持即时聊天、多人音视频会议、互动直播等核心功能，采用控制面与媒体面彻底分离的架构设计。
技术栈
| 层级 | 技术 | 说明 |
|---|---|---|
| 前台前端 | uniapp (Vue 3) + mediasoup-client | 多端适配（H5/App/小程序） |
| 后台管理端 | Vue 3 + Vite + Element Plus | PC Web 管理后台 |
| 后端服务 | Go (Gin + GORM + Wire + zap) | 业务逻辑、信令控制 |
| 媒体服务 | Node.js + mediasoup | SFU 媒体控制与转发 |
| 数据库 | PostgreSQL 17 | 持久化数据存储 |
| 缓存 | Redis 7 | 实时状态、会话缓存 |
| 部署 | Docker Compose / Nginx | 容器化部署，预留 K8s |
系统架构
客户端 (uniapp / Vue3 管理端)
│
│ WebSocket + HTTP
│
Go 单体服务 (模块化)
│ ├── auth 用户认证鉴权
│ ├── im 即时通讯
│ ├── contact 联系人管理
│ ├── meeting 会议控制/信令
│ ├── notify 消息通知
│ └── admin 后台管理
│
├── PostgreSQL (持久化数据)
├── Redis (实时状态)
│
│ HTTP
│
mediasoup Node 服务
│ IPC
mediasoup Worker (C++ SFU)
核心设计思想：控制面与媒体面分离。Go 处理所有业务逻辑和信令控制，mediasoup 专注音视频媒体转发，音视频流直连 SFU Worker，不经过 Go 服务。
项目结构：
EchoChat/
├── frontend/ # 前台用户端 (uni-app + Vue 3.4)
├── admin/ # 后台管理端 (Vue 3.5 + Element Plus)
├── backend/
│ └── go-service/ # Go 后端服务 (Gin + GORM + Wire)
│ ├── app/ # 业务模块 (auth / admin)
│ ├── cmd/server/ # 服务入口
│ ├── config/ # 配置文件
│ ├── pkg/ # 公共包 (db / logs / middleware / utils)
│ └── router/ # 路由聚合
├── media-server/ # mediasoup Node 媒体服务 (Phase 3)
├── deploy/ # 部署配置 (Docker Compose)
├── design-system/ # UI 设计系统 (ui-ux-pro-max 生成)
├── docs/ # 项目文档
│ ├── progress/ # 开发进度
│ ├── plans/ # 实施计划
│ ├── api/ # API 接口文档
│ └── architecture/ # 架构设计文档
└── README.md
快速开始
环境要求
- Go 1.23+
- Node.js 18+
- Docker & Docker Compose
- PostgreSQL 17（通过 Docker 自动启动）
- Redis 7（通过 Docker 自动启动）
方式一：一键脚本（推荐）
项目在 scripts/ 目录遵循「首次初始化 / 日常启停」职责分离模式，参考 Rails / Django / Next.js 社区通用做法：
| 脚本 | 用途 | 使用频率 |
|---|---|---|
scripts/dev-setup.sh |
首次环境初始化：检查 Docker、拉起 Postgres/Redis/MinIO、重试式健康检查 | 仅首次 clone 或重建卷时 |
scripts/start.sh |
日常启动：秒级拉起全部服务（容器 + 应用层） | 每天多次 |
scripts/stop.sh |
日常停止：优雅终止应用层，默认保留容器 | 每天多次 |
scripts/status.sh |
状态查看：端口 / PID / 容器一览 | 排障随时 |
首次使用（仅一次）
# 首次 clone 后执行一次，完成 Docker 中间件初始化 + 健康检查
./scripts/dev-setup.sh
日常启停
# 启动全部服务
./scripts/start.sh
# 查看服务状态（端口/PID/容器）
./scripts/status.sh
# 停止应用层（保留 Docker 中间件）
./scripts/stop.sh
# 停止全部（含 Docker 中间件）
./scripts/stop.sh --all
# 只启停单项（可选 docker|backend|frontend|admin）
./scripts/start.sh backend
./scripts/stop.sh frontend
后台进程的 PID 与日志默认写入 .run/（已加入 gitignore），排障时可直接查看 .run/logs/*.log。
启动后各服务地址：
| 服务 | 端口 | 说明 |
|---|---|---|
| 前台用户端 (H5) | 5173 | http://localhost:5173 |
| 后台管理端 | 3100 | http://localhost:3100 |
| Go 后端 API | 8085 | http://localhost:8085（/health 健康检查） |
| PostgreSQL | 5432 | Docker 容器 echochat-postgres |
| Redis | 6379 | Docker 容器 echochat-redis |
| MinIO API | 9000 | 对象存储，S3 兼容 |
| MinIO Console | 9001 | http://localhost:9001（echochat / echochat123456） |
方式二：Docker Compose 全量启动
cd deploy
docker compose -f docker-compose.dev.yml up -d
注意：此方式下 Go 后端、前台、管理端需按下方「方式三」各自启动，或在 compose 中启用
go-service服务。
方式三：分步手动启动（开发调试）
1. 启动基础设施（数据库 + 缓存）
cd deploy
docker compose -f docker-compose.dev.yml up -d postgres redis
2. 启动 Go 后端
cd backend/go-service
go mod tidy
go run cmd/server/main.go
后端启动在 http://localhost:8085，健康检查：GET /health
3. 启动前台用户端（uni-app H5）
cd frontend
npm install --legacy-peer-deps
npm run dev:h5
前台 H5 启动在 http://localhost:5173（端口可能递增）
4. 启动后台管理端（Vue 3）
cd admin
npm install
npm run dev
管理端启动在 http://localhost:3100（自动代理 /api 到后端 8085）
MVP 功能规划（第一期）
Phase 1 — 基础设施与用户认证 ✅
- 设计方案与架构文档
- Docker Compose 开发环境（PostgreSQL + Redis）
- Go 后端服务骨架（Gin + GORM + Wire + Zap）
- 用户注册/登录 API（用户名+邮箱+密码）
- JWT Token 认证（有状态 JWT + Redis）
- RBAC 角色权限（user / admin / super_admin）
- 前台 uni-app 骨架 + 登录/注册/TabBar/个人中心
- 后台 Vue 3 管理端 + 登录/布局/用户管理
- Go 服务 Dockerfile + Docker Compose 全栈部署
Phase 2 — 即时通讯（待开始）
- 即时聊天（单聊 + 群聊，文字/图片/文件）
- 联系人/好友管理
- 消息通知系统
Phase 3 — 音视频会议（待开始）
- 多人音视频会议（即时会议 + 预约会议）
- 后台管理端会议监控
后续规划
- 屏幕共享
- 微信授权登录
- 互动直播（主播/观众/弹幕）
- 会议录制与回放
- 微服务拆分 + K8s 部署
- AI 辅助功能（语音转文字、会议纪要）
文档导航
| 文档 | 路径 | 说明 |
|---|---|---|
| 项目进度 | docs/progress/CURRENT_STATUS.md | 当前开发进度与技术决策 |
| 整体设计方案 | docs/plans/2026-02-27-echochat-system-design.md | 系统完整设计方案 |
| 第一阶段实施计划 | docs/plans/2026-02-27-phase1-foundation-and-auth.md | 基础设施+用户体系实施步骤 |
| 系统架构文档 | docs/architecture/system-architecture.md | 架构分层与技术选型 |
| API 接口文档 | docs/api/ | 按端+模块拆分的 REST API + WebSocket 事件定义 |
开源协议
MIT License