Розгортання та HTTPS

2 хв читання

Розгортання та HTTPS

PgArachne створений, щоб добре виконувати одну роботу: API-шлюз. Для SSL/TLS (HTTPS), безпеки заголовків та публічної маршрутизації вам слід розмістити перед ним зворотний проксі.

Варіант A: Caddy Server

Найкраще для: Сучасних продакшн-розгортань, простоти використання.

Caddy — єдиний веб-сервер, який отримує та автоматично оновлює SSL-сертифікати (Let’s Encrypt) за умовчанням. Він потребує майже нульового налаштування.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Варіант B: Nginx

Найкраще для: Корпоративних середовищ, складної маршрутизації.

Nginx — галузевий стандарт для високопродуктивного балансування навантаження. Використовуйте це, якщо у вас уже є інфраструктура Nginx. Вам доведеться керувати Certbot вручну.

server {
    server_name example.com;
    location / {
        proxy_pass http://localhost:8080;
    }
}

Варіант C: Ngrok

Найкраще для: Локальної розробки, демонстрацій, тестування вебхуків.

Ngrok створює безпечний тунель з публічного інтернету безпосередньо до вашого ноутбука без налаштування фаєрволів. Ідеально підходить для миттєвої демонстрації роботи колегам.

./ngrok http 8080

Контрольний список для продакшну

Завершуйте TLS на зворотному проксі та передавайте X-Forwarded-Proto і X-Forwarded-For.
Встановіть у PgArachne TRUSTED_PROXIES на діапазони IP/CIDR вашого проксі.
Вимкніть буферизацію для маршрутів SSE та зробіть тайм-аути читання достатньо довгими для потокової передачі.
Надавайте доступ до метрик лише внутрішньо (за умовчанням 127.0.0.1:9090) і опитуйте (scrape) з вашої мережі моніторингу.

Приклад посилення захисту Nginx (SSE, завантаження файлів, forwarded-заголовки)

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

# SSE: /{API_PREFIX}/{database}/sse — long-lived stream, must not be buffered
location ~ ^/db/[^/]+/sse$ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_buffering off;
    proxy_read_timeout 1h;
}

# File downloads: /{API_PREFIX}/{database}/file — large files and ZIP archives
location ~ ^/db/[^/]+/file/?$ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_buffering off;
    proxy_read_timeout 300s;
}

Замініть db на ваш API_PREFIX, якщо ви його змінили.

Великі завантаження (`/file`) за reverse proxy

Вимкніть буферизацію відповідей (proxy_buffering off у Nginx). Одиночний файл надсилається із заголовком Content-Length, ZIP-архів передається потоком без нього. Якщо буферизація ввімкнена, Nginx спочатку записує всю відповідь у тимчасовий файл, що затримує початок завантаження і займає місце на диску.
Збільште тайм-аут читання (proxy_read_timeout, за умовчанням 60 с), якщо функція бази даних, що формує файли, може працювати довше — PgArachne нічого не надсилає, доки функція не поверне всі рядки.
Не стискайте application/zip та вже стиснені типи медіа (gzip для ZIP лише марнує CPU).
Ліміт пам’яті: PgArachne буферизує рядки однієї відповіді в пам’яті (обмежено FILE_MAX_BYTES, за умовчанням 64 МіБ, та FILE_MAX_ENTRIES); підберіть ліміти під очікувану кількість одночасних завантажень. client_max_body_size стосується лише невеликого JSON-запиту, а не завантаження.
Caddy за умовчанням передає відповіді потоком; додаткове налаштування не потрібне.

← Безпека та автентифікація Коди помилок →

Розгортання та HTTPS