에어갭 설치

Ongrid 는 완전 오프라인 설치가 가능하도록 설계되었습니다. 모든 릴리스 tarball 은 다음을 포함합니다.

• ongrid 매니저 docker 이미지,
• ongrid-web (프론트엔드 + nginx) docker 이미지,
• singchia/frontier 브로커 docker 이미지,
• 4 개의 edge 플러그인 바이너리 (promtail, otelcol-contrib, node_exporter, process_exporter) — linux/amd64 및 linux/arm64,
• 아키텍처별 ongrid-edge 바이너리,
• 지식 베이스용 선택적 오프라인 임베딩 모델 (fast-bge-small-zh-v1.5) — make package 전에 make fetch-embedding-model 을 실행했다면.

설치 시점에 Docker Hub, GitHub, 또는 어떤 벤더 API 에서도 풀하지 않습니다. 런타임 외부 의존성은 구성한 LLM API 엔드포인트뿐 — 완전 에어갭 셋업에서는 이를 사내 vLLM / Ollama / OpenRouter relay 로 가리키세요.

이 페이지는 공인 인터넷에 도달할 수 없는 환경의 워크플로를 다룹니다.

연결된 호스트에서 tarball 다운로드

인터넷이 있는 워크스테이션에서:

VER=v0.7.159

gh release download "$VER" \
    --repo ongridio/ongrid \
    -p 'ongrid-*-linux-amd64.tar.xz*'

두 개의 파일이 생깁니다.

ongrid-v0.7.159-linux-amd64.tar.xz          # ~380 MB (xz compressed)
ongrid-v0.7.159-linux-amd64.tar.xz.sha256   # the sidecar

Clash 위에서의 GitHub 업로드

Clash 프록시 위에서 큰 릴리스 asset 이 중간에 리셋됩니다. 다운로드 중 tarball 이 짧게 끝난다면 NO_PROXY=objects.githubusercontent.com 으로 직접 시도하세요. 항상 sha256 을 검증하세요 (다음 단계).

sha256 검증

다른 무엇보다 먼저:

sha256sum -c ongrid-v0.7.159-linux-amd64.tar.xz.sha256
# → ongrid-v0.7.159-linux-amd64.tar.xz: OK

이것이 실패하면 진행하지 마세요. 재다운로드 하세요.

에어갭 호스트로 전송

귀사에서 승인된 경로 무엇이든. USB 키, 사내 아티팩트 저장소, 점프 호스트 경유 SFTP. 두 파일은 함께 이동합니다; 전송 후 sha256 을 재검증할 수 있습니다.

# 목적지 호스트에서:
sha256sum -c ongrid-v0.7.159-linux-amd64.tar.xz.sha256

설치

server install 와 동일 — 에어갭에 필요한 플래그 없음, installer 는 절대 외부로 나가지 않음:

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

install.sh 가 하는 일:

• 번들된 세 이미지 (images/ongrid.tar, images/frontier.tar, images/ongrid-web.tar) 를 docker load.
• 설정 스테이지, 호스트 데이터 디렉터리 셋업, self-signed TLS 인증서 생성 (로컬 openssl 사용; 외부 CA 불필요).
• 템플릿에서 .env 배선, 강력한 랜덤 시크릿 in-place 생성, ONGRID_PUBLIC_URL 입력 요청.
• docker compose up -d, /healthz 폴링.

"downloading..." 로그 라인이 보이면 안 됩니다.

사내에서 설치 URL 호스팅

edge 가 자체 설치할 때 curl https://<manager>/install.sh | bash 를 실행합니다. 그 install.sh 는 매니저 자신이 제공합니다 — 구체적으로 nginx 가 /opt/ongrid/edge/install.sh 에서 제공. edge 설치 경로에 GitHub 나 다른 외부 의존성은 없습니다.

같은 nginx 가 제공:

Path on nginx	What
/install.sh	edge install.sh 스크립트.
/edge/ongrid-edge-linux-amd64	edge 에이전트 바이너리.
/edge/ongrid-edge-linux-arm64	동일, arm64.
/edge/promtail-linux-amd64	플러그인 바이너리.
/edge/otelcol-contrib-linux-amd64	플러그인 바이너리.
/edge/node_exporter-linux-amd64	플러그인 바이너리.
/edge/process_exporter-linux-amd64	플러그인 바이너리.
/edge/apply-pending-upgrade.sh	ADR-024 ExecStartPre 훅.
/edge/edge-bundle-linux-amd64-<ver>.tar.gz	업그레이드 번들.
/edge/edge-bundle-linux-amd64-<ver>.tar.gz.sha256	사이드카.

이 모든 것은 install.sh 실행 시 /opt/ongrid/edge/ 에 안착하며 nginx 컨테이너가 읽기 전용으로 제공합니다. 그 외에는 필요 없습니다.

Edge 설치 (에어갭)

edge 가 매니저에 도달할 수 있는 한 표준 한 줄이 동작합니다.

curl -k -sSL https://manager.internal/install.sh | sudo bash -s -- \
    --access-key=AK_xxxxxxxxxxxxxxxx \
    --secret-key=SK_yyyyyyyyyyyyyyyy \
    --server-edge-addr=manager.internal:40012 \
    --server-http-addr=manager.internal:443

매니저에는 직접 도달할 수 없지만 사내 아티팩트 미러에는 도달할 수 있는 edge 호스트가 있다면 다음을 할 수 있습니다.

1. 매니저의 /install.sh, /edge/* 경로를 사내 웹서버로 미러링.
2. 그 미러의 URL 을 가리켜 한 줄 실행.
3. 에이전트는 여전히 실제 매니저를 가리키는 --server-edge-addr 과 --server-http-addr 가 필요합니다 — 미러는 설치 아티팩트만 호스팅, 터널은 아닙니다.

이는 "edge 가 매니저에 TCP 40012 + 큐레이션된 일부 포트로만 대화 가능" 인 셋업에서 매니저로의 TCP 443 은 불가하지만 사내 웹서버는 가능할 때 유용합니다.

데이터 플레인은 여전히 매니저로의 HTTPS 가 필요

로그와 트레이스는 각 edge 에서 https://<manager>/loki/api/v1/push 와 https://<manager>/v1/traces 로 직접 push 합니다. edge 가 매니저의 443 에 도달할 수 없으면 이 플러그인들은 실패합니다. 에이전트 자체는 정상으로 보이지만 (40012 만 필요), 데이터 플레인은 침묵 — edge → 매니저 경로의 443 이 열려 있는지 확인하세요.

에어갭 모델 provider

기본 ONGRID_*_API_KEY= 슬롯들은 벤더 URL (OpenAI, Anthropic, Zhipu, …) 을 가리킵니다. 에어갭을 유지하려면 Settings → Models 에서 사내 relay 를 가리키는 Custom (OpenAI-compatible) provider 를 구성하세요.

• vLLM — 더미 OPENAI_API_KEY 와 함께 OPENAI_API_BASE=http://vllm.internal:8000/v1.
• Ollama — OPENAI_API_BASE=http://ollama.internal:11434/v1.
• LocalAI / LMStudio — 동일 패턴.
• OpenRouter (사내) — relay base URL 붙여넣기.

에이전트는 신경 쓰지 않습니다; OpenAI 호환 wire 포맷은 보편적입니다. 그런 다음 새 provider 를 Default provider 로 설정하여 모든 백엔드 호출 (알림 investigation, 번역, 요약) 이 그것을 사용하도록 합니다.

사이드바의 Models 아래 Custom (OpenAI-compatible) 항목을 참고하세요.

에어갭 지식 베이스 (GitHub 없이 vault 동기화)

내장 vault 는 첫 부팅에서 github.com/ongridio/vault 에서 동기화합니다. 에어갭 사이트는 GitHub 에 도달할 수 없습니다. 두 가지 옵션:

옵션 A — vault 를 인라인으로 출하

릴리스 tarball 은 vault 의 기준 스냅샷을 이미지의 일부로 포함합니다. 첫 부팅 시 매니저가 그것을 직접 Qdrant 에 복사 — 네트워크 불필요. 기준선 (릴리스 태그 시점의 마지막 완전 공개 동기화) 은 얻지만 매니저 업그레이드 전까지 새 플레이북은 보지 못합니다.

옵션 B — vault 저장소를 사내 미러링

1. 연결된 호스트에서 공개 vault 를 클론:

   git clone --bare https://github.com/ongridio/vault.git

2. 사내 Git 서버로 push:

   git push --mirror git@git.internal:ops/vault.git

3. Settings → Knowledge → Vault 에서 동기화 URL 을 git@git.internal:ops/vault.git 로 설정하고 SSH 배포 키를 붙여넣으세요. 매니저는 GIT_SSH_COMMAND 로 키를 바인딩 — ADR-023 참고.

매니저는 UI 에서 vault 를 요청 시 재동기화합니다 ("Sync vault" 버튼). 각 풀은 구성된 remote 에 대한 git fetch 입니다; 경로에 GitHub 특화 코드는 없습니다.

에어갭 업그레이드

초기 설치와 마찬가지로 설치 시점에 인터넷 불필요. 흐름:

1. 연결된 워크스테이션에서: gh release download v0.7.160 ... 와 sha256 검증.
2. tarball 전송.
3. 에어갭 호스트에서:

   tar xf ongrid-v0.7.160-linux-amd64.tar.xz
   cd     ongrid-v0.7.160-linux-amd64
   sudo ./upgrade.sh

4. UI 에서 Edges → Upgrade all — edge 가 https://<manager>/edge/edge-bundle-linux-amd64-v0.7.160.tar.gz 에서 새 번들을 fetch 하고 표준 ADR-024 stage-then-swap 흐름을 통해 적용.

tarball 을 다운로드하는 워크스테이션 외에는 인터넷이 필요한 단계가 없습니다.

상세는 upgrade 를 참고하세요.

다음은

• Models / Custom (OpenAI-compatible) — vLLM / Ollama / 사내 relay 를 기본 provider 로 배선 (사이드바의 Models 참고).
• 지식 베이스 기능 — vault 가 포함하는 내용과 자체 runbook 추가 방법.
• On-prem 플랫폼 — SELinux, 커스텀 CA, 아웃바운드 프록시 등 on-prem / 에어갭 배포 관련 노트.