使用 Docker 部署

.deb 软件包的替代方案：uVersion 服务器及其 PostgreSQL 数据库以容器方式运行， 由单条 docker compose up 启动。如果你偏好容器化部署，或想快速试用，这很理想。

前置条件：带 Compose v2 插件的 Docker Engine 20.10+ （docker compose version），以及一枚 uVersion 许可证密钥。没有有效且已签名的 密钥，服务器会拒绝启动：请从你的账户获取（或从 注册页面申领一枚）。

安装

1. 获取 compose 文件与环境模板

两个文件，放进一个将成为该栈目录的新文件夹里：docker-compose.yml 和模板 .env。

mkdir uversion && cd uversion
wget -N -O docker-compose.yml https://uversion.io/downloads/server/docker/docker-compose.yml
wget -N -O .env https://uversion.io/downloads/server/docker/env.example

2. 获取镜像

在线时，registry 就够了：

docker compose pull

在无法访问互联网时（隔离网络），改为下载归档并加载它：它与 compose 带有相同的 镜像名，因此启动时无需下载任何东西即可找到它。

wget -N https://uversion.io/downloads/server/docker/uversion-server_latest_docker.tar.gz
docker load -i uversion-server_latest_docker.tar.gz

3. 填写 .env

有两个值是必填的：UVERSION_LICENCE__KEY（你的许可证密钥，即邮件收到的那串 很长的已签名字符串）和 POSTGRES_PASSWORD（随附数据库的强密码）。

nano .env

为会话签名的密钥在首次启动时生成并保存在数据目录中。你无需输入任何内容。 它是备份的一部分：若它丢失，每个人只需重新登录一次，不会丢失任何东西。若你更愿意设定自己的 （至少 32 个字符），请在 .env 中填写 UVERSION_SECURITY__JWT_SECRET： 它确实会传给容器，容器随后使用它而不再自行生成。

# Changer reellement le mot de passe de la base
docker compose exec db psql -U uversion -c "ALTER USER uversion PASSWORD 'nouveau-mot-de-passe'"

# Puis reporter la MEME valeur dans POSTGRES_PASSWORD (.env) et relancer
docker compose up -d

4. 启动该栈

docker compose up -d

服务器随后可在 https://YOUR-HOST:8443 访问。无需域名，也无需 Let’s Encrypt 证书：TOFU 模型会处理它，也就是首次接触即信任，如同 SSH 第一次让你确认一台机器的指纹那样。

5. 读取服务器指纹

它在每次启动时都会被重写进日志：

# L'empreinte du serveur, reecrite dans les journaux a chaque demarrage
docker compose logs server | grep -i "TLS fingerprint"

这就是服务器指纹（其证书的 SHA-256）：服务器在 8443 端口提供自签名 HTTPS，每个客户端在首次连接时予以确认。请与你的团队共享（见 TLS 指纹）。不要把它与校验和混淆，后者用于 校验下载的文件：这一个标识的是你的服务器。

6. 读取初始管理员密码

用这个密码以 admin 登录，然后修改它。一经修改，该文件即被删除。

# Le mot de passe admin initial (le fichier disparait des que vous le changez)
docker compose exec server cat /data/initial-admin-password

要实时跟踪启动，docker compose logs -f server 合适，但别把它放在一串命令 中间：-f 会无限期跟随日志，永不交还控制权（按 Ctrl + C 退出）。

数据与数据库

服务器的全部状态（分块存储、TLS 证书因而也是指纹、服务器身份）存放在一个宿主机目录里，而 PostgreSQL 数据库放在另一个目录里。两者都在 .env 中设置：

# Dans .env : placer les donnees et la base sur un disque large et sauvegarde
UVERSION_DATA_DIR=/srv/uversion/data      # chunks, cert TLS, identite serveur
UVERSION_DB_DIR=/srv/uversion/db          # PostgreSQL fourni

对于真正的部署，请把 UVERSION_DATA_DIR 指向一块大且有备份的磁盘：一个 Unreal 项目的二进制分块可能很大。容器会自行调整挂载目录的权限（它仅在纠正属主期间以 root 启动，随后 降到一个非特权用户），因此你无需事先 chown 任何东西。

要使用一个已就位的外部 PostgreSQL，请在 .env 中填写 UVERSION_DATABASE__URL，然后删除 docker-compose.yml 中的 db 服务和 depends_on 块。

# Dans .env : brancher un PostgreSQL existant
UVERSION_DATABASE__URL=postgres://user:motdepasse@db.interne:5432/uversion

迁移数据与数据库

最简单的情形是在首次 up 之前就设好两个变量：此时什么都还不 存在，没有什么可复制。若栈已在运行，就得停掉它，并手动复制目录，同时保留属主。

1. 停止该栈

复制期间不得有任何写入：

docker compose down

2. 复制两个目录

保留属主和权限的正是 -a：

sudo rsync -a ./data/server/ /srv/uversion/data/
sudo rsync -a ./data/db/     /srv/uversion/db/

3. 把 .env 指向新位置

# Dans .env, LES DEUX lignes, pas une seule
UVERSION_DATA_DIR=/srv/uversion/data
UVERSION_DB_DIR=/srv/uversion/db

4. 重启

docker compose up -d

三个路径陷阱，都曾遇到过：

• 相对路径是相对 compose 文件解析的，而不是相对你运行命令所在的目录。 ./data/server 始终指向 docker-compose.yml 的邻居。
• 网络共享（NFS、CIFS、Windows 共享）通常会拒绝容器在启动时执行的 chown。于是容器立即退出，报出一个既不提 uVersion 也不提存储的权限 错误。请使用本地磁盘或块卷。
• rsync -a 才是保留属主和权限的手段。用不带选项的 cp，或从文件管理器复制，会把一切重置到当前账户，于是 PostgreSQL 会拒绝在它 自己的目录上启动。

运维

备份：数据库

它承载元数据：文件、修订、用户、锁。

docker compose exec db pg_dump -U uversion uversion > uversion-db.sql

备份：服务器数据

这是由 UVERSION_DATA_DIR 指定的宿主机目录。两份备份都重要：缺一份，就什么都 恢复不了。

# .env n'est pas charge dans votre shell, chargez-le pour reutiliser la variable
set -a; . ./.env; set +a
DATA_DIR="$UVERSION_DATA_DIR"
[ -n "$DATA_DIR" ] || DATA_DIR=./data/server      # valeur par defaut

tar czf uversion-data.tar.gz -C "$DATA_DIR" .

更新

数据和数据库不受影响，迁移会在启动时应用。

docker compose pull
docker compose up -d   # les migrations s'appliquent au demarrage

在隔离网络上，改为加载一个更新的归档：

wget -N https://uversion.io/downloads/server/docker/uversion-server_latest_docker.tar.gz
docker load -i uversion-server_latest_docker.tar.gz
docker compose up -d

停止

docker compose stop 停止容器，docker compose down 移除它们。两种 情况下你的数据都留在原处。