Lite 文档

Appearance

更新与数据库迁移 ​

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

更新前 ​

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

先确认备份可用

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

Docker 更新 ​

拉取当前正式版镜像：

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

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

bash
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 脚本直装、并满足安全回退条件的实例，在后台发现新版本后会显示更新窗口。systemd 主机和 OpenWrt / iStoreOS 的 procd 实例均可使用。确认版本和更新说明后，点击“立即更新”即可完成下载、校验、备份、程序替换和服务重启；服务恢复后页面会自动刷新。

如果新版本未能正常启动或通过检查，Lite 会尝试恢复更新前的程序和数据。即使支持自动回退，正式更新前仍应自行保留一份完整备份。

在线更新仅支持符合条件的 Linux 直装实例。Docker、Windows、非 systemd/procd 服务、外置指标数据库或无法安全备份和恢复数据的目录布局不会显示“立即更新”，更新窗口会改为提供 GitHub Release 入口，请按对应部署方式手动更新。具体条件见一键更新的限制。

通过安装脚本更新 ​

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

无论使用哪种方式，更新前都不要手工删除 /opt/lite 或 data。旧 Komari Lite 脚本部署迁移后使用 /opt/lite、Lite 二进制和对应的 Lite 服务，不要让新旧服务同时指向同一份数据。

支持的迁移来源 ​

当前迁移路径覆盖：

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

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

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

服务端迁移后迁移 Agent ​

从上游 Komari 完成服务端和数据库迁移后，先确认原有节点记录仍在 Lite 后台，再到每台仍运行上游 komari-agent 的服务器执行 Agent 迁移。不要在 Lite 中重新添加节点，也不要重置或替换原节点 Token。

主控地址没有变化时，在节点上执行下面一条命令：

bash
curl -sL https://raw.githubusercontent.com/nuomiiiii/Lite-agent/main/migrate.sh | sudo bash

迁移脚本会读取原 komari-agent 的主控地址、Token 和启动参数，安装 Lite-agent，并在新服务成功启动后才卸载上游 Agent。完成后回到 Lite 后台，确认原节点恢复在线且历史数据仍归属于同一节点。

主控地址已经变化、Windows 节点和 Docker Agent 的迁移方法见从上游 komari-agent 迁移。具体变更记录见 Lite-agent 2.3.6.0 Release。

升级到 Lite 2.3.7 ​

Lite 2.3.7 推荐配套 Lite-agent 2.3.6.0，默认主题为 Lite-Theme 1.2.4。本次新增定时任务，可在“远程管理 → 定时任务”创建按间隔、每天、每周或每月执行的命令；更新不会自动创建任务。创建或启用前，需检查站点与节点的远程管理开关，并完成身份验证。

从 Lite 2.3.6 升级时，沿用原部署方式和数据目录，更新后在“关于”核对版本与构建码。Agent 已为 2.3.6.0 时，可继续配合定时任务使用；旧节点应升级到当前配套版本。文件二进制传输和并行上传需要服务端、后台和 Agent 同时支持，详见远程终端与文件。

此前的通行密钥、头像和全局自动登出设置继续保留，已有账号和密码不会被自动修改。通行密钥与注册时的域名绑定，更换域名时应保留密码或 SSO 等备用登录方式。

功能更新后检查
定时任务按需新建并启用；日历定时使用北京时间，创建后核对下次执行时间和节点结果
通知渠道原渠道会自动分配到各类事件；可改为按事件选择多个渠道，渠道参数与分配分别保存
告警汇总推送默认关闭，按需开启并设置 1–3600 秒的汇总时间，默认 5 秒
MCP 授权既有授权仍为临时授权；长期授权需重新申请并明确勾选，临时最长时长可调至 72 小时
续费日历已有仪表盘配置会补入并开启，可调整位置、宽度或关闭
Lite-Theme更新到 1.2.4 后可配置每台节点的首页探测任务；手机端概览默认关闭

仪表盘的平均时延、延迟抖动和近 15 分钟丢包改为按“服务器 + Ping 任务”分别展示，同一节点可能出现多条记录。重置节点 Token 后，旧 Token 最多保留 24 小时，新 Token 首次成功连接后会提前使旧 Token 失效；应在原节点直接执行新的部署指令，无需先卸载 Agent。

当前 Lite-agent 继续提供从上游 komari-agent 接续原节点的专用迁移脚本。服务端迁移完成后按服务端迁移后迁移 Agent处理，不要使用新节点的 Token 覆盖旧身份。已有节点只设置了流量重置日时，升级后继续按 Asia/Shanghai 当天 00:00:00 重置；需要精确重置时，可由 Lite 下发时区、日期和时分秒。

Lite 的 Docker 镜像不再内置 cloudflared。继续使用后台 Cloudflare Tunnel 管理时，需要自行提供可执行文件或单独运行 cloudflared 容器，详见反向代理与 Tunnel。

Lite 2.3.3 以前的兼容提示 ​

Lite 2.3.3 只接受 Agent 协议 2，推荐升级到当前 Lite-agent 2.3.6.0。只支持旧协议的 Agent 在服务端更新后将无法继续上报；旧协议 2 Agent 即使仍能监控，也需要升级到配套版本才能使用 MCP 完整管理。

从更早版本升级时，还需处理已下线的自动发现安装。新节点及 Docker 重建应使用后台为具体节点生成的普通部署命令。旧安装仍带 --auto-discovery 时，Lite-agent 只读取已有 auto-discovery.json 继续使用原节点身份；文件缺失、损坏或身份不完整时会停止启动，不会重新注册。更新前请按旧自动发现安装迁移改用原节点的普通部署命令。

远程管理在新安装中默认关闭，需要同时开启站点“允许远程管理”和 Agent 本地 --enable-remote-control。已有 Lite 实例和 Agent 升级时会保留原有远程可用状态；旧 Agent 配置中的 disable_web_ssh 会由新版 Agent 迁移为正向设置，不需要先手工删除旧配置。

Docker Agent 如果没有保留原有远程控制配置或状态，也没有显式传入远程开关，重建后默认关闭远程控制。需要继续使用远程管理时，请在原容器参数中明确加入 --enable-remote-control 后重建，不能只依赖旧容器曾经可用。

更新后请重新检查远程终端、文件管理和远程执行。旧远程终端协议已经移除，不支持当前协议的 Agent 会直接提示升级，不会回退到旧通道。

MCP 代理默认关闭。需要使用时，在“系统设置 → 通用”中额外开启“启用 MCP 代理”，再按MCP 代理与 AI 授权连接客户端并选择节点授权。已有远程终端授权不能直接用于 MCP。

仪表盘新增“近 30 天流量”摘要。已有布局缺少该模块时，会放在“流量概览”后，并沿用流量概览的开关状态；可以在“仪表盘配置”中调整。

迁移过程中会发生什么 ​

  • 页面显示当前阶段、进度和错误；应等待页面明确显示完成。
  • 指标、延迟和丢包记录会自动转换为当前格式。
  • 迁移失败会停止并保留原数据，页面会显示错误。
  • 已删除服务器或探测任务的历史残留会被清理。
  • SQLite 释放出的空闲页会优先复用，数据库文件不一定立即变小。
  • 原有数据保留天数会继续生效。

不要中断正在写入的迁移

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

更新后检查 ​

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

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

基于 MIT 许可证发布

Lite 文档 · 部分结构参考上游项目