Ρύθμιση

4 λεπτά ανάγνωσης

Γρήγορη έναρξη

  1. Εγκαταστήστε το PgArachne
  2. Διαμορφώστε το περιβάλλον
  3. Ρυθμίστε ασφάλεια και έλεγχο ταυτότητας
  4. Αναπτύξτε πίσω από HTTPS proxy

Ρύθμιση

Το PgArachne φορτώνει τη ρύθμιση από μεταβλητές περιβάλλοντος ή από αρχείο.

Σημείωση: Το schema.sql προσπαθεί να δημιουργήσει τον ρόλο pgarachne_admin και να τον χορηγήσει στον pgarachne. Αν εκτελέσετε το script χωρίς δικαιώματα superuser, η δημιουργία ρόλου παραλείπεται. Δημιουργήστε τον ρόλο και χορηγήστε τον χειροκίνητα εάν χρειάζεται.
Ο proxy χρήστης (DB_USER) πρέπει να είναι μέλος των pgarachne και pgarachne_admin για να επικυρώνει και να εκδίδει API tokens.
Σημείωση Ασφαλείας: Το PgArachne δεν διαχειρίζεται κωδικούς πρόσβασης βάσης δεδομένων στο αρχείο ρύθμισης. Βασίζεται στον τυπικό μηχανισμό αρχείου .pgpass της PostgreSQL (ή στη μεταβλητή συστήματος PGPASSWORD) για authentication.
Συμβουλή: Εάν εκτελείτε το PgArachne πίσω από reverse proxy, ορίστε TRUSTED_PROXIES ώστε οι IP των clients να επιλύονται σωστά και το rate limiting να μην μπορεί να παρακαμφθεί.
Σειρά Αναζήτησης: Αν δεν έχει καθοριστεί αρχείο ρύθμισης μέσω CLI, γίνεται αναζήτηση σε:
  1. Τρέχων κατάλογος: ./pgarachne.env (Όλα τα OS)
  2. Ρύθμιση χρήστη:
    • Linux/macOS: ~/.config/pgarachne/pgarachne.env
    • Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. Ρύθμιση συστήματος: /etc/pgarachne/pgarachne.env (μόνο Linux/macOS)

Παράδειγμα Ελάχιστης Ρύθμισης

Αυτό είναι το μόνο που χρειάζεστε για να ξεκινήσετε:

DB_HOST=localhost
DB_PORT=5432
DB_USER=pgarachne
JWT_SECRET=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Απαιτούμενες μεταβλητές: DB_HOST, DB_PORT, DB_USER, JWT_SECRET (ελάχιστο 32 bytes· δημιουργήστε με openssl rand -hex 32).

Λίστα Ελέγχου Ταχείας Επικύρωσης

  • Το JWT_SECRET είναι μεγάλο, τυχαίο, και δεν επαναχρησιμοποιείται σε διαφορετικά περιβάλλοντα.
  • Ο DB_USER μπορεί να μεταβεί μόνο στους αναμενόμενους ρόλους (επιβεβαιώστε τα role membership grants).
  • Το TRUSTED_PROXIES έχει ρυθμιστεί όταν εκτελείται πίσω από reverse proxy.
  • Το LOGIN_RATE_LIMIT είναι ενεργοποιημένο για deployments προσβάσιμα από το διαδίκτυο.
  • Το METRICS_LISTEN_ADDR είναι ιδιωτικό (για παράδειγμα 127.0.0.1:9090).

Αναφορά Ρύθμισης

ΜεταβλητήΑπαιτείταιΠεριγραφή
Σύνδεση με τη Βάση Δεδομένων
DB_HOST✓Διεύθυνση του server PostgreSQL (π.χ. localhost).
DB_PORT✓Θύρα της βάσης δεδομένων.
DB_USER✓Ο χρήστης βάσης δεδομένων με τον οποίο συνδέεται το PgArachne.
DB_SSLMODE○Λειτουργία SSL της PostgreSQL. Προεπιλογή: require. Ορίστε ρητά disable μόνο για τοπική ανάπτυξη έναντι PostgreSQL χωρίς TLS.
DB_SSLROOTCERT○Διαδρομή προς το CA root certificate (PEM).
DB_SSLCERT○Διαδρομή προς το client certificate (PEM).
DB_SSLKEY○Διαδρομή προς το ιδιωτικό κλειδί client (PEM).
HTTP Server
HTTP_PORT○Θύρα ακρόασης. Προεπιλογή: 8080.
API_PREFIX○Πρώτο τμήμα διαδρομής URL για όλα τα endpoints βάσης δεδομένων (/jsonrpc, /sse, /mcp). Προεπιλογή: db, δίνοντας διαδρομές όπως /db/:database/jsonrpc. Επιτρέπονται μόνο γράμματα, ψηφία, ενωτικά και κάτω παύλες.
PID_FILE○Διαδρομή προς το αρχείο PID του daemon που χρησιμοποιείται από τα -start/-stop. Προεπιλογή: κατάλογος cache χρήστη OS (fallback: κατάλογος temp).
ALLOWED_ORIGINS○Ρυθμίσεις CORS. Λίστα επιτρεπόμενων origins χωρισμένων με κόμμα (π.χ. https://myapp.com). Προεπιλογή: μη ορισμένο — τα cross-origin requests browser απενεργοποιούνται. Ορίστε ρητά * για να επιτρέψετε οποιοδήποτε origin.
STATIC_FILES_PATH○Απόλυτη διαδρομή για την εξυπηρέτηση static files (Explorer/Frontend).
Ασφάλεια (JWT)
JWT_SECRET✓Ένα μεγάλο, τυχαίο string που χρησιμοποιείται για την υπογραφή session tokens. Ελάχιστο 32 bytes· δημιουργήστε με openssl rand -hex 32.
JWT_EXPIRY_HOURS○Διάρκεια ισχύος session σε ώρες. Προεπιλογή: 8.
JWT_ISSUER○Αν έχει οριστεί, γράφεται στο claim iss κατά την έκδοση και απαιτείται να ταιριάζει ακριβώς κατά την επικύρωση. Αφήστε το κενό για να παραλείψετε τον έλεγχο issuer.
JWT_AUDIENCE○Αν έχει οριστεί, γράφεται στο claim aud κατά την έκδοση και απαιτείται να ταιριάζει κατά την επικύρωση. Αφήστε το κενό για να παραλείψετε τον έλεγχο audience.
JWT_LEEWAY○Ανοχή απόκλισης ώρας (clock-skew) για την επικύρωση exp/nbf/iat (π.χ. 30s). Προεπιλογή: 30s.
LOGIN_RATE_LIMIT○Μέγιστες προσπάθειες σύνδεσης ανά χρονικό παράθυρο. Προεπιλογή: 5. Ορίστε 0 για απενεργοποίηση.
LOGIN_RATE_LIMIT_PER_IP○Μέγιστες προσπάθειες σύνδεσης ανά IP client σε όλα τα usernames, ώστε η εναλλαγή usernames να μην παρακάμπτει το όριο. Προεπιλογή: 5× LOGIN_RATE_LIMIT. Ορίστε 0 για απενεργοποίηση.
LOGIN_RATE_WINDOW○Διάρκεια χρονικού παραθύρου rate limit. Προεπιλογή: 1m.
Το rate limiting σύνδεσης είναι ανά instance (in-memory). Σε deployments με πολλαπλά instances, χρησιμοποιήστε κοινό limiter αν χρειάζεστε καθολική εφαρμογή.
TRUSTED_PROXIES○Έμπιστες IP/CIDR proxy για τον χειρισμό του X-Forwarded-For. Χωρισμένες με κόμμα. Αν είναι κενό, οι forwarded headers αγνοούνται και η IP client λαμβάνεται από την άμεση σύνδεση.
MAX_REQUEST_BYTES○Μέγιστο μέγεθος σώματος request σε bytes. Προεπιλογή: 2097152.
MCP_SQL_ERROR_DETAIL○Συμπερίληψη του ανεπεξέργαστου μηνύματος σφάλματος PostgreSQL στα σφάλματα εργαλείων MCP. Τα λεπτομερή σφάλματα βοηθούν τους LLM agents να αυτοδιορθωθούν, αλλά μπορούν να εκθέσουν λεπτομέρειες σχήματος (ονόματα πινάκων και constraints) σε αυθεντικοποιημένους καλούντες. Προεπιλογή: false.
DIRECT_POOL_LIMIT○Μέγιστος αριθμός διακριτών connection pools διαπιστευτηρίων Basic-Auth. Προεπιλογή: 1000.
METRICS_ENABLED○Ενεργοποίηση αποκλειστικού endpoint μετρικών. Προεπιλογή: true.
METRICS_LISTEN_ADDR○Διεύθυνση listener μετρικών (host:port). Προεπιλογή: 127.0.0.1:9090.
SSE_MAX_CHANNELS○Μέγιστα κανάλια ανά σύνδεση SSE. Προεπιλογή: 8.
SSE_MAX_CLIENTS○Μέγιστοι ταυτόχρονοι clients SSE ανά βάση δεδομένων. Προεπιλογή: 1000.
SSE_CLIENT_BUFFER○Μέγεθος buffer ανά client SSE (μηνύματα). Προεπιλογή: 64.
SSE_SEND_TIMEOUT○Μέγιστος χρόνος αναμονής κατά την αποστολή σε αργό client. Προεπιλογή: 2s.
SSE_HEARTBEAT○Διάστημα heartbeat για συνδέσεις SSE. Προεπιλογή: 20s.
SSE_IDLE_TIMEOUT○Timeout αδράνειας χωρίς notifications. Προεπιλογή: 90s.
Καταγραφή (Logging)
LOG_LEVEL○Επίπεδο λεπτομέρειας: DEBUG, INFO, WARN, ERROR. Προεπιλογή: INFO.
LOG_OUTPUT○Πού θα γράφονται τα logs: stdout ή διαδρομή αρχείου.

Απαιτείται   Προαιρετικό

Συμπεριφορά ασφαλείας: τα requests χωρίς έγκυρη κεφαλίδα Authorization απορρίπτονται πριν ανοίξει σύνδεση βάσης δεδομένων.

Εκκίνηση του server:

./pgarachne -config .env

Δείτε επίσης

Σχετική τεκμηρίωση

← Εγκατάσταση JSON-RPC (Hello World) →