문제 해결

서비스가 시작되지 않음

sudo journalctl -u uversion-server -n 100 --no-pager

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

활성화 코드가 거부됨

• 코드가 다른 컴퓨터에서 사용되지 않았는지 확인하세요 (각 코드는 최초 설치 시의 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를 수신합니다.

어떤 프로세스가 포트를 점유하고 있는지 확인하려면, 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에 기록되어 있습니다. 이는 워크스페이스를 한 컴퓨터에서 다른 컴퓨터로 복사하거나 클라이언트에서 계정을 전환할 때 발생합니다. 이 거부는 의도적입니다: 다른 ID로 작업하면 잘못된 사람에게 귀속되는 잠금과 커밋이 생성됩니다. 자신의 복사본을 클론하세요. 그것이 정말 자신의 폴더이고 다른 계정도 자신의 것이라면, 계정 선택기에서 그쪽으로 전환하세요.

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 제거 페이지를 참조하세요.