55d6352c6a
- 新增 MediaServerConfig + config.{dev,docker}.yaml 的 media_server 段
（base_url / internal_token / timeout_ms / close_timeout_ms / close_retry）
- 新建 HTTPMediaOrchestrator（8 方法 + sync.Map 缓存 roomCode→routerID
+ 关闭类指数退避重试 200/500ms + ErrMediaResourceNotFound/ErrMediaServerError
两类错误）实现 MediaOrchestrator 接口
- wire 绑定由 NoopMediaOrchestrator 切换到 HTTPMediaOrchestrator；
MeetingService / MeetingSignalService 调用侧零改动
- E2E 脚本 docs/verify/meeting_t7_verify.mjs 证明 16/16 PASS：
健康检查/错token 401/REST 创房加入/WS room.join/真实 mediasoup
transport.create（ICE/DTLS 指纹均由 Node 返回非占位）/404 幂等关 producer
/host 结束会议触发 CloseRouter
- 同步更新 13 份文档：CURRENT_STATUS / implementation.plan / design
变更记录 / project-context / api 导览 / api websocket / api frontend meeting
/ system-architecture / media-server README / 顶层 README 等
- go build ./... 全绿
Made-with: Cursor
239 lines
7.5 KiB
Markdown
239 lines
7.5 KiB
Markdown
# 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 2e-2 Task 0-2 已落地 9 REST API，Task 7 起 Go 通过 HTTPMediaOrchestrator 接入)
|
||
├── 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 / 容器一览 | 排障随时 |
|
||
|
||
#### 首次使用（仅一次）
|
||
|
||
```bash
|
||
# 首次 clone 后执行一次，完成 Docker 中间件初始化 + 健康检查
|
||
./scripts/dev-setup.sh
|
||
```
|
||
|
||
#### 日常启停
|
||
|
||
```bash
|
||
# 启动全部服务
|
||
./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 全量启动
|
||
|
||
```bash
|
||
cd deploy
|
||
docker compose -f docker-compose.dev.yml up -d
|
||
```
|
||
|
||
> 注意：此方式下 Go 后端、前台、管理端需按下方「方式三」各自启动，或在 compose 中启用 `go-service` 服务。
|
||
|
||
### 方式三：分步手动启动（开发调试）
|
||
|
||
**1. 启动基础设施（数据库 + 缓存）**
|
||
|
||
```bash
|
||
cd deploy
|
||
docker compose -f docker-compose.dev.yml up -d postgres redis
|
||
```
|
||
|
||
**2. 启动 Go 后端**
|
||
|
||
```bash
|
||
cd backend/go-service
|
||
go mod tidy
|
||
go run cmd/server/main.go
|
||
```
|
||
|
||
后端启动在 `http://localhost:8085`，健康检查：`GET /health`
|
||
|
||
**3. 启动前台用户端（uni-app H5）**
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install --legacy-peer-deps
|
||
npm run dev:h5
|
||
```
|
||
|
||
前台 H5 启动在 `http://localhost:5173`（端口可能递增）
|
||
|
||
**4. 启动后台管理端（Vue 3）**
|
||
|
||
```bash
|
||
cd admin
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
管理端启动在 `http://localhost:3100`（自动代理 `/api` 到后端 8085）
|
||
|
||
---
|
||
|
||
## MVP 功能规划（第一期）
|
||
|
||
### Phase 1 — 基础设施与用户认证 ✅
|
||
|
||
- [x] 设计方案与架构文档
|
||
- [x] Docker Compose 开发环境（PostgreSQL + Redis）
|
||
- [x] Go 后端服务骨架（Gin + GORM + Wire + Zap）
|
||
- [x] 用户注册/登录 API（用户名+邮箱+密码）
|
||
- [x] JWT Token 认证（有状态 JWT + Redis）
|
||
- [x] RBAC 角色权限（user / admin / super_admin）
|
||
- [x] 前台 uni-app 骨架 + 登录/注册/TabBar/个人中心
|
||
- [x] 后台 Vue 3 管理端 + 登录/布局/用户管理
|
||
- [x] Go 服务 Dockerfile + Docker Compose 全栈部署
|
||
|
||
### Phase 2 — 即时通讯（待开始）
|
||
|
||
- [ ] 即时聊天（单聊 + 群聊，文字/图片/文件）
|
||
- [ ] 联系人/好友管理
|
||
- [ ] 消息通知系统
|
||
|
||
### Phase 3 — 音视频会议（待开始）
|
||
|
||
- [ ] 多人音视频会议（即时会议 + 预约会议）
|
||
- [ ] 后台管理端会议监控
|
||
|
||
## 后续规划
|
||
|
||
- 屏幕共享
|
||
- 微信授权登录
|
||
- 互动直播（主播/观众/弹幕）
|
||
- 会议录制与回放
|
||
- 微服务拆分 + K8s 部署
|
||
- AI 辅助功能（语音转文字、会议纪要）
|
||
|
||
---
|
||
|
||
## 文档导航
|
||
|
||
| 文档 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| 项目进度 | [docs/progress/CURRENT_STATUS.md](docs/progress/CURRENT_STATUS.md) | 当前开发进度与技术决策 |
|
||
| 整体设计方案 | [docs/plans/2026-02-27-echochat-system-design.md](docs/plans/2026-02-27-echochat-system-design.md) | 系统完整设计方案 |
|
||
| 第一阶段实施计划 | [docs/plans/2026-02-27-phase1-foundation-and-auth.md](docs/plans/2026-02-27-phase1-foundation-and-auth.md) | 基础设施+用户体系实施步骤 |
|
||
| 系统架构文档 | [docs/architecture/system-architecture.md](docs/architecture/system-architecture.md) | 架构分层与技术选型 |
|
||
| API 接口文档 | [docs/api/](docs/api/) | 按端+模块拆分的 REST API + WebSocket 事件定义 |
|
||
|
||
---
|
||
|
||
## 开源协议
|
||
|
||
MIT License
|