API 与实时协作
HTTP REST、公开 gRPC、WebSocket 和房间实时事件共享同一套业务服务与权限模型。
架构总览
SyncTV 是一个单二进制服务，内部组合 HTTP API、公开 gRPC、management gRPC、实时房间状态、媒体 Provider、媒体代理、直播和集群协调能力。持久状态在 PostgreSQL，跨节点临时状态和分布式协调依赖 Redis，本地运行时文件放在 data_dir。
身份认证
本地密码、passkey/WebAuthn、邮箱验证码、OAuth2、用户级 2FA 和 JWT token 共同构成登录层。
媒体能力
Provider 负责解析外部媒体，proxy 负责可控转发，slice cache 只缓存 Range slice，不做 full-body cache。
横向扩展
多节点通过 Redis pub/sub、Redis Stream、节点发现和 leader election 同步房间事件与后台任务。
| 入口 | 默认端口或路径 | 作用 | 生产建议 |
|---|---|---|---|
| HTTP REST | server.port=8080 | 客户端业务 API、健康检查、OpenAPI UI | 通过反向代理或 Ingress 暴露 |
| 公开 gRPC | server.port=8080 | 客户端或 SDK 使用的 gRPC API | Kubernetes 中使用独立 Service 和独立 Ingress |
| WebSocket | server.port=8080 | 房间实时事件、播放同步、聊天等长连接 | 配置连接限制和合理的 shutdown drain |
| management gRPC | Unix socket 或 management.port=50052 | CLI、管理命令、运维控制面 | 优先 Unix socket；TCP 必须配置 token |
| metrics | metrics.port=9090 | Prometheus 指标出口 | 不直接暴露公网，启用鉴权 |
| RTMP | livestream.rtmp_port=1935 | 直播推流入口 | 只在需要直播时放行 |
| STUN UDP | webrtc.stun_port=3478 | WebRTC NAT 辅助 | 只在需要内置 STUN 时放行 |
HTTP REST 和公开 gRPC 共享主端口，但在 Kubernetes 中仍建议拆成两个 Service 和两个 Ingress。这样可以给 gRPC Ingress 单独设置 nginx.ingress.kubernetes.io/backend-protocol: "GRPC"，也更容易分别做路由、TLS 和观测。
PostgreSQL 是唯一必须持久化的核心状态层。用户、房间、权限、Provider 实例、用户偏好、审计和业务数据都在这里。
生产要求：启动阶段会自动执行 embedded SQLx migrations；必须有备份与恢复流程；数据库连接池大小不能超过数据库和连接代理的容量；回滚前必须确认数据库 migration 是否可逆。
Redis 是共享临时状态和分布式协调层。单节点可以不配置 Redis，但生产和多副本建议配置。
Redis 影响：限流和暴力破解防护、token blacklist、OAuth2 state、WebAuthn challenge、邮箱验证码短期状态、L2 缓存、集群 pub/sub、节点注册和事件 catch-up。
Redis 通常不作为长期持久数据备份对象，但重启或清空会影响正在进行的登录、验证码、限流窗口和集群短期状态。
data_dir 是 SyncTV 写入本地运行时文件的根目录。
常见内容：management Unix socket、文件日志、HLS 文件、proxy slice cache 文件后端。
*_file secret、TLS 证书等静态输入文件不会被 data_dir 自动重定位。
普通 API 请求
Section titled “普通 API 请求”- 客户端通过 HTTP 或 gRPC 访问 SyncTV。
- API 层完成认证、限流、权限检查和请求解析。
- 业务服务读写 PostgreSQL，并按需使用 Redis/L1 缓存。
- 实时变更通过 WebSocket 推送给房间成员；集群模式下通过 Redis 同步到其他节点。
媒体 Provider 和代理请求
Section titled “媒体 Provider 和代理请求”- Provider 根据实例配置解析媒体地址，并决定返回直连地址还是代理地址。
- Provider 明确声明上游请求需要哪些 header，例如
User-Agent、Referer、Range或认证 header。 - proxy 底层只使用 Provider 给出的 header，不自行转发原始客户端 header。
- slice cache 只处理支持 Range 的上游响应；上游不支持 Range 时直接 bypass，不缓存完整响应体。
集群模式适合多副本部署。开启 cluster.enabled=true 后，Redis 和 server.cluster_secret 都是必需项。
关键配置：
| 配置 | 作用 |
|---|---|
cluster.discovery_mode | 节点发现方式，支持 redis、static、k8s_dns |
cluster.leader_election_mode | 后台任务 leader 选举方式，支持 redis、k8s_lease |
server.advertise_host | 其他节点连接当前节点时使用的地址 |
server.cluster_secret | 节点间 gRPC 调用认证 |
cluster.catchup_window_secs | 节点短暂断开后从 Redis Stream 补事件的窗口 |
多副本时还要确认：
- 所有副本共享同一个 PostgreSQL。
- 所有副本共享同一个 Redis 和
redis.key_prefix。 - HLS 跨节点访问可以走 publisher-node proxy；高流量生产场景建议使用共享文件系统或 OSS，减少 publisher 节点压力。
- Pod 关闭时给足
server.shutdown_drain_timeout_seconds和 Kubernetes termination grace period。
更完整的运行时设计、发现模式、leader election 和集群直播边界见 集群配置。
直播路径和点播 proxy 路径不同。RTMP 是推流入口；HTTP-FLV 面向低延迟播放；HLS 通过 remuxer 生成 playlist/segment 并写入 memory、file 或 oss backend。多副本时，publisher 所在节点通过共享 registry 暴露给其他节点；非 publisher 节点可以通过 HLS gRPC proxy 向 publisher 节点读取分片，也可以在共享文件系统或 OSS 模型下直接读取分片。
详细的 RTMP/StreamHub/HTTP-FLV/HLS pipeline、backend 选择和集群直播故障边界见 直播与 HLS/FLV。
生产架构建议
Section titled “生产架构建议”最小生产拓扑：
Kubernetes 多副本拓扑：
