首次启动清单

install.sh 跑完、你用引导管理员登录进去之后，过一遍这份清单。这些都不是"开始能看到东西"的必备项——快速开始不配这些也能跑——但每一条都在你把系统交给团队之前补上一个缺口。

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；agent 会定期从 manager 重读数据面端点。

参见 ONGRID_PUBLIC_URL。

2. 配默认 LLM provider

开箱时没配任何 provider。Agent 会拒绝思考。

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-compatible（vLLM、Ollama、OpenRouter、公司中继……）
2. 贴 API key。可选：在 "Advanced" 里覆盖默认模型。
3. Save. 预注册是热的——不用重启。
4. 在同一页把 Default provider 设成你刚配的那个。

别混淆 default_provider 和 per-route 模型

"default" 驱动后端 LLM 调用（告警调查、翻译、总结）。Chat 顶部的 model picker 是当前线程级覆盖——适合"试试这道题让 Opus 答"，但 cron 任务和 incident 跑的是站点默认。

参见边栏 Models 下的 Routing & default 和 Budget & limits 条目。

3. 配一个通知通道

就算还没写告警规则，也先接一个通道，让未来的 incident 有地方落。

推荐的入门搭配：

• 一个 Webhook 通道指到通用 incoming-webhook 收集器（之后随时可删）——证明通知链路可用。
• 一个 IM 通道 —— Telegram 最容易，只需要 bot token 和 chat ID；Slack/飞书/钉钉/企业微信配起来麻烦点。

参见通道概览。

4. 设 manager 时区

Incident timeline 和告警事件里的时间戳跟随 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 输出语言（LLM 用英文还是中文回答），设 ONGRID_DEFAULT_LOCALE。默认 en；合法值跟 UI 翻译一致（en、zh-CN、ja ……）。通道可以按通道覆盖；UI 手动触发跟随 Accept-Language。

5. 决定 Prometheus 保留

Compose 默认 90 天 / 20 GB 上限。要改：

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

Loki 保留改 /opt/ongrid/loki-config.yaml，然后重启 loki 容器。Tempo 改 /opt/ongrid/tempo-config.yaml。

6. 决定要不要留内置 Loki / Tempo

如果你已经有托管日志/链路后端（Grafana Cloud、Honeycomb、Splunk、自己的 VictoriaLogs / VictoriaTraces……），可以：

• 留内置的作为 agent 查询的 sink（最省，没额外基建）。
• 换掉：通过 ONGRID_LOG_QUERY_URL / ONGRID_TRACE_QUERY_URL 把 agent 指到托管 URL，并重配每个 edge 的 promtail / otelcol 直接推到那边。

混合（edge 同时推到两边）：在每个 edge 的 /etc/ongrid-edge/ 里放自定义 promtail.yaml / otelcol.yaml，agent 会自动取用。

参见日志能力和链路能力。

7. 换掉自签名 TLS 证书

试用够用。生产把证书放到 /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 永不覆盖运维放的证书。

8. 备份 /var/lib/ongrid 和 /opt/ongrid/.env

所有有状态的东西都在这两个路径下：

• /opt/ongrid/.env —— secrets（JWT、MySQL、admin 密码、embed key）。
• /var/lib/ongrid/mysql/ —— 所有运行态。不能丢的东西都在这：edge、告警规则、incident、通道配置、审计日志、自定义技能、知识库元数据。
• /var/lib/ongrid/qdrant/ —— 向量 embedding（可从源文档重建，但开销大）。
• /var/lib/ongrid/prometheus/、loki/、tempo/ —— 遥测；要长保留时再备。

一个简单的 cron + rsync（或 restic）打这两个根，就有了 DR。恢复 = 停栈、替目录、起栈。

9. 建一个真实管理员账号

引导管理员的 email 就是你（或 install.sh）填进 ONGRID_ADMIN_EMAIL 的那个。给真实团队：

1. Settings → Identity → Users → Invite user 给每个真实运维。
2. 每人分配一个角色：admin、user、或 viewer（ADR-022 RBAC）。
   • admin —— 全控。
   • user —— 能跟 Agent 聊天、查看 incident、静音告警。Toolbag 过滤到 ClassSafe。
   • viewer —— 只读聊天（不能调写技能）、只读 incident。
3. 想降级引导管理员就降，或者直接不用它。

10. 触发第一个 incident（冒烟测试）

强制让一条内置规则触发。最简单的：停一个 edge。

sudo systemctl stop ongrid-edge

在 ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD（默认 90s）+ evaluator 间隔（默认 5m）内，edge_offline 规则触发。UI 里：

• Alerts —— 新事件。
• Incidents —— 把事件聚合成新的 incident。
• Channels —— 你接的通道收到一张卡片。

如果你配了 IM 通道，回复 bot "investigate this"。Incident investigator 端到端跑一遍并回一份报告。

重启 edge：

sudo systemctl start ongrid-edge

规则不再触发时，incident 自动进 mitigated；你在 UI 上把它标 resolved。

接下来

• 通道概览 —— 接你真实的 on-call 通道。
• 告警能力 —— 在 6 条内置规则之上写自定义规则。
• 升级 —— v0.7.X+1 发布时。
• 参考 / env —— 所有 ONGRID_* 可调项。