跳到主要内容

数据库后端

默认使用 SQLite(纯 Go 驱动,无 CGO)。需要多个入口共享一套状态时,切换到 MySQL 或 PostgreSQL。

选型​

场景选择
单机、本机使用SQLite(默认)
多个入口 / 多个实例共享配置、熔断、用量、日志MySQL 或 PostgreSQL
需要外部备份、审计、统一运维MySQL 或 PostgreSQL

SQLite 是单文件本地库,多进程各持一份文件,不会共享任何状态。把同一个 SQLite 文件放到共享盘上也不行。

配置​

database:
driver: postgres
dsn: postgres://user:pass@db.internal:5432/omnigate?sslmode=disable
init_sql: ["/etc/omnigate/init.sql"]
init_sql_inline: ""
max_open_conns: 20
max_idle_conns: 10
conn_max_lifetime_s: 0

MySQL:

database:
driver: mysql
dsn: user:pass@tcp(127.0.0.1:3306)/omnigate?charset=utf8mb4&parseTime=true

对应环境变量:DATABASE_DRIVER、DATABASE_DSN、DATABASE_INIT_SQL(文件路径列表,PATH 同款分隔符)。

启动时会拒绝两种静默错配:

  • driver=sqlite 却配了 dsn(会悄悄按本地文件跑起来)
  • driver=mysql/postgres 却没有 dsn

连接池参数为负也会拒绝。默认值:SQLite 4/2,远程库 20/10。

初始化 SQL​

init_sql 文件与 init_sql_inline 在连接建立之后、建表迁移之前按序执行,适合建库、装扩展、预置数据。

  • 任一条执行失败会中止启动,不会带着半成品继续跑
  • 建议写成幂等语句(IF NOT EXISTS / ON CONFLICT)
  • 一个文件里可以写多条语句;网关按方言切分,字符串、注释、PostgreSQL $$ 函数体里的分号不会被误切

实例标识​

一个数据库 = 一个实例。PID 文件与开机自启实例名按数据库目标派生:

  • SQLite:数据库文件绝对路径,PID 文件落在数据库同目录
  • 远程库:driver://host:port/dbname,不含凭据;PID 文件落在 ~/.omnigate/

远程库实例注册开机自启时,必须把 database.dsn 写在 config.yaml 里,并通过 --config 给出。连接串不会写进 systemd unit、launchd plist 或 Windows 注册表——它们都是明文。详见 开机自启。

SQLite 专有行为​

以下行为在远程库自动跳过:

  • PRAGMA wal_checkpoint
  • 内容捕获表的手工 DDL(远程库由迁移创建)
  • SQLite 的本地文件锁与 WAL 空间回收

空间回收、binlog、autovacuum 交给数据库自身。

多实例注意​

  • 小时请求数与并发上限是进程内计数,多实例各自计数,不共享
  • 日/月额度、熔断状态、通知去重状态落库,多实例共享
  • 定时探测也可能多实例同时运行,使用 CAS 更新,不会互相覆盖