github-ops
149 lines
3.9 KiB
Markdown
149 lines
3.9 KiB
Markdown
# 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
|
|
```
|
|
|