bayrepo/hestiacp
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Added API for bunkerweb

Browse Source
This commit is contained in:
Alexey Berezhok
2026-04-27 00:47:57 +03:00
parent 4b023ea671
commit 592b954a9f
9 changed files with 1286 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

467
func_ruby/docs/BunkerWebApiDoc.md Normal file
View File

@@ -0,0 +1,467 @@
# HestiaBunkerWebApi - Ruby класс для работы с BunkerWeb API
## Описание
Класс `HestiaBunkerWebApi` предоставляет простой интерфейс для управления сервисами BunkerWeb через REST API. Класс реализует:
- **Аутентификацию** с получением токена
- **Управление сервисами** (создание, обновление, удаление)
- **Управление SSL сертификатами**
- **Управление instances** (worker nodes)
- **Полное исключение ошибок** при любых проблемах
## Установка и импорт
```bash
# Ruby 3.3+ рекомендуется
ruby --version
# ruby 3.3.x or later
# Класс использует стандартные библиотеки Ruby:
# - json (для JSON парсинга)
# - net/http (для HTTP запросов)
# - uri (для URL парсинга)
```
## Использование класса
### Базовое использование
```ruby
require_relative "HestiaBunkerWebApi.rb"
# Создаём экземпляр API с аутентификацией
api = HestiaBunkerWebApi.new(
"http://127.0.0.1:8888", # URL API (можно https://)
"admin", # username
"password" # password
)
# или
api = HestiaBunkerWebApi.new(
"http://127.0.0.1:8888", # URL API (можно https://)
)
# в этом случае пароль и логин читаются автоматически из файла /etc/bunkerweb/api.env
# При создании экземпляра автоматически происходит аутентификация
# Если ошибка - выбрасывается BunkerWebApiError с описанием проблемы
```
### Обработка ошибок
Все ошибки наследуются от `StandardError` через класс `BunkerWebApiError`:
```ruby
begin
api.create_service("example.domain", options)
rescue BunkerWebApiError => e
puts "[ERROR] Ошибка API: #{e.message}"
# Примеры возможных ошибок:
# - "Authentication failed: 401 - Unauthorized"
# - "Service 'x' already exists"
# - "Certificate and Key paths are required when USE_SSL is enabled"
# - "Failed to create service: status=500, body={...}"
exit 1
end
```
## Методы класса
### Конструктор
```ruby
HestiaBunkerWebApi.new(api_url, username, password)
```
**Параметры:**
- `api_url` - URL BunkerWeb API в формате `http://ip:port` или `https://ip:port`
- `username` - имя администратора для аутентификации
- `password` - пароль для аутентификации
**Действие:** При создании автоматически пытается аутентифицироваться через POST /auth и сохраняет токен.
### Создание сервиса
```ruby
api.create_service(service_name, options = {})
```
**Параметры:**
- `service_name` - имя домена/сервиса (например, "example.my.domain")
- `options` - хэш с конфигурацией:
| Параметр | Тип | Описание | Пример |
|----------|-----|----------|--------|
| `ssl` | String | "yes" для SSL, "no" для HTTP | `"no"` |
| `certificate_path` | String | Путь к SSL сертификату (если ssl="yes") | `"/etc/ssl/certs/example.crt"` |
| `key_path` | String | Путь к приватному ключу (если ssl="yes") | `"/etc/ssl/private/example.key"` |
| `use_template` | String | Безопасность шаблона | `"high"` (default) |
| `reverse_proxy_host` | String | Target reverse proxy | `"http://192.168.3.51:8078"` |
| `reverse_proxy_url` | String | URL трансформация | `"~ ^/(.*)$"` |
| `real_ip_from` | String | CIDR trusted network для RealIP | `"192.168.3.0/24"` |
| `use_modsecurity` | String | WAF включение | `"yes"` (default) |
| `anti_bot` | String | Bot protection | `"captcha"` (default) |
| `http_port` | Integer/nil | HTTP порт | `"80"` или `null` |
| `https_port` | Integer | HTTPS порт | `443` или `null` |
**Пример - создание reverse proxy сервиса без SSL:**
```ruby
result = api.create_service("example.my.domain", {
ssl: "no",
reverse_proxy_host: "http://192.168.3.51:8078"
})
# Генерирует variables:
# - USE_TEMPLATE: "high"
# - USE_SSL: "no"
# - LISTEN_HTTPS_PORT: "null"
# - LISTEN_HTTP_PORT: "80"
# - USE_REVERSE_PROXY: "yes"
# - REVERSE_PROXY_HOST: "http://192.168.3.51:8078"
```
**Пример - создание сервиса с SSL + reverse proxy:**
```ruby
result = api.create_service("example.my.domain", {
ssl: "yes", # Включаем SSL
certificate_path: "/etc/ssl/certs/example.crt", # Путь к сертификату
key_path: "/etc/ssl/private/example.key", # Путь к ключу
reverse_proxy_host: "http://192.168.3.51:8078", # Reverse proxy target
use_template: "high",
anti_bot: "captcha"
})
# Генерирует variables:
# - USE_TEMPLATE: "high"
# - USE_SSL: "yes"
# - SSL_CERTIFICATE_FILE_PATH: "/etc/ssl/certs/example.crt"
# - SSL_KEY_FILE_PATH: "/etc/ssl/private/example.key"
# - LISTEN_HTTPS_PORT: "443"
# - LISTEN_HTTP_PORT: "80"
```
### Обновление SSL сертификата для существующего сервиса
```ruby
api.update_service_ssl(service_name, certificate_path, key_path, https_port = nil)
```
**Параметры:**
- `service_name` - имя уже созданного сервиса
- `certificate_path` - новый путь к SSL сертификату
- `key_path` - новый путь к приватному ключу
- `https_port` (optional) - HTTPS порт (default: 443)
**Пример:**
```ruby
api.update_service_ssl(
"example.my.domain",
"/etc/ssl/certs/example.crt",
"/etc/ssl/private/example.key"
)
# Обновляет существующий сервис, сохраняя reverse proxy настройки
```
### Удаление сервиса
```ruby
api.delete_service(service_name)
```
**Параметры:**
- `service_name` - имя сервиса для удаления
**Пример:**
```ruby
api.delete_service("example.my.domain")
# Удаляет сервис и конфигурацию
```
### Получение списка всех сервисов
```ruby
api.list_services(drafts = false)
```
**Параметры:**
- `drafts` (optional) - включать draft сервисы (default: false)
**Возвращает:** Array of service objects
**Пример:**
```ruby
services = api.list_services()
services.each { |s| puts "- #{s['server_name']}" }
```
### Получение деталей конкретного сервиса
```ruby
api.get_service(service_name)
```
**Параметры:**
- `service_name` - имя сервиса для получения деталей
**Возвращает:** Hash with service configuration (variables, settings, etc.)
**Пример:**
```ruby
config = api.get_service("example.my.domain")
puts config.inspect
```
### Перезагрузка конфигурации на instance
```ruby
api.reload_instance(instance_hostname = nil)
```
**Параметры:**
- `instance_hostname` (optional) - hostname instance для перезагрузки (если nil, reloads all instances)
**Пример:**
```ruby
# Reload все instances
api.reload_instance()
# Reload конкретный instance
api.reload_instance("192.168.3.50")
```
### Получение списка всех instances
```ruby
api.list_instances()
```
**Возвращает:** Array of instance objects (hostname, name, port, etc.)
### Создание/регистрация BunkerWeb instance (worker node)
```ruby
api.create_instance(hostname, name = nil, port = 8888, https_port = nil)
```
**Параметры:**
- `hostname` - IP address или hostname worker node
- `name` (optional) - Human-readable имя instance
- `port` - API port на worker node (default: 8888)
- `https_port` (optional) - HTTPS port если есть
**Пример:**
```ruby
api.create_instance(
"192.168.3.50", # IP worker node
"BunkerWeb Worker Node", # Optional name
8888 # API port
)
# Возвращает: { status: 201/409, body: {...} }
# Если статус 201 - instance создан
# Если статус 409 - instance уже существует (это OK)
```
### Удаление BunkerWeb instance
```ruby
api.delete_instance(hostname)
```
**Параметры:**
- `hostname` - hostname instance для удаления
## Примеры полного использования
### Пример 1: Создание и управление сервисом
```ruby
require_relative "HestiaBunkerWebApi.rb"
begin
# 1. Подключаемся к API
api = HestiaBunkerWebApi.new(
"http://127.0.0.1:8888",
"admin",
"your_password"
)
# 2. Создаём reverse proxy сервис без SSL
result = api.create_service("u4.my.brp", {
ssl: "no",
reverse_proxy_host: "http://192.168.3.51:8078"
})
puts "[INFO] Service created: #{result.inspect}"
# 3. Добавляем SSL сертификат позже (если нужно)
api.update_service_ssl(
"u4.my.brp",
"/etc/ssl/certs/u4.crt",
"/etc/ssl/private/u4.key"
)
# 4. Проверяем список сервисов
services = api.list_services()
puts "[INFO] All services:"
services.each { |s| puts "- #{s['server_name']}" }
# 5. Удаление сервиса (при необходимости)
api.delete_service("u4.my.brp")
rescue BunkerWebApiError => e
puts "[ERROR] Ошибка API: #{e.message}"
exit 1
end
```
### Пример 2: Управление несколькими сервисами
```ruby
require_relative "HestiaBunkerWebApi.rb"
api = HestiaBunkerWebApi.new("http://127.0.0.1:8888", "admin", "password")
# Создаём несколько сервисов с разными конфигурациями
services_to_create = [
{ name: "service1.domain", ssl: "no", reverse_proxy_host: "http://192.168.3.50:80" },
{ name: "service2.domain", ssl: "yes", certificate_path: "/certs/service2.crt", key_path: "/keys/service2.key", reverse_proxy_host: "http://192.168.3.51:8078" }
]
services_to_create.each do |opts|
begin
api.create_service(opts[:name], opts)
rescue BunkerWebApiError => e
puts "[ERROR] #{e.message}" if e.message.include?("already exists")
end
end
# Reload конфигурации на instance
api.reload_instance("192.168.3.50")
```
### Пример 3: Обработка ошибок и логирование
```ruby
require_relative "HestiaBunkerWebApi.rb"
def safe_create_service(api_url, username, password, service_name, options)
begin
api = HestiaBunkerWebApi.new(api_url, username, password)
result = api.create_service(service_name, options)
return { success: true, data: result }
rescue BunkerWebApiError => e
if e.message.include?("Authentication")
puts "[FATAL] Authentication failed: #{e.message}"
elsif e.message.include?("already exists")
begin
existing = api.get_service(service_name)
return { success: false, already_exists: true, service: existing }
rescue => get_error
return { success: false, error: "Can't retrieve service: #{get_error.message}" }
else
return { success: false, error: e.message }
end
end
{ success: false, error: "Unknown error" }
end
# Использование
result = safe_create_service("http://127.0.0.1:8888", "admin", "password", "example.domain", { ssl: "yes" })
if result[:success]
puts "[SUCCESS] Service created"
elsif result[:already_exists]
puts "[INFO] Service exists:"
puts JSON.generate(result[:service])
else
puts "[FAILED] #{result[:error]}"
end
```
## Ошибки и их обработка
### Типичные ошибки:
| Код ответа | Описание | Пример сообщения |
|------------|----------|------------------|
| **401** | Authentication failed | "Authentication failed: 401 - Unauthorized" |
| **200 (no token)** | Auth passed but no token | "Authentication succeeded but no token received" |
| **Connection error** | API недоступен | "Authentication error: Connection refused" |
| **409 Conflict** | Service already exists | "Service 'x' already exists" |
| **422 Unprocessable Entity** | Invalid data (например, LISTEN_HTTPS_PORT = nil) | "Failed to create service: status=422..." |
| **429 Too Many Requests** | Rate limit exceeded | "Rate limit exceeded: 10 per 1 minute" |
### Решение проблем с rate limiting
Если получаете ошибку `429` (rate limit), нужно отключить или увеличить лимит в `/etc/bunkerweb/api.env`:
```bash
# Откройте конфиг и найдите секцию Rate limiting
nano /etc/bunkerweb/api.env
# Добавьте/измените:
API_RATE_LIMIT_ENABLED=no # Отключение rate limiting
# или
API_RATE_LIMIT=1000/minute # Увеличение лимита до 1000/m
```
Затем перезагрузите API service:
```bash
systemctl reload bunkerweb-api.service
```
## Особенности реализации
### 1. SSL сертификатные пути
Когда `ssl: "no"` - API ожидает `"LISTEN_HTTPS_PORT" => "null"` (строка), а не JSON null (`nil`):
```ruby
# ❌ Ошибка:
variables["LISTEN_HTTPS_PORT"] = nil # → 422 error
# ✅ Правильно:
variables["LISTEN_HTTPS_PORT"] = "null" # → 200 OK
```
### 2. Статусы ответа для создания сервиса
BunkerWeb API возвращает **200 OK** вместо стандартного **201 Created**:
```ruby
# Класс принимает оба статуса как успех:
if [201, 200].include?(response[:status])
puts "[INFO] Service created successfully"
end
```
### 3. Поддержка HTTP методов
Класс поддерживает все основные HTTP методы для API операций:
- **GET** - получение данных (services, instances)
- **POST** - создание (services, instances, auth)
- **PATCH** - обновление (services)
- **DELETE** - удаление (services, instances)
## Совместимость
- **Ruby**: 3.0+
- **BunkerWeb API**: 1.6.x и выше
- **ZooKeeper/Redis**: не требуются для этого класса (работает через HTTP API напрямую)
## Дополнительные ресурсы
- [Документация BunkerWeb API](https://docs.bunkerweb.io/api.md)
- [API Swagger docs at /docs](http://127.0.0.1:8888/docs)
- [OpenAPI schema](http://127.0.0.1:8888/openapi.json)