Skip to content

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

## Контекст

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

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

### 1. Environment Variables

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

    # 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

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

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

Вміст файлу:

    [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

Активувати:

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

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

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

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

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

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

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

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

    -- Перевірити чи оновлюються метрики для НОДА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:

    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 правильно парсить відповідь:

3. Дивитись логи guardian на повідомлення про Swapper metrics

4. Перевірити чи `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:

    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

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

    ┌─────────────────┐
    │  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`, тому дані не перетираються між нодами.