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

Служба запускается, а затем останавливается. Проверьте Event Viewer:

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 (postinst в Linux, как и install.ps1 в Windows) может автоматически вернуть 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 по умолчанию слушает HTTPS на порту 8443.

Нет отката на HTTP по порту 8080: два режима взаимоисключающие Сервер слушает либо HTTPS на tls.https_port (по умолчанию 8443), либо простой HTTP на server.port, никогда оба сразу. Простой 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). Самые частые причины:

Первое подключение не подтверждено: настольный клиент показывает окно Verify server identity с отпечатком SHA-256. Сравните его с тем, что сообщил вам администратор, затем нажмите 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
```
Если ничего не слушает, проверьте, что [tls] disabled = false в config.toml (это значение по умолчанию). Напоминание: когда 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. Вероятно, вы указали родительскую папку или подпапку. Укажите корень workspace, тот, что содержит папку .uversion/.

Создание репозитория из существующей папки завершается ошибкой

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

Папка уже является workspace. Вы пытаетесь не создать новый, а снова открыть этот: используйте Open Local Repository.

Клиент отказывается открыть workspace

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

Эта папка была клонирована другой учётной записью, имя которой записано в .uversion/config.toml. Это происходит при копировании workspace с одной машины на другую или при смене учётной записи в клиенте. Отказ сделан намеренно: работа под чужой личностью привела бы к блокировкам и коммитам, приписанным не тому человеку. Клонируйте свою собственную копию. Если это действительно ваша папка, но другая учётная запись тоже ваша, переключитесь на неё в селекторе учётных записей.

Путь к движку Unreal отклонён

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. Он ищет его только на три уровня в глубину под корнем workspace, а дальше исчезает без сообщения. Переместите проект ближе к корню.

Unreal отклоняет отправку моего кода

Code files must be submitted from the uVersion desktop client

Плагин отклоняет checkin файлов .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 не преодолевает это препятствие, заполнять её бесполезно. Запустите настольный клиент, войдите под учётной записью, которой принадлежит workspace, и плагин будет работать через него.

Блокировка файлов завершается ошибкой

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 требует пустую или несуществующую папку назначения. Очистите её, удалите или укажите другой путь. Не путайте с настольным клиентом, где выбираемая вами папка является родительской: внутри неё он создаёт подпапку с именем workspace.

Сессия истекла

Клиент сначала пытается молча обновить токен. Если не удаётся, он возвращается на страницу входа с баннером. Просто введите пароль заново. Если это повторяется без конца, обычно это означает, что учётная запись была деактивирована на стороне сервера, либо явный выход отозвал токены всех ваших клиентов.

Полный сброс

См. страницы Удаление в Ubuntu/Debian или Удаление в Windows, чтобы начать с чистой установки.