Wiki

TLS 指纹

服务器在安装时生成自签名证书。每个客户端在首次连接时确认其指纹。

安全吗？ 安全。所有连接和所有文件传输都经过加密：网络上没有人能读取在你的电脑和服务器之间传输的内容。你的数据保留在你自己的基础设施上：不由任何第三方托管，也不经过 uVersion。只有持有各自登录凭据的团队成员才能访问。而且一旦连接出现异常，软件会检测到并立即阻止，而不会悄无声息地放行。

uVersion 默认通过 HTTPS 加密所有连接，无需域名，也无需购买证书。服务器在首次启动时生成证书，管理员将其指纹分享给团队，每台电脑确认一次。这就是 TOFU 模型：首次接触即信任，就像 SSH 第一次让你确认某台机器的指纹一样。此后，客户端在每次连接时都会比对指纹，并拒绝与已经改变的服务器通信。

服务器指纹，还是校验和？ 两者都是 SHA-256，这正是让所有人混淆的地方。服务器指纹标识你服务器的证书：用于辨认你的电脑所连接的那台机器。校验和用于验证下载的文件是否完好。本页只讨论前者。

操作分两步：在服务器上找到指纹一次，然后在每台电脑上确认它，每台电脑一次。本页其余部分是参考资料，等到某天有变化时再读。

查找指纹

它在安装结束时显示，紧邻管理员密码。此后有三种找回方式，从最简单到最手动。

1. 从浏览器，无需安装任何东西

服务器提供一个无需认证的信息页面：打开 https://服务器:8443/api/server-info。不需要 sudo，不需要 SSH 访问，也不需要 uVersion 账户：这是最短的路径。

浏览器会先显示一条安全警告。这是正常且预期之中的：证书是自签名的，没有任何公共机构认识它。继续前往站点即可。

首次打开服务器地址时浏览器的安全警告，其中带有可在自签名证书情况下继续的链接或按钮。

随后显示的页面是一段原始数据。指纹是 tls_fingerprint 字段的值：一串以冒号分隔的十六进制字节。你要传给团队的，正是这整串字符。

在浏览器中打开的 /api/server-info 页面：version、build_sha、设为 self_signed 的 tls_mode，以及承载以冒号分隔的十六进制 SHA-256 指纹的 tls_fingerprint 字段。

这个页面显示的是服务器所声称的内容 既然你是管理员，用它向团队发布指纹再合适不过。但它本身并不构成验证：拦截连接的人会返回他自己的值。真正起保护作用的，是每台电脑将服务器实际出示的指纹，与你通过另一条渠道（内部聊天、口头、团队 wiki）传达的值进行比对。命令行客户端其实两者都做，并在二者不一致时向你发出警告。

2. 从服务器日志

服务器每次启动都会把指纹重新写入日志。无论你把数据目录放在哪里，这个方法都有效：

# Linux (paquet .deb)
sudo journalctl -u uversion-server | grep "TLS fingerprint" | tail -1

# Docker
docker compose logs server | grep "TLS fingerprint" | tail -1

3. 在 `fingerprint` 文件中

该文件写在证书旁边，也就是 config.toml 中 [tls] cert_path 所指的目录。下面的路径是默认值：如果你移动了数据目录，请先在配置中查看 cert_path。

# Linux, dossier de donnees par defaut
sudo cat /var/lib/uversion/data/tls/fingerprint

# Windows
Get-Content "C:\ProgramData\uVersion\data\tls\fingerprint"

# Docker : chemin fixe par l'entrypoint, sur le volume de donnees
docker compose exec server cat /data/tls/fingerprint

在客户端确认

每台电脑一次，一劳永逸。具体操作取决于工具。

桌面客户端

像平常一样填写登录界面。首次连接到该服务器时，系统不会让你登录，而是弹出一个 Verify server identity 窗口。把显示的指纹与管理员分享的进行比对，若一致就点击 Trust this server：连接随即会自动继续。若不一致，点 Cancel，然后去问清楚原因。

CLI `uversion`

uversion trust https://uversion.example.com:8443          # interactif
uversion trust https://uversion.example.com:8443 --yes    # sans question (CI, script)
uversion trusted                                          # liste les serveurs epingles
uversion login <url>                                      # propose l'epinglage si besoin

uversion trust 是交互式的：它显示主机、服务器版本、TLS 模式和指纹，提醒你与管理员传达的内容比对，然后等待一个 y/N 确认。任何其他回答都会取消，不固定任何东西。--yes 选项会跳过这个提问，用于脚本或持续集成：它会在无人查看的情况下固定，只应在你掌控的可信网络中使用。

当服务器尚未固定时，uversion login 会自行提出同样的确认：在一台电脑上，通常无需事先运行任何命令。

Unreal Engine 插件

在打开项目之前，在终端中运行一次 uversion trust <url>，或者先从桌面客户端登录：插件会沿用它的固定（pin）。编辑器内的原生对话框计划稍后支持。

Rider 插件

它在底层使用 uversion。运行一次 uversion trust <url>，Rider 即可通过。

如果指纹发生变化

客户端会拒绝连接并明确告知。不要出于习惯就重新确认：先向管理员核实，而且要通过与该连接不同的渠道。有三种可能的解释：服务器重装、有意的证书轮换，或有人插在你的电脑和服务器之间。得到解释之后：

桌面客户端：警告对话框中的 Trust new fingerprint 按钮。
CLI：uversion mistrust <url>，然后 uversion login <url>。

重新生成证书

证书默认有效期为十年：无需安排任何续期。若要强制轮换（疑似泄露、审计要求）：

# Linux
sudo rm /var/lib/uversion/data/tls/cert.pem /var/lib/uversion/data/tls/key.pem
sudo systemctl restart uversion-server

# Windows
Remove-Item "C:\ProgramData\uVersion\data\tls\cert.pem"
Remove-Item "C:\ProgramData\uVersion\data\tls\key.pem"
Restart-Service uVersionServer

服务器会在启动时重新生成证书和新指纹。请通知团队并重新分享：每台电脑都需要重新确认。

提供自己的证书

你可以放入自己的证书，由你的内部 PKI 或某个公共机构签发。没有需要开启的选项：启动时，服务器会重用位于 [tls] cert_path 和 [tls] key_path 路径上的文件，并重新计算指纹。这只有在你的服务器拥有 DNS 名称时才成立：没有任何机构会为私有 IP 地址签发证书。

三个格式约束，每一个都已经让某人搭进去一个晚上：

证书文件包含完整的链，叶证书在前（certbot 的 fullchain.pem 正是这种形式）；
私钥是未加密的 PEM：用口令保护的密钥不会被解密；
在重启之前放入两个文件。如果只找到一个，服务器会认为状态不完整，并在剩下的那个之上重新生成一对自签名证书。

这对各台电脑意味着什么：

浏览器：只要用证书所带的名称打开服务器，就不再有警告。用它的 IP 地址打开，警告依旧存在。
已固定的电脑：指纹会变，因此每台都会看到上面描述的警告，需要重新确认。请在更换前通知，否则整个团队会在同一时刻遇到一条被拦截的提示。
续期：每次续期都会改变指纹并重启这套流程，而且证书只在服务器启动时才被重新读取。若用 90 天的公共证书，一年就是六次全团队的重新确认：在这项成本被消化之前，请优先选择较长的有效期。