管理员操作手册

这页解决什么问题

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

控制面边界

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

生产建议：

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

常见连接方式：

Unix socket

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

TCP

synctv \
  --endpoint http://127.0.0.1:50052 \
  --auth-token-file /run/secrets/management_token \
  system stats

用户管理

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

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

角色层级：

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

常见操作：

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 因素。

房间管理

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

类别	常见命令	风险
生命周期	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. 对删除、封禁、转让所有权等操作保留原因。

审核与封禁

审核队列覆盖：

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

示例：

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 管理

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

常见操作：

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

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

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 参考。

系统与缓存运维

系统状态：

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

slice cache：

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 持久业务数据，但会降低后续缓存命中率。

操作前检查

先看语义

不确定命令影响时，先读本页和 房间、权限与用户偏好，再查 CLI 参数。

先看状态

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

保留原因

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

验证结果

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