toolkitbox

~/ / AI 기사 / VPS에서 로컬 LLM / VPS에서 Open WebUI 사용하기: Docker로 실행하고 Ollama에 연결하기

VPS에서 Open WebUI 사용하기: Docker로 실행하고 Ollama에 연결하기

브라우저의 채팅 창은 자신의 서버에서 돌아가는 모델을 가장 쉽게 쓰는 방법입니다. Open WebUI는 그런 인터페이스 중 하나이며, 문서에는 Docker로 실행하는 방법과 Ollama에 연결하는 방법이 나와 있습니다. 이 글은 공식 퀵 스타트와 연결 가이드를 단계별로 따라가며, 두 가이드가 연결을 서로 다르게 설명하는 부분도 함께 짚습니다.

게시: · 읽는 데 약 6분 · 2026-10-26에 Open WebUI 공식 문서와 대조해 확인했습니다. 명령어, 이미지 태그, 설정은 버전에 따라 달라지므로, 서버에서 무엇이든 실행하기 전에 최신 문서에서 확인하세요.

먼저 메모리를 확인하세요

Open WebUI는 같은 서버에서 돌아가는 추가 프로그램이며, 문서에는 이에 필요한 메모리 수치가 나와 있지 않습니다. 퀵 스타트에 따르면 main 태그가 붙은 표준 이미지에는 음성 인식 모델과 임베딩 모델이 함께 들어 있습니다. 먼저 사용할 모델의 메모리를 추정하고, 인터페이스와 운영 체제를 위한 여유를 남겨 두세요.

직접 해 보기: Local LLM Memory Estimator

모델

Ollama 태그 qwen3:8b, 양자화 Q4_K_M, 다운로드 크기 5.2 GB.

추정값

모델 가중치
4.84 GiB
KV 캐시
0.56 GiB
예비분
1.00 GiB
합계
6.41 GiB (6.88 GB)
담을 수 있는 가장 작은 일반 메모리 크기
8 GiB

이 값은 추정입니다. 런타임의 연산 버퍼는 포함하지 않으며, 모든 레이어의 KV 구조가 같다고 가정합니다. 플랜을 정하기 전에 실제로 실행해 측정하세요.

모델 데이터 확인일: 2026-10-26.

출처: Ollama library · 모델 구성 파일 (config.json) · Ollama FAQ

모든 처리는 브라우저 안에서 이루어지며 아무것도 업로드되지 않습니다.

Docker로 실행하기

퀵 스타트는 Open WebUI를 http://localhost:3000 에서 제공하며, docker run 명령 하나로 실행합니다. your-secret-key는 직접 생성한 값으로 바꾸세요. 가이드가 알려 주는 명령어로 만들어도 됩니다.

단계명령어
비밀 키 생성openssl rand -hex 32
Open WebUI 실행docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data -e WEBUI_SECRET_KEY=your-secret-key --name open-webui --restart always ghcr.io/open-webui/open-webui:main
로그 확인docker logs -f open-webui
  • -p 3000:8080은 호스트의 3000번 포트를 컨테이너의 8080번 포트에 연결합니다.
  • open-webui 볼륨에는 채팅, 사용자, 설정이 저장됩니다. 가이드에 따르면 이 볼륨은 업데이트 후에도 유지되며, 볼륨 없이 실행해서는 안 됩니다.
  • WEBUI_SECRET_KEY: 가이드는 한 번 설정하고 계속 유지하라고 합니다. 키가 고정되어 있지 않으면 컨테이너를 다시 만들 때마다 모든 사용자가 로그아웃되고, 새 키로 바꾸면 모두 로그아웃되기 때문입니다.
  • 이미지 태그: main은 표준 이미지이고, cuda는 NVIDIA GPU 지원을 추가하며 --gpus all이 필요하고, ollama는 같은 컨테이너 안에 Ollama를 함께 담고 있습니다.

첫 번째 계정이 관리자입니다

첫 화면에서 관리자 계정을 만들도록 안내합니다. 가이드에 따르면 이 첫 번째 계정이 관리자이며, 사용자와 인스턴스 전체의 모든 설정을 관리하고, 관리자 계정이 만들어지면 회원 가입은 저절로 꺼집니다.

문서에 있는 내용이 아니라 우리의 권장 사항입니다. 누구에게도 주소를 알리기 전에, 컨테이너를 시작하자마자 관리자 계정을 만드세요. 페이지에 가장 먼저 접속한 사람이 만들 수 있기 때문입니다.

Ollama에 연결하기: 문서에 나온 두 가지 방법

우리가 확인한 Open WebUI 페이지들은 연결을 서로 다른 두 가지 방식으로 설명합니다. 사용 중인 버전에 맞는 페이지를 참고하고, 사용 중인 버전이 어떤 유형을 제공하는지는 설정, 관리자, 연결에서 확인하세요.

연결페이지의 설명
Ollama API 프로토콜설정 > 관리자 > 연결에서 Ollama API 연결 관리를 엽니다. 페이지는 일반적인 포트로 11434를 제시하며, Open WebUI가 Docker에서 실행되고 Ollama가 호스트에서 실행될 때는 http://host.docker.internal:11434 를 사용하라고 합니다.
OpenAI 유형 연결유형이 OpenAI인 연결을 추가하고, Base URL은 http://localhost:11434/v1 로, API 키는 아무 텍스트로 지정합니다. 페이지에 따르면 Ollama는 키를 검사하지 않지만 필드를 비워 둘 수는 없으며, ollama라고 입력해도 됩니다.
  • 받아 둔(pull한) 모델은 자동으로 검색되어 모델 선택 창에 나타납니다. 쉼표로 구분한 목록으로 표시할 모델을 제한할 수도 있습니다.
  • Ollama 인스턴스를 여러 개 추가할 수 있습니다. 페이지에 따르면 요청은 무작위로 선택되어 분산되고, 모델 ID는 인스턴스 간에 정확히 일치해야 하며, 모델 이름이 같은 인스턴스는 remote/ 같은 접두사로 구분합니다.
  • 응답이 느리거나 접속할 수 없는 엔드포인트에 대해서는, 더 빠른 장애 조치(failover)를 위해 AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=3 으로 설정하라고 페이지가 제안합니다(기본값은 10초).
  • 연결에 실패하면, 페이지는 네트워크 설정 오류를 가장 흔한 원인으로 꼽고 문제 해결 가이드를 안내합니다.

우리가 확인한 페이지들에는 127.0.0.1에서만 수신 대기하는 Ollama에 컨테이너가 접속할 수 있는지가 나와 있지 않으며, Ollama의 주소를 넓히는 방법도 다루지 않습니다. Ollama의 FAQ에 따르면 Ollama는 기본적으로 127.0.0.1에 바인딩됩니다. 우리의 권장 사항: 사용하는 주소로만 제한하는 방화벽 규칙 없이 Ollama를 네트워크 전체에 열어 두지 마세요.

업데이트와 삭제

작업퀵 스타트의 명령어
수동으로 업데이트docker rm -f open-webui, 그다음 docker pull ghcr.io/open-webui/open-webui:main, 그다음 이전과 같은 docker run 명령
Watchtower로 업데이트docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock nickfedor/watchtower --run-once open-webui
삭제docker rm -f open-webui, 그다음 docker rmi ghcr.io/open-webui/open-webui:main, 그다음 docker volume rm open-webui

볼륨을 삭제하면 채팅, 사용자, 설정이 지워집니다. 가이드에 따르면 데이터는 볼륨에 있으므로, 업데이트할 때는 볼륨을 그대로 두세요.

비공개로 유지하기

  • 퀵 스타트에는 WEBUI_AUTH=False를 사용하는 변형이 나와 있습니다. 문서에 있는 내용이 아니라 우리의 권장 사항입니다. 누구나 접속할 수 있는 서버에서는 사용하지 마세요.
  • 주소를 공유하기 전에 3000번 포트 앞에 HTTPS와 방화벽 규칙을 두고, 비밀 키가 커밋하는 어떤 파일에도 들어가지 않게 하세요.
  • 퀵 스타트에는 OLLAMA_BASE_URL로 Open WebUI가 다른 서버를 가리키게 하는 방법도 나와 있습니다. 그렇게 한다면 그 연결도 비공개 네트워크의 일부로 취급하세요.

출처

다음에 읽기