docs: 서버 인프라 문서 및 API 가이드 추가
- log-api-guide.md: 로그 조회 API 사용 가이드 - server-architecture.md: 51123/51124 서버 인프라 구성도 - emergency-manual.md: 비상 대응 매뉴얼 및 트러블슈팅 가이드 로컬 개발자와 51124 서버 담당자가 참고할 수 있도록 문서화
This commit is contained in:
parent
ae9598f8ab
commit
ef54297247
168
docs/architecture/emergency-manual.md
Normal file
168
docs/architecture/emergency-manual.md
Normal file
@ -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. 팀 공유 및 개선사항 논의
|
||||
96
docs/architecture/server-architecture.md
Normal file
96
docs/architecture/server-architecture.md
Normal file
@ -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 인증서
|
||||
- 자동 갱신 설정
|
||||
116
docs/guide/log-api-guide.md
Normal file
116
docs/guide/log-api-guide.md
Normal file
@ -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**: 서버 문제입니다. 서버팀에 문의하세요.
|
||||
Loading…
x
Reference in New Issue
Block a user