企业官网建设流程全解析

codex-lb 多账号代理数据库指南：SQLite 与 PostgreSQL 取舍、备份快照与升级实战

【免费下载链接】codex-lbCodex/ChatGPT multiple account load balancer & proxy with usage tracking, dashboard, and OpenCode-compatible endpoints项目地址: https://gitcode.com/gh_mirrors/co/codex-lb

🗄️ codex-lb 是一款面向 Codex / ChatGPT 多账号的负载均衡代理，自带用量追踪、管理面板和 OpenCode 兼容端点。它的所有账号、用量历史、请求日志都存储在数据库中——选 SQLite 还是 PostgreSQL、如何备份快照、升级时怎么不丢数据，正是新手最常踩坑的三个问题。本文带你一次搞懂。

一、为什么数据库选型对 codex-lb 很重要

codex-lb 会持续写入三类数据：账号凭据（加密存储）、用量快照（usage_history）、请求日志（request_logs）。面板上看到的用量曲线、费用统计、账号趋势，全部来自这些表。

• 数据量小、单机自用 →SQLite一个文件搞定，零配置；
• 多副本部署、高并发写日志、外部高可用集群 →PostgreSQL更稳。

好消息是：codex-lb 对两者做了统一封装，切换只靠一个环境变量，无需改代码。

二、SQLite：默认后端，零配置上手

SQLite 是 codex-lb 的默认后端，安装后无需任何配置即可运行。🚀

数据存放在哪里？

⚠️ 记住一句话：备份这个目录，就备份了你的全部数据（数据库、加密密钥、会话归档）。

数据库文件旁还会生成一个runstate状态文件：进程正常运行时记录running，干净关机后记录clean。下次启动时如果检测到上次是"非干净退出"（崩溃、断电、被 kill），会自动对数据库做一次启动完整性检查，确保文件没有损坏才放行。这是 codex-lb 内置的第一道数据安全网。

面板上的用量看板、账号列表，读的全是这份 SQLite 数据：

三、PostgreSQL：一个环境变量即可切换

当你的部署是多副本、Helm/Kubernetes 集群时，建议切换 PostgreSQL。原理很简单：请求路径引擎启用连接池预检（pre-ping）与连接回收，遥测写入放宽同步刷盘以获得更高吞吐，而配置类写入（账号、API Key、限额）始终保留完整持久性——这些细节都由 codex-lb 自动处理，你只需给对连接串。

1. 设置环境变量

export CODEX_LB_DATABASE_URL="postgresql+asyncpg://codex_lb:codex_lb@127.0.0.1:5432/codex_lb"

2. 用 Docker Compose 一键起 Postgres

项目根目录的 docker-compose.yml 内置了postgres与postgres-upgrade两个 profile：

# 启用 Postgres 18 服务（数据落在命名卷 codex-lb-postgres-data） docker compose --profile postgres up -d

postgres服务还带了一个"入口守卫"：如果检测到卷里还是旧版本 Postgres 的数据目录，会拒绝启动并提示你先用postgres-upgrade升级，避免直接打开不兼容的数据目录。

3. 连接池调优（可选）

相关配置见 docs/reference/settings.md：

• CODEX_LB_DATABASE_POOL_SIZE（默认 25）
• CODEX_LB_DATABASE_MAX_OVERFLOW（默认 15）

默认值已按"单副本不超过 Postgres 默认 100 连接的 80%"设计，一般无需调整。

四、备份与快照：自动 pre-migrate 备份 + 损坏恢复

1. 升级前的自动快照

每次执行数据库结构升级前，codex-lb 会先自动创建一份 SQLite 快照，命名形如store.pre-migrate-20260927T010000Z.db：

• 基于 SQLite 官方 Backup API 生成，是热备而非"复制半截文件"；
• 默认最多保留 5 份（CODEX_LB_DATABASE_SQLITE_PRE_MIGRATE_BACKUP_MAX_FILES），超出自动淘汰最旧的；
• 可用CODEX_LB_DATABASE_SQLITE_PRE_MIGRATE_BACKUP_ENABLED关闭。

快照逻辑位于 app/db/backup.py，升级主流程在 app/db/migrate.py。

2. 数据库损坏了怎么救？

万一启动时完整性检查未通过，codex-lb 提供了宿主级恢复命令，思路是"把能读的页面抢救出来，生成一个新的、完整的数据库文件"，并顺手清理-wal、-shm等附属文件。核心实现见 app/db/recover.py。

日常备份建议（最稳的一条）：

# 定期打包数据目录即可（本地） tar -czf codex-lb-backup-$(date +%F).tgz ~/.codex-lb/

五、升级实战：版本迁移与 Postgres 16 → 18

1. 应用版本升级（Schema 迁移）

codex-lb 使用 Alembic 管理表结构，服务启动时默认自动迁移（CODEX_LB_DATABASE_MIGRATE_ON_STARTUP默认为True），迁移过程受分布式锁保护，多副本同时启动也不会互相踩踏。你也可以手动执行：

# 手动触发一次数据库升级（自动先打快照） codex-lb-db upgrade # 升级后做一次体检 codex-lb-db check

所有历史迁移脚本都在 app/db/alembic/ 下，可追溯每一次表结构变化。

2. Postgres 16 → 18 数据卷升级

如果你在用 Compose 内置的 Postgres，官方文档给出了标准的四步升级流程（先停库 → 备份卷 → 跑pg_upgrade→ 重启）：

docker compose --profile postgres stop postgres docker run --rm -v codex-lb-postgres-data:/var/lib/postgresql -v "$PWD:/backup" alpine \ tar -C /var/lib/postgresql -czf /backup/codex-lb-postgres-data-before-pg18.tgz . docker compose --profile postgres-upgrade run --rm postgres-upgrade docker compose --profile postgres up -d postgres

postgres-upgrade容器会对同一个命名卷执行一次性的pg_upgrade，把数据目录原地升级到 Postgres 18 布局后自动退出。✅升级完成的应用启动、且codex-lb-db check通过之前，请不要删除那份备份。

六、数据留存：别让日志无限膨胀

请求日志会持续增长，codex-lb 内置了数据留存（data retention）机制：可以在面板的高级设置中配置保留周期，过期日志由后台任务自动清理，SQLite 与 PostgreSQL 行为一致。相关文档：docs/database.md、docs/configuration.md。

七、常见疑问速查

总结

1. 默认 SQLite：零配置、单文件，备份~/.codex-lb/（或 Docker 下/var/lib/codex-lb/）目录即可；
2. 多副本 / 集群：用CODEX_LB_DATABASE_URL切到 PostgreSQL，连接池默认值已调好；
3. 升级别慌：每次迁移自动打快照，Postgres 大版本升级走postgres-upgradeprofile；
4. 守住底线：定期codex-lb-db check+ 定期打包数据目录，数据永远有一手备份。

📌 更多细节请阅读 docs/database.md 与 docs/reference/settings.md。

【免费下载链接】codex-lbCodex/ChatGPT multiple account load balancer & proxy with usage tracking, dashboard, and OpenCode-compatible endpoints项目地址: https://gitcode.com/gh_mirrors/co/codex-lb