跳转到内容
SyncTV 文档

管理员操作手册

这页解决什么问题

Section titled “这页解决什么问题”

CLI 参考 负责列命令，这页负责解释管理动作的语义、顺序和风险。生产管理员通常需要同时处理用户、房间、审核、Provider、运行时设置、系统状态和缓存清理；这些操作都通过 management gRPC 控制面执行。

控制面边界

Section titled “控制面边界”

management gRPC 是运维控制面，不是普通用户 API。

生产建议：

  • 优先使用 Unix socket。
  • TCP management 必须配置 management.auth_token。
  • 不要把 TCP management 暴露公网。
  • 远程管理优先走内网、VPN、堡垒机或 Kubernetes exec。
  • 所有涉及 root/admin、用户安全偏好和 Provider 凭据的操作都应该保留审计日志。

常见连接方式：

Terminal window
synctv --endpoint unix:///var/lib/synctv/synctv.sock system stats

用户管理

Section titled “用户管理”

用户有全局角色和有效状态：

概念值说明
全局角色root、admin、user控制平台级管理能力
有效状态active、banned由封禁记录派生，影响登录、建房和加入房间
用户偏好2FA、通知、Provider 默认实例用户级设置，不等同于 YAML 配置

角色层级：

  • root 可以管理所有用户和管理员。
  • admin 可以管理普通用户，但不能管理 root 或同级管理员的敏感设置。
  • user 只能按业务权限使用房间和媒体功能。

常见操作：

Terminal window
synctv user list
synctv user get alice
synctv user create alice --password 'StrongPass123'
synctv user ban alice --reason "abuse"
synctv user unban alice
synctv user set-role alice admin
synctv user preferences get alice

安全建议：

  • 禁用用户优先使用 ban，不要直接删除，除非你明确要清理其相关数据。
  • 改密码、改角色、改 2FA 偏好属于敏感操作，应限制给 root 或受信任 admin。
  • 开启 2FA 前必须确认用户拥有至少两种本地验证方式，OAuth2 不计入本地 2FA 因素。

房间管理

Section titled “房间管理”

房间操作分为生命周期、成员、设置、播放和直播几类。

类别常见命令风险
生命周期room create、room delete、room ban、room transfer-owner会影响房间可见性、所有权和数据保留
成员room member add/kick/ban/unban/set-permissions会改变访问和管理能力
设置room settings update/reset会改变加入规则、游客、聊天、弹幕和权限默认值
播放room playback play/pause/seek/start/stop会改变所有在线成员看到的播放状态
直播room stream list、provider rtmp create-publish-key涉及推流密钥和直播会话

建议顺序：

  1. 先查询房间和成员当前状态。
  2. 修改前确认操作者、目标用户和房间角色。
  3. 对成员权限只授予必要权限，不把 DELETE_ROOM 作为房间内可委派能力。
  4. 修改房间设置后观察 WebSocket 同步和加入流程。
  5. 对删除、封禁、转让所有权等操作保留原因。

审核与封禁

Section titled “审核与封禁”

审核队列覆盖：

  • 用户注册审核。
  • 房间创建审核。
  • 房间加入审核。

示例：

Terminal window
synctv review user-registration list
synctv review user-registration approve <REVIEW_ID>
synctv review user-registration reject <REVIEW_ID> --reason "reason"

建议：

  • 对拒绝和封禁写清楚 reason，方便后续审计和申诉。
  • 批量封禁前先用 user list 或 room member list 确认目标集合。
  • 用户封禁会影响登录、建房和加入房间；房间成员封禁只影响指定房间。

Provider 管理

Section titled “Provider 管理”

Provider 实例是外部媒体源的连接配置。实例配置通常包含 URL、token、cookie、UA、认证信息、远程 gRPC 信息或特定后端参数。

常见操作：

Terminal window
synctv provider available
synctv provider list
synctv provider create <NAME> <PROVIDER_ENDPOINT> --provider alist
synctv provider update <NAME> --provider-endpoint <PROVIDER_ENDPOINT> --provider alist
synctv provider enable <NAME>
synctv provider disable <NAME>
synctv provider reconnect <NAME>
synctv provider delete <NAME>

生产建议：

  • 敏感凭据优先用 secret 文件、加密存储或受控管理接口，不要写入 shell history。
  • 修改 Provider header、UA、代理策略后，测试直连和代理路径是否一致。
  • Bilibili、Alist 这类对 header 敏感的 Provider，要重点确认 User-Agent、Referer、Range 和认证 header。
  • 删除实例前确认是否有用户偏好或房间媒体引用该实例。

Runtime settings

Section titled “Runtime settings”

runtime settings 是数据库里的热更新设置，和 YAML 启动配置不同。

Terminal window
synctv settings list
synctv settings get user.enable_password_signup
synctv settings update user --set enable_password_signup=true

语义：

  • 写入 PostgreSQL。
  • 多副本通过 PostgreSQL LISTEN/NOTIFY 同步。
  • 由注册的 setting provider 校验类型和值。
  • 适合开关注册、房间创建、代理策略、CORS 热更新等运行时策略。
  • 不适合保存启动期必须固定的 secret、监听端口、数据库连接、Redis 连接等配置。

完整字段见 Runtime settings 参考。

系统与缓存运维

Section titled “系统与缓存运维”

系统状态：

Terminal window
synctv system stats
synctv system stream list
synctv system stream kick <STREAM_ID>

slice cache：

Terminal window
synctv slice-cache stats
synctv slice-cache evict-expired
synctv slice-cache purge

注意：

  • slice cache 是否启用由 cache.proxy_slice_cache_enabled 启动配置决定。
  • CLI 不支持动态启停 slice cache，只提供统计、过期驱逐和清空。
  • purge 会清理缓存数据，不影响 PostgreSQL 持久业务数据，但会降低后续缓存命中率。

操作前检查

Section titled “操作前检查”

先看状态

删除、封禁、转让、批量操作前先执行 list/get，确认目标对象和当前状态。

保留原因

对拒绝、封禁、踢出、删除这类操作写 reason，减少后续审计成本。

验证结果

操作后检查 API、WebSocket、Provider、metrics 或日志，确认变更确实生效。