환경 변수
Arkvory는 이름이 ARKVORY_로 시작하는 환경 변수로 구성합니다. 이 페이지는 서버 프로세스, 명령줄 클라이언트, 설치 스크립트가 읽는 모든 변수를 나열합니다.
값을 가져오는 위치
설치 프로그램은 서버 설정을 설치 루트의 config/runtime.json 파일 하나에 기록합니다. 각 서비스의 런처가 이 파일을 읽어 값을 API, 워커, 백업 에이전트에 전달합니다. 각 키는 ARKVORY_로 시작해야 하며, 각 값은 문자열이어야 합니다.
json
{
"ARKVORY_HOST": "127.0.0.1",
"ARKVORY_PORT": "8080",
"ARKVORY_CAPACITY_BYTES": "10995116277760",
"ARKVORY_DATABASE_URL": "postgresql://arkvory:PASSWORD@127.0.0.1:54329/arkvory",
"ARKVORY_DATA_DIR": "/opt/proanima-arkvory/data",
"ARKVORY_KEYS_FILE": "/opt/proanima-arkvory/config/keys.json",
"ARKVORY_MAX_DOWNLOADS": "32"
}이 파일에는 데이터베이스 비밀번호가 들어 있습니다. 설치 프로그램이 설정한 접근 권한을 그대로 유지하세요.
설정을 변경하려면 config/runtime.json을 편집하고 서비스를 다시 시작하세요. arkvory configure 명령이 해당 설정(HTTPS, 백업 보관소, 미러, 업데이트)을 지원하면 그 명령을 사용하는 것이 좋습니다. 이 명령은 변경 사항을 검사하고, 서비스가 시작되지 않으면 이전 파일을 복원합니다. 구성을 참조하세요.
bash
sudo systemctl restart arkvory-api arkvory-worker arkvory-backuppowershell
Restart-Service Arkvoryapi, Arkvoryworker, Arkvorybackup허용 범위를 벗어난 값은 시작할 때 해당 변수의 이름을 알리는 메시지와 함께 프로세스를 중지시킵니다. 이 경우 Arkvory는 기본값으로 대체하지 않습니다.
"읽는 주체" 열에는 다음 이름을 사용합니다. API는 HTTP 서버(읽기 게이트웨이 포함), 워커는 백그라운드 워커, 에이전트는 백업 에이전트, CLI는 arkvoryctl입니다.
핵심 설정
| 변수 | 읽는 주체 | 기본값 | 의미 |
|---|---|---|---|
ARKVORY_DATABASE_URL | API, 워커, 에이전트, 마이그레이션 | 필수 | PostgreSQL 연결 URL(postgres:// 또는 postgresql://). 설치마다 별도의 데이터베이스를 사용하세요. |
ARKVORY_DATA_DIR | API, 워커, 에이전트 | 필수 | 로컬 스토리지 디렉터리: 스테이징, 콘텐츠, storage-id 파일. 네트워크 공유를 사용하지 마세요. |
ARKVORY_HOST | API | 127.0.0.1 | 수신할 주소. 설치 프로그램은 127.0.0.1을 기록합니다. Docker Compose에서는 컨테이너 안에서 0.0.0.0이며, 포트는 호스트의 루프백에만 게시됩니다. |
ARKVORY_PORT | API | 8080 | TCP 포트, 1–65535. |
ARKVORY_WEB_DIR | API | apps/web/public | 웹 콘솔 파일이 있는 디렉터리. 런처가 시작할 때마다 현재 릴리스로 설정합니다. |
ARKVORY_DATABASE_POOL_SIZE | API | 20 | API 쿼리 연결 풀의 크기, 4–200. 장기 세션은 연결 3개짜리 별도 풀을 사용합니다. |
스토리지와 제한
| 변수 | 읽는 주체 | 기본값 | 의미 |
|---|---|---|---|
ARKVORY_CAPACITY_BYTES | API, 워커 | 10 TiB | 예약된 모든 콘텐츠(게시된 콘텐츠, 완료되지 않은 업로드, 정리를 기다리는 콘텐츠)에 대한 상한(바이트). 디스크 검사가 아닙니다. 워커는 미러 복사에만 이 값을 읽습니다. |
ARKVORY_STORAGE_RESERVE_BYTES | API, 워커, 에이전트 | 1073741824 | 업로드가 절대 사용하지 않는 여유 공간(바이트). 데이터베이스, 로그, 시스템을 위해 남겨 둡니다. 0이면 예약을 끕니다. |
ARKVORY_MAX_OBJECT_BYTES | API | 약 10 TiB | 가장 큰 객체의 크기(바이트). 허용되는 최댓값은 1 GiB 파트 10 000개입니다. 파일 크기를 제한하려면 더 낮은 값을 설정하세요. |
전송과 대역폭
이 제한은 API 프로세스 하나에 적용됩니다. 속도의 단위는 초당 바이트입니다. 0은 제한 없음을 뜻하고, 다른 값은 65 536에서 1 TiB 사이여야 합니다.
| 변수 | 읽는 주체 | 기본값 | 의미 |
|---|---|---|---|
ARKVORY_MAX_UPLOADS | API | 8 | 동시에 실행되는 업로드 수, 1–32. |
ARKVORY_MAX_DOWNLOADS | API | 16 | 동시에 실행되는 다운로드 수, 1–256. |
ARKVORY_MAX_UPLOADS_PER_PRINCIPAL | API | 4 | 계정 또는 키 하나의 동시 업로드 수. 전체 업로드 한도를 넘을 수 없습니다. |
ARKVORY_MAX_DOWNLOADS_PER_PRINCIPAL | API | 4 | 계정 또는 키 하나의 동시 다운로드 수. 전체 다운로드 한도를 넘을 수 없습니다. |
ARKVORY_DOWNLOAD_STRATEGY | API | ordered | 다운로드 대기열이 ARKVORY_DOWNLOAD_SESSION_MIN_BYTES보다 큰 객체의 전체 다운로드를 정렬하는 방식: ordered(우선순위 클래스, 계정과 키 차례대로), smallest-first(작은 객체 먼저) 또는 shared(대기열 없음: 요청마다 따로 허용). 읽기 게이트웨이(ARKVORY_SHARED_DOWNLOADS_* 변수)를 사용하면 쓰기 프로세스를 포함한 모든 프로세스에서 기본값이 shared입니다. |
ARKVORY_MAX_DOWNLOAD_SESSIONS | API | ARKVORY_MAX_DOWNLOADS | 동시에 자리를 차지하는 다운로드 수, 1–1024. |
ARKVORY_DOWNLOAD_RESERVE | API | 1 | 대량 업데이트 중 사람(콘솔 세션과 개인 토큰)을 위해 남겨 두는 자리. 자리가 네 개 미만이면 기본값 0. |
ARKVORY_DOWNLOAD_WEIGHTS | API | interactive=8,release=4,bulk=2,background=1 | 클래스별 빈 자리 비율. 바꾸는 클래스만 적으세요. |
ARKVORY_DOWNLOAD_SESSION_MIN_BYTES | API | 16777216 | 이 크기 이하의 객체는 대기열을 거치지 않고 요청마다 허용됩니다. |
ARKVORY_DOWNLOAD_IDLE_SECONDS | API | 30 | 범위 사이의 멈춤이 이보다 길면 자리가 풀립니다. 다운로드는 10분 동안 순서를 유지합니다. |
ARKVORY_DOWNLOAD_AGING_MINUTES | API | 15 | 이만큼 기다릴 때마다 다운로드가 한 클래스 올라가며 최대 release까지입니다. 0이면 에이징을 끕니다. |
ARKVORY_DOWNLOAD_PREEMPT | API | true | 대기열 프로토콜 클라이언트(SDK, arkvoryctl)는 자리를 1분 이상 가진 뒤 범위 경계에서 더 높은 클래스나 몫보다 적게 쓰는 키에 자리를 양보합니다. |
ARKVORY_DOWNLOAD_RANGES_PER_SESSION | API | 4 | 한 다운로드의 동시 요청 수: 병렬 범위, 한 주소 뒤의 클라이언트. |
ARKVORY_DOWNLOAD_QUEUE_LIMIT | API | 65536 | 대기열의 전체 다운로드 수(활성 및 대기). 넘으면 1분 뒤에 다시 오라고 안내합니다. |
ARKVORY_DOWNLOAD_QUEUE_PER_PRINCIPAL | API | 4096 | 한 계정, 키 또는 링크의 전체 다운로드 수. |
ARKVORY_DOWNLOAD_HOLD_SECONDS | API | 20 | 대기열 프로토콜 밖의 도구(docker, npm, curl, 브라우저) 요청을 503으로 답하기 전에 차례를 기다리게 붙잡아 두는 시간. 기본값: ARKVORY_TRANSFER_QUEUE_TIMEOUT_MS. 0이면 즉시 답합니다. |
ARKVORY_SITE_NAME | API | — | 다른 설치의 사이트 페이지에서 이 설치를 부르는 이름, 1–63자. |
ARKVORY_FLEET_KEY_FILE | API | fleet.key | 이 설치가 관리하는 사이트의 키를 봉인하는 키. 쓰기 프로세스가 처음 시작될 때 만듭니다. 데이터 디렉터리처럼 보호하세요. 데이터베이스와 백업에는 없습니다. |
ARKVORY_SITE_URL | API | 설정 안 함 | 다른 사이트가 이 설치에 접근할 때 쓰는 https://host[:port] 주소. 설정하면 원본이 이 설치인 다른 사이트의 미러가 사이트 페이지의 지도에서 외부 주소 대신 이 설치로 연결됩니다. 잘못된 값이면 시작이 중지됩니다. |
ARKVORY_FLEET_LAG_ALERT | API | 1000 | 관리 대상 사이트의 미러가 원본보다 몇 개의 변경만큼 뒤처지면 컨트롤러의 사이트 페이지가 경보를 띄우는지. 1 이상의 정수. |
ARKVORY_TRANSFER_QUEUE_LIMIT | API | 64 | 빈 슬롯을 기다릴 수 있는 전송 수, 1–1024. |
ARKVORY_TRANSFER_QUEUE_PER_PRINCIPAL | API | 8 | 계정 또는 키 하나의 대기 중인 전송 수. 대기열 한도를 넘을 수 없습니다. |
ARKVORY_TRANSFER_QUEUE_TIMEOUT_MS | API | 20000 | 전송이 대기열에서 기다릴 수 있는 시간, 1–120 000 ms. |
ARKVORY_MAX_REQUESTS | API | 128 | 동시에 처리하는 인증된 요청 수, 1–4096. 업로드 수와 다운로드 수의 합보다 커야 합니다. 설정하지 않았고 전송 한도가 높으면 기본값은 업로드 수 + 다운로드 수 + 64입니다. |
ARKVORY_UPLOAD_BYTES_PER_SECOND | API | 0 | 프로세스 전체의 업로드 속도. |
ARKVORY_DOWNLOAD_BYTES_PER_SECOND | API | 0 | 프로세스 전체의 다운로드 속도. |
ARKVORY_UPLOAD_BYTES_PER_SECOND_PER_PRINCIPAL | API | 0 | 계정 또는 키 하나의 업로드 속도(모든 연결의 합계). |
ARKVORY_DOWNLOAD_BYTES_PER_SECOND_PER_PRINCIPAL | API | 0 | 계정 또는 키 하나의 다운로드 속도(모든 연결의 합계). |
ARKVORY_UPLOAD_IDLE_TIMEOUT_MS | API | 30000 | 이 시간 동안 데이터를 보내지 않는 업로드 요청은 중지됩니다, 1–1 800 000 ms. |
ARKVORY_UPLOAD_DEADLINE_MS | API | 1800000 | 업로드 요청 하나의 최대 소요 시간, 1–1 800 000 ms. 유휴 시간 제한보다 짧을 수 없습니다. |
네트워크, HTTPS, 브라우저
| 변수 | 읽는 주체 | 기본값 | 의미 |
|---|---|---|---|
ARKVORY_TLS_CERT_FILE | API | 설정 안 함 | 내장 HTTPS용 PEM 인증서(체인 포함). 키 파일과 함께 설정하세요. |
ARKVORY_TLS_KEY_FILE | API | 설정 안 함 | 비밀번호가 없는 PEM 개인 키. |
ARKVORY_TLS_MIN_VERSION | API | TLSv1.2 | TLSv1.2 또는 TLSv1.3. |
ARKVORY_TLS_RELOAD_SECONDS | API | 300 | 갱신된 인증서 파일을 읽는 주기: 30–86 400초. 0이면 시작할 때만 읽습니다. |
ARKVORY_CORS_ORIGINS | API | 비어 있음 | 다른 주소의 콘솔을 위한 브라우저 출처의 쉼표 구분 목록(최대 16개). HTTPS만 허용하며, 루프백에서는 HTTP도 허용합니다. |
ARKVORY_TRUSTED_PROXIES | API | 비어 있음 | 리버스 프록시 주소(IP 또는 CIDR) 최대 32개. 이 주소만 X-Forwarded-For로 클라이언트 주소를 설정할 수 있습니다. |
내장 HTTPS는 네이티브 설치용입니다. Docker Compose에서는 리버스 프록시를 사용하세요. HTTPS를 참조하세요.
ID와 키
| 변수 | 읽는 주체 | 기본값 | 의미 |
|---|---|---|---|
ARKVORY_KEYS_FILE | API, 워커 | 필수 | 복구 키와 상태 확인 키 같은 파일 키가 들어 있는 JSON 파일. 키 자체가 아니라 SHA-256 해시를 저장합니다. |
ARKVORY_ALLOW_REGISTRATION | API | 꺼짐 | true이면 사용자가 로그인 페이지에서 직접 계정을 만들 수 있습니다. 다른 값이면 꺼진 상태로 유지됩니다. |
백업
| 변수 | 읽는 주체 | 기본값 | 의미 |
|---|---|---|---|
ARKVORY_BACKUP_VAULT | 에이전트 | 설정 안 함 | 초기화된 보관소의 디렉터리. 설정하지 않으면 에이전트는 실행되지만 보관소가 구성되지 않았다고 보고합니다. arkvory configure --backup-vault가 이 값을 기록합니다. |
ARKVORY_BACKUP_VAULT_KEY_FILE | 에이전트 | 설정 안 함 | 암호화된 vault용 에이전트 키(AK1-…)가 든 파일 또는 복구 키트. 명령은 이를 --key-file로도 받습니다. arkvory configure --vault-key-file이 씁니다. |
ARKVORY_BACKUP_BYTES_PER_SECOND | 에이전트 | 제한 없음 | 백업의 복사 속도 제한, 최소 65 536. |
ARKVORY_BACKUP_POLL_SECONDS | 에이전트 | 15 | 에이전트가 새 백업 작업을 확인하는 주기, 1–3600초. |
ARKVORY_BACKUP_LEASE_SECONDS | 에이전트 | 60 | 두 번째 에이전트가 동시에 실행되지 못하게 하는 리스 시간, 2–3600초. |
ARKVORY_BACKUP_SNAPSHOT_SECONDS | 에이전트 | 1800 | 백업의 데이터베이스 스냅샷 단계에 대한 시간 제한, 60–86 400초. |
ARKVORY_BACKUP_BARRIER_SECONDS | 에이전트 | 30 | 백업이 실행 중인 정리 단계를 기다리는 시간, 1–600초. |
ARKVORY_RESTORE_DATABASE_URL | 복원 명령 | 설정 안 함 | 복원 대상 데이터베이스. 다른 사용자가 프로세스 목록에서 볼 수 없으므로 --database-url보다 안전합니다. |
백업을 참조하세요.
미러
| 변수 | 읽는 주체 | 기본값 | 의미 |
|---|---|---|---|
ARKVORY_MIRRORS_FILE | API, 워커 | 설정 안 함 | 미러링된 리포지토리(최대 64개)를 나열하는 JSON 파일. arkvory configure --mirror가 이 파일을 기록합니다. |
ARKVORY_MIRRORS_CA_FILE | 워커 | 설정 안 함 | 원본 서버를 위한 추가 인증 기관이 들어 있는 PEM 파일의 절대 경로. TLS는 항상 검증됩니다. |
미러를 참조하세요.
웹훅
| 변수 | 읽는 주체 | 기본값 | 의미 |
|---|---|---|---|
ARKVORY_WEBHOOKS_FILE | 워커 | 설정 안 함 | 웹훅 구독 목록이 담긴 JSON 파일(최대 16개). 없으면 웹훅을 보내지 않습니다. |
ARKVORY_WEBHOOKS_ALLOW_PRIVATE | 워커 | 설정 안 함 | 공인 주소 외에 웹훅을 받을 수 있는 네트워크를 CIDR 형식으로 쉼표로 구분해 지정합니다(최대 32개). 예: 10.20.0.0/16. |
ARKVORY_WEBHOOKS_CA_FILE | 워커 | 설정 안 함 | 수신자를 위한 추가 인증 기관이 담긴 PEM 파일의 절대 경로. TLS는 항상 검증됩니다. |
참고: 웹훅.
고가용성 클러스터
| 변수 | 읽는 주체 | 기본값 | 의미 |
|---|---|---|---|
ARKVORY_REPLICA_SOCKET | API | 설정 안 함 | arkvory-replica 서비스의 소켓. arkvory configure --cluster가 설정합니다. 설정되면 필요한 복사본이 완전할 때만 쓰기가 2xx를 받습니다. 설정 안 함: 독립 서버. |
참고: 고가용성 클러스터.
업데이트와 허브
| 변수 | 읽는 주체 | 기본값 | 의미 |
|---|---|---|---|
ARKVORY_HUB_URL | API | https://hub.proanima.net | 콘솔 피드백만 사용하는 ProAnimaStudio 허브의 주소(업데이트 허브는 config/hub.json에 저장되며 arkvory configure로 변경합니다). 값이 비어 있으면 피드백이 꺼집니다. HTTPS만 허용하며, 루프백에서는 HTTP도 허용합니다. |
ARKVORY_HUB_PROJECT | API | arkvory | 허브의 프로젝트 이름. |
ARKVORY_UPDATE_CONTROL_DIR | API | 설정 안 함 | API가 호스트 업데이터와 공유하는 디렉터리. 설치 프로그램이 설정합니다. 설정하지 않으면 콘솔에서 업데이트를 요청할 수 없습니다. |
업데이트를 참조하세요.
로깅과 종료
| 변수 | 읽는 주체 | 기본값 | 의미 |
|---|---|---|---|
ARKVORY_LOG_LEVEL | API, 워커, 에이전트 | info | debug, info, warning, error. |
ARKVORY_ACCESS_LOG | API | true | true이면 HTTP 요청마다 JSON 한 줄을 기록하고, false이면 끕니다. |
ARKVORY_DRAIN_TIMEOUT_MS | API | 30000 | 중지 신호를 받은 뒤 실행 중인 요청이 끝날 때까지 기다리는 시간, 0–3 600 000 ms. |
읽기 게이트웨이
이 변수 중 하나라도 설정하면 슬롯, 슬롯 수, 공유 속도가 필요합니다. 쓰기 서버는 역할 api와 슬롯 0을 사용합니다. 각 읽기 게이트웨이는 역할 reader와 자신의 슬롯을 사용합니다. 읽기 게이트웨이를 참조하세요.
| 변수 | 읽는 주체 | 기본값 | 의미 |
|---|---|---|---|
ARKVORY_ROLE | API | api | api(쓰기 서버) 또는 reader(읽기 게이트웨이). |
ARKVORY_GATEWAY_SLOTS | API | 설정 안 함 | 다운로드 예산을 공유하는 프로세스 수, 2–16. |
ARKVORY_GATEWAY_SLOT | API | 설정 안 함 | 이 프로세스의 슬롯, 0부터 슬롯 수 − 1까지. |
ARKVORY_SHARED_DOWNLOAD_BYTES_PER_SECOND | API | 설정 안 함 | 모든 프로세스의 전체 다운로드 속도. 각 슬롯은 같은 몫(최소 초당 65 536바이트)을 받습니다. |
ARKVORY_SHARED_DOWNLOAD_BYTES_PER_SECOND_PER_PRINCIPAL | API | 0 | 계정 또는 키 하나의 모든 프로세스에 걸친 전체 다운로드 속도. 0은 제한 없음을 뜻합니다. |
워치독
| 변수 | 읽는 주체 | 기본값 | 의미 |
|---|---|---|---|
ARKVORY_WATCHDOG_SECONDS | API, 워커, 에이전트 | 60 | 이 시간 동안 멈춰 있는 프로세스는 스스로 종료되고, 서비스 관리자가 다시 시작합니다. 0이면 끕니다(디버거용). 그 외에는 10–3600초. |
자가 복구를 참조하세요.
명령줄 클라이언트
| 변수 | 읽는 주체 | 기본값 | 의미 |
|---|---|---|---|
ARKVORY_BASE_URL | CLI | 프로필, 없으면 http://127.0.0.1:8080 | 서버 주소. 설정하면 키도 환경에서 가져와야 합니다. |
ARKVORY_TOKEN | CLI | 설정 안 함 | 키 자체. 키 파일보다 우선합니다. |
ARKVORY_TOKEN_FILE | CLI | 프로필의 키 파일 | 키가 들어 있는 파일의 경로. |
ARKVORY_CLI_HOME | CLI | ~/.config/arkvory | profiles.json 파일의 디렉터리. |
ARKVORY_CLI_VERSION | CLI | development | --version이 출력하는 버전. 릴리스 패키지에 포함되어 있습니다. |
명령줄 클라이언트를 참조하세요.
설치 스크립트
이 변수는 Linux의 install.sh가 읽습니다. Windows의 install.ps1은 대신 -Root, -Artifact 같은 매개 변수를 사용합니다.
| 변수 | 기본값 | 의미 |
|---|---|---|
ARKVORY_INSTALL_ROOT | /opt/proanima-arkvory | 설치 루트. 네이티브 설치를 홈 디렉터리에 두지 마세요. |
ARKVORY_ARTIFACT_DIR | 설정 안 함 | 압축을 푼 릴리스의 디렉터리. 스크립트는 릴리스를 다운로드하는 대신 이 디렉터리에서 설치합니다. |
ARKVORY_RELEASE_VERSION | 최신 안정 버전 | 설치할 정확한 안정 버전(예: 1.2.3). |
설치 프로그램이 설정하는 변수
설치 프로그램은 자체 도우미 프로세스를 위해 이 변수를 설정합니다. 직접 설정하지 마세요.
| 변수 | 의미 |
|---|---|
ARKVORY_IMAGE | config/compose.env에 있는 현재 릴리스의 컨테이너 이미지. |
ARKVORY_SERVICE_WRAPPER | 서비스가 중지된 상태에서 사용하는 Windows 백업 서비스 래퍼의 경로. |
ARKVORY_PROTECT_ROOT | Windows에서 접근 규칙을 설정하는 설치 루트. |
ARKVORY_ENGINE_USER | Windows의 Docker Desktop에서 현재 사용자에게 루트 접근 권한을 부여합니다. |