Русский · English

REST API для удалённого управления VPN-сервером на базе Amnezia. Превращает CLI-управление Amnezia (AmneziaWG, AmneziaWG 2.0, Xray) в удобный HTTP-интерфейс с типизированными схемами и Swagger из коробки.

Подходит для того, чтобы построить поверх Amnezia свою инфраструктуру: админ-панель, Telegram-бота, биллинг или балансировку по нескольким серверам — без ручного захода на сервер.

• Три протокола в одном API — AmneziaWG, AmneziaWG 2.0 и Xray через единый набор маршрутов.
• Управление клиентами — создание, список, обновление и удаление пиров; готовый конфиг для импорта в приложение.
• Пауза пользователей — можно временно отключить доступ (status: disabled), не удаляя ключ, а затем возобновить (status: active). Пользователю не придется заново генерировать конфиг.
• QR-коды конфигов — генерация серии QR (POST /clients/qr) в том же формате, что и клиент Amnezia: большие конфиги разбиваются на несколько кодов, приложение Amnezia их сканирует и импортирует.
• Срок действия доступа — поле expiresAt у клиента и фоновая задача, автоматически отключающая истёкших клиентов по cron.
• Статистика по каждому пиру — трафик (отдано/принято), последнее рукопожатие, online-статус, endpoint и разрешенные IP.
• Метрики сервера — CPU, RAM, диск, сеть, load average, uptime и статистика Docker-контейнеров VPN.
• Бэкап и восстановление — выгрузка и импорт конфигурации сервера через API.
• Балансировка — вес сервера, регион и лимит клиентов в ответе /server для маршрутизации между нодами.
• Swagger UI на /docs со схемами, примерами и валидацией запросов.
• Локализация ответов (ru/en) и аутентификация по API-ключу.

# Клонировать репозиторий
git clone https://github.com/kyoresuas/amnezia-api.git

# Перейти в репозиторий
cd ./amnezia-api

# Запустить установку (предложит режим pm2 или docker)
bash ./scripts/setup.sh

Скрипт сам поставит зависимости, сгенерирует .env, поднимет API и настроит nginx. После установки API доступен на http://<ваш_сервер>.

docker compose up -d --build

docker-compose.yml пробрасывает docker.sock, чтобы API мог управлять контейнерами Amnezia на хосте. Конфигурация читается из .env.

Файл .env генерируется автоматически из .env.example при первом запуске setup.sh.

Все маршруты (кроме /healthz, /metrics, /docs) защищены preHandler-ом и требуют заголовок:

x-api-key: <FASTIFY_API_KEY>

Базовый адрес ниже — http://<ваш_сервер>. Подставьте свой ключ в x-api-key.

curl -X POST http://<ваш_сервер>/clients \
  -H "x-api-key: <FASTIFY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "clientName": "Kyoresuas",
    "protocol": "amneziawg2",
    "expiresAt": null
  }'

{
  "message": "Клиент создан",
  "client": {
    "id": "PF77ZXRl1yAkFzhBq/zQNlDPD73XXTq+Zs2PgtjLKVA=",
    "config": "vpn://3fa85f64-5717-4562-b3fc-2c963f66afa6...",
    "protocol": "amneziawg2"
  }
}

curl "http://<ваш_сервер>/clients?skip=0&limit=100" \
  -H "x-api-key: <FASTIFY_API_KEY>"

status: disabled отключает доступ, не удаляя ключ; status: active возвращает доступ — конфиг у пользователя остаётся прежним.

curl -X PATCH http://<ваш_сервер>/clients \
  -H "x-api-key: <FASTIFY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "PF77ZXRl1yAkFzhBq/zQNlDPD73XXTq+Zs2PgtjLKVA=",
    "protocol": "amneziawg2",
    "status": "disabled",
    "expiresAt": 1735689600
  }'

Передайте config, полученный при создании клиента. В ответе — массив QR (PNG data URI); для длинных конфигов их несколько, сканируйте по очереди в приложении Amnezia.

curl -X POST http://<ваш_сервер>/clients/qr \
  -H "x-api-key: <FASTIFY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "config": "vpn://3fa85f64-5717-4562-b3fc-2c963f66afa6..."
  }'

{
  "total": 1,
  "items": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."]
}

curl -X DELETE http://<ваш_сервер>/clients \
  -H "x-api-key: <FASTIFY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "PF77ZXRl1yAkFzhBq/zQNlDPD73XXTq+Zs2PgtjLKVA=",
    "protocol": "amneziawg2"
  }'

curl http://<ваш_сервер>/server \
  -H "x-api-key: <FASTIFY_API_KEY>"

Swagger UI доступен на маршруте /docs:

• http://<ваш_сервер>/docs

Там — все схемы, параметры, примеры запросов и ответов.

├─ /scripts [скрипты]
├─ /src [корень]
│  ├─ /config [инициализация проекта]
│  ├─ /constants [константы]
│  ├─ /contracts [настройки сервисов]
│  ├─ /controllers [контроллеры для маршрутов API]
│  ├─ /handlers [обработчики запросов API]
│  ├─ /helpers [специализированные помощники]
│  ├─ /locales [файлы перевода]
│  ├─ /middleware [промежуточное ПО для маршрутов API]
│  ├─ /schemas [схемы маршрутов API для Swagger и валидации]
│  ├─ /services [сервисы]
│  ├─ /tasks [отложенные задачи]
│  ├─ /types [типизация]
│  ├─ /utils [вспомогательные функции]
│  └─ main.ts [файл запуска]
├─ .env.example [пример конфигурации]
└─ .env [конфигурация разработчика]

• amnezia-panel — веб-панель управления поверх Amnezia API.

• Telegram: @stercuss
• Email: hey@kyoresuas.com

MIT — см. файл LICENSE.