65 lines
3.8 KiB
Markdown
65 lines
3.8 KiB
Markdown
# **ADR-005**
|
|
|
|
- 제목: **LLM Gateway의 로깅 로직 개선: 클라이언트 IP 및 포트 추출 방식 보강**
|
|
- 날짜: **2025-07-29**
|
|
- 상태: 채택됨 (Proposed)
|
|
- 작성자: **\[김용연 연구원]**
|
|
|
|
---
|
|
|
|
## 1. 컨텍스트 (Context)
|
|
|
|
LLM Gateway에서 API 요청을 처리할 때, 로그에 기록되는 `ip`와 `swagger_port` 값이 프록시 환경에서 정확하지 않은 문제가 발생했다.
|
|
|
|
- 외부망 요청 시 `request.client.host` 값이 **회사 공인 IP(프록시/NAT IP)** 로만 기록됨.
|
|
- `Host` 헤더 기반 포트 추출이 실패해 `"unknown"`으로 로그에 기록되는 사례 발생.
|
|
|
|
---
|
|
|
|
## 2. 배경 (Background)
|
|
|
|
- 로드밸런서나 리버스 프록시(Nginx, ALB 등)를 거치는 구조에서, 원래 클라이언트 정보를 담은 헤더(`X-Forwarded-For`, `X-Real-IP`, `X-Forwarded-Port`)가 전달되지 않거나 무시되는 문제가 있었다.
|
|
- 그 결과, 모니터링과 디버깅 과정에서 **실제 사용자의 접속 정보(IP/포트)** 를 추적하기 어려웠다.
|
|
|
|
---
|
|
|
|
## 3. 결정 (Decision)
|
|
|
|
- **클라이언트 IP**: `X-Forwarded-For` → `X-Real-IP` → `request.client.host` 순으로 확인해 기록.
|
|
- **포트 정보**: `X-Forwarded-Port` → `request.url.port` → `Host` 헤더 → 기본 포트(443/80) 순으로 확인해 기록.
|
|
|
|
---
|
|
|
|
## 4. 대안 (Alternatives)
|
|
|
|
<<<<<<< Updated upstream
|
|
|
|
|
|
| 대안 | 장점 | 단점 |
|
|
| -------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------- |
|
|
| **기존 방식 유지**<br>`request.client.host`와 `Host`만 사용 | 코드 단순, 별도 설정 불필요 | 프록시 환경에서 실제 사용자 IP·포트 추적 불가,`"unknown"` 로그 발생 가능 |
|
|
| **프록시 헤더 활용 (채택)**<br>`X-Forwarded-For`, `X-Real-IP`, `X-Forwarded-Port` 사용 | 외부망·내부망 모두에서 정확한 IP/포트 기록 가능 | 프록시 설정 누락 시 fallback 값(`request.client.host`, `443/80`)으로만 기록됨 |
|
|
|
|
=======
|
|
|
|
|
|
| 대안 | 장점 | 단점 |
|
|
| -------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------- |
|
|
| **기존 방식 유지**<br>`request.client.host`와 `Host`만 사용 | 코드 단순, 별도 설정 불필요 | 프록시 환경에서 실제 사용자 IP·포트 추적 불가,`"unknown"` 로그 발생 가능 |
|
|
| **프록시 헤더 활용 (채택)**<br>`X-Forwarded-For`, `X-Real-IP`, `X-Forwarded-Port` 사용 | 외부망·내부망 모두에서 정확한 IP/포트 기록 가능 | 프록시 설정 누락 시 fallback 값(`request.client.host`, `443/80`)으로만 기록됨 |
|
|
|
|
>>>>>>> Stashed changes
|
|
>>>>>>>
|
|
>>>>>>
|
|
>>>>>
|
|
>>>>
|
|
>>>
|
|
>>
|
|
|
|
---
|
|
|
|
## 5. 결과 (Consequences)
|
|
|
|
- LLM Gateway의 로그에 실제 사용자 접속 정보(IP, 포트)가 일관되게 기록되어 **모니터링과 디버깅 품질 개선**.
|
|
- 프록시 설정(`X-Forwarded-For`, `X-Real-IP`, `X-Forwarded-Port`)이 누락되면 여전히 기본값(`request.client.host`, `443/80`)으로만 기록될 수 있으므로, 인프라 설정 가이드와 함께 배포 필요
|