Ongrid

한국어

English
简体中文
日本語
Español
Français
Deutsch
Português
Русский

한국어

English
简体中文
日本語
Español
Français
Deutsch
Português
Русский

Appearance

빠른 시작 ​

목표: 약 10 분 안에 다음을 갖추는 것입니다.

  1. Linux 한 대에서 docker compose 로 전체 Ongrid 스택이 동작 (manager
    • frontier 브로커 + Prometheus + Loki + Tempo + Grafana + Qdrant + SearXNG).
  2. 관리자 계정으로 HTTPS 로그인.
  3. 매니저에 등록된 ongrid-edge 하나가 CPU / 메모리 / 디스크 메트릭을 전송하고, Monitor 페이지에서 그것들을 볼 수 있다.

더 깊은 가이드를 원한다면 Server install 과 Edge install 을 참고하세요.

0. 사전 요구사항 ​

Linux 박스 한 대 (Ubuntu 22.04+, Debian 12+, RHEL/Rocky/Alma 9+ 검증 완료).

  • 최소 4 GB RAM (8 GB 권장)
  • /var/lib/ongrid (데이터 디렉터리) 아래 여유 디스크 20 GB
  • root 또는 sudo
  • docker ≥ 24 및 docker compose v2 서브커맨드
  • openssl (첫 부팅에서 self-signed TLS 인증서 생성에 사용)
  • edge 가 실행될 호스트에서 TCP 443 과 40012 개방

로컬 전용 테스트

랩탑에서 전부 실행할 수 있습니다. 다만 ONGRID_PUBLIC_URL 이 기본적으로 랩탑의 LAN IP 가 되므로, 다른 머신에 설치한 edge 가 그 LAN IP 의 TCP/443 에 도달할 수 있어야 합니다.

1. 서버 설치 ​

표준 설치 경로는 gh release download 와 sudo ./install.sh 입니다. tarball 은 자체 완결적입니다 — docker 이미지, edge 바이너리, 설정 파일이 모두 번들되어 있습니다.

bash
# 최신 태그는 https://github.com/ongridio/ongrid/releases 에서 선택
VER=v0.7.159

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

tar xf "ongrid-${VER}-linux-amd64.tar.xz"
cd     "ongrid-${VER}-linux-amd64"

sudo ./install.sh

install.sh 가 순서대로 하는 일:

  1. Preflight. docker + docker compose v2 가 있고 daemon 에 접근 가능한지 검증.
  2. /opt/ongrid/ 아래에 설정 스테이징 (compose 파일, prometheus, loki, tempo, grafana, searxng, edge 아티팩트).
  3. /var/lib/ongrid/ 아래에 데이터 디렉터리 생성 (mysql, prometheus, loki, tempo, qdrant, grafana, embeddings) 후 각 컨테이너 이미지가 기대하는 uid 로 chown. 로그는 /var/log/ongrid/ 로.
  4. /opt/ongrid/certs/ 에 self-signed TLS 인증서 생성 — 첫 접속 시 브라우저가 경고합니다. 나중에 실제 인증서로 교체; Server install 참고.
  5. tarball 에서 docker 이미지 로드 (ongrid, ongrid-web, frontier) — Docker Hub pull 불필요.
  6. MYSQL_*, ONGRID_JWT_SECRET, GRAFANA_ADMIN_PASSWORD, 부트스트랩 ONGRID_ADMIN_PASSWORD 용 강력한 랜덤 비밀번호로 .env 채우기.
  7. 30 초 카운트다운으로 ONGRID_PUBLIC_URL 입력 요청. 이 URL 은 edge 들이 이 매니저의 데이터 플레인 (로그 → Loki, 트레이스 → OTLP push) 에 도달하기 위해 사용할 URL 입니다. 인터랙티브 터미널에서 잘못된 값이 "매니저 호스트의 edge 만 로그를 보낸다" 문제의 1 번 원인이므로 확인하세요. ONGRID_PUBLIC_URL 참고.
  8. docker compose up -d 실행 후 https://localhost/healthz 를 최대 60 초 폴링.
  9. Web URL, API URL, 터널 엔드포인트, 부트스트랩 관리자 비밀번호가 적힌 배너 출력 — 단 한 번 기록됨.

정상 설치는 이렇게 끝납니다.

text
[INFO] ongrid is healthy (took ~14s)

===============================================================
  ongrid installation complete
===============================================================

Web UI:          https://203.0.113.10/
API URL:         https://203.0.113.10/api/v1
Tunnel endpoint: 203.0.113.10:40012   (for edges)

---------------- bootstrap admin ----------------
email:    admin@example.com
password: 9Xp4hKqf1bL2zRq3Wn7v
>> Record this password NOW. It will not be shown again.
-------------------------------------------------

관리자 비밀번호 기록

부트스트랩 비밀번호는 설치 배너에 단 한 번 표시되며 /opt/ongrid/.env 에도 ONGRID_ADMIN_PASSWORD 로 (chmod 600) 저장됩니다. 둘 다 잃으면 데이터베이스에서 리셋해야 합니다; 첫 부팅 체크리스트 참고.

2. 로그인 ​

브라우저로 https://<your-host>/ 를 엽니다. TLS 경고를 수락 (또는 실제 인증서를 먼저 설치) 하고 다음으로 로그인합니다.

  • email — .env 의 ONGRID_ADMIN_EMAIL 값 (기본 admin@example.com)
  • 비밀번호 — 설치 배너에 표시된 값

첫 로그인 시 채팅 홈 페이지로 이동합니다. 상단 바의 모델 선택기에 "no provider configured" 라고 표시됩니다 — 계속 전에 이것부터 고치세요.

3. 모델 구성 (1 분) ​

Settings → Models 로 이동합니다. 다음 중 아무거나 고릅니다.

  • OpenAI — sk-… 붙여넣기, 기본 모델 gpt-5.4.
  • Anthropic — sk-ant-… 붙여넣기, 기본 claude-opus-4-7.
  • Zhipu (GLM) — API 키 붙여넣기, 기본 glm-4.7.
  • DeepSeek, Gemini, Kimi, 그 외에는 Custom (OpenAI-compatible) (vLLM, Ollama, OpenRouter, 사내 relay…).

Save 를 누릅니다. 폼이 provider 를 pre-register 합니다 — 재시작 불필요. 그런 다음 같은 페이지에서 Default provider 를 방금 구성한 것으로 설정합니다.

기본값이 중요한 이유

Default provider 는 모든 백엔드 LLM 호출 (알림 investigation, 번역, 요약) 을 구동합니다. 채팅 페이지의 모델 선택기는 현재 채팅 스레드에만 오버라이드를 줍니다 (라우팅 상세는 사이드바의 Models 섹션 참고).

상단 nav 의 Chat 으로 돌아가 "hello" 라고 물어보세요. 모델이 응답하면 연결된 것입니다.

4. 첫 edge 등록 ​

사이드 nav 에서 Edges → New edge 를 클릭. 다음을 채웁니다.

  • Name — 자유롭게; 예: prod-web-01.
  • Description — 선택.

Create 를 누릅니다. 상세 페이지에 필요한 두 가지가 표시됩니다.

  • Access key / secret key — 서버 측에서 생성. secret 은 단 한 번 표시됨.
  • Install command — 다음과 같은 한 줄.
bash
curl -k -sSL https://203.0.113.10/install.sh | sudo bash -s -- \
    --access-key=AK_xxxxxxxxxxxxxxxx \
    --secret-key=SK_yyyyyyyyyyyyyyyy \
    --server-edge-addr=203.0.113.10:40012 \
    --server-http-addr=203.0.113.10:443

모니터링하려는 호스트로 SSH 하고 (매니저를 설치한 같은 박스여도 됩니다 — 유효한 데모) root 로 그 명령을 실행합니다.

순서대로 일어나는 일:

  1. installer 가 해당하는 ongrid-edge-linux-amd64 바이너리와 4 개의 플러그인 바이너리 (promtail, node_exporter, process_exporter, otelcol-contrib), apply-pending-upgrade.sh 훅을 /usr/local/lib/ongrid-edge/ 에 다운로드.
  2. ongrid-edge 시스템 사용자를 만들고 adm, systemd-journal 그룹에 넣어 logs 플러그인이 /var/log/* 와 journal 을 읽을 수 있게 함.
  3. /etc/systemd/system/ongrid-edge.service 에 systemd unit 배치.
  4. /etc/ongrid-edge/ongrid-edge.env 에 access/secret key 작성 (mode 0640, root:ongrid-edge 소유).
  5. systemctl enable --now ongrid-edge. agent: registered with cloud 라인을 journal 에서 최대 20s 폴링.
  6. 자체 점검 출력 (플러그인 바이너리 존재 여부? journald 읽기 가능? 데이터 플레인 호스트 도달 가능?).

성공적인 등록은 다음으로 끝납니다.

text
[OK]    plugin binary present: promtail
[OK]    plugin binary present: otelcol-contrib
[OK]    plugin binary present: node_exporter
[OK]    plugin binary present: process_exporter
[OK]    journald readable by ongrid-edge
[OK]    data-plane host 203.0.113.10:443 reachable (TCP)
[OK]    self-check passed

[OK]    installed:    ongrid-edge v0.7.159
[OK]    connected:    edge_id=42 via 203.0.113.10:40012
[OK]    tail logs:    journalctl -u ongrid-edge -f

5. UI 에서 확인 ​

브라우저로 돌아가서.

  • Edges — 녹색 "online" 점과 함께 목록에 edge 가 보입니다. 카드에는 hostname, 커널 버전, 총 RAM, 디스크, 배포판이 표시됩니다.
  • Monitor — edge 를 고릅니다. 약 30 초 안에 CPU, 메모리, 디스크, load, 네트워크 IO 차트가 채워지기 시작합니다. /grafana/ 서브 경로를 통해 페이지에 임베드된 Grafana 패널입니다.
  • Logs — edge 를 고릅니다. /var/log/* 와 systemd journal 을 실시간으로 tail; 검색 바에서 LogQL 지원.
  • Topology — edge 가 호스트 노드로 나타납니다. 더 많은 edge 를 추가하거나 (expand_topology 기능으로 서비스를 발견하면) 그래프가 점점 채워집니다.

6. 에이전트에게 물어보기 ​

Chat 으로 돌아갑니다. 다음 중 하나를 시도하세요.

  • "List my edges and show me which has the highest load."
  • "Tail /var/log/syslog on prod-web-01 for the last 5 minutes."
  • "Why did CPU spike on prod-web-01 around 10:42?"

에이전트는 실제 도구들을 호출합니다 — list_edges, bash, query_promql, search_logs, find_topology_node 등. 대화 로그는 각 호출을 접을 수 있는 칩으로 보여 줍니다. 칩을 클릭하면 인자와 출력을 볼 수 있습니다.

다음은? ​

  • 채널 구성 — 에이전트가 Slack / Telegram / Larksuite / DingTalk / WeCom 에서 답할 수 있게.
  • 알림 규칙 작성 — Ongrid 는 6 개의 내장 호스트 규칙과 PromQL / log_match / log_volume / trace_latency / trace_error_rate 를 포함한 14 개의 규칙 kind 를 제공합니다.
  • 지식 베이스 연결 — 내장 vault 는 오프라인. 자체 조직 플레이북 (Markdown, PDF, DOCX) 을 추가하거나 Git 저장소를 동기화하세요.
  • 프로덕션 하드닝 — self-signed TLS 인증서 교체, ONGRID_PUBLIC_URL 을 실제 도메인으로 설정, /var/lib/ongrid 백업, 예산 상한이 있는 실제 default_provider 설정.

제거

매니저에서: cd ongrid-vX.Y.Z-linux-amd64 && sudo ./uninstall.sh. edge 에서: curl -k -sSL https://<server>/install.sh | sudo bash -s -- --uninstall. /var/log/ongrid-edge 아래 로그는 보존됩니다.