---

주의: 이 프로젝트는 활발히 발전 중입니다. 견고한 핵심 기능과 테스트 범위를 갖추고 있으며, 각 릴리스마다 문서, 보안 강화, 기능 깊이를 계속 개선하고 있습니다. 기여, 버그 신고, 피드백을 환영합니다.

기능

• 시각적 그래프 조사 — 엔티티 드래그 앤 드롭, 대화형으로 연결 탐색
• 20개 이상의 내장 변환 — DNS, WHOIS, SSL 인증서, 지리적 위치, 웹/이메일/해시/소셜 인리치먼트 등
• Transform Hub — 레지스트리에서 커뮤니티 변환 탐색 및 설치
• AI 조사관 — 프롬프트 기반 에이전트 조사로 변환 실행 계획, 실시간 진행 스트리밍, 감사 가능한 결과 요약
• 가져오기 / 내보내기 — JSON, CSV, GraphML, MTGX 형식 가져오기
• 그래프 분석 — 중심성, 커뮤니티 탐지, 최단 경로
• 실시간 협업 — Supabase Realtime을 통한 프로젝트, 공유, 실시간 동기화
• 비동기 변환 작업 — WebSocket 진행 업데이트가 포함된 Redis/RQ 큐
• 플러그인 시스템 — YAML 매니페스트를 사용한 디렉터리 기반 플러그인 검색
• CLI 도구 — 터미널에서 변환 검색, 설치, 관리
• 어디서나 실행 — 로컬 SQLite 모드(설정 불필요) 또는 팀/클라우드 설정용 PostgreSQL + Supabase
• Docker 지원 — docker compose up 한 번으로 배포

스크린샷

빠른 시작

사전 요구 사항

도구	버전
Python	3.14+
uv	최신
Node.js	20+
pnpm	최신

백엔드```bash

cd backend uv sync uv run uvicorn ogi.main:app --reload

API는 `http://localhost:8000`에서 사용할 수 있습니다.

로컬 변환 실행을 위해서는 Redis와 변환 작업자도 실행 중이어야 합니다. Redis만으로는 충분하지 않습니다.

Redis 시작:```bash
docker run -d --name ogi-redis -p 6379:6379 redis:7-alpine

두 번째 터미널에서 변환 작업자를 시작하십시오:```bash cd backend uv run python -m ogi.worker.run_worker

`Job queue not available` 또는 `Redis not available`가 표시되면 다음을 확인하세요:

- `OGI_REDIS_URL`이 로컬 호스트 기반 실행의 경우 `redis://localhost:6379/0`을 가리키는지
- Redis가 실행된 후 백엔드가 재시작되었는지
- 별도의 worker 프로세스가 실행 중인지
- Docker Compose 외부에서 Docker 전용 호스트명 `redis`를 사용하지 않는지

PostgreSQL (`OGI_USE_SQLITE=false`)에 대해 백엔드를 실행하면 시작 시 요청을 처리하기 전에 Alembic 마이그레이션이 자동으로 적용됩니다. Docker 배포도 백엔드 컨테이너 진입점에서 동일하게 수행합니다.

AI Investigator 실행은 또 다른 별도의 worker에 의해 처리됩니다:```bash
cd backend
uv run python -m ogi.agent.run_worker

프론트엔드```bash

cd frontend pnpm install pnpm dev

Open http://localhost:5173. 그게 전부입니다.

### AI Investigator

AI Investigator는 선택적 공급자 기반 워크플로로, 변환 시퀀스를 계획하고, 승인을 요청하며, 작업 공간 내에서 조사 진행 상황을 요약할 수 있습니다.

- 프로젝트 내에서 `AI Investigator` 탭을 엽니다.
- 조사자 설정 대화상자에서 공급자와 모델을 구성합니다.
- 공급자 API 키를 `API Keys`에 저장합니다.
- 백엔드와 함께 별도의 `agent-worker` 프로세스를 실행합니다.

현재 구현은 사용자별 공급자 구성과 메인 API 서버와 독립적으로 조사 단계를 실행하는 전용 워커를 지원합니다.

### CLI

CLI를 실행하는 두 가지 지원 방식:

**권장** (활성화 불필요):```bash
cd backend
uv sync
uv run ogi --help

활성화된 virtualenv (일반 ogi 명령):```bash cd backend uv venv

PowerShell:

..venv\Scripts\Activate.ps1 uv pip install -e . ogi --help

## Docker

### 개발```bash
cp .env.example .env
docker compose up

프로덕션

사전 빌드된 GHCR 이미지를 사용하세요.

중요: docker-compose.prod.yml은 외부 PostgreSQL 데이터베이스가 필요합니다. db 서비스를 포함하지 않습니다.

내장 Postgres 및 Redis가 포함된 올인원 로컬 Docker 스택을 원하신다면 다음을 사용하세요:```bash docker compose up -d

도달 가능한 PostgreSQL 인스턴스가 이미 있고 `OGI_DATABASE_URL`을 적절히 설정한 경우에만 프로덕션 compose 파일을 사용하세요:```bash
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

.env 파일에서 OGI_IMAGE_TAG를 설정하여 특정 릴리스 이미지 태그를 고정할 수 있습니다 (예: v0.2.6). 기본값은 latest입니다.

Hetzner Cloud

새로운 Hetzner 사용자는 첫 번째 링크를 사용하여 Hetzner Cloud 크레딧으로 가입할 수 있습니다. 이 링크는 추천 링크이므로, 추천이 적격할 경우 OGI 유지 관리자도 Hetzner Cloud 크레딧을 받을 수 있습니다. 서버를 생성한 후 위의 Docker 배포 명령어를 사용하여 OGI를 실행하세요.

구성 가능한 변환 상한

OGI는 max_results, max_links, max_urls, max_content_chars와 같은 항목에 대해 합리적인 변환별 최대값을 제공하지만, 이제 이러한 상한을 중앙에서 재정의할 수 있어 클라우드 배포에서 로컬 제한을 하드코딩하지 않고도 적용할 수 있습니다.

.env에서 OGI_TRANSFORM_SETTING_MAX_OVERRIDES를 사용하세요:```env OGI_TRANSFORM_SETTING_MAX_OVERRIDES=max_results=50,max_urls=25,max_links=40,max_content_chars=20000

로컬 우선 배포에서 특정 한도를 제거하려면:```env
OGI_TRANSFORM_SETTING_MAX_OVERRIDES=max_results=none,max_urls=none,max_links=none,max_content_chars=none

재정의는 변환 설정 이름으로 키가 지정되며, OGI의 공유 변환 기반/런타임을 사용하는 내장 변환 및 커뮤니티 플러그인에 적용됩니다.

Hosted cloud instance and Supporter plan

ogi.khas.app에서 제공되는 호스티드 클라우드 버전은 사용자가 셀프 호스팅 여부를 결정하기 전에 OGI를 빠르게 사용해볼 수 있도록 처음 구축되었습니다. 이후 350명 이상의 활성 클라우드 사용자를 보유한 이 프로젝트의 가장 인기 있는 사용 방식이 되었습니다.

이러한 사용량은 이 사이드 프로젝트의 인프라 비용도 증가시켰습니다. 따라서 저장소에는 클라우드 전용 Supporter 구독 및 변환 실행 쿨다운 시스템이 포함되어 있습니다. 공용 클라우드 인스턴스에서 무료 사용자는 변환 실행 간 시간 제한이 있을 수 있으며, Supporter 사용자는 Supabase 및 VPS 비용을 지원하기 위해 상징적인 월 3 USD의 구독료를 낼 수 있습니다.

Supporter 구독은 프로필 청구 컨트롤 또는 Stripe 청구 포털에서 취소할 수 있습니다. 취소는 향후 청구를 중단하지만, 유료 구독 기간은 환불되지 않거나 비례 배분되지 않습니다.

이 청구 코드는 의도적으로 구성에 의해 보호됩니다. OGI_DEPLOYMENT_MODE=cloud 및 OGI_CLOUD_BILLING_ENABLED=true인 경우에만 효과가 있습니다. 자체 호스팅 배포는 청구를 비활성화된 상태로 두어야 하며, 청구 또는 페이월 동작이 표시되지 않아야 합니다.

Telemetry

OGI에는 실제 사용 현황, 특히 자체 호스팅 배포 전반에 걸친 사용을 이해하는 데 도움이 되는 설치 수준의 제품 텔레메트리가 포함되어 있습니다.

• OGI_TELEMETRY_ENABLED=true는 텔레메트리 수집을 활성화합니다.
• OGI_TELEMETRY_LEVEL=full은 기본 수집 레벨입니다.
• OGI_TELEMETRY_ENABLED=false로 설정하면 텔레메트리 수집을 완전히 비활성화합니다.
• OGI_TELEMETRY_LEVEL=basic으로 설정하면 전송되는 데이터를 줄입니다.

basic 전송 내용:

• OGI 버전
• 일일 활성 설치 핑

full 추가 전송 내용:

• 인스턴스 생성 날짜
• 해당 기간의 프로젝트, 엔티티, 엣지, 변환 실행, 조사자 실행 및 활성 사용자에 대한 집계 수
• 설치된 변환 및 해당 버전