uVersion
简体中文
下载 →

Wiki

故障排除

服务器端和用户端常见问题的解决方法：服务无法启动、激活码被拒绝、PostgreSQL、TLS、客户端和 Unreal 编辑器的消息。

服务无法启动

Linux：systemctl start 失败 
sudo journalctl -u uversion-server -n 100 --no-pager

常见原因：

  • PostgreSQL 未运行： sudo systemctl status postgresql
  • 丢失数据库密码： postinst 会使用 --reconfigure 重新生成配置 (sudo dpkg-reconfigure uversion-server)
  • 端口 8443 被占用：请参阅下方的专门章节
Windows：错误 1053 或 1067

服务启动后立即停止。请检查事件查看器：

Get-EventLog -LogName Application -Source uVersionServer -Newest 50

常见原因：

  • 缺少 CONFIG_PATH 环境变量： 通常由安装程序在 HKLM\SYSTEM\CurrentControlSet\Services\uVersionServer\Environment 中设置
  • PostgreSQL 未运行： Get-Service postgresql*

激活码被拒绝

  • 请确认该激活码未在其他机器上使用过 （每个激活码都与首次安装的 server-ID 绑定）。请从您的 账户页面申请新的激活码。
  • 检查到 licence.uversion.io 的连接： curl -I https://licence.uversion.io/api/v1/health
  • 如果您想在卸载后在新机器上重复使用某个激活码， 请联系支持团队以释放之前的 server-ID。

无法连接 PostgreSQL

uVersion 服务无法连接到数据库。请先独立于 uVersion 测试数据库本身。

在 Linux 上：

sudo -u postgres psql -c "SELECT 1;"

在 Windows 上：

& "C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -h 127.0.0.1 -c "SELECT 1;"

如果 PostgreSQL 有响应但超级用户密码丢失， uVersion 安装程序（Linux 的 postinst 以及 Windows 的 install.ps1）可以 自动将 PostgreSQL 恢复为 trust 模式、重置密码，然后 恢复原始配置。请重新运行。

在 Linux 上：

sudo dpkg-reconfigure uversion-server

在 Windows 上：普通的安装命令即可，只要保存的密码缺失或被拒绝， 重置就会自动触发。

iwr https://uversion.io/downloads/server/install.ps1 -UseBasicParsing | iex

-Reconfigure 参数只用于额外重写已存在的 config.toml， 并且需要命令的完整形式：上面的简短形式不会向脚本传递任何参数。请参阅 在 Windows 上安装。

端口 8443 已被占用

uVersion 默认在 8443 上监听 HTTPS。

没有回退到 8080 的 HTTP：两种模式互斥 服务器要么在 tls.https_port（默认 8443）上监听 HTTPS， 要么在 server.port 上监听纯 HTTP，绝不会同时监听两者。纯 HTTP 仅在 TLS 被显式禁用（[tls] disabled = true）时存在，在这种情况下 8443 完全不再监听。因此：“8443 上没有任何监听”并不意味着“已回退到 8080”， 而是意味着“TLS 已禁用”或“服务器未启动”。而在正常安装中，8080 被占用与 uVersion 无关。

要查明是哪个进程占用了该端口，在 Linux 上：

sudo ss -tlnp | grep 8443

在 Windows 上，分两步：占用进程，然后是它的名称。

Get-NetTCPConnection -LocalPort 8443 | Select-Object OwningProcess, State
Get-Process -Id <PID>

要更改 TLS 端口，请编辑 config.toml：

[tls]
https_port = 9443

然后重启服务。

客户端拒绝 TLS 连接

uVersion 使用在客户端通过 TOFU 锁定的自签名证书（参见 TLS 指纹）。 最常见的原因：

  • 首次连接未确认：桌面客户端会显示带有 SHA-256 指纹的 Verify server identity 窗口。请将其与管理员告知您的值进行比较，然后点击 Trust this server。在 CLI 中，等效命令是 uversion trust <url>：它是交互式的，会显示服务器 通告的指纹并等待您在键盘上确认。 例如在脚本中，可添加 --yes 以跳过此确认。
  • 指纹已更改（红色警告）：服务器已重新安装并 重新生成了证书。请通过其他渠道与管理员确认，然后：
    • 桌面端：在红色对话框中点击 Trust new fingerprint
    • CLI：uversion mistrust <url> 然后 uversion login <url>
  • 服务器未提供 HTTPS：请检查它是否确实在 8443 上监听。 在 Linux 上： 
    ss -tlnp | grep 8443
    在 Windows 上： 
    Get-NetTCPConnection -LocalPort 8443 -State Listen
    如果没有任何监听，请检查 config.toml 中的 [tls] disabled = false（这是默认值）。提示：当 TLS 被禁用时，服务器会 切换到纯 HTTP，8443 完全不再监听，不存在双重监听。
  • 在服务器端重新显示指纹，在 Linux 上： 
    sudo cat /var/lib/uversion/data/tls/fingerprint
    在 Windows 上： 
    Get-Content "C:\ProgramData\uVersion\data\tls\fingerprint"

用户端：客户端和编辑器的消息

以上章节涉及服务器。以下是用户会遇到的阻碍， 附有其显示的确切消息以及应采取的措施。

我无法创建仓库

Admin role required

创建仓库仅限服务器的超级管理员。 project_admin 角色不够：它管理委派给它的项目，但不创建项目。 请让您的超级管理员创建仓库，然后将您任命为其管理员。

打开本地文件夹失败

Not a uVersion repository

所选文件夹不包含 .uversion/config.toml。您可能指定了父文件夹或 子文件夹。请指向工作区根目录，即包含 .uversion/ 文件夹的那个。

从现有文件夹创建仓库失败

This folder is already a uVersion repository - use "Open Local Repository" instead.

该文件夹已经是一个工作区。您不是要创建新的，而是要重新打开它： 请使用 Open Local Repository。

客户端拒绝打开工作区

This workspace belongs to '<owner>'. Clone your own copy instead.

此文件夹由另一个账户克隆，其名称记录在 .uversion/config.toml 中。 这发生在将工作区从一台机器复制到另一台，或在客户端中切换账户时。此拒绝是 有意的：以另一身份操作会产生归属于错误人员的锁和提交。 请克隆您自己的副本。如果这确实是您的文件夹，而另一个账户也是您的， 请在账户选择器中切换到它。

Unreal Engine 路径被拒绝

Invalid Unreal Engine path: '...' is not a recognizable engine install

客户端需要 Unreal 安装的根目录，即同时包含 Engine/Build/BatchFiles 和 Engine/Binaries 的目录。例如 C:\Program Files\Epic Games\UE_5.6，而不是 Engine 子文件夹，也不是您的 项目文件夹，也不是快捷方式。

某个 Unreal 操作无法启动

Unreal Engine path not configured. Please set it first.

自动检测没有找到任何内容。请通过 Unreal 栏的 “ … ” 菜单、 Set Engine Path... 项设置路径。没有其他入口：栏本身既没有 输入框，也没有 Browse 按钮。

如果 Unreal 栏完全不存在，那就不是引擎路径的问题：客户端没有 找到 .uproject。它只在工作区根目录下三层深度内查找， 超出后就会无提示地消失。请将项目移动到更靠近根目录的位置。

Unreal 拒绝我的代码提交

Code files must be submitted from the uVersion desktop client

插件拒绝 .cpp、.h、.hpp、.c 和 .cs 文件的签入：桌面客户端在提交前会编译并发布编辑器二进制文件。请从客户端提交您的代码。

You have code files checked out (...): submit your code from the uVersion desktop client first

一种更令人困惑的变体，甚至会影响不写代码的人：只要有一个由您签出的 代码文件，也会阻止您的内容提交，即使该文件不属于本次提交。请打开桌面客户端的 Pending 标签、Your locks 部分，对滞留在那里的代码文件执行 Checkin 或 Revert。参见 Unreal Engine 插件。

Unreal 看不到服务器

编辑器会显示一条通知，要求启动桌面客户端。这是预期的：uVersion 服务器默认 自签名，而 Unreal 无法验证自签名证书。Revision Control Login 窗口的 登录表单无法越过这一障碍，填写它没有用。请启动桌面 客户端，用拥有该工作区的账户登录，插件就会通过它工作。

文件锁定失败

Failed to acquire locks for {n} file(s). Another user may have them checked out.

其他人持有这些锁。Pending 标签的 Other Users' Locks 部分会说明 是谁，并为每一行提供 Request Release 按钮。有用的提示：锁永不 过期，没有人会仅仅因为时间流逝而释放它。管理员可以强制 解锁，该操作会记录在审计中。

命令行克隆拒绝该文件夹

Directory '...' already exists and is not empty

uversion clone 需要一个空的或不存在的目标文件夹。请将其清空、删除，或指向 另一个路径。请勿与桌面客户端混淆，在桌面客户端中您选择的文件夹是 父目录：它会在其中创建一个以工作区命名的子文件夹。

会话已过期

客户端会先尝试静默续订令牌。如果无法续订，它会带着横幅返回登录页面。 只需重新输入您的密码即可。如果这种情况不断发生，通常是因为 账户已在服务器端被停用，或者一次显式注销已撤销您所有客户端的令牌。

完全重置

要从干净的安装重新开始，请参阅Ubuntu/Debian 卸载 或 Windows 卸载 页面。