Эксплуатация и обновление

Бэкапы

Полный бэкап состоит из двух частей:

1. База данных — файл SQLite или дамп PostgreSQL.
2. S3-бакет — вложения, аватары и артефакты.

Каталог данных также содержит process-логи, полезные для отладки, но не нужные для восстановления.

SQLite, с остановленной agency:

systemctl stop cherrypi-agency
tar -czf cherrypi-agency-$(date +%F).tar.gz \
  -C /var/lib/cherrypi agency
systemctl start cherrypi-agency

PostgreSQL:

pg_dump --format=custom --file=cherrypi.dump 'postgres://…'

MinIO / S3: используйте версионирование и lifecycle провайдера либо зеркальте бакет через mc mirror / aws s3 sync.

Проверяйте восстановление

Бэкап, который ни разу не восстанавливали, — это догадка. Восстановите базу и бакет в staging-agency и убедитесь, что вложения и история задач открываются.

Обновление

Docker:

docker pull ghcr.io/cherrypidotdev/cherrypi-agency:latest
docker compose up -d agency

Бинарник:

systemctl stop cherrypi-agency
install -m 0755 cherrypi-agency /usr/local/bin/cherrypi-agency
systemctl start cherrypi-agency

Миграции применяются при старте. Они только вперёд: для отката восстановите бэкап, сделанный до обновления.

Агентов обновляйте отдельно. Agency показывает сборку и версию протокола каждого агента; устаревший агент может работать, но терять новые возможности. Если агент отстаёт на несколько версий протокола, agency помечает его несовместимым и перестаёт планировать на него задачи.

Логи

• Process-лог agency — Settings → Logs, а также файлы с метками времени в $CHERRYPI_AGENCY_DIR/logs. Можно смотреть в реальном времени и скачивать.
• Process-лог агента — вкладка Logs на странице агента: запуск, подключение, жизненный цикл задач и ошибки.
• Консоль задачи — живой транскрипт Pi, включая вызовы инструментов и ошибки.
• Логи контейнера — docker logs cherrypi-agency для ошибок до появления process-лога.

CHERRYPI_AGENCY_LOG_FILES задаёт, сколько process-логов хранить.

Retention

Администраторы настраивают retention логов и истории в Settings. Pruning удаляет старые операционные записи, а не задачи или пользовательские данные. Артефакты и вложения удаляются вместе с задачей или по lifecycle-правилам бакета.

Размеры ресурсов

Развёртывание	Рекомендации
Личное / небольшая команда	1 vCPU, 1 ГБ RAM, SQLite, 10 ГБ диска + бакет.
Команда с множеством параллельных задач	2 vCPU, 2–4 ГБ RAM, PostgreSQL, управляемый бакет.

Agency стримит большие payload'ы терминалов и рабочего стола, но не запускает модели и не выполняет код задач. Масштабируйте машины агентов под CPU, RAM и диск.

Production-чеклист

• [ ] TLS терминируется reverse proxy; порт agency не публичен.
• [ ] CHERRYPI_PUBLIC_URL — реальный HTTPS origin.
• [ ] Пароль bootstrap-администратора изменён.
• [ ] Настроены SMTP и/или провайдер идентичности; хотя бы один админ всегда может войти.
• [ ] S3-бакет приватный, версионируется и бэкапится.
• [ ] База и бакет бэкапятся по расписанию, восстановление проверено.
• [ ] Read timeout reverse proxy отключён для долгих потоков.
• [ ] Agency и все агенты на поддерживаемых версиях.
• [ ] Каталоги данных агентов на постоянном хранилище.
• [ ] Разрешён egress агентов к agency; входящий порт агента не открыт.

Решение проблем

Смотрите Решение проблем: ошибки запуска и хранилища, агент offline, проблемы WebSocket через прокси и пропавшие вложения.