업데이트

ProAnimaStudio는 허브를 통해 Arkvory의 각 안정 릴리스를 알립니다. 서버는 허브에 설치할 수 있는 버전을 묻고, 릴리스를 다운로드하고, 서명을 확인한 다음 설치합니다. 직접 시작하거나 자동 업데이트를 켜지 않으면 아무것도 설치되지 않습니다. 자동 업데이트는 기본적으로 꺼져 있습니다.

업데이트는 롤링 업데이트가 아닙니다. 서비스가 잠시 중지되고 실행 중인 전송이 중단됩니다. 이어서 진행할 수 있는 클라이언트는 전송을 계속합니다. 유지 관리 시간에 업데이트하세요.

업데이트 작동 방식

• 릴리스. 버전이 x.y.z인 게시된 안정 릴리스만 설치됩니다. 사전 릴리스, 브랜치, 임의 주소, 이전 버전은 거부됩니다.
• 허브가 결정합니다. 서버는 6시간마다 허브에 자신에게 승인된 버전을 묻습니다. 허브는 새 버전을 보류하거나 단계적으로 공개합니다. 파일 자체는 허브가 발급하는 단기 링크를 통해 GitHub에서 가져옵니다. 이때 서버에 GitHub 토큰은 필요하지 않습니다.
• 서명. 각 릴리스 매니페스트는 ProAnimaStudio가 서명합니다. 서버는 설치된 프로그램에 내장된 공개 키로 서명을 확인한 다음 아카이브의 SHA-256을 확인합니다. 서명되지 않았거나 변경된 릴리스는 허브에서 왔든 GitHub에서 왔든 설치되지 않습니다. 허브는 무결성에 대해 신뢰되지 않습니다.
• 호스트 업데이터. 서버의 타이머(Linux에서는 arkvory-update.timer, Windows에서는 ProAnimaArkvoryUpdate 작업)가 매분 업데이터를 실행합니다. 콘솔의 요청을 처리하고, 마지막 확인 후 6시간이 지나면 릴리스를 확인하며, 정해진 시간에 자동 업데이트를 시작합니다. 자동 설치가 꺼져 있어도 확인은 실행됩니다.

업데이트가 하는 일

1. 서비스가 계속 실행되는 동안 릴리스를 다운로드하고 서명과 SHA-256을 확인한 다음, 설치 루트의 releases/<version>/에 파일을 풉니다. Compose에서는 새 이미지를 빌드합니다.
2. 릴리스가 데이터베이스 스키마를 변경하면 먼저 새 백업을 만들고 검증합니다. 업데이트 전 백업을 참조하세요.
3. 백업 에이전트, 워커, API를 중지합니다. 각각 최대 120초 동안 마무리할 시간이 주어집니다.
4. 설치를 새 버전으로 전환합니다. 스키마 변경이 있으면 이때 마이그레이션이 실행됩니다.
5. API와 워커를 시작하고 API가 연속 세 번 준비 상태를 보고할 때까지 기다립니다. 그런 다음 백업 에이전트를 시작합니다. 에이전트는 확인 대상이 아닙니다. 약 90초 안에 보고하지 않으면 업데이트는 경고를 출력하고 그대로 유지됩니다.
6. 통계가 켜져 있으면 익명 updated 이벤트를 허브로 보냅니다. 이 단계의 실패가 업데이트를 되돌리지는 않습니다.

이전 버전은 releases/에 남아 있습니다. 모든 데이터, 키, 구성은 그대로 유지됩니다.

업데이트 확인

관리자로 콘솔에 로그인하고 업데이트를 여세요. 페이지에는 설치된 버전, 최신 안정 릴리스, 마지막 확인가 표시됩니다. 지금 허브에 물으려면 지금 확인를 선택하세요. 로그인하면 더 새로운 릴리스가 있을 때 업데이트 보기이 있는 배너가 알려 줍니다.

확인이 실패하면(예: 네트워크 액세스 없음) 페이지는 마지막으로 찾은 릴리스를 유지하고 오래된 것일 수 있다고 표시합니다. 확인은 6시간 후 또는 지금 확인를 선택할 때 다시 시도됩니다.

서버에서는 arkvory status --root <root>가 설치된 버전, 자동 업데이트 설정, 고정을 표시합니다.

페이지에 호스트 업데이터가 연결되지 않았다고 표시되면 arkvory updates-connect --root <root>를 실행하세요. 오래된 릴리스에서 업데이트된 설치의 콘솔과 업데이트 타이머를 연결합니다. 업데이터가 보고를 중단했다고 페이지에 표시되면 타이머나 작업이 5분 동안 실행되지 않은 것입니다. 문제 해결을 참조하세요.

직접 설치

콘솔에서

1. 업데이트를 열고 최신 안정 릴리스에 원하는 버전이 표시되는지 확인하세요.
2. 업데이트 설치을 선택하세요. 대화 상자에 버전이 표시되고 전송이 중단될 수 있다고 경고합니다.
3. 이 릴리스 설치을 선택하세요. 콘솔은 확인한 버전과 SHA-256을 보냅니다. 그 사이 게시된 바이트가 변경되었다면 요청은 거부됩니다.
4. 기다리세요. 요청은 즉시 접수되며 호스트 업데이터가 1분 안에 처리합니다. 서비스가 다시 시작되는 동안 페이지가 연결을 잃을 수 있지만 스스로 다시 연결합니다. 두 번째 요청을 보내지 마세요.

버전이 고정되어 있으면 콘솔은 설치를 거부합니다. 버전 고정을 참조하세요.

명령으로

sudo arkvory update --root /opt/proanima-arkvory
sudo arkvory update --root /opt/proanima-arkvory --version 1.2.3

--version이 없으면 명령은 허브가 이 서버에 승인한 버전을 설치합니다. --version을 사용하면 설치된 버전보다 새로워야 하는 해당 안정 버전을 정확히 설치합니다. 업데이트가 실패하면 명령은 오류 코드와 함께 종료됩니다. 각 플랫폼에서 명령을 실행하는 방법은 구성에 있습니다.

자동 업데이트

자동 업데이트를 켜는 방법은 세 가지입니다.

• 콘솔에서 업데이트를 열고 자동 업데이트 아래의 호환되는 안정 릴리스 자동 설치을 선택한 다음 유지 관리 시간(UTC)를 고르고 설정 저장를 선택하세요.
• 서버에서: arkvory configure --root <root> --enable-updates.
• 스크립트로 설치할 때: install.sh는 --automatic, install.ps1은 -AutomaticUpdates를 사용하세요.

콘솔 또는 arkvory configure --root <root> --disable-updates로 끌 수 있습니다.

규칙	값
시간 창	선택한 UTC 시간. 기본값은 03:00~03:59 UTC입니다. 시간은 콘솔에서만 설정합니다
시도	UTC 기준 하루에 최대 한 번, 성공하든 실패하든 마찬가지입니다. 놓친 시간 창은 그날 나중에 보충되지 않습니다
건너뛰는 경우	버전이 고정되었거나, 마지막 확인이 실패했거나, 더 새로운 릴리스를 알 수 없는 경우
릴리스	마지막 확인에서 허브가 승인한 가장 새로운 릴리스

업데이트 시간 창 밖에 백업 일정을 잡으세요. 업데이트는 백업 에이전트를 중지하며, 실행 중인 백업은 중단되고 다시 대기열에 추가됩니다.

업데이트 전 백업

데이터베이스 스키마를 변경하지 않는 업데이트는 백업을 만들지 않습니다. 예약된 백업에 의존하세요.

데이터베이스 스키마를 변경하는 릴리스는 새로 검증된 백업이 있을 때만 설치됩니다. 업데이터는 서비스가 아직 실행 중일 때 다음을 수행합니다.

1. 백업 에이전트에 새 백업을 요청하고 백업이 만들어지고 검사될 때까지 기다립니다. 최대 6시간을 기다립니다. 이 시간 동안 콘솔에는 릴리스가 설치 중이라고 표시됩니다.
2. 그런 다음에야 서비스를 중지하고 데이터베이스를 마이그레이션한 다음 새 버전을 시작합니다.

백업에는 세 가지가 필요합니다. 사용 가능한 연결된 백업 보관소, 온라인 상태인 백업 에이전트, 이전에 완료된 백업이 최소 하나. 테라바이트 규모의 첫 전체 백업은 계획된 작업이며, 업데이트의 부작용이 아닙니다. 세 가지 중 하나라도 없으면 업데이트는 아무것도 변경되기 전에 거부됩니다. 서비스는 계속 실행되고, 콘솔에는 설치가 거부되었다고 표시되며, 자동 업데이트는 다음 날 다시 시도합니다. 보관소를 연결하고 첫 백업을 실행하세요. 백업을 참조하세요.

스냅샷 이후, 서비스 중지 이전에 도착한 변경 사항은 그 백업에 포함되지 않습니다. 백업은 새 버전이 마이그레이션 후 실패할 때만 중요합니다. 롤백 및 복구를 참조하세요.

직접 만든 백업으로 업그레이드

내장 보관소가 없으면 데이터베이스와 전체 스토리지의 백업을 직접 만들고 검증한 다음, 이를 기록한 파일을 업데이터에 제공하세요.

sudo arkvory upgrade --root /opt/proanima-arkvory --version 1.2.3 --backup-record /secure/backup-record.txt

이 파일은 직접 작성한 메모입니다. 업데이터는 파일이 존재하는지만 확인하며, 백업이 완전하다는 것을 증명하지는 않습니다. 저널과 롤백은 update와 같습니다. 이 명령은 앞으로만 진행하며, 버전이 다른 버전으로 고정되어 있으면 거부됩니다.

롤백 및 복구

자동 롤백

• 스키마 변경 없음. 새 버전이 준비 상태가 되지 않으면 업데이터는 이를 중지하고, 이전 릴리스를 복원하고, 준비 상태를 기다린 다음 Update failed; previous release restored를 보고합니다.
• 스키마 변경, 마이그레이션 실패. 마이그레이션은 하나의 트랜잭션에서 실행됩니다. 실패한 마이그레이션은 롤백되고 이전 릴리스가 변경되지 않은 스키마에서 다시 시작됩니다.
• 스키마 변경, 마이그레이션 후 새 버전이 시작되지 않음. 이전 릴리스가 새 스키마를 읽을 수 없으므로 자동으로 되돌릴 방법이 없습니다. 업데이터는 저널을 maintenance-required로 표시하고 백업 지점을 알려 줍니다. 원인을 해결한 다음 업데이트를 마무리하는 recover를 실행하세요. 또는 journal.json에 명시된 백업 지점을 복원하고 이전 버전을 실행하세요.

Arkvory에는 다운그레이드 명령이 없습니다. 이 명령은 오래된 버전을 거부합니다. 이전 버전은 자동 롤백용으로만 releases/에 남아 있습니다.

중단된 업데이트 복구

업데이트 중 충돌이나 정전이 발생하면 설치 루트에 잠금 operation.lock과 기록 journal.json 두 가지가 남습니다. 복구하기 전까지 새 업데이트와 대부분의 명령은 실행을 거부합니다. 상태를 알기 전에는 잠금을 삭제하지 마세요.

진행 중인 업데이트가 없었고(저널이 완료되었거나 없음) 잠금을 잡은 프로세스가 더 이상 실행되지 않으면, 예를 들어 중지된 업데이트 확인이나 클러스터에서 격리된 서버가 잡은 잠금이면, 다음 명령이 잠금을 스스로 제거하고 경고를 기록합니다.

1. 새 실행이 시작되지 않도록 업데이트 타이머를 중지하세요. Linux에서는 sudo systemctl stop arkvory-update.timer. Windows에서는 Disable-ScheduledTask -TaskName ProAnimaArkvoryUpdate. 타이머가 없는 Compose 설치에서는 예약 작업을 중지하세요.
2. 업데이터 프로세스가 실행되고 있지 않은지 확인하세요. journal.json과 로그를 저장하세요.
3. 그런 다음에야 operation.lock을 삭제하세요.
4. arkvory recover --root <root>를 실행하세요. 저널이 허용하는 방향으로 진행합니다.
   • 스키마 변경이 없는 업데이트이거나 마이그레이션이 시작되기 전이면 이전 버전으로 되돌아갑니다.
   • 마이그레이션이 시작된 후라면 앞으로 진행합니다. 반복해도 안전한 마이그레이션을 다시 실행하고 새 버전을 시작합니다.
5. 서비스가 준비되었는지 확인하고 테스트 다운로드가 작동하는지 확인하세요. 타이머를 다시 시작하세요. sudo systemctl start arkvory-update.timer 또는 Enable-ScheduledTask -TaskName ProAnimaArkvoryUpdate.

업데이트를 시작한 콘솔 요청이 아직 저장되어 있으면 arkvory updates-reset --root <root>가 이를 제거합니다. 상태를 확인한 뒤에만 실행하세요. 잠금은 제거하지 않습니다.

버전 고정

다른 버전으로의 모든 업데이트를 중지하려면 버전을 고정하세요.

sudo arkvory configure --root <root> --pin                  # pin the installed version
sudo arkvory configure --root <root> --pin --version 1.2.3  # pin another stable version
sudo arkvory configure --root <root> --unpin

버전이 고정되어 있는 동안:

• 자동 업데이트는 아무것도 하지 않습니다.
• 콘솔은 릴리스 설치를 거부하고 서버에서 고정을 해제하라고 요청합니다.
• arkvory update는 고정된 버전을 설치하며 다른 --version은 거부합니다.
• 확인은 계속 실행되므로 콘솔에는 여전히 더 새로운 릴리스가 표시됩니다.

오래된 버전을 고정한 뒤 더 새로운 버전을 설치하려면 더 새로운 버전을 고정하고 arkvory update를 실행하세요. 스크립트로 설치하면서 고정할 수도 있습니다. install.sh는 --pin, install.ps1은 -Pin을 사용하세요.

허브, 채널 및 통계

서버가 허브로 보내는 것

시점	전송 내용
업데이트 확인, 6시간마다 또는 요청 시	설치된 버전, 운영 체제(linux 또는 windows), 프로세서(x86_64 또는 aarch64), 채널과 함께 프로젝트 arkvory의 업데이트를 요청합니다. 통계가 켜져 있으면 무작위 설치 ID가 담긴 X-Install-Id 헤더가 추가됩니다
업데이트 완료, 통계가 켜져 있음	설치 ID, 새 버전, 운영 체제, 프로세서, 채널이 담긴 updated 이벤트 하나
릴리스 다운로드	허브가 GitHub 링크로 응답합니다. 파일은 그곳에서 가져옵니다

키, 계정, 호스트 이름, 저장된 콘텐츠는 전송되지 않으며 자격 증명이 허브에 도달하지 않습니다. 설치 ID는 설치만 식별하는 무작위 값입니다. 프로젝트에 따르면 허브는 IP 주소, 이름, 콘텐츠를 저장하지 않습니다. 허브는 또한 사용자가 콘솔에서 보내는 피드백을 받습니다. 이는 사용자의 별도 작업입니다.

통계가 꺼져 있으면 서버는 설치 ID와 이벤트를 보내지 않습니다. 그러면 허브는 버전을 모든 설치에 공개한 경우에만 해당 버전을 제공합니다.

옵션

설정	기본값	변경 방법
통계	켜짐	콘솔: ProAnimaStudio에 익명 통계 보내기는 자동 업데이트 아래에 있습니다. 명령: --statistics off 또는 --statistics on
채널	stable	--update-channel beta는 ProAnimaStudio가 더 일찍 제공하는 버전을 받고, --update-channel stable은 되돌립니다
허브 주소	https://hub.proanima.net	--hub-url https://hub.example은 자체 허브, --hub-off는 GitHub만 사용합니다. 주소는 HTTPS를 사용해야 합니다

모두 arkvory configure --root <root> 옵션이며 다시 시작하지 않고 적용됩니다. 설정은 config/hub.json에 저장됩니다. 허브 주소를 변경하면 서비스를 다음에 다시 시작한 후 콘솔이 피드백을 보내는 위치도 바뀝니다.

허브에 연결할 수 없을 때

허브가 응답하지 않으면(네트워크 장애, 시간 초과 또는 서버 오류) 업데이터는 대신 GitHub의 최신 안정 릴리스를 읽고 경고를 기록합니다. 같은 서명과 SHA-256 검사를 수행합니다. 허브의 거부(4xx 상태), 누락된 파일 또는 잘못된 서명은 오류이며 대체 수단이 없습니다.

GitHub의 릴리스에 인증이 필요하면 리포지토리 콘텐츠를 읽을 수 있는 토큰이 담긴 github-token.txt 파일을 설치 루트에 만드세요. 관리자만 이 파일을 읽을 수 있습니다. 업데이터가 이 파일을 사용하며 서비스는 사용하지 않고, 명령 옵션으로 전달되지도 않습니다. --hub-off를 사용하면 업데이터는 항상 GitHub를 사용합니다.

서버는 hub.proanima.net, api.github.com, github.com 및 GitHub 다운로드 호스트에 대한 HTTPS 액세스가 필요합니다.

오프라인 설치

인터넷에 접속할 수 없는 서버는 릴리스를 확인할 수 없습니다. 그러면 업데이트 페이지에 확인이 실패했다고 표시됩니다. 서비스에는 영향을 주지 않습니다. 대신 파일에서 업데이트하세요.

1. 인터넷에 접속할 수 있는 컴퓨터에서 서버 플랫폼용 키트(Arkvory-Linux.tar.gz 또는 Arkvory-Windows.zip)를 다운로드하세요. SHA-256을 해당 릴리스의 release-checksums.json과 비교하세요.

2. 키트를 서버로 복사하고 압축을 푸세요. 디렉터리에는 arkvory-release.json, arkvory-runtime.zip, arkvory-setup.mjs가 들어 있습니다. 키트에는 서명 파일이 없습니다. 같은 릴리스 페이지에서 arkvory-release.json.sig를 다운로드하여 arkvory-release.json 옆에 두세요. 그러면 업데이터가 서명도 검증합니다.

3. 디렉터리의 절대 경로로 업데이트를 실행하세요.

   sudo arkvory update --root /opt/proanima-arkvory --artifact /media/release

   & 'C:\Program Files\ProAnima\Arkvory\arkvory.ps1' update --root C:\ProgramData\ProAnima\Arkvory --artifact D:\release

업데이터는 아카이브의 SHA-256을 매니페스트와 비교하여 확인합니다. 서명은 arkvory-release.json.sig가 매니페스트 옆에 있을 때만 확인합니다. 로컬 디렉터리는 직접 선택한 것이므로 업데이트에 서명이 필요하지 않습니다. 서명이 없으면 1단계에서 키트를 release-checksums.json과 비교한 것이 출처를 증명하는 유일한 방법입니다. 스키마 변경에 대한 규칙도 같습니다. 먼저 검증된 백업이 필요합니다.

네이티브 패키지나 Arkvory-Setup-x64.exe는 자체 릴리스를 포함하므로 인터넷 액세스가 필요하지 않습니다. Compose 업데이트는 호스트에서 이미지를 빌드합니다. 기본 이미지 node:24.21.0-bookworm-slim이 아직 호스트에 없을 때만 Docker Hub가 필요합니다.

플랫폼별 업데이트

Windows

설치된 버전 위에 더 새로운 Arkvory-Setup-x64.exe를 실행하세요. Setup은 데이터를 찾고 소유자를 다시 묻지 않습니다. 콘솔에서 업데이트하는 것과 같은 방식으로 프로그램, 서비스, 데이터베이스 릴리스를 업데이트합니다. 오래된 버전의 Setup은 거부되고, 같은 버전의 Setup은 서비스를 복구합니다. 업데이트가 실행 중일 때는 Setup을 시작하지 마세요. 설치 프로그램은 영어와 러시아어로만 제공됩니다. 콘솔이나 명령으로 업데이트할 수도 있습니다.

Linux 패키지

릴리스 페이지에서 더 새로운 패키지를 다운로드하고 첫 번째와 같은 방식으로 설치하세요. sudo apt install ./Arkvory-amd64.deb 또는 sudo dnf install ./Arkvory-x86_64.rpm. apt 또는 dnf 리포지토리는 없으므로 apt upgrade와 dnf upgrade는 새 버전을 찾지 못합니다. 패키지의 구성 단계는 패키지 안의 릴리스로 명령과 같은 업데이트를 실행합니다. 실행 중인 서비스는 전환될 때까지 계속 응답합니다.

업데이트가 거부되면(예: 스키마 변경에 필요한 백업이 없는 경우) 이전 버전이 계속 실행되고 구성 단계가 실패합니다. 원인을 해결한 다음 Debian과 Ubuntu에서는 sudo dpkg --configure -a로, RPM 시스템에서는 같은 패키지를 다시 설치하여 단계를 반복하세요.

콘솔에서 업데이트한 후 패키지 관리자가 표시하는 버전이 실행 중인 버전보다 오래된 것일 수 있습니다. 실행 중인 버전보다 오래된 패키지는 거부됩니다.

스크립트 설치

스크립트 설치에는 arkvory 명령이 없습니다. 콘솔에서 업데이트하거나 설치의 Node.js로 manage.mjs update를 실행하세요. 구성을 참조하세요.

Docker Compose

콘솔에서 또는 manage.mjs update로 업데이트하세요. 업데이터는 새 버전의 이미지를 빌드하고 backup, worker, api 컨테이너를 교체하며 볼륨은 유지합니다. root가 없는 Compose 설치에는 예약된 updates-poll이 필요합니다. Docker Compose를 참조하세요.

업데이트 후

• arkvory status --root <root>를 확인하고 콘솔에 로그인하세요.
• 더 이상 필요 없는 버전은 releases/에서 삭제하세요. 현재 버전과 journal.json에 명시된 이전 버전은 유지하세요. 오래된 버전, 다운로드 파일, 스테이징은 업데이터가 삭제하지 않습니다.
• 업데이트는 스크립트 설치의 Node.js, PostgreSQL 프로그램, 운영 체제, 컨테이너 엔진을 업그레이드하지 않습니다. 이들은 별도로 업데이트하세요. PostgreSQL 메이저 버전 변경은 그 자체로 마이그레이션이므로 먼저 백업하세요.

문제 해결

표시되는 내용	해결 방법
페이지에 호스트 업데이터가 연결되지 않았다고 표시됩니다	유지 관리 시간에 arkvory updates-connect --root <root>를 실행하세요
페이지에 업데이터가 보고를 중단했다고 표시됩니다	타이머나 작업을 확인하세요. Linux에서는 systemctl status arkvory-update.timer와 journalctl -u arkvory-update. Windows에서는 ProAnimaArkvoryUpdate 작업과 logs\updater.log. operation.lock이 남아 있지 않은지 확인하세요
릴리스 확인이 실패했습니다	서버에서 허브와 GitHub에 대한 액세스를 확인하세요. 서비스에는 영향을 주지 않습니다
백업이 필요하여 설치가 거부되었습니다	보관소를 연결하고, 첫 백업을 기다린 다음, 상태를 다시 확인하세요. 업데이트 전 백업을 참조하세요
업데이트가 실패했습니다	다시 시도하기 전에 journal.json, 업데이터 로그, 서비스 로그를 읽어 보세요
수동 복구가 필요합니다	중단된 업데이트 복구를 따르세요
요청이 대기하는 동안 설정이 변경되었습니다	페이지를 새로 고치고 요청을 다시 보내세요
Installation is locked	다른 작업이 실행 중이거나 하나가 중단되었습니다. 중단된 업데이트 복구를 참조하세요
Interrupted deployment; use recover after inspecting journal.json	이전 업데이트가 끝나지 않았습니다. 먼저 복구하세요
Downgrades are forbidden	버전이 설치된 버전보다 새롭지 않습니다
Version is pinned	고정을 해제하거나 고정된 버전을 설치하세요
Interrupted update request; inspect installation and use updates-reset	콘솔의 요청이 접수되었지만 끝나지 않았습니다. 상태를 확인한 다음 updates-reset을 실행하세요

더 많은 도움말은 문제 해결과 자가 복구에 있습니다.