配置总索引

静态配置字段索引列出源码默认值；实际生效值还会叠加配置文件、环境变量、CLI 覆盖、路径解析和时区 fallback。

完整 YAML 模板见 完整配置示例。当前二进制的生效配置可用 synctv config show --output yaml 查看，secret 会打码。

OAuth2 provider 实例属于 Runtime settings。远程 media provider instance 通过管理 API/CLI 持久化，不属于静态配置文件。

配置决策

绝大多数字段可以保留默认值。生产上线优先处理 secret、数据库、入口、安全边界和备份。

配置	什么时候要改	常见错误	改动后	生产建议
jwt.secret	任何生产部署	使用 change-me-in-production 或提交到 Git	需要重启；旧 token 可能失效	用 Secret Manager 或 secret file 注入
security.opaque_server_setup_secret	启用本地密码/OPAQUE 登录	每次部署随机生成	需要重启；随意变更会影响密码记录	生成一次，长期备份
security.credential_encryption_key	保存加密 Provider 凭据	不是 64 个十六进制字符，或丢失 key	需要重启；丢失会影响已加密凭据读取	openssl rand -hex 32，加密备份
database.url / 拆分字段	连接生产 PostgreSQL	指向本机开发库或连接数过大	需要重启	PostgreSQL 必须持久化并备份
redis.url / 拆分字段	生产、OAuth2、多副本、限流、L2 缓存	多副本使用不同 Redis 或 key prefix 冲突	需要重启	生产推荐，多副本必需
server.cors_allowed_origins	Web 前端和 API 不同 origin	填 * 或带 path	需要重启	只填真实 origin，例如 https://app.example.com
server.trusted_proxies	前面有反向代理或 Ingress	信任全网，导致客户端 IP 可伪造	需要重启	只填你控制的代理网段
management.*	需要 CLI 或运维控制面	TCP 暴露公网且无 token	需要重启	优先 Unix socket；TCP 必须鉴权
metrics.*	接入 Prometheus 或告警	/metrics 裸露公网	需要重启	启用鉴权和网络隔离
webauthn.*	启用 passkey	rp_origin 与真实访问 origin 不一致	需要重启	只使用 HTTPS 生产 origin
email.*	邮箱验证、找回密码、邮箱 MFA、通知	TLS/端口/from_email 不匹配	需要重启	用 synctv settings test-email 验证
cluster.* / cluster.secret	多副本集群	开了集群但没 Redis 或 cluster secret	需要重启	所有副本共享 PostgreSQL、Redis、secret
livestream.*	RTMP/FLV/HLS 直播	多副本 HLS 存储模型不一致	需要重启	高流量使用共享文件系统或 OSS
proxy_slice_cache.*	需要代理 Range slice 缓存	误以为会缓存完整文件	需要重启	挂载容量足够的目录，只缓存 Range slice

最短验证闭环：

synctv config validate
synctv config show --output yaml
curl -fsS http://localhost:8080/health/ready

单机生产重点字段

生产 Compose 优先维护 .env.postgres、.env.redis 和 .env.synctv，不需要手写完整 YAML。上线前确认：

目标	Compose/env 重点	对应配置字段
初始管理员	SYNCTV_BOOTSTRAP_ROOT_PASSWORD	bootstrap.root_password
token 签名	SYNCTV_JWT_SECRET	jwt.secret
OPAQUE 密码登录	SYNCTV_SECURITY_OPAQUE_SERVER_SETUP_SECRET	security.opaque_server_setup_secret
Provider 凭据加密	SYNCTV_SECURITY_CREDENTIAL_ENCRYPTION_KEY	security.credential_encryption_key
Web 前端跨域	SYNCTV_SERVER_CORS_ALLOWED_ORIGINS='["https://app.example.com"]'	server.cors_allowed_origins
PostgreSQL	.env.postgres 和 Compose 数据卷	database.*
Redis	.env.redis、Compose Redis 服务和 key prefix	redis.*
运行时文件	Compose /data volume	data_dir

裸机、Kubernetes、secret file 或自定义配置文件使用下面的字段索引。

顶层配置

字段	类型	默认值	详细说明
server	对象	见下方	服务监听与运行时路径
time	对象	见下方	服务监听与运行时路径
public_ids	对象	见下方	公开 ID
security	对象	见下方	安全与密钥
data_dir	字符串路径	平台相关	服务监听与运行时路径
metrics	对象	见下方	Metrics 监控
management	对象	见下方	服务监听与运行时路径
database	对象	见下方	数据库与 Redis
redis	对象	见下方	数据库与 Redis
jwt	对象	见下方	安全与密钥
logging	对象	见下方	服务监听与运行时路径
livestream	对象	见下方	直播配置
chat	对象	见下方	聊天
webauthn	对象	见下方	WebAuthn 配置
email	对象	见下方	邮件与 OAuth2
media_providers	对象	见下方	媒体 Provider
webrtc	对象	见下方	WebRTC 配置
connection_limits	对象	见下方	限流与连接限制
bootstrap	对象	见下方	初始化 root 用户
cluster	对象	见下方	集群配置
password_complexity	对象	见下方	安全与密钥
buffer_sizes	对象	见下方	内部缓冲区
cache	对象	见下方	业务缓存
proxy_slice_cache	对象	见下方	Proxy slice cache
messaging_rate_limits	对象	见下方	限流与连接限制
request_rate_limits	对象	见下方	限流与连接限制
request_rate_limits	对象	见下方	限流与连接限制

server

字段	类型/可选值	默认值	说明
server.host	IP/监听地址	0.0.0.0	主 API 监听地址
server.port	端口	8080	HTTP REST、公开 gRPC、健康检查端口
server.enable_reflection	布尔值	false	是否开启公开 gRPC reflection
server.trusted_proxies	字符串数组	[]	可信反向代理 IP/CIDR
server.cors_allowed_origins	字符串数组	[]	允许跨域访问的前端 origin
server.advertise_host	字符串	""	其他节点连接本节点时使用的地址
server.shutdown_drain_timeout_seconds	秒数	30	关闭时等待连接 drain 的时间
server.grpc_max_message_size_bytes	字节数	16777216	gRPC 消息最大大小
server.grpc_compression_enabled	布尔值	true	是否允许 gRPC gzip 压缩协商

time、public_ids、security

字段	类型/可选值	默认值	说明
time.timezone	IANA 时区名	""	人类可读时间显示和本地时间解析时区
public_ids.sqids	对象或空	null	是否启用 sqids 公开 ID
public_ids.sqids.alphabet	字符串或空	null	sqids alphabet
public_ids.sqids.min_length	整数	12	sqids 最小长度
security.credential_encryption_key	64 个十六进制字符	""	Provider 凭据加密 key
security.opaque_server_setup_secret	secret 字符串	""	OPAQUE 密码认证服务端 setup secret
security.ssrf.enabled	布尔值	false	是否启用全局 SSRF 出站防护
security.ssrf.allow_private_network_targets	布尔值	false	是否允许服务端出站访问 private/loopback/link-local/reserved/metadata 目标
security.ssrf.allowed_hosts	字符串数组	[]	全局 SSRF 策略额外允许的主机名
security.ssrf.allowed_ip_ranges	IP/CIDR 字符串数组	[]	全局 SSRF 策略额外允许的 IP 或网段

metrics

字段	类型/可选值	默认值	说明
metrics.enabled	布尔值	false	是否启动 metrics 监听器
metrics.host	IP/监听地址	0.0.0.0	metrics 监听地址
metrics.port	端口	9090	metrics 监听端口
metrics.tls.enabled	布尔值	false	metrics 是否启用 TLS
metrics.tls.cert_path	文件路径	""	metrics TLS 证书
metrics.tls.key_path	文件路径	""	metrics TLS 私钥
metrics.auth.mode	bearer_token、basic、kubernetes	bearer_token	metrics 鉴权模式
metrics.auth.bearer_token	secret 字符串	""	bearer token 模式 token
metrics.auth.basic_username	字符串	""	basic 模式用户名
metrics.auth.basic_password	secret 字符串	""	basic 模式密码
metrics.auth.kubernetes.audience	字符串	""	Kubernetes TokenReview audience
metrics.auth.kubernetes.authentication_cache_ttl_seconds	秒数	60	TokenReview 结果缓存
metrics.auth.kubernetes.authorization_cache_ttl_seconds	秒数	60	SubjectAccessReview 结果缓存

management

字段	类型/可选值	默认值	说明
management.enabled	布尔值	true	是否启用管理端点
management.transport	unix 或 tcp	Unix 平台为 unix，其他平台为 tcp	管理端点传输方式
management.port	端口	50052	TCP management 端口
management.unix_socket_path	文件路径	平台相关	Unix socket 路径
management.auth_token	secret 字符串	""	TCP management bearer token
management.enable_reflection	布尔值	false	管理 gRPC reflection

database

字段	类型/可选值	默认值	说明
database.url	PostgreSQL URL	postgresql://synctv:synctv@localhost:5432/synctv	完整数据库连接串
database.host	字符串	""	拆分配置的数据库主机
database.port	端口	0	拆分配置的数据库端口
database.username	字符串	""	数据库用户
database.password	secret 字符串	""	数据库密码
database.name	字符串	""	数据库名
database.max_connections	整数	20	最大连接数
database.min_connections	整数	5	最小空闲连接数
database.connect_timeout_seconds	秒数	10	连接超时
database.idle_timeout_seconds	秒数	600	空闲连接超时
database.max_lifetime_seconds	秒数	1800	单个连接最大生命周期

redis

字段	类型/可选值	默认值	说明
redis.url	Redis URL	""	完整 Redis 连接串
redis.host	字符串	""	拆分配置的 Redis 主机
redis.port	端口	0	拆分配置的 Redis 端口
redis.username	字符串	""	Redis 用户
redis.password	secret 字符串	""	Redis 密码
redis.database	整数	0	Redis database index
redis.connect_timeout_seconds	秒数	5	Redis 连接超时
redis.response_timeout_seconds	秒数	5	Redis 命令响应超时
redis.pipeline_buffer_size	整数	512	Redis connection manager pipeline buffer 大小
redis.key_prefix	字符串	synctv:	Redis key 前缀
redis.deployment_mode	standalone 或 sentinel	standalone	Redis 部署模式
redis.sentinel_master_name	字符串或空	null	Sentinel master 名称
redis.sentinel_addresses	字符串数组	[]	Sentinel 节点地址

jwt 和 logging

字段	类型/可选值	默认值	说明
jwt.secret	secret 字符串	change-me-in-production	token 签名密钥
jwt.access_token_duration_hours	小时数	1	access token 有效期
jwt.refresh_token_duration_days	天数	30	refresh token 有效期
jwt.guest_token_duration_hours	小时数	4	guest token 有效期
jwt.clock_skew_leeway_secs	秒数	60	token 时间误差容忍
logging.level	error、warn、info、debug、trace	info	日志级别
logging.format	pretty 或 json	pretty	日志格式
logging.filter	tracing filter 字符串或空	null	高级模块级日志过滤
logging.backtrace	布尔值	false	是否输出 backtrace
logging.file_path	文件路径或空	null	日志文件路径

livestream

字段	类型/可选值	默认值	说明
livestream.rtmp_port	端口	1935	RTMP 推流端口
livestream.public_rtmp_host	字符串	""	返回给推流端的公网 RTMP host
livestream.gop_cache_size	整数	2	每路流 GOP 缓存数量
livestream.stream_timeout_seconds	秒数	300	拉流空闲超时
livestream.cleanup_check_interval_seconds	秒数	60	清理检查间隔
livestream.pull_max_retries	整数	10	拉流最大重试次数
livestream.pull_initial_backoff_ms	毫秒	1000	拉流初始退避
livestream.pull_max_backoff_ms	毫秒	30000	拉流最大退避
livestream.max_flv_tag_size_bytes	字节数	10485760	最大 FLV tag 大小
livestream.gop_cache_max_memory_mb	MB	100	GOP 缓存最大内存
livestream.hls_memory_max_mb	MB	0	内存 HLS 存储上限，0 表示内置默认
livestream.hls_storage_backend	memory、file、shared_file、oss	memory	HLS 分片存储后端
livestream.hls_storage_path	路径	""	file / shared_file 后端 HLS 文件存储路径
livestream.hls_oss.endpoint	字符串	""	oss 后端 S3/OSS endpoint，启用 oss 时必填
livestream.hls_oss.access_key_id	secret 字符串	""	oss 后端 access key ID，启用 oss 时必填
livestream.hls_oss.secret_access_key	secret 字符串	""	oss 后端 secret access key，启用 oss 时必填
livestream.hls_oss.bucket	字符串	""	oss 后端 bucket，启用 oss 时必填
livestream.hls_oss.region	字符串或空	null	oss 后端 region
livestream.hls_oss.base_path	字符串	hls/	oss 后端 bucket 内对象前缀
livestream.flv_max_connection_duration_seconds	秒数	86400	HTTP-FLV 最大连接时长
livestream.flv_write_timeout_seconds	秒数	30	HTTP-FLV 写超时

file_storage

字段	类型/可选值	默认值	说明
file_storage.default_backend	backend 名称	disabled	各业务默认使用的后端
file_storage.chat_attachments_backend	backend 名称或空	""	聊天附件后端；空值继承 default_backend
file_storage.user_avatars_backend	backend 名称或空	""	用户头像后端；空值继承 default_backend
file_storage.media_covers_backend	backend 名称或空	""	媒体封面后端；空值继承 default_backend
file_storage.room_covers_backend	backend 名称或空	""	房间封面后端；空值继承 default_backend
file_storage.playlist_covers_backend	backend 名称或空	""	播放列表封面后端；空值继承 default_backend
file_storage.upload_token_secret	secret 字符串	""	文件上传/读取 token 签名密钥；空值在启动时由 jwt.secret 派生
file_storage.unreferenced_object_retention_seconds	秒数	86400	未被业务引用的已上传对象清理宽限期；0 表示关闭孤儿对象清理
file_storage.backends.<name>.type	disabled、database 或 s3	disabled	已注册后端实现类型
file_storage.backends.<name>.database.compression	none、lz4 或 zstd	zstd	type: "database" 后端写入 PostgreSQL 永久 file_blob_parts 分段的压缩算法
file_storage.backends.<name>.database.compression_min_size_bytes	字节数	4096	原始 payload 达到该大小后才尝试压缩
file_storage.backends.<name>.database.compression_min_savings_percent	0 到 100	10	压缩节省比例达到该百分比才存储压缩结果
file_storage.backends.<name>.s3.*	S3 配置	S3 默认字段	type: "s3" 后端的 S3-compatible 配置；public_base_url 必填，用于上传或 ownership proof 通过后的可读文件 URL

上传会话使用服务端分片计划：客户端先用空 parts 请求 FileUploadPlan，按计划计算每片 SHA-256，再提交 FileUploadManifestPart[]。SyncTV 根据 canonical manifest 计算 content_manifest_sha256，用它命中秒传对象和未完成断点续传会话。Database 后端持久化固定 file_blob_parts 分段，并直接从分段服务 HTTP Range 请求，只解压覆盖请求区间的分段。S3 后端使用原生 multipart upload 和预签名 part URL，part URL 签入 x-amz-checksum-sha256，完成时用已记录分片 manifest 校验对象身份，服务端无需从 S3 读回 GB 级对象。重复对象返回 upload_required=false 和 ownership proof challenge；可读 URL 会在 proof 通过并写入业务引用后签发。

文件存储配置示例

关闭文件存储：

file_storage:
  default_backend: "disabled"
  backends: {}

使用 PostgreSQL 存储文件二进制：

file_storage:
  default_backend: "database"
  chat_attachments_backend: "database"
  user_avatars_backend: "database"
  media_covers_backend: "database"
  room_covers_backend: "database"
  playlist_covers_backend: "database"
  upload_token_secret_file: "/run/secrets/file_upload_token_secret"
  backends:
    database:
      type: "database"
      database:
        compression: "zstd"

使用 S3-compatible 对象存储：

file_storage:
  default_backend: "s3_public"
  chat_attachments_backend: "s3_public"
  user_avatars_backend: "s3_public"
  media_covers_backend: "s3_public"
  room_covers_backend: "s3_public"
  playlist_covers_backend: "s3_public"
  upload_token_secret_file: "/run/secrets/file_upload_token_secret"
  backends:
    s3_public:
      type: "s3"
      s3:
        endpoint: "https://s3.example.com"
        access_key_id_file: "/run/secrets/file_storage_s3_access_key_id"
        secret_access_key_file: "/run/secrets/file_storage_s3_secret_access_key"
        bucket: "synctv-files"
        region: "auto"
        base_path: "files/"
        public_base_url: "https://cdn.example.com/files"
        upload_expires_seconds: 900

webauthn 和 email

字段	类型/可选值	默认值	说明
webauthn.enabled	布尔值	false	是否启用 passkey
webauthn.rp_id	域名	""	WebAuthn relying party ID
webauthn.rp_origin	origin	""	WebAuthn 主 origin
webauthn.rp_name	字符串	SyncTV	认证器显示名称
webauthn.allowed_origins	origin 数组	[]	额外允许 origin
webauthn.allow_subdomains	布尔值	false	是否允许子域
webauthn.allow_any_port	布尔值	false	是否忽略端口
webauthn.timeout_seconds	秒数	300	challenge 超时
email.smtp_host	字符串	""	SMTP 主机
email.smtp_port	端口	587	SMTP 端口
email.smtp_username	字符串	""	SMTP 用户名
email.smtp_password	secret 字符串	""	SMTP 密码
email.from_email	邮箱	""	发件邮箱
email.from_name	字符串	SyncTV	发件人显示名
email.use_tls	布尔值	true	是否使用 TLS

media_providers 和 webrtc

字段	类型/可选值	默认值	说明
media_providers.alist.request_timeout_seconds	秒数	30	本地 Alist provider 请求总超时
media_providers.alist.connect_timeout_seconds	秒数	10	本地 Alist provider 建连超时
media_providers.bilibili.request_timeout_seconds	秒数	30	本地 Bilibili provider 请求总超时
media_providers.bilibili.connect_timeout_seconds	秒数	10	本地 Bilibili provider 建连超时
media_providers.emby.request_timeout_seconds	秒数	30	本地 Emby/Jellyfin provider 请求总超时
media_providers.emby.connect_timeout_seconds	秒数	10	本地 Emby/Jellyfin provider 建连超时
webrtc.mode	signaling_only 或 peer_to_peer	peer_to_peer	WebRTC 工作模式
webrtc.enable_builtin_stun	布尔值	true	是否启用内置 STUN
webrtc.stun_port	端口	3478	STUN 端口
webrtc.stun_host	IP/监听地址	0.0.0.0	STUN 监听地址
webrtc.stun_external_addr	字符串	""	对客户端公布的 STUN 外部地址
webrtc.filter_private_ice_candidates	布尔值	true	是否过滤私网 ICE candidate

connection_limits、bootstrap、cluster

字段	类型/可选值	默认值	说明
connection_limits.max_per_user	整数	20	每用户最大连接数
connection_limits.max_per_room	整数	2000	每房间最大连接数
connection_limits.max_total	整数	100000	全服务最大连接数
connection_limits.idle_timeout_seconds	秒数	300	空闲连接超时
connection_limits.max_duration_seconds	秒数	86400	单连接最大时长
connection_limits.ws_message_rate_limit_per_second	次/秒	50	每连接 WebSocket 消息速率
bootstrap.create_root_user	布尔值	false	是否自动创建初始 root
bootstrap.root_username	字符串	root	初始 root 用户名
bootstrap.root_password	secret 字符串	""	初始 root 密码
cluster.enabled	布尔值	false	是否启用集群模式
cluster.secret	secret 字符串	""	集群内部 gRPC 认证密钥
cluster.secret_file	文件路径或空	""	读取集群内部 gRPC 认证密钥的文件
cluster.critical_channel_capacity	整数	10000	高优先级集群事件队列容量
cluster.publish_channel_capacity	整数	100000	普通集群发布队列容量
cluster.discovery_mode	redis、static、k8s_dns	redis	节点发现模式
cluster.leader_election_mode	redis 或 k8s_lease	redis	leader election 模式
cluster.peers	字符串数组	[]	静态 peer 地址
cluster.catchup_window_secs	秒数	300	Redis Stream catch-up 回放窗口
cluster.stream_max_length	整数	100000	Redis Stream 近似最大长度

password_complexity、buffer_sizes、cache

字段	类型/可选值	默认值	说明
password_complexity.min_length	整数	8	密码最小长度
password_complexity.require_uppercase	布尔值	true	是否要求大写字母
password_complexity.require_lowercase	布尔值	true	是否要求小写字母
password_complexity.require_digit	布尔值	true	是否要求数字
password_complexity.require_special	布尔值	false	是否要求特殊字符
password_complexity.max_repeated_chars	整数	3	最大连续重复字符数，0 表示关闭
password_complexity.zxcvbn_enabled	布尔值	false	是否启用 zxcvbn 熵估算评分
password_complexity.zxcvbn_min_score	整数 0-4	3	启用 zxcvbn 时的最低分数
buffer_sizes.websocket_outbound	整数	256	每连接 WebSocket 出站队列
buffer_sizes.audit_buffer	整数	10000	审计事件缓冲容量
cache.l1_capacity	整数	5000	L1 内存缓存容量
cache.l1_ttl_seconds	秒数	300	L1 内存缓存 TTL
cache.l2_ttl_seconds	秒数	300	Redis L2 缓存 TTL
cache.username_cache_capacity	整数	10000	用户名缓存容量
cache.username_cache_ttl_seconds	秒数	3600	用户名缓存 TTL
cache.permission_cache_capacity	整数	20000	权限缓存容量
cache.permission_cache_ttl_seconds	秒数	300	权限缓存 TTL
proxy_slice_cache.enabled	布尔值	true	是否启用代理 slice cache
proxy_slice_cache.slice_size_bytes	整数	2097152	单个 Range 分片大小
proxy_slice_cache.max_cache_size_bytes	整数	536870912	slice cache 最大总容量
proxy_slice_cache.segment_ttl_seconds	秒数	300	分片新鲜期
proxy_slice_cache.stale_max_age_seconds	秒数	60	过期分片可被短暂兜底使用的时间
proxy_slice_cache.stale_while_revalidate	布尔值	true	过期命中时是否后台刷新
proxy_slice_cache.file_backend_enabled	布尔值	false	是否启用文件后端
proxy_slice_cache.file_cache_dir	路径	""	slice cache 文件目录
proxy_slice_cache.eviction_interval_seconds	秒数	60	后台驱逐检查间隔
proxy_slice_cache.watermark_ratio	浮点数	0.875	驱逐后的目标水位比例

messaging_rate_limits

字段	类型/可选值	默认值	说明
messaging_rate_limits.chat_per_second	整数	10	聊天消息窗口内最大数量
messaging_rate_limits.window_seconds	秒数	1	聊天限流窗口

request_rate_limits

字段	类型/可选值	默认值	说明
request_rate_limits.auth_max_requests	整数	5	请求认证接口窗口内最大请求数
request_rate_limits.auth_window_seconds	秒数	60	请求认证接口限流窗口
request_rate_limits.write_max_requests	整数	120	请求写接口窗口内最大请求数
request_rate_limits.write_window_seconds	秒数	60	请求写接口限流窗口
request_rate_limits.read_max_requests	整数	600	请求读接口窗口内最大请求数
request_rate_limits.read_window_seconds	秒数	60	请求读接口限流窗口
request_rate_limits.media_max_requests	整数	120	请求媒体接口窗口内最大请求数
request_rate_limits.media_window_seconds	秒数	60	请求媒体接口限流窗口
request_rate_limits.admin_max_requests	整数	180	请求管理接口窗口内最大请求数
request_rate_limits.admin_window_seconds	秒数	60	请求管理接口限流窗口
request_rate_limits.streaming_max_requests	整数	1200	streaming 接口窗口内最大请求数
request_rate_limits.streaming_window_seconds	秒数	60	streaming 接口限流窗口
request_rate_limits.websocket_max_requests	整数	60	WebSocket 建连窗口内最大请求数
request_rate_limits.websocket_window_seconds	秒数	60	WebSocket 建连限流窗口