Arkvory

클라이언트 및 프로토콜 ​

Arkvory에는 스토리지와 액세스 모델이 하나뿐이지만, 접근하는 방법은 여러 가지입니다. 각 방법은 도구가 이미 사용하는 클라이언트 또는 프로토콜입니다. 어떤 방법을 사용하든 데이터는 모두 Arkvory 아티팩트로 저장됩니다. 따라서 같은 권한, 할당량, SHA-256 검증, 보존 규칙, 백업, 미러가 적용됩니다.

이 페이지는 Arkvory와 통신하는 모든 방법과 각 방법의 용도, 허용하는 자격 증명을 정리합니다. 작업에 맞는 도구를 고를 때 참고하세요.

개요 ​

방법주소용도자격 증명
웹 콘솔https://arkvory.example/console/브라우저에서 리포지토리 탐색, 업로드와 다운로드, 사용자·키·백업 관리사용자 이름과 비밀번호로 로그인하거나 서비스 키 사용
arkvoryctl 명령줄/api/v1CI 스크립트, 재개 가능한 업로드와 다운로드, 경로 기반 파일, 승격, 백업파일이나 환경 변수의 키(Bearer로 전송)
TypeScript SDK/api/v1Node.js나 브라우저에서 TypeScript 또는 JavaScript로 만드는 자체 도구콜백에서 가져오는 키(Bearer로 전송)
REST API/api/v1/...모든 언어에서의 통합Authorization: Bearer <key>만 허용
컨테이너 레지스트리(OCI)/v2/Docker, Podman, Buildx, containerd, Helm 차트, ORAS 아티팩트키를 비밀번호로 쓰는 Basic(docker login) 또는 Bearer
Git LFS/lfs/<repository>git 리포지토리의 대용량 파일, Unity와 Unreal을 위한 파일 잠금키를 비밀번호로 쓰는 Basic(git 자격 증명 도우미) 또는 Bearer
npm 레지스트리/npm/<repository>/Unity Package Manager의 범위 지정 레지스트리, npm publish, npm installBearer(.npmrc의 _authToken, .upmconfig.toml의 token) 또는 Basic _auth
경로 기반 원시 파일/api/v1/repositories/<repository>/raw/<path>curl -T 또는 PowerShell을 사용한 단일 요청Authorization: Bearer <key>만 허용
웹훅내 수신자 URL리포지토리가 바뀌면 배포나 작업 시작모든 요청의 HMAC 서명

/v2, /lfs, /npm 아래의 경로는 각 프로토콜의 사양을 따릅니다. 이 경로는 /api/v1의 OpenAPI 문서에 포함되지 않으며, 오류를 해당 클라이언트가 기대하는 형식으로 보고합니다.

자격 증명 ​

공개 상태 확인을 제외한 모든 요청에는 자격 증명이 필요합니다. Arkvory는 다음 종류를 허용합니다.

종류형태발급처일반적인 용도
개인용 액세스 토큰pat_...사용자가 콘솔에서 만듭니다. 범위는 read 또는 read-write입니다. 만료됩니다(기본 90일, 최대 365일).개발자: 워크스테이션의 Unity, git, Docker
서비스 키arkvory_...관리자가 서비스 계정에 발급하며, 리포지토리별로 허용할 작업을 정확히 지정합니다CI/CD, 배포 에이전트, 빌드 서버
파일 키임의의 시크릿서버 키 파일(ARKVORY_KEYS_FILE)에서 리포지토리별로 read 또는 write를 지정합니다. 소유자 키는 관리도 할 수 있습니다설치 소유자, 기존 통합
세션dps_...콘솔 로그인. 12시간 동안 유효합니다대화형 콘솔 작업
다운로드 링크?token=이 있는 URL아티팩트 하나에 대해 만듭니다. 60초~24시간키가 없는 사람에게 파일 하나 전달

프로토콜마다 다른 점은 키를 보내는 방식뿐입니다.

  • /api/v1, CLI, SDK, 원시 파일은 Authorization: Bearer <key>를 사용합니다.
  • /v2, /lfs, /npm은 HTTP Basic도 허용합니다. 사용자 이름은 검사하지 않으며, 비밀번호가 Arkvory 키입니다. docker login, git 자격 증명 도우미, npm _auth가 이 방식으로 자격 증명을 보냅니다.
  • 읽기 전용 개인용 토큰은 데이터를 절대 변경하지 않습니다. Git LFS 배치 요청은 다운로드에도 POST를 사용하므로, 이 토큰으로도 Git LFS 객체를 다운로드할 수 있습니다.

토큰과 키를 만드는 방법은 계정 및 키를, 헤더에 대한 자세한 내용은 인증을 참조하세요.

어떤 방법을 사용해야 하나요? ​

작업권장하는 방법
CI에서 빌드 아티팩트를 업로드하고 네트워크 장애 후 이어서 진행arkvoryctl upload 또는 arkvoryctl put
CI에서 UPack 패키지 게시arkvoryctl packages publish
서버에 "최신 1.4 릴리스" 배포arkvoryctl packages download --range ^1.4 --stage release
아무것도 설치하지 않고 셸 스크립트에서 작은 파일이나 중간 크기 파일을 경로에 저장curl -T 또는 PowerShell로 원시 파일 사용
컨테이너 이미지나 Helm 차트 저장컨테이너 이미지
게임의 텍스처, 모델, 레벨을 git 호스트 밖에 보관Git LFS
프로젝트 간에 Unity 패키지 공유Unity 및 npm 패키지
자체 도구나 웹 인터페이스 개발TypeScript SDK
Python, Go, C# 등 다른 언어에서 통합REST API
둘러보기, 사용자·키·백업 관리웹 콘솔

선택 기준은 다음과 같습니다.

  • 대용량 파일(수 GB 이상): arkvoryctl 또는 SDK를 사용하세요. 파트로 나누어 업로드하며, 중단 후에도 이어서 진행합니다. 단일 PUT 요청(원시 파일, Git LFS 객체, npm publish, Docker 레이어)은 실패하면 처음 바이트부터 다시 시작합니다.
  • 도구가 이미 특정 프로토콜을 사용하는 경우: 그 프로토콜을 사용하세요. Docker, git, Unity에는 추가 소프트웨어가 필요하지 않습니다.
  • 읽기만 하는 머신: 읽기 전용 토큰이나 읽기 작업만 허용한 서비스 키를 부여하세요.

공통 규칙 ​

HTTPS. 모든 클라이언트에 HTTPS를 사용하세요. CLI와 SDK는 루프백(localhost, 127.0.0.1, [::1])을 제외하고 일반 HTTP를 거부합니다. Docker에는 신뢰할 수 있는 인증서가 필요합니다. Git은 모든 요청과 함께 키를 보냅니다. HTTPS를 참조하세요.

같은 스토리지. 이미지 레이어, Git LFS 객체, npm tarball, 원시 파일은 모두 아티팩트입니다. 이들은 리포지토리 할당량과 설치 용량에 포함되고, 저장될 때 SHA-256으로 검증되며, 백업에 포함됩니다.

읽기 게이트웨이와 미러. 읽기 게이트웨이는 GET과 HEAD만 받습니다. 미러는 다른 설치에 있는 리포지토리의 읽기 전용 복사본입니다.

방법읽기 게이트웨이에서미러에서
/api/v1, CLI, SDK읽기만 가능읽기 가능. 변경은 거부됨(409 mirror_read_only)
컨테이너 레지스트리PullPull. push는 거부됨
Git LFS지원하지 않음(배치 요청이 POST임)clone과 fetch. push와 잠금은 거부됨
npm 레지스트리설치와 검색설치와 검색. publish는 거부됨
원시 파일GET과 HEADGET과 HEAD

읽기 게이트웨이와 미러를 참조하세요.

Arkvory · ProAnimaStudio