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, Verbrauchsanzeige)
- OpenAI-kompatibler
/v1/chat/completions-Endpunkt mit Streaming und Tool-Use - 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) - Port 8001 kann optional auf
127.0.0.1gebunden werden (zusätzliche Härtung)
Konfiguration
.env-Datei im Projektverzeichnis anlegen:
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
LOG_FILE=logs/usage.log
| 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 (SQLite oder PostgreSQL) |
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 |
LOG_FILE |
logs/usage.log |
Pfad der rotierenden Nutzungs-Logdatei |
ALLOWED_ORIGINS |
http://localhost:5173 |
CORS-Origins (nur für Entwicklung relevant) |
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
Produktion (Docker)
Docker Compose (empfohlen)
docker compose up -d
Zieht das Image von DockerHub, lädt Variablen aus .env und verwendet die lokale SQLite-Datenbank. Weitere Compose-Varianten (PostgreSQL, Ollama als Container) siehe DOCKERHUB.md.
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)
Port 8001 muss exposed werden, da der Container die Admin-Oberfläche auf diesem Port ausliefert. Alle API-Endpunkte erfordern das ADMIN_PASSWORD — der Token ist der primäre Schutz. Optionale zusätzliche Härtung: Bindung auf 127.0.0.1:
ports:
- "127.0.0.1:8001:8001" # nur lokal
# oder:
- "8001:8001" # netzwerkweit, Schutz durch ADMIN_PASSWORD
Proxy-Endpunkte (Port 8000)
Alle Endpunkte erfordern einen gültigen API-Key im Authorization-Header.
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"}]}'
| Endpunkt | Methode | Beschreibung |
|---|---|---|
/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
├── 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
├── run_dev.py # Entwicklungs-Runner für PyCharm
├── build_push.sh # Docker-Build & Push zu DockerHub
├── DOCKERHUB.md # DockerHub-Beschreibung (deutsch)
├── DOCKERHUB.en.md # DockerHub-Beschreibung (englisch)
└── .gitignore
Lizenz
MIT