디렉터리 트리
배포 에이전트나 CI 작업에는 디렉터리 전체가 필요한 경우가 많습니다. 게임 빌드, 도구 모음, 구성 트리 같은 것입니다. arkvoryctl tree는 디렉터리를 하나의 ZIP 아티팩트로 게시하고, 이를 폴더로 가져오고, 폴더를 이와 대조하고, 다른 파일만 복구합니다. 아티팩트는 일반 ZIP 파일입니다. 콘솔, API, 모든 ZIP 도구에서 읽을 수 있으며, 백업도 다른 아티팩트와 똑같이 보관합니다.
이 명령은 무료 코어에 포함됩니다. 업로드 및 다운로드와 같은 권한이 필요합니다. 업로드 및 다운로드를 참조하세요.
디렉터리 게시
arkvoryctl tree push ./Build/Game --name game-1.4.zip --label release| 옵션 | 의미 |
|---|---|
--name NAME.zip | 아티팩트 이름. 기본값: 폴더 이름 뒤에 .zip. 이름은 .zip으로 끝나야 합니다. |
--label TAG | 아티팩트의 레이블 |
--file METADATA.json | 레이블과 메타데이터(upload와 동일) |
--compress | 항목을 압축합니다(deflate). 지정하지 않으면 파일이 있는 그대로 저장됩니다. |
결과에는 아티팩트의 id, size, sha256과 entries에 파일 수가 표시됩니다.
- 같은 폴더에서는 같은 아카이브가 만들어집니다. 파일은 경로 순서로 정렬되고, 모든 항목의 날짜는 1980-01-01이며, 파일 시스템 속성은 하나만 유지됩니다. 소유자가 실행할 수 있는 파일은 모드 755, 그 밖의 파일은 644가 됩니다. 변경되지 않은 폴더를 다시 푸시하면 같은 바이트와 같은 SHA-256이 나옵니다.
- 중단. 아카이브는 폴더 옆(
.<folder>.arkvory-tree.zip)에 만들어지고 체크포인트와 함께 파트 단위로 업로드됩니다. Ctrl+C나 네트워크 장애 후에는 같은 명령을 다시 실행하세요. 같은 아카이브를 만들고 업로드를 재개합니다. 성공하면 두 파일 모두 삭제됩니다. - 거부되는 항목. 폴더 안의 심볼릭 링크, 정션, 장치, 파이프(
tree_entry_unsupported), Windows에서 사용할 수 없는 이름(unsafe_name), 대소문자만 다른 두 이름(case_collision). 빈 폴더는 유지되지 않습니다. - 저장 또는 압축.
--compress를 지정하지 않으면 각 파일의 바이트가 아카이브 안에서 연속된 범위를 이룹니다. 그래서 서버가 파일 하나를 바이트 범위로 제공할 수 있고, 복구할 때 다른 파일의 바이트만 정확히 전송됩니다.--compress를 지정하면 아카이브가 작아지고, 복구되는 파일은 사용자의 컴퓨터에서 압축이 풀립니다.
디렉터리 가져오기
arkvoryctl tree pull 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./Game- 비어 있거나 없는 폴더에는 아카이브 전체를 받습니다. 아카이브는 체크포인트와 함께 폴더 옆에 다운로드되므로, 중단된 pull은 멈춘 지점부터 재개됩니다. SHA-256을 확인한 후 파일을 대상 옆의 새 폴더에 풀고, 그 폴더가 대상을 대신합니다.
- 파일이 있는 폴더는 트리와 같아집니다. 서버에 목차가 있으면 다른 파일만 각각의 바이트 범위로 다운로드하고, 트리에 없는 파일은 삭제합니다. 목차가 없으면 아카이브 전체를 다운로드하고, 압축을 푼 폴더가 이전 폴더를 대신합니다.
상위 폴더가 있어야 합니다. 대상 안의 파일은 한 단계로 교체됩니다. 옆에 있는 임시 파일에 쓰고, 확인한 다음 이름을 바꿉니다. 파일을 읽는 프로그램에는 이전 버전 또는 새 버전 중 하나만 보입니다.
디렉터리 대조
arkvoryctl tree verify 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./Game결과에는 missing(없는) 파일, mismatched(크기나 SHA-256이 다른) 파일, 트리에 없는 extra(추가) 파일이 나열되고, 각각의 개수가 counts에 들어갑니다. 각 목록에는 최대 1000개의 경로가 표시됩니다. 없는 파일과 다른 파일이 없으면 ok는 true입니다. 추가 파일은 영향을 주지 않습니다. 종료 코드는 ok가 true이면 0, 그렇지 않으면 5입니다.
디렉터리 복구
arkvoryctl tree repair 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./Game복구는 없는 파일과 다른 파일을 모두 다시 쓰고 추가 파일은 그대로 둡니다. 목차가 있으면 해당 파일의 항목만 다운로드합니다. 결과의 fetchedBytes는 아카이브에서 읽은 바이트 수를 나타냅니다. 목차가 없으면 먼저 아카이브 전체를 다운로드합니다.
목차
아카이브가 게시되면 서버의 워커가 이를 한 번 읽고 각 파일의 경로, 크기, SHA-256, 아카이브 안에서 바이트가 있는 위치를 기록합니다. 이름이 .zip 또는 .upack으로 끝나는 아티팩트가 대상입니다. 이 작업이 끝나기 전이나 아카이브의 인덱스를 만들 수 없는 경우에는 명령이 대신 아카이브 전체를 사용합니다.
목차를 지원하는 서버는 GET /api/v1/capabilities의 tree에서 zip-tree를 제공합니다(arkvoryctl doctor 참조). 이전 버전의 서버에서는 명령이 아카이브 전체를 사용합니다. 목차 자체는 getArtifactTree 작업입니다. status는 ready, pending, 또는 reason이 있는 unavailable입니다.
reason | 의미 |
|---|---|
not_archive | 아티팩트 이름이 .zip 또는 .upack으로 끝나지 않음 |
invalid_archive | 파일이 읽을 수 있는 ZIP 아카이브가 아님 |
unsafe_entry | 경로가 아카이브를 벗어나거나, 항목이 링크 또는 특수 파일임 |
encrypted_entry | 항목이 암호화되어 있음 |
duplicate_entry | 두 항목의 경로가 같음(대소문자를 무시했을 때 같은 경우 포함) |
unsupported_method | 항목이 stored나 deflate가 아닌 압축 방식을 사용함 |
crc_mismatch | 항목의 바이트가 아카이브에 기록된 체크섬과 일치하지 않음 |
too_many_entries | 항목이 100,000개를 초과함 |
too_large | 압축을 푼 크기가 100 GiB를 초과함 |
파일 확인 방법
- 모든 파일은 제자리에 놓이기 전에 확인됩니다. 목차가 있으면 크기와 SHA-256이 게시된 아카이브에서 서버가 계산한 값과 일치해야 합니다. 목차가 없으면 먼저 아카이브 전체의 SHA-256을 확인한 다음 각 파일의 크기와 CRC-32를 확인합니다. 일치하지 않으면 명령이
checksum_mismatch(종료 코드 5)로 중지되고, 폴더 안의 파일은 그대로 남습니다. - 폴더 밖에는 아무것도 쓰지 않습니다. 아카이브와 서버에서 읽은 경로는 신뢰할 수 없는 데이터로 취급됩니다. 폴더를 벗어나는 경로는
path_outside_root로 거부됩니다. 파일로 가는 경로에 있는 폴더 안의 링크는 절대 따라가지 않습니다. Windows에서 사용할 수 없는 이름(CON,aux.txt,a:b, 끝의 점이나 공백)은 모든 시스템에서unsafe_name으로 거부되므로, 트리는 Windows와 Linux에서 같은 의미를 갖습니다. - 모드. 아카이브에서 푼 파일은 아카이브에 실행 가능으로 표시되어 있으면 모드 755, 그렇지 않으면 644가 됩니다(Linux와 macOS). 범위로 복구한 파일은 교체되는 파일의 모드를 유지합니다.
더 빠른 전송
tree push의 아카이브 전체 업로드와 tree pull의 아카이브 전체 다운로드는 upload, download와 같은 전송을 사용합니다. 서버가 같은 확장을 제공하면 전송 확장이 있는 클라이언트 모듈이 이를 맡을 수 있습니다. 아카이브는 일반 ZIP 그대로이며, SHA-256과 모든 파일은 위에서 설명한 대로 확인됩니다. 모듈이 없거나 서버가 확장을 제공하지 않으면 arkvoryctl은 자체 전송을 사용합니다.