VeScreen

简体中文

English

简体中文

English

外观

部署 VeScreen Server ​

English · 简体中文 · 文档导航

VeScreen Server 将网页、房间管理和可选的媒体转发打包在一个服务端程序中。 解压后即可运行，房间数据保存在 SQLite 中。

默认的 P2P 配置由服务器负责房间管理、信令和 STUN，画面与声音在参与者之间传输。 启用 SFU 后，服务器还会承担媒体转发的带宽和处理开销。配置较低的服务器可以先用默认设置， 按预计的房间数和观众数观察 CPU、内存与网络占用，再决定是否开启 SFU。 降低画面分辨率主要减轻参与者设备的采集和编码负担。

先在本机试用 ​

以下操作适用于 Linux x64 和 ARM64 服务器。

从 GitHub Releases 或 Gitee 镜像下载对应架构的服务端程序包。 可运行 uname -m 查看架构：

架构程序包
x86_64（x64）piik-<revision>-runtime.tar.gz
aarch64（ARM64）piik-<revision>-linux-arm64-runtime.tar.gz

解压后，在该目录运行：

sh
./piik-server

打开 http://localhost:8787 即可试用。需要让朋友通过互联网访问时， 继续完成下方配置。如果只想在自己的电脑上临时开房间，可直接使用 VeScreen App。

使用 Docker Compose ​

在已安装 Docker Compose v2 的 Linux x64 或 ARM64 服务器上，从 VeScreen 目录复制两个部署文件到空目录中：

sh
cp deploy/container/compose.yaml .
cp deploy/container/.env.example .env

将 .env 中的 share.example.com 换成自己的域名，然后启动：

sh
docker compose run --rm piik --check-config
docker compose up -d

ghcr.io/tntcrafthim/piik:latest 镜像包含网页、信令、STUN 和可选 SFU。 Docker 会自动选择对应架构的镜像。 接着完成下方的 HTTPS 配置和端口放行。 默认使用 P2P；如需 SFU 兜底，按 .env 中的说明启用即可。 请保留 piik-data 数据卷，房间数据和可选诊断文件都保存在其中。 更新与备份见容器维护说明。

对外提供服务 ​

准备一台 Linux x64 或 ARM64 服务器，以及一个指向服务器公网 IP 的域名。 下文以 share.example.com 为例，请替换成自己的域名。

1. 配置并启动 VeScreen ​

在程序旁新建 .env 文件：

dotenv
PIIK_ENV=production
LISTEN_HOST=127.0.0.1
PUBLIC_BASE_URL=https://share.example.com
STUN_URLS=stun:share.example.com:3478
MAX_VIEWERS_PER_ROOM=20
SITE_ACCESS_PASSWORD=

使用普通用户，在该目录执行：

sh
./piik-server --check-config
./piik-server

程序会自动读取 .env，并将房间数据保存在工作目录的 rooms.sqlite 中。 SITE_ACCESS_PASSWORD 留空时，进入站点无须口令； 如需设置口令，填写你想使用的口令即可。房间邀请与加入权限仍由房主管理。

PUBLIC_BASE_URL 应与浏览器访问的网址一致，包括 HTTPS 和非默认端口。 只使用这个地址时，ALLOWED_ORIGINS 不设置或留空即可；已有的非空值会覆盖此默认值， 旧地址未更新可能导致创建房间返回 403。

MAX_VIEWERS_PER_ROOM 可设置每房观众上限，不含房主，支持 1..20，修改后重启生效。 人数越多，对网络和转发资源的需求也可能增加。默认值及 App 房间的区别见 人数限制。

公开站点可选设 ROOM_EMPTY_TIMEOUT_SECONDS=3600，重启后，无人在线的房间会在空置一小时后 回收；房间号用满时，会提前回收最早创建的空房间，仍有人在线的房间不受影响。 被回收的房间需要重新创建并发送邀请。不设置或设为 0 则保持默认的长期保留行为， 详见房间保留策略。

2. 配置 HTTPS ​

如果已有 HTTPS 反向代理，将请求转发到 127.0.0.1:8787，并启用 WebSocket 支持。 如果还没有，可以安装 Caddy，在 Caddyfile 中加入：

text
share.example.com {
    reverse_proxy 127.0.0.1:8787
}

重新加载 Caddy。域名解析正确且 TCP 80/443 可访问时，它会自动申请和续期证书。 具体操作见 Caddy 的 HTTPS 代理说明。

nginx 可参考配置示例。如果沿用了旧示例，请将 Permissions-Policy 改为 camera=(self), microphone=(self), geolocation=()，然后重新加载 nginx。 摄像头和麦克风的空白允许列表会阻止浏览器采集，即使用户已授权；self 允许本站请求访问。

3. 放行端口并检查 ​

在服务器防火墙和云平台安全组中放行 TCP 80/443（HTTPS）和 UDP 3478（STUN）。 TCP 8787 仅供本机反向代理访问。STUN 域名需要直接解析到服务器，不能只经过 CDN 的 HTTP 代理。 可选服务的端口见完整端口表。 内置 SFU 的媒体流复用 SFU_UDP_PORT 指定的单个 UDP 端口。

打开 https://share.example.com/healthz，应返回 {"status":"ok"}。 随后打开站点，分享一个画面，并用另一台设备加入验证。 上述基础配置使用 P2P 传输，参与者之间需要可用的 UDP 通路。

可选：启用媒体兜底 ​

在 .env 中添加 SFU_UDP_PORT=7882，放行 UDP 7882，再重启 VeScreen，即可启用自动 SFU 兜底。 如果服务器处于 NAT 后方，还需将 SFU_PUBLIC_IP 设置为外部可达的公网 IPv4 地址。 这项功能由同一个服务端程序提供。 服务器需要为实际经由 SFU 观看的观众承担转发负载和出口带宽。 房主需要在开始分享前关闭 隐私模式，才会允许使用这条线路。 直连和 SFU 媒体都需要可用的 UDP 通路。

如需所有房间都通过服务器转发，再设置 SFU_ONLY=true 并重启。 分享设置中会显示 服务器转发。请为每位观众预留服务器带宽； 服务器线路失败时，此模式不会改走 P2P。

长期运行与更新 ​

需要开机启动时，参阅 systemd 与容器配置。 更新时保留 .env 和 rooms.sqlite：停止服务、备份房间数据、替换新版程序，再启动并检查健康状态和房间访问。 涉及数据格式变化的版本，请先阅读发布说明。

全部配置与端口 · 维护者发版工具

第三方软件许可