설정 레퍼런스
EdgeSettings 전 필드, 설정 파일 탐색 순서, GEO_EDGE_* 환경 변수, 크기 문자열
에이전트 설정은 EdgeSettings 하나입니다. YAML(또는 JSON) 파일과 환경 변수로 채웁니다.
우선순위: 환경 변수 > 파일 > 기본값
같은 키가 여러 곳에 있으면 환경 변수가 이깁니다. 토큰 같은 비밀은 /etc/geo-mlops/edge.env 에, 현장 구성(수집기·주소·보존 한도)은 edge.yaml 에 나눠 두라는 뜻입니다. 그러면 토큰을 교체할 때 YAML 을 건드리지 않아도 됩니다.
설정 파일 탐색 순서
--config 를 주지 않으면 이 순서로 찾고, 처음 있는 파일 하나만 읽습니다.
- 환경 변수
GEO_EDGE_CONFIG가 가리키는 파일. 이 변수가 있으면 여기서 끝입니다. 그 파일이 없으면 다른 곳을 찾지 않고 기본값으로 뜹니다. /etc/geo-mlops/edge.yaml- 현재 디렉터리의
edge.yaml
아무 파일도 없어도 에이전트는 기본값으로 뜹니다. 이때 central 이 비어 있으므로 링크는 계속 offline 이고 데이터는 로컬에만 쌓입니다. geo-mlops-edge config 로 실제 적용된 값을 확인합니다.
환경 변수
접두사 GEO_EDGE_ 뒤에 키 이름을 대문자로 붙이고, **중첩 키는 밑줄 두 개(__)**로 잇습니다.
GEO_EDGE_CENTRAL__BASE_URL=https://mlops.example.com
GEO_EDGE_CENTRAL__TOKEN=<device-token>
GEO_EDGE_DATA_DIR=/var/lib/geo-mlops-edge
GEO_EDGE_API__TOKEN=<your-secret>
GEO_EDGE_RETENTION__MAX_BYTES=100GiB
GEO_EDGE_LOG_LEVEL=DEBUG목록(collectors, sync.windows, api.cors_origins)은 파일에 적는 것이 낫습니다. 환경 변수로 주려면 JSON 문자열(GEO_EDGE_SYNC__WINDOWS='["22:00-06:00"]')이어야 합니다.
크기 문자열
크기 필드는 바이트 정수 대신 50GiB 같은 문자열을 받습니다. 대소문자는 가리지 않습니다.
| 단위 | 배수 | 단위 | 배수 |
|---|---|---|---|
B | 1 | ||
KB | 1000 | KiB | 1024 |
MB | 1000² | MiB | 1024² |
GB | 1000³ | GiB | 1024³ |
TB | 1000⁴ | TiB | 1024⁴ |
적용되는 필드: retention.max_bytes, retention.free_disk_min_bytes, sync.chunk_bytes, sync.max_bytes_per_s, api.max_body_bytes, http 수집기의 max_body_bytes.
전체 필드
최상위
| 키 | 기본값 | 설명 |
|---|---|---|
central | (아래) | 중앙 서버 접속 |
device | (아래) | 장비 이름·위치 |
data_dir | /var/lib/geo-mlops-edge | 큐 DB(edge.db), 파일 스풀(spool/), 모델 캐시(models/)가 모두 여기 |
disk_path | "" | 디스크 사용률을 재고 보존 한도를 지킬 파일시스템. 비우면 data_dir |
heartbeat_interval_s | 30 | 하트비트 주기(초) |
commands_poll_s | 25 | 명령 롱폴 대기 시간(초) |
retention | (아래) | 로컬 보존 한도 |
sync | (아래) | 업로드 조절 |
link | (아래) | 연결 감시 |
api | (아래) | 로컬 HTTP API |
collectors | [] | 수집기 목록(데이터 수집기 참고) |
models | (아래) | 모델 캐시 |
policy_source | central | central 이면 중앙이 내려준 정책이 heartbeat_interval_s·commands_poll_s·retention·sync 를 덮어씀. local 이면 이 파일이 우선 |
log_level | INFO | DEBUG·INFO·WARNING·ERROR |
central
| 키 | 기본값 | 설명 |
|---|---|---|
base_url | "" | 중앙 API 주소(https://mlops.example.com). 비면 오프라인 전용 |
token | "" | 디바이스 토큰. 환경 변수 GEO_EDGE_CENTRAL__TOKEN 으로만 주세요 |
timeout_s | 10.0 | 요청 제한 시간(초) |
verify_tls | true | TLS 인증서 검증 |
base_url 과 token 이 둘 다 있어야 중앙과 통신합니다.
device
| 키 | 기본값 | 설명 |
|---|---|---|
id | "" | 장비 이름. 비면 호스트 이름, 그것도 없으면 edge-<머신ID 앞 8자>. 영문·숫자·.·_·- 외 문자는 - 로 바뀌고 64자에서 잘립니다 |
location | 없음 | 등록할 때 중앙에 알리는 위치 |
retention: 로컬 보존 한도
셋 중 하나라도 먼저 걸리면 정리를 시작합니다. 넘으면 우선순위가 낮은 것부터, 같은 우선순위에서는 오래된 것부터 버립니다.
| 키 | 기본값 | 설명 |
|---|---|---|
max_bytes | 50GiB | 큐 전체 크기 상한 |
max_age_days | 30 | 이보다 오래된 항목은 버림. 0 이면 기간 제한 없음 |
free_disk_min_bytes | 5GiB | 디스크 여유가 이보다 적어지면 버려서 확보. 0 이면 검사 안 함 |
sync: 업로드 조절
| 키 | 기본값 | 설명 |
|---|---|---|
batch_size | 500 | 한 요청에 보내는 레코드 수(서버 상한 1000) |
chunk_bytes | 32MiB | 파일 청크 크기 요청값. 실제 크기는 서버가 정해 돌려준 값을 씀 |
max_bytes_per_s | 0 | 전송 속도 상한. 0 은 무제한 |
cpu_pause_percent | 85 | 시스템 CPU 가 이 값을 넘으면 전송을 멈춤. 0 이면 검사 안 함 |
windows | [] | 전송 허용 시간대(장비 현지 시각), 예: ["22:00-06:00"]. 비면 항상 |
concurrency | 1 | 동시 전송 수 |
urgent_priority | 90 | 이 우선순위 이상은 windows 를 무시하고 보냄 |
link: 연결 감시
| 키 | 기본값 | 설명 |
|---|---|---|
probe_interval_s | 5.0 | 중앙 /api/v1/health 를 찔러 보는 주기 |
backoff_max_s | 60.0 | 실패가 이어질 때 늘어나는 간격의 상한 |
online_after_ok | 2 | 연속 몇 번 성공해야 online 으로 보나 |
offline_after_fail | 3 | 연속 몇 번 실패해야 offline 으로 보나 |
공장 회선은 자주 끊겼다 붙습니다. 한 번 우연히 성공했다고 바로 수십 GB 를 보내기 시작하지 않도록 이 두 값을 둡니다.
api: 로컬 HTTP API
| 키 | 기본값 | 설명 |
|---|---|---|
enabled | true | 로컬 API 를 띄울지 |
host | 0.0.0.0 | 바인드 주소. 개발 PC 는 127.0.0.1 |
port | 8600 | 포트 |
token | "" | 비면 인증 없음. 있으면 X-Edge-Api-Token 헤더로 보내야 함 |
cors_origins | ["*"] | 허용할 브라우저 출처 |
max_body_bytes | 2GiB | 요청 본문 상한. 넘으면 413. 0 이면 검사 안 함 |
models: 모델 캐시
| 키 | 기본값 | 설명 |
|---|---|---|
keep_versions | 2 | 모델마다 디스크에 남길 버전 수. 새 버전을 받으면 오래된 것부터 지움. 0 은 무제한 |
auto_activate | Production | 설정 항목은 있지만 0.2.0 런타임은 이 값을 읽지 않습니다. 자동 활성화 동작은 모델과 추론을 보세요 |
예시 전체
central:
base_url: https://mlops.example.com
timeout_s: 10
verify_tls: true
device:
id: edge-line-01
location: line-1
data_dir: /var/lib/geo-mlops-edge
retention:
max_bytes: 50GiB
max_age_days: 30
free_disk_min_bytes: 5GiB
sync:
batch_size: 500
chunk_bytes: 32MiB
max_bytes_per_s: 0
cpu_pause_percent: 85
windows: []
urgent_priority: 90
link:
probe_interval_s: 5
backoff_max_s: 60
online_after_ok: 2
offline_after_fail: 3
heartbeat_interval_s: 30
commands_poll_s: 25
api:
enabled: true
host: 0.0.0.0
port: 8600
token: ""
max_body_bytes: 2GiB
models:
keep_versions: 2
policy_source: central
log_level: INFO
collectors: [] # 데이터 수집기 페이지 참고