Initial commit: 프로젝트 초기 구성

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-09 08:21:50 +09:00
commit 0ee5d066b4
20 changed files with 2981 additions and 0 deletions
--- a/.claude/skills/infrastructure-setup.md
+++ b/.claude/skills/infrastructure-setup.md
@ -0,0 +1,268 @@
+# 인프라 구축 가이드 (Infrastructure Setup)
+
+인프라 설정 패턴입니다.
+
+## MAAS (Metal as a Service)
+
+### 개요
+- 베어메탈 서버 프로비저닝 도구
+- Ubuntu 기반 자동 배포
+- 네트워크 자동 설정
+
+### 기본 설정
+```yaml
+# MAAS 설정 예시
+machines:
+  - hostname: k8s-master-01
+    architecture: amd64
+    cpu_count: 8
+    memory: 32768
+    storage: 500GB
+    tags:
+      - kubernetes
+      - master
+
+  - hostname: k8s-worker-01
+    architecture: amd64
+    cpu_count: 16
+    memory: 65536
+    storage: 1TB
+    tags:
+      - kubernetes
+      - worker
+```
+
+### 네트워크 설정
+```yaml
+# 서브넷 설정
+subnets:
+  - cidr: 10.10.0.0/16
+    gateway_ip: 10.10.0.1
+    dns_servers:
+      - 8.8.8.8
+      - 8.8.4.4
+```
+
+## Kubernetes 클러스터
+
+### 클러스터 구성
+```yaml
+# 마스터 노드: 3대 (HA 구성)
+# 워커 노드: 3대 이상
+# etcd: 마스터 노드에 내장
+```
+
+### kubeadm 초기화
+```bash
+# 마스터 노드 초기화
+kubeadm init --pod-network-cidr=10.244.0.0/16 \
+             --control-plane-endpoint="k8s-api.example.com:6443" \
+             --upload-certs
+
+# 워커 노드 조인
+kubeadm join k8s-api.example.com:6443 \
+    --token <token> \
+    --discovery-token-ca-cert-hash sha256:<hash>
+```
+
+### CNI 설치 (Flannel)
+```bash
+kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
+```
+
+## Rancher 설치
+
+### Docker 기반 설치
+```bash
+docker run -d --restart=unless-stopped \
+  -p 80:80 -p 443:443 \
+  --privileged \
+  -v /opt/rancher:/var/lib/rancher \
+  rancher/rancher:latest
+```
+
+### Helm 기반 설치
+```bash
+# Rancher Helm 레포 추가
+helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
+helm repo update
+
+# 네임스페이스 생성
+kubectl create namespace cattle-system
+
+# cert-manager 설치 (Let's Encrypt 사용 시)
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
+
+# Rancher 설치
+helm install rancher rancher-latest/rancher \
+  --namespace cattle-system \
+  --set hostname=rancher.example.com \
+  --set replicas=3 \
+  --set ingress.tls.source=letsEncrypt \
+  --set letsEncrypt.email=admin@example.com
+```
+
+## Docker Compose 배포
+
+### docker-compose.yml 구조
+```yaml
+services:
+  # ===================
+  # Infrastructure
+  # ===================
+  mongodb:
+    image: mongo:7.0
+    container_name: {프로젝트}-mongodb
+    restart: unless-stopped
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: ${MONGO_USER:-admin}
+      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD:-password123}
+    ports:
+      - "{호스트포트}:27017"
+    volumes:
+      - {프로젝트}_mongodb_data:/data/db
+    networks:
+      - {프로젝트}-network
+    healthcheck:
+      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  redis:
+    image: redis:7-alpine
+    container_name: {프로젝트}-redis
+    restart: unless-stopped
+    ports:
+      - "{호스트포트}:6379"
+    volumes:
+      - {프로젝트}_redis_data:/data
+    networks:
+      - {프로젝트}-network
+
+volumes:
+  {프로젝트}_mongodb_data:
+  {프로젝트}_redis_data:
+
+networks:
+  {프로젝트}-network:
+    driver: bridge
+```
+
+### 배포 명령어
+```bash
+# 전체 서비스 시작
+docker-compose up -d
+
+# 특정 서비스만 재빌드
+docker-compose up -d --build {서비스명}
+
+# 로그 확인
+docker-compose logs -f {서비스명}
+
+# 서비스 상태 확인
+docker-compose ps
+```
+
+## 환경 변수 관리
+
+### .env 파일
+```bash
+# Infrastructure
+MONGO_USER=admin
+MONGO_PASSWORD={비밀번호}
+REDIS_URL=redis://redis:6379
+
+# API Keys
+CLAUDE_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+JWT_SECRET_KEY={시크릿키}
+
+# Database
+DB_NAME={데이터베이스명}
+TARGET_COLLECTION={컬렉션명}
+```
+
+### 환경별 설정
+```bash
+# 개발 환경
+docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
+
+# 프로덕션 환경
+docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+## 백업 전략
+
+### MongoDB 백업
+```bash
+# 백업
+BACKUP_NAME="mongodb_backup_$(date +%Y%m%d_%H%M%S)"
+docker exec {프로젝트}-mongodb mongodump \
+    --uri="mongodb://{user}:{password}@localhost:27017" \
+    --authenticationDatabase=admin \
+    --out="/tmp/$BACKUP_NAME"
+docker cp {프로젝트}-mongodb:/tmp/$BACKUP_NAME ./backups/
+
+# 복원
+docker cp ./backups/$BACKUP_NAME {프로젝트}-mongodb:/tmp/
+docker exec {프로젝트}-mongodb mongorestore \
+    --uri="mongodb://{user}:{password}@localhost:27017" \
+    --authenticationDatabase=admin \
+    "/tmp/$BACKUP_NAME"
+```
+
+### 볼륨 백업
+```bash
+# 볼륨 백업
+docker run --rm \
+    -v {프로젝트}_mongodb_data:/data \
+    -v $(pwd)/backups:/backup \
+    alpine tar czf /backup/mongodb_volume.tar.gz -C /data .
+```
+
+## 네트워크 구성
+
+### 포트 매핑 규칙
+```yaml
+# Infrastructure (기본 포트 + 오프셋)
+MongoDB: {오프셋}+27017:27017
+Redis: {오프셋}+6379:6379
+
+# Application Services
+api-service: 8000:8000
+admin-frontend: 3000:3000
+```
+
+### 내부 통신
+```yaml
+# 컨테이너 간 통신은 서비스명 사용
+mongodb: mongodb://{user}:{password}@mongodb:27017/
+redis: redis://redis:6379
+```
+
+## 모니터링 접근점
+
+### 헬스체크 엔드포인트
+```bash
+# MongoDB
+docker exec {프로젝트}-mongodb mongosh --eval "db.adminCommand('ping')"
+
+# Redis
+docker exec {프로젝트}-redis redis-cli ping
+
+# FastAPI 서비스
+curl http://localhost:{포트}/health
+```
+
+### 로그 수집
+```bash
+# 전체 로그
+docker-compose logs -f
+
+# 특정 서비스 로그
+docker-compose logs -f {서비스명}
+
+# 최근 100줄만
+docker-compose logs --tail=100 {서비스명}
+```