Wiki

在 Ubuntu / Debian 上安装

.deb 软件包：三个问题、数据目录、离线安装、备份与卸载。

Ubuntu 24.04+、Debian 13+（x86_64）。两条命令，三个问题。

安装

1. 下载软件包

在将托管服务器的机器上，以普通会话执行：

cd /tmp && wget -N https://uversion.io/downloads/server/uversion-server_latest_amd64.deb

_latest_ URL 始终指向最新发布的版本。 -N 标志告诉 wget 仅在远程文件更新时才重新下载：便于更新而不堆积 .deb.1、.deb.2 等副本。当 .deb 位于您的主目录时，cd /tmp 可避免一个无关紧要的 apt 警告（"unsandboxed as root"）。

2. 启动安装

在您刚刚下载软件包的目录中，只需一条命令：

sudo apt install ./uversion-server_latest_amd64.deb

随后安装程序会按下面三个步骤的顺序提出三个问题。它们显示在一个全屏蓝色对话框中：用 Tab 移动，用 Enter 确认。

3. 回答：数据目录

默认值：/var/lib/uversion。您受版本管理的文件的内容会落到这里，因此这是会变大的目录，也就是您希望放在大磁盘上的目录。并非所有路径都被接受：选择数据目录一节列出四条规则，安装程序会指出您违反的那条规则并加以拒绝。

Debian 安装程序的第一个问题，在一个全屏蓝色对话框中：数据目录的路径，已预填为 /var/lib/uversion。

4. 回答：是否也把数据库放到数据目录？

默认值：否。这是安装中影响最深远的问题，而这个默认值有一项在您照单接受之前应当了解的代价。

这个回答决定了单块磁盘是否足以重建您的服务器。

否（默认）：PostgreSQL 数据库留在系统目录（/var/lib/postgresql），与您的数据分离。如果机器损毁，幸存的数据磁盘含有文件内容，却再也没有任何修订、任何账户、任何锁和任何权限。这不是一台可以重启的服务器，而是一堆字节。
是：安装程序在数据目录内部创建一个专用数据库，并在其中写入一份恢复流程。届时，一块幸存的磁盘，加上 PostgreSQL 和这个软件包，就足以在另一台机器上重建服务器。

回答“是”之前有两点代价要知道。这个数据库目录只能由创建它的 PostgreSQL 主版本重新打开，因此几年后的重建可能需要显式安装该版本。而且这块磁盘届时还会带有许可证密钥、JWT 密钥和数据库密码：请把它当作机密对待。这个回答以后可用 sudo dpkg-reconfigure uversion-server 更改。

5. 回答：激活码

必填，除非机器上或第 3 步所选磁盘上已存在许可证：这种情况下安装程序会在一条专门的消息中告知您，并且不再提问，因为激活码是一次性的，而您的激活码已被这块磁盘来源的机器消耗掉。

该字段接受三种形式，这是机器没有互联网时的出路：短码 UV-XXXX-XXXX-XXXX、指向含有您完整许可证密钥的文件的绝对路径，或者把这段完整密钥直接粘贴（一段以 eyJ 开头的长字符串）。仅在第一种形式下，安装程序才会联系 licence.uversion.io 用激活码换取完整密钥。

6. 记下结尾处显示的内容

安装以一个彩色框结束：admin 用户名、临时密码、服务器地址和证书指纹。 请把它们记下来：含有该密码的文件会在您更改密码后立即被删除。

随后您可以继续首次登录。

中断的安装可以安全地重新开始。 如果您关闭了窗口、网络掉线，或安装程序在某个错误处停止，只需重新运行同一条 apt install 命令。您的激活码不会再次丢失：一旦经过交换，取得的密钥便写入磁盘，并在后续尝试中重复使用。而要事后重新审视任意回答且无需重装：sudo dpkg-reconfigure uversion-server。这是本页通用的补救命令。

选择一个安装程序会接受的数据目录

四条规则。前三条在您的激活码被消耗之前就会检查，因此被拒绝毫无损失：改正后重来即可。

既不在 /home 下，也不在 /root 下。 服务器以一个被刻意剥夺了对个人目录任何访问权的系统账户运行：它永远无法在那里读写，也不会启动。
路径中不含空格。 该路径会原样复制到服务的设置中，而那里用空格分隔两个值。以 /media/jean/My Book 这类名称自动挂载的外置磁盘正好会栽在这上面。
绝对路径，也就是以 / 开头。
每个上级目录都必须让 uversion 和 postgres 账户通过。 这是最不显眼的陷阱，以 root 身份安装时看不出来：一个手工创建并已关闭的上级目录（例如从 Helix 仓库沿用下来、权限为 root:root 0750 的 /perforce）会让整个安装通过，随后在首次访问时阻塞服务。症状是一个以 status=200/CHDIR 拒绝启动的服务，或首次写入时的 "Permission denied"。

要在启动安装之前检查这最后一点，请显示通往您所选位置的整条目录链的权限：

namei -l /srv/uversion        # remplacez par le chemin que vous voulez utiliser

每一行的最后一列权限（“其他”那一列）都必须带有一个 x。若缺了一个，安装程序会指出出问题的目录以及要执行的确切命令，形如 sudo chmod o+x /le/dossier。它绝不会自行修改一个不属于它的目录：在您的目录树上开放访问权是您的决定，而不是它的决定。

文件的存放位置

两个位置，其中只有一个会在您更改数据目录时跟随您。

在数据目录中（问题 1 的那个）：您受版本管理的文件内容（在 data/chunks 下）、TLS 证书及其指纹（在 data/tls 下）、服务器身份（server-id、last-validated-at）、初始管理员密码（initial-admin-password，在您更改后立即被清除）、PostgreSQL 数据库（pgdata），以及若您对问题 2 回答“是”，还有恢复套件（recovery）。

在 /etc/uversion/ 中，它从不移动：配置文件 config.toml、许可证密钥的纯副本（licence-key）以及数据库密码（db-password）。

本页所有命令都用 <data-dir> 代替写死的路径，因为那条路径是您选择的。要在一台已安装的机器上读取真实值：

sudo sed -n 's/^WorkingDirectory=//p' /etc/systemd/system/uversion-server.service.d/10-data-dir.conf

验证安装

三项独立检查，按此顺序进行：服务在运行，它在监听，且它没有报告任何问题。

1. 服务在运行

systemctl status uversion-server

预期：active (running)。任何其他值都请转到故障排查。

2. 服务器在 8443 上以 HTTPS 监听

ss -tlnp | grep 8443

应当出现一行。如果服务在运行却什么都没输出，通常是配置中禁用了 TLS：此时服务器改为纯 HTTP，8443 便完全不再监听。

3. 日志中没有错误

sudo journalctl -u uversion-server -n 50

journalctl 是系统的日志阅读器：这里是服务器记录其行为的地方，也是有东西启动不了时首先要看的地方。

重新显示证书指纹

把 <data-dir> 替换为上面读到的值：

sudo cat <data-dir>/data/tls/fingerprint

重新显示初始管理员密码

只要它还没被更改，就仍在磁盘上：

sudo cat <data-dir>/initial-admin-password

这里出现 "No such file or directory" 意味着密码已被更改：这是预期行为，文件在那一刻被删除。

非交互与离线安装

两种不同的需求，同一套机制：在运行 apt 之前预先填好回答，使任何问题都不再显示。存储这些回答的系统叫 debconf，通过命令行来驱动。

1. 预填三个回答

每个问题一行，正是交互式安装中的那三个：

echo 'uversion-server uversion-server/data-dir string /srv/uversion' | sudo debconf-set-selections
echo 'uversion-server uversion-server/db-on-data-dir boolean true'   | sudo debconf-set-selections
echo 'uversion-server uversion-server/licence-key string UV-XXXX-XXXX-XXXX' | sudo debconf-set-selections

2. 无对话框安装

回答既已就位，安装便不再询问任何内容：

sudo DEBIAN_FRONTEND=noninteractive apt install -y ./uversion-server_latest_amd64.deb

离线变体：给出密钥而非激活码

在没有互联网访问的网络上，激活码无法交换：没有可联系的对象。届时请在一台联网的工作站上从您的账户区域取回完整许可证密钥，放到机器上，在上面的第 1 步用文件路径代替激活码。这是唯一的出路，并且是预留好的：

echo 'uversion-server uversion-server/licence-key string /root/uversion-licence.key' | sudo debconf-set-selections

该文件必须只含密钥本身，占一行，周围没有引号或其他内容。误指向整个 config.toml 会被明确拒绝。第三种可能的形式，若您不想放文件：把完整密钥直接粘贴进该值，代替路径。

在任何有风险的操作之前备份

要复制三样东西，它们的备份方式各不相同：数据库（账户、修订、锁、权限）、 数据目录（文件内容），以及位于别处、人们会忘记的配置。

1. 数据库

它以 postgres 账户来备份，绝不以 root：PostgreSQL 没有名为 root 的“角色”（它对数据库账户的称呼），因此直接以 root 运行的命令会以一条看似故障、实则是身份问题的消息失败。

如果您对关于数据库的问题回答了否（默认），它位于系统集群中：

sudo -u postgres pg_dump -Fc uversion > /tmp/uversion.dump

如果您回答了是，它位于一个独立的集群中，必须显式命名，否则您会备份错的那个：

pg_lsclusters                                    # repere la ligne "uversion" et sa version
sudo -u postgres pg_dump --cluster <major>/uversion -Fc uversion > /tmp/uversion.dump

2. 数据目录

停止服务，以获得一致的副本：

sudo systemctl stop uversion-server
sudo tar czf /tmp/uversion-data.tar.gz -C <data-dir> .
sudo systemctl start uversion-server

3. 配置

/etc/uversion/ 不跟随数据目录，也不在数据库中：它带有许可证密钥、为会话签名的密钥以及数据库密码。没有它，在新机器上的恢复会以一个全新的密钥重新开始，于是整个团队会一下子被断开连接，并且需要重新申请许可证。

sudo tar czf /tmp/uversion-etc.tar.gz -C /etc uversion

卸载

警告： 这些命令会删除您的仓库、历史记录、用户账户和配置。如果您想能够回退，请先完成上一节的备份。

1. 清除软件包

清除会移除二进制文件、服务、配置回答、/etc/uversion/ 和系统账户 uversion。它刻意保留数据库和数据目录：这些是您的文件，包管理器不会背着您把它们抹掉。

sudo systemctl stop uversion-server 2>/dev/null
sudo apt purge -y uversion-server

不要在此次卸载之后运行 sudo apt autoremove --purge。 PostgreSQL 是作为这个软件包的依赖进来的，因此 apt 会提议移除它，而它自己的清除会抹掉机器上所有的数据库，包括与 uVersion 毫无关系的那些。软件包在安装时设有防护，但这条命令仍应避免。

2. 遵循清除刚刚打印出的序列

数据库和数据目录仍然还在，而移除它们的命令取决于您的机器：正因如此，它们是被计算并打印到屏幕上，而不是写在这里。

请阅读清除所显示的内容：接下来的步骤取决于您的机器。 卸载脚本会查看您的数据库实际所在之处，然后把针对您这一情形的确切命令序列打印到屏幕上，连路径和版本号都包含在内。请遵循那一份，而不是通用食谱：一条大概其的命令要么摧毁错误的数据库，要么什么都没做。

此序列所规避的两个陷阱，也解释了它为何是为您计算，而不是从指南里抄来的：

不指明集群的 DROP DATABASE 会瞄准错误的数据库服务器。 如果您对关于数据库的问题回答了是，您的数据库位于一个专用集群中：默认命令面向的是系统集群，找不到可删除的东西，却让您以为已经删好了。
未先移除集群就 rm -rf 数据目录会留下一个仍向系统声明存在的幽灵数据库，它会在机器每次启动时索要一个已不存在的目录而失败。顺序很重要： pg_dropcluster --stop，然后再删除目录。

3. 删除恢复套件

若磁盘必须脱离您的控制（转售、租赁归还、报废）就要做这一步：该目录含有您的 许可证密钥、JWT 密钥和数据库密码，并且按设计会在清除后留存。

sudo rm -rf <data-dir>/recovery

4. 确认系统账户已消失

它通常已被清除移除。若已消失，此命令无任何作用：

sudo deluser --system uversion 2>/dev/null || true

5. 检查没有任何残留

四项检查，每项旁边都附上您应当看到的内容：

systemctl status uversion-server         # "not-found" ou "inactive"
ls /etc/uversion 2>&1                    # "No such file"
id uversion                              # "no such user"
sudo -u postgres psql -tAc "SELECT 1 FROM pg_database WHERE datname='uversion';"   # (vide)