### 提交前自查 - [x] 已搜索现有 Issues 与 CHANGELOG.md,没有同范围的功能请求。 ### 当前使用的版本 需求评估基于原仓库 `main` 源码:`eee8f6ecb6ca04455e6edef0c8e498fb3be21f21`,`VERSION=1.3.207`。 ### 使用场景 / 痛点 希望将 vm2api 用于规模更大的多租户、多账号场景。随着请求量和日志保留量增长,请求日志、计费、额度、账号状态与后台任务会持续写入同一个数据库,需要更好的并发写入能力、独立数据库运维能力,以及后续多个控制面实例共享业务数据的基础。 当前 [`src/lib/db/database.mjs`](https://github.com/dofastted/vm2api/blob/eee8f6ecb6ca04455e6edef0c8e498fb3be21f21/src/lib/db/database.mjs#L1-L19) 明确采用单进程、同步 `node:sqlite.DatabaseSync` 和本地 SQLite WAL 文件。SQLite WAL 同时只允许一个写入者,并依赖同机共享内存,不能通过把数据库文件放到网络共享盘来实现跨节点多副本共享。相关约束见 [SQLite 官方 WAL 文档](https://www.sqlite.org/wal.html#concurrency)。 因此,现有存储方式不能满足这里需要的大规模、高并发写入及跨节点共享部署目标。这里提出的是架构与扩展能力需求,具体吞吐上限应由项目工作负载压测确定。 ### 建议方案 将大规模部署的控制面业务持久化迁移到 PostgreSQL(PG),并提供现有 SQLite 安装的正式迁移路径。 1. **运行数据迁移**:覆盖用户、API 密钥、账号、额度与调度状态、代理与节点、请求日志、计费统计、配置及备份记录。使用异步驱动和连接池,保持事务边界,保证并发额度与余额更新的原子性。 2. **存量迁移工具**:从一致的 SQLite 快照导入;保留主键、关联关系、密文和 64 位计数,处理自增序列。逐表核对数量和内容,失败回滚,保留原库与文件快照,并说明切换和回退条件。 3. **备份恢复**:支持 PG 备份、恢复及旧备份转换。明确数据库与 VM/配置文件的一致性窗口,保留既有凭据目录和加密密钥。 4. **部署运维**:提供数据库连接配置、支持的服务端/客户端版本、部署及升级说明、连接池/数据库监控,并在 CI 中使用真实 PG 做回归。 ### 验收条件 - 业务运行与持久化使用 PG,覆盖正常请求、流式请求、日志、计费、额度、重启、备份和恢复。 - 当前及受支持历史 SQLite 数据可迁移;导入失败不留下部分业务数据,迁移前后业务值可核对。 - 并发写入不丢失计数或余额变更;提供包含日志写入、账单更新和统计查询的可复现压测结果,报告延迟、吞吐和错误率。 - 提供从现有部署切换到 PG 的操作文档及自动化测试。 ### 现有替代做法 增加控制面宿主机资源、缩短日志保留时间或优化 SQLite 参数,仍然保留同一数据库的写入串行化和本地文件约束。共享 SQLite 文件也不能作为跨节点扩容方案。 ### 关联需求 关联 #376(控制面主备高可用与平滑升级)。PG 提供共享持久化基础;多副本调度、限流和任务协调还需要单独设计。
Activity
liubing0806 commentedon Oct 21, 2026
补充目前的实现,已通过 fork 分支向上游提交 Draft PR:#649。
cf9462d5501c323efa95c254feb3821f7cf656f0eee8f6e逐项比较,断言相同。实际结果及验证 SHA 均已保留在分支中的报告和基线对照里。验证报告:https://github.com/liubing0806/vm2api/blob/codex/postgresql-migration/docs/plans/2026-10-21-postgresql-migration-results.md
原生 ARM64 构建运行、生产规模压测和现有部署切换尚未验证,因此先以 Draft 供评审。活凭据仍保留既有槽位/CLI-home 存储,迁移必须保留对应目录与原业务加密密钥。该实现提供共享数据库基础,#648 的多副本协调需要后续独立实现。