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 файл або додайте до існуючого:

# 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:

   curl -v https://daarion.space/api/city/health
   

2. Перевірити чи Swapper доступний:

   curl http://localhost:8890/health
   curl http://localhost:8890/models
   

3. Перевірити чи Router доступний:

   curl http://localhost:9102/health
   

4. Перевірити логи guardian на помилки:

   sudo journalctl -u node-guardian --since "10 minutes ago" | grep -i error
   

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

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

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

1. Перевірити чи Swapper реально має моделі:

   curl http://localhost:8890/models | jq
   

2. Перевірити чи guardian правильно парсить відповідь:

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

3. Перевірити чи swapper_state зберігається в БД:

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