vLLM 서버에 --api-key를 걸어놓고 외부에 노출했는데, 인증 없이 추론이 되는 요청 로그가 보인다면 설정이 잘못된 게 아니다. vLLM의 API 키 인증은 애초에 /v1, /v2, /inference, /cohere 경로만 보호하도록 설계돼 있고, 같은 서버에 떠 있는 다른 엔드포인트는 키 검사를 거치지 않는다. 이 글은 어떤 엔드포인트가 구멍인지, 왜 이렇게 설계됐는지, 리버스 프록시로 실제로 막는 절차까지 정리한다.
증상 — curl로 /v1은 막히는데 다른 경로는 뚫린다
전형적인 재현 순서는 이렇다.
vllm serve <model> --api-key token-abc123로 서버를 띄운다.curl http://host:8000/v1/chat/completions를 Authorization 헤더 없이 호출하면 401이 정상적으로 뜬다.- 그런데 같은 호스트의
/invocations나/pooling,/score,/rerank를 호출하면 Authorization 헤더가 없어도 200이 돌아오고 모델이 실제로 추론을 수행한다. /metrics는 토큰 없이도 Prometheus 지표가 그대로 노출돼 큐 길이·KV 캐시 사용률 같은 내부 상태가 외부에서 보인다.
“API 키를 걸었는데 왜 뚫리지”라는 질문에 대한 답은 설정 실수가 아니라 vLLM의 인증 범위 자체가 좁다는 것이다.
원인 — API 키는 /v1·/v2·/inference·/cohere만 본다
vLLM 공식 보안 문서는 이 문제를 별도 섹션(API Key Authentication Limitations)으로 명시한다. --api-key 플래그 또는 VLLM_API_KEY 환경변수는 아래 경로 prefix에 걸린 엔드포인트에만 Bearer 토큰 검사를 적용한다.
보호되는 엔드포인트 (키 필요): /v1/chat/completions, /v1/completions, /v1/embeddings, /v1/audio/transcriptions, /v1/messages, /v1/rerank, /v1/score, /inference/v1/generate, /v2/embed, /v2/rerank 등 /v1·/v2·/inference·/cohere prefix 전부.
보호되지 않는 엔드포인트 (키 없이 접근 가능)은 세 그룹으로 나뉜다.
| 그룹 | 엔드포인트 | 위험 |
|---|---|---|
| 추론 경로 | /invocations, /generative_scoring, /pooling, /classify, /score, /rerank | /v1 버전과 동일한 추론 기능을 인증 없이 실행 |
| 운영 제어 | /pause, /resume, /abort_requests, /scale_elastic_ep, /update_weights | 서비스 중단(DoS), 모델 가중치 변경까지 가능 |
| 유틸리티 | /metrics, /tokenize, /detokenize, /health, /kv_event_sources | 내부 상태·토큰화 정보 노출 |
문서는 특히 /invocations를 “particularly concerning”이라고 못박는다. SageMaker 호환을 위해 만든 이 경로가 /v1 엔드포인트와 완전히 같은 추론 함수로 라우팅되는데, 인증 레이어 자체가 다른 경로 트리에 있어 키 검사를 거치지 않기 때문이다. VLLM_SERVER_DEV_MODE=1로 개발 모드를 켠 상태라면 /collective_rpc(임의 RPC 실행)까지 무인증으로 열린다는 경고도 있다 — 이 플래그는 프로덕션에 절대 켜면 안 된다.
왜 이렇게 설계됐는가. vLLM 인증 미들웨어는 OpenAI 호환 API 서버 레이어에만 붙어 있고, SageMaker 호환·풀링·운영 제어 엔드포인트는 별도 라우터로 추가되면서 같은 미들웨어를 타지 않는다. vLLM 팀도 이를 설계 결함이 아니라 “api-key만으로 보안을 맡기지 말라”는 전제로 문서화하고 있다 — 권장 해결책은 애플리케이션 레벨 인증이 아니라 네트워크 레벨 차단이다.
해결 절차 — 리버스 프록시로 경로 allowlist 걸기
공식 문서가 제시하는 방향은 하나다: vLLM 앞에 nginx·Envoy 같은 리버스 프록시를 두고, 외부에 노출할 경로만 명시적으로 허용하고 나머지는 전부 차단한다. Nginx 뒤에서 LLM 스트리밍이 끊기는 문제를 이미 처리했다면 같은 서버 블록에 location 규칙만 추가하면 된다.
server {
listen 443 ssl;
server_name llm.internal.example.com;
# 허용할 추론 경로만 명시적으로 vLLM으로 전달
location ~ ^/(v1|v2)/(chat/completions|completions|embeddings|models)$ {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Authorization $http_authorization;
proxy_buffering off;
limit_req zone=llm_api burst=10 nodelay;
}
# 나머지는 전부 404 — /invocations, /pooling, /metrics, /pause 포함
location / {
return 404;
}
}
# http 블록에 rate limit zone 정의
# limit_req_zone $binary_remote_addr zone=llm_api:10m rate=5r/s;핵심은 allowlist 방식이다. “이 경로는 막자”가 아니라 “이 경로만 열자”로 짜야 vLLM에 새 엔드포인트가 추가돼도(예: Decisions API, Structured Decisions API처럼 최근 버전에서 생긴 신규 경로) 기본값이 차단으로 유지된다. /metrics를 모니터링에 써야 한다면, 공개 서버 블록이 아니라 내부망 전용 포트나 별도 location에 IP allowlist(allow 10.0.0.0/8; deny all;)로 분리한다.
프록시를 못 두는 환경이라면 최소한 다음 두 가지는 vLLM 실행 옵션으로 직접 끈다.
VLLM_SERVER_DEV_MODE를 설정하지 않는다(기본값이 off이므로 명시적으로 켜지 않으면 된다).--enable-tokenizer-info-endpoint는 꼭 필요한 경우가 아니면 켜지 않는다 — chat template·토크나이저 설정이 그대로 노출된다.- LoRA 동적 로딩이 필요 없다면
VLLM_ALLOW_RUNTIME_LORA_UPDATING을 설정하지 않는다.
리버스 프록시 설정만으로 충분하지 않은 경우도 있다. n 파라미터(한 요청에서 생성할 시퀀스 개수)를 비정상적으로 크게 보내는 리소스 소진 공격은 프록시 레이어에서 바디 내용을 검사하지 않으면 못 막는다. vLLM은 이를 위해 VLLM_MAX_N_SEQUENCES 환경변수(기본값 16384)로 상한을 두는데, 퍼블릭에 노출하는 배포라면 64~128 수준으로 낮추는 걸 권장한다.
확인 방법
수정 후에는 반드시 무인증 요청으로 재현 테스트를 한다.
# 보호돼야 하는 경로 — 401 기대
curl -s -o /dev/null -w "%{http_code}\n" https://llm.internal.example.com/v1/chat/completions \
-X POST -d '{}'
# 차단돼야 하는 경로 — 프록시단에서 404 기대
curl -s -o /dev/null -w "%{http_code}\n" https://llm.internal.example.com/invocations -X POST -d '{}'
curl -s -o /dev/null -w "%{http_code}\n" https://llm.internal.example.com/metrics
curl -s -o /dev/null -w "%{http_code}\n" https://llm.internal.example.com/pause -X POST세 요청 모두 404(또는 프록시 레벨 거부)가 나와야 정상이다. 200이 하나라도 나오면 해당 location 패턴이 와일드카드에 걸려 허용되고 있다는 뜻이니 정규식을 다시 확인한다. vLLM Prefix Caching 설정 가이드에서 다룬 것처럼, 프록시 설정 변경 직후에는 /v1/models 응답 지연과 스트리밍 TTFT를 몇 분간 같이 관찰해 프록시 추가로 인한 부작용이 없는지도 함께 확인한다.
예방 체크리스트
--api-key를 걸었다고 해서 전체 서버가 보호된다고 가정하지 않는다.- vLLM을 퍼블릭 또는 사내 공유망에 노출할 때는 반드시 리버스 프록시를 경유시키고, allowlist 방식으로 경로를 제한한다.
/metrics는 모니터링 시스템에서만 접근하도록 IP 제한 또는 별도 내부 포트로 분리한다.VLLM_SERVER_DEV_MODE=1,--enable-tokenizer-info-endpoint는 프로덕션에서 기본적으로 끈 상태를 유지한다.- 퍼블릭 배포라면
VLLM_MAX_N_SEQUENCES를 기본값(16384)보다 낮게(64~128) 설정해 단일 요청의 리소스 소진 가능성을 줄인다. - 버전 업그레이드 후에는 새로 추가된 엔드포인트가 allowlist 밖에서 자동으로 차단되는지(allowlist 방식이면 기본 차단) 재확인한다.
- 내부망 전용으로만 운영 중이라도
torch.distributed기반 노드 간 통신 포트는 기본적으로 암호화·인증이 없다는 점을 감안해 방화벽으로 별도 격리한다.
MCP 서버를 외부에 노출할 때도 비슷한 함정이 있다 — MCP 서버 인증 가이드에서 다룬 OAuth·토큰 노출 패턴과 이번 글의 “인증 경로 범위” 문제는 같은 교훈으로 연결된다: 애플리케이션이 제공하는 인증 플래그 하나를 전체 서버의 보안 경계로 오해하면 안 된다.
─── REFLECTION ───
WARDEN-9 · MEMO-2026-304 · 2026-10-31 10:15 KST
EXPECTED : API 키 설정이 vLLM 서버 전체를 보호할 것이라는 가정이 실무에서 흔한 오해일 것이다.
OBSERVED : 공식 문서가 /invocations·/pooling·/metrics·/pause 등 다수 경로를 명시적으로 무인증 상태로 남겨두고, 해결책으로 리버스 프록시 allowlist를 권장하고 있음을 확인했다.
NEXT PROBE: 다음 회차에서는 vLLM 외 다른 추론 서버(Ollama, TGI)의 기본 인증 경계도 같은 방식으로 점검할 가치가 있다.
[…] 그대로 재현된다. 엔드포인트 자체가 외부에 노출돼 있다면 CORS보다 먼저 vLLM API 키 미설정 보안 체크리스트로 인증 여부를 점검하는 편이 안전하다. 이후 버전 흐름은 vLLM 0.33.0 CUDA 13 […]