`database.yml`：SQLite 与 MySQL

完整默认文件见从零服主实战。这里逐项解释范围、重启要求与故障处理。

后端与连接

键	默认	范围/规则	生效
`config-version`	1	固定	启动/重载校验
`type`	SQLITE	SQLITE/MYSQL	重启
`sqlite.file`	`storage/sealattributes.db`	相对路径，不得含 `..` 逃出目录	重启
`mysql.host`	127.0.0.1	非空，最多 255 字符	重启
`mysql.port`	3306	1～65535	重启
`mysql.database`	sealattributes	1～64 个字母、数字、下划线	重启
`mysql.username`	sealattributes	非空，最多 128 字符	重启
`mysql.password`	change-me	最多 1024 字符	重启；生产必须替换
`mysql.use-ssl`	false	布尔	重启
`mysql.allow-public-key-retrieval`	false	布尔	重启；仅明确理解风险时开启

生产 MySQL 示例：

yaml

config-version: 1
type: MYSQL
sqlite:
  file: storage/sealattributes.db
mysql:
  host: db.internal.example
  port: 3306
  database: sealattributes_prod
  username: sealattributes_app
  password: "replace-with-secret"
  use-ssl: true
  allow-public-key-retrieval: false
pool:
  minimum-idle: 1
  maximum-pool-size: 4
  connection-timeout-ms: 5000
  validation-timeout-ms: 2000
  idle-timeout-ms: 600000
  maximum-lifetime-ms: 1800000
queue:
  storage-threads: 2
  capacity: 4096
timeouts:
  query-seconds: 5
  startup-seconds: 15
  preload-seconds: 15
  shutdown-seconds: 8
health-checkpoint:
  interval-seconds: 60
reconnect:
  interval-seconds: 15
migration:
  mysql-backup-confirmed: false

不要提交含密码的文件。插件会在错误输出中清理密码，但这不能替代最小权限账户、网络 ACL 和凭据轮换。

连接池与队列

键	默认	范围
`pool.minimum-idle`	1	0～16，且 ≤ maximum
`pool.maximum-pool-size`	1	1～16
`connection-timeout-ms`	5000	1000～30000
`validation-timeout-ms`	2000	250～connection timeout
`idle-timeout-ms`	600000	0 或 ≥10000
`maximum-lifetime-ms`	1800000	0 或 ≥30000
`queue.storage-threads`	1	1～8；SQLite 必须为 1
`queue.capacity`	2048	128～16384

这些字段全部要求重启。SQLite 的 pool maximum 和 storage threads 必须为 1。扩大池和队列不能修复慢 SQL；先测延迟、索引、网络和消费速率。

超时与后台周期

键	默认	范围	热重载
`timeouts.query-seconds`	5	1～30	是
`timeouts.startup-seconds`	15	2～60	配置可重载，实际启动预算在下次启动使用
`timeouts.preload-seconds`	15	1～60	是
`timeouts.shutdown-seconds`	5	1～30	是
`health-checkpoint.interval-seconds`	60	0 或 10～600	是；0 关闭周期检查点
`reconnect.interval-seconds`	15	5～300	是
`migration.mysql-backup-confirmed`	false	布尔	可读入，但仅下次完整启动迁移使用

迁移确认

全新 MySQL schema 保持 false。只有版本说明明确要求、并且你已完成外部备份与恢复演练时，才在维护窗口临时设为 true。插件不会替你创建可靠的 MySQL 备份。未来 schema 比当前代码新时会拒绝启动；禁止手改 sa_schema_version。

后端切换不等于迁移

把 type: SQLITE 改成 MYSQL 只会连接另一套空/已有数据库，不会复制任何数据。正确流程是停服、备份、在隔离环境使用经过审计的迁移工具导入、验证行数/约束/登录，再切换。当前插件没有导出、导入或恢复命令。

故障行为

启动数据库失败会停止插件，不自动回退 SQLite；
READY 前持久数据预载超时会让该会话 fail closed；
队列有界，满时拒绝新写入而不是无限占内存；
永久来源写入失败会保留旧持久事实，不伪装成功；
断线后按 reconnect 周期探测；恢复连接不代表此前失败写入都自动重试；
/sa database flush 使用 shutdown timeout，busy/timeout 需要先查数据库而不是无限重复。

用 /sa database status 观察后端、连接和队列；正常停服必须确认 storage stopped: drained=true。

database.yml：SQLite 与 MySQL ​

后端与连接 ​

连接池与队列 ​

超时与后台周期 ​

迁移确认 ​

后端切换不等于迁移 ​