跳转到内容
SyncTV SyncTV 文档

常见任务流程

先选目标

Section titled “先选目标”

从正在处理的目标进入，不必按侧边栏顺序阅读。流程只保留操作顺序；字段、接口或配置细节在对应专题页展开。

普通用户流程

Section titled “普通用户流程”
  1. 登录账号，确认邮箱、2FA 或 OAuth2 状态正常。
  2. 创建房间或打开已有房间入口。
  3. 如果房间需要密码或审核，按提示提交。
  4. 添加媒体，或从已有播放列表选择媒体。
  5. 有播放控制权限时开始播放；没有权限时等待房间管理员开始。
  6. 播放异常时先刷新播放信息，再确认是否需要代理播放。

房间管理员流程

Section titled “房间管理员流程”

创建受控房间

Section titled “创建受控房间”
  1. 创建房间，设置清晰名称和说明。
  2. 根据需要设置房间密码。
  3. 如果是半公开房间，启用 requireApproval。
  4. 设置 maxMembers，避免超过服务和上游 Provider 能力。
  5. 检查 member/guest 默认权限，不要把播放控制、成员封禁等管理权限开放给游客。
  6. 用普通成员账号加入验证一次。

处理成员问题

Section titled “处理成员问题”
目标动作注意
临时禁言在成员权限里移除 send_chat比修改全房间聊天设置影响更小
给某人控制播放给成员增加 play_control如果还要切媒体，加 change_current_media
清理扰乱成员kick 成员踢出后会进入临时重新加入冷却
调整长期职责修改房间角色或默认权限长期不要依赖大量个人覆盖

权限细节见 权限模型 和 房间、权限与用户偏好。

平台管理员流程

Section titled “平台管理员流程”

首次上线验收

Section titled “首次上线验收”
  1. 按 生产部署清单 确认 secret、数据库、Redis、TLS 和备份。
  2. 运行 synctv config validate --strict。
  3. 检查 /health/ready。
  4. 登录 root，创建普通用户和测试房间。
  5. 验证 WebSocket、聊天、播放控制、Provider 浏览、代理播放。
  6. 启用 metrics 并确认抓取成功。
  7. 做一次 PostgreSQL 和 secret 恢复演练。

接入一个媒体 Provider

Section titled “接入一个媒体 Provider”
  1. 确认使用本地 Provider 还是远程 Provider instance。
  2. 配置或创建 Provider instance，确保凭据加密 key 已配置。
  3. 用管理员账号测试登录、浏览、搜索和播放。
  4. 分别测试直连和代理播放。
  5. 对支持 Range 的上游验证 seek 和 slice cache 行为。
  6. 给普通用户分配合适的 Provider 默认实例或使用说明。

更多配方见 添加媒体。

开发者流程

Section titled “开发者流程”

跑通一个客户端

Section titled “跑通一个客户端”
  1. 读取 客户端集成指南 确认 HTTP、gRPC 和 WebSocket 分工。
  2. 启动带 OpenAPI 的服务，导出 /api-docs/openapi.json。
  3. 生成 SDK 或手写最小请求。
  4. 实现登录和 refresh token 流程。
  5. 创建 WebSocket ticket 并连接 /ws/rooms/{roomId}。
  6. 用 Realtime API 订阅播放状态、播放信息、房间设置和成员列表。
  7. 按 错误参考 处理 status、code、requestId 和 Retry-After。

新增或修改 API

Section titled “新增或修改 API”
  1. 先确认使用 HTTP/OpenAPI、gRPC 还是 Realtime。
  2. 修改 proto 或 HTTP handler，保持错误分类和权限检查一致。
  3. 为新增字段补测试、OpenAPI 或 protobuf 文档。
  4. 更新 SDK 与 API 示例、Realtime API 或 gRPC 调试。
  5. 如果破坏已有协议语义，同步更新 API 与 protobuf 演进策略。

运维流程

Section titled “运维流程”

容量或性能异常

Section titled “容量或性能异常”
  1. 查看 /metrics 中 HTTP、WebSocket、数据库、缓存、Provider、直播和集群指标。
  2. 按 容量规划 判断瓶颈是连接数、数据库、Redis、Provider 上游、带宽还是存储。
  3. 优先降低上游压力：开启 Redis、合理使用 slice cache、限制房间人数和连接数。
  4. 如果是多副本，确认所有节点共享 PostgreSQL、Redis 和一致的 secret。
  5. 记录版本、部署方式、关键指标和日志，再进入 排障入口。

密钥轮换

Section titled “密钥轮换”
  1. 先读 安全加固与密钥轮换。
  2. 区分可直接轮换的 token、需要用户重新登录的 JWT secret、不能随意更换的 OPAQUE setup secret 和 credential encryption key。
  3. 备份旧 secret。
  4. 在测试环境验证登录、Provider 解密、WebSocket、OAuth2 和 WebAuthn。
  5. 低峰期发布并观察错误率。

继续阅读

Section titled “继续阅读”