Konfiguration

4 Min. Lesezeit

Schnellstart

  1. PgArachne installieren
  2. Umgebung konfigurieren
  3. Sicherheit und Auth konfigurieren
  4. Hinter HTTPS-Proxy bereitstellen

Konfiguration

PgArachne lädt die Konfiguration aus Umgebungsvariablen oder einer Datei.

Note: schema.sql versucht, die Rolle pgarachne_admin zu erstellen und an pgarachne zu vergeben. Ohne Superuser-Rechte wird die Erstellung übersprungen. Rolle und Grant ggf. manuell anlegen.
Der Proxy-User (DB_USER) muss Mitglied von pgarachne und pgarachne_admin sein, um API-Token zu prüfen und zu erstellen.
Sicherheitshinweis: PgArachne verarbeitet keine Datenbankpasswörter in der Konfigurationsdatei. Es verlässt sich auf den Standardmechanismus der .pgpass-Datei von PostgreSQL (oder die systemweite Variable PGPASSWORD) für die Authentifizierung.
Tipp: Wenn PgArachne hinter einem Reverse Proxy läuft, setzen Sie TRUSTED_PROXIES, damit die Client-IP korrekt ermittelt wird und das Rate Limiting nicht spoofbar ist.
Suchreihenfolge: Wenn keine Konfigurationsdatei über CLI angegeben ist, wird wie folgt gesucht:
  1. Aktuelles Verzeichnis: ./pgarachne.env (Alle Betriebssysteme)
  2. Benutzerkonfiguration:
    • Linux/macOS: ~/.config/pgarachne/pgarachne.env
    • Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. Systemkonfiguration: /etc/pgarachne/pgarachne.env (Nur Linux/macOS)

Minimales Konfigurationsbeispiel

Das ist alles, was Sie zum Einstieg benötigen:

DB_HOST=localhost
DB_PORT=5432
DB_USER=pgarachne
# Optional — enables JWT sessions (POST /db//token):
# JWT_SECRET=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Erforderliche Variablen: DB_HOST, DB_PORT, DB_USER.

JWT_SECRET ist optional. Setzen Sie es (mindestens 32 Bytes; erzeugen Sie es mit openssl rand -hex 32), um JWT-Sitzungen über POST /{prefix}/{database}/token sowie extern ausgestellte JWTs zu aktivieren. Ohne es ist die JWT-Unterstützung deaktiviert, und Clients authentifizieren sich mit HTTP-Basic-Zugangsdaten (Datenbank-Benutzername und -Passwort) oder langlebigen API-Token.

Schnelle Validierungs-Checkliste

  • Falls JWT aktiviert ist: JWT_SECRET ist lang, zufällig und wird nicht zwischen Umgebungen geteilt.
  • DB_USER kann nur auf erwartete Rollen wechseln (Role-Membership-Grants prüfen).
  • TRUSTED_PROXIES ist gesetzt, wenn PgArachne hinter einem Reverse Proxy läuft.
  • LOGIN_RATE_LIMIT ist für öffentlich erreichbare Deployments aktiviert.
  • METRICS_LISTEN_ADDR ist nicht öffentlich (z. B. 127.0.0.1:9090).

Konfigurationsreferenz

VariableErforderlichBeschreibung
Datenbank-Verbindung
DB_HOST✓PostgreSQL-Serveradresse (z. B. localhost).
DB_PORT✓Datenbankport.
DB_USER✓Der Datenbankbenutzer, mit dem sich PgArachne verbindet.
DB_SSLMODE○PostgreSQL-SSL-Modus. Standard: require. Setzen Sie disable nur für die lokale Entwicklung gegen ein PostgreSQL ohne TLS explizit.
DB_SSLROOTCERT○Pfad zum CA-Root-Zertifikat (PEM).
DB_SSLCERT○Pfad zum Client-Zertifikat (PEM).
DB_SSLKEY○Pfad zum privaten Client-Schlüssel (PEM).
HTTP-Server
HTTP_PORT○Port, auf dem gelauscht wird. Standard: 8080.
API_PREFIX○Erstes URL-Pfadsegment für alle Datenbank-Endpunkte (/jsonrpc, /file, /sse, /mcp). Standard: db, ergibt Routen wie /db/:datenbank/jsonrpc. Nur Buchstaben, Ziffern, Bindestriche und Unterstriche erlaubt.
PID_FILE○Pfad zur Daemon-PID-Datei für -start/-stop. Standard: User-Cache-Verzeichnis (Fallback: Temp-Verzeichnis).
ALLOWED_ORIGINS○CORS-Einstellungen. Kommagetrennte Liste zulässiger Domains (z. B. https://meineapp.de). Standard: nicht gesetzt — Cross-Origin-Anfragen aus dem Browser sind deaktiviert. Setzen Sie * explizit, um jeden Origin zuzulassen.
STATIC_FILES_PATH○Absoluter Pfad zum Bereitstellen statischer Dateien (Explorer/Frontend).
Sicherheit (JWT & Login)
JWT_SECRET○Eine lange, zufällige Zeichenfolge zum Signieren von Sitzungstoken. Mindestens 32 Bytes; erzeugen Sie es mit openssl rand -hex 32. Ist es nicht gesetzt, ist die JWT-Unterstützung deaktiviert: der Endpunkt /token ist nicht verfügbar, und Clients authentifizieren sich ausschließlich mit HTTP-Basic-Zugangsdaten oder API-Token.
JWT_EXPIRY_HOURS○Gültigkeit der Sitzung in Stunden (muss größer als 0 sein). Standard: 8.
JWT_ISSUER○Falls gesetzt, wird in den iss-Claim geschrieben und muss bei der Validierung exakt übereinstimmen. Leer lassen = keine Prüfung.
JWT_AUDIENCE○Falls gesetzt, wird in den aud-Claim geschrieben und muss bei der Validierung übereinstimmen. Leer lassen = keine Prüfung.
JWT_LEEWAY○Uhr-Toleranz für exp/nbf/iat-Prüfung (z. B. 30s). Standard: 30s.
LOGIN_RATE_LIMIT○Maximale Authentifizierungsversuche pro Client-IP und Benutzername pro Zeitfenster. Gilt für jede Login-Methode: Jede /token-Anfrage zählt, bei HTTP-Basic-Zugangsdaten (auf allen Endpunkten) zählen fehlgeschlagene Versuche. Standard: 5. 0 deaktiviert.
LOGIN_RATE_LIMIT_PER_IP○Maximale Authentifizierungsversuche pro Client-IP über alle Benutzernamen hinweg, sodass wechselnde Benutzernamen das Limit nicht umgehen. Zählt auch fehlgeschlagene Bearer-Versuche (ungültiges JWT oder API-Token). Standard: 5× LOGIN_RATE_LIMIT. 0 deaktiviert.
LOGIN_RATE_WINDOW○Dauer des Zeitfensters. Standard: 1m.
Login-Rate-Limit ist pro Instanz (in-memory). Bei mehreren Instanzen ist ein geteilter Limiter nötig.
TRUSTED_PROXIES○Vertrauenswürdige Proxy-IPs/CIDRs für X-Forwarded-For. Kommagetrennt. Wenn leer, werden Forwarded-Header ignoriert und die Client-IP aus der direkten Verbindung übernommen.
FILE_MAX_BYTES○Maximale unkomprimierte Gesamtgröße einer /file-Antwort in Bytes. Standard: 67108864 (64 MiB).
FILE_MAX_ENTRIES○Maximale Anzahl von Dateien in einer /file-Antwort. Standard: 1000.
MAX_REQUEST_BYTES○Maximale Request-Body-Größe in Bytes. Standard: 2097152.
MCP_SQL_ERROR_DETAIL○Rohe PostgreSQL-Fehlermeldung in MCP-Tool-Fehlern einschließen. Detaillierte Fehler helfen LLM-Agenten bei der Selbstkorrektur, können aber Schemadetails (Tabellen- und Constraint-Namen) an authentifizierte Aufrufer preisgeben. Standard: false.
DIRECT_POOL_LIMIT○Maximale Anzahl unterschiedlicher Verbindungspools für Basic-Auth-Zugangsdaten. Standard: 1000.
METRICS_ENABLED○Dedizierten Metrics-Endpunkt aktivieren. Standard: true.
METRICS_LISTEN_ADDR○Adresse des Metrics-Listeners (host:port). Standard: 127.0.0.1:9090.
SSE_MAX_CHANNELS○Maximale Anzahl von Kanälen pro SSE-Verbindung. Standard: 8.
SSE_MAX_CLIENTS○Maximale Anzahl gleichzeitiger SSE-Clients pro Datenbank. Standard: 1000.
SSE_CLIENT_BUFFER○SSE-Buffer pro Client (Anzahl Nachrichten). Standard: 64.
SSE_SEND_TIMEOUT○Maximale Wartezeit beim Senden an langsame Clients. Standard: 2s.
SSE_HEARTBEAT○Heartbeat-Intervall für SSE-Verbindungen. Standard: 20s.
SSE_IDLE_TIMEOUT○Timeout bei Inaktivität ohne Benachrichtigungen. Standard: 90s.
Logging
LOG_LEVEL○Ausführlichkeit: DEBUG, INFO, WARN, ERROR. Standard: INFO.
LOG_OUTPUT○Wohin Logs geschrieben werden: stdout oder Dateipfad.

Erforderlich   Optional

Sicherheitsverhalten: Requests ohne gültigen Authorization-Header werden abgelehnt, bevor eine Datenbankverbindung geöffnet wird.

Starten Sie den Server:

./pgarachne -config .env

Verwandte Doku

← Installation JSON-RPC →