4.9 KiB
服务器离线部署与配置
此文档适用于服务器已有 Nginx 的场景。部署包不包含 .env，因为其中存放数据库密码、JWT Secret、LiveKit Secret 和初始管理员密码。
1. 在构建机生成部署包
构建机需要 Docker、JDK 21 和 Node.js/npm。脚本先在宿主机执行 Gradle 和 npm 构建；前端 dist 放入部署包的 web 目录，由应用服务器的 Gateway Nginx 容器托管。外部 Nginx 只需反代 Gateway 的一个地址。
cd /path/to/ScreenShare
chmod +x scripts/package-release.sh
./scripts/package-release.sh 0.1.0
生成文件：
release/screen-share-0.1.0.tar.gz
若当前账户没有 Docker socket 权限，脚本会仅对 Docker 命令自动调用 sudo。不要使用 sudo ./scripts/package-release.sh，这样 Gradle/npm 才能使用当前用户已经下载的依赖缓存。
脚本默认使用本项目开发机 IntelliJ 下载的 JDK 21：/home/orangeroll/.jdks/ms-21.0.12，无需手动设置 JAVA_HOME。换电脑或升级 JDK 时，直接修改 scripts/package-release.sh 顶部的 project_java_home 路径。
Docker 代理
Docker daemon 不会自动使用桌面或终端的系统代理。若构建机缺少 API、PostgreSQL、LiveKit 或 Nginx 镜像且访问 Docker Hub 较慢，先为 Docker daemon 配置 HTTP/HTTPS 代理。下面以本机 HTTP 代理端口 7890 为例；如果使用 Clash 等工具，应填写 HTTP 代理端口，不是 SOCKS 端口。已有本地镜像会被脚本直接复用。
sudo systemctl edit docker
写入：
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,::1,postgres,api,livekit"
然后执行：
sudo systemctl daemon-reload
sudo systemctl restart docker
sudo docker info | grep -i proxy
重启 Docker 会短暂影响运行中的容器。Gradle/npm 现在在宿主机运行，直接使用当前用户的网络和本地缓存；Docker daemon 代理只负责拉取基础镜像。
./scripts/package-release.sh 0.1.0
不要把 SOCKS 代理端口直接填入 Docker daemon 配置。
2. 传输并导入服务器
服务器需要 Docker Compose，但不需要访问镜像仓库。
scp release/screen-share-0.1.0.tar.gz deploy@your-server:/opt/
ssh deploy@your-server
cd /opt
tar -xzf screen-share-0.1.0.tar.gz
cd screen-share-0.1.0
sudo docker load -i images.tar
3. 创建服务器 .env
cp .env.example .env
chmod 600 .env
必须修改下列值，且不要提交或传回 Git：
POSTGRES_PASSWORD=替换为随机数据库密码
LIVEKIT_API_KEY=生产环境Key
LIVEKIT_API_SECRET=替换为随机LiveKit密钥
LIVEKIT_PUBLIC_URL=wss://share.example.com
GATEWAY_BIND_ADDRESS=应用服务器内网IP
AUTH_JWT_SECRET=替换为随机JWT密钥
CORS_ALLOWED_ORIGINS=https://share.example.com
BOOTSTRAP_ADMIN_PASSWORD=替换为强管理员密码
SCREENSHARE_VERSION=0.1.0
GATEWAY_BIND_ADDRESS 推荐填应用服务器的内网 IP。也可暂时保留默认 0.0.0.0，但必须在应用服务器防火墙中只允许外部 Nginx 服务器访问 8081/TCP。
4. 配置外部 Nginx
部署包内的 gateway 服务负责静态前端、/api/ 与 LiveKit 信令；外部 Nginx 只需要一个上游地址。复制 infra/nginx/screenshare.conf.example 的 server 配置到外部 Nginx 站点，将 share.example.com、证书路径和 10.0.0.20:8081 改为真实值。map 指令只能在 http 块中声明一次。
外部 Nginx 不需要复制 web 目录，也不需要分别配置 /api/、/rtc/ 或 /twirp/。
验证并重载：
sudo nginx -t
sudo systemctl reload nginx
5. 启动服务
sudo docker compose --env-file .env up -d
sudo docker compose ps
sudo docker compose logs -f api
首次 API 启动会执行 Flyway 迁移并创建 bootstrap 管理员。浏览器访问 https://share.example.com。
6. 防火墙与安全组
应用服务器开放：
TCP 8081（仅允许外部 Nginx 的内网 IP）
TCP 7881（浏览器直接访问 LiveKit 的 TCP 兜底）
UDP 50000-50100
外部 Nginx 服务器向公网开放 TCP 80, 443。不要公开 PostgreSQL 5432、API 8080 或 LiveKit HTTP/WebSocket 7880；它们只供 Docker 内部 Gateway 使用。
浏览器的 WebRTC 媒体不会经过任一 Nginx，仍须直连应用服务器的 LiveKit 7881/TCP 和 50000-50100/UDP。生产环境还需要在 LiveKit 中正确声明公网 IP/NAT。
7. 更新版本
在构建机用新版本号重新打包，例如 0.1.1。服务器上导入新 images.tar，修改 .env 中 SCREENSHARE_VERSION，再重建服务：
sudo docker load -i images.tar
sed -i 's/^SCREENSHARE_VERSION=.*/SCREENSHARE_VERSION=0.1.1/' .env
sudo docker compose --env-file .env up -d
PostgreSQL 卷会保留；Flyway 会自动执行新增迁移。数据库升级前建议备份卷或执行 pg_dump。