兼容与公共接口

Lite 的内部数据库会继续演进，主题和外部集成应使用公共 API 或 RPC，不应读取数据库表。

兼容原则

• 旧字段能明确映射时保留字段名，返回新版统一口径。
• 新字段不会改变原有字段的类型。
• 公共接口缺失或权限不足时，主题应显示可理解的空状态。
• 管理接口必须保持登录与权限校验，不能为了主题兼容开放内部数据。

实时状态

公共 WebSocket 和 common:getNodesLatestStatus 返回服务器最新状态。当前周期校准后的上传与下载、国家/地区和本周期有效额度会在服务端统一映射，主题不需要了解内部迁移表。

主题节点资料

common:getNodes 使用独立的主题节点结构。无论匿名访问还是管理员已经登录，都不会返回以下后台字段：

• Agent 版本和私有备注。
• 部署状态、远程协议、远程控制状态及 MCP 能力字段。
• 重置流量追加额度与内部周期标记。
• 节点创建时间和更新时间。

节点 UUID、名称、硬件信息、地区、公开备注、分组、标签、带宽、账单和生效流量额度等主题展示字段仍会返回。账单到期瞬间使用 expired_at，并附带 expiry_timezone。已启用流量重置的节点还会返回重置日期、时间、时区和下一次重置时刻，主题可直接使用 traffic_reset_at，不必自行换算时区。匿名访问继续过滤隐藏节点，并按站点的访客 IP 设置决定隐藏或脱敏 IP；管理员登录不会让上述后台字段重新出现在 common:getNodes 中。

/api/nodes 和对应的 public:getNodesInformation 是单独保留的兼容接口。它们对所有调用者固定清空响应中的 version、remark、ipv4、ipv6，并在 JSON 中省略这些字段，也不返回 mcp_full、mcp_full_version；管理员登录或使用 API Key 也不会返回。登录状态只影响这里是否过滤隐藏节点。新主题应优先依赖 common:getNodes 的公开字段。

流量口径

第三方主题应区分：

• 当前周期校准后的生效上传与下载。
• 当前统计方式计算出的用量。
• 本周期有效额度。
• 计费节点筛选结果。

公共接口中的现有上传、下载字段已经包含当前周期生效的校准结果。主题不应读取内部校准记录后再次叠加，也不应把“额度追加”当作实际用量。未设置价格的节点不要擅自纳入计费汇总。

流量校准只修正当前计费周期的有效用量，不会改写 Agent 原始累计计数。需要展示服务商计费进度、当前用量或告警状态时，应直接使用公共接口返回值，确保与仪表盘和报告一致。

历史接口

较长时间范围可能返回降采样后的数据。主题不应假设所有时间范围都存在原始秒级点，也不应依赖每个指标拥有完全相同的采样间隔。

仪表盘跳转属于另一项显式能力。主题可以在 Lite-theme.json 中声明服务器详情、网络总览和 Ping 任务参数；旧 komari-theme.json 继续兼容，未声明时使用安全回退。具体格式见 主题开发指南。

版本探测

遇到不同版本接口差异时，可以按能力判断接口是否存在，但应集中在单一适配层中，避免每个组件各自维护 try/catch 和回退分支。

私有站点

私有站点在登录前仍会加载当前主题所需的站点信息，使访问提示和登录入口能够保持主题风格。主题应先检查 /api/public 的 private_site 和 /api/me 的登录状态，再决定是否连接 RPC 和实时数据。

收到 HTTP 401、RPC 未认证错误或明确的私有站点拒绝后，应停止当前 RPC 连接与自动重连，显示登录提示。用户完成登录或主动刷新后再重新建立连接，不要在未登录状态下持续请求 /api/rpc2。

安全边界

管理员会话、2FA 验证结果、远程授权、备份和私钥路径都不是主题公共数据。远程管理需绑定当前管理员登录会话的短期授权，同源运行不能代替这些校验。