# 服务器离线部署与配置

此文档适用于服务器已有 Nginx 的场景。部署包不包含 .env，因为其中存放数据库密码、JWT Secret、LiveKit Secret 和初始管理员密码。

## 1. 在构建机生成部署包

构建机需要 Docker、JDK 21 和 Node.js/npm。脚本先在宿主机执行 Gradle 和 npm 构建；前端 `dist` 放入部署包的 `web` 目录，由应用服务器的 Gateway Nginx 容器托管。外部 Nginx 只需反代 Gateway 的一个地址。

~~~bash
cd /path/to/ScreenShare
chmod +x scripts/package-release.sh
./scripts/package-release.sh 0.1.0
~~~

生成文件：

~~~text
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 端口。已有本地镜像会被脚本直接复用。

~~~bash
sudo systemctl edit docker
~~~

写入：

~~~ini
[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"
~~~

然后执行：

~~~bash
sudo systemctl daemon-reload
sudo systemctl restart docker
sudo docker info | grep -i proxy
~~~

重启 Docker 会短暂影响运行中的容器。Gradle/npm 现在在宿主机运行，直接使用当前用户的网络和本地缓存；Docker daemon 代理只负责拉取基础镜像。

~~~bash
./scripts/package-release.sh 0.1.0
~~~

不要把 SOCKS 代理端口直接填入 Docker daemon 配置。

## 2. 传输并导入服务器

服务器需要 Docker Compose，但不需要访问镜像仓库。

~~~bash
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

~~~bash
cp .env.example .env
chmod 600 .env
~~~

必须修改下列值，且不要提交或传回 Git：

~~~dotenv
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/`。

验证并重载：

~~~bash
sudo nginx -t
sudo systemctl reload nginx
~~~

## 5. 启动服务

~~~bash
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. 防火墙与安全组

应用服务器开放：

~~~text
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，再重建服务：

~~~bash
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。