Чек-лист первого запуска

Сразу после того, как install.sh завершился, и вы залогинились как bootstrap-админ, пройдитесь по этому списку. Ничто из этого не требуется, чтобы «начать видеть вещи» — Quickstart работает без всего этого — но каждый пункт закрывает gap до того, как вы передадите систему команде.

1. Установить ONGRID_PUBLIC_URL правильно

Вероятно, самый важный пункт. Этот URL — это то, что ваши edge'и используют для плоскости данных — логи пушат на <url>/loki/api/v1/push, трейсы пушат на <url>/v1/traces.

Проверьте, что заполнил install.sh:

sudo grep '^ONGRID_PUBLIC_URL=' /opt/ongrid/.env

Если вы приняли внутренний адрес, но ваши edge'и живут в публичном интернете, логи и трейсы будут молча падать — туннель всё ещё работает (у него свой порт), так что edge выглядит здоровым.

Чтобы починить:

# Edit
sudo sed -i 's|^ONGRID_PUBLIC_URL=.*|ONGRID_PUBLIC_URL=https://ops.example.com|' /opt/ongrid/.env

# Restart the affected services
sudo docker compose -f /opt/ongrid/docker-compose.yml --env-file /opt/ongrid/.env up -d ongrid nginx

Вам не нужно передеплоивать edge'и; агент периодически перечитывает data-plane эндпоинт от manager.

См. ONGRID_PUBLIC_URL.

2. Сконфигурировать дефолтный LLM provider

Из коробки provider не сконфигурирован. Агент откажется думать.

1. Settings → Models. Выберите одного из:
   • OpenAI (gpt-5.4 по умолчанию)
   • Anthropic (claude-opus-4-7 по умолчанию)
   • Zhipu (glm-4.7 по умолчанию)
   • DeepSeek (deepseek-v4-flash по умолчанию)
   • Gemini (gemini-2.5-pro по умолчанию)
   • Kimi (kimi-k2.6 по умолчанию)
   • Custom OpenAI-совместимый (vLLM, Ollama, OpenRouter, корпоративный relay…)
2. Вставьте API-ключ. Опционально: override дефолтной модели в "Advanced".
3. Save. Pre-registration — hot — без рестарта.
4. На той же странице поставьте Default provider на тот, который вы только что подключили.

Не путайте default_provider и per-route модели

«Default» управляет back-end LLM вызовами (alert investigation, translate, summarize). Model picker в chat-заголовке — это per-thread override — полезно для «попробую Opus на этот один вопрос», но site default — это то, что запускается для cron-job'ов и incident'ов.

См. записи Routing & default и Budget & limits под Models в сайдбаре.

3. Сконфигурировать канал уведомлений

Даже если у вас пока нет alert-правил, подключите один канал, чтобы будущие incident'ы имели куда приземлиться.

Рекомендуемая стартовая пара:

• Webhook-канал на generic incoming-webhook collector (вы всегда можете удалить его позже) — доказывает, что путь уведомлений работает.
• Один IM-канал — Telegram — самый простой, потому что вам нужны только bot-токен и chat ID; Slack/Lark/DingTalk/WeCom требуют больше setup'а.

См. обзор каналов.

4. Установить timezone manager

Time stamps в incident-таймлайнах и alert-event'ах следуют timezone manager. По умолчанию — UTC внутри контейнера; для UI, который соответствует вашей команде:

# Set TZ in compose env. Edit /opt/ongrid/docker-compose.yml or drop a
# /opt/ongrid/docker-compose.override.yml with:
services:
  ongrid:
    environment:
      TZ: Asia/Shanghai

sudo docker compose -f /opt/ongrid/docker-compose.yml --env-file /opt/ongrid/.env up -d ongrid

Для AI output locale (отвечает ли LLM на английском или китайском), поставьте ONGRID_DEFAULT_LOCALE. По умолчанию en; валидные значения соответствуют вашим UI-переводам (en, zh-CN, ja, …). Каналы могут override per-channel; ручные UI-запросы следуют Accept-Language.

5. Решить retention Prometheus

Compose по умолчанию — 90 дней / 20 GB cap. Чтобы изменить:

# /opt/ongrid/docker-compose.override.yml
services:
  prometheus:
    command:
      - --storage.tsdb.path=/prometheus
      - --storage.tsdb.retention.time=30d
      - --storage.tsdb.retention.size=10GB
      - --web.enable-remote-write-receiver
      - --web.enable-lifecycle
      - --web.external-url=/prometheus/
      - --web.route-prefix=/prometheus/
      - --config.file=/etc/prometheus/prometheus.yml

sudo docker compose -f /opt/ongrid/docker-compose.yml --env-file /opt/ongrid/.env up -d prometheus

Для retention Loki отредактируйте /opt/ongrid/loki-config.yaml и рестартните loki-контейнер. Для Tempo отредактируйте /opt/ongrid/tempo-config.yaml.

6. Решить, держать ли встроенные Loki / Tempo

Если вы уже запускаете managed log/trace бэкенды (Grafana Cloud, Honeycomb, Splunk, ваш собственный VictoriaLogs / VictoriaTraces…), вы можете:

• Держать встроенные как data sink, который агент запрашивает (самый дешёвый путь, без дополнительной инфры).
• Свопнуть их, направив агента на managed URL через ONGRID_LOG_QUERY_URL / ONGRID_TRACE_QUERY_URL, и реконфигурировав promtail / otelcol каждого edge, чтобы пушить туда напрямую.

Для гибридного setup'а (edge'и пушат в оба), положите кастомный promtail.yaml / otelcol.yaml в /etc/ongrid-edge/ на каждом edge, и агент подхватит.

См. возможность логов и возможность трейсов.

7. Заменить self-signed TLS-сертификат

Для пробного использования — нормально. Для prod сертификат в /opt/ongrid/certs/:

sudo cp fullchain.pem /opt/ongrid/certs/tls.crt
sudo cp privkey.pem   /opt/ongrid/certs/tls.key
sudo chmod 600        /opt/ongrid/certs/tls.key
sudo chmod 644        /opt/ongrid/certs/tls.crt
sudo docker compose -f /opt/ongrid/docker-compose.yml restart nginx

install.sh и upgrade.sh никогда не перезаписывают operator-сертификаты.

8. Бэкапить /var/lib/ongrid и /opt/ongrid/.env

Всё stateful живёт под этими двумя путями:

• /opt/ongrid/.env — секреты (JWT, MySQL, admin password, embed keys).
• /var/lib/ongrid/mysql/ — всё operational-состояние. Всё, что вы не можете потерять, живёт здесь: edge'и, alert-правила, incident'ы, channel- конфиги, audit log, кастомные скиллы, knowledge-метаданные.
• /var/lib/ongrid/qdrant/ — векторные embeddings (восстанавливаемо из исходных доков, но дорого).
• /var/lib/ongrid/prometheus/, loki/, tempo/ — телеметрия; бэкап только если вам нужен длинный retention.

Простой cron + rsync (или restic) этих двух корней даёт вам disaster recovery. Восстановление = остановить стек, заменить директории, запустить стек.

9. Настроить реальный admin-аккаунт

Email bootstrap-админа — это то, что вы (или install.sh) положили в ONGRID_ADMIN_EMAIL. Для реальной команды:

1. Settings → Identity → Users → Invite user для каждого реального оператора.
2. Назначьте каждому роль: admin, user или viewer (ADR-022 RBAC).
   • admin — полный контроль.
   • user — может чатиться с агентом, смотреть incident'ы, mute алерты. Toolbag отфильтрован до ClassSafe.
   • viewer — read-only chat (без write-скиллов), read-only incident'ы.
3. Понизьте bootstrap admin'а, если хотите, или просто перестаньте его использовать.

10. Триггернуть первый incident (smoke test)

Заставьте одно из встроенных правил сработать. Самое простое: остановите один из ваших edge'ей.

sudo systemctl stop ongrid-edge

В пределах ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD (по умолчанию 90с) плюс интервал evaluator (по умолчанию 5м), правило edge_offline срабатывает. UI:

• Alerts — новое событие.
• Incidents — новая incident-группировка этого события.
• Channels — ваш подключённый канал получает карточку.

Если вы настроили IM-канал, ответьте боту «investigate this». Incident investigator запускается end-to-end и постит обратно отчёт.

Перезапустите edge:

sudo systemctl start ongrid-edge

Incident автоматически переходит в mitigated, когда правило перестаёт срабатывать; вы помечаете его resolved из UI.

Что дальше

• Обзор каналов — подключите ваши реальные on-call каналы.
• Возможность алертов — авторируйте кастомные правила сверх 6 встроенных.
• Апгрейд — когда v0.7.X+1 выходит.
• Reference / env — каждая ONGRID_* tunable.