microdao-daarion/docs/NODE2_GUARDIAN_SETUP.md

# Налаштування Node Guardian для НОДА2

## Контекст

Node Guardian — це сервіс, який періодично збирає метрики з DAGI Router та Swapper Service та оновлює їх в `node_cache` таблиці БД. Це дозволяє UI показувати актуальний стан нод.

## Налаштування для НОДА2 (MacBook)

### 1. Environment Variables

Створіть `.env` файл або додайте до існуючого:

```bash
# Node Identity
NODE_ID=node-2-macbook-m4max
NODE_NAME=НОДА2
NODE_ENVIRONMENT=development
NODE_ROLES=gpu,ai_runtime
NODE_HOSTNAME=$(hostname)

# City Service URL (HTTPS для проді)
CITY_SERVICE_URL=https://daarion.space/api/city

# Node-specific service URLs (для НОДА2 - localhost)
NODE_SWAPPER_URL=http://localhost:8890
NODE_ROUTER_URL=http://localhost:9102

# Guardian interval (секунди)
GUARDIAN_INTERVAL=60
```

### 2. Запуск Node Guardian

#### Як фонове завдання (рекомендовано)

```bash
# Створити systemd service
sudo nano /etc/systemd/system/node-guardian.service
```

Вміст файлу:

```ini
[Unit]
Description=DAARION Node Guardian
After=network.target

[Service]
Type=simple
User=$USER
WorkingDirectory=/path/to/microdao-daarion
EnvironmentFile=/path/to/.env
ExecStart=/usr/bin/python3 /path/to/microdao-daarion/scripts/node-guardian-loop.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Активувати:

```bash
sudo systemctl daemon-reload
sudo systemctl enable node-guardian
sudo systemctl start node-guardian
sudo systemctl status node-guardian
```

#### Або вручну

```bash
cd /path/to/microdao-daarion
python3 scripts/node-guardian-loop.py
```

### 3. Перевірка роботи

#### Перевірити логи

```bash
# Якщо systemd service
sudo journalctl -u node-guardian -f

# Або якщо запущено вручну - дивитись stdout
```

#### Перевірити в БД

```sql
-- Перевірити чи оновлюються метрики для НОДА2
SELECT 
    node_id,
    swapper_healthy,
    swapper_models_loaded,
    swapper_models_total,
    router_healthy,
    router_version,
    last_heartbeat,
    updated_at
FROM node_cache
WHERE node_id = 'node-2-macbook-m4max'
ORDER BY updated_at DESC
LIMIT 1;
```

#### Перевірити Swapper State

```sql
SELECT 
    node_id,
    swapper_state->'models' as models
FROM node_cache
WHERE node_id = 'node-2-macbook-m4max'
  AND swapper_state IS NOT NULL;
```

### 4. Troubleshooting

#### Guardian не оновлює метрики

1. Перевірити з'єднання з city-service:
   ```bash
   curl -v https://daarion.space/api/city/health
   ```

2. Перевірити чи Swapper доступний:
   ```bash
   curl http://localhost:8890/health
   curl http://localhost:8890/models
   ```

3. Перевірити чи Router доступний:
   ```bash
   curl http://localhost:9102/health
   ```

4. Перевірити логи guardian на помилки:
   ```bash
   sudo journalctl -u node-guardian --since "10 minutes ago" | grep -i error
   ```

#### Помилки авторизації (401/403)

- Перевірити що `CITY_SERVICE_URL` правильний
- Перевірити що немає старого токена в конфігурації
- Перевірити що city-service доступний з MacBook

#### Swapper показує 0 моделей

1. Перевірити чи Swapper реально має моделі:
   ```bash
   curl http://localhost:8890/models | jq
   ```

2. Перевірити чи guardian правильно парсить відповідь:
   - Дивитись логи guardian на повідомлення про Swapper metrics

3. Перевірити чи `swapper_state` зберігається в БД:
   ```sql
   SELECT swapper_state FROM node_cache WHERE node_id = 'node-2-macbook-m4max';
   ```

---

## Налаштування для НОДА1 (Production Server)

На НОДА1 guardian зазвичай запускається автоматично через docker-compose або systemd.

### ENV змінні для НОДА1

```bash
NODE_ID=node-1-hetzner-gex44
NODE_NAME=НОДА1
NODE_ENVIRONMENT=production
NODE_SWAPPER_URL=http://swapper-service:8890  # Docker service name
NODE_ROUTER_URL=http://dagi-router:9102        # Docker service name
CITY_SERVICE_URL=https://daarion.space/api/city
```

---

## Архітектура

```text
┌─────────────────┐
│  Node Guardian  │ (на кожній ноді)
│  (loop script)  │
└────────┬────────┘
         │
         ├─→ Swapper API (/health, /models)
         ├─→ Router API (/health)
         │
         ▼
┌─────────────────┐
│  City Service   │
│  /heartbeat     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   PostgreSQL    │
│   node_cache    │
└─────────────────┘
         │
         ▼
┌─────────────────┐
│   UI (Frontend) │
│   Node Cabinet  │
└─────────────────┘
```

---

## Важливі моменти

1. **Один Router/Swapper для всіх нод у проді**:
   На НОДА1 є один DAGI Router та один Swapper Service, які обслуговують всі ноди.
   Guardian на кожній ноді просто збирає метрики та пушить їх в БД
   з правильним `node_id`.

2. **ENV змінні мають пріоритет**:
   Guardian використовує `NODE_SWAPPER_URL` та `NODE_ROUTER_URL` з ENV,
   якщо вони встановлені. Це дозволяє для НОДА2 використовувати `localhost`,
   а для НОДА1 - Docker service names.

3. **Heartbeat оновлює node_cache**: Кожен heartbeat оновлює метрики в `node_cache` для конкретного `node_id`, тому дані не перетираються між нодами.