Konfigurace

5 min čtení

Rychlý start

  1. Nainstalujte PgArachne
  2. Nastavte prostředí
  3. Nastavte bezpečnost a autentizaci
  4. Nasaďte za HTTPS proxy

Konfigurace

PgArachne načítá konfiguraci z proměnných prostředí nebo ze souboru.

Poznámka: schema.sql se pokusí vytvořit roli pgarachne_admin a přiřadit ji roli pgarachne. Bez superuser práv se vytvoření přeskočí. V tom případě vytvořte roli a nastavte grant ručně.
Proxy uživatel (DB_USER) musí být členem pgarachne a pgarachne_admin, aby mohl ověřovat a vytvářet API tokeny.
Bezpečnostní poznámka: PgArachne nepracuje s hesly k databázi v konfiguračním souboru. Pro autentizaci spoléhá na standardní mechanismus PostgreSQL souboru .pgpass (nebo systémovou proměnnou PGPASSWORD).
Tip: Pokud běží PgArachne za reverse proxy, nastavte TRUSTED_PROXIES, aby se správně určovala IP klienta a nešlo obejít rate limiting.
Pořadí hledání: Pokud není konfigurační soubor specifikován přes CLI, hledá se v tomto pořadí:
  1. Aktuální složka: ./pgarachne.env (všechny OS)
  2. Uživatelská konfigurace:
    • Linux/macOS: ~/.config/pgarachne/pgarachne.env
    • Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. Systémová konfigurace: /etc/pgarachne/pgarachne.env (pouze Linux/macOS)

Příklad minimální konfigurace

Pro základní spuštění aplikace postačuje následující nastavení:

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

Povinné proměnné: DB_HOST, DB_PORT, DB_USER.

JWT_SECRET je volitelný. Nastavte ho (minimálně 32 bajtů; vygenerujte pomocí openssl rand -hex 32), pokud chcete povolit JWT relace přes POST /{prefix}/{database}/token a externě vydané JWT. Bez něj je podpora JWT vypnutá a klienti se autentizují pomocí HTTP Basic údajů (databázové uživatelské jméno a heslo) nebo dlouhodobých API tokenů.

Rychlý validační checklist

  • Pokud je JWT zapnuté, JWT_SECRET je dlouhý, náhodný a není sdílený mezi prostředími.
  • DB_USER může přepínat jen do očekávaných rolí (zkontrolujte role membership granty).
  • TRUSTED_PROXIES je nastaveno, pokud běžíte za reverse proxy.
  • LOGIN_RATE_LIMIT je zapnut pro veřejně dostupné nasazení.
  • METRICS_LISTEN_ADDR je neveřejný (např. 127.0.0.1:9090).

Kompletní přehled nastavení

ProměnnáPovinnéPopis
Připojení k databázi
DB_HOST✓Adresa PostgreSQL serveru (např. localhost).
DB_PORT✓Port databáze.
DB_USER✓Databázový uživatel, pod kterým se PgArachne připojuje.
DB_SSLMODE○SSL režim PostgreSQL. Výchozí: require. Hodnotu disable nastavte explicitně jen pro lokální vývoj proti PostgreSQL bez TLS.
DB_SSLROOTCERT○Cesta k CA root certifikátu (PEM).
DB_SSLCERT○Cesta ke klientskému certifikátu (PEM).
DB_SSLKEY○Cesta ke klientskému privátnímu klíči (PEM).
HTTP Server
HTTP_PORT○Port pro naslouchání. Výchozí: 8080.
API_PREFIX○První segment URL cesty pro všechny databázové endpointy (/jsonrpc, /file, /sse, /mcp). Výchozí: db, výsledné cesty jako /db/:databaze/jsonrpc. Povoleny jsou pouze písmena, číslice, pomlčky a podtržítka.
PID_FILE○Cesta k PID souboru démona používanému při -start/-stop. Výchozí: cache adresář uživatele (fallback: temp adresář).
ALLOWED_ORIGINS○Nastavení CORS. Čárkou oddělený seznam povolených domén (např. https://mojeaplikace.cz). Výchozí: nenastaveno — cross-origin požadavky z prohlížeče jsou zakázané. Pro povolení libovolného původu nastavte explicitně *.
STATIC_FILES_PATH○Absolutní cesta k servírování statických souborů (Explorer/Frontend).
Bezpečnost (JWT & přihlášení)
JWT_SECRET○Dlouhý náhodný řetězec používaný k podepisování relačních tokenů. Minimálně 32 bajtů; vygenerujte pomocí openssl rand -hex 32. Pokud není nastaven, je podpora JWT vypnutá: endpoint /token není k dispozici a klienti se autentizují pouze pomocí HTTP Basic údajů nebo API tokenů.
JWT_EXPIRY_HOURS○Platnost relace v hodinách (musí být větší než 0). Výchozí: 8.
JWT_ISSUER○Pokud je nastaveno, zapisuje se do claimu iss a musí přesně souhlasit při ověření. Prázdné = kontrola vypnuta.
JWT_AUDIENCE○Pokud je nastaveno, zapisuje se do claimu aud a musí souhlasit při ověření. Prázdné = kontrola vypnuta.
JWT_LEEWAY○Tolerance hodinového posunu pro exp/nbf/iat (např. 30s). Výchozí: 30s.
LOGIN_RATE_LIMIT○Max. počet pokusů o autentizaci na IP klienta a uživatelské jméno v okně. Platí pro všechny způsoby přihlášení: počítá se každý požadavek na /token a u HTTP Basic údajů (na všech endpointech) neúspěšné pokusy. Výchozí: 5. Pro vypnutí nastavte 0.
LOGIN_RATE_LIMIT_PER_IP○Max. počet pokusů o autentizaci na IP klienta napříč všemi uživatelskými jmény, takže střídání jmen limit neobejde. Počítají se i neúspěšné pokusy s Bearer tokenem (neplatný JWT nebo API token). Výchozí: 5× LOGIN_RATE_LIMIT. Pro vypnutí nastavte 0.
LOGIN_RATE_WINDOW○Délka časového okna pro omezení. Výchozí: 1m.
Omezení přihlášení je platné pro jednu instanci (uloženo v paměti). Při provozu více instancí je nutný sdílený limiter pro globální vynucení.
TRUSTED_PROXIES○Důvěryhodné proxy IP/CIDR pro zpracování X-Forwarded-For. Čárkou oddělené. Pokud je hodnota prázdná, forwardované hlavičky se ignorují a IP klienta se bere z přímého spojení.
FILE_MAX_BYTES○Maximální celková nekomprimovaná velikost odpovědi /file v bajtech. Výchozí: 67108864 (64 MiB).
FILE_MAX_ENTRIES○Maximální počet souborů v odpovědi /file. Výchozí: 1000.
MAX_REQUEST_BYTES○Maximální velikost request body v bajtech. Výchozí: 2097152.
MCP_SQL_ERROR_DETAIL○Zahrnout surovou chybovou zprávu PostgreSQL do chyb MCP nástrojů. Detailní chyby pomáhají LLM agentům se opravit, ale mohou odhalit detaily schématu (názvy tabulek a omezení) autentizovaným volajícím. Výchozí: false.
DIRECT_POOL_LIMIT○Maximální počet různých connection poolů pro přihlašovací údaje Basic Auth. Výchozí: 1000.
METRICS_ENABLED○Povolit dedikovaný endpoint metrik. Výchozí: true.
METRICS_LISTEN_ADDR○Adresa listeneru metrik (host:port). Výchozí: 127.0.0.1:9090.
SSE_MAX_CHANNELS○Maximální počet kanálů na SSE připojení. Výchozí: 8.
SSE_MAX_CLIENTS○Maximální počet současných SSE klientů na databázi. Výchozí: 1000.
SSE_CLIENT_BUFFER○Velikost per‑klientského bufferu SSE (počet zpráv). Výchozí: 64.
SSE_SEND_TIMEOUT○Maximální čekání při odesílání pomalému klientovi. Výchozí: 2s.
SSE_HEARTBEAT○Interval heartbeat zpráv pro SSE. Výchozí: 20s.
SSE_IDLE_TIMEOUT○Timeout neaktivity bez notifikací. Výchozí: 90s.
Logování
LOG_LEVEL○Úroveň detailů: DEBUG, INFO, WARN, ERROR. Výchozí: INFO.
LOG_OUTPUT○Kam zapisovat logy: stdout nebo cesta k souboru.

Povinné   Volitelné

Bezpečnostní chování: požadavky bez validní hlavičky Authorization jsou odmítnuty ještě před navázáním databázového připojení.

Spuštění serveru:

./pgarachne -config .env

Související dokumentace

← Instalace JSON-RPC →