Open WebUI가 Docker 환경에서 Ollama에 연결할 수 없을 때 해결 방법

Open WebUI를 실행하고 모델 선택기를 열어보면 비어 있거나, 관리자 연결 확인이 실패하는 경우가 있습니다. 서버에서 curl localhost:11434를 실행하면 'Ollama is running'이라는 응답이 오므로 Ollama는 분명히 작동하고 있습니다. 그렇다면 왜 Open WebUI가 이를 인식하지 못할까요?

거의 항상, Open WebUI는 컨테이너 내부에서 Ollama로 연결되지 않는 주소에 있는 Ollama에 접근하려고 시도합니다. 이 가이드에서는 각 일반적인 설정에 맞는 URL, 컨테이너 내부에서 실행할 수 있는 간단한 테스트, 그리고 올바른 수정이 아무 효과가 없는 것처럼 보이게 만드는 '저장된 설정' 함정을 제공합니다.

많은 사람들이 이 두 가지를 함께 사용합니다. 2026년 10월 14일 기준으로 Open WebUI repository는 약 155,600개의 GitHub 스타를 보유했으며, ollama/ollama 이미지는 Docker Hub에서 1억 8,600만 회 이상 풀링되었습니다.

시작하기 전에 한 가지 경고가 있습니다. Open WebUI의 roles documentation에 따르면: "새 설치에서 생성되는 첫 번째 계정은 자동으로 Admin 역할을 할당받습니다." 만약 가입하기 전에 포트 3000이 인터넷에서 접근 가능하다면, 외부인이 해당 계정을 만들어 인스턴스를 장악할 수 있습니다. 또한 Docker's firewall docs에 따르면 Docker로 게시된 포트는 UFW를 건너뜁니다. 따라서 아래의 모든 예시는 UI를 127.0.0.1:3000에 바인딩합니다. Nginx Proxy Manager와 같은 리버스 프록시나 SSH 터널(ssh -L 3000:127.0.0.1:3000 you@server)을 통해 접근하고 즉시 관리자 계정을 생성하세요.

요약하자면:

• Open WebUI 컨테이너 내부에서 localhost는 해당 컨테이너 자체를 의미하므로, http://localhost:11434로는 Ollama에 도달할 수 없습니다.
• 두 서비스가 하나의 Compose 파일 내에서 실행되는 경우 http://ollama:11434를 사용하세요. Ollama가 Linux 호스트에서 실행되는 경우, http://host.docker.internal:11434와 함께 extra_hosts 항목으로 host.docker.internal:host-gateway를 추가하고, Ollama가 127.0.0.1보다 더 많은 주소(IP)에서 수신 대기하도록 설정해야 합니다.
• 컨테이너 내부에서 테스트해 보세요. 예를 들어 docker exec open-webui curl -s http://ollama:11434. 'Ollama가 실행 중'이어야 합니다.
• OLLAMA_BASE_URL을 변경했는데 아무 변화가 없다면? Open WebUI가 이전에 저장된 값을 데이터베이스에 보관했기 때문입니다. 관리자 패널(Admin Panel) > 설정(Settings) > 연결(Connections)에서 변경하세요.

설정 환경에 맞는 올바른 Ollama URL

빠른 답변

만약 OLLAMA_BASE_URL을 변경했는데 아무 변화가 없다면, 저장된 설정 섹션으로 건너뛰세요.

컨테이너 내부에서 localhost가 실패하는 이유

각 컨테이너는 자체 네트워크 네임스페이스를 가지고 있습니다. Open WebUI 컨테이너 내부에서 localhost와 127.0.0.1은 서버 자체가 아니라 Open WebUI 컨테이너 자신을 의미합니다. 해당 컨테이너 내에서는 아무것도 11434 포트에서 수신 대기하고 있지 않으므로, 연결이 거부됩니다.

이 문제는 OLLAMA_BASE_URL=http://localhost:11434로 설정하고 Ollama를 별도의 컨테이너에서 실행했을 때 재현됩니다. UI에는 오류 없이 모델 목록만 `{

관리 설정의 연결 확인 기능에서 문제가 있음을 보여주었습니다. http://localhost:11434에 대한 '연결 편집(Edit Connection)' 대화 상자에서 검증 버튼을 클릭하자 빨간색으로 "Ollama: 네트워크 문제(Network Problem)" 메시지가 나타났습니다:

먼저 본인의 로그를 확인하세요:

docker logs open-webui 2>&1 | grep -i "ollama\|11434" | tail

컨테이너 내부에서 연결 테스트하기

Open WebUI가 실행되는 곳에서 curl 실행하기

노트북이나 호스트 셸에서 테스트하지 마세요. Open WebUI가 실제로 실행되는 곳에서 테스트해야 합니다. 공식 이미지는 curl을 포함하고 있습니다:

docker exec open-webui curl -s http://ollama:11434
docker exec open-webui curl -s http://host.docker.internal:11434/api/version

첫 번째 명령어의 경우 "Ollama is running"이, 두 번째 명령어의 경우 {"version":"0.40.4"}와 같은 응답을 받아야 합니다. 작동하는 것을 확인했다면, 동일한 네트워크 액세스를 가진 컨테이너에서 Uptime Kuma의 HTTP 모니터로 계속 주시할 수 있습니다. URL만 같은 것이라면 됩니다. open-webui를 본인의 컨테이너 이름으로 교체하세요. docker ps 명령어로 확인할 수 있으며, Compose 이름은 myproject-open-webui-1과 같은 형태입니다.

이것은 실험실의 테스트와 동일합니다. 먼저 localhost로 설정된 컨테이너에서 테스트하고, 다음으로 서비스 이름으로 설정된 컨테이너에서 테스트하는 것입니다:

curl 오류의 의미

• curl: (7) Failed to connect ... Couldn't connect to server: 이름은 확인되었으나, 해당 IP 및 포트에서 연결을 수락하는 서버가 없습니다. Ollama는 아마도 127.0.0.1에서만 리스닝하고 있을 가능성이 높습니다 (다음 섹션 참조).
• Could not resolve host: 컨테이너 내부에는 해당 이름이 존재하지 않습니다. Linux 환경에서는 host.docker.internal을 사용하려면 extra_hosts가 필요합니다. Compose 서비스 이름은 동일한 Compose 네트워크 내부에서만 해결됩니다.
• 타임아웃까지 대기(hang until timeout): 패킷 손실이 발생하고 있다는 의미이며, 보통 방화벽 때문입니다.

호스트에 설치된 Ollama (Ollama installed on the host)

이 설정은 사용자가 서버에서 Ollama 설치 스크립트를 실행하여 Ollama가 시스템d 서비스로 실행되고 Open WebUI가 Docker 내부에서 실행되는 경우입니다. 이 설정에는 두 가지 수정 사항이 필요하며, 대부분의 사람들은 첫 번째 것만 수행합니다.

Linux에서 host.docker.internal 추가하기

Docker Desktop(Mac 및 Windows)에서는 host.docker.internal이 별도의 설정 없이 작동합니다. 하지만 Linux에서는 이를 추가하지 않으면 존재하지 않습니다. Docker의 특별한 값인 host-gateway는 이를 기본 브릿지 네트워크 상의 호스트 주소에 매핑해 줍니다. 이 테스트 박스는 172.17.0.1이었습니다.

이것이 Open WebUI 자체의 빠른 시작(quick-start) 명령어가 --add-host를 포함하는 이유입니다. 여기서는 포트를 localhost에 바인딩한 예시가 있습니다. 문서는 -p 3000:8080을 사용하는데, 이는 모든 인터페이스에서 리스닝합니다.

openssl rand -hex 32 > ~/.open-webui-secret && chmod 600 ~/.open-webui-secret
docker run -d -p 127.0.0.1:3000:8080 \
  --add-host=host.docker.internal:host-gateway \
...

또는 Compose를 사용하는 경우:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:v0.12.0
...

Open WebUI의 환경 변수 참조(environment variable reference)에는 OLLAMA_BASE_URL에 대한 Docker 기본값으로 http://host.docker.internal:11434가 나열되어 있습니다. 따라서 이 설정의 경우, extra_hosts가 compose 파일에서 누락된 유일한 항목인 경우가 많습니다.

비밀 키를 파일 안에 직접 입력하는 대신, compose.yaml 옆에 있는 .env 파일에 넣으세요. Compose는 .env 파일을 자동으로 읽어 들입니다:

echo

고정 키(fixed key)가 왜 필요할까요? 고정 키가 없으면 Open WebUI는 컨테이너 내부에 키 파일을 생성합니다. 같은 참고 자료에 따르면, 컨테이너를 재생성하고 해당 파일이 영속 볼륨(persisted volume)에 없을 경우 새로운 키가 생성된다고 합니다. 이 경우 모든 사용자가 로그아웃되고, OAuth 세션이 작동하지 않으며, MCP 도구들이 토큰을 복호화하는 데 실패하고, MFA가 활성화된 상태에서는 Open WebUI가 시작을 거부합니다(단, `MFA_ENCRYPTION_KEY`가 설정되지 않은 경우). 

키 생성 명령어 중 아무거나 한 번 실행하세요. 다시 실행하면 키가 새로운 것으로 덮어쓰여지며, 새 키는 정확히 동일한 영향을 미칩니다: 모든 사용자가 로그아웃됩니다.

### Ollama가 127.0.0.1보다 더 많은 주소에서 수신 대기하도록 설정하기

이 방법은 호스트에 있는 Ollama를 사용하는 거의 모든 경우에 해당합니다. [Ollama FAQ](https://docs.ollama.com/faq)에는 명확하게 나와 있습니다: "Ollama는 기본적으로 127.0.0.1 포트 11434에서 바인딩됩니다." 이는 루프백(loopback) 전용입니다. 컨테이너에서 오는 요청은 Docker 브릿지 주소(`172.17.0.1`)로 도착하며, 루프백으로 오지 않기 때문에 Ollama가 이를 감지하지 못합니다. [Open WebUI 연결 가이드](https://docs.openwebui.com/troubleshooting/connection-error/)에서도 동일한 원인을 가장 먼저 언급하고 있습니다.

이를 재현하려면, Ollama를 호스트 네트워크에 `127.0.0.1:11434`로 바인딩하여 실행합니다. `host-gateway`가 설정된 컨테이너에서 다음을 수행합니다:

$ getent hosts host.docker.internal
172.17.0.1 host.docker.internal
$ curl http://host.docker.internal:11434
...

이름은 올바르게 해석되지만, 연결이 거부됩니다. 반면 호스트에서 `curl localhost:11434`는 정상적으로 작동하므로 이 상황이 매우 혼란스럽습니다.

해결책은 Ollama가 루프백보다 더 많은 주소에서 수신 대기하도록 만드는 것입니다. Linux systemd 설치의 경우, FAQ에 나와 있는 방법은 다음과 같습니다:

sudo systemctl edit ollama.service

다음 내용을 추가합니다:

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

그런 다음:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ss -ltn | grep 11434 # 이제 *:11434 또는 0.0.0.0:11434가 표시되어야 하며, 127.0.0.1:11434는 아니어야 합니다

이 변경 사항을 적용한 후, 컨테이너에서 실행한 동일한 `curl` 명령은 'Ollama is running'이라는 응답을 반환했습니다.

`0.0.0.0`을 사용할 때는 주의해야 합니다. 이는 공용 인터페이스를 포함한 모든 인터페이스를 의미하며, Ollama의 API는 인증이 없습니다. VPS(Virtual Private Server)를 사용한다면 클라우드 방화벽에서 11434 포트를 인터넷으로부터 차단하십시오. 또는 Ollama을 Docker 브릿지 주소에만 바인딩하세요:

[Service]
Environment="OLLAMA_HOST=172.17.0.1:11434"

이 방법도 테스트해 보았습니다. 기본 브릿지(default bridge)의 컨테이너와 Compose 네트워크의 컨테이너 모두 `host.docker.internal`을 통해 접근할 수 있었고, 호스트 외부에서는 아무것도 할 수 없었습니다. 문제는 호스트의 `localhost:11434`가 작동하지 않으므로, 셸에서도 `ollama` CLI에 `OLLAMA_HOST=172.17.0.1:11434`를 설정해야 한다는 것입니다.

`172.17.0.1`은 Docker의 `docker0` 브릿지에 속하므로, Docker가 실행되는 동안에만 존재합니다. 시스템 부팅 후에도 systemd가 Ollama을 시작하도록 하려면, 동일한 오버라이드(override) 내의 `[Unit]` 섹션 아래에 `After=docker.service`도 추가하십시오.

UFW(Uncomplicated Firewall) 역시 여기서 방해가 될 수 있습니다. 컨테이너에서 `172.17.0.1:11434`로 가는 트래픽은 공개된 컨테이너 포트로 향하는 것이 아니라 호스트 자체에 주소 지정되므로, UFW의 일반적인 인바운드(input) 규칙이 적용됩니다. 만약 UFW 기본 설정이 `deny incoming`(들어오는 연결 거부)이고 컨테이너 요청이 멈춘다면, Docker의 서브넷만 해당 포트로 허용하는 규칙은 다음과 같습니다:

sudo ufw allow from 172.16.0.0/12 to any port 11434 proto tcp