247 lines
8.5 KiB
Markdown
247 lines
8.5 KiB
Markdown
# 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 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)
|
|
- Admin-Port 8001 über `ADMIN_HOST=127.0.0.1` auf lokalen Zugriff beschränkbar
|
|
|
|
## Konfiguration
|
|
|
|
`.env`-Datei im Projektverzeichnis anlegen:
|
|
|
|
```env
|
|
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
|
|
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 |
|
|
| `ADMIN_HOST` | `0.0.0.0` | Bind-Adresse der Admin-API (z. B. `127.0.0.1` für lokalen Zugriff) |
|
|
| `ALLOWED_ORIGINS` | `http://localhost:5173` | CORS-Origins (nur für Entwicklung relevant) |
|
|
|
|
## Entwicklung (lokal)
|
|
|
|
### Voraussetzungen
|
|
|
|
- Python 3.12+ mit virtualenv
|
|
- Node.js 18+
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r backend/requirements-dev.txt
|
|
cd frontend && npm install
|
|
```
|
|
|
|
### Starten
|
|
|
|
**Per Script:**
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
Zieht das Image von DockerHub, lädt Variablen aus `.env` und verwendet `network_mode: host` — der Container erreicht Ollama direkt über `localhost:11434`. Weitere Compose-Varianten (Ollama als Container, PostgreSQL) siehe `DOCKERHUB.md`.
|
|
|
|
### Image selbst bauen und pushen
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```env
|
|
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):
|
|
|
|
```nginx
|
|
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.
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|