happybell80 15d776d888 docs: 트러블슈팅 문서 정리 및 업데이트

- 모든 트러블슈팅 파일명을 yymmdd 형식으로 통일
- 오늘 작업 내용 추가 (서버 구조 변경, auth-server 설정)
- Git 작업 실수 관련 교훈 기록

2025-07-29 20:07:20 +09:00

5.5 KiB

Raw Blame History

중앙 인증 서버(auth.ro-being.com) 구축

날짜: 2025-07-16
관련 서비스: auth-server, nginx-deploy
작성자: Claude AI Assistant

작업 개요

로빙 프로젝트의 모든 외부 서비스(Gmail, Slack, Notion 등) OAuth 인증을 중앙에서 관리하기 위한 auth.ro-being.com 서버를 구축했습니다.

주요 작업 내용

1. 인증 서버 아키텍처 설계

문제 상황:

Gmail OAuth 리디렉션 URI 설정 필요
각 로빙 컨테이너가 개별적으로 인증을 관리하면 복잡도 증가
토큰 관리의 중앙화 필요

해결 방안:

auth.ro-being.com을 중앙 인증 허브로 구축
모든 OAuth 토큰을 중앙 DB에 저장
로빙 컨테이너는 API를 통해 토큰 조회

2. auth-server 저장소 생성

# 저장소 생성
git.ro-being.com/ivada_Ro-being/auth-server

# 기본 구조
auth-server/
├── app/
│   ├── main.py              # FastAPI 메인
│   ├── providers/           # OAuth 제공자별 모듈
│   │   └── gmail.py        # Gmail OAuth (구현 예정)
│   └── api/                 # API 엔드포인트
│       └── tokens.py       # 토큰 관리 API
├── docker-compose.yml      # 포트 9000 설정
├── Dockerfile
└── requirements.txt

3. Nginx 리버스 프록시 설정

nginx-deploy/default.conf 수정:

# Auth server configuration
server {
    listen 80;
    server_name auth.ro-being.com;
    
    location / {
        proxy_pass http://192.168.219.45:9000/;  # 끝에 / 중요!
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # OAuth 콜백 타임아웃 늘리기
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }
}

주의사항:

proxy_pass 끝에 / 필수 - 없으면 하위 경로 전달 안됨
기존 서버 블록에 server_name 패턴 추가하여 auth 제외

4. Docker 구성

docker-compose.yml:

services:
  auth-server:
    build: .
    container_name: auth-server
    ports:
      - "9000:9000"
    environment:
      - PORT=9000
      - DATABASE_URL=${DATABASE_URL}
      - JWT_SECRET_KEY=${JWT_SECRET_KEY}
      - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}
      - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}
    networks:
      - appnet

전체 인증 플로우

1. 사용자 요청: "Gmail 읽어줘"
   ↓
2. 로빙 컨테이너: 토큰 확인
   ↓
3. 토큰 없음 → auth.ro-being.com/auth/gmail/login 링크 전송
   ↓
4. 사용자: 링크 클릭 → Google 로그인
   ↓
5. Google → auth.ro-being.com/auth/gmail/callback
   ↓
6. auth-server: 토큰 저장 (PostgreSQL)
   ↓
7. 로빙: API로 토큰 조회하여 Gmail 접근

다음 단계

서버 작업:
- auth-server 클론 및 빌드
- .env 파일 설정
- docker-compose up -d 실행
- nginx reload
개발 작업:
- Gmail OAuth provider 구현
- PostgreSQL 토큰 저장 모델
- JWT 기반 API 인증
- rb10508_test에 Gmail 스킬 통합

SSL/HTTPS 설정 추가

문제 상황

HTTP는 정상 작동하지만 HTTPS 접속 불가
SSL 인증서는 이미 발급되어 있음 (auth.ro-being.com)
nginx 설정에 HTTPS 서버 블록 누락

해결 과정

nginx-deploy 저장소 구조 파악:
- default.conf: Docker nginx 설정 (legacy)
- server-nginx-default: 실제 서버 nginx 설정 파일
- GitHub Actions가 server-nginx-default를 서버의 /etc/nginx/sites-available/default로 복사
HTTPS 서버 블록 추가:

# Auth server configuration
server {
    listen 80;
    server_name auth.ro-being.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name auth.ro-being.com;

    ssl_certificate /etc/letsencrypt/live/auth.ro-being.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/auth.ro-being.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    location / {
        proxy_pass http://localhost:9000/;  # 끝에 / 필수!
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # OAuth 콜백 타임아웃 늘리기
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }
}

최종 결과

✅ HTTPS 접속: 정상 작동
✅ HTTP → HTTPS 리다이렉션: 설정됨
✅ SSL 인증서: 유효 (2025-10-14까지)
✅ Health check: 정상 응답
✅ OAuth 타임아웃: 300초로 설정

교훈

Nginx proxy_pass 설정: 끝에 / 유무가 경로 전달에 중요한 영향
중앙 인증의 장점: 토큰 관리 일원화, 보안 강화, 확장성
마이크로서비스 구조: 각 서비스(인증, API, 로빙)를 독립적으로 관리
SSL 설정 패턴: HTTP는 HTTPS로 리다이렉션, HTTPS 블록에 실제 프록시 설정
nginx-deploy 워크플로우: 로컬 수정 → Git push → GitHub Actions → 서버 배포

5.5 KiB Raw Blame History