인프라 아키텍처¶

GovOn 시스템의 배포 인프라 구성, Docker Compose 서비스 토폴로지, GPU 할당, 네트워크 아키텍처, 모니터링, 확장 전략을 설명���다.

전체 배포 아키텍처¶

graph TB
    subgraph "GitHub (소스 및 레지스트리)"
        REPO[GitHub Repository<br/>GovOn-Org/GovOn]
        GHCR[GitHub Container Registry<br/>ghcr.io/govon-org/govon]
        RELEASE[GitHub Releases<br/>오프라인 패키지]
    end

    subgraph "CI/CD Pipeline"
        CI[GitHub Actions]
        TRIVY[Trivy 보안 스캔]
        SMOKE[Smoke Test]
    end

    subgraph "온라인 배포 대상 서버"
        DOCKER_ONLINE[Docker Engine]
        GPU_ONLINE[NVIDIA GPU]
        COMPOSE_ONLINE[docker-compose.yml]
    end

    subgraph "오프라인 배포 대상 서버 (폐쇄망)"
        USB[USB / 외장 매체]
        DOCKER_OFFLINE[Docker Engine]
        GPU_OFFLINE[NVIDIA GPU]
        COMPOSE_OFFLINE[docker-compose.offline.yml]
    end

    subgraph "Docker 컨테이너"
        APP[FastAPI + vLLM<br/>포트 8000]
        VOLUMES["볼륨 마운트<br/>models/ | data/ | agents/ | configs/"]
    end

    REPO -->|main push / v* tag| CI
    CI -->|Build & Push| GHCR
    CI --> TRIVY
    CI --> SMOKE
    CI -->|Release 발행| RELEASE

    GHCR -->|docker pull| DOCKER_ONLINE
    DOCKER_ONLINE --> COMPOSE_ONLINE
    COMPOSE_ONLINE --> APP
    GPU_ONLINE --> APP

    RELEASE -->|govon-offline-package.tar.gz| USB
    USB -->|물리 전달| DOCKER_OFFLINE
    DOCKER_OFFLINE -->|docker load| COMPOSE_OFFLINE
    COMPOSE_OFFLINE --> APP
    GPU_OFFLINE --> APP

    APP --> VOLUMES

Docker Compose 서비스 토폴로지¶

컨테이너 내부 구조¶

graph LR
    subgraph "Docker 컨테이너 (govon-backend)"
        API[FastAPI API 서버<br/>포트 8000]
        VLLM[vLLM 엔진<br/>EXAONE-Deep-7.8B AWQ]
        FAISS[FAISS 벡터 검색<br/>multilingual-e5-large]
        BM25[BM25 텍스트 검색]
        RAG[RAG 파이프라인]
        AGENT[에이전트 매니저<br/>분류/생성 에이전트]

        API --> VLLM
        API --> RAG
        API --> AGENT
        RAG --> FAISS
        RAG --> BM25
        AGENT --> VLLM
    end

    subgraph "볼륨 마운트"
        MODEL["/app/models<br/>모델 파일, 인덱스"]
        DATA["/app/data<br/>학습/검색 데이터"]
        AGENTDIR["/app/agents<br/>에이전트 설정 YAML"]
        CONFIG["/app/configs<br/>시스템 설정"]
    end

    subgraph "외부"
        CLIENT["웹 브라우저<br/>Next.js 프론트엔드"]
        GPU[NVIDIA GPU<br/>CUDA 12.x]
    end

    CLIENT -->|HTTP :8000| API
    GPU -->|CUDA| VLLM
    GPU -->|CUDA| FAISS
    MODEL --> VLLM
    MODEL --> FAISS
    MODEL --> BM25
    DATA --> RAG
    AGENTDIR --> AGENT
    CONFIG --> API

서비스 구성 파일¶

볼륨 마운트 구조¶

컨테이너 설정¶

# docker-compose.yml 핵심 설정
services:
  govon-backend:
    image: ghcr.io/govon-org/govon:latest
    ports:
      - "8000:8000"
    env_file:
      - .env
    volumes:
      - ./models:/app/models
      - ./data:/app/data
      - ./agents:/app/agents
      - ./configs:/app/configs
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 120s  # 모델 로딩에 시간이 걸림
    restart: unless-stopped

GPU 할당 및 VRAM 요구사항¶

VRAM 사용량 분석¶

pie title GPU VRAM 사용량 분포 (16GB 기준)
    "EXAONE AWQ 모델 가중치" : 5
    "vLLM KV 캐시" : 5
    "multilingual-e5-large 임베딩" : 2
    "CUDA 런타임 오버헤드" : 1
    "여유 공간" : 3

환경별 권장 사양¶

네트워크 아키텍처: 폐쇄망 (Closed Network)¶

GovOn은 행정기관 내부망(폐쇄망)에서의 운영을 기본 전제로 설계되었다.

폐쇄망 네트워크 구성¶

graph TB
    subgraph "행정기관 내부망 (폐쇄망)"
        subgraph "민원 처리 영역"
            USER1[민원 담당자 A]
            USER2[민원 담당자 B]
            USER3[민원 담당자 C]
        end

        subgraph "GovOn 서버"
            LB[로드 밸런서 / Nginx]
            API1["GovOn API (Blue)<br/>:8001"]
            API2["GovOn API (Green)<br/>:8002"]
            GPU1[NVIDIA GPU]
        end

        subgraph "데이터 영역"
            DB[(민원 데이터 DB)]
            INDEX[(FAISS 벡터 인덱스)]
            MODEL[(EXAONE 모델)]
        end

        USER1 --> LB
        USER2 --> LB
        USER3 --> LB
        LB --> API1
        LB --> API2
        API1 --> GPU1
        API2 --> GPU1
        API1 --> DB
        API1 --> INDEX
        API1 --> MODEL
        API2 --> DB
        API2 --> INDEX
        API2 --> MODEL
    end

    subgraph "외부 네트워크"
        INTERNET[인터넷]
    end

    LB -.-x|완전 차단| INTERNET

    style INTERNET fill:#f66,stroke:#333

포트 구성¶

온라인 vs 오프라인 배포 비교¶

모니터링¶

/health 엔드포인트¶

서버 상태를 확인하는 헬스 체크 엔드포인트이다. 인증 없이 접근 가능하다.

curl -s http://localhost:8000/health | python -m json.tool

{
    "status": "healthy",
    "rag_enabled": true,
    "indexes": null
}

Docker 헬스체크¶

docker-compose.yml에 정의된 헬스체크가 30초 간격으로 /health 엔드포인트를 호출한다.

# 컨테이너 헬스 상태 확인
docker inspect --format='{{.State.Health.Status}}' govon-backend

# 헬스체크 로그 확인
docker inspect --format='{{json .State.Health}}' govon-backend | python -m json.tool

모니터링 대시보드 구성¶

graph LR
    subgraph "GovOn 서버"
        API[FastAPI<br/>/health]
        LOGS[loguru 로그<br/>stdout/stderr]
        GPU_MON[nvidia-smi<br/>GPU 메트릭]
    end

    subgraph "모니터링 스택"
        PROM[Prometheus<br/>메트릭 수집]
        GRAFANA[Grafana<br/>대시보드]
        LOKI[Loki<br/>로그 수집]
    end

    API -->|HTTP scrape| PROM
    LOGS -->|log driver| LOKI
    GPU_MON -->|DCGM exporter| PROM
    PROM --> GRAFANA
    LOKI --> GRAFANA

주요 모니터링 지표¶

CI/CD 배포 파이프라인¶

graph LR
    subgraph "트리거"
        PUSH[main 브랜치 Push]
        TAG["v* 태그 생성"]
        REL[Release 발행]
    end

    subgraph "Docker Publish 워크플로우"
        BUILD["Docker Build<br/>(Buildx)"]
        PUSH_IMG["GHCR Push<br/>latest / sha-* / v*"]
        SCAN["Trivy 보안 스캔<br/>CRITICAL, HIGH"]
        TEST["Smoke Test<br/>이미지 구조 검증"]
    end

    subgraph "Offline Package 워크플로우"
        PULL[GHCR에서 Pull]
        SAVE["docker save<br/>govon-image.tar.gz"]
        PACKAGE["패키징<br/>govon-offline-package.tar.gz"]
        UPLOAD[Release 에셋 업로드]
    end

    PUSH --> BUILD
    TAG --> BUILD
    BUILD --> PUSH_IMG
    PUSH_IMG --> SCAN
    PUSH_IMG --> TEST

    REL --> PULL
    PULL --> SAVE
    SAVE --> PACKAGE
    PACKAGE --> UPLOAD

배포 모드별 상세¶

온라인 배포¶

개발자 PC → git push → GitHub Actions → GHCR → 서버에서 docker pull → docker compose up

• main 브랜치에 push할 때마다 최신 이미지가 자동으로 빌드되어 GHCR에 저장된다
• 서버에서 docker pull로 최신 이미지를 가져와 배포한다
• Blue/Green 배포 스크립트(scripts/deploy.sh)를 사용하면 무중단 업데이트가 가능하다

오프라인 배포¶

GitHub Release 발행 → 오프라인 패키지 자동 생성 → USB 전달 → offline-deploy.sh ���행

• Release를 발행하면 GitHub Actions가 자동으로 오프라인 패키지를 생성한다
• 패키지에는 Docker 이미지 아카이브, 배포 스크립트, Compose 파일이 포함된다
• 폐��망 서버에서 offline-deploy.sh 한 번 실행으로 전체 배포가 완료된다

243개 기초자치단체 확장 전략¶

GovOn은 전국 243개 기초자치단체에 배포하는 것을 목표로 설계되었다.

확장 모델¶

graph TB
    subgraph "중앙 관리"
        CENTRAL["중앙 관리 서버<br/>(온라인 환경)"]
        REGISTRY[이미지 레지스트리<br/>GHCR]
        UPDATE[업데이트 패키지<br/>GitHub Releases]
    end

    subgraph "지자체 A (온라인)"
        A_SERVER["GovOn 서버 A"]
        A_GPU[GPU]
        A_DATA[(지역 민원 데이터)]
    end

    subgraph "지자체 B (폐쇄망)"
        B_SERVER["GovOn 서버 B"]
        B_GPU[GPU]
        B_DATA[(지역 민원 데이터)]
    end

    subgraph "지자체 C (폐쇄망)"
        C_SERVER["GovOn 서버 C"]
        C_GPU[GPU]
        C_DATA[(지역 민원 데이터)]
    end

    CENTRAL --> REGISTRY
    CENTRAL --> UPDATE
    REGISTRY -->|docker pull| A_SERVER
    UPDATE -->|USB 전달| B_SERVER
    UPDATE -->|USB 전달| C_SERVER
    A_GPU --> A_SERVER
    B_GPU --> B_SERVER
    C_GPU --> C_SERVER
    A_DATA --> A_SERVER
    B_DATA --> B_SERVER
    C_DATA --> C_SERVER

확장 시 고려사항¶

하이브리드 전략: 온프레미스 + 클라우드¶

GovOn은 사건별 핵심 데이터와 공개/공통 데이터를 구조적으로 분리하는 하이브리드 전략을 따른다.

graph TB
    subgraph "온프레미스 고정 (Case Core Zone)"
        CASE[민원 원문 / 상담이력]
        ATTACH[첨부 증빙 OCR 결과]
        LOG[프롬프트 로그 / 평가 로그]
        MEMO[내부 처리 메모]
    end

    subgraph "클라우드 연계 가능 (Common Data Zone)"
        LAW[공개 법령 / 지침]
        MANUAL[표준 매뉴얼 / 보도자료]
        AIHUB[AI Hub 공개 데이��]
        FAQ[공개 FAQ]
    end

    subgraph "Docker 컨테이너"
        ENGINE[AI 추론 엔진<br/>vLLM + FAISS]
    end

    CASE --> ENGINE
    ATTACH --> ENGINE
    LOG --> ENGINE
    MEMO --> ENGINE
    LAW --> ENGINE
    MANUAL --> ENGINE
    AIHUB --> ENGINE
    FAQ --> ENGINE

데이터 배치 전략¶

관련 문서¶

• 시작하기 -- Docker 기반 실행, 환경 변수 설정
• 보안 정책 -- 온프레미스 보안 이점, 네트워크 격리
• 트러블슈팅 -- Docker 네트워킹, GPU 인식 문제
• 온라인 배포 -- 온라인 환경 배포 절차 상세
• 오프라인 배포 -- 폐���망 배포 절차 상세
• Docker 가이드 -- Docker 이미지 빌드, 컨테이너 관리