数据库(主库 / 次库)
2026/11/17大约 4 分钟约 1261 字
数据库(主库 / 次库)
CloudNETP 支持两种数据库:MySQL(适合多设备、远程、数据量大)和 SQLite(单文件、零运维)。 你可以分别指定「主库」和「次库」用哪一种,次库还可以不设置。
- 主库:平时真正在读写的那一个。
- 次库:主库连不上时自动接管的备胎;主库正常时定期把数据复制过来。
- 次库不设置:只跑主库,没有容灾、没有自动回切,最省事也最不容易出意外。
两种库可以任意组合 —— 主库 MySQL + 次库 SQLite(最稳)、主库 SQLite + 次库 MySQL (本机快、远程备份)、两个都是 SQLite(两份文件互为备份)、以及只设主库。
怎么选
管理后台 → 系统设置 → 数据库:

两个下拉分别选主库与次库的类型,点「保存并切换」即可,改完立刻生效,不用重启:
| 操作 | 会发生什么 |
|---|---|
| 只改次库 | 立即重建次库连接并镜像一份最新副本;选「不使用」则停掉镜像与自动回切 |
| 改主库 | 先连目标库并探活,探通了把当前库的数据整体复制过去(按主键 upsert),旧库原样保留;目标库连不上就报错,当前库保持不变 |
| 保存 | 选择记在 storage/db/roles.json,重启后仍然是这套角色;优先级高于 .env |
数据不会被清空
换主库只是把数据复制到新库,旧库文件 / 旧 MySQL 里的数据都还在。 确认新库跑稳了再自行清理,不用急着删。
也可以直接改 .env:
# 主库:mysql 或 sqlite(留空 = 按 DATABASE_URL 自动判断)
DB_PRIMARY=mysql
# 次库:mysql / sqlite / none(留空 = 跟着 DB_FALLBACK_ENABLED 走)
DB_SECONDARY=sqlite容灾是怎么跑的
| 阶段 | 行为 |
|---|---|
| 正常 | 每 DB_MIRROR_INTERVAL 秒把主库全表镜像进次库(审计日志只留最近 5000 条) |
| 主库断连 | 看门狗按 DB_PROBE_INTERVAL 探测,失败后新请求全部改走次库,并写 __failover_dirty 标记;文件本体在磁盘,不受影响 |
| 主库恢复 | 先把降级期间的变更回迁主库(按主键覆盖),成功后切回主库并立即重新镜像 |
降级期间重启也没关系:启动时发现 __failover_dirty 会先回迁再镜像,不会把这段时间的写入盖掉。
几条边界
- 按单实例部署设计。多实例同时写主库时,「以次库为准」的回迁会打架 —— 这种部署请把次库设成「不使用」。
- 如果次库是从未镜像成功过的新库(
__failover_mirror_at不存在),回迁只补缺失行、 绝不覆盖主库:宁可少迁,不能拿空库盖掉线上数据。 - 次库与主库都选同一个 MySQL 库等于自己备份自己,后台会直接当作「不使用」。
- 主库选 SQLite 时用的是
DATABASE_URL本来指向的那个文件(默认dev.db); 主库原本是 MySQL 则落在storage/db/primary.db。次库固定是storage/db/fallback.db(可用SQLITE_PATH改)。 - 切换瞬间正在飞行的请求可能失败一次(旧连接已断),重试即可。
- 内部标记键都以
__开头,只写进次库,不会被同步进主库。 - 镜像与回迁都按表逐行 upsert、单表一个事务;中途失败下一轮重试,不会写坏数据。
卡片上的其他按钮
| 按钮 | 作用 |
|---|---|
| 刷新配置 | 重读 .env 里的数据库与容灾参数,就地更新配置、重建连接池并重新探活;连接串变了会一起生效 |
| 重新连接主库 | 丢弃旧连接池重新握手;若当前跑在次库,先回迁数据,回迁成功才切回,连不上就报错并保持现状 |
| 切到次库 | 先镜像一份最新副本,再切到次库服务;切过来后暂停自动回切(否则看门狗很快又切回去),点「重新连接主库」或重启进程才恢复 |
刷新、换库与手动切换都会写审计日志(admin_db_refresh / admin_db_roles / admin_db_reconnect)。
环境变量优先级更高
「刷新配置」只覆盖从 .env 读到的值。用 systemd / 命令行显式 export 的同名变量优先级更高, 不会被文件覆盖 —— 想彻底改就用环境变量管理工具改。
相关环境变量
| 变量 | 说明 |
|---|---|
DATABASE_URL | MySQL 连接串;写成 sqlite:///./dev.db 时它就是 SQLite 主库的文件 |
DB_PRIMARY | 主库类型:mysql / sqlite;留空按 DATABASE_URL 判断 |
DB_SECONDARY | 次库类型:mysql / sqlite / none;留空跟着 DB_FALLBACK_ENABLED 走 |
DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME | 分开写 MySQL 连接信息(DATABASE_URL 留空时用) |
DB_FALLBACK_ENABLED | 老开关,等价于「次库 = sqlite / none」,DB_SECONDARY 有值时以它为准 |
DB_PROBE_INTERVAL | 探活间隔秒数,0 表示只在启动时选库、运行期不切换 |
DB_MIRROR_INTERVAL | 主库 → 次库镜像间隔秒数,0 表示不做周期镜像 |
SQLITE_PATH | 次库 SQLite 文件位置,默认 storage/db/fallback.db |
DB_CONNECT_TIMEOUT / DB_TIMEOUT | 远程库连接与读写超时(秒),链路慢时调大 |
