제어면 드라이브 및 객체 저장소 설정
AI Agent용 안내: 이 페이지의 Markdown 버전은 https://ankole.agentbull.com/ko-KR/docs/drive-storage/index.md, 전체 문서 색인은 https://ankole.agentbull.com/ko-KR/llms.txt에 있습니다.
ANKOLE_FILES_STORE는 컨트롤 플레인 객체 저장소(Ankole.ObjectStore)를 지정하는 설정입니다. 이곳에는 Worker가 중지되어 있어도 접근 가능한 Agent 드라이브를 비롯해 Pod file 페이지, Pod 문서/Base/Chat 및 대화 첨부 파일, 컴파일된 Applet 번들이 저장됩니다. 파일 경로와 권한 및 콘텐츠 참조는 PostgreSQL이 관리하고, 실제 콘텐츠 주소 기반(content-addressed) blob 바이트는 OpenDAL 백엔드가 보관합니다. 지원 백엔드는 fs, s3, azblob, d1, cos, postgresql, oss, tos, gcs, sftp, webdav입니다.
이 설정은 사이트 부팅 시점에 읽히며 사이트 내 모든 테넌트가 동일한 객체 저장소를 공유합니다. WorkerProvider의 Home 볼륨, 캐시, Cloudflare R2 백업은 이와 별도로 구성하며, 자세한 내용은 WorkerProvider와 파일 관리를 참조하세요.
backend 선택
| 배포 | ANKOLE_FILES_STORE |
구성 |
|---|---|---|
| 단일 호스트 또는 컨트롤 플레인 복제본 1개 | fs |
영속 볼륨 또는 로컬 디렉터리 |
| AWS S3 | s3 |
버킷, 리전, AWS 자격 증명 체인 |
| Cloudflare R2 | s3 |
S3 API 엔드포인트, 리전 auto, R2 자격 증명 |
| 기타 S3 호환 서비스 | s3 |
엔드포인트, 서명 리전, 자격 증명, 사전 호환성 검증 |
여러 control plane 복제본을 실행하려면 모든 복제본이 같은 공유 원격 backend와 root를 사용하고 Distributed Erlang 클러스터를 구성해야 합니다. Worker에서 Pod IP로 직접 접근할 수 있어야 하며 endpoints.relayOrigin은 지정할 수 없습니다. 공식 Helm 차트는 클러스터 검색을 구성하고, 복제본이 둘 이상일 때 files.store: fs 또는 provider의 endpoints.relayOrigin을 거부합니다. 채팅 연결은 노드 간에 담당을 조정하고 Oban은 작업 큐를 공유합니다. 구성과 업그레이드 요건은 컨트롤 플레인 복제본 안내를 참조하세요.
환경 변수
| 변수 | backend | 요구 사항 |
|---|---|---|
ANKOLE_FILES_STORE |
전체 | 운영 환경 필수: 지원 백엔드 중 하나 선택 |
ANKOLE_FILES_FS_ROOT |
fs |
컨트롤 플레인 컨테이너 내부의 쓰기 가능한 절대 경로 |
ANKOLE_FILES_S3_BUCKET |
s3 |
미리 생성해 둔 버킷 이름 |
ANKOLE_FILES_S3_REGION |
s3 |
필수. AWS는 버킷 리전, R2는 auto |
ANKOLE_FILES_S3_ENDPOINT |
s3 |
호환 서비스 엔드포인트. AWS S3는 보통 생략 |
ANKOLE_FILES_S3_ROOT |
s3 |
선택적 객체 접두사(prefix). 예: /ankole/production/ |
ANKOLE_FILES_S3_ACCESS_KEY_ID |
s3 |
선택적 정적 자격 증명. 아래 시크릿 키와 함께 설정 |
ANKOLE_FILES_S3_SECRET_ACCESS_KEY |
s3 |
선택적 정적 자격 증명. 위 액세스 키와 함께 설정 |
정적 자격 증명을 생략하면 EKS Pod Identity를 포함한 기본 AWS 자격 증명 체인을 사용합니다. 스토리지 자격 증명은 컨트롤 플레인에만 부여하세요. Worker는 RuntimeFabric을 거쳐 자신의 드라이브에 접근하므로 버킷 키가 필요하지 않습니다. 이 변수들은 프로세스 시작 시에만 읽히므로 값을 바꾼 뒤에는 컨트롤 플레인을 재시작해야 하며, 표에 없는 임의의 OpenDAL 옵션을 Ankole 환경 변수로 추가해서는 안 됩니다.
추가 OpenDAL backend
추가 백엔드의 환경 변수는 ANKOLE_FILES_<SCHEME>_<FIELD> 형식을 따르며 백엔드 이름과 필드 이름은 모두 대문자로 표기합니다. 예를 들어 Azure Blob을 쓰려면 ANKOLE_FILES_STORE=azblob, ANKOLE_FILES_AZBLOB_CONTAINER, ANKOLE_FILES_AZBLOB_ENDPOINT를 설정합니다. 아래 표는 Ankole이 노출하는 전체 필드 목록이며, 필수 필드가 빠져 있거나 빈 값이면 컨트롤 플레인 부팅이 실패합니다.
| backend | 필수 필드 | 선택 필드 |
|---|---|---|
azblob |
CONTAINER, ENDPOINT |
ROOT, ACCOUNT_NAME, ACCOUNT_KEY, SAS_TOKEN |
d1 |
ACCOUNT_ID, DATABASE_ID, TOKEN, TABLE, KEY_FIELD, VALUE_FIELD |
ROOT |
cos |
BUCKET, ENDPOINT |
ROOT, SECRET_ID, SECRET_KEY, SECURITY_TOKEN |
postgresql |
CONNECTION_STRING, TABLE, KEY_FIELD, VALUE_FIELD |
ROOT |
oss |
BUCKET, ENDPOINT |
ROOT, ACCESS_KEY_ID, ACCESS_KEY_SECRET, SECURITY_TOKEN |
tos |
BUCKET, ENDPOINT, REGION |
ROOT, ACCESS_KEY_ID, SECRET_ACCESS_KEY, SECURITY_TOKEN |
gcs |
BUCKET |
ROOT, ENDPOINT, CREDENTIAL, CREDENTIAL_PATH |
sftp |
ENDPOINT |
ROOT, USER, KEY, KNOWN_HOSTS_STRATEGY |
webdav |
ENDPOINT |
ROOT, USERNAME, PASSWORD, TOKEN |
민감한 자격 증명은 컨트롤 플레인 Secret에 보관하세요. GCS의 CREDENTIAL에는 Base64로 인코딩한 서비스 계정 JSON을 넣고 CREDENTIAL_PATH에는 원본 JSON 파일 경로를 지정하며, 둘 다 생략하면 기본 Google 자격 증명 체인을 따릅니다. SFTP는 컨트롤 플레인 이미지 내장 ssh를 사용하며 KEY에는 개인 키 파일 경로를 지정합니다. 호스트 키 검증 기본값이 strict이므로 컨트롤 플레인 실행 계정의 ~/.ssh/known_hosts를 미리 구성해 두어야 합니다. WebDAV는 Basic 인증 자격 증명 또는 Bearer TOKEN을 지원합니다.
D1과 PostgreSQL 백엔드를 쓸 때는 대상 테이블을 미리 만들어 두어야 합니다(Ankole이 자동 생성하지 않음). D1에는 TEXT 기본 키와 BLOB 값 컬럼을, PostgreSQL에는 TEXT 기본 키와 BYTEA 값 컬럼을 두고 TABLE, KEY_FIELD, VALUE_FIELD로 각각의 이름을 지정하세요. D1, PostgreSQL, WebDAV는 네이티브 백엔드 계층에서 객체 전체를 메모리에 버퍼링합니다. 특히 D1은 문자열·BLOB·행 크기 상한이 2,000,000바이트이며 Ankole이 객체를 여러 행으로 쪼개 저장하지 않으므로, 대용량 파일을 다루어야 한다면 버킷 기반 백엔드를 선택하세요.
SFTP 백엔드는 대상 객체와 같은 디렉터리에 임시 파일을 기록한 뒤 파일을 닫고 이름을 바꾸는 방식으로 동작하므로, SFTP 서버가 OpenSSH posix-rename 같은 원자적 이름 변경을 지원해야 합니다. 쓰기 도중 컨트롤 플레인이 비정상 종료되면 blobs/<digest>.<uuid>.tmp 형태의 임시 파일이 남을 수 있는데, 모든 쓰기 프로세스를 내린 점검 시간에 정리하면 됩니다.
Helm 환경에서는 files.store로 백엔드를 고르고 일반 변수는 controlPlane.extraEnv에, 자격 증명 변수는 secrets.existingSecret에 넣으세요. 차트는 해당 Secret을 컨트롤 플레인과 마이그레이션 Job 환경 양쪽에 주입하며, 같은 Secret의 항목들을 컨트롤 플레인 컨테이너의 /etc/ankole/bootstrap 아래에 읽기 전용 파일로도 마운트합니다. SSH 키 권한과 known_hosts는 컨테이너 실행 계정인 uid 10001에 맞춰 구성하세요. Docker Compose에서는 아래 오버라이드 방식에 따라 선택한 백엔드 변수를 migrate와 control-plane 두 서비스 모두에 전달하고, 운영 전환 전에 읽기·쓰기·덮어쓰기·삭제·대용량 전송을 반드시 검증하세요.
로컬 폴더와 영구 volume
ANKOLE_FILES_STORE=fs
ANKOLE_FILES_FS_ROOT=/var/lib/ankole/files
위 경로는 컨트롤 플레인 프로세스 내부에서 바라보는 경로입니다. 컨테이너가 재생성되어도 파일이 사라지지 않도록 반드시 영속 볼륨을 마운트해야 하며, 공식 이미지 실행 계정인 uid/gid 10001에 디렉터리 생성·쓰기·이름 변경·삭제 권한이 부여되어 있어야 합니다. fs 백엔드는 지정한 루트 아래에 .tmp 작업 폴더도 함께 생성합니다.
공식 Compose 파일은 기본적으로 files_data 명명 볼륨을 /var/lib/ankole/files에 마운트합니다. 호스트 디렉터리를 직접 바인드 마운트하려면 먼저 폴더를 생성하고 uid/gid 10001 쓰기 권한을 부여한 뒤 오버라이드 파일로 교체하세요.
services:
control-plane:
volumes:
- ./ankole-files:/var/lib/ankole/files
운영 중인 사이트의 마운트 경로를 바꿀 때는 기존 파일 저장소의 데이터를 먼저 새 폴더로 복사하세요. 빈 호스트 폴더를 마운트해도 기존 볼륨의 파일이 자동으로 옮겨지지는 않습니다.
Helm에서 로컬 영속 볼륨을 쓰는 설정 예시는 다음과 같습니다.
controlPlane:
replicaCount: 1
files:
store: fs
persistence:
size: 100Gi
storageClass: YOUR_STORAGE_CLASS
# existingClaim: YOUR_EXISTING_FILES_PVC
차트는 파일 전용 PVC를 새로 생성하거나 지정한 기존 PVC를 인계받아 /var/lib/ankole/files에 마운트합니다. 차트가 생성한 PVC는 릴리스를 삭제(uninstall)하더라도 자동 삭제되지 않고 보존됩니다. 기존 PVC를 연결할 때도 동일한 권한 및 백업 요건을 갖추어야 하며, Agent Home은 이 볼륨과 별개의 스토리지를 사용합니다.
AWS S3
비공개 버킷을 생성한 뒤 지정한 prefix 아래에서 읽기, 쓰기, 삭제, 멀티파트 업로드를 수행할 수 있는 IAM 권한을 컨트롤 플레인 실행 신원에 부여하세요. 버킷에 KMS 암호화를 적용했다면 관련 KMS 키 권한도 함께 필요합니다.
ANKOLE_FILES_STORE=s3
ANKOLE_FILES_S3_BUCKET=ankole-files
ANKOLE_FILES_S3_REGION=ap-southeast-1
ANKOLE_FILES_S3_ROOT=/ankole/production/
AWS 워크로드 신원(EKS Pod Identity 등)을 사용하면 정적 키 환경 변수를 생략할 수 있습니다. 정적 키를 사용할 때는 ANKOLE_FILES_S3_ACCESS_KEY_ID와 ANKOLE_FILES_S3_SECRET_ACCESS_KEY 두 값을 모두 배포 Secret에 넣어 전달하세요.
Helm 설정 예시:
files:
store: s3
s3:
bucket: ankole-files
region: ap-southeast-1
root: /ankole/production/
secrets.existingSecret으로 두 S3 키가 담긴 부트스트랩 Secret을 참조할 수 있습니다. 이때 해당 Secret에는 데이터베이스 자격 증명(DATABASE_URL 및 내장 PostgreSQL 사용 시 POSTGRES_PASSWORD), 원래 ANKOLE_SECRET_BASE, ANKOLE_FUNCTION_RUNTIME_TOKEN, RELEASE_COOKIE도 빠짐없이 함께 들어 있어야 합니다. 차트에서 secrets.filesS3AccessKeyID와 secrets.filesS3SecretAccessKey 값을 직접 받을 수도 있으나, 평문 시크릿을 values 파일에 커밋하지는 마세요.
Cloudflare R2와 기타 S3 호환 서비스
Cloudflare R2 역시 s3 백엔드로 연결합니다.
ANKOLE_FILES_STORE=s3
ANKOLE_FILES_S3_BUCKET=ankole-files
ANKOLE_FILES_S3_REGION=auto
ANKOLE_FILES_S3_ENDPOINT=https://ACCOUNT_ID.r2.cloudflarestorage.com
ANKOLE_FILES_S3_ROOT=/ankole/production/
ANKOLE_FILES_S3_ACCESS_KEY_ID=YOUR_R2_ACCESS_KEY_ID
ANKOLE_FILES_S3_SECRET_ACCESS_KEY=YOUR_R2_SECRET_ACCESS_KEY
이때 공개 버킷 도메인이나 Cloudflare Worker URL이 아니라 계정의 S3 API 전용 엔드포인트와 R2 S3 API 자격 증명을 입력해야 합니다. auto 리전 설정과 호환 API 범위는 R2 S3 API 호환성 문서를 참조하세요. Helm에서는 files.s3.endpoint, files.s3.region, files.s3.root 필드를 사용합니다.
MinIO 등 다른 S3 호환 스토리지도 s3 백엔드에 실제 엔드포인트와 서명 리전을 지정해 연결합니다. 다만 벤더가 S3 호환을 표방한다는 이유만으로 검증을 생략하지 말고, 읽기·쓰기·삭제·멀티파트 업로드·대용량 파일 전송이 정상 동작하는지 직접 확인하세요. Ankole이 지원하는 백엔드와 시작 변수는 이 문서의 표에 정리된 항목이 전부이며, S3 가상 호스트 주소 방식(virtual-hosted-style) 전환이나 사용자 지정 서명 옵션은 별도로 노출하지 않습니다. 내부 동작은 상위 OpenDAL S3 백엔드 문서를 참고할 수 있습니다.
Compose에서 S3 사용
공식 compose.yaml에는 ANKOLE_FILES_STORE: fs가 명시되어 있으므로 .env에 ANKOLE_FILES_STORE=s3만 적어서는 설정이 바뀌지 않습니다. compose.files-s3.yaml 같은 오버라이드 파일을 만들어 migrate와 control-plane 서비스 양쪽에 동일한 S3 변수를 주입하세요. 정적 자격 증명을 쓰는 예시는 다음과 같습니다.
x-files-environment: &files-environment
ANKOLE_FILES_STORE: s3
ANKOLE_FILES_S3_BUCKET: ${ANKOLE_FILES_S3_BUCKET:?Set the files bucket}
ANKOLE_FILES_S3_REGION: ${ANKOLE_FILES_S3_REGION:?Set the files region}
ANKOLE_FILES_S3_ENDPOINT: ${ANKOLE_FILES_S3_ENDPOINT:-}
ANKOLE_FILES_S3_ROOT: ${ANKOLE_FILES_S3_ROOT:-/ankole/}
ANKOLE_FILES_S3_ACCESS_KEY_ID: ${ANKOLE_FILES_S3_ACCESS_KEY_ID:?Set the access key}
ANKOLE_FILES_S3_SECRET_ACCESS_KEY: ${ANKOLE_FILES_S3_SECRET_ACCESS_KEY:?Set the secret key}
services:
migrate:
environment: *files-environment
control-plane:
environment: *files-environment
.env 또는 배포 환경에 실제 변수 값을 채운 뒤, 신규 사이트라면 아래 명령으로 바로 시작하면 됩니다(운영 중인 사이트라면 먼저 다음 절의 객체 이전 절차부터 완료하세요).
docker compose -f compose.yaml -f compose.files-s3.yaml up -d
이후 run, exec, 버전 업그레이드, Home 가져오기 명령을 실행할 때도 항상 두 -f 플래그를 함께 지정해야 합니다. AWS 기본 자격 증명 체인을 쓸 때는 오버라이드 파일에서 정적 키 두 줄을 빼고 컨테이너에 워크로드 신원을 연결하세요.
backend, 버킷, prefix 변경
환경 변수만 바꾼다고 해서 기존 파일이 새 저장소로 자동 이전되지는 않습니다. 또한 PostgreSQL의 콘텐츠 참조에 대응하는 실제 객체 키는 루트(또는 prefix) 아래의 blobs/<전체 SHA-256> 형식이며, Agent의 논리 드라이브 경로명을 딴 일반 폴더 구조가 아닙니다.
- 신규 유입 요청과 예약 작업을 멈추고 Agent들을 비활성화한 뒤 진행 중인 작업이 끝날 때까지 기다립니다. 이어서 모든 Worker와 컨트롤 플레인 프로세스를 중지해 파일 커밋과 가비지 컬렉션까지 완전히 멈추세요.
- 데이터베이스, 기존 객체 저장소, Agent Home, 배포 시크릿을 한 세트로 백업합니다.
blobs/하위 객체 전체를 키 이름을 바꾸지 않은 채 새 대상 루트(또는 prefix)로 그대로 복사합니다.fs에서 복사할 때는.tmp디렉터리를 제외하고, 임의로 논리 드라이브 경로명으로 바꾸지 마세요.- 모든 컨트롤 플레인 노드가 새 저장소를 바라보도록 설정을 맞춘 뒤 기동합니다. 기존 파일 다운로드와 내용 일치 여부, 신규 업로드, Worker에서의 읽기·쓰기, 채팅 첨부 전송을 차례로 검증합니다.
- 이상이 없으면 작업을 재개하고, 만일의 롤백에 대비해 기존 저장소도 당분간 보존합니다. 만약 전환 이후에 새로 쓰인 파일까지 살리면서 이전 저장소로 되돌아가야 한다면 신규 객체와 데이터베이스 참조를 함께 맞춰야 합니다.
서로 독립된 두 Ankole 사이트가 같은 버킷 prefix를 공유하게 두지 마세요. 한 사이트의 가비지 컬렉션이 실행될 때 다른 사이트에서 참조 중인 객체까지 미사용 파일로 판단해 지워 버릴 수 있습니다. 반대로 같은 사이트에 속한 복제본들은 모두 동일한 저장소 설정을 공유해야 합니다.
백업과 정리
데이터베이스 백업에는 메타데이터와 참조만 들어 있고 실제 파일 바이트는 버킷이나 로컬 폴더에 있으므로, 백업과 복원은 항상 두 저장소를 함께 묶어 수행해야 합니다. 컨트롤 플레인의 가비지 컬렉션은 Agent 드라이브, Pod file 페이지, Pod 문서/Base/Chat 및 대화 첨부 파일, 컴파일된 Applet 번들 등 모든 소유 참조에서 어디에서도 가리키지 않는 미사용 blob만 골라 삭제합니다. 따라서 버킷 측에 아직 참조 중인 정상 객체까지 만료 삭제하는 수명 주기(lifecycle) 규칙을 걸어 두어서는 안 됩니다.
다만 S3 멀티파트 업로드 도중 프로세스가 끊기면 미완료 업로드 조각이 버킷에 남을 수 있으므로, 워크로드에 맞는 유예 기간 뒤에 미완료 멀티파트 업로드만 정리(abort)하는 수명 주기 규칙은 설정해 두는 것이 좋습니다. fs 백엔드는 저장소를 열 때 생성된 지 하루가 넘도록 갱신되지 않은 임시 파일을 스스로 정리하지만, 이러한 정리 동작이 정기 백업을 대신하지는 않습니다.
점검 시에는 먼저 Worker가 떠 있지 않은 상태에서 Console을 통해 파일을 업로드·다운로드해 보고, 이어서 Worker 하나를 띄워 파일 접근과 첨부 전송까지 확인하세요. AccessDenied가 나면 실행 신원과 버킷 정책을, fs 쓰기 오류가 나면 볼륨 마운트·uid 10001 권한·디스크 잔여 용량을, 마이그레이션 후 기존 파일 누락이 보이면 버킷·리전·prefix 설정과 blobs/ 복사 결과를 점검하세요. 자세한 백업 절차는 백업과 복원을, 구버전 파일 이전은 2.0 업그레이드를 참조하세요.