跳到主要内容

配置项总表

启动层与运行层的完整配置项。启动层改完要重启;运行层保存即热生效。

9. 配置清单(分层)​

9.1 启动层 —— 本地 config.yaml + 命令行参数(重启生效)​

启动时就要确定、运行期不变的配置放本地文件;数据库路径存在鸡生蛋问题,只能走命令行。

来源项默认值说明
命令行 --dbSQLite 数据库路径./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: sqlitedriver(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/NOTHING vs ON 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_threshold3连续失败禁用阈值
breaker.max_hops3单请求最多尝试的不同路由模型数;每个模型会先耗尽其可用密钥
retry.cooldown_s60429 缺省冷却(有 Retry-After 时优先)
retry.statuses[401,403,429,500,502,503,504]可重试/触发处置的 HTTP 状态码
stream.idle_timeout_s300流式读取空闲超时
stream.inject_usagetrue自动注入 include_usage 获取精确 token
capture.enabledfalse是否捕获成功请求;关闭时仍记转发失败
capture.routes[]路由白名单(空=全路由;对成功和失败同样生效)
capture.retention_days3内容日志保留期
log.retention_days0(永久)请求日志保留期,0=不清理;>0 时每小时自动清理
affinity.enabledfalse会话亲和开关(同会话粘住上次成功模型,最大化上游缓存命中)
affinity.headers["X-Session-ID"]会话 ID 请求头候选列表(按顺序取第一个有值的;均未传时按消息前缀哈希自动识别会话)
affinity.ttl_s3600亲和记忆时长(秒)
header_profile_presets[]客户端模拟请求头模板库(管理台"模板库一键插入"的数据源)
debug.stream_logfalse调试模式:记录每次出站请求与每个 SSE 块(见 调试模式)
audio.max_upload_mb25STT 上传上限(MB),范围 1–200
quota.alert_enabledtrue配额类事件总开关(站内通知 + 外发渠道);关掉后配额类连站内也不记
quota.warn_pct80全局预警阈值(%),范围 1–99;密钥可用 warn_threshold_pct 覆盖
quota.check_interval_s300告警扫描间隔(秒),范围 30–86400
quota.repeat_interval_h0同档位重复提醒间隔(小时),0=只在跨档位时通知一次
notify.model_health_enabledtrue是否把模型健康事件(全部密钥被禁用/恢复)记入通知中心

启动引导:首次启动自动建表、为运行层写入全部默认值、生成默认 config.yaml 模板。