Apache APISIX на Ubuntu 24.04: пошаговая установка

MAATRIX

Когда перед десятком бэкендов нужен один вход с маршрутизацией, лимитами и TLS, а трафик растёт быстрее, чем вы успеваете переписывать nginx.conf, — пора выносить эту логику в отдельный слой. Apache APISIX закрывает эту задачу как высокопроизводительный API-шлюз на базе Nginx/OpenResty: конфигурация меняется через API на лету, без перезапуска и простоя. Ниже — установка APISIX на чистый Ubuntu 24.04 вместе с etcd, первый маршрут через Admin API и то, что нужно закрыть от интернета сразу после установки.

Что такое Apache APISIX и когда он нужен

APISIX — это API-шлюз с открытым кодом от Apache Software Foundation, построенный поверх OpenResty (nginx + Lua). Ключевое отличие от классического nginx: маршрутизация, апстримы, TLS-сертификаты и плагины хранятся не в текстовом конфиге, а в etcd — распределённом key-value хранилище. Изменения применяются через REST-запросы к Admin API и подхватываются воркерами без nginx -s reload и без разрыва существующих соединений.

Для чего его обычно ставят:

• Единая точка входа перед микросервисами — клиент стучится в один домен, APISIX решает, на какой апстрим и по какому пути отправить запрос.
• Плагины из коробки — аутентификация (key-auth, JWT, basic-auth), rate limiting, трансформация запросов/ответов, кэширование — десятки готовых модулей, включаются флагом в конфиге маршрута.
• Динамический балансировщик — апстрим меняется на лету через API, без переброса трафика вручную.
• Наблюдаемость — встроенная интеграция с Prometheus и OpenTelemetry, кастомные логи через плагины http-logger, kafka-logger.

Если у вас один сервис без внутренней маршрутизации, APISIX избыточен, хватит обычного Caddy или nginx. По архитектуре APISIX ближе всего к Kong Gateway: оба построены на nginx/OpenResty, но у APISIX конфигурация хранится в etcd, а не в PostgreSQL — это меняет и модель отказоустойчивости, и подход к бэкапам.

Требования к серверу и подготовка

APISIX сам по себе лёгкий процесс на базе nginx, но ему нужен etcd рядом — на этом же сервере или на отдельном. Для одиночного сервера с etcd локально хватает следующего:

Под серьёзный прод-трафик APISIX масштабируется горизонтально — несколько нод-шлюзов перед общим etcd-кластером из трёх узлов для кворума, но для старта хватает одного сервера.

Обновите систему и поставьте базовые пакеты:

apt update && apt upgrade -y
apt install -y curl gnupg2 lsb-release apt-transport-https ca-certificates

Если firewall ещё не настроен — сделайте это до того, как APISIX начнёт слушать порты наружу, инструкция есть в статье про настройку UFW на Ubuntu 24.04. Забегая вперёд: наружу должен смотреть только proxy-порт (9080/9443), Admin API — никогда.

Установка etcd — хранилища конфигурации APISIX

etcd хранит всю конфигурацию APISIX: маршруты, апстримы, плагины, сертификаты. Версия etcd в репозиториях Ubuntu часто отстаёт от актуальных релизов, поэтому проще поставить бинарник с GitHub — сверьтесь с таблицей совместимости в документации APISIX, поддержка веток etcd 3.4.x и 3.5.x отличается между релизами шлюза.

Скачиваем актуальный релиз и разворачиваем бинарники:

ETCD_VER=$(curl -s https://api.github.com/repos/etcd-io/etcd/releases/latest | grep '"tag_name"' | cut -d '"' -f4)
mkdir -p /tmp/etcd-download
curl -L "https://github.com/etcd-io/etcd/releases/download/${ETCD_VER}/etcd-${ETCD_VER}-linux-amd64.tar.gz" -o /tmp/etcd.tar.gz
tar xzf /tmp/etcd.tar.gz -C /tmp/etcd-download --strip-components=1
install -m 755 /tmp/etcd-download/etcd /tmp/etcd-download/etcdctl /usr/local/bin/

Создайте пользователя и каталог данных, затем systemd-юнит:

useradd --system --no-create-home --shell /usr/sbin/nologin etcd
mkdir -p /var/lib/etcd && chown etcd:etcd /var/lib/etcd

# /etc/systemd/system/etcd.service
[Unit]
Description=etcd key-value store
After=network.target

[Service]
User=etcd
Type=notify
ExecStart=/usr/local/bin/etcd \
  --name default \
  --data-dir /var/lib/etcd \
  --listen-client-urls http://127.0.0.1:2379 \
  --advertise-client-urls http://127.0.0.1:2379 \
  --listen-peer-urls http://127.0.0.1:2380
Restart=on-failure
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Для одиночного сервера client URL достаточно привязать к 127.0.0.1 — APISIX ходит в etcd локально, и снаружи этот порт видеть не должен вовсе. Запускаем:

systemctl daemon-reload
systemctl enable --now etcd
etcdctl endpoint health

Команда должна вернуть 127.0.0.1:2379 is healthy. Если нет — смотрите journalctl -u etcd -n 50 на предмет ошибок доступа к /var/lib/etcd.

Установка Apache APISIX из официального репозитория и первый запуск

APISIX публикует .deb-пакеты через собственный APT-репозиторий, но пакет зависит от OpenResty, поэтому сначала добавляем репозиторий OpenResty, затем репозиторий APISIX:

curl -fsSL https://openresty.org/package/pubkey.gpg | gpg --dearmor -o /usr/share/keyrings/openresty.gpg
echo "deb [signed-by=/usr/share/keyrings/openresty.gpg] http://openresty.org/package/ubuntu $(lsb_release -sc) main" | tee /etc/apt/sources.list.d/openresty.list

curl -fsSL https://repos.apiseven.com/repos/GPG-KEY-APISEVEN | gpg --dearmor -o /usr/share/keyrings/apiseven.gpg
echo "deb [signed-by=/usr/share/keyrings/apiseven.gpg] https://repos.apiseven.com/packages/debian $(lsb_release -sc) main" | tee /etc/apt/sources.list.d/apisix.list

apt update
apt install -y apisix

Пути и ключи сторонних репозиториев время от времени меняются — если apt update ругается, сверьтесь с актуальной инструкцией в документации APISIX, принцип не меняется: ключ, строка репозитория, обновление индекса.

Основной конфиг лежит в /usr/local/apisix/conf/config.yaml. Пропишите адрес etcd и задайте свой admin-ключ вместо дефолтного:

deployment:
  admin:
    admin_key:
      - name: admin
        key: замените_на_свой_длинный_случайный_ключ
        role: admin
  etcd:
    host:
      - "http://127.0.0.1:2379"
    prefix: /apisix
    timeout: 30

Дефолтный ключ из quickstart-примеров APISIX (edd1c9f034335f136f87ad84b625c8f) знают все, кто хоть раз читал документацию, — оставить его как есть на сервере с интернетом равносильно админке без пароля. Генерируйте свой:

openssl rand -hex 16

Запускаем APISIX и проверяем статус:

systemctl enable --now apisix
systemctl status apisix
curl -i http://127.0.0.1:9180/apisix/admin/routes -H "X-API-KEY: ваш_admin_key"

Пустой список маршрутов в ответе (JSON вида {"list":[],"total":0}, формат отличается между версиями) означает, что Admin API работает и достучался до etcd. Порт 9080 — proxy для клиентского трафика, 9443 — тот же порт с TLS, 9180 — Admin API, который должен слушать только 127.0.0.1 (проверьте admin.listen в config.yaml).

Маршруты, апстримы и первые плагины через Admin API

В APISIX всё настраивается через REST-запросы к Admin API — отдельного конфиг-файла для маршрутов нет, всё сразу пишется в etcd. Базовая единица — route: путь/домен плюс апстрим плюс (опционально) плагины.

Пример: есть бэкенд на http://10.0.0.5:3000, нужно проксировать на него запросы к /api/users.

curl -i -X PUT http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: ваш_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "/api/users*",
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "10.0.0.5:3000": 1
      }
    }
  }'

Проверяем через proxy-порт:

curl -i http://127.0.0.1:9080/api/users

Запрос уйдёт на 10.0.0.5:3000, а APISIX подставит себя посередине. Для балансировки между несколькими бэкендами перечислите их в nodes с весами — они задают пропорцию трафика, а не абсолютные лимиты.

Добавим ограничение частоты запросов — один из самых частых сценариев для API-шлюза, плагин limit-count:

curl -i -X PATCH http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: ваш_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": {
      "limit-count": {
        "count": 60,
        "time_window": 60,
        "rejected_code": 429,
        "policy": "local"
      }
    }
  }'

Это ограничит клиента 60 запросами в минуту на маршрут, с ответом 429 при превышении. policy: local хранит счётчик в памяти воркера — для одной ноды достаточно, для кластера нужен policy: redis, иначе каждая нода считает независимо и реальный лимит окажется в разы выше задуманного.

Для аутентификации по ключу используется плагин key-auth на маршруте плюс объект consumer — та же логика: плагин конфигурируется через Admin API, без изменений на стороне бэкенда.

TLS, защита Admin API, мониторинг и резервное копирование

Сертификат в APISIX прикрепляется не к конфигу nginx, а тоже через Admin API — объектом ssl, привязанным к SNI:

curl -i -X PUT http://127.0.0.1:9180/apisix/admin/ssls/1 \
  -H "X-API-KEY: ваш_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    "snis": ["api.example.com"]
  }'

Сам сертификат получаете любым привычным способом — принцип выбора между certbot и acme.sh разобран в статье certbot или acme.sh, только PEM сертификата и ключа вставляются в JSON-запрос к Admin API, а не в конфиг nginx.

Закройте Admin API от внешнего мира, если ещё не сделали: проверьте, что admin.listen смотрит на 127.0.0.1, и зафиксируйте это на уровне firewall:

ufw deny 9180/tcp
ufw allow 9080/tcp
ufw allow 9443/tcp

Если удалённый доступ к Admin API всё же нужен — для CI/CD или дашборда apisix-dashboard — пробрасывайте его через SSH-туннель или VPN, а не открытым портом: через Admin API шлюз перенастраивается полностью, включая подмену апстримов.

Для метрик у APISIX есть встроенный плагин prometheus:

curl -i -X PUT http://127.0.0.1:9180/apisix/admin/global_rules/1 \
  -H "X-API-KEY: ваш_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"plugins": {"prometheus": {}}}'

После этого метрики отдаются на отдельном порту (по умолчанию 9091, путь /apisix/prometheus/metrics) — их скрейпит Prometheus и визуализирует Grafana, установка обеих частей разобрана в статье про Grafana и Prometheus на Ubuntu 24.04.

Резервное копирование сводится к снапшоту etcd — там живёт вся конфигурация APISIX:

etcdctl snapshot save /backup/etcd-snapshot-$(date +%F).db

Автоматизируйте через cron и храните снапшоты вне сервера — потеря etcd означает потерю всех маршрутов и плагинов, а восстанавливать это руками через Admin API долго. Обновление APISIX — обычное обновление deb-пакета:

apt update
apt install --only-upgrade apisix
systemctl restart apisix

Перед обновлением в проде проверьте changelog версии — между мажорными релизами APISIX иногда меняет формат объектов в etcd, и конфигурация может потребовать миграции; тестируйте на staging-копии сервера.

Частые вопросы