更新与数据库迁移

Lite 可以从已有 Lite、旧 Komari Lite 以及已支持的上游数据库来源升级。更新程序、迁移数据和更新 Agent 是三个独立步骤；容器或服务已经启动，不代表数据库迁移和节点连接已经完成。

更新前

1. 在“关于”页面记录当前版本和七位构建码。
2. 停止会继续写入数据的旧实例。
3. 备份程序和完整 data 目录，不要只复制单个 .db 文件。
4. 确认磁盘可以同时容纳现有数据库、迁移临时数据和 WAL。
5. 记录当前监听端口、HTTPS、反向代理、数据挂载和外置数据库配置。

先确认备份可用

数据库迁移会改变存储结构。正式更新前至少保留一份不与运行目录共用的完整备份，并确认能够读取备份文件。

Docker 更新

拉取当前正式版镜像：

docker pull ghcr.io/nuomiiiii/lite:latest
docker rm -f lite

随后使用原来的端口、环境变量和 data 挂载重新创建容器。不要为更新临时改用新的空目录，否则页面会表现为首次安装。

docker run -d \
  --name lite \
  --restart unless-stopped \
  -p 27777:27777 \
  -v "$(pwd)/data:/app/data" \
  ghcr.io/nuomiiiii/lite:latest

镜像包含 linux/amd64 和 linux/arm64。使用 Compose 时执行 docker compose pull 后重新创建服务即可，不需要修改为固定版本标签。

Linux 脚本更新

由官方 Linux 脚本安装并由 lite.service 管理的实例，可以重新运行安装脚本并选择更新。脚本会确认当前服务和数据目录，替换程序后重新启动服务；更新失败时会尝试回滚程序文件。

更新前不要手工删除 /opt/lite 或 data。旧 Komari Lite 脚本部署迁移后使用 /opt/lite、Lite 二进制和 lite.service，不要让新旧服务同时指向同一份数据。

支持的迁移来源

当前迁移路径覆盖：

• 已验证的上游 1.3.1、1.3.2 数据库来源。
• 上游 1.4.x 指标数据库及 zstd 压缩的指标摘要。
• Lite 2.1.7 及之后的正式版。
• 已经使用早期快照数据库格式的测试实例。
• Komari 或 Lite 生成且通过结构校验的完整备份 ZIP。

“支持迁移”只表示这些来源的数据转换已经适配，不表示 Lite 与上游的数据库结构、镜像、后台和完整备份格式完全相同，也不自动包含未列出的上游版本。

如果同一份数据库同时包含两套完整的上游指标布局，迁移会拒绝继续，避免误选源表。不要通过删除数据表来绕过检查。

迁移过程中会发生什么

• 页面显示当前阶段、进度和错误；应等待页面明确显示完成。
• 指标、延迟和丢包记录会转换为当前紧凑格式。
• 上游 zstd 指标摘要会在迁移时读取并转换。
• 旧数据每批成功后才清理；单批失败会回滚并保留原数据。
• 已删除服务器或探测任务的历史残留会被清理。
• SQLite 释放出的空闲页会优先复用，数据库文件不一定立即变小。
• 原有数据保留天数会继续保留，分层降采样由当前版本统一管理。

不要中断正在写入的迁移

不要同时启动两个 Lite 实例指向同一个 data 目录，也不要在迁移过程中手工替换数据库文件。

更新后检查

• “关于”页面是否显示预期版本与构建码。
• 数据库页面是否仍有迁移错误或待处理项目。
• 服务器在线状态、最后上报时间和探测任务是否正常。
• 历史曲线是否覆盖原有保留周期。
• 日报、周报、月报和流量统计方式是否符合服务器设置。
• 账单中心的资费、月度/年度合计、附加费用和剩余价值是否正常。
• 远程终端和文件管理能否通过当前反向代理建立连接。
• 内置 HTTPS、Cloudflare Tunnel 和公开大屏主题是否可以正常访问。
• Lite-agent 是否为当前兼容版本，服务日志是否持续显示正常连接。

如果希望立即把 SQLite 空闲页归还给磁盘，可在业务低峰期执行“回收空间”。这不是每次更新都必须执行的步骤。