环境变量

ongrid 和 ongrid-edge 都只通过环境变量配置。没有 YAML。规范接线在 internal/pkg/config/config.go 和 deploy/docker-compose.yml 的 env 块 里。下面每个变量在启动时读；manager 不热加载。

按子系统分组的表。默认值是变量未设或为空时二进制选的那个。"必需" 意思是 "没它第 1 列的功能不工作"。

---

HTTP & metrics listener

变量	类型	默认	描述
ONGRID_HTTP_ADDR	string	:8080	API + SPA 的 TCP listen。compose 栈里的 nginx 把 /api/* 代理到这。
ONGRID_METRICS_ADDR	string	:9100	/metrics 的 TCP listen。Prometheus 抓。
ONGRID_TUNNEL_ADDR	string	:40012	Geminio broker listen。frontier 服务绑，不是 manager 自己。
ONGRID_PUBLIC_URL	string	空	manager 发给 edge 作为数据面端点（日志/链路摄入、edge bundle 下载）的规范 https://... URL。空时禁用数据面插件 endpoint。生产里设它。

---

数据库（默认 MySQL，opt-in SQLite）

变量	类型	默认	描述
ONGRID_DB_DIALECT	string	mysql	mysql（默认）或 sqlite。空当 mysql 处理。
ONGRID_DB_DSN	string	ongrid:ongrid@tcp(127.0.0.1:3306)/ongrid?parseTime=true&charset=utf8mb4&loc=Local	MySQL DSN。生产必填。
ONGRID_DB_PATH	string	./data/ongrid.db	SQLite 数据库文件路径。测试里 :memory: 也接受。

---

JWT（iam）

变量	类型	默认	描述
ONGRID_JWT_SECRET	string	dev-insecure-secret-change-me	access + refresh token 的 HS256 签名 key。必填；生产构建里默认值拒发 token。
ONGRID_JWT_ACCESS_TTL	duration	15m	access token TTL。
ONGRID_JWT_REFRESH_TTL	duration	168h（7d）	refresh token TTL。

duration 接受 Go time.ParseDuration 语法（15m、2h、30s）。裸整数 当秒解读。

---

LLM provider

chat agent 支持六个一等 provider 加一个 Custom（OpenAI 兼容）槽。每个 provider 由它的 API key 卡 —— 空 key = provider 不露给 chat picker。

OpenAI

变量	类型	默认	描述
ONGRID_OPENAI_API_KEY	string	空	OpenAI API key。空 = OpenAI 从 picker 隐藏。
ONGRID_OPENAI_MODEL	string	gpt-5.4	OpenAI 是当选 provider 时的默认 model。
ONGRID_OPENAI_BASE_URL	string	空	OpenAI 兼容中继的 base URL 覆盖（Azure / vLLM / Ollama / one-api）。

Anthropic、Zhipu、Gemini、DeepSeek、Kimi

每个 provider 有相同的三个 key（API key / 默认 model / base URL），加第四 个（MODELS，可选 model slug 的逗号分隔列表）：

变量	默认
ONGRID_ANTHROPIC_API_KEY	空
ONGRID_ANTHROPIC_MODEL	claude-sonnet-4-6
ONGRID_ANTHROPIC_BASE_URL	空
ONGRID_ANTHROPIC_MODELS	claude-opus-4-7,claude-sonnet-4-6,claude-haiku-4-5
ONGRID_ZHIPU_API_KEY	空
ONGRID_ZHIPU_MODEL	glm-4.7
ONGRID_ZHIPU_BASE_URL	空
ONGRID_ZHIPU_MODELS	glm-5.1,glm-5,glm-4.7,glm-4.7-flash
ONGRID_GEMINI_API_KEY	空
ONGRID_GEMINI_MODEL	gemini-2.5-pro
ONGRID_GEMINI_BASE_URL	空
ONGRID_GEMINI_MODELS	gemini-3.5-flash,gemini-2.5-pro,gemini-2.5-flash
ONGRID_DEEPSEEK_API_KEY	空
ONGRID_DEEPSEEK_MODEL	deepseek-v4-flash
ONGRID_DEEPSEEK_BASE_URL	空
ONGRID_DEEPSEEK_MODELS	deepseek-v4-pro,deepseek-v4-flash,deepseek-reasoner
ONGRID_KIMI_API_KEY	空
ONGRID_KIMI_MODEL	kimi-k2.6
ONGRID_KIMI_BASE_URL	空
ONGRID_KIMI_MODELS	kimi-k2.6,kimi-k2.5,moonshot-v1-128k

路由 & 预算

变量	类型	默认	描述
ONGRID_LLM_DEFAULT_PROVIDER	string	空	请求没指定时用的 provider。空 = 第一个配置的 provider（字典序）。想要某个 provider 作为站点默认时设它。
ONGRID_LLM_DAILY_TOKEN_LIMIT	int	0	全局按 UTC 日的 token 上限。0 = 无限。

---

agent kernel & 工具

变量	类型	默认	描述
ONGRID_AGENT_KERNEL	string	graph	graph 启用 eino graph kernel + SkillRegistry.Resolve 激活关键词过滤 + ToolBag 延迟管线。legacy 是更老的 for 循环 runner，所有工具永远完整 schema。只在二分时切到 legacy。
ONGRID_TOOLBAG_DEFERRAL_THRESHOLD	int	30	工具数超它就把 specialty 层的工具改为打码 schema（LLM 必须调 ToolSearch 展开）。
ONGRID_SKILLS_EXTERNAL_DIRS	csv	空	技能加载器扫描 skill.json manifest 的逗号/冒号分隔绝对路径。每条都得绝对；相对或缺失会被跳过并打日志。

---

Frontier broker client

变量	类型	默认	描述
ONGRID_FRONTIER_ADDR	string	frontier:40011	manager 拨的上游 frontier broker 的服务端 listen。
ONGRID_FRONTIER_SERVICE_NAME	string	ongrid-manager	连接时上报的标识符。
ONGRID_FRONTIER_DISABLED	bool	false	整体跳过长寿命服务端拨号。e2e 用；需要 broker 的特性（webssh、edge 反向调用）在调用点出错。

---

云端 Prometheus

变量	类型	默认	描述
ONGRID_PROM_ENABLED	bool	false	卡 Prometheus 接线。false 时 manager 不带指标存储跑；push_prom_samples 静默丢，query_promql 不注册为工具。
ONGRID_PROM_URL	string	http://prometheus:9090	Prom 服务端根 URL。
ONGRID_PROM_REMOTE_WRITE_URL	string	空	上游不以 /api/v1/write 为根时的精确 remote_write endpoint（Mimir / Cortex / VictoriaMetrics 网关）。
ONGRID_PROM_QUERY_URL	string	空	给 query_promql 的查询 API 根。空回退到 ONGRID_PROM_URL。
ONGRID_PROM_TLS_INSECURE	bool	false	跳 TLS 证书校验。
ONGRID_PROM_TLS_CA_FILE	string	空	验 TSDB 证书的根 CA PEM 文件。空 = 系统 root。

---

Grafana

变量	类型	默认	描述
ONGRID_GRAFANA_INTERNAL_URL	string	http://grafana:3000/grafana	manager 通过 docker 网络到 Grafana 的 URL。
ONGRID_GRAFANA_BOOTSTRAP_USER	string	admin	一次性 admin 用户，用来自动创建 ongrid Service Account + token。
ONGRID_GRAFANA_BOOTSTRAP_PASSWORD	string	空	bootstrap 密码；空禁用 bootstrap（UI 里粘贴手建的 SA token）。
ONGRID_GRAFANA_TLS_INSECURE	bool	false	bootstrap 调用跳证书校验。
ONGRID_GRAFANA_ROOT_URL	string	%(protocol)s://%(domain)s/grafana/	转给 GF_SERVER_ROOT_URL。

---

日志 & 链路（数据面）

变量	类型	默认	描述
ONGRID_LOG_QUERY_URL	string	http://loki:3100	manager 跟它说话做 query_range / labels / values 的 Loki API 根。空 = Logs 页返 503。
ONGRID_TRACE_QUERY_URL	string	http://tempo:3200	/api/search、/api/traces/<id>、/api/search/tag/<tag>/values 用的 Tempo HTTP listener 根。空 = Traces 页返 503。

edge 数据面 endpoint（日志 / 链路插件 POST 的地方）从 ONGRID_PUBLIC_URL 派生；见 遥测数据面。

---

内置告警阈值

这些驱动主机指标闭合集上的四条规范内置规则。设 0 禁用。

变量	类型	默认	描述
ONGRID_ALERT_ENABLED	bool	true	内置主机告警评估主开关。
ONGRID_ALERT_COOLDOWN	duration	10m	按 (edge, rule) 冷却。窗口内通知被压。
ONGRID_ALERT_CPU_PERCENT	float	90	cpu_pct >= threshold 时触发。
ONGRID_ALERT_MEM_PERCENT	float	90	mem_pct >= threshold 时触发。
ONGRID_ALERT_DISK_USED_PERCENT	float	90	disk_used_pct >= threshold 时触发。
ONGRID_ALERT_LOAD1	float	0	load1 >= threshold 时触发。0 禁用（load 在不同主机形状里差太大，没有有用默认）。
ONGRID_ALERT_EVAL_INTERVAL	duration	5m	pipeline evaluator 扫 edge 并查 Prom 的频率。
ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD	duration	90s	心跳超此陈旧度算 edge 离线。
ONGRID_ALERT_PROM_INGEST_FAIL_LIMIT	int	5	连续 remote_write 失败到此触发 prom_ingest_fail。

---

通知

主开关 + 四种内置 channel 类型。UI 建的 channel 自带 enabled flag，不受 这些影响。

变量	类型	默认	描述
ONGRID_NOTIFY_ENABLED	bool	true	外发通知主开关。
ONGRID_NOTIFY_DEFAULT_CHANNELS	csv	空	调用方没指定目的地时用的 channel 名顺序列表。
ONGRID_NOTIFY_TIMEOUT	duration	10s	按 channel 发送超时。
ONGRID_NOTIFY_WEBHOOK_ENABLED	bool	false	启用 env 配置的 webhook channel。
ONGRID_NOTIFY_WEBHOOK_NAME	string	webhook	显示名。
ONGRID_NOTIFY_WEBHOOK_URL	string	空	POST endpoint。
ONGRID_NOTIFY_WEBHOOK_SECRET	string	空	可选 HMAC secret。
ONGRID_NOTIFY_SLACK_ENABLED	bool	false	启用 env 配置的 Slack channel。
ONGRID_NOTIFY_SLACK_NAME	string	slack	显示名。
ONGRID_NOTIFY_SLACK_WEBHOOK_URL	string	空	Incoming Webhook URL。
ONGRID_NOTIFY_FEISHU_ENABLED	bool	false	启用 env 配置的飞书 channel。
ONGRID_NOTIFY_FEISHU_NAME	string	feishu	显示名。
ONGRID_NOTIFY_FEISHU_WEBHOOK_URL	string	空	自定义 Bot URL。
ONGRID_NOTIFY_FEISHU_SECRET	string	空	签名 secret。
ONGRID_NOTIFY_DINGTALK_ENABLED	bool	false	启用 env 配置的钉钉 channel。
ONGRID_NOTIFY_DINGTALK_NAME	string	dingtalk	显示名。
ONGRID_NOTIFY_DINGTALK_WEBHOOK_URL	string	空	自定义 Bot URL。
ONGRID_NOTIFY_DINGTALK_SECRET	string	空	签名 secret。

企业微信和 Telegram channel 通过 Settings → Channels UI 创建 —— 它们是 一等的，但没有 env 配置捷径。

---

bootstrap admin

变量	类型	默认	描述
ONGRID_ADMIN_EMAIL	string	空	bootstrap admin 的 email。空时不种 admin；首次启动从 UI 注册。
ONGRID_ADMIN_PASSWORD	string	空	初始密码。运维预期首次登录改它。

---

edge agent

这些由 ongrid-edge 消费，安装器写到 /etc/ongrid-edge/ongrid-edge.env。

变量	类型	默认	描述
ONGRID_EDGE_CLOUD_ADDR	string	127.0.0.1:40012	Frontier broker host:port。agent 用 TLS 拨它。
ONGRID_EDGE_ACCESS_KEY	string	空	按 edge access key。UI 里建 edge 时 manager 发。
ONGRID_EDGE_SECRET_KEY	string	空	匹配的 secret。edge 创建时显示一次；通过 UI 轮换。
ONGRID_EDGE_COLLECTOR_MODE	string	off	off（默认；hostmetrics + procmetrics 插件处理指标）、auto（遗留内嵌 + scraper）、embedded（仅内嵌推）、scrape（多目标 HTTP scraper）。
ONGRID_EDGE_SCRAPE_CONFIG_FILE	string	/etc/ongrid-edge/scrape.yaml	scrape config YAML 路径。仅当 COLLECTOR_MODE=scrape 时查。
ONGRID_EDGE_COLLECTOR_INTERVAL	duration	10s	内嵌 collector 快照频率。scrape 模式忽略。
ONGRID_EDGE_PLUGIN_BIN_DIR	string	/usr/local/lib/ongrid-edge	装插件二进制的目录（promtail、otelcol-contrib、node_exporter、process_exporter）。
ONGRID_EDGE_PLUGIN_WORK_DIR	string	/var/lib/ongrid-edge/plugins	按插件运行时目录（config、PID 文件、队列 spool）。
ONGRID_EDGE_UPGRADE_STAGE_DIR	string	/var/lib/ongrid-edge/.upgrade	ADR-024 暂存包目录。空禁用远程整包升级。
ONGRID_INSTALL_WAIT	int	20	curl-pipe 安装器轮询 journal 等 "registered with cloud" 的秒数。

---

embedding & RAG

变量	类型	默认	描述
ONGRID_EMBEDDING_PROVIDER	string	zhipu	zhipu（默认；调 GLM embedding API）、local（用磁盘上的 bge 模型）、openai（用 OpenAI embedding）。
ONGRID_EMBEDDING_LOCAL_MODEL_PATH	string	空	PROVIDER=local 时本地模型的绝对路径。release tarball 把 bge-base-en-v1.5 暂存到 .cache/ 下。
ONGRID_VAULT_REPO_URL	string	https://github.com/ongridio/vault	manager 拉基线知识的上游 vault 仓库。离线镜像覆盖。

---

locale & 杂项

变量	类型	默认	描述
ONGRID_DEFAULT_LOCALE	string	en	自动 LLM 输出（告警调查、计划摘要）的默认 locale。UI 触发的 chat 用用户 UI locale 代替。

---

另见

• REST API —— 这些 env 变量接通的 endpoint。
• CLI —— 两个二进制的命令行 flag。
• 遥测数据面 —— 为什么日志/链路 endpoint 跟 tunnel 不同。
• 架构 —— 每个 env 变量在栈图里的位置。