crank/docs/troubleshooting.md

Troubleshooting

Этот документ помогает быстро проверить типовые проблемы при запуске и работе Crank.

Веб-интерфейс открывается, но данные не загружаются

Проверьте admin-api:

curl http://127.0.0.1:3001/health
docker compose logs -f admin-api

Типовые причины:

• admin-api не подключился к PostgreSQL;
• неверные POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD;
• reverse proxy не проксирует /api/admin/;
• браузерная сессия истекла.

502 Bad Gateway через nginx

Проверьте, на каком адресе опубликованы контейнеры:

docker compose ps

Если nginx работает на другом host, в .env нужно:

CRANK_PUBLISH_BIND=0.0.0.0

Если nginx работает на том же host, обычно достаточно:

CRANK_PUBLISH_BIND=127.0.0.1

MCP-клиент получает 401 Unauthorized

Проверьте:

• API-ключ создан именно для нужного агента;
• ключ передается как Authorization: Bearer <key>;
• ключ не был удален или отозван;
• MCP URL содержит правильные workspace_slug и agent_slug.

MCP-клиент не видит инструмент

Проверьте:

• операция опубликована;
• операция привязана к агенту;
• агент опубликован;
• ключ выдан на этого агента;
• прошел интервал CRANK_MCP_REFRESH_MS.

Для demo seed ожидаемый инструмент:

frankfurter_latest_rate

Тест операции возвращает ошибку внешнего API

Откройте preview запроса в wizard-е и проверьте:

• base_url;
• path_template;
• HTTP method;
• query/path/body mapping;
• auth profile;
• статические заголовки.

Для Frankfurter рабочий запрос:

GET https://api.frankfurter.dev/v1/latest?base=USD&symbols=EUR

Секрет не виден после создания

Это ожидаемое поведение. Crank шифрует секрет и больше не возвращает его значение через UI или API.

Если значение нужно заменить, используйте Ротировать.

После обновления не появился demo-пример

Проверьте:

CRANK_DEMO_SEED=true

Затем перезапустите admin-api:

docker compose up -d admin-api

Seed идемпотентный: он не создает дубликаты, но поддерживает Frankfurter-пример.

Контейнеры не стартуют из-за занятых портов

Проверьте, кто занимает порт:

docker ps --format 'table {{.Names}}\t{{.Ports}}'
sudo ss -ltnp

Чаще всего конфликтуют:

• 3000 - UI;
• 3001 - Admin API;
• 3002 - MCP server;
• 5432 - PostgreSQL, если включен profile local-db.

PostgreSQL недоступен

Проверьте доступность из контейнера:

docker compose exec admin-api sh -lc 'nc -vz "$POSTGRES_HOST" "$POSTGRES_PORT"'

Проверьте переменные:

docker compose exec admin-api env | grep POSTGRES

Где смотреть логи

docker compose logs -f admin-api
docker compose logs -f mcp-server
docker compose logs -f ui

Для подробных логов временно укажите:

CRANK_LOG_LEVEL=debug