Установка pgAdmin 4 через APT-репозиторий с Apache и Nginx

Методичка по развёртыванию pgAdmin 4 из официального APT-репозитория. Apache работает как backend на отдельном порту (8080), Nginx — как внешний обратный прокси, публикующий pgAdmin по подпути /pgadmin4.

---

Содержание

1. Требования
2. Шаг 1. Подключение APT-репозитория pgAdmin
3. Шаг 2. Установка pgAdmin и первичная настройка
4. Шаг 3. Перевод Apache на порт 8080
5. Шаг 4. Настройка Nginx как обратного прокси
6. Проверка
7. Диагностика

---

Требования

• Debian 13 (Trixie) или совместимый дистрибутив
• root-доступ или sudo
• Уже работающий сайт на Nginx (если нужен доступ по подпути)
• Свободный порт 8080 для Apache

---

Шаг 1. Подключение APT-репозитория pgAdmin

Установите утилиты и добавьте официальный репозиторий pgAdmin.

sudo apt update
sudo apt install -y curl gnupg lsb-release

# Импорт ключа
curl -fsS https://www.pgadmin.org/static/packages_pgadmin_org.pub | \
    sudo gpg --dearmor -o /usr/share/keyrings/packages-pgadmin-org.gpg

# Добавление репозитория с ЯВНЫМ указанием trixie
echo "deb [signed-by=/usr/share/keyrings/packages-pgadmin-org.gpg] \
https://ftp.postgresql.org/pub/pgadmin/pgadmin4/apt/trixie pgadmin4 main" | \
    sudo tee /etc/apt/sources.list.d/pgadmin4.list

# Обновление индекса
sudo apt update

Важно: Указывайте trixie явно, а не через $(lsb_release -cs). На некоторых системах команда возвращает пустое значение или n/a, что приводит к ошибке 404 Not Found.

---

Шаг 2. Установка pgAdmin и первичная настройка

sudo apt install -y pgadmin4-web

Запустите скрипт настройки. При запросе Apache-конфигурации ответьте y — скрипт создаст рабочий конфиг для Apache.

sudo PGADMIN_PLATFORM_TYPE=debian /usr/pgadmin4/bin/setup-web.sh

Пример диалога:

Email address: frolin@city70.ru
Password:
Retype password:
pgAdmin 4 - Application Initialisation
======================================

Creating storage and log directories...
We can now configure the Apache Web server for you. This involves enabling
the wsgi module and configuring the pgAdmin 4 application to mount at /pgadmin4.
Do you wish to continue (y/n)? y
The Apache web server is running and must be restarted for the pgAdmin 4
installation to complete. Continue (y/n)? y
Apache successfully restarted. You can now start using pgAdmin 4 in web mode
at http://127.0.0.1/pgadmin4

Сохраните введённые email и пароль — они понадобятся для входа в веб-интерфейс.

---

Шаг 3. Перевод Apache на порт 8080

Поскольку порт 80 занят Nginx, переводим Apache на альтернативный порт.

3.1. Изменение порта прослушивания

Откройте /etc/apache2/ports.conf:

sudo nano /etc/apache2/ports.conf

Замените Listen 80 на:

Listen 8080

Рекомендация по безопасности: Если Nginx и Apache находятся на одном хосте, ограничьте Apache только локальными подключениями:

Listen 127.0.0.1:8080

Это предотвратит прямой внешний доступ к Apache в обход Nginx.

3.2. Изменение порта в VirtualHost

Откройте /etc/apache2/sites-available/000-default.conf:

sudo nano /etc/apache2/sites-available/000-default.conf

Замените <VirtualHost *:80> на:

<VirtualHost *:8080>

3.3. Изменение WSGIScriptAlias

Откройте /etc/apache2/conf-available/pgadmin4.conf:

sudo nano /etc/apache2/conf-available/pgadmin4.conf

Замените строку WSGIScriptAlias /pgadmin4 /usr/pgadmin4/web/pgAdmin4.wsgi на:

WSGIScriptAlias / /usr/pgadmin4/web/pgAdmin4.wsgi

Почему меняем путь на /: pgAdmin будет монтироваться в корень Apache (на порту 8080). Nginx возьмёт на себя роль публикации по подпути /pgadmin4 через заголовок X-Script-Name. Если оставить WSGIScriptAlias /pgadmin4, возникнет двойной префикс /pgadmin4/pgadmin4.

3.4. Перезапуск Apache

sudo systemctl restart apache2

Проверьте, что Apache слушает нужный порт:

sudo ss -tlnp | grep apache

---

Шаг 4. Настройка Nginx как обратного прокси

Добавьте location-блок для pgAdmin в конфигурацию вашего существующего сайта.

Если pgAdmin должен быть единственным сайтом на этом домене, создайте отдельный файл /etc/nginx/sites-available/pgadmin с полным server-блоком. Если у вас уже есть работающий сайт — просто добавьте location в его конфигурацию.

# Перенаправляем /pgadmin4 на /pgadmin4/ (важно для корректной работы путей)
location = /pgadmin4 {
    return 301 /pgadmin4/;
}

location ^~ /pgadmin4/ {
    proxy_pass http://127.0.0.1:8080/;

    # Ключевой заголовок: сообщаем pgAdmin, что он находится в /pgadmin4
    proxy_set_header X-Script-Name /pgadmin4;

    # Используем $http_host, чтобы избежать проблем с редиректами
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Настройки для корректной работы WebSocket и таймаутов
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 300;
    proxy_connect_timeout 60;
}

Обратите внимание на завершающий слэш в proxy_pass: http://127.0.0.1:8080/ — он обязателен. Без него Nginx передаст Apache путь /pgadmin4/..., что приведёт к двойному префиксу.

Проверьте синтаксис и перезагрузите Nginx:

sudo nginx -t
sudo systemctl reload nginx

---

Проверка

Откройте в браузере:

http://your-domain.com/pgadmin4/

Используйте email и пароль, введённые на шаге 2.

---

Диагностика

Логи Apache:

sudo tail -f /var/log/apache2/error.log

Логи Nginx:

sudo tail -f /var/log/nginx/error.log

Проверка портов:

sudo ss -tlnp | grep -E 'apache|nginx'

Типичные ошибки:

Ошибка	Причина	Решение
404 Not Found при apt update	Неверное кодовое имя в репозитории	Укажите trixie явно
502 Bad Gateway	Apache не слушает 8080 или Nginx не видит его	Проверьте ss -tlnp и proxy_pass
Пустая страница / нет стилей	Не передан или передан неверно X-Script-Name	Убедитесь, что заголовок равен /pgadmin4
Двойной путь /pgadmin4/pgadmin4	В Apache оставлен WSGIScriptAlias /pgadmin4, а Nginx тоже добавляет префикс	Установите в Apache WSGIScriptAlias /
Редирект на /login вместо /pgadmin4/login	Не используется $http_host	Замените $host на $http_host

---

Итог

Схема использует официальный APT-пакет pgadmin4-web (простое обновление через apt upgrade), Apache в роли WSGI-контейнера на изолированном порту 8080 и Nginx в роли публичного обратного прокси. Такой подход удобен, если вы предпочитаете пакетное управление зависимостями и не хотите возиться с venv и Gunicorn.