配置项总表
启动层与运行层的完整配置项。启动层改完要重启;运行层保存即热生效。
9. 配置清单(分层)
9.1 启动层 —— 本地 config.yaml + 命令行参数(重启生效)
启动时就要确定、运行期不变的配置放本地文件;数据库路径存在鸡生蛋问题,只能走命令行。
| 来源 | 项 | 默认值 | 说明 |
|---|---|---|---|
命令行 --db | SQLite 数据库路径 | ./data/omnigate.db | 路径无法存进数据库自身;仅 driver=sqlite 时生效 |
命令行 --db-driver | 数据库类型 | 空(不覆盖) | 覆盖 database.driver(sqlite/mysql/postgres) |
命令行 --db-dsn | 远程库连接串 | 空(不覆盖) | 覆盖 database.dsn |
命令行 --config | 配置文件路径 | ./config.yaml | 文件不存在时自动生成含注释的默认模板 |
命令行 --host | 监听地址 | 空(不覆盖) | 覆盖 server.host,优先级最高 |
命令行 --port | 监听端口 | 0(不覆盖) | 覆盖 server.port,优先级最高 |
config.yaml → server.host / server.port | 监听地址/端口 | 127.0.0.1 / 17777 | 启动即需确定;dev 模式下 start.sh 用 --host/--port 固定 27777,vite 独立前端跑 27778 反代到本端口 |
config.yaml → admin.username / admin.password | 管理账号密码 | ""(关闭) | Web 登录 + /api 保护;用户名禁冒号;重启生效 |
config.yaml → database.* | 数据库目标 | driver: sqlite | driver(sqlite/mysql/postgres)、path(sqlite 文件)、dsn(远程连接串)、init_sql/init_sql_inline(初始化 SQL)、max_open_conns/max_idle_conns/conn_max_lifetime_s(连接池) |
优先级:--db/--db-driver/--db-dsn 与 --host/--port > 环境变量 DATABASE_*/SERVER_* > config.yaml > 内置默认值。
数据库后端与多实例(database.driver):
- 默认 SQLite 是单文件本地库;部署多个入口共用一套状态(配置、熔断、用量、日志)时,
换
driver: mysql或postgres并给dsn。Validate拒绝两件静默错配: driver=sqlite 却配了 dsn(会按本地文件跑起来)、远程驱动却没有 dsn。 - 初始化 SQL:
init_sql(文件列表)+init_sql_inline(内联)在连接建立后、 建表迁移之前按序自动执行——它要负责的正是「迁移之前就该存在的东西」(建库、装扩展、 预置数据)。语句按方言切分(字符串/引号/注释/$$函数体内的分号不是边界),逐条执行、 失败立即中止启动。建议幂等(IF NOT EXISTS/ON CONFLICT)。 - 方言差异收口在
Dialect(internal/store/dialect.go):冲突子句 (ON CONFLICT … DO UPDATE/NOTHINGvsON DUPLICATE KEY UPDATE,后者吞不下数据超长 错误所以不用INSERT IGNORE)、字符串拼接(CONCAT()vs||)、时间桶 (col - (col % ?)——MySQL/是小数除法)、回填日聚合的本地日历日表达式、PRAGMA wal_checkpoint(仅 SQLite)等。日聚合 upsert 与 content_log upsert 用 「参数拼两遍」的写法规避各方言的 excluded/VALUES() 伪表差异。 - 实例标识 = 数据库目标(anchor):一个数据库就是一个实例。SQLite 沿用数据库文件
绝对路径;远程库用不含凭据的
driver://host:port/dbname(解析不出时退回 DSN 的 sha256 前缀)——anchor 进入 PID 文件名与开机自启实例名(unit/plist 文件名),绝不带密码。 远程库的 PID 文件落在~/.omnigate/下而非数据库目录(那里不可写)。 - 远程库实例配置开机自启必须把
database.dsn写进 config.yaml 并通过--config注册: 连接串不写进 systemd unit / launchd plist / Windows 注册表(明文);只给命令行或 环境变量的话,开机进程拿不到 DSN。 - 连接池默认值按驱动区分:SQLite 4/2(单文件写串行,连接多了互相等锁),远程库 20/10。
9.2 运行层 —— app_config 表(保存即热生效)
| key | 默认值 | 说明 |
|---|---|---|
breaker.cooldown_ladder | ["30s","1m","3m"] | 阶梯序列,末档重复 |
breaker.disable_threshold | 3 | 连续失败禁用阈值 |
breaker.max_hops | 3 | 单请求最多尝试的不同路由模型数;每个模型会先耗尽其可用密钥 |
retry.cooldown_s | 60 | 429 缺省冷却(有 Retry-After 时优先) |
retry.statuses | [401,403,429,500,502,503,504] | 可重试/触发处置的 HTTP 状态码 |
stream.idle_timeout_s | 300 | 流式读取空闲超时 |
stream.inject_usage | true | 自动注入 include_usage 获取精确 token |
capture.enabled | false | 是否捕获成功请求;关闭时仍记转发失败 |
capture.routes | [] | 路由白名单(空=全路由;对成功和失败同样生效) |
capture.retention_days | 3 | 内容日志保留期 |
log.retention_days | 0(永久) | 请求日志保留期,0=不清理;>0 时每小时自动清理 |
affinity.enabled | false | 会话亲和开关(同会话粘住上次成功模型,最大化上游缓存命中) |
affinity.headers | ["X-Session-ID"] | 会话 ID 请求头候选列表(按顺序取第一个有值的;均未传时按消息前缀哈希自动识别会话) |
affinity.ttl_s | 3600 | 亲和记忆时长(秒) |
header_profile_presets | [] | 客户端模拟请求头模板库(管理台"模板库一键插入"的数据源) |
debug.stream_log | false | 调试模式:记录每次出站请求与每个 SSE 块(见 调试模式) |
audio.max_upload_mb | 25 | STT 上传上限(MB),范围 1–200 |
quota.alert_enabled | true | 配额类事件总开关(站内通知 + 外发渠道);关掉后配额类连站内也不记 |
quota.warn_pct | 80 | 全局预警阈值(%),范围 1–99;密钥可用 warn_threshold_pct 覆盖 |
quota.check_interval_s | 300 | 告警扫描间隔(秒),范围 30–86400 |
quota.repeat_interval_h | 0 | 同档位重复提醒间隔(小时),0=只在跨档位时通知一次 |
notify.model_health_enabled | true | 是否把模型健康事件(全部密钥被禁用/恢复)记入通知中心 |
启动引导:首次启动自动建表、为运行层写入全部默认值、生成默认 config.yaml 模板。