Это образец раздела документации продукта. Полная и актуальная документация публикуется на homyak.interforum.su; вопросы — на hello@inter-forum.org.
Homyak — система серверного резервного копирования с централизованным хранением и контролем целостности. Состоит из агентов, которые снимают копии и передают их, и сервера хранения, который проверяет целостность принимаемых и хранимых данных, управляет копиями и отдаёт состояние по REST API.
Серверная часть и агенты написаны на Go и собираются из единой моно-репозитории.
| Компонент | Назначение | Платформа |
|---|---|---|
homyak-server | Приём, хранение, контроль целостности, REST API | Linux |
homyak-agent-kvm | Копирование ВМ KVM/libvirt | Linux |
homyak-agent-mssql | Копирование баз MS SQL Server | Windows |
homyak-staging | Консолидированный слепок копий перед выгрузкой | Linux |
Жизненный цикл одной копии — от снятия на агенте до фоновой перепроверки на сервере:
Агент делает копию и считает SHA-256.
Потоковая передача с возобновлением во временный .partial.
Сверка суммы и атомарный rename в финальный файл + манифест.
Фоновый сканер периодически пересчитывает суммы хранимых копий.
Общий HTTP-протокол: агент идентифицируется заголовком, отправляет манифест и поток данных. Загрузка крупных копий устойчива к обрывам (resume). Сервер проверяет соответствие агента, имя файла и контрольную сумму.
POST /api/v1/backups X-Homyak-Agent-Id: mssql-prod-1 # 1) манифест (YAML) + 2) поток данных # resume: повтор с того же смещения при обрыве 201 Created # копия принята и зафиксирована 409 Conflict # имя занято — перезапись запрещена 422 # манифест/сумма не прошли валидацию
Контрольная сумма SHA-256 проверяется при приёме и затем периодически фоновым пересканированием уже сохранённых копий. Расхождения пишутся в отдельный integrity.log и влияют на /health.
Режим «Копилка» — это модель write-once: агент может только добавлять копии. Удаление принятых данных по запросу агента не предусмотрено протоколом; стирание возможно лишь серверной retention-политикой (expires_at) или решением оператора. Без политики копия хранится бессрочно.
Сервер отдаёт машиночитаемое состояние — основа для мониторинга и ИИ-наблюдателей.
| Метод | Назначение |
|---|---|
GET /api/v1/health | Сводное состояние: агенты, целостность, хранилище |
GET /api/v1/backups | Индекс копий с фильтрами и пагинацией |
GET /api/v1/integrity | Зафиксированные проблемы целостности |
POST /api/v1/backups | Приём копии от агента |
Состояние агентов и сервера отдаётся в формате, готовом к снятию метрик Zabbix и Prometheus без дополнительного кода. Heartbeat агентов с настраиваемым тайм-аутом помечает «отвалившиеся» источники; события целостности идут в JSON-лог с ротацией.
Конфигурация — YAML, секреты — в .env. Пример блока контроля целостности:
integrity: verify_on_receive: true background_rescan: enabled: true schedule: "0 3 * * *" # 5-польный crontab affect_health: true max_concurrent: 1 retention: cleanup_interval: "5h"
Модульность (агенты ↔ общий протокол ↔ сервер) позволяет адаптировать систему под инфраструктуру заказчика: