数据库选型与建库

默认的内置 SQLite 能满足大多数单机部署，不需要安装任何数据库。以下情况再考虑外部数据库：已有统一的数据库运维体系、需要主备容灾，或客户要求使用国产数据库。

支持情况

driver	数据库	状态
sqlite	内置 SQLite	可用（默认）
postgres	PostgreSQL 16	可用
mysql	MySQL 8.0 及以上	可用
kingbase	人大金仓 KingbaseES（PG 模式）	可用，尚未经实例实测
dm	达梦 DM8	暂不可用，配置后启动即报错

与 MySQL / PostgreSQL 协议兼容的库（OceanBase MySQL 模式、TiDB、PolarDB、openGauss、Vastbase）可按对应 driver 配置，但均未经验证，上线前须先冒烟测试。

明确不支持：金仓 Oracle 模式、达梦 Oracle / MySQL 兼容模式、GBase 8s、MySQL 5.7、MariaDB。

通用要求

1. 库要提前建好，空库即可。表结构由程序首次启动时自动创建，不需要手工导入 SQL。
2. 连接用户对该库要有建表、建索引权限，直接用库的 owner 最省事。
3. 选定后不要更换 driver：换库等于换成一个空库，没有自动数据迁移。

SQLite

database:
  driver: sqlite
  dsn: ./data/apexpm.db

• 相对路径按 config.yaml 所在目录解析；也可写绝对路径。
• 连接数固定为 1，连接池参数对它无效。
• 备份：停服后复制 .db 文件即可。
• 不要把数据库文件放在 NFS、SMB 等网络文件系统上，文件锁不可靠，可能损坏数据库。

PostgreSQL

CREATE DATABASE apexpm ENCODING 'UTF8';

database:
  driver: postgres
  dsn: "postgres://apexpm:密码@127.0.0.1:5432/apexpm?sslmode=disable&TimeZone=Asia/Shanghai"

• sslmode：内网直连填 disable，要求加密填 require / verify-full。
• 经 pgbouncer 的 transaction pooling 连接时加 simple_protocol: true。

MySQL

必须 8.0 及以上：程序依赖 utf8mb4_0900_ai_ci 排序规则，5.7 与 MariaDB 都没有。

CREATE DATABASE apexpm CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;

database:
  driver: mysql
  dsn: "apexpm:密码@tcp(127.0.0.1:3306)/apexpm"

parseTime、loc、charset、collation 等参数由程序自动补全，不用写。

人大金仓 KingbaseES

只支持 PG 模式建的库。客户已有 Oracle 模式实例时，需要为本系统单独新建一个 PG 模式、UTF8 字符集的库（兼容模式与字符集建库后不可更改）。

database:
  driver: kingbase
  dsn: "postgres://system:密码@127.0.0.1:54321/apexpm?sslmode=disable"

金仓默认端口 54321，默认管理员 system。

连接错误对照

数据库问题会让进程启动后立即退出，日志里是 database connect failed 或 migrations failed：

日志中的 error（节选）	原因	处理
connection refused	数据库没启动、端口不对或防火墙拦截	在部署机上 telnet 主机 端口 或 nc -zv 主机 端口 验证连通
password authentication failed / Access denied for user	用户名或密码错	核对 DSN；密码含 @ : / ? # 时需 URL 编码
database "apexpm" does not exist / Unknown database	库没建	按上文先建库
Unknown collation: 'utf8mb4_0900_ai_ci'	MySQL 版本低于 8.0 或是 MariaDB	换 MySQL 8.0+
permission denied for schema public	用户没有建表权限	把库的 owner 设为该用户，或授予 CREATE 权限
no pg_hba.conf entry for host	PostgreSQL 未放行该来源 IP	在 pg_hba.conf 中添加规则后 reload
prepared statement "..." does not exist	经 pgbouncer 连接但没开简单协议	加 simple_protocol: true
migrations failed	表结构升级失败	保留完整日志联系我方，不要反复重启；如为升级后出现，按回滚步骤恢复备份