← 블로그로 돌아가기

Ollama 프록시: HTTP_PROXY 설정 및 모델 풀 오류 수정 방법

Ollama를 프록시 서버에서 설정하는 방법에 대한 자세한 분석 - 환경 변수에서 모델 풀 오류 진단 및 적절한 프록시 유형 선택까지.

📅2026년 11월 16일

기업 네트워크, VPN 또는 외부 프록시 서버를 통해 ollama pull 명령으로 모델을 다운로드하려고 시도하는 경우, dial tcp: lookup registry.ollama.ai 또는 context deadline exceeded와 같은 오류에 직면했을 것입니다. Ollama는 기본적으로 시스템 프록시 설정을 항상 올바르게 인식하지 않으며, 모델의 큰 용량(2GB에서 70GB 이상)은 문제를 악화시킵니다 — 다운로드 중간에 연결이 끊어질 수 있습니다. 이 기사에서는 환경 변수를 올바르게 설정하고 Docker 및 systemd에서 프록시를 구성하는 방법을 설명하며, 가장 일반적인 pull 오류를 해석하고 이를 해결하는 방법을 제시합니다.

Ollama가 네트워크 및 프록시와 함께 작동하는 방법

Ollama는 클라이언트-서버 애플리케이션입니다: 로컬 서버(ollama serve) 는 CLI에서 명령을 받고 모델 레지스트리 registry.ollama.ai 및 모델 레이어를 저장하는 CDN에 네트워크 요청을 수행합니다. ollama pull llama3 명령은 실제로 Docker pull과 유사한 일련의 HTTPS 요청을 수행합니다: 먼저 모델의 매니페스트를 요청한 후, 이진 레이어(GGUF 파일)를 순차적으로 또는 병렬로 다운로드합니다.

중요한 점: 네트워크 요청은 서버 프로세스 Ollama에 의해 수행되며, CLI 명령이 아닙니다. 이는 프록시 설정을 포함한 환경 변수를 ollama serve 프로세스가 실행되는 곳에서 설정해야 하며, ollama pull을 호출하는 터미널에서는 설정하지 않아야 합니다. 서비스가 systemd 유닛으로 실행되거나 Docker 컨테이너에서 실행되는 경우, 일반 bash 세션에서 변수를 내보내는 것은 영향을 미치지 않습니다 — 이는 "프록시가 설정된 것 같은데 pull이 여전히 작동하지 않는" 가장 일반적인 이유입니다.

HTTP_PROXY, HTTPS_PROXY, NO_PROXY 환경 변수

Ollama는 Go로 작성되었으며, Go의 표준 HTTP 라이브러리는 전통적인 환경 변수에서 프록시 설정을 읽습니다:

  • HTTP_PROXY — 일반 HTTP 요청을 위한 프록시
  • HTTPS_PROXY — HTTPS 요청을 위한 프록시 (모델 다운로드에 필요하며, 레지스트리는 TLS를 통해 작동합니다)
  • NO_PROXY — 프록시에서 제외할 호스트 목록 (예: 127.0.0.1:11434에서 Ollama의 로컬 API)

값의 형식: http://user:password@host:port는 인증이 필요한 프록시를 위한 것이며, socks5://host:port는 SOCKS5를 위한 것입니다. Go는 두 가지 옵션을 모두 지원하지만, SOCKS5의 경우 Ollama 바이너리가 이 프록시를 지원하도록 빌드되어야 합니다 — 대부분의 최신 빌드에서 지원되지만, 오류가 발생할 경우 먼저 HTTP/HTTPS 프록시에서 테스트하여 이 변수를 배제하는 것이 좋습니다.

중요: 환경 변수를 소문자와 대문자 모두에서 지정하세요 (http_proxy 및 HTTP_PROXY). 일부 Linux 배포판은 소문자만 읽고, Go 애플리케이션은 때때로 대문자를 기대합니다 — 둘 다 설정하는 것이 좋습니다, 그래야 추측할 필요가 없습니다.

Linux 및 macOS에서의 설정

Ollama를 터미널에서 직접 실행하는 경우(시스템 서비스로 실행하지 않는 경우), 서버를 시작하기 전에 변수를 내보내면 됩니다:

export HTTP_PROXY="http://user:[email protected]:8000"
export HTTPS_PROXY="http://user:[email protected]:8000"
export http_proxy="http://user:[email protected]:8000"
export https_proxy="http://user:[email protected]:8000"
export NO_PROXY="localhost,127.0.0.1"

ollama serve &
ollama pull llama3

설정을 세션 간 유지하려면, 이 줄을 ~/.bashrc, ~/.zshrc 또는 ~/.profile 파일에 추가하세요, 사용하는 셸에 따라 다릅니다. 편집 후 source ~/.bashrc를 실행하고 Ollama 프로세스를 재시작하세요 — 환경 변수는 프로세스 시작 시에만 읽히며, 핫 리로드는 지원되지 않습니다.

macOS에서 Ollama가 애플리케이션으로 설치된 경우(홈브류를 통해 설치하지 않은 경우), 터미널의 환경 변수가 GUI를 통해 실행된 프로세스에 도달하지 않을 수 있습니다. 이 경우 launchctl setenv를 통해 변수를 설정하는 것이 더 안전합니다:

launchctl setenv HTTPS_PROXY "http://user:[email protected]:8000"
launchctl setenv HTTP_PROXY "http://user:[email protected]:8000"
# 이후 Ollama 애플리케이션을 완전히 재시작하세요 (트레이에서 종료, 단순히 창을 닫는 것이 아님)

Windows에서의 설정

PowerShell에서 변수는 현재 세션에 대해 다음 명령으로 설정됩니다:

$env:HTTP_PROXY="http://user:[email protected]:8000"
$env:HTTPS_PROXY="http://user:[email protected]:8000"
$env:NO_PROXY="localhost,127.0.0.1"

ollama pull mistral

Ollama가 백그라운드 서비스로 실행되는 경우(시스템 트레이 아이콘), 세션 변수만으로는 충분하지 않습니다 — 서비스는 시스템에 로그인할 때 시작되며 PowerShell을 열기 전에 시작됩니다. 사용자 또는 시스템 수준에서 변수를 설정해야 하며, "설정 → 시스템 → 정보 → 고급 시스템 설정 → 환경 변수"를 통해 설정한 후, ollama.exe 프로세스를 작업 관리자를 통해 완전히 종료하고 애플리케이션을 재시작해야 합니다.

Docker에서 Ollama를 위한 프록시

Ollama가 컨테이너에서 실행되는 경우(서버 배포에서 흔한 경우), 호스트의 환경 변수가 자동으로 컨테이너 내부로 전달되지 않습니다 — -e 또는 docker-compose의 environment 섹션을 통해 명시적으로 전달해야 합니다:

docker run -d \
  -e HTTP_PROXY="http://user:[email protected]:8000" \
  -e HTTPS_PROXY="http://user:[email protected]:8000" \
  -e NO_PROXY="localhost,127.0.0.1" \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama ollama/ollama

docker-compose.yml에서도 유사하게 설정합니다:

version: "3.8"
services:
  ollama:
    image: ollama/ollama
    environment:
      - HTTP_PROXY=http://user:[email protected]:8000
      - HTTPS_PROXY=http://user:[email protected]:8000
      - NO_PROXY=localhost,127.0.0.1
    volumes:
      - ollama:/root/.ollama
    ports:
      - "11434:11434"
volumes:
  ollama:

변수를 변경한 후에는 컨테이너를 재생성해야 합니다 (docker compose up -d --force-recreate), 단순한 재시작으로는 충분하지 않습니다, 환경 변수는 컨테이너 생성 시에 고정됩니다.

Ollama systemd 서비스용 프록시

Linux 서버에서 Ollama는 종종 공식 설치 스크립트를 통해 systemd 서비스로 설치됩니다. 이 경우 환경 변수는 터미널에서 export를 통해 설정하는 것이 아니라 오버라이드 파일을 통해 설정됩니다:

sudo systemctl edit ollama.service

열린 편집기에 다음을 추가하세요:

[Service]
Environment="HTTP_PROXY=http://user:[email protected]:8000"
Environment="HTTPS_PROXY=http://user:[email protected]:8000"
Environment="NO_PROXY=localhost,127.0.0.1"

그런 다음 변경 사항을 적용하세요:

sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama --property Environment

마지막 명령은 프로세스가 실제로 인식하는 변수를 보여줍니다 — 이는 구성이 적용되었는지 확인하는 편리한 방법으로, 다시 pull을 시도하기 전에 확인할 수 있습니다.

pull 오류 분석 및 해결 방법

프록시를 통해 모델을 다운로드할 때 발생하는 가장 일반적인 오류 메시지와 그에 대한 해결 방법을 살펴보겠습니다.

dial tcp: lookup registry.ollama.ai: no such host

프록시 뒤에서 DNS 해상도가 작동하지 않습니다 — 일반적으로 이는 요청이 프록시 서버를 우회하여 직접 나가려 하거나, 머신이 DNS에 접근할 수 없음을 의미합니다 (폐쇄된 기업 네트워크). 해결 방법: HTTPS_PROXY 가 실제로 프로세스에 인식되고 있는지 확인하세요 (위의 systemctl show 명령 참조), 그리고 프록시 서버가 외부 도메인을 해상할 수 있는지 확인하세요 (SOCKS5 프록시는 자신의 측에서 DNS를 해상하고, HTTP 프록시도 마찬가지지만, 일부 로컬 프록시는 이를 수행하지 않습니다).

proxyconnect tcp: dial tcp: connection refused

Ollama가 프록시에 연결하려고 시도하지만 거부됩니다. 포트와 호스트에 오타가 없는지 확인하고, 프록시 서버가 실제로 외부에서 지정된 포트를 수신하고 있는지 확인하세요 (localhost에서만 수신하는 것이 아님) 및 방화벽이 프록시 포트에 대한 아웃바운드 연결을 차단하고 있지 않은지 확인하세요.

407 Proxy Authentication Required

프록시가 로그인과 비밀번호를 요구하지만 제공되지 않았거나 잘못 제공되었습니다. 환경 변수에 로그인과 비밀번호가 http://user:password@host:port 형식으로 포함되어 있는지 확인하고, 비밀번호의 특수 문자 (예: @ 또는 :) URL 인코딩을 통해 인코딩되어 있는지 확인하세요 (%40, %3A).

x509: certificate signed by unknown authority

이는 TLS 검사(MITM)가 있는 기업 프록시의 징후로, SSL 인증서를 자신의 루트로 대체합니다. Ollama의 Go 클라이언트는 이 인증서를 신뢰하지 않습니다. 해결 방법은 기업의 루트 인증서를 시스템의 신뢰할 수 있는 인증 기관 저장소에 추가하는 것입니다 (Linux에서는 일반적으로 .crt 파일을 /usr/local/share/ca-certificates/에 복사한 후 update-ca-certificates를 통해 수행합니다). 인증서 검증을 전역적으로 비활성화하는 것은 권장되지 않습니다 — 이는 트래픽 가로채기에 대한 경로를 열어줍니다.

context deadline exceeded / i/o timeout при скачивании слоя

대형 모델 레이어를 다운로드하는 중간에 연결이 끊어집니다 (종종 4-40GB 파일). 이러한 오류는 거의 항상 프록시 서버의 불안정성 또는 낮은 대역폭을 나타내며, Ollama 자체의 문제는 아닙니다. 무료 또는 과부하된 공용 프록시는 긴 TCP 세션을 끊어버리며, 다운로드가 몇 분 이상 걸리는 경우 특히 그렇습니다. 이러한 경우 더 안정적인 채널로 전환하는 것이 도움이 됩니다 — 예를 들어, 데이터 센터 프록시는 높은 속도와 안정적인 연결을 제공하여 대형 파일을 다운로드할 때 끊김 없이 지원합니다.

Ollama에 적합한 프록시 유형 선택

프록시 유형 선택은 Ollama에 프록시가 필요한 이유에 따라 다릅니다. 기업 방화벽의 제한을 우회하는 것이 목표라면, 거의 모든 안정적인 HTTP(S) 프록시가 적합합니다. 그러나 모델 레지스트리의 지리적 차단을 우회하거나 요청이 데이터 센터에서 발생하는 것을 숨기는 것이 목표라면, 프록시 유형 선택이 중요해집니다.

프록시 유형 속도 Ollama에 사용할 때
데이터 센터 높음 대형 모델 레이어(4-40+GB) 다운로드 시 끊김 없이, 다양한 데이터 센터 위치에서 테스트
주거용 중간 레지스트리의 지리적 제한 우회, 데이터 센터 IP가 지역 속도 제한에 걸릴 때
모바일 변동 IP 제공업체의 범위가 완전히 차단된 경우, 속도 변동으로 인해 대규모 다운로드에는 덜 효과적

Ollama와 관련된 대부분의 시나리오에서 — 수십 기가바이트의 모델을 안정적으로 다운로드해야 할 경우 — 최적의 선택은 데이터 센터 프록시입니다: 최대 대역폭과 최소 지연을 제공하여 대형 이진 레이어를 다운로드할 때 매우 중요합니다. 주거용 IP는 데이터 센터 IP가 실제로 모델 레지스트리 측의 제한에 걸릴 경우에만 연결하는 것이 좋습니다.

연결 진단

Ollama 자체의 디버깅에 시간을 낭비하기 전에, curl을 통해 프록시를 직접 확인하세요 — 이는 애플리케이션 문제와 프록시 서버 문제 간의 혼란을 배제합니다:

# 프록시를 통한 레지스트리 접근성 확인
curl -v -x http://user:[email protected]:8000 https://registry.ollama.ai/v2/

# 프록시를 통한 다운로드 속도 측정
curl -x http://user:[email protected]:8000 -o /dev/null -w "%{speed_download}\n" https://registry.ollama.ai/v2/

# 자세한 로그와 함께 ollama serve 실행
OLLAMA_DEBUG=1 ollama serve

curl이 성공적으로 응답을 받지만 ollama pull이 여전히 실패한다면 — 문제는 거의 확실히 환경 변수가 서버 프로세스에 전달되지 않았기 때문입니다 (서비스가 다른 사용자로 실행되거나, 다른 셸에서 실행되거나, 오버라이드 없이 systemd 유닛으로 실행됨). systemd 섹션으로 돌아가서 systemctl show ollama --property Environment의 출력을 확인하세요.

curl도 대형 파일 다운로드 중에 끊기거나 불안정한 속도를 보여준다면 — 원인은 프록시 서버 측에 있으며, 대량 데이터 전송에 더 안정적인 프록시 공급자로 변경하는 것을 고려해야 합니다.

결론

Ollama를 프록시에서 설정하는 것은 세 가지 핵심 사항으로 요약됩니다: 환경 변수는 ollama serve 프로세스에 대해 설정되어야 하며, pull을 호출하는 터미널이 아니라; 프록시 URL 형식은 올바르게 인코딩된 로그인과 비밀번호를 포함해야 하며; 인증서 오류가 발생할 경우 기업 루트 인증서를 신뢰할 수 있는 저장소에 추가해야 하며, TLS 검증을 비활성화해서는 안 됩니다. 대부분의 pull 오류는 Ollama 자체의 버그가 아니라, 네트워크 설정이 필요한 프로세스에 적용되지 않았거나 프록시 서버가 대형 파일의 장기 전송을 견디지 못하는 결과입니다.

주요 목표가 수십 기가바이트의 모델을 안정적이고 빠르게 다운로드하여 연결이 끊어지지 않도록 하는 것이라면, 데이터 센터 프록시를 시도해 보시기를 권장합니다 — 이들은 대형 모델 레이어를 다운로드하는 데 필요한 높은 대역폭을 제공합니다. 프록시 사용의 이유가 모델 레지스트리의 지리적 제한을 우회하는 것이라면, 주거용 프록시에 주목하세요, 이들은 클라우드 공급자의 IP 범위에 적용되는 지역 제한에 덜 걸리기 때문입니다.