Complete markdown documentation

2026-06-21 12:49:56 +00:00
parent c77065756d
commit 9331ee1d89
11 changed files with 680 additions and 135 deletions
@@ -0,0 +1,148 @@
+# Troubleshooting
+
+Этот документ помогает быстро проверить типовые проблемы при запуске и работе Crank.
+
+## Веб-интерфейс открывается, но данные не загружаются
+
+Проверьте `admin-api`:
+
+```bash
+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
+
+Проверьте, на каком адресе опубликованы контейнеры:
+
+```bash
+docker compose ps
+```
+
+Если nginx работает на другом host, в `.env` нужно:
+
+```env
+CRANK_PUBLISH_BIND=0.0.0.0
+```
+
+Если nginx работает на том же host, обычно достаточно:
+
+```env
+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 ожидаемый инструмент:
+
+```text
+frankfurter_latest_rate
+```
+
+## Тест операции возвращает ошибку внешнего API
+
+Откройте preview запроса в wizard-е и проверьте:
+
+- `base_url`;
+- `path_template`;
+- HTTP method;
+- query/path/body mapping;
+- auth profile;
+- статические заголовки.
+
+Для Frankfurter рабочий запрос:
+
+```text
+GET https://api.frankfurter.dev/v1/latest?base=USD&symbols=EUR
+```
+
+## Секрет не виден после создания
+
+Это ожидаемое поведение. Crank шифрует секрет и больше не возвращает его значение через UI или API.
+
+Если значение нужно заменить, используйте **Ротировать**.
+
+## После обновления не появился demo-пример
+
+Проверьте:
+
+```env
+CRANK_DEMO_SEED=true
+```
+
+Затем перезапустите `admin-api`:
+
+```bash
+docker compose up -d admin-api
+```
+
+Seed идемпотентный: он не создает дубликаты, но поддерживает Frankfurter-пример.
+
+## Контейнеры не стартуют из-за занятых портов
+
+Проверьте, кто занимает порт:
+
+```bash
+docker ps --format 'table {{.Names}}\t{{.Ports}}'
+sudo ss -ltnp
+```
+
+Чаще всего конфликтуют:
+
+- `3000` - UI;
+- `3001` - Admin API;
+- `3002` - MCP server;
+- `5432` - PostgreSQL, если включен profile `local-db`.
+
+## PostgreSQL недоступен
+
+Проверьте доступность из контейнера:
+
+```bash
+docker compose exec admin-api sh -lc 'nc -vz "$POSTGRES_HOST" "$POSTGRES_PORT"'
+```
+
+Проверьте переменные:
+
+```bash
+docker compose exec admin-api env | grep POSTGRES
+```
+
+## Где смотреть логи
+
+```bash
+docker compose logs -f admin-api
+docker compose logs -f mcp-server
+docker compose logs -f ui
+```
+
+Для подробных логов временно укажите:
+
+```env
+CRANK_LOG_LEVEL=debug
+```
+