外接 PostgreSQL

何时该切 PostgreSQL:

• 已有云数据库的统一备份 / 高可用方案
• 计划多实例部署 (SQLite 不支持多写)
• 单库数据量 > 几十万行, 看重并发查询
• 想统一接入企业的审计 / 监控

推荐: 直接用 Docker compose 一键启动 里的 完全版 compose, 那一份就是 imagic + Postgres + Redis 一起跑, 复制粘贴即可。

下面给个外接 PG 的差异化配置参考。

接外部 PG (云数据库 / 自建)

把 imagic.DB_DSN 指向你的外部 PG 即可, 不需要 db 服务。完整 compose 见 一键启动 的 外接版。

services:
  imagic:
    environment:
      DB_DRIVER: postgres
      DB_DSN: postgresql://user:strongpass@your-pg-host.example.com:5432/imagic?sslmode=require

外部 PG 上需要预先做的事:

1. 创建数据库 imagic (或你想用的库名), 字符集 UTF8
2. 创建专用用户并授权:

   CREATE USER imagic WITH PASSWORD 'strongpass';
   GRANT ALL PRIVILEGES ON DATABASE imagic TO imagic;
   -- PG 15+ 还要给 schema 权限
   GRANT ALL ON SCHEMA public TO imagic;

3. 网络放行: 容器到 PG 的 5432 端口连通; 云数据库一般要在白名单加上服务器公网 IP
4. SSL: 公网链路务必带 sslmode=require, 内网可用 sslmode=disable

DSN 两种格式

后端两种格式都支持, 任选其一:

密码含 @:/?# 等特殊字符时, URL 风格必须 URL-encode, KV 风格直接写不用转义。 密码里有 @ 时尤其建议走 KV 风格避免歧义。

从 SQLite 迁移到 PostgreSQL

仓库不内置数据迁移脚本。建议:

• 数据量不大时, 直接重新部署 PG, 让 admin 在新库里重新配置渠道 / 套餐 / 兑换码
• 数据量较大或必须保留用户和历史时, 用通用工具 (如 pgloader) 把 SQLite 拷到 PG; 注意外键、自增 ID、时间戳精度

迁移完成后, 改 DB_DRIVER + DB_DSN, 重启 imagic 即可。

验证

docker compose exec imagic wget -qO- http://localhost:8080/api/v1/health
# 期望: {"code":200,"data":{"status":"ok"},"msg":"ok"}

docker compose logs imagic | grep -i "database"
# 期望看到连上 postgres 的日志

数据库切换不影响 Redis 与图片存储, 这两个组件独立配置。