服务监听与运行时路径

这些配置决定 SyncTV 监听地址、外部访问方式、运行时文件目录、日志格式和 CLI 管理端点。

`server`

HTTP REST 和公开 gRPC 共用 server.port。

`server.host`

默认值：

server:
  host: "0.0.0.0"

值	含义	场景
`0.0.0.0`	监听所有 IPv4 网卡	Docker、Kubernetes、服务器部署
`127.0.0.1`	只监听本机	本地开发、只允许反向代理访问
`::`	监听所有 IPv6 网卡	IPv6 环境

`server.port`

默认值：

server:
  port: 8080

HTTP REST、公开 gRPC 和健康检查使用这个端口。Helm 会把 HTTP 和 gRPC 暴露成独立 Service，但它们仍指向同一个容器端口。

`server.enable_reflection`

默认值：false。

开启公开 gRPC reflection。默认关闭；本地开发和受控内网调试可以显式开启，公网生产环境应保持关闭。

`server.grpc_max_message_size_bytes`

默认值：16777216，即 16 MiB。

限制 gRPC 请求和响应大小。只有批量操作确实需要时才调高。

`server.grpc_compression_enabled`

默认值：true。

允许主 SyncTV 进程中的 gRPC 客户端和服务端协商 gzip 压缩，包括公开 gRPC、management gRPC、cluster/livestream 内部 gRPC 链路，以及出站远程 media-provider gRPC client。它不强制所有请求压缩。

独立部署的远程 media-provider server 不读取主 SyncTV 配置文件。它的服务端压缩协商使用 PROVIDER_GRPC_COMPRESSION_ENABLED 配置。

`server.trusted_proxies`

默认值：[]。

允许指定哪些反向代理的 X-Forwarded-For / X-Real-IP 可信：

server:
  trusted_proxies:
    - "10.0.0.0/8"
    - "172.16.0.0/12"
    - "192.168.0.0/16"

不要使用 0.0.0.0/0 或 ::/0。不确定时保持空列表，SyncTV 使用 socket peer address。

`server.cors_allowed_origins`

默认值：[]。

允许浏览器跨域访问 API 的前端 origin：

server:
  cors_allowed_origins:
    - "https://app.example.com"

值必须是 origin，只包含协议、域名和可选端口。不要包含路径、query 或 fragment。

环境变量：

SYNCTV_SERVER_CORS_ALLOWED_ORIGINS='["https://app.example.com"]'

`server.advertise_host`

其他节点访问本节点时使用的地址。

场景	值
Kubernetes	Pod IP 或可解析的 Pod DNS
静态多节点	内网 IP 或内部 DNS
单机	留空

留空时，SyncTV 会尝试 POD_IP，再尝试系统 hostname。

`server.shutdown_drain_timeout_seconds`

默认值：30。

关闭时等待已有连接 drain 的时间。Kubernetes rolling update 中，termination grace period 应大于这个值。

`time.timezone`

示例：

time:
  timezone: "Asia/Shanghai"

解析顺序：

time.timezone
SYNCTV_TIME_TIMEZONE
TZ
系统时区
UTC

`data_dir`

data_dir: "/var/lib/synctv"

data_dir 用于 SyncTV 自己写入的本地运行时文件：

management Unix socket
文件日志
HLS 直播分片
proxy slice cache 文件

容器部署通常使用 /data 并挂载 volume。data_dir 不影响 *_file secret 路径。

`logging`

字段	默认值	用途
`logging.level`	`info`	日志级别
`logging.format`	`pretty`	人类可读日志或 JSON
`logging.filter`	`null`	tracing 过滤表达式
`logging.backtrace`	`false`	是否输出 backtrace
`logging.file_path`	`null`	可选文件输出

Kubernetes 或日志采集系统使用 JSON：

logging:
  level: "info"
  format: "json"

相对 logging.file_path 会解析到 data_dir 下。容器中通常输出到 stdout。

`management`

management endpoint 供 synctv CLI 执行受控管理操作，不是客户端业务 API。

字段	默认值	用途
`management.enabled`	`true`	启用管理端点
`management.transport`	Unix-like 默认 Unix，其他平台默认 TCP	传输模式
`management.port`	`50052`	TCP 管理端口
`management.unix_socket_path`	`data_dir` 下的平台相关路径	Unix socket 路径
`management.auth_token`	`""`	TCP management bearer token
`management.enable_reflection`	`false`	management gRPC reflection

TCP management 必须配置强 token，不要暴露公网。Unix socket 路径可以相对 data_dir。