🚨 1. 에러 메시지 및 문제 상황
1️⃣ Nginx 설정 문제 (nginx: configuration file test failed)
에러 메시지
nginx: configuration file /etc/nginx/nginx.conf test failed
문제 상황
- nginx -t 명령어 실행 시 설정 파일이 올바르게 로드되지 않음.
- nginx.conf 또는 sites-available/hjwjo.com 설정 파일의 문제일 가능성 높음.
- SSL 인증서 접근 권한 문제로 인해 fullchain.pem 또는 privkey.pem을 읽지 못함.
2️⃣ Redirect URI Mismatch (KOE303)
에러 메시지
{
"error": "invalid_grant",
"error_description": "Redirect URI mismatch.",
"error_code": "KOE303"
}
문제 상황
- 카카오 로그인 요청 시 OAuth2 Redirect URI가 올바르게 등록되지 않음.
- 카카오 개발자 콘솔에서 등록된 Redirect URI와 현재 요청 URL이 다름.
- 프론트엔드 혹은 백엔드의 redirect_uri 설정이 올바르지 않을 가능성 존재.
3️⃣ .git 디렉터리 노출 (GET /.git/config HTTP/1.1 200)
에러 메시지
18.234.216.213 - - [07/Feb/2025:11:41:21 +0000] "GET /.git/config HTTP/1.1" 200 1752
문제 상황
- .git/config 요청이 200 OK 응답을 반환함.
- 보안 취약점!
.git 디렉터리에 접근 가능하면 소스 코드가 유출될 위험이 있음. - 이를 방지하기 위해 Nginx에서 .git 디렉터리에 대한 접근을 차단해야 함.
🔧 2. 해결 방법
✅ 1️⃣ Nginx SSL 인증서 문제 해결 (configuration file test failed)
🔹 해결 방법
- SSL 인증서 파일의 권한을 조정
sudo chmod 644 /etc/letsencrypt/live/hjwjo.com/fullchain.pem
sudo chmod 644 /etc/letsencrypt/live/hjwjo.com/privkey.pem- 파일 소유권 변경 (필요할 경우)
sudo chown root:root /etc/letsencrypt/live/hjwjo.com/fullchain.pem
sudo chown root:root /etc/letsencrypt/live/hjwjo.comprivkey.pem- Nginx 설정 테스트 후 재시작
sudo nginx -t # 설정 테스트
sudo systemctl restart nginx # Nginx 재시작
✅ 2️⃣ Redirect URI Mismatch 해결 (KOE303)
🔹 해결 방법
- 카카오 개발자 콘솔에서 Redirect URI 확인
- 카카오 개발자 콘솔 접속
- 내 애플리케이션 → 앱 설정 → 플랫폼 → Redirect URI 확인
- 백엔드에서 사용하는 redirect_uri 값과 일치하는지 확인
- 예: https://hjwjo.com/auth/kakao/callback
- 백엔드의 redirect_uri 값 점검
- Spring Boot의 application.yml 또는 .env 파일에서 확인:
kakao.redirect_uri: https://hjwjo.com/auth/kakao/callback- 또는 .env 파일에서:
KAKAO_REDIRECT_URI=https://hjwjo.com/auth/kakao/callback - 프론트엔드에서 올바른 Redirect URI 설정
- React/Vue 등 프론트엔드의 .env 파일에서 redirect_uri 확인:
const KAKAO_REDIRECT_URI = "https://hjwjo.com/auth/kakao/callback";
✅ 3️⃣ .git 디렉터리 접근 차단
🔹 해결 방법
- Nginx 설정 파일 수정
sudo nano /etc/nginx/sites-available/hjwjo.com- .git 디렉터리 접근 차단 추가:
location ~ /\.git {
deny all;
}
- 설정 적용 및 재시작:
sudo nginx -t # 설정 테스트
sudo systemctl restart nginx # Nginx 재시작
🔥 최종 해결 사항
✅ Nginx SSL 인증서 권한 문제 해결
✅ 카카오 Redirect URI Mismatch (KOE303) 해결
✅ .git 디렉터리 접근 차단으로 보안 강화
⚡ 트러블슈팅 과정에서의 핵심 학습 포인트
- nginx -t를 통해 설정 오류를 빠르게 확인하는 방법
- OAuth2 Redirect URI 불일치 문제 해결하는 방법
- .git/config 노출을 막아 보안 강화를 수행하는 방법
🚀 이제 다시 nginx와 access.log를 모니터링하면서 정상 작동 여부를 확인하면 됨!
📝 추가 내용: 변수 관리
이번 문제의 원인은 .env 파일에서 Redirect URI를 로컬 IP로 설정해두었기 때문이었다.
즉, 환경 변수(.env)에서 정의된 값이 개발 환경(로컬)과 배포 환경(프로덕션)에서 다르게 설정되어 있어 생긴 문제였다.
✅ 변수 관리의 중요성
- .env 파일은 환경별 설정을 분리하는 핵심적인 도구이며, 로컬 개발 환경과 서버 환경에서 일관된 값이 유지되어야 한다.
- 동일한 값이 여러 곳에 하드코딩되면 변경이 발생할 때 실수할 가능성이 커지고, 유지보수가 어려워진다.
- 환경 변수를 정의할 때는 기본값(default value) 설정도 신중하게 고려해야 한다.
- 이번 사례에서는 .env 파일에서 KAKAO_REDIRECT_URI가 로컬 IP로 고정되어 있어, 서버 배포 시에도 로컬 환경의 값이 사용되면서 KOE303 에러가 발생했다.
✅ 소통과 협업의 중요성
- 백엔드와 프론트엔드, DevOps 등 각 팀원들이 서로의 환경 변수를 어떻게 설정하고 있는지 공유하고 명확하게 이해해야 한다.
- 코드 리뷰 및 문서화가 중요한 이유
- "이 변수가 어디서 어떻게 사용되는가?"에 대한 명확한 문서화가 필요하다.
- 팀원 간에 변경 사항을 공유하는 습관이 있으면 이런 문제를 미리 방지할 수 있다.
- .env.example과 같은 환경 변수 템플릿을 유지하면 협업이 수월해진다.
✅ 중복성과 가독성
- 여러 곳에서 같은 변수를 하드코딩하지 않고, 단일 환경 변수에서 관리하는 것이 핵심이다.
- 중복된 값이 많아질수록 가독성이 낮아지고, 유지보수가 어려워진다.
- 특히 OAuth 관련 URL은 프론트엔드, 백엔드, OAuth 제공 업체(카카오 개발자 콘솔)까지 일관성이 유지되어야 한다.
- 로컬에서는 http://localhost:3000/auth/kakao/callback
- 배포 서버에서는 https://hjwjo.com/auth/kakao/callback
- 하지만 .env에서 변경 없이 로컬 값을 사용하면 문제가 발생한다.
🚀 배운 점 및 개선 방안
- 환경 변수 관리 철저히 하기
- .env에서 환경별 값(development, production)을 구분하여 설정
- .env.example을 유지하여 팀원 간 공유
- .gitignore로 .env 파일이 Git에 올라가지 않도록 관리
- 팀 내 공유 및 문서화 강화
- 팀원 간 중요 설정값을 공유하는 채널 운영 (예: Notion, Confluence, Google Docs)
- 코드 리뷰 및 PR 작성 시 환경 변수 설정도 확인
- 가독성 높은 코드 유지
- 하드코딩을 지양하고, 하나의 환경 변수에서 값을 관리
- application.yml, .env, config.js 등에서 일관된 변수명 사용