English | 简体中文 | 繁體中文 | Русский
GatewayCrate
오픈 소스, 자체 호스팅형 AI 게이트웨이.
Build Status Docker Pulls License: MIT
GatewayCrate를 통해 애플리케이션을 구성된 클라우드 및 로컬 모델 제공업체에 연결하세요. LiteLLM의 지원을 받아 공통 OpenAI 호환 API, 자동 모델 설정, 관리 도구를 제공합니다. 포함된 PostgreSQL 설정은 관리자 UI, 가상 키, 지출 추적 기능을 활성화합니다.
이전에 docker-litellm으로 알려졌으며 hwdsl2가 유지보수하고 있습니다. Docker 이미지 이름은 hwdsl2/litellm-server로 유지됩니다.
주요 기능:
- 기본적으로 보안 강화 (Secure by default): 최초 시작 시 마스터 API 키를 자동으로 생성하며, 모든 API 요청에는 이 키가 필요합니다.
- OpenAI 호환 API: OpenAI SDK 및 앱을 프록시에 연결할 수 있습니다. 지원되는 엔드포인트와 필드는 LiteLLM, 선택된 제공업체, 모델 기능에 따라 달라집니다.
- 제공업체 선택 (Provider choice): OpenAI, Anthropic, Groq, Gemini, Ollama 및 100개 이상의 다른 제공업체를 지원합니다.
- 자동 모델 설정: 환경 파일에 설정된 제공업체 API 키에 대한 모델을 추가합니다.
- 관리자 UI 및 사용량 추적:
docker-compose.yml에는 관리자 UI, 가상 키 관리, 지출 추적을 위한 PostgreSQL이 포함됩니다.
- 모델 관리: 헬퍼 스크립트(
litellm_manage)를 통해 가능합니다.
- 자동 빌드: 이미지는 GitHub Actions을 통해 자동으로 빌드 및 게시됩니다.
또한, 단일 명령으로 전체 자체 호스팅 AI 스택을 배포하는 Self-Hosted AI Stack의 일부로도 사용할 수 있습니다.
📘 The Self-Hosted AI Builder’s Guide는 자체 프라이빗 AI 스택을 구축, 보안 및 운영하기 위한 실용적인 가이드입니다.
추가 이용 가능 서비스:
빠른 시작 (Quick start)
1단계. GatewayCrate 시작하기:
docker run \
--name litellm \
--restart=always \
...
최초 실행 시, 서버는 자동으로 마스터 API 키를 생성하고 설정을 만듭니다. 이 마스터 키는 컨테이너 로그에 출력됩니다.
[!NOTE]
인터넷에 노출되는 배포 환경에서는 HTTPS를 추가하기 위해 리버스 프록시를 사용하세요. 또한, docker run 명령어에서 -p 4000:4000/tcp 대신 -p 127.0.0.1:4000:4000/tcp로 변경하여 암호화되지 않은 포트로의 직접 접근을 방지하세요.
2단계. 컨테이너 로그를 확인하여 마스터 키 가져오기:
마스터 키는 GatewayCrate master key라고 표시된 상자에 나타납니다. 이 키를 복사하세요. 모든 API 요청에 인증하는 데 사용하게 됩니다.
참고: 마스터 키는 최초 실행 설정 시에만 출력됩니다. 언제든지 다시 표시하려면 다음을 실행하세요:
docker exec litellm litellm_manage --showkey
3단계. OpenAI와 호환되는 요청으로 프록시 테스트하기:
아래의 채팅 완료 명령어는 먼저 모델이 구성되어야 합니다. 모델 관리를 참조하세요.
curl http://localhost:4000/v1/models \
-H
- 💬 토론 및 소개를 위해 [r/selfhostedstack](https://www.reddit.com/r/selfhostedstack/) 커뮤니티에 참여하세요.
- ⭐ 유용하다고 생각되면 레포지토리에 별점을 주어주세요. 다른 사람들이 발견하는 데 도움이 됩니다.
<details>
<summary>자체 호스팅 VPN 및 네트워킹 프로젝트</summary>
- [IPsec VPN 설정](https://github.com/hwdsl2/setup-ipsec-vpn)
- [Docker용 IPsec VPN](https://github.com/hwdsl2/docker-ipsec-vpn-server)
- [WireGuard](https://github.com/hwdsl2/docker-wireguard)
- [OpenVPN](https://github.com/hwdsl2/docker-openvpn)
- [Headscale](https://github.com/hwdsl2/docker-headscale)
</details>
- Docker가 설치된 Linux 서버 (로컬 또는 클라우드)
- 최소 하나의 LLM 제공업체 API 키 (OpenAI, Anthropic, Groq 등) **또는** [InferCrate](https://github.com/hwdsl2/infercrate)와 같은 로컬 실행 Ollama 서버
- TCP 포트 4000 (또는 구성한 포트)가 열려 있고 접근 가능해야 함
프록시를 시작하는 데 LLM 제공업체 키는 필요하지 않습니다. 빈 모델 목록으로도 서버가 성공적으로 시작됩니다. `litellm_manage`를 사용하여 언제든지 모델을 추가할 수 있습니다.
인터넷에 노출되는 배포의 경우, [리버스 프록시 사용하기](#using-a-reverse-proxy)를 참조하여 HTTPS를 추가하세요.
[Docker Hub 레지스트리](https://hub.docker.com/r/hwdsl2/litellm-server/)에서 신뢰할 수 있는 빌드를 받으세요:
```bash
docker pull hwdsl2/litellm-server
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
대안으로, Quay.io에서 다운로드할 수 있습니다:
docker pull quay.io/hwdsl2/litellm-server
docker image tag quay.io/hwdsl2/litellm-server hwdsl2/litellm-server
지원되는 플랫폼: linux/amd64 및 linux/arm64.
환경 변수 (Environment variables)
모든 변수는 선택 사항입니다. LITELLM_MASTER_KEY가 설정되지 않은 경우, 첫 시작 시 마스터 API 키가 자동 생성됩니다.
이 Docker 이미지는 다음 변수를 사용하며, 이는 env 파일에 선언할 수 있습니다 (예시: litellm.env.example).
| 변수 | 설명 | 기본값 |
|---|
LITELLM_MASTER_KEY | 프록시용 마스터 API 키 | 자동 생성 |
| ... | | |
참고: env 파일에서 값을 작은따옴표로 묶을 수 있습니다. 예: VAR='value'. = 주변에 공백을 추가하지 마세요. LITELLM_PORT를 변경하면 docker run 명령어의 -p 플래그도 그에 맞게 업데이트해야 합니다. | | |
env 파일을 사용하는 예시:
cp litellm.env.example litellm.env
docker run \
...
이 env 파일은 컨테이너 내부로 바인드 마운트(bind-mounted)되므로, 컨테이너를 다시 생성하지 않아도 재시작 시 변경 사항이 적용됩니다.
모델 관리 (Model management)
litellm_manage 헬퍼 스크립트를 사용하여 docker exec으로 모델을 관리하세요. 모델은 Docker 볼륨 내부의 config.yaml에 저장되며 컨테이너 재시작에도 유지됩니다.
[!NOTE]
--addmodel과 --removemodel은 config.yaml에 쓰기 작업을 수행하며, 변경 사항 적용을 위해 프록시를 자동으로 재시작합니다.
LITELLM_OLLAMA_BASE_URL이 설정되면, 컨테이너는 하위 호환성을 위한 기본 Ollama 별칭인 ollama/llama3.2:3b와 채팅 네이티브(chat-native) Ollama 동작을 위한 ollama-chat/llama3.2:3b 두 가지를 모두 config.yaml에 유지합니다. 스트리밍 도구 호출에는 ollama-chat/... 별칭을 사용하세요.
설정된 모델 목록 보기:
docker exec litellm litellm_manage --listmodels
API 키로 모델 추가하기:
docker exec litellm litellm_manage --addmodel openai/gpt-4o --key sk-...
...
로컬 Ollama 모델 추가하기:
docker exec litellm litellm_manage \
--addmodel ollama/llama3.2:3b \
...
네이티브 채팅 동작이나 스트리밍 도구 호출이 필요한 Ollama 모델의 경우, ollama-chat/llama3.2:3b와 같은 사용자 대상 별칭(user-facing alias)을 사용하여 ollama_chat/... 프로바이더 모델을 사용하세요.
모델 제거하기 (--listmodels에서 얻은 id 사용):
docker exec litellm litellm_manage --removemodel <model_id>
마스터 키 보기 (조회가 필요한 경우):
UplinkCrate 통합
litellm.env 파일에 LITELLM_MCP_URL을 설정하여 GatewayCrate를 UplinkCrate와 같은 호환 가능한 MCP HTTP 엔드포인트에 연결할 수 있습니다. 엔드포인트가 Bearer 인증을 요구하는 경우 LITELLM_MCP_API_KEY도 설정하세요. 그러면 AI 클라이언트가 LiteLLM 프록시를 통해 MCP 도어를 호출할 수 있게 됩니다.
LITELLM_MCP_URL이 설정되면, 컨테이너가 시작될 때마다 config.yaml에 mcp_servers: 블록이 주입됩니다. 따라서 수동으로 YAML을 편집할 필요가 없습니다.
예시: UplinkCrate 연결:
LITELLM_MCP_URL=http://mcp:3000/mcp
LITELLM_MCP_API_KEY=mcp-xxxx...
이 값들을 설정한 후, 컨테이너를 재시작하세요:
docker compose restart litellm
litellm_manage로 MCP 서버 관리:
docker exec litellm litellm_manage --listmcp
...
[!NOTE]
--addmcp와 --removemcp는 config.yaml에 쓰기 작업을 수행하며 프록시를 자동으로 재시작합니다. LITELLM_MCP_URL을 통해 추가된 MCP 서버는 설정에서 docker_mcp_gateway라는 이름으로 지정되며, --removemcp docker_mcp_gateway로 관리할 수 있습니다.
가상 키(Virtual key) 관리
가상 키는 사용자나 애플리케이션에 발급할 수 있는 범위 제한형 API 키입니다. 각 키는 선택적으로 접근 가능한 모델을 제한하고, 최대 지출 예산(maximum spend budget)을 설정하며, 만료일을 지정할 수 있습니다. 가상 키를 사용하려면 PostgreSQL 데이터베이스가 필요하며, 이는 기본 docker-compose.yml에 포함되어 있습니다.
가상 키 생성:
docker exec litellm litellm_manage --createkey
...
모든 가상 키 목록 보기:
docker exec litellm litellm_manage --listkeys
가상 키 삭제:
docker exec litellm litellm_manage --deletekey sk-...
OpenAI SDK와 프록시 사용하기
OpenAI SDK를 사용하는 앱을 프록시에 연결하려면 두 가지 환경 변수를 설정하세요:
Python용:
from openai import OpenAI
client = OpenAI(
...
이 프록시는 OpenAI API 형식을 지원하는 모든 도구나 라이브러리와 호환됩니다.
영속적인 데이터 (Persistent data)
모든 프록시 데이터는 Docker 볼륨(/etc/litellm 컨테이너 내부)에 저장됩니다:
/etc/litellm/
├── config.yaml # 프록시 구성 및 모델 목록 (한 번 생성되며 재시작 시에도 유지됨)
├── .master_key # 마스터 API 키 (자동 생성되거나 LITELLM_MASTER_KEY에서 동기화됨)
...
마스터 키와 구성된 모델을 보존하려면 Docker 볼륨을 백업하세요.
docker-compose 사용하기
cp litellm.env.example litellm.env
docker compose up -d
...
새로 설치하는 Compose는 무작위 PostgreSQL 비밀번호를 자동으로 생성하고 litellm-secrets 볼륨에 저장합니다. 기존의 기본 설치는 호환성을 위해 레거시 litellm 데이터베이스 비밀번호를 계속 사용합니다. 이전에 데이터베이스 비밀번호를 사용자 정의했다면, docker compose up -d를 실행하기 전에 셸 환경에서 LITELLM_POSTGRES_PASSWORD에 해당 비밀번호를 설정하거나, litellm.env에 명시적인 LITELLM_DATABASE_URL 재정의 값을 유지하세요.
기존 체크아웃을 업그레이드할 때는 LiteLLM 이미지가 LITELLM_POSTGRES_PASSWORD_FILE을 지원하도록 docker compose up -d 전에 docker compose pull을 실행하세요.
예시 docker-compose.yml (이미 포함됨):
services:
litellm-init:
image: alpine:3.24
...
[!NOTE]
인터넷에 노출되는 배포의 경우, HTTPS를 추가하기 위해 리버스 프록시를 사용하세요. 또한 docker-compose.yml에서 `
인터넷에 노출되는 배포 환경의 경우, HTTPS 종료(termination)를 처리하기 위해 LiteLLM 앞에 리버스 프록시(reverse proxy)를 배치해야 합니다. 이 서버는 로컬 또는 신뢰할 수 있는 네트워크에서는 HTTPS 없이도 작동하지만, API 엔드포인트가 인터넷에 노출될 때는 HTTPS 사용을 권장합니다.
리버스 프록시에서 LiteLLM 컨테이너에 접근하려면 다음 주소 중 하나를 사용하십시오:
litellm:4000 — 리버스 프록시가 LiteLLM과 동일한 Docker 네트워크 내의 컨테이너로 실행되는 경우 (예: 동일한 docker-compose.yml에 정의된 경우).127.0.0.1:4000 — 리버스 프록시가 **호스트(host)**에서 실행되고 포트 4000이 게시되는 경우 (기본 docker-compose.yml은 이를 게시합니다).
Caddy (Docker 이미지)를 사용한 예시 (Let's Encrypt를 통한 자동 TLS, 동일 Docker 네트워크 내 리버스 프록시):
