KPanel 持久化与数据存储策略

August 2, 2026 · View on GitHub

  • 版本：2026-07-31
  • 状态：长期强制策略

本策略服从仓库根目录的 PROJECT_RULES.md，用于指导 KPanel 根据产品需求选择 JSON、JSONL、SQLite 或 PostgreSQL。存储技术服务于业务，不预设 “全部 JSON”或“全面数据库化”路线。

1. 产品前提

  1. Docker Engine、Nginx、systemd、系统文件、/home/web 和 kejilion.sh 产物是业务 真实状态；任何数据库都不得成为这些资源的第二套事实来源。
  2. Panel 只持久化面板自身数据，例如账户、Session、审计、任务索引、通知、计划和必要缓存。
  3. Agent 的高权限执行状态、完成凭据和有界日志保持独立，不能为了统一查询而扩大 Panel 容器的宿主机权限。
  4. 每一种存储必须有容量、条目数、保留期、清理、备份、恢复和损坏处理规则。
  5. 当前版本继续使用已有 JSON/JSONL 实现；本策略保留 SQLite 的产品演进能力，不增加当前 安装、运行或升级依赖。
  6. 交互终端的 PTY 输出、输入和会话映射只允许保存在有界内存中，不写入 JSON、JSONL、 SQLite、审计或终端回放；进程退出、闲置回收或服务重启即清除。

2. 分层选型

存储适用业务不适用业务
JSON小型配置、单对象快照、完成凭据、导入导出；写入频率低且可整体原子替换持续增长的审计、频繁并发写、多条件查询、跨记录事务
JSONL有界、追加写的监控采样和事件流；按日期分片并按保留期删除高频随机更新、唯一约束、复杂关联和强一致事务
SQLite单机 Panel 的账户、Session、审计、任务索引、通知、计划和结构化历史；需要事务、索引或分页Docker/Nginx/系统实际状态，多 Panel 共享写入，网络文件系统上的数据库
PostgreSQL多 Panel 共享写入、主动高可用、多租户控制面或集中式大规模查询当前单机轻量面板的默认安装

同一业务只能有一个权威写入存储。缓存必须可丢弃并可从权威数据或真实产物重建。

3. SQLite 启用条件

以下任一条件持续出现时，必须进入 SQLite 方案评审，而不是继续扩大 JSON 文件：

  • 单个可变 JSON 文件超过 8 MiB 或有效记录超过 5,000；
  • 整体改写的写入 P95 超过 50 ms，或持续写入超过每秒 1 次；
  • 产品需要跨记录原子事务、唯一约束、外键、稳定分页、组合过滤、聚合或全文检索；
  • 多管理员并发、API Token、通知、计划任务或长期审计使数据关系明显结构化；
  • JSON 解析、复制或整体落盘导致最近稳定基线的延迟、CPU 或峰值 RSS 回退超过 20%。

触发评审不等于立即迁移。实现前必须用真实规模数据比较 JSON/JSONL 与候选 SQLite 驱动的 二进制体积、空闲/峰值 RSS、读写 P95、磁盘放大、升级和恢复时间。

未触发以上条件且结构简单、有明确上限的业务可以长期保留 JSON；不得为了“技术统一”强制迁移。

4. SQLite 强制基线

SQLite 只能用于 Panel 本机持久化，并满足以下要求：

  • 数据库位于本地文件系统；禁止放在 NFS、SMB 或其他网络文件系统。
  • 数据目录权限为 0700，数据库、-wal、-shm、备份和导出默认 0600。
  • 仅 paneld 持有数据库写权限；Agent 不读取 Panel 数据库，Panel 不因此获得宿主机目录权限。
  • 使用参数化 SQL、固定 Schema 和白名单迁移；禁止任意 SQL、动态 ATTACH、运行时扩展加载。
  • 默认启用 foreign_keys=ON、journal_mode=WAL、synchronous=FULL、 trusted_schema=OFF、busy_timeout=5000 和 mmap_size=0。
  • 连接数、事务时长、WAL 大小、查询返回量、分页大小和保留期必须有界；禁止无界全表加载。
  • 数据库文件不是加密保险箱。密码继续使用 Argon2，Token 仅保存不可逆摘要；密钥和高价值凭据 继续使用独立最小权限文件或专用 Secret。
  • SQLite 驱动必须固定版本并纳入 SBOM、漏洞扫描和许可证审查。选型须比较 CGO、跨架构构建、 scratch 镜像兼容、二进制体积和运行时内存，验证前不预先指定驱动。

备份必须使用 SQLite Backup API 或 VACUUM INTO 等一致性方式；WAL 模式下不得仅复制主 数据库文件。恢复前校验格式、摘要、Schema 版本和可用磁盘空间。

5. 数据模型规则

  • Schema 和迁移版本必须单调递增，迁移过程可重复检测，不得依赖页面是否打开。
  • 高频历史数据按时间范围查询并设置保留期；大日志、归档和二进制文件不直接写入数据库。
  • 审计保存动作、对象、结果和必要上下文，不保存明文密码、Token、Cookie 或完整环境变量。
  • 面板缓存字段必须带采集时间和来源；缓存失效时显示未知或重新读取，不能伪装成真实状态。
  • Repository/Store 接口应隔离业务逻辑与存储实现，禁止在 HTTP Handler 中散落 SQL 或文件写入。

6. 迁移与回滚

JSON → SQLite 的迁移必须按以下顺序实施：

  1. 先建立存储接口、Schema、限额和兼容测试，不同时改动无关业务。
  2. 在真实规模副本上验证性能、资源占用、损坏输入、并发写和低磁盘场景。
  3. 升级前生成可恢复的 JSON 备份；迁移在单个 SQLite 事务中完成。
  4. 校验记录数、关键字段、唯一约束、摘要和 integrity_check 后，原子切换存储标记。
  5. 不进行长期双写。短期灰度双读只能用于比对，必须有截止版本和删除计划。
  6. 回滚通过版本化 SQLite → JSON 导出或恢复升级前备份完成；不得直接让旧二进制读取新 Schema。

自动迁移、默认启用或删除旧数据属于 L3 发布；必须覆盖升级中断、重启恢复、回滚和跨架构实机 验收。实验性存储只能显式启用，不能让新旧用户获得不同且无法解释的数据语义。

7. 测试与验收

新增或修改持久化业务至少验证：

  • 空库、新建、读取、更新、删除、分页、过滤和并发写；
  • 旧版本升级、重复启动、迁移中断、磁盘写满、只读文件系统和损坏文件；
  • 原子性、唯一约束、外键、权限、敏感字段脱敏和超限拒绝；
  • 备份、恢复、回滚、integrity_check 和旧格式兼容；
  • 真实规模下的二进制体积、空闲/峰值 RSS、读写 P95、磁盘增长与基线对比；
  • amd64、arm64 和正式支持的 Linux 发行版。

每次设计评审必须明确：权威事实来源、选用的存储、容量模型、保留期、事务边界、查询模式、 安全边界、迁移版本、备份恢复和回滚点。

8. PostgreSQL 边界

只有出现多 Panel 共享写入、主动高可用、多租户隔离或单机 SQLite 已有实测瓶颈时，才评估 PostgreSQL。引入前必须给出连接管理、部署依赖、备份恢复、网络加密、凭据轮换、离线降级和 运维成本方案。当前单机产品不得仅为“以后可能集群化”提前增加外部数据库依赖。