Screego 1.12.6 配置参数详解

以 screego.config.example 20 个配置项为依据详解 Screego 1.12.6 配置：加载机制与优先级、逐项语义、八组启动强校验实测 FTL 输出、Prometheus/CORS/debug 日志运行时行为与排障速查，全部实测照抄

ScreegoScreegoWebRTC屏幕共享2026/10/27

Screego 1.12.6 配置参数详解

目标：以 Screego 1.12.6 官方 screego.config.example 的 20 个配置项为权威依据，讲清配置加载机制（查找目录、优先级）、逐项参数语义、启动强校验行为与运行时实测表现。全部校验错误行与运行日志均在 Ubuntu 22.04 实测环境中逐行采集照抄，查询日期 2026-10-27。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS 测试机
  • Screego 版本：1.12.6（screego 无参数启动显示 VERSION: 1.12.6; screego/server@4ae5f443190be0ffa192a950531cf0aef646162b）
  • 二进制来源：官方 screego/server:1.12.6 软件包内 /screego，sha256 1cc7216d7f8b801067a1fd20fb86670e161e906cf8eb8a785499033ca69e3f11
  • 测试目录：/tmp/c1test/（内含被测二进制与多份 screego.config*，每次启动前重写）
  • 对照环境：《Ubuntu 22.04 安装 Screego 1.12.6 指南》的 systemd 部署与《Screego 1.12.6 Docker Compose 部署指南》的编排部署

二、配置加载机制

Screego 的配置有三个入口：配置文件、环境变量、命令行（仅 serve/hash 两个子命令，serve 不接受任何配置类 flag）。生效优先级：环境变量 > 配置文件；同名键先加载者胜。

2.1 配置文件查找目录

源码（config/config.go）定义的查找顺序：

  1. 可执行文件所在目录：screego.config.development.local → screego.config.development → screego.config.local → screego.config
  2. $HOME/.config/screego/server.config
  3. /etc/screego/server.config

关键点：前四个文件全部相对「可执行文件所在目录」查找，与当前工作目录无关。 实测：把二进制放在 /tmp/c1test/ 运行，向该目录写 screego.config 有效；目录里没有任何配置文件时立即启动失败：

2026-10-27T00:17:36Z INF SCREEGO_SECRET unset, user logins will be invalidated on restart
2026-10-27T00:17:36Z FTL SCREEGO_EXTERNAL_IP or SCREEGO_TURN_EXTERNAL_IP must be set

开启 SCREEGO_LOG_LEVEL=debug 后，加载了哪个文件会在日志中逐个列出：

2026-10-27T00:18:00Z DBG Loading file /tmp/c1test/screego.config

2.2 优先级实测

环境变量 > 配置文件：配置文件写 SCREEGO_SERVER_ADDRESS=0.0.0.0:8195，同时环境变量设 SCREEGO_SERVER_ADDRESS=0.0.0.0:8194 启动：

2026-10-27T00:20:52Z INF Start HTTP addr=0.0.0.0:8194

8194 端口 /health 返回 200，8195 无监听——环境变量胜出。这是编排部署（B2 篇全部配置走环境变量）能够覆盖配置文件的原因。

screego.config.local > screego.config：screego.config 写 SCREEGO_SERVER_ADDRESS=0.0.0.0:8195，screego.config.local 写 SCREEGO_SERVER_ADDRESS=0.0.0.0:8196，启动日志与探活结果：

2026-10-27T00:20:26Z INF Start HTTP addr=0.0.0.0:8196
{"status":"up","clients":0}

8196 生效。据此可以在保留默认 screego.config 的同时，用 .local 文件做本机差异化覆盖，避免改动版本管理的模板文件。

2.3 配置文件的语法

配置文件是 dotenv 格式（KEY=value，每行一个），键名与环境变量完全一致（SCREEGO_ 前缀 + 全大写，见下表），不是 YAML/TOML。

三、配置项总表（20 键）

以下 20 个键与官方 screego.config.example 完全一致，默认值取自源码 config.Config 结构：

#配置项默认值说明
1SCREEGO_EXTERNAL_IP（空）服务器对外 IP，写入 ICE 候选。必填（与 9 二选一）。多地址用逗号分隔（IPv4+IPv6）；无静态 IP 可用 dns:app.example.com 或 dns:app.example.com@9.9.9.9:53 动态解析
2SCREEGO_SECRET（随机）会话 Cookie 签名密钥。不设置则每次启动随机生成，重启后所有已登录会话失效；生产必须固定（openssl rand -hex 16）
3SCREEGO_SERVER_TLSfalse是否由 Screego 直接终止 HTTP TLS。开启后必须配 4、5 两项；反代终止 TLS 时保持 false
4SCREEGO_TLS_CERT_FILE（空）TLS 证书文件路径（仅 3 开启时需要）
5SCREEGO_TLS_KEY_FILE（空）TLS 私钥文件路径（仅 3 开启时需要）
6SCREEGO_SERVER_ADDRESS:5050HTTP 监听地址，格式 host:port 或 unix:/path/socket
7SCREEGO_TURN_ADDRESS:3478内置 TURN/STUN 监听地址
8SCREEGO_TURN_PORT_RANGE（空）TURN 中继端口段，格式 min:max（注意用冒号）。空=不限制；少于 40 个端口启动警告
9SCREEGO_TURN_EXTERNAL_IP（空）使用外部 TURN 时的地址（支持逗号多地址与 dns: 前缀）。设置后内置 TURN 不启动，与 1 互斥
10SCREEGO_TURN_EXTERNAL_PORT3478外部 TURN 服务监听端口
11SCREEGO_TURN_EXTERNAL_SECRET（空）外部 TURN 认证密钥（仅使用外部 TURN 时必填）
12SCREEGO_TURN_DENY_PEERS0.0.0.0/8,127.0.0.1/8,::/128,::1/128,fe80::/10TURN 中继禁止转发的对端 CIDR 黑名单，防止把 TURN 当跳板访问内网
13SCREEGO_TRUST_PROXY_HEADERSfalse是否信任反代头。TURN 认证按来源 IP 白名单，部署在反代之后必须开启并让反代设置 X-Real-Ip，否则所有请求的来源都是代理 IP
14SCREEGO_AUTH_MODEturn登录要求：all=所有操作都要登录；turn=房主登录、加入者可匿名（默认）；none=永不要求登录
15SCREEGO_CORS_ALLOWED_ORIGINS（空）允许跨域访问的 Origin 正则列表（逗号分隔），作用于 HTTP + WebSocket。见 5.3 实测语义
16SCREEGO_USERS_FILE（空）用户凭据文件路径，格式 user:bcrypt_hash，用 screego hash --name ... --pass ... 生成。空=没有本地用户（匿名模式可用）
17SCREEGO_SESSION_TIMEOUT_SECONDS0登录会话有效期（秒），写入 Cookie 的 MaxAge。0=浏览器会话结束即失效
18SCREEGO_CLOSE_ROOM_WHEN_OWNER_LEAVEStrue房主离开是否关闭房间的创建页默认勾选值
19SCREEGO_LOG_LEVELinfo日志级别：debug/info/warn/error。debug 会输出每条 HTTP 访问记录与配置加载过程
20SCREEGO_PROMETHEUSfalse是否在 /metrics 暴露 Prometheus 指标（需 Basic Auth，见 5.2 实测）

已废弃项：SCREEGO_TURN_STRICT_AUTH 在 1.12.6 中已被移除，设置后仅得到警告 The setting SCREEGO_TURN_STRICT_AUTH has been removed.，不产生任何效果。

四、启动强校验项（实测 FTL 集）

以下场景全部在测试机实测，均为启动即失败（FTL），不产生任何监听。错误行逐字照抄（已去 ANSI 颜色码）：

4.1 未配置对外 IP（最常见的首启失败）

2026-10-27T00:17:36Z FTL SCREEGO_EXTERNAL_IP or SCREEGO_TURN_EXTERNAL_IP must be set

4.2 内置/外部 TURN 同时启用

2026-10-27T00:17:36Z FTL SCREEGO_EXTERNAL_IP and SCREEGO_TURN_EXTERNAL_IP must not be both set

（同场景还会追加 4.3 的错误行——外部 TURN 必须配密钥。）

4.3 使用外部 TURN 但未设密钥

2026-10-27T00:17:36Z FTL SCREEGO_TURN_EXTERNAL_SECRET must be set if external TURN server is used

4.4 AUTH_MODE 非法值

2026-10-27T00:17:36Z FTL invalid SCREEGO_AUTH_MODE: invalid

合法值仅 turn、all、none 三种。

4.5 开启 TLS 但未配证书/私钥

2026-10-27T00:17:36Z FTL SCREEGO_TLS_CERT_FILE must be set if TLS is enabled
2026-10-27T00:17:36Z FTL SCREEGO_TLS_KEY_FILE must be set if TLS is enabled

4.6 TURN 端口段 min 大于 max

2026-10-27T00:17:36Z FTL invalid SCREEGO_TURN_PORT_RANGE: min port (100) is higher than max port (50)

4.7 TURN 端口段格式错误

2026-10-27T00:17:36Z FTL invalid SCREEGO_TURN_PORT_RANGE: must include one colon

（该值用冒号分隔；而编排文件的端口映射用短横线，两处写法不同，容易混淆。）

4.8 端口段少于 40 个（警告，不阻止启动）

2026-10-27T00:17:36Z WRN Less than 40 ports are available for turn. When using multiple TURN connections this may not be enough

多路并发共享时中继端口可能不够用，建议端口段 ≥ 40。

校验顺序说明：FTL 错误在监听创建之前输出；一次启动可能同时报多条 FTL（如 4.2 连带 4.3），日志中的 Deny turn peers within [...] 行属于正常信息输出，不代表启动成功，判定以是否出现 Start HTTP addr=... 为准。

五、运行时行为实测

5.1 SCREEGO_LOG_LEVEL=debug

debug 级别下每条 HTTP 请求都会输出访问记录（默认 info 级别完全静默）：

2026-10-27T00:19:45Z DBG HTTP duration=152.695529ms host=172.17.0.4:8199 ip=172.17.0.1:46642 path=/metrics size=9426 status=200
2026-10-27T00:19:45Z DBG HTTP duration="46.871µs" host=172.17.0.4:8199 ip=172.17.0.1:46646 path=/config size=136 status=200
2026-10-27T00:19:46Z DBG HTTP duration=0s host=172.17.0.4:8199 ip=172.17.0.1:46664 path=/notexist size=0 status=404

5.2 SCREEGO_PROMETHEUS 与 /metrics

开启后启动日志出现 INF Prometheus enabled，/metrics 需要 Basic Auth（凭据来自 SCREEGO_USERS_FILE 中的用户）：

无认证与错误口令均返回 401：

HTTP/1.1 401 Unauthorized
Www-Authenticate: Basic realm="screego"
Content-Length: 14
Content-Type: text/plain; charset=utf-8

正确凭据返回标准 exposition 格式（Go 运行时指标 + Screego 房间指标）：

# HELP go_gc_duration_seconds A summary of the wall-time pause (stop-the-world) duration in garbage collection cycles.
# TYPE go_gc_duration_seconds summary
go_gc_duration_seconds{quantile="0"} 0

两个易踩的怪癖（实测）：

  1. SCREEGO_PROMETHEUS=false（默认）时访问 /metrics 不是 404，而是 status=200 size=0 的空响应——因为 Screego 对所有未注册路径统一返回 200 空体。做存活探测不要用 /metrics，用 /health。
  2. 未知路径（如 /notexist）线上返回 200 空体，但 debug 日志内部记录 status=404（见 5.1 第三行）——空 200 是 NotFoundHandler 的展示怪癖，不是真的路由成功。

5.3 SCREEGO_CORS_ALLOWED_ORIGINS

携带非白名单 Origin 头请求 /config 的实测响应：

HTTP/1.1 200 OK
Date: Tue, 27 Oct 2026 00:20:23 GMT
Content-Length: 143
Content-Type: text/plain; charset=utf-8

服务端不拦截非白名单来源（状态码仍 200），但响应中不含 Access-Control-Allow-Origin 头——即跨域站点的浏览器脚本无法读取响应。它的作用是控制「哪些第三方网页可以把 Screego 当跨域 API 用」，默认空值即可满足同源站点的正常使用；该值为空时任何带 Origin 的跨域请求都不会被放行读取。

5.4 SCREEGO_AUTH_MODE 三档语义

  • turn（默认）：房主创建房间需要登录，普通加入者可匿名观看/共享；/config 接口回显 "authMode":"turn"（见 B2 篇 6.2 节）。
  • all：一切操作都要求登录，适合内网强管控。
  • none：永不要求登录，任何访客都能建房，仅建议临时演示使用（此时 SCREEGO_USERS_FILE 可不配，启动日志出现 INF Users file not specified）。

5.5 SCREEGO_SESSION_TIMEOUT_SECONDS

该值直接写入登录 Cookie 的 MaxAge（源码 auth/auth.go：session.Options.MaxAge = u.sessionTimeout）。0 表示会话级 Cookie，浏览器关闭后登录态消失；设为 86400 表示登录 24 小时内免重新登录。

5.6 SCREEGO_TURN_DENY_PEERS 与 SCREEGO_TRUST_PROXY_HEADERS

  • SCREEGO_TURN_DENY_PEERS：每次启动都会打印生效的黑名单（默认值见总表第 12 项）。服务器在 NAT 后时，必须保留内网段黑名单，否则外部用户可借 TURN 中继探测内网。
  • SCREEGO_TRUST_PROXY_HEADERS：Screego 的 TURN 认证包含来源 IP 白名单逻辑。部署在 Nginx/Caddy 之后时，Screego 看到的来源永远是代理 IP，必须设为 true 并让反代注入 X-Real-Ip，否则登录与 TURN 授权行为异常（典型表现是《Ubuntu 22.04 安装 Screego 1.12.6 指南》FAQ 中 could not authenticate 类错误在反代场景的变体）。

六、与两种部署形态的对照

同一套配置在两种部署形态下的写法对照（以本文总表键为准）：

配置项systemd 二进制方案（B1）Docker Compose 方案（B2）
载体/opt/screego/screego.config（dotenv 文件）docker-compose.yml 的 environment: 段（同名键去掉值外的引号）
SCREEGO_EXTERNAL_IP=10.89.56.2文件行SCREEGO_EXTERNAL_IP: 10.89.56.2
SCREEGO_TURN_PORT_RANGE=50000:50200文件行（冒号）环境变量用冒号，端口映射用短横线 50000-50200:50000-50200/udp
布尔值 false/true文件行裸值建议加引号：SCREEGO_SERVER_TLS: "false"
修改后生效systemctl restart screegodocker compose up -d（重建服务实例）

两处修改后都要确认日志出现 Start HTTP addr=... 才算生效。

七、排障速查

现象根因处理
启动即退，FTL SCREEGO_EXTERNAL_IP or SCREEGO_TURN_EXTERNAL_IP must be set未配对外 IP补 1 号项；注意它只认「可执行文件目录/两处绝对路径」的配置与环境变量
配置改了不生效环境变量遮蔽文件值；或写错了查找目录按 2.1/2.2 排查：`env
重启后所有用户要重新登录SCREEGO_SECRET 未固定固定 2 号项（B2 篇排障 8.2 有完整实录）
/metrics 返回 200 空体SCREEGO_PROMETHEUS=false开启 20 号项；或改用 /health 探活
TURN 相关握手失败、中继不通端口段过小/防火墙未放行/黑名单过宽检查 8 号项（≥40 端口）、对应 UDP 段放行、12 号项黑名单
外部 TURN 报 must be set if external TURN server is used只配了地址没配密钥补 11 号项；同时确认 1 号项已清空

八、参考链接