English

폐쇄망 설치

인터넷이 없는 현장에 설치할 때 할 일. 이미지 tar 반입, 패키지 프록시 끄기, 사전학습 가중치 미리 넣기

Geo-MLOps 는 기본 설정에서 몇 군데 인터넷에 나갑니다. 폐쇄망에서는 그 지점마다 미리 가져오거나, 사내 미러로 돌리거나, 끄는 준비가 필요합니다. 이 페이지는 무엇이 어디서 인터넷을 쓰는지부터 정리합니다.

인터넷을 쓰는 곳

언제무엇을 받나폐쇄망에서는
앱 이미지 빌드(docker compose up --build)uv, kubectl, 파이썬 패키지외부망에서 빌드해 tar 로 반입
Compose 서비스 기동Postgres·RustFS·Prometheus 등 공개 이미지tar 로 반입
k3s 설치, device plugink3s 바이너리·이미지, nvcr.io/nvidia/k8s-device-plugink3s 공식 폐쇄망(에어갭) 설치 + 이미지 반입
공유 이미지 게시(클러스터 안 빌드)docker.io/moby/buildkit:v0.18.2-rootless, pip·apt 패키지, PyTorch 휠사내 미러를 가리키거나, 외부에서 구운 이미지를 반입
학습 실행사전학습 가중치(체크포인트)가중치 미러에 미리 넣고 인터넷 받기를 끔

1. 컨테이너 이미지 반입

  1. 외부망 PC 에서 같은 버전의 소스로 앱 이미지를 빌드하고, Compose 가 쓰는 이미지 이름을 확인합니다.

    docker compose -f /opt/geo-mlops/docker-compose.yml build
docker compose -f /opt/geo-mlops/docker-compose.yml pull --ignore-buildable
docker compose -f /opt/geo-mlops/docker-compose.yml config --images

  2. 위에서 나온 이미지를 모두 한 tar 로 묶어 옮깁니다. 클러스터 파드용 이미지(BuildKit rootless, device plugin)는 따로 묶습니다.

    docker save -o geo-mlops-compose.tar $(docker compose -f /opt/geo-mlops/docker-compose.yml config --images)
docker pull docker.io/moby/buildkit:v0.18.2-rootless
docker pull nvcr.io/nvidia/k8s-device-plugin:v0.19.3
docker save -o geo-mlops-k3s.tar docker.io/moby/buildkit:v0.18.2-rootless nvcr.io/nvidia/k8s-device-plugin:v0.19.3

  3. 폐쇄망 서버 에서 불러오고, 빌드 없이 띄웁니다.

    docker load -i geo-mlops-compose.tar
sudo k3s ctr images import geo-mlops-k3s.tar
docker compose -f /opt/geo-mlops/docker-compose.yml up -d --no-build

학습 런타임처럼 플랫폼이 보통 클러스터 안에서 굽는 이미지도 외부에서 구워 들여올 수 있습니다. docker save 로 만든 tar 를 웹 화면 컨테이너 레지스트리 → 이미지 반입으로 올린 뒤, 학습 런타임 화면에서 그 이미지를 외부 이미지 변형으로 등록합니다. 외부 이미지 변형은 게시(빌드) 단계가 없습니다.

2. 빌드 패키지 프록시

Compose 에 들어 있는 proxpi(pip)·apt-cacher-ng(apt)는 캐시일 뿐 미러가 아닙니다. 인터넷에 닿지 않으면 채울 수도 없고, 비어 있는 캐시를 거친 빌드는 실패합니다. 둘 중 하나를 고릅니다.

선택설정(app.env)
사내 미러가 있다: pip 인덱스·apt 미러를 사내에 운영GEO_MLOPS_BUILD_PIP_INDEX_URL=http://<사내 pip 미러>/simple/GEO_MLOPS_BUILD_APT_PROXY=http://<사내 apt 프록시>:3142필요하면 GEO_MLOPS_TRAINING_RUNTIME_TORCH_INDEX 도 사내 PyTorch 휠 인덱스로
미러가 없다: 프록시 주입을 끔GEO_MLOPS_BUILD_PACKAGE_PROXY_ENABLED=false
# /etc/geo-mlops/app.env (프록시를 쓰지 않는 환경)
GEO_MLOPS_BUILD_PACKAGE_PROXY_ENABLED=false
  • 끄는 스위치는 이것 하나입니다. 주소 설정을 비워 두는 것은 "끄기" 가 아니라 "기본 주소(10.42.0.1:5000, :3142)를 쓰기" 입니다.
  • 끄면 빌드가 PyPI·데비안 저장소로 직접 나갑니다. 폐쇄망에서는 그 빌드 역시 실패하므로, 미러가 없다면 위 1절처럼 외부에서 구운 이미지를 반입해 쓰세요.
  • 설정을 바꾼 뒤에는 앱을 다시 만들고(docker compose … up -d app), 서빙 빌더를 한 번 다시 게시합니다. 업그레이드의 "이미지 재게시" 를 참고하세요.
  • 빌드 캐시 화면에서 두 프록시가 "꺼져 있음" 으로 보이면 제대로 꺼진 것입니다. 켜 둔 채 프록시가 죽어 있으면 "장애" 로 보이고, 그 상태의 빌드는 모두 실패합니다.
빌드 캐시: pip·apt 패키지 프록시와 레이어 캐시

3. 사전학습 가중치 미리 넣기

학습은 시작할 때 사전학습 체크포인트(예: YOLO·RF-DETR 가중치)를 씁니다. 플랫폼은 이것을 오브젝트 저장소의 가중치 미러에 두고 파드에 미리 내려놓습니다. 기본 설정에서는 미러에 없으면 스테이저가 인터넷에서 받아 미러를 채웁니다. 폐쇄망에서는 이 인터넷 받기를 끄고, 미러를 손으로 채웁니다.

# /etc/geo-mlops/app.env
GEO_MLOPS_TRAINING_WEIGHTS_UPSTREAM_FETCH=false

  1. 카탈로그에 어떤 가중치가 있고, 미러에 무엇이 있는지 봅니다.

    docker exec geo-mlops-app ./run geo-mlops-admin weights list
# rf-detr  rf-detr-nano   349.3MB  --
# yolo     yolo11n          5.4MB  --
# -> 0/16 mirrored, 3.6GB total

  2. 외부망에서 받아 온 체크포인트 파일을 앱 컨테이너에 복사하고, 카탈로그의 모델 키와 함께 밀어 넣습니다. 파일의 MD5 가 카탈로그와 다르면 거부되므로, 잘못된 파일이 들어갈 걱정은 없습니다.

    docker cp ./rf-detr-nano.pth geo-mlops-app:/tmp/rf-detr-nano.pth
docker exec geo-mlops-app ./run geo-mlops-admin weights push rf-detr-nano /tmp/rf-detr-nano.pth
# rf-detr/rf-detr-nano: pushed

  3. 시스템 콘솔 가중치 미러 화면에서 해당 모델의 미러 칸이 "아직 없음" 에서 "있음" 으로 바뀌었는지 확인합니다. 인터넷 받기를 끈 상태면 화면 위에 "자동 확보 꺼짐" 이 보입니다. 같은 모델 키가 여러 프레임워크에 있으면 --framework 를 붙이라는 오류가 나옵니다.

    가중치 미러: 사전학습 체크포인트를 사내 저장소에 보관

미러에 없는 가중치로 학습을 제출해도 학습이 막히지는 않습니다. 다만 인터넷 받기가 꺼져 있으면 트레이너가 스스로 받으려다 실패할 수 있으니, 쓸 모델은 미리 넣어 두세요.

4. 웹 화면

웹 화면 정적 파일도 외부망에서 빌드(npm ci && npm run build)해 dist/ 를 옮겨 옵니다. 방법은 Docker Compose 로 설치의 "웹 화면 올리기" 와 같습니다.

설정 전체 목록은 레퍼런스에 있습니다.

2026-09-21 기준 플랫폼에 맞춰 작성했습니다.

© Geo-MLOps