Ollama Proxy mit API-Keys und Quotas
Ein Reverse-Proxy für Ollama mit API-Key-Authentifizierung, Quota-Management und Web-Admin-Oberfläche.
Features
- API-Key-Authentifizierung (Bearer Token oder
sk--Prefix) - Optionales Ablaufdatum pro API-Key
- Quota-Management mit getrennten Tages- und Monatslimits (Tokens & Requests)
- Token-Zählung via tiktoken, Reset-Grenzen in der Zeitzone Europe/Berlin
- Web-Admin-Oberfläche (API-Keys verwalten, Ollama-Einstellungen, Proxy-Info)
- OpenAI-kompatibler
/v1/chat/completions-Endpunkt
Sicherheit
- Admin-Oberfläche passwortgeschützt (
ADMIN_PASSWORD) - Admin-API bindet lokal auf
127.0.0.1(nicht von außen erreichbar) - API-Keys als SHA-256-Hash in der DB — Plaintext nur einmalig bei Erstellung
- Quota-Check atomar mit
SELECT FOR UPDATE(kein TOCTOU-Race) - CORS-Origins konfigurierbar via
ALLOWED_ORIGINS
Konfiguration
.env-Datei im Projektverzeichnis anlegen (Vorlage: .env.example):
ADMIN_PASSWORD=change-me
PROXY_HOST=0.0.0.0
PROXY_PORT=8000
ADMIN_PORT=8001
DATABASE_URL=sqlite:///./test.db
OLLAMA_URL=http://localhost:11434
DEFAULT_MODEL=llama3
APP_TZ=Europe/Berlin
| 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_PORT |
8001 |
Port der Admin-API |
DATABASE_URL |
sqlite:///./test.db |
DB-Verbindungsstring |
OLLAMA_URL |
http://localhost:11434 |
Adresse der Ollama-Instanz (auch in der UI änderbar) |
DEFAULT_MODEL |
llama3 |
Standard-Modell für /v1/chat/completions (auch in der UI änderbar) |
APP_TZ |
Europe/Berlin |
Zeitzone für tägliche/monatliche Quota-Resets |
ALLOWED_ORIGINS |
http://localhost:5173 |
Kommagetrennte CORS-Origins |
Entwicklung (lokal)
cp .env.example .env
# ADMIN_PASSWORD in .env setzen
./start.sh
Das Script prüft alle Ports auf Belegung, aktiviert automatisch eine vorhandene .venv, initialisiert die Datenbank und startet Proxy, Admin-API und Vite-Dev-Server.
Admin-Oberfläche: http://localhost:5173
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
Produktion (Docker)
Image bauen
docker build -t llm-quota .
Container starten
docker run -d \
-p 8000:8000 \
-p 127.0.0.1:8001:8001 \
-e ADMIN_PASSWORD=geheim \
-e OLLAMA_URL=http://host.docker.internal:11434 \
-e DATABASE_URL=sqlite:///./data/quota.db \
-v $(pwd)/data:/app/backend/data \
--name llm-quota \
llm-quota
| Port | Bindung | Dienst |
|---|---|---|
8000 |
0.0.0.0 — öffentlich |
Proxy (für LLM-Clients) |
8001 |
127.0.0.1 — nur lokal am Server |
Admin-API + Admin-Oberfläche |
Docker unterscheidet beim Port-Mapping zwischen 0.0.0.0 (alle Interfaces, öffentlich erreichbar) und 127.0.0.1 (nur der Server selbst kann zugreifen). Mit -p 127.0.0.1:8001:8001 ist Port 8001 am Server verfügbar, aber von außen nicht direkt ansprechbar.
Admin-Oberfläche per SSH-Tunnel erreichbar machen
Der SSH-Tunnel leitet einen lokalen Port auf den Server weiter und nutzt dabei, dass Port 8001 dort auf 127.0.0.1 erreichbar ist:
Admin-Laptop:8001 ──SSH──► Server:127.0.0.1:8001 ──► Container:8001
ssh -L 8001:localhost:8001 user@server
Danach ist die Admin-Oberfläche auf dem Laptop unter http://localhost:8001 erreichbar — ohne dass Port 8001 öffentlich exponiert wird.
Mit PostgreSQL
docker run -d \
-p 8000:8000 \
-p 127.0.0.1:8001:8001 \
-e ADMIN_PASSWORD=geheim \
-e DATABASE_URL=postgresql://user:pass@db-host:5432/llm_quota \
-e OLLAMA_URL=http://ollama:11434 \
llm-quota
Proxy-Endpunkte (Port 8000)
Alle Endpunkte erfordern einen gültigen API-Key im Authorization-Header.
curl -X POST http://localhost:8000/api/chat \
-H "Authorization: Bearer sk-xxxxxx" \
-H "Content-Type: application/json" \
-d '{"model":"llama3","messages":[{"role":"user","content":"Hallo"}]}'
| Endpunkt | Methode | Beschreibung |
|---|---|---|
/api/generate |
POST | Ollama generate |
/api/chat |
POST | Ollama chat |
/api/tags |
GET | Verfügbare Modelle |
/api/versions |
GET | Ollama-Version |
/v1/models |
GET | Modelle (OpenAI-Format) |
/v1/chat/completions |
POST | Chat (OpenAI-Format) |
Admin-API (Port 8001)
Alle Endpunkte erfordern Authorization: Bearer <ADMIN_PASSWORD>.
| Endpunkt | Methode | Beschreibung |
|---|---|---|
/api/api-keys |
GET | Alle API-Keys auflisten |
/api/api-keys |
POST | Neuen API-Key erstellen |
/api/api-keys/{id}/deactivate |
PUT | API-Key deaktivieren |
/api/api-keys/{id}/quota |
PATCH | Quota eines Keys aktualisieren |
/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
│ ├── setup_admin.py # Standard-API-Key erstellen
│ ├── requirements.txt # Produktiv-Dependencies
│ ├── requirements-dev.txt # Test-Dependencies
│ └── tests/
│ ├── conftest.py # Fixtures
│ ├── test_auth.py # Authentifizierungs-Tests
│ └── test_quota.py # Quota-, Token- und Ablauf-Tests
├── frontend/
│ └── src/
│ ├── main.jsx # React-Admin-UI
│ └── styles.css
├── Dockerfile
├── docker-entrypoint.sh
├── .dockerignore
├── .env.example
├── start.sh # Entwicklungs-Startscript
└── .gitignore
Lizenz
MIT