Руководство по Global System 3 Rest API

Руководство по Global System 3 Rest API#

Назначение#

Global System 3 Rest API (standalone) — это REST‑сервис для упрощенного мониторинга и управления systemd‑сервисами на Linux‑хосте.
Он предоставляет безопасный HTTP API для просмотра статуса, запуска, остановки и перезагрузки systemd‑юнитов (например, globalscheduler) с ролевой моделью доступа и полным аудитом всех операций.

Авторизация и безопасность#

В системе предусмотрено два способа взаимодействия:

JWT Bearer (рекомендуемый)#

  1. Получаем токен через /auth/login

  2. Передаем его в заголовке: Authorization: Bearer <token>

  3. Эндпоинты этого типа начинаются с нижнего подчеркивания (например, /_status)

Basic Auth (для простых скриптов)#

Логин и пароль передаются прямо в JSON‑теле запроса.
Эндпоинты без подчеркивания (например, /status).

Все пароли хранятся в sec/users.json в виде bcrypt‑хешей.
При первом запуске или изменении файла пароли автоматически мигрируются в хешированный формат.

Основные эндпоинты#

Аутентификация#

POST /auth/login
Обмен логина/пароля на временный JWT токен.
Лимит: 3 попытки в минуту (настраивается в config.yaml).

Пример запроса:

curl -X POST 'http://localhost:8000/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

Успешный ответ (200 OK):

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "bearer",
  "expires_in": 900
}

GET /me
Информация о текущем пользователе и его правах.
Требуется Bearer‑токен.

Пример:

curl -X GET 'http://localhost:8000/me' \
  -H 'Authorization: Bearer <token>'

Ответ:

{
  "username": "admin",
  "permissions": ["service:all"],
  "expires_at": "2026-02-24T12:34:56.789012"
}

Работа с сервисами (через Bearer Token)#

Все эндпоинты используют имя сервиса, заданное в config.yaml (поле name в списке services).

GET /{service_name}/_status
Получить статус systemd‑сервиса.
Требуется разрешение: service:view или service:{service_name}:view.

Пример:

curl -X GET 'http://localhost:8000/global-scheduler/_status' \
  -H 'Authorization: Bearer <token>'

Ответ (StatusResponse):

{
  "service": "global-scheduler",
  "status": "running",
  "is_active": true,
  "uptime": {
    "service_start_time": "2026-02-24T10:00:00",
    "uptime_formatted": "2h 34m 12s",
    "uptime_seconds": 9252
  },
  "timestamp": "2026-02-24T12:34:56.789012"
}

POST /{service_name}/_restart
Перезагрузить сервис.
Требуется разрешение: service:restart или service:{service_name}:restart.
Тело (опционально): {"reason": "Причина перезагрузки"}

Аналогичные эндпоинты:

  • /_start — запуск сервиса

  • /_stop — остановка сервиса

Пример перезагрузки:

curl -X POST 'http://localhost:8000/global-scheduler/_restart' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "Плановая замена конфигурации"
  }'

Ответ (ServiceActionResponse):

{
  "status": "success",
  "action": "restart",
  "service": "global-scheduler",
  "message": "Service restarted successfully",
  "reason": "Плановая замена конфигурации",
  "timestamp": "2026-02-24T12:35:00.123
}

Работа с сервисами (через Basic Auth)#

Эти эндпоинты позволяют выполнить операцию и аутентификацию в одном запросе (без предварительного получения токена).

POST /{service_name}/status
Получить статус.
Тело: {"username": "...", "password": "..."}

POST /{service_name}/restart
Перезагрузить сервис.
Тело: {"username": "...", "password": "...", "reason": "..."}

Аналогично: /start, /stop.

Пример:

curl -X POST 'http://localhost:8000/global-scheduler/restart' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "operator",
    "password": "operator123",
    "reason": "Обновление"
  }'

Служебные#

GET /health
Проверка доступности API (без авторизации).
Возвращает статус приложения, версию и время.

{
  "status": "operational",
  "app": "Global System 3 Rest API",
  "version": "1.5.0",
  "timestamp": "2026-02-24T12:36:00.000000"
}

Форматы ответов#

StatusResponse (статус сервиса)#

Поле

Тип

Описание

service

string

Логическое имя сервиса (из конфига)

status

string

running, stopped или error

is_active

bool

Активен ли сервис

uptime

object

Информация о времени работы (если доступна)

message

string

Доп. сообщение (опционально)

error

string

Описание ошибки (если status: error)

timestamp

string

Время ответа (ISO 8601)

ServiceActionResponse (результат действия)#

Поле

Тип

Описание

status

string

success или error

action

string

Выполненное действие (start, stop, restart)

service

string

Имя сервиса

message

string

Успешное сообщение

reason

string

Причина (если передана)

error

string

Текст ошибки (при status: error)

timestamp

string

Время ответа

Валидация и ограничения#

  • Reason Validation: Поле reason проверяется на опасные символы и конструкции (инъекции команд, SQL, path traversal). Длина ограничена (по умолчанию 500 символов).

  • Rate Limiting: По умолчанию 10 запросов в минуту на эндпоинты сервисов (настраивается в rate_limiting.requests_per_minute).

  • Доступ к systemctl: Для выполнения команд systemctl требуется настроенный sudo без пароля для конкретных команд. Это автоматически делает скрипт setup.sh, создавая файл в /etc/sudoers.d/.

Настройка standalone#

Настройка сервиса производится через конфигурационные файлы и скрипт автоматической установки.

Конфигурационные файлы#

  • conf/config.yaml — основной YAML‑конфиг. Содержит:

    • параметры приложения (порт, хост, окружение);

    • список управляемых сервисов (логическое имя → systemd‑юнит);

    • настройки безопасности (JWT, rate limit, CORS);

    • параметры логирования и аудита;

    • список пользователей и их разрешений (пароли хранятся отдельно).

Пример фрагмента config.yaml:

app:
  port: 8000
  host: "0.0.0.0"
services:
  - name: global-scheduler
    service_name: globalscheduler
security:
  access_token_expire_minutes: 15
users:
  - username: admin
    permissions: ["service:all"]
  - username: viewer
    permissions: ["service:view"]

  • sec/users.json — хешированные пароли пользователей. Автоматически создаётся/обновляется при миграции. Не редактируется вручную (лучше через скрипт или прямую запись хеша).

Автоматическая установка (setup.sh)#

Скрипт setup.sh выполняет полную подготовку окружения:

  • проверяет версию Python (3.11+);

  • создаёт виртуальное окружение и устанавливает зависимости;

  • генерирует самоподписанные SSL‑сертификаты (если отсутствуют);

  • создаёт каталог для логов (по умолчанию /var/log/scheduler-api/);

  • регистрирует systemd‑сервис scheduler-api для автозапуска;

  • настраивает sudo для команд systemctl над указанными сервисами;

  • валидирует конфигурацию.

Запуск:

cd standalone
chmod +x setup.sh
./setup.sh --run

Параметры:

  • --run — запустить API после подготовки;

  • --force — пересоздать venv и переустановить зависимости;

  • --skip-sudo — пропустить настройку sudo;

  • --dry-run — показать план действий без выполнения.

Требования к sudo#

Для выполнения команд systemctl start/stop/restart/status от имени пользователя, под которым работает API, необходим доступ без пароля. Скрипт setup.sh создаёт файл /etc/sudoers.d/scheduler-api примерно такого содержания:

<пользователь> ALL=(ALL) NOPASSWD: /bin/systemctl status globalscheduler
<пользователь> ALL=(ALL) NOPASSWD: /bin/systemctl restart globalscheduler
...

При ручной настройке убедитесь, что эти правила присутствуют.

Запуск без установки (для разработки)#

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 main.py

Сервис будет доступен по адресу http://localhost:8000.
Документация Swagger UI — /docs, ReDoc — /redoc (доступны только в режиме разработки, если app.env: development).

Встроенная документация#

В режиме development (в config.yaml app.env: development) доступны:

  • Swagger UI: /docs — интерактивная документация.

  • ReDoc: /redoc — расширенное отображение спецификации OpenAPI.

Содержание