Jacode 관리자 가이드

이 문서는 Jacode 시스템 관리자를 위한 가이드입니다. 시스템 설치, AI 모델 설정, 사용자 관리 및 문제 해결 방법을 다룹니다.

1. 시스템 요구사항 및 설치

필수 구성 요소

• OS: Linux (Ubuntu 20.04+ 권장), macOS, Windows (WSL2)
• Runtime: Node.js v18 이상 (LTS 권장)
• Database: PostgreSQL 16
• Cache: Redis 7
• AI Engine: Ollama (또는 vLLM)
• Container: Docker & Docker Compose (선택 사항)

설치 절차 (Docker Compose 권장)

1. 저장소를 클론하고 프로젝트 루트로 이동합니다.
2. 환경 변수 파일을 준비합니다.

   cp .env.example .env
   # .env 파일 내의 POSTGRES_*, REDIS_*, JWT_SECRET 등을 설정합니다.
   

3. Docker Compose로 실행합니다.

   docker-compose up -d
   

4. 초기 데이터베이스 마이그레이션 및 시딩을 수행합니다.

   docker-compose exec backend npm run prisma:migrate
   docker-compose exec backend npm run db:seed
   

2. AI Provider 설정

Jacode는 다양한 로컬 LLM 서버(Provider)를 지원합니다.

지원 Provider

• Ollama: 설치가 간편하고 개인용/소규모 팀에 적합합니다.
• vLLM: 고성능 추론이 필요하거나 엔터프라이즈 환경에 적합합니다.

Provider 연결 설정

1. 관리자 대시보드 > Settings 페이지로 이동합니다.
2. Global AI Settings 섹션에서 AI API URL을 설정합니다.
   • 예: http://localhost:11434 (Ollama 기본값)
3. API Key: 필요한 경우 API 키를 입력합니다 (Ollama는 불필요).

3. 모델 및 라우팅 정책 관리 (Model & Routing)

모델 관리

• 시스템은 연결된 Provider에서 사용 가능한 모델 목록을 자동으로 가져옵니다.
• Admin > Models 메뉴에서 개별 모델을 활성화/비활성화할 수 있습니다.
• 모델별로 ‘용도(Capability)’를 태깅할 수 있습니다 (예: coding, chat, embedding).

라우팅 정책 (Routing Policy)

작업 유형에 따라 어떤 모델을 사용할지 결정하는 규칙을 설정합니다.

• Admin > Routing Policies 메뉴로 이동합니다.
• Rules 예시:
  • Chat 요청 -> 속도가 빠른 mistral:7b 모델 사용
  • Code Generation 요청 -> 성능이 좋은 codellama:13b 또는 deepseek-coder 모델 사용
• 가중치(Cost, Performance, Availability) 기반으로 점수를 매겨 최적의 모델을 선택하도록 설정할 수 있습니다.

4. 보안 및 제한 설정 (Security & Limits)

보안 설정

• Prompt Injection Protection: 사용자 입력에 대한 인젝션 공격 탐지 활성화 여부를 설정합니다.
• PII Masking: 코드 생성 시 이메일, IP 등 민감 정보 마스킹 여부를 설정합니다.
• Code Safety Check: 생성된 코드에 취약점 패턴이 있는지 검사합니다.

사용량 제한 (Rate Limiting)

• 사용자별/IP별 분당 요청 횟수 제한 설정이 가능합니다.
• Throttler 설정을 통해 과도한 리소스 사용을 방지합니다.

5. 문제 해결 (Troubleshooting)

주요 이슈

Q: AI 응답이 오지 않고 타임아웃이 발생합니다.

• 확인: 백엔드 서버에서 AI Provider(Ollama/vLLM) URL로 접속이 가능한지 확인하세요 (curl 테스트).
• 조치: Docker 환경인 경우 host.docker.internal 또는 올바른 서비스 이름을 사용했는지 확인하세요. 모델이 로드되는 데 시간이 오래 걸릴 수 있으므로 타임아웃 설정을 늘려보세요.

Q: “No active model found” 에러가 발생합니다.

• 확인: 관리자 페이지에서 활성화된(Active) 모델이 하나 이상 있는지 확인하세요.
• 조치: Provider 연결을 확인하고 Sync Models 버튼을 눌러 모델 목록을 갱신하세요.

Q: 데이터베이스 연결 오류

• 확인: .env 파일의 DATABASE_URL이 올바른지 확인하세요.
• 조치: PostgreSQL 서비스가 실행 중인지 확인하고 로그를 점검하세요.

로그 확인

• 백엔드 로그: docker-compose logs -f backend
• 프론트엔드 로그: docker-compose logs -f frontend