셀프 호스팅 개요
셀프 호스팅 개요 (Self-Hosting Overview)
AgentOps 백엔드 서비스와 인프라를 직접 호스팅하는 전체 가이드를 소개해요. 아키텍처, 배포 옵션, 퀵 스타트, 그리고 설정 선택 기준까지 알아볼게요.
출처: 문서
본문
AgentOps 셀프 호스팅
AgentOps 셀프 호스팅 문서에 오신 것을 환영합니다. 이 섹션은 여러분의 인프라에서 AgentOps 백엔드 서비스와 인프라를 실행하는 방법에 대한 포괄적인 가이드를 제공합니다.
셀프 호스팅이란? (What is Self-Hosting?)
AgentOps를 셀프 호스팅한다는 것은 전체 AgentOps 플랫폼을 여러분의 서버나 클라우드 인프라에서 실행하는 것을 의미하며, 다음에 대한 완전한 제어권을 제공합니다.
- Data sovereignty - 데이터가 여러분의 인프라에 유지됨
- Customization - 필요에 맞게 플랫폼 수정
- Security - 자체 보안 정책 구현
- Compliance - 특정 규제 요구사항 충족
- Cost control - 인프라 비용을 직접 관리
아키텍처 개요 (Architecture Overview)
AgentOps 플랫폼은 몇 가지 핵심 컴포넌트로 구성됩니다.
핵심 서비스 (Core Services)
- API Server - 인증, 데이터 처리, 비즈니스 로직을 처리하는 FastAPI 백엔드
- Dashboard - 사용자 인터페이스와 시각화를 제공하는 Next.js 프론트엔드
- Database Layer - 기본 데이터용 Supabase (PostgreSQL)와 분석용 ClickHouse
지원 인프라 (Supporting Infrastructure)
- OpenTelemetry Collector - 트레이스와 메트릭 수집
- Authentication - 사용자 관리를 위한 Supabase Auth
- File Storage - 파일 처리를 위한 Supabase Storage
- Monitoring - 선택적 Sentry, PostHog 통합
외부 의존성 (External Dependencies)
- Supabase - 데이터베이스 및 인증 서비스
- ClickHouse - 트레이스와 메트릭용 분석 데이터베이스
- Stripe (선택) - 빌링 기능을 위한 결제 처리
배포 옵션 (Deployment Options)
1. 개발 설정 (Development Setup)
로컬 개발과 테스트에 적합해요.
- Native Development - 머신에서 서비스를 직접 실행
- Docker Development - 격리된 환경을 위해 Docker Compose 사용
- Hybrid Approach - 네이티브와 컨테이너화 서비스 혼합
2. 프로덕션 배포 (Production Deployment)
프로덕션 워크로드용입니다.
- Docker Compose - 간단한 단일 서버 배포
- Kubernetes - 확장 가능한 컨테이너 오케스트레이션
- Cloud Platforms - AWS, GCP, Azure에 배포
- Serverless - 클라우드 함수와 관리형 서비스 사용
퀵 스타트 가이드 (Quick Start Guide)
사전 요구사항 (Prerequisites)
시작하기 전에 다음이 준비되어 있는지 확인하세요.
- 최신 운영체제 (Linux, macOS, 또는 WSL이 포함된 Windows)
- Docker와 Docker Compose
- Node.js 18+와 Python 3.12+
- 외부 서비스 접근 권한 (Supabase, ClickHouse)
5분 설정 (5-Minute Setup)
# 1. Clone the repository
git clone https://github.com/AgentOps-AI/AgentOps.Next.git
cd AgentOps.Next/app
# 2. Copy environment files
cp .env.example .env
cp api/.env.example api/.env
cp dashboard/.env.example dashboard/.env.local
# 3. Configure external services (see guides below)
# Edit .env files with your service credentials
# 4. Start with Docker
docker-compose up -d
# Or start natively for development
just api-native # Terminal 1
just fe-run # Terminal 2
http://localhost:3000을 방문해 대시보드에 접속하세요!
문서 섹션 (Documentation Sections)
백엔드 설정 가이드
AgentOps 백엔드 서비스 설정을 위한 완전한 가이드로, 다음을 포함합니다.
- 사전 요구사항과 시스템 요구사항
- 환경 설정
- 외부 서비스 설정
- 서비스 검증과 문제 해결
Docker 가이드
포괄적인 Docker와 Docker Compose 문서입니다.
- Docker 설정과 구성
- 컨테이너 관리 명령어
- 프로덕션 Docker 설정
- 성능 최적화와 모니터링
네이티브 개발 가이드
Docker 없이 서비스를 네이티브로 실행하는 가이드입니다.
- 가장 빠른 개발 설정
- IDE 설정과 디버깅
- 성능 최적화
- 고급 개발 워크플로우
Just 커맨드 레퍼런스
사용 가능한 모든 Just 명령어의 완전한 레퍼런스입니다.
- 설정과 설치 명령어
- 개발 워크플로우 명령어
- 테스트와 품질 보증
- Docker 관리 유틸리티
설정 선택하기 (Choosing Your Setup)
활발한 개발용 (For Active Development)
권장: 네이티브 개발 (Native Development)
- 가장 빠른 반복 주기
- 직접적인 디버깅 능력
- 더 낮은 리소스 사용량
- 즉시 파일 시스템 접근
just api-native # Start API natively
just fe-run # Start dashboard
팀 개발용 (For Team Development)
권장: Docker 개발 (Docker Development)
- 팀 전체에 일관된 환경
- 격리된 서비스 의존성
- 쉬운 환경 리셋
- 프로덕션 유사 테스트
just up # Start all services
just logs # Monitor services
프로덕션용 (For Production)
권장: 외부 서비스를 사용한 Docker (Docker with External Services)
- 확장 가능하고 유지보수 가능
- 헬스 체크와 재시작 정책
- 리소스 제한과 모니터링
- 쉬운 백업과 복구
외부 서비스 설정 (External Services Setup)
필수 서비스 (Required Services)
Supabase (Database & Auth)
- 목적: 기본 PostgreSQL 데이터베이스와 사용자 인증
- 설정: supabase.com에서 프로젝트 생성
- 비용: 무료 티어 제공, 사용량에 따라 확장
- 대안: 자체 호스팅 PostgreSQL + 커스텀 인증
ClickHouse (Analytics)
- 목적: 트레이스와 메트릭용 고성능 분석 데이터베이스
- 설정: ClickHouse Cloud 또는 자체 호스팅
- 비용: 사용량 기준 또는 고정 인스턴스
- 대안: PostgreSQL (성능 트레이드오프 포함)
선택 서비스 (Optional Services)
Stripe (Billing)
- 목적: 결제 처리와 구독 관리
- 설정: stripe.com에서 계정 생성
- 다음에 필요: 빌링 기능
- 대안: 빌링 기능 제거 또는 커스텀 결제 솔루션
모니터링 & 분석 (Monitoring & Analytics)
- Sentry: 오류 추적과 성능 모니터링
- PostHog: 제품 분석과 기능 플래그
- 설정: 선택 사항이지만 프로덕션에 권장
보안 고려사항 (Security Considerations)
인증과 권한 부여 (Authentication & Authorization)
- API 인증을 위한 JWT 토큰
- 사용자 관리를 위한 Supabase Auth
- PostgreSQL의 행 단위 보안 (Row-level security)
- SDK 접근을 위한 API 키 관리
데이터 보호 (Data Protection)
- 전송 중 HTTPS/TLS 암호화
- 저장 시 데이터베이스 암호화
- 환경 변수 보안
- 비밀 관리 모범 사례
네트워크 보안 (Network Security)
- 방화벽 설정
- VPN 또는 프라이빗 네트워크
- API 속도 제한
- CORS 설정
모니터링과 관측성 (Monitoring & Observability)
애플리케이션 모니터링 (Application Monitoring)
- 헬스 체크 엔드포인트
- 애플리케이션 메트릭과 로그
- Sentry를 사용한 오류 추적
- 성능 모니터링
인프라 모니터링 (Infrastructure Monitoring)
- 컨테이너 리소스 사용량
- 데이터베이스 성능
- 네트워크 연결성
- 스토리지 활용
알림 (Alerting)
- 서비스 가용성 알림
- 오류율 모니터링
- 리소스 사용 임계값
- 커스텀 비즈니스 메트릭
확장 고려사항 (Scaling Considerations)
수평 확장 (Horizontal Scaling)
- 여러 API 서버 인스턴스
- 로드 밸런서 설정
- 데이터베이스 연결 풀링
- 공유 세션 스토리지
수직 확장 (Vertical Scaling)
- 리소스 할당 최적화
- 데이터베이스 성능 튜닝
- 캐싱 전략
- 정적 자산용 CDN
데이터베이스 확장 (Database Scaling)
- PostgreSQL 읽기 복제본
- ClickHouse 클러스터 설정
- 연결 풀 관리
- 쿼리 최적화
백업과 복구 (Backup & Recovery)
데이터베이스 백업 (Database Backups)
- 자동 Supabase 백업
- ClickHouse 데이터 내보내기
- 특정 시점 복구 (Point-in-time recovery)
- 크로스 리전 복제
애플리케이션 백업 (Application Backups)
- 설정 파일
- 환경 변수
- 커스텀 수정 사항
- SSL 인증서
재해 복구 (Disaster Recovery)
- 복구 시간 목표 (RTO)
- 복구 시점 목표 (RPO)
- 페일오버 절차
- 데이터 무결성 검증
비용 최적화 (Cost Optimization)
인프라 비용 (Infrastructure Costs)
- 컴퓨트 리소스 적정 크기
- 적절한 곳에 spot 인스턴스 사용
- 오토 스케일링 구현
- 사용량 모니터링과 최적화
서비스 비용 (Service Costs)
- 데이터베이스 쿼리 최적화
- 캐싱 전략 구현
- 적절한 서비스 티어 사용
- 타사 서비스 사용량 모니터링
도움 받기 (Getting Help)
문서 (Documentation)
- 단계별 가이드 따라하기
- 문제 해결 섹션 확인
- 설정 예제 검토
- 아키텍처 결정 이해
커뮤니티 지원 (Community Support)
- 버그 보고용 GitHub Issues
- 질문용 GitHub Discussions
- 실시간 도움 위한 Discord 커뮤니티
- 기술 질문용 Stack Overflow
전문 지원 (Professional Support)
- 엔터프라이즈 지원 옵션
- 컨설팅 서비스 제공
- 커스텀 배포 지원
- 교육과 온보딩
다음 단계 (Next Steps)
- 백엔드 설정 가이드로 시작 - 환경을 실행하세요
- 배포 방법을 선택 - Docker 또는 네이티브 개발
- 외부 서비스를 설정 - Supabase와 ClickHouse 구성
- 필요에 맞게 커스터마이즈 - 설정과 기능 수정
- 프로덕션을 계획 - 모니터링, 백업, 확장 구현
시작할 준비가 되셨나요? 백엔드 설정 가이드로 시작하세요!