diff --git a/docs/architecture/emergency-manual.md b/docs/architecture/emergency-manual.md new file mode 100644 index 0000000..404d620 --- /dev/null +++ b/docs/architecture/emergency-manual.md @@ -0,0 +1,168 @@ +# 비상 대응 매뉴얼 + +## 🚨 긴급 상황별 대응 + +### 1. 서비스 다운 + +#### rb 서비스가 응답하지 않을 때 +```bash +# 1. 51124 서버 상태 확인 +ssh -p 51124 admin@192.168.219.52 + +# 2. 컨테이너 상태 확인 +docker ps | grep rb + +# 3. 컨테이너 재시작 +docker restart [container_name] + +# 4. 로그 확인 +docker logs [container_name] --tail 100 +``` + +#### nginx 502 Bad Gateway +```bash +# 1. nginx 상태 확인 +sudo systemctl status nginx + +# 2. 에러 로그 확인 +sudo tail -f /var/log/nginx/error.log + +# 3. nginx 재시작 +sudo systemctl restart nginx +``` + +### 2. 배포 실패 + +#### Gitea Actions 실패 +1. Gitea 웹 UI에서 Actions 로그 확인 +2. SSH 키 문제인 경우: + ```bash + # 키 fingerprint 확인 + ssh-keygen -l -f ~/.ssh/id_rsa_51123_to_51124 + ``` +3. 수동 배포: + ```bash + ssh -p 51124 admin@192.168.219.52 + cd /home/admin/ivada_project/[project] + git pull + docker compose down + docker compose up -d --build + ``` + +### 3. 디스크 용량 부족 + +```bash +# 1. 디스크 사용량 확인 +df -h + +# 2. Docker 정리 (주의: 실행 중인 컨테이너 확인 필수) +docker system prune -af + +# 3. 로그 정리 +sudo rm -rf /var/log/nginx/*.gz +find /mnt/hdd/logs -name "*.log" -mtime +30 -delete +``` + +### 4. 메모리 부족 + +```bash +# 1. 메모리 사용량 확인 +free -h +htop + +# 2. 메모리 많이 쓰는 프로세스 찾기 +ps aux --sort=-%mem | head -10 + +# 3. 불필요한 컨테이너 중지 +docker ps +docker stop [불필요한_컨테이너] +``` + +### 5. SSL 인증서 문제 + +```bash +# 1. 인증서 만료일 확인 +sudo certbot certificates + +# 2. 수동 갱신 +sudo certbot renew --force-renewal + +# 3. nginx 재시작 +sudo systemctl restart nginx +``` + +## 📞 연락처 및 우선순위 + +### 장애 레벨별 대응 + +#### Level 1 (Critical) - 즉시 대응 +- 전체 서비스 다운 +- 데이터 유실 위험 +- 보안 침해 +→ 서버팀 + 개발팀 모두 알림 + +#### Level 2 (Major) - 1시간 내 대응 +- 일부 서비스 장애 +- 성능 심각한 저하 +→ 담당 서버팀 알림 + +#### Level 3 (Minor) - 업무시간 내 대응 +- 단순 에러 +- 일시적 장애 +→ 로그 기록 후 정기 점검 시 처리 + +## 🔧 유용한 명령어 모음 + +### 모니터링 +```bash +# 시스템 전체 상태 +htop + +# 네트워크 연결 상태 +ss -tlnp + +# Docker 리소스 사용량 +docker stats + +# 디스크 I/O +iotop +``` + +### 로그 확인 +```bash +# 실시간 로그 모니터링 +tail -f /var/log/nginx/access.log +docker logs -f [container_name] + +# 에러 검색 +grep -i error /var/log/nginx/error.log +docker logs [container_name] 2>&1 | grep -i error +``` + +### 백업 & 복구 +```bash +# PostgreSQL 백업 +docker exec [postgres_container] pg_dump -U [user] [database] > backup.sql + +# 복구 +docker exec -i [postgres_container] psql -U [user] [database] < backup.sql +``` + +## ⚡ 빠른 체크리스트 + +문제 발생 시: +- [ ] 서비스 상태 확인 (`docker ps`) +- [ ] 로그 확인 (`docker logs`) +- [ ] 디스크 공간 확인 (`df -h`) +- [ ] 메모리 상태 확인 (`free -h`) +- [ ] nginx 상태 확인 (`systemctl status nginx`) +- [ ] 네트워크 연결 확인 (`ping`, `curl`) +- [ ] 최근 변경사항 확인 (Gitea 커밋 로그) + +## 📝 사후 조치 + +장애 해결 후: +1. 트러블슈팅 문서 작성 (`/home/admin/temp_docs/troubleshooting/`) +2. 모니터링 강화 필요 여부 검토 +3. 자동화 가능한 부분 스크립트 작성 +4. 팀 공유 및 개선사항 논의 \ No newline at end of file diff --git a/docs/architecture/server-architecture.md b/docs/architecture/server-architecture.md new file mode 100644 index 0000000..cbb11b7 --- /dev/null +++ b/docs/architecture/server-architecture.md @@ -0,0 +1,96 @@ +# 로빙 서버 인프라 구성도 + +## 서버 구성 + +### 51123 서버 (192.168.219.45) +**역할**: 프록시, CI/CD, 인증 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 51123 서버 │ +│ │ +│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │ +│ │ nginx │ │ Gitea │ │ skill-email │ │ +│ │ (80/443) │ │ (3000) │ │ (8501) │ │ +│ └─────┬───────┘ └──────┬───────┘ └───────────────┘ │ +│ │ │ │ +│ │ ┌───────┴──────┐ │ +│ │ │ Actions │ │ +│ │ │ Runner │ │ +│ │ └──────────────┘ │ +└────────┼────────────────────────────────────────────────┘ + │ + │ 프록시 + ▼ +┌─────────────────────────────────────────────────────────┐ +│ 51124 서버 │ +│ (192.168.219.52) │ +│ │ +│ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │ +│ │ rb8001 │ │ rb10508 │ │ rb10408 │ │ +│ │ (8001) │ │ (10508) │ │ (10408) │ │ +│ └────────────┘ └────────────┘ └────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────┐ │ +│ │ PostgreSQL Database │ │ +│ │ (5432) │ │ +│ └────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────┘ +``` + +## 포트 매핑 + +### 51123 서버 +| 서비스 | 내부 포트 | 외부 접근 | 용도 | +|--------|-----------|-----------|------| +| nginx | 80/443 | ro-being.com | 리버스 프록시 | +| Gitea | 3000 | git.ro-being.com | Git 저장소 | +| frontend-base | 8000 | /admin/* | 관리자 대시보드 | +| skill-email | 8501 | /skill-email/* | 이메일 스킬 | + +### 51124 서버 +| 서비스 | 포트 | nginx 경로 | 용도 | +|--------|------|------------|------| +| rb8001 | 8001 | /rb8001/* | 메인 로빙 서비스 | +| rb10508 | 10508 | /rb10508/* | 로빙 테스트 | +| rb10408 | 10408 | /rb10408/* | 로빙 서비스 | + +## 배포 플로우 + +``` +개발자 PC + │ + ├─── git push ──→ Gitea (51123) + │ │ + │ ├─── webhook ──→ Actions Runner + │ │ │ + │ │ ├─── Build + │ │ ├─── Test + │ │ └─── Deploy + │ │ + │ ▼ + │ SSH (51124) + │ │ + └─── https://ro-being.com ←─── nginx ←────────── Services +``` + +## 네트워크 구성 + +- **내부 네트워크**: 172.17.0.0/16 (Docker bridge) +- **서버 간 통신**: SSH (포트 51124) +- **외부 도메인**: ro-being.com (HTTPS) + +## 보안 설정 + +1. **방화벽** + - 외부: 80, 443만 개방 + - 내부: 필요한 포트만 개방 + +2. **인증** + - Gitea: 개인 토큰 + - Admin API: JWT 토큰 + - SSH: 키 기반 인증 + +3. **SSL/TLS** + - Let's Encrypt 인증서 + - 자동 갱신 설정 \ No newline at end of file diff --git a/docs/guide/log-api-guide.md b/docs/guide/log-api-guide.md new file mode 100644 index 0000000..70fd3ed --- /dev/null +++ b/docs/guide/log-api-guide.md @@ -0,0 +1,116 @@ +# 로그 API 사용 가이드 + +## 개요 +이 문서는 로컬 개발자와 51124 서버에서 로빙 서비스들의 로그를 조회하는 방법을 안내합니다. + +## API 엔드포인트 +- **URL**: `https://ro-being.com/admin/logs/{service}` +- **메소드**: GET +- **인증**: Bearer Token (JWT) + +## 사용 단계 + +### 1. 로그인하여 토큰 발급 +```bash +# 로그인 요청 +curl -X POST https://ro-being.com/admin/login \ + -H "Content-Type: application/json" \ + -d '{"password": "19800508"}' + +# 응답 예시 +{ + "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "token_type": "bearer" +} +``` + +### 2. 로그 조회 +```bash +# 토큰을 환경변수에 저장 +export TOKEN="발급받은_토큰" + +# 로그 조회 (최근 50줄) +curl -H "Authorization: Bearer $TOKEN" \ + https://ro-being.com/admin/logs/rb10508_test + +# 특정 라인 수 지정 (예: 100줄) +curl -H "Authorization: Bearer $TOKEN" \ + https://ro-being.com/admin/logs/rb10508_test?lines=100 +``` + +## 사용 가능한 서비스명 +- `rb10508_test` - 로빙 테스트 서비스 (51124 서버) +- `rb8001` - 로빙 메인 서비스 (51124 서버) +- `rb10408` - 로빙 서비스 (51124 서버) +- `skill-email` - 이메일 스킬 서비스 (51123 서버) +- `frontend-base` - 관리자 대시보드 + +## 응답 형식 +```json +{ + "logs": [ + "2025-07-28T02:10:12.932703068Z INFO: Log message 1", + "2025-07-28T02:10:13.033248022Z INFO: Log message 2" + ], + "service": "rb10508_test", + "container_name": "rb10508_test", + "total_lines": 50 +} +``` + +## 실제 사용 예시 + +### 로컬 개발자용 (bash) +```bash +#!/bin/bash +# log-viewer.sh + +# 1. 로그인 +RESPONSE=$(curl -s -X POST https://ro-being.com/admin/login \ + -H "Content-Type: application/json" \ + -d '{"password": "19800508"}') + +TOKEN=$(echo $RESPONSE | python3 -c "import sys, json; print(json.load(sys.stdin)['access_token'])") + +# 2. 로그 조회 +SERVICE=${1:-rb10508_test} +LINES=${2:-50} + +curl -s -H "Authorization: Bearer $TOKEN" \ + "https://ro-being.com/admin/logs/$SERVICE?lines=$LINES" | \ + python3 -m json.tool +``` + +### Python 예시 +```python +import requests +import json + +# 로그인 +login_response = requests.post( + 'https://ro-being.com/admin/login', + json={'password': '19800508'} +) +token = login_response.json()['access_token'] + +# 로그 조회 +headers = {'Authorization': f'Bearer {token}'} +logs_response = requests.get( + 'https://ro-being.com/admin/logs/rb10508_test?lines=100', + headers=headers +) + +logs_data = logs_response.json() +for log in logs_data['logs']: + print(log) +``` + +## 주의사항 +1. 토큰은 24시간 후 만료됩니다 +2. 한 번에 최대 1000줄까지 조회 가능합니다 +3. 컨테이너가 중지된 경우 로그를 조회할 수 없습니다 + +## 문제 해결 +- **401 Unauthorized**: 토큰이 만료되었거나 잘못되었습니다. 다시 로그인하세요. +- **404 Not Found**: 서비스명이 잘못되었거나 컨테이너가 존재하지 않습니다. +- **500 Internal Server Error**: 서버 문제입니다. 서버팀에 문의하세요. \ No newline at end of file