Open WebUI 화면은 열리는데 모델 선택 목록이 비어 있으면, 먼저 Ollama를 어디에서 실행하고 있는지 떠올려 보세요. 브라우저가 화면을 여는 경로와 Open WebUI가 Ollama에 접속하는 경로는 다릅니다. 호스트에서 Ollama가 정상이어도 WebUI 컨테이너는 그 서버에 닿지 못할 수 있어요.
이 글은 Docker의 Open WebUI 백엔드가 Ollama에 연결하는 구성을 다룹니다. 확인 순서는 Ollama의 모델 목록 → WebUI 컨테이너에서의 연결 → 관리자 연결 설정 → 사용자별 모델 접근입니다. 화면 이름은 Open WebUI 버전에 따라 조금 달라질 수 있습니다.
이 글의 목차
Ollama에 모델이 있는지 API로 먼저 확인합니다
Ollama를 설치한 호스트에서 다음을 실행합니다. Ollama가 컨테이너에 있고 호스트로 포트를 공개하지 않았다면, 호스트의 127.0.0.1에 API가 없을 수 있습니다. 그 구성에서는 다음 절의 같은 Docker 네트워크 경로로 검사합니다.
ollama list
curl --fail --show-error --connect-timeout 3 --max-time 10 http://127.0.0.1:11434/api/tagsAPI 응답의 models가 빈 배열이면 그 Ollama 서버에는 표시할 모델이 없는 상태입니다. 이미 다운로드한 모델이 있다고 생각했다면 다른 서버나 다른 저장 경로를 보고 있지 않은지 확인하세요. 셸의 OLLAMA_HOST가 원격 서버를 가리키면 ollama list와 위의 로컬 curl이 서로 다른 서버를 조회할 수도 있습니다.
Connection refused는 해당 주소·포트에서 연결을 받지 못했다는 단서입니다. ollama list도 실패하면 WebUI 설정에 앞서 Ollama 서비스부터 확인합니다. 모델 설치와 Linux 서비스 구성은 리눅스에서 Ollama 실행하기에 정리되어 있습니다.
localhost가 어느 컴퓨터인지 맞춰봅니다
| Ollama 위치 | WebUI 백엔드에서 사용할 주소 예시 | 먼저 확인할 조건 |
|---|---|---|
같은 Compose 네트워크의 ollama 서비스 | http://ollama:11434 | 서비스 이름과 공유 네트워크 |
| Docker 호스트에서 직접 실행 | http://host.docker.internal:11434 | 호스트 이름 매핑과 Ollama의 대기 주소 |
| 별도 사설 서버 | http://10.20.30.10:11434 | 실제 서버 IP·라우팅·방화벽 |
| WebUI와 Ollama 모두 같은 호스트에서 직접 실행 | http://127.0.0.1:11434 | 두 프로세스가 같은 네트워크 공간을 사용 |
표의 주소는 구성별 예시입니다. 일반적인 Docker 브리지 네트워크에서 컨테이너의 localhost는 그 컨테이너 자신을 가리킵니다. WebUI 컨테이너 안에 Ollama가 없는데 http://localhost:11434를 넣으면 엉뚱한 곳을 찾게 됩니다. 호스트 네트워크 모드는 동작 조건이 다르므로 구분합니다.
같은 Compose 프로젝트에서 실행한다면 서비스 이름으로 연결하는 구성이 이해하기 편합니다. 다른 프로젝트의 컨테이너라면 같은 사용자 정의 네트워크에 연결되어 있는지도 확인하세요. 두 컨테이너가 같은 서버에 있다는 사실만으로 서비스 이름이 서로 해석되는 것은 아닙니다.
WebUI 컨테이너 안에서 API를 호출합니다
다음 예시는 WebUI 컨테이너 이름이 open-webui, Ollama 서비스 이름이 ollama인 경우입니다. 실제 이름과 주소로 바꿉니다. 컨테이너 안에 별도 curl이 없어도 Python 3 표준 라이브러리로 연결을 확인할 수 있습니다.
docker exec -i open-webui python3 - <<'PY'
import json
import urllib.request
base = "http://ollama:11434"
with urllib.request.urlopen(base + "/api/tags", timeout=5) as response:
data = json.load(response)
print([model["name"] for model in data.get("models", [])])
PY여기서 모델 이름이 출력되면 WebUI 컨테이너에서 그 API까지는 연결됩니다. 이름 해석 오류는 서비스 이름·네트워크를, 연결 거절은 주소·포트·대기 상태를, 시간 초과는 경로·방화벽·서버 상태를 확인할 단서입니다. 하나의 오류 문구가 원인을 완전히 확정하는 것은 아닙니다.
HTTP 401·403이나 로그인 페이지가 돌아온다면 프록시 인증과 접근 정책도 확인합니다. 상태 코드는 성공인데 JSON 해석이 실패하면 Ollama API 대신 다른 웹 페이지에 연결했을 수 있어요. 주소 끝에 WebUI 화면 경로나 불필요한 /api를 붙이지 않았는지 살펴봅니다.
환경 변수와 관리자에 저장된 주소를 함께 확인합니다
관리자 계정에서 설정의 연결 메뉴를 열고 Ollama 연결이 활성화되어 있는지 확인합니다. URL은 앞서 컨테이너 내부에서 성공한 주소와 같아야 합니다. 여러 주소를 등록했다면 사용하지 않는 서버나 응답하지 않는 주소도 정리합니다. 한 연결의 지연이 모델 목록 로딩에 영향을 줄 수 있어요.
Compose에서 주소를 지정한다면 아래처럼 기존 open-webui 서비스의 환경 설정에 병합합니다. 이 코드는 전체 Compose 파일이 아니므로 이미지·볼륨·포트 설정을 지우고 대체하면 안 됩니다.
services:
open-webui:
environment:
OLLAMA_BASE_URL: http://ollama:11434Open WebUI는 관리자 화면에서 저장한 설정을 데이터베이스에 유지할 수 있습니다. 이 경우 환경 변수만 바꾸고 재시작해도 이전 주소가 계속 사용될 수 있어요. 관리자 화면의 실제 저장 주소를 먼저 수정하고, Compose 변경은 docker compose up -d open-webui로 반영합니다. 단순한 docker restart는 기존 컨테이너의 환경 변수를 바꾸지 않습니다.
연결 하나를 고치기 위해 데이터 볼륨이나 전체 설정을 삭제하지 않습니다. 관리자 화면에 접근할 수 없는 경우에는 데이터를 백업한 뒤 공식 연결 오류 문서의 복구 절차를 버전에 맞게 검토합니다. 전체 설정 초기화는 다른 연결과 인증 설정에도 영향을 줄 수 있습니다.
호스트 Ollama에 연결한다면 대기 주소도 봅니다
Linux Docker Engine에서는 host.docker.internal이 자동으로 만들어지지 않는 구성이 있습니다. 그런 경우 WebUI 서비스에 아래 항목을 병합해 호스트 게이트웨이 이름을 지정할 수 있습니다. 이 설정만으로 Ollama의 대기 주소가 바뀌지는 않습니다.
services:
open-webui:
extra_hosts:
- "host.docker.internal:host-gateway"
environment:
OLLAMA_BASE_URL: http://host.docker.internal:11434Ollama가 호스트의 127.0.0.1에서만 대기하면 브리지 네트워크의 컨테이너에서 접근하지 못할 수 있습니다. 호스트에서 ss -lntp로 11434번 포트의 대기 주소를 확인하고, 필요할 때 Ollama 서버의 OLLAMA_HOST 설정을 조정합니다. 방화벽과 허용할 접근 경로도 함께 설정해야 합니다.
Ollama 로컬 API에는 기본적으로 인증이 없습니다. 연결 문제를 해결하려고 11434번 포트를 인터넷 전체에 공개하지 않습니다. 같은 Docker 네트워크 안에서 연결하거나, 필요한 사설 경로만 허용하는 구성을 우선하세요. OLLAMA_ORIGINS는 브라우저의 교차 출처 요청과 관련된 설정이므로 백엔드에서 연결 자체가 안 되는 문제와 구분합니다.
관리자에게만 보인다면 모델 접근 설정을 확인합니다
컨테이너에서 모델 목록을 가져오는데도 일반 사용자에게만 안 보이면 네트워크보다 모델 접근 권한과 공개 범위를 살펴봅니다. 관리자와 일반 사용자 계정에서 같은 연결을 보는지, 모델이 비활성화되거나 특정 그룹으로 제한되어 있지 않은지 확인하세요. 이 단계에서는 모델을 다시 다운로드할 필요가 있는지부터 의심하지 않아도 됩니다.
마지막에는 목록 표시와 짧은 대화 응답을 따로 확인합니다. 목록이 보이는데 답변 생성만 실패하면 모델 적재·메모리·요청 시간 초과를 조사합니다. WebUI 로그의 실패 시각과 Ollama 로그의 같은 시각을 맞춰 보면 어느 구간까지 요청이 갔는지 좁힐 수 있습니다.
docker logs --since 10m --tail 100 open-webui
# Ollama도 컨테이너로 실행한 경우
docker logs --since 10m --tail 100 ollama작성 과정에서는 별도 HTTP 응답 서버를 사용해 컨테이너의 localhost와 공유 네트워크 서비스 이름의 연결 차이를 확인했습니다. 실제 Open WebUI 화면과 모델 생성까지 실행한 검증은 아닙니다. 기본 구성부터 필요하면 Open WebUI와 Ollama 웹 채팅 구성으로 이어서 볼 수 있습니다.
.jpg){kind=link}