161 lines
6.0 KiB
Markdown
161 lines
6.0 KiB
Markdown
# Aide → Kraken Backend: план настройки
|
||
|
||
> Создано: 2026-05-13
|
||
> Статус: ✅ работает (Aide + SpeakGPT)
|
||
|
||
## Цель
|
||
|
||
Сделать Кракена бэкендом для приложения **Aide** на Android — как замена Siri/Google Assistant с Hermes вместо Claude API напрямую.
|
||
|
||
---
|
||
|
||
## Почему это реализуемо
|
||
|
||
- Hermes gateway уже поддерживает **OpenAI-compatible API server** (`gateway/platforms/api_server.py`)
|
||
- Endpoint: `POST /v1/chat/completions` — именно то, что ожидает Aide (BYOK → Custom Endpoint)
|
||
- Кракен работает в режиме `network_mode: host` → порт 8642 будет доступен напрямую на хосте
|
||
- cloudflared уже запущен на Кракене (туннель `kraken` активен) → достаточно добавить hostname
|
||
|
||
---
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
Android (Aide)
|
||
└── HTTPS → hermes.kraken.qentra.top/v1/chat/completions
|
||
↓ Cloudflare Tunnel
|
||
cloudflared (контейнер на Кракене, host network)
|
||
↓ localhost
|
||
hermes-kraken:8642 (API server)
|
||
↓
|
||
Hermes gateway → Gemini / OpenRouter / ...
|
||
```
|
||
|
||
---
|
||
|
||
## Шаги
|
||
|
||
### Шаг 1 — Включить API server в Hermes (config.yaml на Кракене)
|
||
|
||
Добавить в `/opt/data/config.yaml`:
|
||
|
||
```yaml
|
||
api_server:
|
||
enabled: true
|
||
port: 8642
|
||
host: "0.0.0.0" # слушать на всех интерфейсах (CF туннель на хосте)
|
||
key: "СГЕНЕРИРОВАТЬ_СЕКРЕТ" # openssl rand -hex 32
|
||
```
|
||
|
||
Перезапустить контейнер:
|
||
```bash
|
||
BASE=http://localhost:9000
|
||
KEY="ptr_AJY+Ba9A7f6pcAHZfDD5koU4stkKgJCdbTEXLDLxn0g="
|
||
EP=3
|
||
|
||
CID=$(curl -s -H "X-API-Key: $KEY" "$BASE/api/endpoints/$EP/docker/containers/json" \
|
||
| jq -r '.[] | select(.Names[] | contains("hermes-kraken")) | .Id')
|
||
|
||
curl -s -X POST -H "X-API-Key: $KEY" "$BASE/api/endpoints/$EP/docker/containers/$CID/restart"
|
||
```
|
||
|
||
Проверить:
|
||
```bash
|
||
curl -s http://localhost:8642/health
|
||
# → {"status":"ok","version":"..."}
|
||
```
|
||
|
||
### Шаг 2 — Изменить hostname в CF Zero Trust
|
||
|
||
В **Cloudflare Zero Trust** → Networks → Tunnels → `kraken` → Edit → Public Hostnames → найти `kraken.qentra.top`:
|
||
|
||
Изменить:
|
||
- Type: `SSH` → `HTTP`
|
||
- URL: `localhost:22` → `localhost:8642`
|
||
|
||
Сохранить. Результат: `https://kraken.qentra.top` → Кракен:8642
|
||
|
||
> Делается через CF Zero Trust Dashboard — нужен Alex.
|
||
|
||
Проверить после изменения:
|
||
```bash
|
||
curl -s https://kraken.qentra.top/health
|
||
```
|
||
|
||
### Шаг 3 — Настроить Aide на Android
|
||
|
||
В Aide → Providers → Add Provider → Custom Endpoint:
|
||
|
||
| Поле | Значение |
|
||
|------|----------|
|
||
| Base URL | `https://kraken.qentra.top/v1` |
|
||
| API Key | секрет из config.yaml |
|
||
| Model | `hermes-agent` (или любое — маппится на Hermes) |
|
||
|
||
### Шаг 4 — Настроить SpeakGPT
|
||
|
||
В SpeakGPT → Settings → API:
|
||
|
||
| Поле | Значение |
|
||
|------|----------|
|
||
| Base URL | `https://kraken.qentra.top/v1` |
|
||
| API Key | секрет из config.yaml |
|
||
| Model | `hermes-agent` |
|
||
|
||
> **Важно:** Base URL обязательно должен заканчиваться на `/v1`, иначе SpeakGPT стучится в корень `/chat/completions`, который не существует.
|
||
|
||
---
|
||
|
||
## Заметки по эксплуатации
|
||
|
||
### Туннель нестабилен — `sendmsg: network is unreachable`
|
||
|
||
Иногда после старта cloudflared начинает циклически падать с ошибкой `write udp: sendmsg: network is unreachable` — проблема с IPv6/UDP на RPi5.
|
||
|
||
**Решение:** пересоздать контейнер с флагом `--protocol http2`:
|
||
```bash
|
||
docker run --rm --network host cloudflare/cloudflared tunnel --no-autoupdate --protocol http2 run --token <TOKEN>
|
||
```
|
||
|
||
После запуска проверить 4/4 Registered в логах.
|
||
|
||
### После пересоздания cloudflared — Cloudflare может выдать 403
|
||
|
||
При смене connector ID (после пересоздания контейнера) Cloudflare WAF может начать блокировать запросы с незнакомых IP. Запросы с телефона (Aide, SpeakGPT) обычно проходят, так как используют мобильный User-Agent.
|
||
|
||
Если 403 — проверить Cloudflare Zero Trust Dashboard:
|
||
- **Access → Applications** — нет ли лишних правил для `kraken.qentra.top`
|
||
- Или просто подождать — кэш обновляется
|
||
|
||
---
|
||
|
||
## О cloudflared
|
||
|
||
SSH через CF (`kraken.qentra.top → SSH → localhost:22`) не используется — SSH ходит через VPS на порту 2223. Поэтому hostname просто перенастраивается с SSH на HTTP без потери функциональности.
|
||
|
||
---
|
||
|
||
## Что НЕ нужно менять
|
||
|
||
- ✅ Контейнер cloudflared — уже запущен и работает
|
||
- ✅ Reverse SSH туннель на VPS — не трогаем, SSH доступ остаётся
|
||
- ✅ network_mode: host у hermes-kraken — порт 8642 сразу на хосте
|
||
|
||
---
|
||
|
||
## Что нужно от Alex
|
||
|
||
1. Сгенерировать API ключ: `openssl rand -hex 32` (сохранить в `.env` или config)
|
||
2. Добавить hostname в CF Zero Trust (вебинтерфейс)
|
||
3. Ввести endpoint + ключ в Aide
|
||
|
||
Всё остальное Орёл сделает сам.
|
||
|
||
---
|
||
|
||
## Связанные заметки
|
||
|
||
- [[kraken-access]] — SSH и Portainer доступ к Кракену
|
||
- [[kraken-portainer-access]] — Portainer API команды
|
||
- [[openmediavault-rpi5]] — структура Docker на Кракене
|