Screego 1.12.6 Docker Compose 部署指南

目标：使用 Docker Compose 编排方式在一台 Ubuntu 服务器上部署 Screego 1.12.6 屏幕共享服务，覆盖用户凭据文件生成、compose 编排文件编写（Web 端口、内置 TURN/STUN 端口与中继端口段、会话密钥）、部署启动、健康检查、STUN 协议实测与排障实录。全部命令与输出均在真实服务器环境中逐行实测照抄，查询日期 2026-10-27。

一、环境信息

操作系统：Ubuntu 26.04.1 LTS（内核 7.0.0-38-generic，x86_64）
Docker 版本：29.9.2（docker --version 实测）
Docker Compose 版本：v5.6.1（docker compose version 实测）
Screego 版本：1.12.6（官方最新稳定版，GitHub Releases 查询日期 2026-10-26）
软件包：screego/server:1.12.6（官方发布包，基于 scratch 精简打包，不含 shell）
对外服务端口：8130（映射到 Screego 默认 HTTP 端口 5050）
TURN/STUN 端口：3478（TCP + UDP）
TURN 中继端口段：50000-50200/udp（SCREEGO_TURN_PORT_RANGE 控制）
编排网络：自定义网络 10.89.60.0/24（服务固定地址 10.89.60.10）
编排文件：/opt/screego/docker-compose.yml（项目名 screego-1.12.6-stack）
管理账号：admin / q1w2e3r4（用户凭据文件 screego.users，bcrypt 存储）

提示：宿主端口 8130 为本环境规划值。Screego 默认 HTTP 端口为 5050，若宿主机 5050 未被占用可直接使用 "5050:5050" 映射，后续命令中的 8130 相应替换即可。

二、架构与组件说明

Screego 是单一 Go 二进制服务，一个服务即包含完整功能，Docker Compose 部署不涉及多服务编排，但需要正确暴露三组端口：

组成部分	端口	协议	职责
HTTP 服务	5050（本文映射 8130）	TCP	Web UI、信令 WebSocket（`/stream`）、REST 接口（`/health`、`/config`、`/login`、`/logout`）
内置 TURN/STUN 服务	3478	TCP + UDP	NAT 穿透的地址发现（STUN）与中继（TURN）
TURN 中继端口段	50000-50200	UDP	TURN 中继分配的媒体转发端口，默认关闭，设置 `SCREEGO_TURN_PORT_RANGE` 后启用

屏幕共享的媒体流走 WebRTC P2P 直连；当双方都在对称型 NAT 之后无法直连时，媒体流回落到内置 TURN 中继转发，因此端口段的开放与 SCREEGO_EXTERNAL_IP 的正确配置共同决定了弱网环境下的可用性。SCREEGO_EXTERNAL_IP 必须填写客户端实际可达的服务器公网或局域网地址，它会被写进 STUN/TURN 应答与 ICE 候选里。

与《Ubuntu 22.04 安装 Screego 1.12.6 指南》中的二进制 + systemd 方案相比，Compose 方案的特点是：升级只需更换软件包版本标签重新编排、配置通过环境变量注入、文件挂载持久化用户数据，更适合以编排方式管理的服务器。

三、前置条件

3.1 Docker 与 Compose

docker --version
docker compose version

实测输出：

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

3.2 端口规划

部署前确认以下端口未被占用（8130、3478/tcp、3478/udp、50000-50200/udp）：

ss -tlnp | grep -E ':8130|:3478'
ss -ulnp | grep -E ':3478|:50000'

实测输出（空闲时应无任何输出行）：

（无输出，端口可用）

若启用防火墙（ufw），放行对应端口：

ufw allow 8130/tcp
ufw allow 3478/tcp
ufw allow 3478/udp
ufw allow 50000:50200/udp

3.3 创建部署目录与用户凭据文件

mkdir -p /opt/screego && cd /opt/screego

Screego 的用户登录依赖 SCREEGO_USERS_FILE 指向的凭据文件，格式为 用户名:bcrypt哈希。哈希值用 Screego 自带的 hash 子命令生成（二进制方案的用法见《Ubuntu 22.04 安装 Screego 1.12.6 指南》）。本环境已持有在 Ubuntu 22.04 实验机生成的哈希（口令 q1w2e3r4），直接写入文件：

printf 'admin:$2a$12$ljTxWqB6uljuV0yYB71lHOg5xxheF5aMpxkpUlndeLgusPkmdjXXi\n' > screego.users
cat screego.users

实测输出：

admin:$2a$12$ljTxWqB6uljuV0yYB71lHOg5xxheF5aMpxkpUlndeLgusPkmdjXXi

四、编排文件编写

4.1 docker-compose.yml

写入 /opt/screego/docker-compose.yml：

name: screego-1.12.6-stack

services:
  screego:
    image: screego/server:1.12.6
    restart: unless-stopped
    volumes:
      - ./screego.users:/opt/screego/screego.users:ro
    ports:
      - "8130:5050"
      - "3478:3478/tcp"
      - "3478:3478/udp"
      - "50000-50200:50000-50200/udp"
    environment:
      SCREEGO_EXTERNAL_IP: 192.168.146.131
      SCREEGO_SECRET: 0c6a4fc14cda8cb69a0c8bd8e71cc034
      SCREEGO_TURN_PORT_RANGE: 50000:50200
      SCREEGO_SERVER_TLS: "false"
      SCREEGO_USERS_FILE: /opt/screego/screego.users
    networks:
      screego-bridge:
        ipv4_address: 10.89.60.10

networks:
  screego-bridge:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.60.0/24

4.2 配置项说明

配置项	取值	说明
`name`	`screego-1.12.6-stack`	编排项目名，显式声明可避免目录名成为项目名，便于后续按项目统一启停
`image`	`screego/server:1.12.6`	官方发布包。建议始终锁定具体版本标签而非 `latest`，保证升级可控
`restart`	`unless-stopped`	服务异常退出或宿主机重启后自动拉起（手动停止的除外）
`volumes`	`./screego.users:/opt/screego/screego.users:ro`	以只读方式挂载用户凭据文件；Screego 默认会在自身文件所在目录查找 `screego.config`，此方案全部配置走环境变量，无需挂载配置文件
`ports`（HTTP）	`8130:5050`	宿主 8130 映射到 Screego 默认 HTTP 端口 5050
`ports`（TURN/STUN）	`3478:3478/tcp`、`3478:3478/udp`	内置 TURN/STUN 监听端口，TCP/UDP 都要暴露
`ports`（中继段）	`50000-50200:50000-50200/udp`	TURN 中继端口段，与 `SCREEGO_TURN_PORT_RANGE` 保持一致
`SCREEGO_EXTERNAL_IP`	`192.168.146.131`	服务器对外 IP，会写入 ICE 候选，必填；公网部署填公网 IP
`SCREEGO_SECRET`	32 字节随机值	会话 Cookie 签名密钥。不设置则每次重启随机生成，所有已登录用户会话失效（见排障实录 9.3）；生成方式 `openssl rand -hex 16`
`SCREEGO_TURN_PORT_RANGE`	`50000:50200`	TURN 中继端口段，注意 compose 端口映射用 `-`，该环境变量用 `:`（源码以冒号切分）
`SCREEGO_SERVER_TLS`	`"false"`	是否由 Screego 直接终止 TLS。反代场景设为 `false` 并由 Nginx/Caddy 处理证书；直接对外提供 HTTPS 时设 `true` 并配合 `SCREEGO_TLS_CERT_FILE`/`SCREEGO_TLS_KEY_FILE`
`SCREEGO_USERS_FILE`	`/opt/screego/screego.users`	指向挂载进来的凭据文件路径
`networks`/`ipam`	`10.89.60.0/24`	自定义网段并固定服务地址；固定地址便于防火墙按源放行与日志审计，非必需

全部环境变量与配置文件的等价关系见《Screego 1.12.6 配置参数详解》。

五、部署启动

5.1 启动服务栈

cd /opt/screego
docker compose up -d

实测输出：

 Network screego-1126-stack_screego-bridge Creating 
 Network screego-1126-stack_screego-bridge Creating 
 Network screego-1126-stack_screego-bridge Created 
 Network screego-1126-stack_screego-bridge Created 
 Container screego-1126-stack-screego-1 Creating 
 Container screego-1126-stack-screego-1 Created 
 Container screego-1126-stack-screego-1 Starting 
 Container screego-1126-stack-screego-1 Started

注：Compose v5.6.1 对网络创建会重复打印两次，属正常回显。服务实例名由项目名（screego-1.12.6-stack 规范化为 screego-1126-stack）加服务名自动生成。

5.2 状态确认

docker compose ps

实测输出：

NAME                           STATUS         PORTS
screego-1126-stack-screego-1   Up 8 seconds   0.0.0.0:3478->3478/udp, [::]:3478->3478/udp, 0.0.0.0:3478->3478/tcp, 0.0.0.0:50000-50200->50000-50200/udp, [::]:3478->3478/tcp, [::]:50000-50200->50000-50200/udp, 0.0.0.0:8130->5050/tcp, [::]:8130->5050/tcp

宿主机侧端口监听复核：

ss -tlnp | grep -E '8130|3478'
ss -ulnp | grep -E '3478|50000|50100'

实测输出：

LISTEN 0      4096         0.0.0.0:3478       0.0.0.0:*    users:(("docker-proxy",pid=175299,fd=8))                
LISTEN 0      4096         0.0.0.0:8130       0.0.0.0:*    users:(("docker-proxy",pid=175343,fd=8))                
LISTEN 0      4096            [::]:3478          [::]:*    users:(("docker-proxy",pid=175304,fd=8))                
LISTEN 0      4096            [::]:8130          [::]:*    users:(("docker-proxy",pid=175350,fd=8))                
UNCONN 0      0            0.0.0.0:50000      0.0.0.0:*    users:(("docker-proxy",pid=175365,fd=8)) 
UNCONN 0      0            0.0.0.0:50100      0.0.0.0:*    users:(("docker-proxy",pid=177631,fd=8)) 
UNCONN 0      0            0.0.0.0:3478       0.0.0.0:*    users:(("docker-proxy",pid=175322,fd=8)) 
UNCONN 0      0               [::]:50000         [::]:*    users:(("docker-proxy",pid=175372,fd=8)) 
UNCONN 0      0               [::]:50100         [::]:*    users:(("docker-proxy",pid=177640,fd=8)) 
UNCONN 0      0               [::]:3478          [::]:*    users:(("docker-proxy",pid=175328,fd=8))

注：ss -ulnp 对端口段映射只抽样显示部分端口（如 50000、50100），整段 201 个端口均已就绪，可用 ss -ulnp | grep -c 501 复核。

5.3 启动日志

docker compose logs screego

实测输出（时间戳部分，ANSI 颜色码已省略）：

screego-1  | 2026-10-27T00:07:44Z INF Deny turn peers within ["0.0.0.0/8" "127.0.0.0/8" "::/128" "::1/128" "fe80::/10"]
screego-1  | 2026-10-27T00:07:44Z INF Loaded Users amount=1
screego-1  | 2026-10-27T00:07:44Z INF Start TURN/STUN addr=:3478
screego-1  | 2026-10-27T00:07:44Z INF Start HTTP addr=:5050

Loaded Users amount=1 说明凭据文件挂载成功；Start TURN/STUN addr=:3478 与 Start HTTP addr=:5050 说明两组监听都已就绪。

六、部署后验证

6.1 健康检查接口

curl -s http://127.0.0.1:8130/health

实测输出：

{"status":"up","clients":0}

status 为 up 表示服务正常，clients 是当前 WebSocket 在线连接数。

6.2 服务配置回显

curl -s http://127.0.0.1:8130/config

实测输出：

{"authMode":"turn","user":"guest","loggedIn":false,"version":"1.12.6","roomName":"kind-fuchsia-cow","closeRoomWhenOwnerLeaves":true}

该接口回显了认证模式（默认 turn：仅房主需要登录，加入者可匿名）、版本号 1.12.6 与随机生成的房间名。

6.3 用户登录

Screego 的登录接口是表单提交（字段 user/pass），不是 JSON：

curl -s -i -X POST http://127.0.0.1:8130/login -d "user=admin&pass=q1w2e3r4" | head -15

实测输出：

HTTP/1.1 200 OK
Set-Cookie: user=MTc5MzA1OTYxMnxEWDhFQVFMX2dBQUJFQUVRQUFBal80QUFBUVp6ZEhKcGJtY01CZ0FFZFhObGNnWnpkSEpwYm1jTUJ3QUZZV1J0YVc0PXyuMAAP5G8hTpYoe-L86U4xwjF7YxPEN0uKLYIbP7vdRQ==
Date: Tue, 27 Oct 2026 00:06:52 GMT
Content-Length: 28
Content-Type: text/plain; charset=utf-8

{"message":"authenticated"}

返回 200 并签发 user Cookie 即登录成功；口令错误时返回 401。

6.4 TURN/STUN 协议实测

端口监听只能证明端口开了，最直接的验证是向 3478 发一个标准 STUN Binding Request 并解析应答。以下脚本保存为 stun_test.py（标准库实现，无第三方依赖）：

#!/usr/bin/env python3
"""Minimal STUN Binding Request test against Screego's built-in TURN/STUN server."""
import socket, struct, sys, os

host, port = sys.argv[1], int(sys.argv[2])
# STUN Binding Request: type 0x0001, length 0, magic cookie 0x2112A442, 12-byte transaction id
tid = os.urandom(12)
req = struct.pack("!HHI", 0x0001, 0, 0x2112A442) + tid

s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
s.settimeout(3)
s.sendto(req, (host, port))
try:
    data, addr = s.recvfrom(2048)
    mtype, mlen, cookie = struct.unpack("!HHI", data[:8])
    rtid = data[8:20]
    print(f"STUN response received from {addr[0]}:{addr[1]}")
    print(f"message type=0x{mtype:04x} length={mlen} magic_cookie={'OK' if cookie == 0x2112A442 else 'MISMATCH'} tid_match={'yes' if rtid == tid else 'no'}")
    # parse attributes: XOR-MAPPED-ADDRESS (0x0020) / MAPPED-ADDRESS (0x0001)
    off = 20
    while off + 4 <= len(data):
        atype, alen = struct.unpack("!HH", data[off:off+4])
        aval = data[off+4:off+4+alen]
        if atype == 0x0020 and alen >= 8:
            port_x = struct.unpack("!H", aval[2:4])[0] ^ 0x2112
            ip_x = bytes(b ^ m for b, m in zip(aval[4:8], struct.pack("!I", 0x2112A442)))
            print(f"XOR-MAPPED-ADDRESS: {socket.inet_ntoa(ip_x)}:{port_x}")
        elif atype == 0x0001 and alen >= 8:
            port_v = struct.unpack("!H", aval[2:4])[0]
            print(f"MAPPED-ADDRESS: {socket.inet_ntoa(aval[4:8])}:{port_v}")
        off += 4 + alen + ((4 - alen % 4) % 4)
except socket.timeout:
    print("STUN request timed out (no response)")

在宿主机与本机局域网地址各测一次：

python3 stun_test.py 127.0.0.1 3478
python3 stun_test.py 192.168.146.131 3478

实测输出：

STUN response received from 127.0.0.1:3478
message type=0x0101 length=20 magic_cookie=OK tid_match=yes
XOR-MAPPED-ADDRESS: 10.89.60.1:37524
STUN response received from 192.168.146.131:3478
message type=0x0101 length=20 magic_cookie=OK tid_match=yes
XOR-MAPPED-ADDRESS: 192.168.146.131:44992

应答类型 0x0101 是 Binding Success Response，XOR-MAPPED-ADDRESS 就是服务端看到的客户端地址。经 192.168.146.131 访问时返回的映射地址也是 192.168.146.131，说明 SCREEGO_EXTERNAL_IP 与 STUN 应答路径一致，NAT 穿透的地址发现链路正常。

编排网络拓扑复核：

docker network inspect screego-1126-stack_screego-bridge --format '{{json .IPAM.Config}} | {{range .Containers}}{{.Name}}={{.IPv4Address}}{{end}}'

实测输出：

[{"Subnet":"10.89.60.0/24","Gateway":"10.89.60.1"}] | screego-1126-stack-screego-1=10.89.60.10/24

6.5 浏览器端验证

浏览器访问 http://192.168.146.131:8130，页面出现房间创建界面；用 admin / q1w2e3r4 登录后创建房间，把房间链接发给同网段另一台电脑即可发起屏幕共享。首次打开若浏览器提示不安全，是因为本方案未启用 TLS（SCREEGO_SERVER_TLS=false）；getUserMedia 屏幕捕获在非 HTTPS 源下受限，生产环境建议按《Screego 1.12.6 配置参数详解》启用 TLS 或配置反向代理。

七、日常运维

# 查看实时日志
docker compose logs -f screego

# 重启服务
docker compose restart screego

# 停止服务（编排与网络保留）
docker compose stop

# 完整停止并移除编排对象（挂载的用户文件在宿主机目录，不受影响）
docker compose down

restart: unless-stopped 已覆盖宕机自愈场景；SCREEGO_SECRET 已显式设置，重启不会使已登录用户失效。

升级版本：修改 docker-compose.yml 中的 image 标签（如 screego/server:1.12.7）后执行：

docker compose up -d

Compose 会重建变化的服务实例并复用网络与挂载，数据无迁移负担（Screego 无本地数据库，唯一持久化对象就是 screego.users）。

八、排障实录

8.1 自定义网段与其他编排冲突：Pool overlaps

现象：docker compose up -d 报错，服务栈无法创建。复现（10.89.57.0/24 已被其他编排占用）：

docker network create --subnet 10.89.57.0/24 screego-conflict-test

实测输出：

Error response from daemon: invalid pool request: Pool overlaps with other one on this address space

原因：Docker 默认地址池被多个自定义网段瓜分后，新编排水段与已存在网段重叠。处理：先盘点现有网段再挑选空闲段：

docker network ls
docker network inspect $(docker network ls --format '{{.Name}}' | grep bridge) --format '{{.Name}} {{json .IPAM.Config}}'

将 ipam.config.subnet 改为未占用网段（本文用 10.89.60.0/24）后重新编排即可。

8.2 未设置 SCREEGO_SECRET：重启后登录失效

现象：服务启动日志出现警告，重启后所有已登录用户需要重新登录。

实测日志行：

SCREEGO_SECRET unset, user logins will be invalidated on restart

原因：SCREEGO_SECRET 未设置时，Screego 每次启动随机生成会话签名密钥，旧 Cookie 全部失效。处理：openssl rand -hex 16 生成密钥写入编排文件并重启，本文 4.1 节已配置。该问题在首次部署不报错、只在重启后暴露，容易被漏配。

8.3 官方软件包不含 shell：无法 exec 进入排障

现象：尝试进入服务实例执行命令时失败。

docker compose exec screego sh

实测输出：

OCI runtime exec failed: exec failed: unable to start container process: exec: "sh": executable file not found in $PATH

原因：screego/server 官方发布包基于 scratch 精简打包，只含 Screego 二进制，无 shell、无常用调试工具。排障应改从外部入手：docker compose logs 看日志、宿主机 ss/curl/STUN 探测看端口与协议、docker network inspect 看网络拓扑。这也是本文 6.4 节在宿主机侧做 STUN 实测的原因。

九、卸载清理

cd /opt/screego
docker compose down            # 停止并移除服务实例与编排网络
docker rmi screego/server:1.12.6   # 移除软件包（可选）
rm -rf /opt/screego            # 移除编排文件与用户凭据（可选）

docker compose down 不带 -v 也不会残留卷（本方案未声明 named volume），唯一的数据文件 screego.users 在宿主机目录中，随目录一起清理。

十、参考链接

《Screego 1.12.6 介绍与选型指南》：https://www.quzuo.net/document/XzOmvpIQfDim
《Ubuntu 22.04 安装 Screego 1.12.6 指南》：https://www.quzuo.net/document/IPfdAp2GZwAK
Screego 官方网站：https://screego.net
GitHub 仓库：https://github.com/screego/server
Docker Hub：https://hub.docker.com/r/screego/server