Runtime settings 参考

Runtime settings 是什么

Runtime settings 是存储在 PostgreSQL 的热更新设置，主要用于运行中调整产品策略。它们不同于 YAML/env/CLI 启动配置：

类型	存储位置	是否热更新	适合内容
启动配置	YAML、env、secret file、CLI flag	否，通常需要重启	端口、数据库、Redis、secret、TLS、data_dir、cache 启用
Runtime settings	PostgreSQL `settings` 表	是，多副本通过 LISTEN/NOTIFY 同步	注册、房间创建、权限默认值、代理开关、CORS、聊天保留策略

CLI 用法

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

如果命令支持 --set 批量形式，也可以用：

synctv settings update email --set whitelist_enabled=true --set whitelist=example.com

具体参数以当前二进制的 synctv settings --help 为准。

同步与一致性

runtime settings 写入 PostgreSQL 后，会通过 PostgreSQL LISTEN/NOTIFY 通知其他副本刷新本地缓存。

语义：

每个设置 key 都有注册的类型 provider。
写入前会做类型和值校验。
多 key 约束会走事务交叉校验，例如 room.room_must_need_pwd 和 room.room_must_no_need_pwd 不能同时为 true。
如果某个副本短暂错过通知，会强制重新拉取快照。

字段参考

Server

Key	类型	默认值	校验	说明
`server.allow_room_creation`	bool	`true`	bool	是否允许用户创建房间
`server.max_rooms_per_user`	i64	`10`	`1..=1000`	每个用户最多创建多少房间
`server.max_members_per_room`	i64	`100`	`1..=10000`	每个房间最大成员数
`server.max_chat_messages`	u64	`500`	`<=10000`，`0` 表示不限	服务级公开聊天消息数量上限策略；清理任务使用 `chat.max_messages_per_room`

Permissions

Key	类型	默认值	说明
`permissions.admin_default`	u64 bitmask	`1073741823`	房间 admin 全局默认权限
`permissions.member_default`	u64 bitmask	`262143`	房间 member 全局默认权限
`permissions.guest_default`	u64 bitmask	`511`	房间 guest 全局默认权限

权限 bitmask 语义见房间、权限与用户偏好。

Room

Key	类型	默认值	校验	说明
`room.disable_create_room`	bool	`false`	bool	是否禁用创建房间
`room.create_room_need_review`	bool	`false`	bool	创建房间是否需要审核
`room.room_ttl`	i64 秒	`172800`	`>=0`，`0` 表示不过期	房间自动过期时间
`room.room_must_need_pwd`	bool	`false`	与 `room.room_must_no_need_pwd` 互斥	是否强制房间必须设置密码
`room.room_must_no_need_pwd`	bool	`false`	与 `room.room_must_need_pwd` 互斥	是否强制房间不能设置密码

User

Key	类型	默认值	说明
`user.enable_password_signup`	bool	`false`	是否允许密码注册，包括传统密码注册和 OPAQUE 密码注册
`user.password_signup_need_review`	bool	`false`	密码注册是否需要审核
`user.enable_email_signup`	bool	`false`	是否允许邮件注册。当前邮件登录只服务已有账号，此开关用于后续邮件无密码建号入口
`user.email_signup_need_review`	bool	`false`	邮件注册是否需要审核
`user.enable_webauthn_signup`	bool	`false`	是否允许 WebAuthn/passkey 作为初始账号注册方式；登录后绑定 passkey 不属于注册
`user.webauthn_signup_need_review`	bool	`false`	WebAuthn 注册是否需要审核。当前审核表不存 WebAuthn 临时凭据，启用后会拒绝新的 WebAuthn 注册
`user.enable_guest`	bool	`true`	是否允许游客能力

注册相关开关默认全部关闭。生产环境应只打开明确需要的注册入口，并分别决定是否需要审核。

OAuth2

Key	类型	默认值	说明
`oauth2.providers`	JSON 对象	`{}`	OAuth2/OIDC provider 实例注册表。每个 key 是实例名，每个 value 包含 `type`、`enable_signup`、`signup_need_review` 和 provider 私有 `config`

oauth2.providers 是唯一的 OAuth2 配置入口，不再使用配置文件、环境变量或 Helm values 定义 provider。实例名只能包含 ASCII 字母、数字、_ 和 -，并且最长 64 字节。外层结构固定，config 内部由具体 provider 解析：

{
  "github": {
    "type": "github",
    "enable_signup": true,
    "signup_need_review": false,
    "config": {
      "client_id": "github-client-id",
      "client_secret": "github-client-secret",
      "redirect_url": "https://app.example.com/oauth2/callback"
    }
  },
  "corp_oidc": {
    "type": "oidc",
    "enable_signup": false,
    "signup_need_review": false,
    "config": {
      "client_id": "synctv",
      "client_secret": "oidc-client-secret",
      "issuer": "https://idp.example.com",
      "redirect_url": "https://app.example.com/oauth2/callback"
    }
  }
}

缺失 provider 实例表示该登录入口不可用。缺失或为 false 的 enable_signup 会阻止首次 OAuth2 登录自动创建本地账号，但已绑定的 OAuth2 登录不受影响。signup_need_review=true 会把首次 OAuth2 注册写入用户注册审核队列，审核通过后才创建本地账号和 OAuth2 绑定。

注意：用户级 2FA、通知偏好和 Provider 默认实例不在这里，属于 user preferences。见房间、权限与用户偏好。

Proxy

Key	类型	默认值	说明
`proxy.movie_proxy`	bool	`true`	是否允许电影/媒体代理路径
`proxy.live_proxy`	bool	`true`	是否允许直播代理路径
`proxy.allow_proxy_to_local`	bool	`true`	是否允许代理访问本地/内网目标

这些是业务代理策略，不等同于启动配置 cache.proxy_slice_cache_enabled。slice cache 启用只能在启动时配置。

RTMP

Key	类型	默认值	说明
`rtmp.custom_publish_host`	string	`""`	返回给推流端的自定义发布 host
`rtmp.ts_disguised_as_png`	bool	`false`	是否把 TS 片段伪装为 PNG 路径或响应形式

Email

Key	类型	默认值	说明
`email.whitelist_enabled`	bool	`false`	是否启用邮箱白名单
`email.whitelist`	string	`""`	邮箱白名单内容，逗号分隔域名或邮箱

email.whitelist_enabled=true 且 email.whitelist 为空时不会拒绝任何邮箱；只有白名单非空时才会按域名或邮箱匹配。

SMTP 主机、密码、发件人等启动配置仍在邮件与 OAuth2。

WebRTC

Key	类型	默认值	说明
`webrtc.external_ice_servers`	JSON/字符串结构	Google STUN 两项	返回给原生客户端的外部 ICE servers

默认值是：

[
  { "urls": ["stun:stun.l.google.com:19302"] },
  { "urls": ["stun:stun1.l.google.com:19302"] }
]

内置 STUN 监听端口、host、candidate 过滤等启动配置见 WebRTC 配置。

Chat

Key	类型	默认值	校验	说明
`chat.max_messages_per_room`	u64	`500`	`<=100000`，`0` 表示不限	每个房间保留的聊天消息数量上限
`chat.message_retention_days`	i64 天	`90`	`1..=3650`	聊天消息最长保留天数

CORS

Key	类型	默认值	说明
`cors.allowed_origins`	JSON/字符串结构	`[]`	代理相关 CORS 允许 origin

主服务启动 CORS 配置是 server.cors_allowed_origins。runtime CORS 适合运行时调整代理相关策略，具体使用范围以当前 API 行为为准。

典型操作

synctv settings update user --set enable_password_signup=true

synctv settings update user --set password_signup_need_review=true

synctv settings update server --set max_rooms_per_user=20

synctv settings update chat --set max_messages_per_room=1000 --set message_retention_days=180

synctv settings update oauth2 --set providers='{
  "github": {
    "type": "github",
    "enable_signup": true,
    "signup_need_review": false,
    "config": {
      "client_id": "github-client-id",
      "client_secret": "github-client-secret",
      "redirect_url": "https://app.example.com/oauth2/callback"
    }
  }
}'

修改前检查

先确认是否应热更新

如果是端口、secret、数据库、Redis、TLS 或 cache 启用，应该改启动配置而不是 runtime settings。

先查当前值

修改前运行 synctv settings get <key>，记录当前值，方便回滚。

关注多副本同步

多副本依赖 PostgreSQL 通知同步，修改后观察所有副本日志和行为。

保留变更原因

对注册、房间创建、代理和权限默认值这类策略变更记录 reason。