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

Начните с process-лога: Settings → Logs в agency, вкладка Logs на агенте и консоль задачи для ошибок уровня задачи.

Agency не запускается

Симптом	Вероятная причина
Embedded frontend unavailable	Сборка из исходников без SPA; выполните make build или используйте релиз.
Embedded docs unavailable	Сборка из исходников без документации; выполните make docs copy_docs.
Invalid CHERRYPI_*	Некорректное значение окружения; в логе названа переменная.
Ошибка хранилища при старте	Неверный endpoint, бакет, регион или ключи; читайте подсказку.

Проверка хранилища при старте

Agency вызывает HeadBucket при запуске. Ошибка прерывает boot с указанием бакета, endpoint и стиля адресации. Частые решения:

• создайте бакет заранее;
• используйте CHERRYPI_S3_FORCE_PATH_STYLE=true для MinIO за прокси без wildcard TLS;
• задайте реальный регион (CHERRYPI_S3_REGION), включая не-AWS;
• выдайте ключу s3:ListBucket/s3:HeadBucket.

Агент остаётся offline

1. Процесс агента жив? docker logs cherrypi-agent или journalctl -u cherrypi-agent.
2. В логе есть Tunneling to agency …? Если нет, URL неверен или процесс падает при старте.
3. Хост достаёт agency? curl -fsS https://cherrypi.example.com/api/rest/health.
4. Токен верный? Выпустите новый personal access token на странице агента и передайте его через --token или CHERRYPI_AGENT_TOKEN. Отвергнутый кэшированный токен удаляется при старте с пояснением в логе.
5. Туннель не блокирует прокси? Разрешите WebSocket на /api/tunnel/ws и отключите read timeout. Не форсируйте h2c на upstream.
6. Версия агента совместима? Проверьте бейдж и лог agency.

После ротации токена перезапустите агента, чтобы он взял новый токен.

Задача не стартует

• Нет подходящего агента — исполнитель должен быть участником проекта задачи и иметь свободный слот. Проверьте доступ и лимиты агента.
• Агент offline — планировщик не отправляет работу отключённому агенту.
• Впереди очередь — задачи выполняются по порядку.
• Сразу упала — читайте консоль задачи и лог агента; частая причина — отсутствующая конфигурация Pi или креденшелы модели.

WebSocket и стриминг не работают

Симптомы: терминалы сразу закрываются, инбокс не обновляется, туннель рвётся, рабочий стол отключается.

• Держите upstream на HTTP/1.1; не включайте h2c-first.
• Отключите read timeout и buffering для долгих маршрутов.
• Пропускайте заголовки Upgrade и Connection.
• Прокси должен поддерживать WebSocket; Caddy и nginx умеют.

Вложения не работают

Ошибка	Решение
storage is not configured	Задайте CHERRYPI_S3_ENDPOINT и CHERRYPI_S3_BUCKET.
403 от бакета	Проверьте ключи, политику и регион.
Файл слишком большой	Увеличьте CHERRYPI_ATTACHMENT_MAX_BYTES или уменьшите файл.
Изображения не видны в Pi	Агент не может скачать вложения; проверьте его токен.

Magic link или приглашения не приходят

Настройте SMTP в Settings → Authentication. Без SMTP UI показывает ссылку для копирования. Не включайте CHERRYPI_AUTH_EXPOSE_MAGIC_LINKS в production.

Циклы входа и secure cookie

• CHERRYPI_PUBLIC_URL должен совпадать с внешним origin, включая схему.
• Терминируйте TLS на прокси и передавайте X-Forwarded-Proto.
• Очистите старые cookie после смены hostname.

Документация отдаёт 404

Релизные сборки встраивают /docs. Dev-сборка без CHERRYPI_DOCS_PROXY_URL не имеет ассетов документации; запустите dev-сервер документации и задайте прокси либо выполните make docs copy_docs перед make build_agency.

Как получить помощь

Откройте issue и приложите:

• версию agency (футер или лог запуска);
• версию агента и статус протокола;
• релевантный фрагмент лога;
• reverse proxy и backend базы/хранилища.

GitHub Issues.