- Documented architecture, artifacts, and success metrics - Noted LXC+Docker cgroup locking behavior for future fix (Variant B) - Formalized the completion of the secure agent control channel
3.7 KiB
3.7 KiB
📋 Отчет по задаче: F2-3 Remediation API & Agent Control
Статус: ✅ DONE
Дата завершения: 2026-10-07
Ответственный: Admin-Buryans (Roman)
1. Цель задачи
Создать безопасный, контролируемый канал для выполнения административных действий (перезапуск сервисов) через Telegram-бота без предоставления прямого root-доступа агентам.
2. Реализованная архитектура
- Telegram Bot (
comms-agent): Принимает команду от администратора, проверяет права (is_admin), формирует JSON-запрос. - Remediation API (FastAPI на PVE, порт 5000):
- Принимает запросы только с валидным
X-API-Key. - Строгий
allowlistдействий (пока реализовано толькоrestart_service). - Динамически читает карту сервисов из
services_map.json.
- Принимает запросы только с валидным
- Proxmox VE (Hyperwisor): Выполняет команды
pctот имени root, возвращая реальный статус операции.
3. Ключевые артефакты
| Артефакт | Путь | Описание |
|---|---|---|
api.py |
/opt/remediation-api/api.py |
Ядро API на FastAPI с валидацией и выполнением команд. |
services_map.json |
/opt/remediation-api/services_map.json |
Динамическая карта соответствия "Имя сервиса → ID контейнера". |
discover_services.sh |
/opt/remediation-api/discover_services.sh |
Скрипт автообнаружения сервисов (Service Discovery). |
bot.py |
services/comms/telegram-admin-bot/bot.py |
Обновленный код бота с поддержкой Inline-кнопок и динамических запросов. |
| Runbooks | services/*/runbook.md |
29 автоматически сгенерированных runbook'ов для всех сервисов. |
4. Метрики успеха
- ✅ Полностью исключен хардкод ID контейнеров в коде бота.
- ✅ Успешная сквозная проверка: Telegram → Bot → API → Proxmox → Выполнение команды.
- ✅ Реализована ролевая модель (только
ADMIN_IDможет нажимать кнопки).
5. Известные особенности и ограничения (To-Do для Варианта Б)
- Нюанс LXC + Docker: При попытке выполнить
pct stopилиpct rebootна контейнерах, внутри которых запущен Docker (например, CT 155 Matrix, CT 118 Radarr), Proxmox может вернуть ошибкуunable to get PID. Это связано с тем, что демоны Docker/containerd удерживают блокировки cgroups. - План решения: Заменить жесткий
pct stop/startна мягкий перезапуск черезpct exec <vmid> -- systemctl rebootили корректную остановку Docker-демона перед остановкой контейнера.
6. Следующие шаги
- Вариант Б: Исправление механизма перезапуска для LXC с Docker внутри.
- F2-5: [Уточнить из Master Plan, например: Расширение возможностей агентов / Интеграция с Observability].