Claire Bible은 안정적인 개인용 프로덕션 운영을 위해 Docker Compose 기반의 컨테이너 아키텍처와 전용 호스트 관리 스크립트인 `cb-manuscript`를 제공합니다.

5.1 호스트 사전 요구사항

배포 대상 Linux 호스트는 다음 요건을 만족해야 합니다:

  • 운영체제: Linux (Ubuntu 22.04 / 24.04 LTS 권장, 또는 WSL2 Ubuntu)

  • Python: Python 3.10 이상 (fcntl, sqlite3 표준 모듈 내장)

  • Docker: Docker Engine 24.0+ 및 Docker Compose V2 plugin (docker compose)

  • 네트워크: GitHub, Container Registry, Python Package Index(PyPI) 접근을 위한 아웃바운드 HTTPS 통신

# Ubuntu 기본 패키지 설치
sudo apt update
sudo apt install -y bash ca-certificates curl git python3

# Docker 및 Compose 버전 점검
docker --version
docker compose version

5.2 호스트 관리 도구 (cb-manuscript)

배포된 인스턴스의 전체 수명주기는 저장소 루트의 ./cb-manuscript 스크립트를 통해 통제합니다.

명령어 단계 설명

./cb-manuscript init

환경 초기화

`.env.example`을 복사하여 `.env`를 생성하고, 보안 소유자 토큰을 발급하며 디렉터리 권한을 설정합니다.

./cb-manuscript config

설정 검증

현재 활성화된 환경변수, 포트 바인딩, 볼륨 마운트 경로의 유효성을 검사합니다.

./cb-manuscript build

이미지 빌드

소스 변경 사항을 반영하여 Claire 애플리케이션 컨테이너 이미지를 빌드합니다.

./cb-manuscript up -d

서비스 기동

스키마 마이그레이션을 자동으로 실행하고 API 서버 및 백그라운드 워커를 기동합니다.

./cb-manuscript down

서비스 중지

실행 중인 컨테이너들을 안전하게 정지하고 네트워크를 정리합니다.

./cb-manuscript logs -f

로그 모니터링

전체 컨테이너의 실시간 통합 로그 스트림을 확인합니다.

./cb-manuscript update

무중단 업데이트

Git 최신 커밋 fetch → 이미지 빌드 → Writer 정지 → 마이그레이션 → 서비스 재기동을 순차 수행합니다.

5.3 환경 설정 파일 (.env)

init 명령 실행 시 생성되는 .env 파일의 주요 설정 항목입니다:

# 기본 환경 설정
CLAIRE_ENVIRONMENT=production
CB_API_BIND=127.0.0.1
CB_API_PORT=8765
CLAIRE_PUBLIC_URL=https://kb.example.com/

# 보안 및 토큰
CLAIRE_INJECT_TOKEN=sec_owner_token_generated_automatically
CLAIRE_ANONYMOUS_READONLY=1

# LLM 프로바이더 설정
GEMINI_API_KEY=your_gemini_api_key_here
CLAIRE_MODEL_NAME=gemini-1.5-pro-latest

# 텔레그램 봇 (선택)
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
TELEGRAM_ALLOWED_USERS=123456789

# 저장 경로
CB_DATA_DIR=./data
CB_VAULT_DIR=./vault

개발(Dev) 프로파일과의 분리

동일한 호스트에서 격리된 테스트를 진행할 때는 ./cb-manuscript dev <명령어>`를 사용합니다. 이는 `.env.dev 오버레이를 적용하여 포트 충돌 없이 완전히 분리된 데이터 디렉터리로 동작합니다.

5.4 외부 접속 및 Reverse Proxy 연동

Claire Bible API는 보안을 위해 로컬 루프백(127.0.0.1) 바인딩을 기본 원칙으로 합니다. 외부 인터넷에서 안전하게 접속하려면 Nginx 또는 Caddy와 같은 Reverse Proxy를 전면에 배치하고 TLS 암호화를 적용해야 합니다.

Nginx 프록시 설정 예시

server {
    listen 443 ssl http2;
    server_name kb.example.com;

    ssl_certificate /etc/letsencrypt/live/kb.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/kb.example.com/privkey.pem;

    # 프록시 헤더 설정
    location / {
        proxy_pass http://127.0.0.1:8765;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 및 스트리밍 지원
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }
}

보안 경계 원칙

  • CLAIRE_ANONYMOUS_READONLY=1 모드에서는 인증 토큰이 없는 일반 방문자가 웹 UI와 검색을 열람할 수 있지만, 데이터 변경(쓰기)이나 LLM 요약 API 호출은 완전히 차단되어 API 비용 누수를 방지합니다.

  • 숨김 문서(hidden=1) 및 해당 문서에만 연결된 엔티티는 익명 조회 시 시스템 수준에서 필터링되어 노출되지 않습니다.

5.5 데이터 영속성 및 백업/복원

지식베이스의 정본 데이터는 data/claire.db (SQLite) 파일에 저장되며, Obsidian 마크다운 문서는 vault/ 디렉터리에 실시간 투영됩니다.

백업 절차

SQLite 데이터베이스의 일관성을 보장하기 위해 온라인 백업 API 또는 cb-manuscript 백업을 활용합니다.

# 안전한 SQLite 백업 생성
sqlite3 ./data/claire.db ".backup './data/claire_backup_$(date +%Y%m%d).db'"

# 전체 데이터 압축 아카이브
tar -czvf "claire_backup_$(date +%Y%m%d).tar.gz" ./data ./vault .env

복원 절차

  1. `./cb-manuscript down`으로 모든 서비스 컨테이너를 중지합니다.

  2. 백업된 claire.db 파일을 data/ 디렉터리에 복원합니다.

  3. `./cb-manuscript up -d`로 서비스를 재기동하고 `./cb-manuscript app doctor`로 무결성을 검증합니다.

이 페이지가 도움이 되었나요?