에어갭 / on-prem

Ongrid 는 정확히 오프라인에서 동작하도록 자체 완결된 하나의 tarball 로 배포됩니다. apt install 도, 대상 호스트에서의 빌드 시점 Go 모듈 페치도, 런타임의 Docker Hub pull 도 없습니다. tarball 을 떨어뜨리고 install.sh 를 실행하면, 동작하는 매니저 + edge 함대를 얻습니다.

에어갭으로 가면서 마주칠 트레이드오프는 LLM 제공자, RAG 임베딩 모델, 그리고 지속적인 업그레이드 주변에 있습니다. 이 페이지는 그 체크리스트입니다.

1단계: 릴리스 tarball 내려받기

인터넷이 있는 호스트에서 최신 릴리스 자산을 받습니다:

gh release download v0.7.167 --repo ongridio/ongrid \
    --pattern 'ongrid-*-linux-amd64.tar.xz'
gh release download v0.7.167 --repo ongridio/ongrid \
    --pattern 'ongrid-*-linux-amd64.tar.xz.sha256'
sha256sum -c ongrid-v0.7.167-linux-amd64.tar.xz.sha256

또는 make package 로 직접 tarball 을 빌드하세요. 어느 쪽이든 결과물은 단일 .tar.xz 와 그 .sha256 입니다.

두 파일을 사용하시는 에어갭 채널 (sneakernet USB, 사내 아티팩트 서버, 서명된 S3 버킷 등) 로 대상 호스트에 옮기세요.

2단계: Tarball 설치

tarball 은 자체 완결된 디렉터리로 풀립니다:

text

ongrid-v0.7.167-linux-amd64/
  install.sh
  upgrade.sh
  docker-compose.yml
  images/
    ongrid.tar              # docker image, saved
    ongrid-web.tar
    frontier.tar
    mysql.tar               # bundled so no Docker Hub pull
    prometheus.tar
    loki.tar
    tempo.tar
    grafana.tar
    searxng.tar
  bin/
    linux-amd64/ongrid-edge
    linux-arm64/ongrid-edge
    darwin-amd64/ongrid-edge
    darwin-arm64/ongrid-edge
    linux-amd64/promtail
    linux-arm64/promtail
    linux-amd64/otelcol-contrib
    linux-arm64/otelcol-contrib
    linux-amd64/node_exporter
    linux-arm64/node_exporter
    linux-amd64/process_exporter
    linux-arm64/process_exporter
  edge/
    apply-pending-upgrade.sh
  .cache/
    bge-base-en-v1.5/       # optional offline RAG embedding model

실행:

tar -xf ongrid-v0.7.167-linux-amd64.tar.xz
cd ongrid-v0.7.167-linux-amd64
sudo ./install.sh

install.sh 는 모든 images/*.tar 을 로컬 docker 에 로드하고, 합리적인 .env 를 작성하고, docker compose up -d 로 스택을 띄우고, 새 매니저의 URL 을 출력합니다. 호스트에는 Docker Engine + Compose v2 가 필요합니다 — Linux (server) 참고.

체크섬과 첫 부팅을 포함한 전체 단계별 안내는 에어갭 설치 를 보세요.

3단계: 사설 레지스트리로 미러링 (선택)

사설 컨테이너 레지스트리 (Harbor / Artifactory / ECR / GCR) 가 있고, docker load 보다 docker pull 을 선호한다면, 번들된 이미지를 한 번 푸시하세요:

for img in images/*.tar; do
  name=$(docker load -i "$img" | awk -F': ' '/Loaded image/ {print $2}')
  registry_tag="registry.internal/${name}"
  docker tag "$name" "$registry_tag"
  docker push "$registry_tag"
done

그런 다음 각 서비스가 원본 이미지 대신 registry.internal/... 을 가리키도록 docker-compose.override.yml 을 작성하면, tarball 을 다시 보내지 않고도 N 개의 호스트에 배포할 수 있습니다. 이후 업그레이드는 "새 이미지 태그 pull, docker compose up -d" 로 줄어듭니다.

4단계: 에어갭 네트워크에서의 edge 설치

curl-pipe 설치 스크립트 (https://<manager>/install.sh | bash) 는 에어갭 네트워크 안에서도 edge 가 매니저에 도달할 수만 있다면 (정적 번들용 443 포트 + 터널용 40012 포트) 잘 동작합니다. 설치 스크립트는 매니저의 /edge/ 에서 에이전트 바이너리와 네 개의 플러그인 바이너리를 받는데, 매니저의 nginx 가 바인드 마운트된 ./bin/ 디렉터리에서 이를 서빙합니다.

edge 가 HTTPS 로 매니저에 도달할 수 없는 경우 (예: 40012 포트만 허용된 네트워크 세그먼트에 있는 edge), 바이너리를 손으로 복사하세요:

# on each edge host
sudo install -m 0755 ongrid-edge /usr/local/bin/ongrid-edge
sudo mkdir -p /usr/local/lib/ongrid-edge
sudo install -m 0755 promtail otelcol-contrib node_exporter process_exporter \
    /usr/local/lib/ongrid-edge/
# then write /etc/ongrid-edge/ongrid-edge.env and the systemd unit
# (see deploy/install/edge/install.sh for the exact unit content)

또는 더 견고하게: ./bin/linux-*/ 의 복제본을 둔 작은 내부 HTTPS 미러를 세우고, fork 한 install.sh 를 그쪽으로 가리키게 하세요.

5단계: LLM 제공자

Ongrid 는 LLM 을 번들하지 않습니다. 에이전트 커널은 매니저의 아웃바운드 인터넷 연결을 통해 업스트림 제공자 — Anthropic, OpenAI, Zhipu, DeepSeek, Gemini, Kimi, 또는 OpenAI 호환 릴레이 — 를 호출합니다. 에어갭 네트워크에서는 세 가지 옵션이 있습니다:

아웃바운드 프록시. 매니저의 env 블록에 HTTPS_PROXY=http://your-proxy:3128 을 설정. 모든 제공자 호출이 프록시를 통과합니다.
자체 호스팅 OpenAI 호환 릴레이. 네트워크 안에서 vLLM / TGI / Ollama / one-api 를 실행하고, ONGRID_OPENAI_BASE_URL 을 거기로 가리키며, ONGRID_OPENAI_API_KEY 를 릴레이가 기대하는 값으로 설정합니다. 완전 단절 설치에서 가장 흔한 패턴입니다.
UI 에서의 커스텀 제공자. Settings → Models → Custom (OpenAI-compatible) 이 재시작 없이 같은 와이어링을 제공합니다.

중국 내 Tencent Cloud 호스팅 엔드포인트에 대해 Zhipu (GLM) 를 쓰려면, ONGRID_ZHIPU_BASE_URL 을 지역 엔드포인트로, ONGRID_ZHIPU_API_KEY 를 당신의 키로 설정하세요 — 프록시는 필요 없고, GLM 은 중국 본토 네트워크 안에서 도달 가능합니다.

6단계: 오프라인 RAG (임베딩 모델)

지식 베이스 ingest 에는 임베딩 모델이 필요합니다. 기본적으로 매니저는 인터넷이 필요한 GLM 임베딩 API (embedding-3) 를 호출합니다. 완전 오프라인 배포에서는 local embedding 프로파일로 전환하세요:

ONGRID_EMBEDDING_PROVIDER=local
ONGRID_EMBEDDING_LOCAL_MODEL_PATH=/var/lib/ongrid/embeddings/bge-base-en-v1.5

릴리스 tarball 은 .cache/bge-base-en-v1.5/ 아래에 BAAI/bge-base-en-v1.5 모델 (~400 MB) 을 배포합니다. 설치 스크립트가 첫 부팅 시 named volume 으로 복사합니다. tarball 빌드 시 make fetch-embedding-model 을 건너뛰었다면 모델이 없어 임베딩이 실패합니다 — 그 단계를 한 번 실행하고 다시 패키징하세요.

기본 Ongrid 내장 vault (github.com/ongridio/vault) 는 공개 이며 임베디드 RAG 시드에 포함된 기본 runbook 을 담습니다. 이를 동기화하려면 GitHub 에 도달해야 합니다. 에어갭 네트워크에서는:

vault 를 자체 내부 Git 서버로 vendoring 하고 ONGRID_VAULT_REPO_URL 을 업데이트하세요.
또는 vault 동기화를 아예 건너뛰세요 — 임베디드 시드 (약 96 개의 playbook) 가 바이너리 안에 들어 있어 항상 사용 가능합니다.

7단계: 업그레이드

두 가지 경로:

같은 tarball 메커니즘. 인터넷이 있는 호스트에서 새 tarball 을 받아 sneakernet 으로 옮기고, ./upgrade.sh 를 실행합니다. 이는 install.sh 에서 부트스트랩을 뺀 것 — 이미지 로드 + docker compose up -d. edge 에이전트들은 다음 재연결 시점에 매칭되는 에이전트 + 플러그인 바이너리를 받아갑니다 (ADR-024 whole-bundle 스테이징).
사설 레지스트리 pull. 이미지를 미러링했다면 (3단계), docker compose pull && docker compose up -d 로 충분합니다. edge 들은 여전히 새 에이전트 + 플러그인 바이너리가 필요하며, 매니저의 /edge/ 정적 경로에서 가져갑니다 — 그것은 tarball 에서 배포된 bin/ 디렉터리를 교체하면 자동으로 업데이트됩니다.

에어갭에서 동작하지 않는 것

미러 없는 내장 vault 자동 동기화 — vault 저장소는 GitHub 에 있습니다.
아웃바운드 프록시 또는 릴레이 없는 제공자의 호스팅 LLM — 배포되는 로컬 LLM 은 없습니다.
기본 GLM 임베딩 프로파일 — local 로 전환하세요 (6단계 참고).
공개 마켓플레이스 skill 설치 (ADR-017) — 대신 사설 레지스트리를 가리키세요.

전체 에이전트 커널, 알림 evaluator, 텔레메트리 파이프라인, 채팅 UI 를 포함한 다른 모든 것은 완전 오프라인에서 동작합니다.

에어갭 / on-prem ​

1단계: 릴리스 tarball 내려받기 ​

2단계: Tarball 설치 ​

3단계: 사설 레지스트리로 미러링 (선택) ​

4단계: 에어갭 네트워크에서의 edge 설치 ​

5단계: LLM 제공자 ​

6단계: 오프라인 RAG (임베딩 모델) ​

7단계: 업그레이드 ​

에어갭에서 동작하지 않는 것 ​