数据库与备份
默认的 SQLite 对绝大多数场景够用。这一页讲什么时候需要换，以及怎么备份才能真的恢复得回来。
该用哪个§
三种驱动是同等受支持的，功能没有阉割，区别在运维：
| 驱动 | 适合 | 代价 |
|---|---|---|
| SQLite | 默认，不用装任何东西。单机部署的首选 | 数据在本机文件里，跟着机器走 |
| MySQL | 已有 MySQL 运维体系，想统一备份和监控 | 多一个要维护的服务 |
| PostgreSQL | 同上，偏好 PG 生态 | 同上 |
2.0 是单实例设计，换成外部数据库不会带来横向扩展能力， 也很少是性能瓶颈所在。 换的理由通常是运维统一——比如你希望数据库备份走公司现有的那套流程。
DSN 写法§
用 DATABASE_DSN 这一个变量决定连哪里。留空即使用受管的 SQLite，存在 DATA_DIR/gpt-load.db。
# 留空：受管 SQLite（默认） DATABASE_DSN= # 外部 SQLite：指定文件路径 DATABASE_DSN=sqlite:///var/lib/gpt-load/data.db # MySQL DATABASE_DSN=mysql://user:password@db.example:3306/gpt_load # PostgreSQL DATABASE_DSN=postgres://user:password@db.example:5432/gpt_load
连接参数按各自的惯例追加在查询串里：
# MySQL 走 TLS mysql://user:pass@db.example:3306/gpt_load?tls=true # PostgreSQL 要求 SSL postgres://user:pass@db.example:5432/gpt_load?sslmode=require
只要 DATABASE_DSN 非空，网关就不再接管这个数据库的目录与文件权限—— 即使你填的 SQLite 路径恰好等于默认位置。 权限、备份、磁盘都由你负责。
连接池大小可以调，见 环境变量。
结构迁移§
版本升级时如果数据库结构有变化，启动时会自动完成迁移， 不需要你执行任何命令。三种驱动走同一条有序的迁移链， 已完成的跳过、未完成的按顺序执行。
迁移是单向的——新版本执行过的结构变更，旧版本未必认得。 跨版本升级前务必备份，否则回滚时会卡住。
如果数据库处于无法安全恢复的中断状态，程序会拒绝启动并说明原因，而不是带着损坏的结构继续跑。 这时候用备份恢复是最快的路径。
备份§
数据库必须和加密密钥来自同一套实例。 使用自动生成的密钥时，auth.key 和 encryption.key都在数据目录中；如果在环境变量或密钥管理服务中显式设置， 还要从原来的安全来源单独备份。本版本不支持主密钥轮换。
SQLite（官方 Compose 默认配置）——先停服务，再从现有容器解析 实际卷名并打包整个数据目录。下面的命令要在 docker-compose.yml所在目录执行：
docker compose stop gpt-load
container_id=$(docker compose ps -a -q gpt-load)
test -n "$container_id"
data_volume=$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/app/data"}}{{.Name}}{{end}}{{end}}' "$container_id")
test -n "$data_volume"
docker volume inspect "$data_volume" >/dev/null
backup_file="gpt-load-$(date +%F-%H%M%S).tar.gz"
docker run --rm --user 0:0 \
--mount "type=volume,src=$data_volume,dst=/data,readonly" \
--mount "type=bind,src=$PWD,dst=/backup" \
alpine:3.24.1 sh -eu -c \
'test -s /data/gpt-load.db; cd /data; tar -czf "/backup/$1" .' sh "$backup_file"
tar -tzf "$backup_file" | sed -n '1,20p'
docker compose start gpt-loaddocker volume inspect 和 test -s 都必须成功， 归档列表中也必须包含 gpt-load.db。 不要把 Compose 的逻辑卷名 gpt-load-data 直接写进docker run -v——实际卷名会随 Compose 项目名变化。
外部数据库——数据库用它自己的工具备份， 并从当前实例的安全来源备份匹配的 AUTH_KEY 与ENCRYPTION_KEY：
mysqldump -h db.example -u user -p gpt_load > gpt_load.sql
# 或
pg_dump -h db.example -U user gpt_load > gpt_load.sql备份文件本身包含可解密的凭据， 按敏感数据对待——加密存放，别丢进公开网盘或仓库。
恢复§
恢复的关键是数据库、加密密钥和程序版本必须匹配。 不要把备份内容直接覆盖到一个已有数据的目录或卷中。
- 停止目标服务，并先备份目标当前数据
- 校验归档，恢复到新的空目录或空卷
- 恢复与数据库匹配的
ENCRYPTION_KEY；显式设置的密钥从原安全来源恢复 - 首次使用与备份相同的 GPT-Load 版本启动，不要同时升级
- 检查健康状态，并登录管理台确认渠道凭据可以正常解密
验证过能恢复，备份才算数。建议在非生产环境实际走一遍这个流程，别等出事才发现备份不完整。
换驱动§
没有自动的数据搬迁工具。换驱动等于换一套新数据库， 原有配置需要重新录入。
如果配置量大，比较务实的做法是：并行跑一段时间—— 新起一个实例连新数据库、配好、验证，再把流量切过去， 和 从 1.x 迁移 的思路一致。
换驱动后 encryption.key 不要换—— 沿用原来那把，重新录入的凭据才能和旧备份保持一致的加密方式。 当然，如果是全新录入，用新密钥也可以，但要记得更新备份。