Rust SyncTV 设计文档

文档状态: 完整设计 (25章)

---

📚 文档目录

本设计文档采用模块化组织，每个大章节独立成文件：

第一部分: 基础架构 (01-05)

• 01-项目概述.md - 项目背景、核心特性、技术栈
• 02-整体架构.md - 系统架构、多副本设计、服务发现
• 03-核心模块.md - 模块设计、API层、业务层、数据层
• 04-数据库设计.md - 表结构、索引、查询优化、OAuth2、审计日志
• 05-缓存设计.md - Redis、本地缓存、一致性策略

第二部分: 核心业务模块 (06-13)

• 06-用户系统设计.md - 认证、授权、OAuth2、邮箱验证
• 07-权限系统设计.md - 角色、状态分离、64位权限位掩码
• 08-视频内容管理.md - 视频解析、代理、字幕系统
• 09-媒体源提供商配置管理.md - Alist、Bilibili、Emby 配置管理
• 10-视频链接过期与代理机制.md - JWT过期、宽限期、无轮询
• 11-实时互动.md - 聊天、弹幕、内容过滤
• 12-时间同步与补偿.md - HTTP时间同步、类NTP算法、延迟补偿
• 13-自动连播设计.md - 播放模式、房间级配置

第三部分: 通信与API (14-18)

• 14-通信架构设计.md - gRPC/gRPC-Web/HTTP 三层架构、API文档生成
• 15-API接口定义.md - gRPC 接口定义、tonic + axum 集成
• 16-实时消息流.md - gRPC Streaming 双向流、Redis Pub/Sub
• 17-数据流设计.md - 推流、拉流、同步流程
• 18-API文档生成方案.md - utoipa、OpenAPI 3.0、Swagger UI

第四部分: 实现与运维 (19-25)

• 19-配置管理系统.md - 配置优先级、热重载、环境变量
• 20-CLI命令设计.md - 命令树结构、配置加载、Shell补全
• 21-关键实现.md - 零拷贝、并发、内存管理
• 22-部署方案.md - Helm Charts、Docker、Docker Compose
• 23-监控优化.md - 性能监控与优化策略
• 24-安全故障.md - RS256 JWT、OAuth2 PKCE、Argon2id
• 25-附录.md - 技术栈详解、配置示例、术语表

---

🗺️ 实施路线图

详见 ROADMAP.md

---

核心架构特点

✅ 平等副本架构

• 所有副本完全平等，无全局角色
• 推流时记录 Publisher 节点位置
• 其他节点懒加载拉流 (收到FLV请求时才拉取)

✅ 直播流分发策略 (懒加载模式)

用户推流 → 任意副本 (成为Publisher)
            ↓
      记录到 Redis: stream:{key} → {publisher_node_id}
            ↓
      客户端请求FLV → 任意副本
            ↓
      副本查询 Redis → 懒加载创建拉流 → 从 Publisher 拉取
            ↓
      本地转码 → 分发给本地客户端

懒加载优势:

• 按需创建拉流连接,节省资源
• 无需监听集群事件
• 自动清理无订阅者的拉流

✅ 数据同步机制

• gRPC: 客户端通信、副本间通信
• Redis Pub/Sub: 集群事件广播、跨节点消息分发
• PostgreSQL: 持久化数据
• gRPC Streaming: 客户端实时消息流

---

快速导航

关注点	推荐阅读
了解项目	01-项目概述
架构设计	02-整体架构
多副本架构	MULTI_REPLICA_AUDIT - 问题总结
gRPC Streaming	16-实时消息流 §10.0 - 双向流通信
分布式锁	21-关键实现 §12.2.3 - Redis锁机制
Publisher冲突	17-数据流设计 §11.1.3 - 原子注册
缓存一致性	05-缓存设计 §5.3.3 - 事件驱动失效
并发控制	04-数据库设计 §6 - 乐观锁
数据库设计	04-数据库设计 - OAuth2、审计日志、乐观锁
用户与认证	06-用户系统设计 - Argon2id、RS256 JWT、OAuth2
权限管理	07-权限系统设计 - 角色/状态分离、权限位掩码
配置管理	19-配置管理系统 - 配置优先级、热重载
CLI命令	20-CLI命令设计 - 命令树、Shell补全
直播流处理	17-数据流设计 - 推流、拉流、Publisher冲突预防
通信架构	14-通信架构设计 - gRPC/gRPC-Web/HTTP 三层架构
gRPC API	15-API接口定义 - 客户端与集群通信
实时消息流	16-实时消息流 - gRPC Streaming 双向流
API文档	18-API文档生成方案 - utoipa、OpenAPI 3.0
部署上线	22-部署方案 - Helm、Docker Compose
安全设计	24-安全故障 - RS256 JWT、OAuth2 PKCE
性能优化	23-监控优化

---

项目仓库: https://github.com/synctv-org/synctv 作者: SyncTV Team