백엔드 설정 가이드
백엔드 설정 가이드 (Backend Setup Guide)
AgentOps 백엔드 서비스를 설정하고 실행하는 완전한 가이드를 소개해요. 아키텍처 개요부터 사전 요구사항, 퀵 스타트, 외부 서비스 설정까지 알아볼게요.
출처: 문서
본문
백엔드 설정 가이드
이 가이드는 /app 디렉토리에서 AgentOps 백엔드 서비스를 설정하고 실행하는 방법을 다룹니다. 백엔드는 API 서버, 대시보드, 데이터베이스 서비스, 그리고 관측성 인프라를 포함합니다.
아키텍처 개요 (Architecture Overview)
AgentOps 백엔드는 여러 상호 연결된 서비스로 구성됩니다.
- API Server (
api/) - 인증, 빌링, 데이터 처리를 담당하는 FastAPI 백엔드 - Dashboard (
dashboard/) - 시각화와 관리를 위한 Next.js 프론트엔드 - Supabase - 인증과 기본 PostgreSQL 데이터베이스
- ClickHouse - 트레이스와 메트릭용 분석 데이터베이스
- OpenTelemetry Collector - 관측성과 트레이스 수집
- Redis (선택) - 캐싱과 세션 스토리지
사전 요구사항 (Prerequisites)
백엔드를 설정하기 전에 다음이 설치되어 있는지 확인하세요.
필수 소프트웨어 (Required Software)
- Node.js 18+ (다운로드)
- Python 3.12+ (다운로드)
- Docker & Docker Compose (다운로드)
- Bun (권장) 또는 npm (Bun 설치)
- uv (Python용 권장) (uv 설치)
- Just (선택, 편의 명령어용) (Just 설치)
외부 서비스 (External Services)
다음 외부 서비스에 대한 계정과 설정이 필요합니다.
- Supabase - 데이터베이스와 인증 (supabase.com)
- ClickHouse Cloud - 분석 데이터베이스 (clickhouse.com/cloud)
- Stripe (선택) - 결제 처리 (stripe.com)
퀵 스타트 (Quick Start)
1. 클론과 이동 (Clone and Navigate)
git clone https://github.com/AgentOps-AI/AgentOps.Next.git
cd AgentOps.Next/app
2. 환경 설정 (Environment Setup)
환경 파일을 복사하고 구성합니다.
# Root environment (for Docker Compose)
cp .env.example .env
# API environment
cp api/.env.example api/.env
# Dashboard environment
cp dashboard/.env.example dashboard/.env.local
3. 의존성 설치 (Install Dependencies)
# Using Just (recommended)
just install
# Or manually:
bun install # Root dependencies
uv pip install -r requirements-dev.txt # Python dev tools
cd api && uv pip install -e . && cd .. # API dependencies
cd dashboard && bun install && cd .. # Dashboard dependencies
4. 외부 서비스 설정 (Configure External Services)
서비스 자격 증명으로 .env 파일을 업데이트하세요. 아래의 외부 서비스 설정을 참조하세요.
5. 서비스 시작 (Start Services)
# Option 1: Using Docker Compose (recommended)
docker-compose up -d
# Option 2: Using Just commands
just api-run # Start API server
just fe-run # Start dashboard (in another terminal)
# Option 3: Native development
cd api && uv run python run.py # API server
cd dashboard && bun dev # Dashboard (in another terminal)
6. 설정 검증 (Verify Setup)
- Dashboard: http://localhost:3000
- API Documentation: http://localhost:8000/redoc
- API Health Check: http://localhost:8000/health
외부 서비스 설정 (External Services Configuration)
Supabase 설정
- supabase.com에서 새 프로젝트 생성
- Settings → API로 이동해 키를 가져오세요
- 데이터베이스 마이그레이션 실행:
cd supabase npx supabase db push .env파일을 다음으로 업데이트:NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key SUPABASE_SERVICE_ROLE_KEY=your-service-role-key SUPABASE_PROJECT_ID=your-project-id
ClickHouse 설정
- ClickHouse Cloud에 가입하거나 자체 호스팅
- 데이터베이스를 만들고 연결 정보를 가져오세요
- ClickHouse 마이그레이션 실행:
# Apply schema from clickhouse/schema_dump.sql .env파일을 다음으로 업데이트:CLICKHOUSE_HOST=your-host.clickhouse.cloud CLICKHOUSE_PORT=8123 CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD=your-password CLICKHOUSE_DATABASE=your-database CLICKHOUSE_SECURE=true
Stripe 설정 (선택)
빌링 기능을 위해:
- Stripe 계정 생성
- 대시보드에서 API 키 가져오기
.env파일을 다음으로 업데이트:NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_... STRIPE_SECRET_KEY=sk_test_... STRIPE_WEBHOOK_SECRET=whsec_...
추가 서비스 (선택)
- Sentry: 오류 모니터링
SENTRY_DSN=https://***@sentry.io/project-id SENTRY_ENVIRONMENT=development - PostHog: 분석
NEXT_PUBLIC_POSTHOG_KEY=phc_your-key NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com
개발 워크플로우 (Development Workflow)
Just 명령어 사용 (권장)
justfile은 개발을 위한 편리한 명령어를 제공합니다.
# Setup and installation
just setup # Complete development setup
just install # Install all dependencies
# API Development
just api-native # Run API natively (fastest)
just api-build # Build API Docker image
just api-run # Run API in Docker
just api-test # Run API tests
# Frontend Development
just fe-run # Run dashboard development server
just fe-build # Build dashboard for production
just fe-test # Run frontend tests
# Code Quality
just lint # Run all linting checks
just format # Format all code
just test # Run all tests
# Docker Management
just up # Start all services
just down # Stop all services
just logs # View service logs
just clean # Clean up Docker resources
수동 개발 (Manual Development)
서비스를 수동으로 실행하는 것을 선호한다면:
# Start API server
cd api && uv run python run.py
# Start dashboard (in another terminal)
cd dashboard && bun dev
# Start landing page (in another terminal)
cd landing && bun dev
서비스 설정 (Service Configuration)
API 서버 설정
API 서버(api/.env)의 핵심 환경 변수:
# Database connections
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-service-role-key
CLICKHOUSE_HOST=your-clickhouse-host
# Application settings
APP_URL=http://localhost:3000
LOGGING_LEVEL=INFO
JWT_SECRET_KEY=your-jwt-secret
# External integrations
SENTRY_DSN=your-sentry-dsn
대시보드 설정
대시보드(dashboard/.env.local)의 핵심 환경 변수:
# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
# Application URLs
NEXT_PUBLIC_APP_URL=http://localhost:8000
NEXT_PUBLIC_SITE_URL=http://localhost:3000
# Features
NEXT_PUBLIC_ENVIRONMENT_TYPE=development
NEXT_PUBLIC_PLAYGROUND=true
문제 해결 (Troubleshooting)
일반적인 문제 (Common Issues)
포트 충돌 (Port conflicts):
# Check what's running on ports 3000 and 8000
lsof -i :3000
lsof -i :8000
데이터베이스 연결 문제 (Database connection issues):
- Supabase와 ClickHouse 자격 증명을 확인하세요
- 외부 서비스에 대한 네트워크 연결을 확인하세요
- 데이터베이스 마이그레이션이 적용되었는지 확인하세요
Docker 문제 (Docker issues):
# Reset Docker environment
just clean
docker system prune -f
just up
의존성 문제 (Dependency issues):
# Clean and reinstall
rm -rf node_modules api/.venv dashboard/node_modules
just install
로그와 디버깅 (Logs and Debugging)
# View service logs
just logs
# View specific service logs
docker-compose logs api
docker-compose logs dashboard
# Run with debug logging
LOGGING_LEVEL=DEBUG just api-run
다음 단계 (Next Steps)
백엔드가 실행되면:
- http://localhost:3000에서 계정을 생성하세요
- 대시보드에서 API 키를 생성하세요
- AgentOps SDK를 설치하고 AI 에이전트 추적을 시작하세요
- 대시보드를 탐색해 트레이스와 분석을 확인하세요
프로덕션 배포에 대해서는 배포 가이드를 참조하세요.