pharmacy-pos-qr-system/docs/WEBSOCKET_PROXY_TROUBLESHOOTING.md

WebSocket 프록시 트러블슈팅 가이드

개요

PAAI 처방감지 시스템에서 WebSocket(wss://)을 Nginx Proxy Manager(NPM)를 통해 프록시하는 과정에서 발생한 문제들과 해결 방법을 정리한 문서입니다.

환경:

• Nginx Proxy Manager (NPM): Docker 컨테이너, CT 150 (192.168.0.105)
• WebSocket 서버: trigger_server.py (192.168.0.14:8765)
• 프론트엔드: https://mile.0bin.in/pmr/
• Proxmox VE: 192.168.0.119

---

문제 1: WebSocket 404 오류

증상

WebSocket connection to 'wss://mile.0bin.in/ws' failed

nginx 액세스 로그에 /ws 요청이 404로 응답됨.

원인

NPM에서 /ws 경로에 대한 프록시 설정이 없었음.

해결 방법

NPM 웹 UI에서 Advanced 설정 추가:

1. NPM 관리자 접속
2. Proxy Hosts → mile.0bin.in → Edit
3. Advanced 탭 클릭
4. 아래 내용 입력:

location /ws {
    proxy_pass http://192.168.0.14:8765;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 86400;
}

5. Save 클릭

⚠️ 주의사항

절대 conf 파일 직접 수정하지 말 것!

NPM은 설정을 SQLite DB에 저장하고, 컨테이너 재시작 시 DB에서 conf 파일을 재생성합니다. /data/nginx/proxy_host/167.conf 같은 파일을 직접 수정해도 재시작 시 덮어씌워집니다.

반드시 NPM 웹 UI의 Advanced 탭을 사용하세요.

---

문제 2: duplicate location 오류

증상

nginx: [emerg] duplicate location "/ws" in /data/nginx/custom/server_proxy.conf:1
nginx: configuration file /etc/nginx/nginx.conf test failed

모든 프록시가 작동하지 않음!

원인

/data/nginx/custom/server_proxy.conf에 /ws location을 추가했는데, NPM Advanced 설정에서도 /ws를 추가하여 중복 발생.

해결 방법

중복 파일 삭제:

# Proxmox에서 실행
pct exec 150 -- docker exec npm rm /data/nginx/custom/server_proxy.conf
pct exec 150 -- docker exec npm nginx -t
pct exec 150 -- docker exec npm nginx -s reload

예방책

• /data/nginx/custom/ 폴더는 건드리지 않기
• 모든 커스텀 설정은 NPM 웹 UI Advanced 탭에서만 추가

---

문제 3: HTTP/2와 WebSocket 충돌

증상

curl: (92) HTTP/2 stream 1 was not closed cleanly: PROTOCOL_ERROR (err 1)

nginx 프록시를 통한 WebSocket 핸드셰이크 실패.

원인

• NPM이 HTTPS에서 HTTP/2를 사용
• 기존 HTTP/2는 WebSocket을 지원하지 않음 (RFC 8441 이후 지원)
• nginx 1.25.1+ 필요

해결 방법

방법 1: 내부 HTTP 접속 (권장, 간단)

http://192.168.0.14:7001/pmr/

HTTP → ws:// 직접 연결로 HTTP/2 문제 회피

방법 2: 프론트엔드에서 분기 처리

const TRIGGER_WS_URL = location.protocol === 'https:'
    ? `wss://${location.host}/ws`  // 외부: NPM 프록시
    : `ws://${location.hostname}:8765`;  // 내부: 직접 연결

방법 3: 별도 WebSocket 전용 서브도메인

• ws.mile.0bin.in 생성
• HTTP/2 비활성화 설정

---

문제 4: nginx 설정 반영 안 됨

증상

conf 파일에 설정이 있지만 nginx -T에서 확인 안 됨.

진단 방법

# 1. conf 파일 확인
pct exec 150 -- docker exec npm cat /data/nginx/proxy_host/167.conf | grep 8765

# 2. nginx 로드된 설정 확인
pct exec 150 -- docker exec npm nginx -T 2>&1 | grep 8765

# 3. 결과 비교
# 파일에는 있는데 nginx -T에 없으면 → reload 필요 또는 문법 오류

해결 방법

# 문법 체크
pct exec 150 -- docker exec npm nginx -t

# 문제 없으면 reload
pct exec 150 -- docker exec npm nginx -s reload

# 그래도 안 되면 컨테이너 재시작
pct exec 150 -- docker restart npm

---

유용한 진단 명령어

NPM 상태 확인

# 컨테이너 상태
pct exec 150 -- docker ps | grep npm

# nginx 설정 테스트
pct exec 150 -- docker exec npm nginx -t

# nginx reload
pct exec 150 -- docker exec npm nginx -s reload

# 컨테이너 재시작
pct exec 150 -- docker restart npm

로그 확인

# 특정 호스트 액세스 로그
pct exec 150 -- docker exec npm tail -50 /data/logs/proxy-host-167_access.log

# 에러 로그
pct exec 150 -- docker exec npm tail -20 /data/logs/proxy-host-167_error.log

# /ws 요청만 필터
pct exec 150 -- docker exec npm tail -100 /data/logs/proxy-host-167_access.log | grep ws

WebSocket 연결 테스트

# 직접 연결 테스트 (CT 150에서)
curl -v --max-time 5 \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  -H "Sec-WebSocket-Version: 13" \
  http://192.168.0.14:8765

# 성공 시: HTTP/1.1 101 Switching Protocols

프록시 호스트 번호 찾기

# 도메인으로 설정 파일 찾기
pct exec 150 -- docker exec npm grep -r "mile.0bin" /data/nginx/proxy_host/
# → /data/nginx/proxy_host/167.conf

---

최종 작동 구성

네트워크 구조

[브라우저] 
    │
    │ HTTPS (외부) 또는 HTTP (내부)
    ▼
[NPM - 192.168.0.105:443/80]
    │
    ├─ /pmr/* → http://192.168.0.14:7001 (Flask)
    │
    └─ /ws → http://192.168.0.14:8765 (WebSocket)
    
[Flask 서버 - 192.168.0.14:7001]
    │
    └─ PMR 웹 앱
    
[Trigger 서버 - 192.168.0.14:8765]
    │
    └─ WebSocket 처방 감지 알림

프론트엔드 WebSocket 연결 코드

// pmr.html
const TRIGGER_WS_URL = location.protocol === 'https:'
    ? `wss://${location.host}/ws`  // 외부: NPM 프록시
    : `ws://${location.hostname}:8765`;  // 내부: 직접 연결

NPM Advanced 설정 (mile.0bin.in)

location /ws {
    proxy_pass http://192.168.0.14:8765;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 86400;
}

---

체크리스트

WebSocket 프록시 설정 시 확인 사항:

• WebSocket 서버(trigger_server.py) 실행 중인가?
• 8765 포트 리스닝 중인가? (netstat -ano | findstr :8765)
• NPM Advanced에 /ws location 설정했는가?
• /data/nginx/custom/ 폴더에 중복 설정 없는가?
• nginx -t 통과하는가?
• nginx reload 했는가?
• 브라우저 캐시 비웠는가? (Ctrl+Shift+R)

---

교훈

1. NPM 설정은 반드시 웹 UI로 - conf 파일 직접 수정 금지
2. duplicate location 주의 - custom 폴더와 Advanced 설정 중복 확인
3. HTTP/2 + WebSocket = 문제 - 내부 HTTP 접속 또는 별도 서브도메인 사용
4. 변경 후 항상 테스트 - nginx -t 습관화
5. 문제 생기면 로그 먼저 - access_log, error_log 확인

---

작성일: 2026-03-05 작성: 용림 (Clawdbot)