개념

이 페이지는 다른 페이지에서 사용하는 용어를 설명합니다. 각 항목은 짧으며 주제를 자세히 다루는 페이지로 연결됩니다. 한 줄 정의는 용어집을 참조하세요.

설치 환경과 서비스

설치 환경 하나는 서버 하나입니다. 하나의 PostgreSQL 데이터베이스와 함께 세 개의 Arkvory 서비스를 실행합니다:

부분	역할
API	HTTP 서버: HTTP API, 웹 콘솔, 그리고 컨테이너, Git LFS, npm용 레지스트리입니다. 보존 규칙 적용과 물리적 정리도 실행합니다.
워커	백그라운드 작업: 대용량 업로드를 마무리하고 미러를 동기화합니다.
백업 에이전트	백업 보관소로의 예약 백업입니다.
PostgreSQL	카탈로그: 아티팩트, 패키지, 리비전, 계정, 키, 작업입니다.

파일 콘텐츠는 데이터베이스가 아니라 서버의 로컬 디렉터리에 있습니다. 모든 구성 요소는 설치 루트(Windows에서는 C:\ProgramData\ProAnima\Arkvory, Linux에서는 /opt/proanima-arkvory)에 있습니다. 서비스는 로그인한 사용자 없이 시작되고, 충돌이나 응답 중단 후 다시 시작됩니다(자가 복구).

설치 환경은 고가용성 클러스터가 아닙니다. 서버가 멈추면 클라이언트는 기다렸다가 전송을 계속합니다. 설치 선택을 참조하세요. Linux에서는 서버 두세 대로 고가용성 클러스터를 구성할 수 있습니다.

리포지토리

리포지토리는 콘텐츠를 위한 이름이 붙은 공간입니다. 자체 액세스 규칙, 자체 스토리지 정책(할당량과 보존), 선택적으로 미러 원본을 가집니다. 리포지토리 이름은 1~64자이며, 소문자 라틴 문자, 숫자, -, _로 구성되고 문자나 숫자로 시작합니다.

리포지토리를 만드는 별도의 명령은 없습니다. 그룹에 이름에 대한 액세스가 부여되거나 서비스 계정 정책이 이름을 지정하는 순간 리포지토리가 존재합니다. 새 설치 환경에는 첫 리포지토리를 위한 releases가 있습니다. 리포지토리를 참조하세요.

아티팩트

아티팩트는 저장된 파일 하나입니다. 변경할 수 없습니다: 바이트가 절대 바뀌지 않습니다. UUID, 이름(/나 \가 없는 최대 240자), 크기, SHA-256 체크섬을 가집니다. 새 콘텐츠는 새 아티팩트를 만들며, 기존 아티팩트를 대체하지 않습니다.

아티팩트는 서버가 바이트가 선언된 크기와 SHA-256에 맞는지 확인한 뒤에만 표시됩니다. 다운로드는 같은 바이트를 반환하며, 체크섬은 강력한 ETag로 사용됩니다. Arkvory의 나머지 모든 것은 아티팩트 위에 있습니다. 패키지 버전, 경로의 리비전, 컨테이너 레이어, Git LFS 객체는 모두 아티팩트입니다.

업로드

업로드는 만들어질 아티팩트를 예약합니다. 파일의 이름, 크기, SHA-256과 함께, 요청을 안전하게 반복할 수 있게 하는 Idempotency-Key로 업로드 세션을 만듭니다. 그런 다음 바이트를 보냅니다:

• 작은 파일과 중간 크기 파일은 요청 하나로; 또는
• 큰 파일은 파트로 나누어 보냅니다. 서버가 파트 크기를 정합니다: 최소 8 MiB이며, 업로드에 10,000개를 넘는 파트가 필요하지 않도록 매우 큰 파일에서는 두 배로 늘립니다. 파트는 1 GiB를 넘지 않습니다. 각 파트는 자체 SHA-256을 가지며, 반복된 파트는 문제가 되지 않습니다.

그런 다음 업로드를 완료합니다. 서버가 전체 파일을 검사하고 게시합니다. 큰 파일의 경우 워커가 클라이언트가 따라가는 완료 작업으로 업로드를 완료합니다. SDK와 명령줄 클라이언트는 16 GiB 이상의 파일에 이 방식을 선택합니다. 업로드 세션은 7일 동안 유지됩니다. 중단된 업로드는 서버가 이미 가진 파트부터 이어서 진행합니다. 관리자가 더 낮은 ARKVORY_MAX_OBJECT_BYTES를 설정하지 않으면 최대 객체 크기는 10,000 GiB입니다.

명령줄 클라이언트와 SDK가 이 모든 것을 대신 처리합니다. 전송과 업로드 참조를 참조하세요.

패키지

패키지는 Arkvory에 등록된 UPack 아카이브입니다. 식별자는 그룹, 이름, SemVer 버전으로 구성되며, 예를 들어 acme / game-server / 1.4.2입니다. 그룹은 식별자의 일부입니다: 다른 그룹에 있는 같은 이름의 두 패키지는 서로 다른 패키지입니다. 게시된 버전은 절대 바뀌지 않으며, 같은 버전에 다른 콘텐츠를 게시하면 거부됩니다.

배포 에이전트는 정확한 버전, ^1.4 같은 버전 범위, 또는 스테이지의 최신 버전으로 패키지를 요청합니다. 사전 릴리스 버전은 요청할 때만 나타납니다. 패키지를 참조하세요.

경로 기반 파일

경로 기반 파일은 builds/game/1.4/Setup.exe 같은 주소를 가지며 아티팩트를 가리킵니다. 경로에 새 바이트를 저장하면 경로에 새 리비전(1, 2, 3 등)이 생깁니다. 이전 리비전은 기록에 남아 있으며, 하나를 복원할 수 있습니다: 복원하면 예전 콘텐츠로 새 리비전이 추가됩니다. 같은 바이트를 다시 저장해도 아무것도 추가되지 않습니다.

경로는 최대 1,024자이며 /를 구분자로 사용하고, 비어 있는 세그먼트, . 또는 .. 세그먼트, :가 없어야 합니다. 변경은 기대하는 리비전을 지정합니다. 다른 변경이 먼저 있었다면 서버는 409로 응답합니다. 아직 존재하지 않는 경로에는 0을 사용하세요. 파일과 경로와 원시 파일을 참조하세요.

레이블, 메타데이터, 컬렉션, 첨부 파일

바이트를 건드리지 않고 아티팩트를 설명할 수 있습니다:

항목	규칙
레이블	nightly나 tested 같은 최대 32개의 짧은 태그입니다.
메타데이터	최대 32개의 텍스트 필드. 키는 최대 64자, 값은 최대 1,024자입니다.
컬렉션	아티팩트를 묶는 이름 있는 집합입니다.
첨부 파일	빌드에서 같은 리포지토리의 다른 아티팩트로 향하는 최대 32개의 링크: 매니페스트, SBOM, 서명, 보고서 또는 기타 파일입니다.

레이블, 메타데이터, 컬렉션은 하나의 리비전 집합으로 함께 변경됩니다. 첨부 파일은 자체 리비전과 기록을 가집니다.

스테이지와 승격

스테이지는 qa, release, prod 같은 빌드에 붙는 통제된 표시입니다. 스테이지 이름은 소문자, 숫자, ., _, -를 사용하며(최대 32자), 아티팩트는 최대 16개의 스테이지를 가질 수 있습니다. 스테이지를 변경하려면 별도의 권한 artifact.promote가 필요하며, 각 변경은 행위자, 시각, 코멘트와 함께 기록됩니다.

승격은 바이트를 다시 보내지 않고 다른 리포지토리에 빌드를 게시합니다. copy는 원본을 유지하고, move는 원본 리포지토리에서 빌드도 제거합니다. 승격을 반복하면 이미 존재하는 사본을 반환합니다. 확인은 스테이지와 버전 범위가 가리키는 빌드를 찾습니다. 승격을 참조하세요.

계정, 그룹, 권한

사람은 계정을 사용합니다. 계정에는 이름(3~64자)과 비밀번호(12~128자)가 있습니다. 관리자 계정은 계정과 그룹을 관리합니다. 계정은 그룹에 속하며, 그룹에는 리포지토리에 대한 read 또는 write("읽기 및 쓰기") 액세스가 부여됩니다. 권한은 요청마다 다시 계산되므로 변경 사항이 즉시 적용됩니다.

자동화는 대신 서비스 계정을 사용합니다. 서비스 계정의 정책은 리포지토리마다 upload.create나 content.read 같은 정확한 작업을 나열하며, 그 키는 정책을 좁힐 수만 있습니다. 서버는 모든 작업을 검사합니다. 콘솔에서 버튼을 숨기는 것은 보호가 아닙니다. 계정 및 액세스와 인증을 참조하세요.

키와 토큰

모든 요청은 자격 증명을 함께 보냅니다. 직접 만드는 네 종류와, 기본 제공되는 한 종류가 있습니다:

자격 증명	용도	수명
콘솔 세션	이름과 비밀번호로 로그인한 사용자	12시간
개인용 액세스 토큰	한 사람의 스크립트와 도구	기본 90일, 최대 365일
서비스 키	CI/CD와 배포 에이전트	기본 90일, 최대 365일
다운로드 링크	키 없이 누군가에게 아티팩트 하나를 전달	60초~24시간(기본 1시간)
복구 키	설치 환경 자체	만료되지 않음

서비스 키는 한 번 발급되고 한 번만 표시되며, 활성화한 뒤에만 사용할 수 있습니다. 키를 교체하고(새 키를 발급한 뒤 이전 키를 정리) 영구적으로 폐기할 수 있습니다. 인증을 참조하세요.

소유자와 복구 키

소유자는 첫 번째 계정입니다. 관리자이며 releases에 대한 write 액세스를 가진 그룹 arkvory-owners의 구성원입니다. Windows 설치 프로그램이 소유자를 만들며, Linux와 Docker에서는 콘솔에서 복구 키로 만듭니다.

복구 키는 설치 프로그램이 설치 루트의 config/bootstrap-token.txt에 기록하는 비밀입니다. 첫 소유자와 계정을 만들고, 서비스 계정과 그 위임을 관리하고, 백업을 실행하고, 업데이트를 요청할 수 있습니다. 설치 도구가 서버에서 이 키를 읽습니다. CI나 일상 작업용이 아닙니다: 서버에 보관하고 복사하지 마세요. 설치 선택과 보안을 참조하세요.

보존, 할당량, 정리

스토리지 정책은 리포지토리에 속합니다. 각 패키지(또는 각 패키지와 채널)의 최근 N개 빌드를 유지하고, 레이블과 스테이지를 제거로부터 보호하고, 아무것도 제거하기 전에 최소 기간을 기다리며, 경고 및 심각 임계값이 있는 할당량을 설정할 수 있습니다. 관리자가 켜기 전까지는 꺼져 있습니다. 아티팩트 제거는 먼저 논리적으로 이루어집니다: 바이트는 유예 기간(기본 24시간) 동안 디스크에 남아 있다가, 물리적 정리가 백그라운드에서 작은 배치로 서버를 멈추지 않고 공간을 확보합니다.

서버는 또한 업로드가 절대 사용하지 않는 여유 디스크 공간 예약분(기본 1 GiB)을 유지합니다. 스토리지를 참조하세요.

백업

백업 에이전트는 데이터베이스와 모든 게시된 콘텐츠를 백업 보관소로 복사합니다. 백업 보관소는 다른 디스크나 네트워크 공유에 있는 폴더입니다. 완전한 복사본 하나가 복원 지점입니다. 에이전트는 모든 지점을 검증하고, 지점에 보존 규칙을 적용하며(기본적으로 일간 7개, 주간 4개, 월간 6개), 보존에서 유지하도록 지점을 고정할 수 있게 합니다. 일일 일정은 관리자가 일정 및 보존에서 켜기 전까지 꺼져 있습니다.

복원은 서버에서 실행하는 명령입니다. 빈 데이터베이스와 빈 스토리지 디렉터리에 기록합니다. 백업을 참조하세요.

미러와 읽기 게이트웨이

미러는 두 번째 설치 환경이 첫 번째 설치 환경인 원본을 따라가며 유지하는 리포지토리의 읽기 전용 복사본입니다. 변경을 거부하고 다운로드를 제공합니다. 원본을 잃으면 운영자가 미러를 분리하고 미러는 일반 리포지토리가 됩니다. 전환은 수동이며 자동 장애 조치가 아닙니다. 미러를 참조하세요.

읽기 게이트웨이는 같은 스토리지에서 GET과 HEAD에만 응답하는 추가 API 프로세스입니다. 쓰기 서버와 게이트웨이는 하나의 다운로드 대역폭 예산을 공유합니다. 읽기 게이트웨이를 참조하세요.

다음에 볼 내용

1. 빠른 시작: Arkvory를 설치하고 첫 파일을 업로드합니다.
2. 계정 및 액세스: 사용자, 그룹, 토큰, 서비스 키입니다.
3. HTTP API 개요: 모든 통합에 필요한 규칙입니다.
4. 용어집: 모든 용어의 짧은 정의입니다.