Konfiguracja

5 min czytania

Szybki start

  1. Zainstaluj PgArachne
  2. Skonfiguruj środowisko
  3. Skonfiguruj bezpieczeństwo i autoryzację
  4. Wdróż za proxy HTTPS

Konfiguracja

PgArachne wczytuje konfigurację ze zmiennych środowiskowych lub z pliku.

Uwaga: schema.sql próbuje utworzyć rolę pgarachne_admin i przypisać ją do pgarachne. Jeśli uruchomisz skrypt bez uprawnień superużytkownika, tworzenie roli zostanie pominięte. W takim przypadku utwórz rolę i przypisz uprawnienia ręcznie.
Użytkownik proxy (DB_USER) musi być członkiem pgarachne i pgarachne_admin, aby móc weryfikować i wydawać tokeny API.
Uwaga dotycząca bezpieczeństwa: PgArachne nie przechowuje haseł do bazy danych w pliku konfiguracyjnym. Do autoryzacji korzysta ze standardowego mechanizmu pliku PostgreSQL .pgpass (lub zmiennej systemowej PGPASSWORD).
Wskazówka: Jeśli uruchamiasz PgArachne za reverse proxy, ustaw TRUSTED_PROXIES, aby IP klientów były rozpoznawane prawidłowo i nie można było oszukać rate limitingu.
Porządek wyszukiwania: Jeśli plik konfiguracyjny nie zostanie wskazany przez CLI, wyszukiwanie odbywa się w kolejności:
  1. Katalog bieżący: ./pgarachne.env (wszystkie systemy operacyjne)
  2. Konfiguracja użytkownika:
    • Linux/macOS: ~/.config/pgarachne/pgarachne.env
    • Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. Konfiguracja systemowa: /etc/pgarachne/pgarachne.env (tylko Linux/macOS)

Przykład minimalnej konfiguracji

To wszystko, czego potrzebujesz na początek:

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

Wymagane zmienne: DB_HOST, DB_PORT, DB_USER.

JWT_SECRET jest opcjonalny. Ustaw go (minimum 32 bajty; wygeneruj za pomocą openssl rand -hex 32), aby włączyć sesje JWT przez POST /{prefix}/{database}/token oraz JWT wydawane zewnętrznie. Bez niego obsługa JWT jest wyłączona, a klienci uwierzytelniają się danymi HTTP Basic (nazwa użytkownika i hasło bazy danych) lub długoterminowymi tokenami API.

Szybka lista kontrolna walidacji

  • Jeśli JWT jest włączony, JWT_SECRET jest długi, losowy i nie jest współdzielony między środowiskami.
  • DB_USER może przełączać się tylko na oczekiwane role (zweryfikuj przypisania członkostwa w rolach).
  • TRUSTED_PROXIES jest ustawione, gdy działasz za reverse proxy.
  • LOGIN_RATE_LIMIT jest włączony dla wdrożeń dostępnych z internetu.
  • METRICS_LISTEN_ADDR jest prywatny (na przykład 127.0.0.1:9090).

Pełny wykaz konfiguracji

ZmiennaWymaganeOpis
Połączenie z bazą danych
DB_HOST✓Adres serwera PostgreSQL (np. localhost).
DB_PORT✓Port bazy danych.
DB_USER✓Użytkownik bazy danych, z którym łączy się PgArachne.
DB_SSLMODE○Tryb SSL PostgreSQL. Domyślnie: require. Ustaw disable jawnie tylko dla lokalnego środowiska deweloperskiego bez TLS.
DB_SSLROOTCERT○Ścieżka do certyfikatu głównego CA (PEM).
DB_SSLCERT○Ścieżka do certyfikatu klienta (PEM).
DB_SSLKEY○Ścieżka do klucza prywatnego klienta (PEM).
Serwer HTTP
HTTP_PORT○Port do nasłuchiwania. Domyślnie: 8080.
API_PREFIX○Pierwszy segment ścieżki URL dla wszystkich endpointów bazodanowych (/jsonrpc, /file, /sse, /mcp). Domyślnie: db, co daje ścieżki takie jak /db/:database/jsonrpc. Dozwolone są tylko litery, cyfry, myślniki i podkreślenia.
PID_FILE○Ścieżka do pliku PID demona używanego przez -start/-stop. Domyślnie: katalog cache użytkownika systemu operacyjnego (fallback: katalog tymczasowy).
ALLOWED_ORIGINS○Ustawienia CORS. Lista dozwolonych źródeł rozdzielona przecinkami (np. https://mojaaplikacja.com). Domyślnie: nieustawione — żądania cross-origin z przeglądarki są wyłączone. Ustaw jawnie *, aby zezwolić na dowolne źródło.
STATIC_FILES_PATH○Ścieżka absolutna do serwowania plików statycznych (Explorer/Frontend).
Bezpieczeństwo (JWT & logowanie)
JWT_SECRET○Długi, losowy ciąg używany do podpisywania tokenów sesji. Minimum 32 bajty; wygeneruj za pomocą openssl rand -hex 32. Jeśli nie jest ustawiony, obsługa JWT jest wyłączona: endpoint /token jest niedostępny, a klienci uwierzytelniają się wyłącznie danymi HTTP Basic lub tokenami API.
JWT_EXPIRY_HOURS○Ważność sesji w godzinach (musi być większa od 0). Domyślnie: 8.
JWT_ISSUER○Jeśli ustawione, jest zapisywane w polu iss przy wydawaniu tokenu i musi się dokładnie zgadzać podczas walidacji. Pozostaw puste, aby wyłączyć sprawdzanie wydawcy.
JWT_AUDIENCE○Jeśli ustawione, jest zapisywane w polu aud przy wydawaniu tokenu i musi się zgadzać podczas walidacji. Pozostaw puste, aby wyłączyć sprawdzanie odbiorcy.
JWT_LEEWAY○Tolerancja przesunięcia zegara dla walidacji exp/nbf/iat (np. 30s). Domyślnie: 30s.
LOGIN_RATE_LIMIT○Maksymalna liczba prób uwierzytelnienia na IP klienta i nazwę użytkownika w oknie czasowym. Dotyczy wszystkich metod logowania: liczy się każde żądanie /token, a w przypadku danych HTTP Basic (na wszystkich endpointach) liczą się nieudane próby. Domyślnie: 5. Ustaw 0, aby wyłączyć.
LOGIN_RATE_LIMIT_PER_IP○Maksymalna liczba prób uwierzytelnienia na IP klienta przy uwzględnieniu wszystkich nazw użytkowników, dzięki czemu zmiana nazwy użytkownika nie pozwala obejść limitu. Liczone są także nieudane próby Bearer (nieprawidłowy JWT lub token API). Domyślnie: 5× LOGIN_RATE_LIMIT. Ustaw 0, aby wyłączyć.
LOGIN_RATE_WINDOW○Długość okna czasowego rate limitu. Domyślnie: 1m.
Rate limiting logowania jest liczony per instancja (w pamięci). We wdrożeniach z wieloma instancjami użyj współdzielonego limitera, jeśli potrzebujesz globalnego wymuszania.
TRUSTED_PROXIES○Zaufane IP/CIDR proxy dla obsługi X-Forwarded-For. Rozdzielone przecinkami. Jeśli puste, przekazywane nagłówki są ignorowane, a IP klienta jest pobierane z bezpośredniego połączenia.
FILE_MAX_BYTES○Maksymalny łączny rozmiar po dekompresji odpowiedzi /file w bajtach. Domyślnie: 67108864 (64 MiB).
FILE_MAX_ENTRIES○Maksymalna liczba plików w odpowiedzi /file. Domyślnie: 1000.
MAX_REQUEST_BYTES○Maksymalny rozmiar ciała żądania w bajtach. Domyślnie: 2097152.
MCP_SQL_ERROR_DETAIL○Uwzględnij surowy komunikat błędu PostgreSQL w błędach narzędzi MCP. Szczegółowe błędy pomagają agentom LLM się samodzielnie skorygować, ale mogą ujawniać szczegóły schematu (nazwy tabel i ograniczeń) uwierzytelnionym wywołującym. Domyślnie: false.
DIRECT_POOL_LIMIT○Maksymalna liczba odrębnych poolów połączeń dla danych uwierzytelniających Basic Auth. Domyślnie: 1000.
METRICS_ENABLED○Włącz dedykowany endpoint metryk. Domyślnie: true.
METRICS_LISTEN_ADDR○Adres nasłuchu metryk (host:port). Domyślnie: 127.0.0.1:9090.
SSE_MAX_CHANNELS○Maksymalna liczba kanałów na połączenie SSE. Domyślnie: 8.
SSE_MAX_CLIENTS○Maksymalna liczba równoczesnych klientów SSE na bazę danych. Domyślnie: 1000.
SSE_CLIENT_BUFFER○Rozmiar bufora SSE na klienta (liczba wiadomości). Domyślnie: 64.
SSE_SEND_TIMEOUT○Maksymalny czas oczekiwania przy wysyłce do wolnego klienta. Domyślnie: 2s.
SSE_HEARTBEAT○Interwał heartbeat dla połączeń SSE. Domyślnie: 20s.
SSE_IDLE_TIMEOUT○Limit czasu bezczynności bez powiadomień. Domyślnie: 90s.
Logowanie
LOG_LEVEL○Poziom szczegółowości: DEBUG, INFO, WARN, ERROR. Domyślnie: INFO.
LOG_OUTPUT○Gdzie zapisywać logi: stdout lub ścieżka do pliku.

Wymagane   Opcjonalne

Zachowanie bezpieczeństwa: żądania bez prawidłowego nagłówka Authorization są odrzucane jeszcze przed otwarciem połączenia z bazą danych.

Uruchomienie serwera:

./pgarachne -config .env

Powiązana dokumentacja

← Instalacja JSON-RPC →