Konfigurationsreferenz
Umgebungsvariablen und Deployment-Modi für selbst gehostetes Noirdoc.
Ueberblick
Noirdoc wird vollstaendig ueber Umgebungsvariablen konfiguriert. Diese Seite deckt alle unterstützten Variablen ab, organisiert nach Deployment-Modus und Funktionsbereich. Als erforderlich gekennzeichnete Variablen muessen gesetzt sein, damit der Proxy startet.
Deployment-Modi
Noirdoc unterstützt zwei Deployment-Modi, gesteuert durch die Variable MODE:
- Standalone (
MODE=standalone) — Single-Tenant-Deployment mit einem statischen Bearer-Token. Keine Benutzerverwaltung, keine JWT-Authentifizierung. Empfohlen für Einzelteam- oder Einzelanwendungs-Deployments. - Cloud (
MODE=cloud) — Multi-Tenant-Deployment mit JWT-Authentifizierung und Admin-Portal. Siehe Managed Service für die Portal-Anleitung.
Beide Modi verwenden denselben Proxy-Kern — PII-Erkennung, Pseudonymisierung, Streaming und Dateiverarbeitung funktionieren unabhaengig vom Modus identisch.
Kern-Einstellungen (alle Modi)
| Variable | Erforderlich | Standard | Beschreibung |
|---|---|---|---|
MODE | Nein | cloud | standalone oder cloud |
DATABASE_URL | Ja | — | PostgreSQL-Verbindungsstring. Beispiel: postgresql+asyncpg://noirdoc:secret@postgres:5432/noirdoc |
REDIS_URL | Ja | — | Redis-Verbindungsstring. Beispiel: redis://redis:6379/0 |
ENCRYPTION_KEY | Ja | — | Fernet-Schluessel zur Verschluesselung von Provider-API-Keys im Ruhezustand. |
Verschluesselungsschluessel generieren
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"Speichern Sie diesen Schluessel sicher. Wenn er verloren geht, werden alle verschluesselten Provider-Keys unwiederbringlich.
Standalone-Modus
Diese Variablen gelten nur bei MODE=standalone.
| Variable | Erforderlich | Standard | Beschreibung |
|---|---|---|---|
STANDALONE_BEARER_TOKEN | Ja | — | Statisches Bearer-Token für die Client-Authentifizierung |
STANDALONE_PROVIDER | Ja | — | LLM-Provider: openai, anthropic, azure_openai, openrouter |
STANDALONE_PROVIDER_KEY | Ja | — | API-Key für den konfigurierten Provider |
STANDALONE_PROVIDER_BASE_URL | Nein | Provider-Standard | Benutzerdefinierte Base-URL (Azure, selbst gehostete Modelle) |
Im Standalone-Modus:
- Es gibt keine Benutzerkonten, kein JWT und kein Portal.
- Clients authentifizieren sich ueber den
Authorization: Bearer <STANDALONE_BEARER_TOKEN>-Header. - Ein einzelner Provider wird ueber Umgebungsvariablen konfiguriert.
- Alle Proxy-Features (Erkennung, Pseudonymisierung, Streaming, Dateiverarbeitung) funktionieren identisch zum Cloud-Modus.
Verwendung mit dem OpenAI SDK
Da Noirdoc ein Drop-in-Proxy ist, der mit dem OpenAI-API-Format kompatibel ist, richten Sie die Base-URL auf Ihre Instanz und verwenden Sie Ihr Standalone-Bearer-Token als API-Key:
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8000/v1",
api_key="ihr-geheimes-token",
)Der gleiche Ansatz funktioniert in Node.js, cURL, LangChain oder jedem anderen OpenAI-kompatiblen Client.
Token-Rotation
Aktualisieren Sie die Umgebungsvariable STANDALONE_BEARER_TOKEN und starten Sie den Proxy neu. Es gibt keine Uebergangsfrist für das alte Token — nach dem Neustart des Proxys wird nur das neue Token akzeptiert.
Cloud-Modus
Diese Variablen gelten nur bei MODE=cloud.
| Variable | Erforderlich | Standard | Beschreibung |
|---|---|---|---|
JWT_SECRET | Nein | Abgeleitet von ENCRYPTION_KEY | Secret für JWT-Tokens. Explizit setzen für Multi-Instanz-Deployments. |
JWT_ACCESS_TOKEN_EXPIRE_MINUTES | Nein | 15 | Lebensdauer des Access-Tokens |
JWT_REFRESH_TOKEN_EXPIRE_DAYS | Nein | 7 | Lebensdauer des Refresh-Tokens |
BOOTSTRAP_ADMIN_EMAIL | Nein | — | Admin-E-Mail, die beim ersten Start erstellt wird |
BOOTSTRAP_ADMIN_PASSWORD | Nein | — | Admin-Passwort. Muss zusammen mit der E-Mail gesetzt werden. |
CORS_ORIGINS | Nein | * | Erlaubte CORS-Origins. In Produktion auf Ihre Frontend-Domain setzen. |
Beim ersten Start erstellt Noirdoc einen Admin-Benutzer aus den Bootstrap-Variablen. Verwenden Sie die Portal API, um danach Tenants und Provider zu verwalten.
PII-Erkennung
| Variable | Erforderlich | Standard | Beschreibung |
|---|---|---|---|
DETECTION_LANGUAGES | Nein | de,en | Komma-separierte Sprachcodes |
DETECTION_SCORE_THRESHOLD | Nein | 0.35 | Konfidenz-Schwellenwert (0-1) |
Pseudonym-Mappings
| Variable | Erforderlich | Standard | Beschreibung |
|---|---|---|---|
DEFAULT_MAPPING_TTL_DAYS | Nein | 30 | Tage, die Zuordnungen bestehen bleiben. 0 = nur für die Dauer der Anfrage. |
Request-Weiterleitung
| Variable | Erforderlich | Standard | Beschreibung |
|---|---|---|---|
FORWARD_TIMEOUT | Nein | 120 | Upstream-Timeout in Sekunden |
Logging
| Variable | Erforderlich | Standard | Beschreibung |
|---|---|---|---|
LOG_LEVEL | Nein | info | debug, info, warning, error |
LOG_FORMAT | Nein | json | json oder text |
Beispielkonfigurationen
Minimales Standalone-Setup
environment:
- MODE=standalone
- DATABASE_URL=postgresql+asyncpg://noirdoc:secret@postgres:5432/noirdoc
- REDIS_URL=redis://redis:6379/0
- ENCRYPTION_KEY=ihr-fernet-schluessel
- STANDALONE_BEARER_TOKEN=mein-geheimes-token
- STANDALONE_PROVIDER=openai
- STANDALONE_PROVIDER_KEY=sk-ihr-openai-keyCloud-Modus mit Bootstrap-Admin
environment:
- MODE=cloud
- DATABASE_URL=postgresql+asyncpg://noirdoc:secret@postgres:5432/noirdoc
- REDIS_URL=redis://redis:6379/0
- ENCRYPTION_KEY=ihr-fernet-schluessel
- JWT_SECRET=ein-separates-jwt-secret
- BOOTSTRAP_ADMIN_EMAIL=admin@ihreFirma.com
- BOOTSTRAP_ADMIN_PASSWORD=sofort-aendern
- CORS_ORIGINS=https://portal.ihreFirma.comSicherheitshinweise
- Committen Sie niemals Secrets in die Versionskontrolle. Verwenden Sie Docker Secrets, eine
.env-Datei, die von Git ausgeschlossen ist, oder einen Secrets-Manager. ENCRYPTION_KEYist das wichtigste Secret — es schützt alle gespeicherten Provider-Keys. Rotieren Sie es nur, wenn Sie zuvor alle gespeicherten Keys neu verschluesselt haben.- Setzen Sie
CORS_ORIGINSin Produktion auf eine spezifische Domain anstelle des Wildcards*. - Verwenden Sie starke, zufaellig generierte Werte für Bearer-Tokens und Passwoerter.