Konfiguracja

4 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
JWT_SECRET=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Wymagane zmienne: DB_HOST, DB_PORT, DB_USER, JWT_SECRET (minimum 32 bajty; wygeneruj za pomocą openssl rand -hex 32).

Szybka lista kontrolna walidacji

  • 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, /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)
JWT_SECRET✓Długi, losowy ciąg używany do podpisywania tokenów sesji. Minimum 32 bajty; wygeneruj za pomocą openssl rand -hex 32.
JWT_EXPIRY_HOURS○Ważność sesji w godzinach. 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 logowania w oknie czasowym. Domyślnie: 5. Ustaw 0, aby wyłączyć.
LOGIN_RATE_LIMIT_PER_IP○Maksymalna liczba prób logowania na IP klienta przy uwzględnieniu wszystkich nazw użytkowników, dzięki czemu zmiana nazwy użytkownika nie pozwala obejść limitu. 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.
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

Zobacz również

Powiązana dokumentacja

← Instalacja JSON-RPC (Hello World) →