Ollama Proxy mit API-Keys und Quotas
Ollama bietet von sich aus keine Authentifizierung — wer die API erreicht, kann sie nutzen. Dieses Projekt löst das Problem: Ollama bleibt an localhost gebunden und ist von außen nicht erreichbar. Vorgeschaltet läuft ein Proxy (Port 8000), der jeden Request auf einen gültigen API-Key prüft und optional Token- sowie Request-Quoten pro Key durchsetzt. Eine Web-Admin-Oberfläche (Port 8001) erlaubt das Verwalten von Keys, Quoten und Ollama-Einstellungen.
Features
- API-Key-Authentifizierung (Bearer Token,
sk--Prefix,x-api-key- undanthropic-auth-token-Header) - Optionales Ablaufdatum pro API-Key
- Quota-Management mit getrennten Tages- und Monatslimits (Tokens & Requests)
- Token-Zählung via tiktoken, Reset-Grenzen in der konfigurierten Zeitzone
- Web-Admin-Oberfläche (API-Keys verwalten, Ollama-Einstellungen, Verbrauchsanzeige)
- OpenAI-kompatibler
/v1/chat/completions-Endpunkt mit Streaming und Tool-Use - Anthropic Messages API
/v1/messages— kompatibel mit Claude Code CLI und Anthropic-SDK-Clients - Rotierende Nutzungs-Logs
- SQLite (Standard) oder PostgreSQL
- Docker-Image auf DockerHub:
mediaeng/llmproxy
Sicherheit
- Admin-Oberfläche passwortgeschützt (
ADMIN_PASSWORD) — alle API-Endpunkte erfordern den Token - API-Keys als SHA-256-Hash in der DB — Plaintext nur einmalig bei Erstellung
- Quota-Check atomar mit
SELECT FOR UPDATE(kein TOCTOU-Race) - Admin-Port 8001 über
ADMIN_HOST=127.0.0.1auf lokalen Zugriff beschränkbar
Konfiguration
.env-Datei im Projektverzeichnis anlegen:
ADMIN_PASSWORD=change-me
PROXY_HOST=0.0.0.0
PROXY_PORT=8000
ADMIN_HOST=0.0.0.0
ADMIN_PORT=8001
DATABASE_URL=sqlite:///./test.db
OLLAMA_URL=http://localhost:11434
APP_TZ=Europe/Berlin
LOG_FILE=logs/usage.log
ANTHROPIC_DEFAULT_MODEL=llama3
| Variable | Standard | Beschreibung |
|---|---|---|
ADMIN_PASSWORD |
— | Passwort für die Admin-Oberfläche (Pflicht) |
PROXY_HOST |
0.0.0.0 |
Bind-Adresse des Proxys |
PROXY_PORT |
8000 |
Port des Proxys |
ADMIN_HOST |
0.0.0.0 |
Bind-Adresse der Admin-API (z. B. 127.0.0.1 für lokalen Zugriff) |
ADMIN_PORT |
8001 |
Port der Admin-API |
DATABASE_URL |
sqlite:///./test.db |
DB-Verbindungsstring (SQLite oder PostgreSQL) |
OLLAMA_URL |
http://localhost:11434 |
Adresse der Ollama-Instanz (auch in der UI änderbar) |
APP_TZ |
Europe/Berlin |
Zeitzone für tägliche/monatliche Quota-Resets |
LOG_FILE |
logs/usage.log |
Pfad der rotierenden Nutzungs-Logdatei |
ALLOWED_ORIGINS |
http://localhost:5173 |
CORS-Origins (nur für Entwicklung relevant) |
ANTHROPIC_DEFAULT_MODEL |
— | Standard-Modell für /v1/messages (Ollama-Modellname) |
Entwicklung (lokal)
Voraussetzungen
- Python 3.12+ mit virtualenv
- Node.js 18+
python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements-dev.txt
cd frontend && npm install
Starten
Per Script:
cp .env.example .env # ADMIN_PASSWORD setzen
./start.sh
Per PyCharm: Run-Config „Dev" starten (startet Proxy, Admin-API und Vite-Dev-Server gemeinsam).
Das Script prüft alle Ports auf Belegung, initialisiert die Datenbank und startet alle drei Dienste.
Admin-Oberfläche: http://localhost:5173
Claude Code CLI
Der Proxy stellt einen Anthropic-kompatiblen Endpunkt bereit, über den Claude Code CLI mit lokalen Ollama-Modellen genutzt werden kann.
# ANTHROPIC_DEFAULT_MODEL in .env setzen, dann:
./start_claude.sh
# Oder mit Key als Argument:
./start_claude.sh sk-dein-api-key
# Oder als Umgebungsvariable:
PROXY_API_KEY=sk-dein-api-key ./start_claude.sh
Das Script setzt ANTHROPIC_BASE_URL und ANTHROPIC_AUTH_TOKEN automatisch aus der .env und startet claude.
Produktion (Docker)
Docker Compose (empfohlen)
docker compose up -d
Zieht das Image von DockerHub und lädt Variablen aus .env.
Das Setup verwendet network_mode: host: Der Container teilt den Netzwerkstack des Hosts, statt ein eigenes virtuelles Netzwerk zu bekommen. Das ist hier aus zwei Gründen die richtige Wahl:
-
Ollama soll nicht von außen erreichbar sein. Ollama läuft auf dem Host und ist an
127.0.0.1:11434gebunden — nur lokal erreichbar. Mit einem eigenen Container-Netzwerk (Bridge-Mode) wärelocalhostaus Sicht des Containers der Container selbst, nicht der Host. Die übliche Alternative (host.docker.internal+extra_hosts) ist auf Linux unzuverlässig. -
Kein doppeltes Port-Mapping nötig. Mit
network_mode: hostsind Port 8000 und 8001 direkt auf dem Host verfügbar, ohneports:-Einträge in der Compose-Datei.
Image selbst bauen und pushen
./build_push.sh
Das Script zeigt den aktuellen Git-Tag, bietet an einen neuen zu setzen, baut das Image für linux/arm64 und pusht zu mediaeng/llmproxy.
Port 8001 (Admin)
Alle Admin-Endpunkte erfordern das ADMIN_PASSWORD — der Token ist der primäre Schutz. Für zusätzliche Härtung lässt sich die Admin-API auf lokalen Zugriff beschränken:
ADMIN_HOST=127.0.0.1
Bei network_mode: host (Produktions-Standard) ist das die einzig wirksame Methode — Docker-Port-Mapping greift dort nicht.
HTTPS via Reverse-Proxy (ungetestet)
Wer Proxy und Admin-Oberfläche per HTTPS bereitstellen will, kann einen weiteren Reverse-Proxy (z. B. Nginx oder Caddy) vorschalten. Bei network_mode: host lauschen beide Dienste direkt auf dem Host, Nginx/Caddy proxyen auf localhost.
Caddy (empfohlen — automatisches TLS via Let's Encrypt):
llm.example.com {
reverse_proxy localhost:8000 {
flush_interval -1
}
}
llm-admin.example.com {
reverse_proxy localhost:8001
}
Nginx (mit Certbot-Zertifikaten):
server {
listen 443 ssl;
server_name llm.example.com;
ssl_certificate /etc/letsencrypt/live/llm.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/llm.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_buffering off; # nötig für Streaming
proxy_cache off;
}
}
server {
listen 443 ssl;
server_name llm-admin.example.com;
ssl_certificate /etc/letsencrypt/live/llm-admin.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/llm-admin.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8001;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
Clients konfigurieren dann https://llm.example.com/v1 als Base URL.
Proxy-Endpunkte (Port 8000)
Alle Endpunkte erfordern einen gültigen API-Key im Authorization-Header (Bearer sk-...), im x-api-key-Header oder im anthropic-auth-token-Header.
# OpenAI-kompatibler Endpunkt
curl -X POST http://localhost:8000/v1/chat/completions \
-H "Authorization: Bearer sk-xxxxxx" \
-H "Content-Type: application/json" \
-d '{"model":"llama3","messages":[{"role":"user","content":"Hallo"}]}'
# Anthropic-kompatibler Endpunkt (z. B. für Claude Code)
curl -X POST http://localhost:8000/v1/messages \
-H "x-api-key: sk-xxxxxx" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{"model":"llama3","messages":[{"role":"user","content":"Hallo"}],"max_tokens":1024}'
| Endpunkt | Methode | Beschreibung |
|---|---|---|
/v1/messages |
POST | Chat (Anthropic-Format, Streaming + Tool-Use) |
/v1/chat/completions |
POST | Chat (OpenAI-Format, Streaming + Tool-Use) |
/v1/models |
GET | Modelle (OpenAI-Format) |
/api/generate |
POST | Ollama generate (nativ) |
/api/chat |
POST | Ollama chat (nativ) |
/api/tags |
GET | Verfügbare Modelle |
/api/versions |
GET | Ollama-Version |
Admin-API (Port 8001)
Alle Endpunkte erfordern Authorization: Bearer <ADMIN_PASSWORD>.
| Endpunkt | Methode | Beschreibung |
|---|---|---|
/api/api-keys |
GET | Alle API-Keys mit Verbrauchsdaten |
/api/api-keys |
POST | Neuen API-Key erstellen |
/api/api-keys/{id}/quota |
PATCH | Limits eines Keys aktualisieren |
/api/api-keys/{id}/activate |
PUT | API-Key aktivieren |
/api/api-keys/{id}/deactivate |
PUT | API-Key deaktivieren |
/api/api-keys/{id} |
DELETE | API-Key löschen |
/api/settings |
GET/PUT | Ollama-URL und Standard-Modell |
/api/ollama-models |
GET | Verfügbare Modelle von Ollama |
/api/proxy-info |
GET | Lokaler Proxy-Endpunkt |
Tests
cd backend
python -m pytest tests/ -v
Projektstruktur
llm_quota/
├── backend/
│ ├── main.py # Proxy-Server (Port 8000)
│ ├── admin.py # Admin-API + Static-File-Serving (Port 8001)
│ ├── database.py # DB-Verbindung & Session
│ ├── models.py # SQLAlchemy-Modelle (APIKey, Setting, Usage)
│ ├── schemas.py # Pydantic-Schemas
│ ├── crud.py # DB-Operationen, Token-Zählung, Quota-Logik
│ ├── init_db.py # Tabellen anlegen & Settings seeden
│ ├── requirements.txt # Produktiv-Dependencies
│ ├── requirements-dev.txt # Test-Dependencies
│ └── tests/
│ ├── conftest.py
│ ├── test_auth.py
│ ├── test_quota.py
│ └── test_anthropic_messages.py
├── frontend/
│ └── src/
│ ├── main.jsx # React-Admin-UI
│ └── styles.css
├── .idea/runConfigurations/
│ └── Dev.xml # PyCharm Run-Config
├── Dockerfile
├── docker-compose.yml # Produktiv-Start mit DockerHub-Image
├── docker-entrypoint.sh
├── .dockerignore
├── start.sh # Entwicklungs-Startscript
├── start_claude.sh # Claude Code CLI mit Proxy starten
├── run_dev.py # Entwicklungs-Runner für PyCharm
├── build_push.sh # Docker-Build & Push zu DockerHub
├── LICENSE
├── DOCKERHUB.md # DockerHub-Beschreibung (deutsch)
├── DOCKERHUB.en.md # DockerHub-Beschreibung (englisch)
└── .gitignore
Danksagung
Der Anthropic-kompatible Endpunkt (/v1/messages) wurde durch das Projekt free-claude-code von Ali Khokhar inspiriert, das einen ähnlichen Ansatz für das Weiterleiten von Claude-Code-Anfragen an alternative LLM-Backends verfolgt.
Lizenz
MIT — siehe LICENSE