Конфігурація

5 хв читання

Швидкий старт

  1. Встановіть PgArachne
  2. Налаштуйте середовище
  3. Налаштуйте безпеку та автентифікацію
  4. Розгорніть за HTTPS-проксі

Конфігурація

PgArachne завантажує конфігурацію зі змінних середовища або з файлу.

Примітка: schema.sql намагається створити роль pgarachne_admin та надати її ролі pgarachne. Якщо ви запускаєте скрипт без прав суперкористувача, створення ролі буде пропущено. За потреби створіть роль та надайте права вручну.
Проксі-користувач (DB_USER) повинен бути членом pgarachne та pgarachne_admin, щоб перевіряти та видавати API-токени.
Примітка щодо безпеки: PgArachne не обробляє паролі бази даних у конфігураційному файлі. Для автентифікації покладайтеся на стандартний механізм файлу PostgreSQL .pgpass (або системну змінну PGPASSWORD).
Порада: Якщо ви запускаєте PgArachne за зворотним проксі, встановіть TRUSTED_PROXIES, щоб IP-адреси клієнтів визначалися коректно і обмеження частоти запитів не можна було обійти.
Порядок пошуку: Якщо конфігураційний файл не вказано через CLI, пошук відбувається в такому порядку:
  1. Поточний каталог: ./pgarachne.env (усі ОС)
  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
# Optional — enables JWT sessions (POST /db//token):
# JWT_SECRET=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Обов’язкові змінні: DB_HOST, DB_PORT, DB_USER.

JWT_SECRET необов’язковий. Встановіть його (мінімум 32 байти; згенеруйте за допомогою openssl rand -hex 32), щоб увімкнути JWT-сесії через POST /{prefix}/{database}/token та JWT, видані зовнішніми системами. Без нього підтримку JWT вимкнено, і клієнти автентифікуються за допомогою облікових даних HTTP Basic (ім’я користувача та пароль бази даних) або довгострокових API-токенів.

Швидкий контрольний список перевірки

  • Якщо JWT увімкнено, JWT_SECRET довгий, випадковий і не використовується повторно в різних середовищах.
  • DB_USER може перемикатися лише на очікувані ролі (перевірте права членства в ролях).
  • TRUSTED_PROXIES встановлено, якщо ви працюєте за зворотним проксі.
  • LOGIN_RATE_LIMIT увімкнено для розгортань, доступних з інтернету.
  • METRICS_LISTEN_ADDR є приватним (наприклад, 127.0.0.1:9090).

Довідник конфігурації

ЗміннаОбов’язковаОпис
Підключення до бази даних
DB_HOST✓Адреса сервера PostgreSQL (наприклад, localhost).
DB_PORT✓Порт бази даних.
DB_USER✓Користувач бази даних, під яким підключається PgArachne.
DB_SSLMODE○Режим SSL PostgreSQL. За умовчанням: require. Встановлюйте disable явно лише для локальної розробки з PostgreSQL без TLS.
DB_SSLROOTCERT○Шлях до кореневого сертифіката CA (PEM).
DB_SSLCERT○Шлях до клієнтського сертифіката (PEM).
DB_SSLKEY○Шлях до приватного ключа клієнта (PEM).
HTTP-сервер
HTTP_PORT○Порт для прослуховування. За умовчанням: 8080.
API_PREFIX○Перший сегмент шляху URL для всіх ендпоінтів бази даних (/jsonrpc, /file, /sse, /mcp). За умовчанням: db, що дає маршрути типу /db/:database/jsonrpc. Дозволені лише букви, цифри, дефіси та підкреслення.
PID_FILE○Шлях до PID-файлу демона, що використовується для -start/-stop. За умовчанням: кеш-каталог користувача ОС (запасний варіант: тимчасовий каталог).
ALLOWED_ORIGINS○Налаштування CORS. Список дозволених джерел, розділених комами (наприклад, https://myapp.com). За умовчанням: не встановлено — міждоменні запити з браузера вимкнено. Встановіть * явно, щоб дозволити будь-яке джерело.
STATIC_FILES_PATH○Абсолютний шлях для надання статичних файлів (Explorer/Frontend).
Безпека (JWT & вхід)
JWT_SECRET○Довгий випадковий рядок, що використовується для підписання токенів сесії. Мінімум 32 байти; згенеруйте за допомогою openssl rand -hex 32. Якщо не встановлено, підтримку JWT вимкнено: endpoint /token недоступний, і клієнти автентифікуються лише за допомогою облікових даних HTTP Basic або API-токенів.
JWT_EXPIRY_HOURS○Термін дії сесії в годинах (має бути більшим за 0). За умовчанням: 8.
JWT_ISSUER○Якщо встановлено, записується в claim iss під час видачі і повинно точно збігатися під час перевірки. Залиште порожнім, щоб пропустити перевірку видавця.
JWT_AUDIENCE○Якщо встановлено, записується в claim aud під час видачі і повинно збігатися під час перевірки. Залиште порожнім, щоб пропустити перевірку аудиторії.
JWT_LEEWAY○Допуск на розсинхронізацію годинників для перевірки exp/nbf/iat (наприклад, 30s). За умовчанням: 30s.
LOGIN_RATE_LIMIT○Максимальна кількість спроб автентифікації на IP-адресу клієнта та ім’я користувача за одне вікно. Застосовується до всіх методів входу: враховується кожен запит до /token, а для облікових даних HTTP Basic (на всіх endpoint-ах) враховуються невдалі спроби. За умовчанням: 5. Встановіть 0, щоб вимкнути.
LOGIN_RATE_LIMIT_PER_IP○Максимальна кількість спроб автентифікації на IP-адресу клієнта за всіма іменами користувачів, тож зміна імен користувачів не дозволяє обійти обмеження. Також враховуються невдалі спроби Bearer (недійсний JWT або API-токен). За умовчанням: 5× LOGIN_RATE_LIMIT. Встановіть 0, щоб вимкнути.
LOGIN_RATE_WINDOW○Тривалість вікна обмеження частоти. За умовчанням: 1m.
Обмеження частоти входу діє в межах одного екземпляра (у пам’яті). У розгортаннях з кількома екземплярами використовуйте спільний лімітер, якщо потрібне глобальне застосування.
TRUSTED_PROXIES○Довірені IP-адреси/CIDR проксі для обробки X-Forwarded-For. Розділені комами. Якщо порожньо, forwarded-заголовки ігноруються, а IP клієнта береться з прямого з’єднання.
FILE_MAX_BYTES○Максимальний сумарний нестиснутий розмір відповіді /file у байтах. За умовчанням: 67108864 (64 MiB).
FILE_MAX_ENTRIES○Максимальна кількість файлів у відповіді /file. За умовчанням: 1000.
MAX_REQUEST_BYTES○Максимальний розмір тіла запиту в байтах. За умовчанням: 2097152.
MCP_SQL_ERROR_DETAIL○Включати необроблене повідомлення про помилку PostgreSQL у помилках інструментів MCP. Детальні помилки допомагають LLM-агентам самостійно виправлятися, але можуть розкрити деталі схеми (назви таблиць та обмежень) автентифікованим викликачам. За умовчанням: false.
DIRECT_POOL_LIMIT○Максимальна кількість окремих пулів з’єднань облікових даних Basic Auth. За умовчанням: 1000.
METRICS_ENABLED○Увімкнути виділений ендпоінт метрик. За умовчанням: true.
METRICS_LISTEN_ADDR○Адреса слухача метрик (host:port). За умовчанням: 127.0.0.1:9090.
SSE_MAX_CHANNELS○Максимальна кількість каналів на одне з’єднання SSE. За умовчанням: 8.
SSE_MAX_CLIENTS○Максимальна кількість одночасних клієнтів SSE на базу даних. За умовчанням: 1000.
SSE_CLIENT_BUFFER○Розмір буфера SSE на одного клієнта (кількість повідомлень). За умовчанням: 64.
SSE_SEND_TIMEOUT○Максимальний час очікування під час надсилання повільному клієнту. За умовчанням: 2s.
SSE_HEARTBEAT○Інтервал heartbeat для з’єднань SSE. За умовчанням: 20s.
SSE_IDLE_TIMEOUT○Тайм-аут неактивності без сповіщень. За умовчанням: 90s.
Журналювання
LOG_LEVEL○Рівень деталізації: DEBUG, INFO, WARN, ERROR. За умовчанням: INFO.
LOG_OUTPUT○Куди записувати журнали: stdout або шлях до файлу.

Обов’язково   Необов’язково

Поведінка безпеки: запити без дійсного заголовка Authorization відхиляються ще до відкриття з’єднання з базою даних.

Запустіть сервер:

./pgarachne -config .env

Пов’язана документація

← Встановлення JSON-RPC →