Neomega

外观

备份与恢复 ​

neomega-maintenance 随运行包提供。备份、恢复与对账都在相关 Host 和服务器停止后执行；工具不会自动启动 Host、服务器或插件。

选择备份范围 ​

profile包含内容适用范围
host-instance明确列出的 Host 数据库、插件制品和数据、配置、凭据及外置材料Host 迁移、升级前备份；不包含远端游戏世界
local-serverHost 状态，加一个具有固定 world_id 的本地服务器根目录对本机服务器文件具有管理权限的整套备份

机器人无法导出网易租赁服的完整底层世界存档。区域导出、单插件备份或 Host 数据库均不能代替世界备份。外部拷贝材料使用 backup import 导入时标记为 external/unverified，不会因此变成已证明一致的整服快照。

1. 登记离线维护范围 ​

正常停止 Host、服务器与自动重启服务后，编写 profile-spec.json。以下示例对应默认离线 Host；替换为自己的绝对路径：

json
{
  "version": 1,
  "kind": "host-instance",
  "world_id": "my-server",
  "database": "/srv/neomega/state/runtime-offline.db",
  "catalog": "/srv/neomega/state/plugins-offline/catalog",
  "roots": [
    {"id": "state", "kind": "host", "path": "/srv/neomega/state"}
  ]
}

database 指向主 Host 数据库；其他 Host 数据库列入 host_databases 数组，插件或其他附属 SQLite 列入 databases 数组。同一路径不能同时属于两类，漏列 SQLite 会使备份被拒绝。所有数据库均取一致性快照；只有 Host 数据库执行 Host 恢复准备、操作隔离与逐安装对账。附属数据库保留快照内容，受同一实例围栏保护，其业务状态须纳入所属安装的对账证据。live 与 offline 状态分开，不能把上述离线文件名直接用于 live 实例。catalog 指向插件管理目录内的 catalog 子目录。

每个 roots 项须有唯一逻辑 ID，根路径不能重叠或包含符号链接。所有数据库、catalog、JSON 配置及引用的外置文件都须被根覆盖。外置 token、动作工件和私有配置应增加独立根；不要把凭据留在备份范围之外。可选 config 必须是可安全重映射路径的 JSON 文件，不是 shell 环境文件。

本地服务器 profile 把 kind 改为 local-server，保留稳定的 world_id，并加入服务器文件根：

json
{"id": "world", "kind": "world", "path": "/srv/bedrock-server"}

在运行包目录登记。--profile 输出必须是新文件，生成的文件仅供运行账户访问：

sh
./neomega-maintenance profile enroll --spec /private/profile-spec.json --profile /private/host-profile.json

Windows 使用 .\neomega-maintenance.exe，JSON 中的 Windows 路径写成 C:\\Neomega\\state。维护工具本身不需要 Python。

登记不能证明不协作的旧程序已经停止。旧版本或外部程序必须先由管理员正常停止，不能只看 PID 消失或删除锁文件。已登记的 Host、维护工具和本地服务器监督器使用相同根锁，锁冲突时停止操作。

本地服务器的停止证据 ​

local-server 首次登记后，在已确认服务器停止的前提下执行：

sh
./neomega-maintenance server enroll --profile /private/host-profile.json

此后通过监督器运行前台服务器命令，例如 Linux：

sh
./neomega-maintenance server run --profile /private/host-profile.json -- /srv/bedrock-server/bedrock_server

监督器以 world 根为工作目录，持有维护锁并记录进程树停止状态。备份前按服务器自身方式正常关闭并等待监督器退出；停止证据缺失、仍在运行或结果不明时不会认定安全。不要编辑状态标记来绕过检查。

2. 创建与检查归档 ​

先检查备份范围，再创建不存在的新归档文件：

sh
./neomega-maintenance backup plan --profile /private/host-profile.json
./neomega-maintenance backup create --profile /private/host-profile.json --archive /private/host-before-upgrade.tar.gz
./neomega-maintenance backup inspect --archive /private/host-before-upgrade.tar.gz

归档记录逻辑根、文件摘要及来源证据；SQLite 使用一致性快照包含已提交 WAL 内容，不靠直接复制 .db 文件。归档可能包含凭据、配置和业务账本，只存放在私有目录，不加入插件包或网站下载目录。

外部离线材料使用 backup import --profile ... --archive ...，必须明确承认来源尚未核实；该命令不能绕过后续恢复围栏与人工对账。

3. 恢复到新目录 ​

使用相容版本的运行包，目标目录必须不存在。--root-map 为归档中每一个逻辑根提供目标下的相对位置；不能遗漏或加入未知 ID。映射不能使用目标顶层的 profile.json、path-remap-audit.json 或其子路径，也不能包含带 .neomega- 的路径段：

sh
./neomega-maintenance backup restore --archive /private/host-before-upgrade.tar.gz --target /srv/neomega-restored --root-map '{"state":"state"}'
./neomega-maintenance recovery inspect --target /srv/neomega-restored

local-server 增加 world 映射，例如 '{"state":"state","world":"server"}'；更多根也须逐个映射。恢复会核对摘要和路径，将已知数据库与 JSON 配置路径改为新位置，并保留私有路径映射审计。不能识别的外部绝对路径会阻止恢复，不继续引用旧目录。

恢复输出包含 receipt、epoch、archive digest、world identity 与新 profile。目标下的 profile.json 是重映射后的维护配置，不能直接作为 Host 启动环境文件使用。后续启动时需让 NEOMEGA_AGENT_STATE_DIR、外置 token 与管理目录等环境设置指向新根。

恢复后所有安装保持禁用，持久恢复围栏阻止世界写入。非终态操作进入恢复隔离：包括旧 accepted 和 unknown，解除围栏后也不会重新发送。原 journal、receipt、digest 与代际历史保留；完整数据回退不撤销备份之后已经发生的游戏操作。

4. 准备逐项对账证据 ​

保留 recovery inspect 输出，在私有目录创建证据 JSON。以下是结构示例，所有身份、数据库路径、安装和 pending 项均须从本次 inspect 结果复制，说明及文件摘要须换成真实材料；没有 pending 时使用空数组：

json
{
  "receipt": "本次receipt",
  "epoch": "本次epoch",
  "archive_digest": "本次归档SHA256",
  "world_id": "my-server",
  "roots": [{"id":"state","kind":"host","path":"/srv/neomega-restored/state"}],
  "operator": "维护者名称",
  "observed_at": "2026-10-03T12:00:00+08:00",
  "world_difference": "说明备份时点到当前世界状态的差异及核对方法",
  "evidence": [{"path":"/private/world-ledger.txt","sha256":"实际文件SHA256"}],
  "pending": [{
    "database":"/srv/neomega-restored/state/runtime-offline.db",
    "id":"inspect中的原操作ID",
    "state":"unknown",
    "observation":"原操作的外部观察结果；不自动重放",
    "evidence":[{"path":"/private/operation-ledger.txt","sha256":"实际文件SHA256"}]
  }],
  "installations": [{
    "database":"/srv/neomega-restored/state/runtime-offline.db",
    "installation_id":"inspect中的安装ID",
    "configuration":"配置与当前用途核对结果",
    "kv":"KV与业务账本核对结果",
    "business_ledger":"备份之后业务记录及处置说明",
    "pending_intents":"未完成业务意图的处置说明",
    "approved":false,
    "evidence":[{"path":"/private/plugin-ledger.txt","sha256":"实际文件SHA256"}]
  }]
}

roots 须与 inspect 一致，包括顺序与 kind。每个 pending 和安装都必须有相应记录（包括返回的保留安装与 service: 标识），证据文件必须存在且 SHA-256 相符。approved:false 表示该安装尚不允许启用；只有确认配置、KV、未完成意图与业务账本均已核对的安装才设为 true。不能用一句“同意恢复”或统一布尔开关替代材料。

Host-only 恢复必须提供当前世界及业务账本的外部对账材料。本地服务器完整恢复可使用同批世界文件与 Host 快照摘要说明共同恢复的时间点。工具校验材料的完整性与身份绑定，不自动证明外部观察为真。

5. 审阅计划并解除围栏 ​

证据 JSON 保持私有权限（Linux / macOS 可执行 chmod 600 /private/reconciliation.json）。先生成计划摘要，再把返回的 plan_sha256 作为 apply 参数：

sh
./neomega-maintenance recovery reconcile-plan --target /srv/neomega-restored --evidence /private/reconciliation.json
./neomega-maintenance recovery reconcile-apply --target /srv/neomega-restored --evidence /private/reconciliation.json --expected-plan PLAN_SHA256

计划生成后状态或证据变化会使 apply 拒绝，需重新核对并生成计划。缺项、冲突或证据不全时保持围栏，不删除标记强行启动。

解除整实例围栏不会改写历史操作结果，不会清除其他领域恢复要求，也不启用插件或启动任何服务。恢复到新根后，按自行部署手动启动 Host，并依照管理插件检查配置与权限；只有同一恢复 epoch 已获逐安装批准、且没有未解决领域围栏的安装才可显式启用和启动。未批准的安装继续保持禁用，隔离的旧操作不自动重放。

进程退出不明时先恢复停止证据 ​

监督器崩溃或进程树退出无法确认时，不能重新 server enroll 覆盖旧记录。外部导入的世界归档若保留 running 标记，也须先处理停止证据，再进入上面的 recovery 对账。

在执行 process inspect 前，先完成以下步骤：

  1. 保存原 unknown 标记和现有监督诊断，不删除、改写标记或锁文件。
  2. 通过原进程管理器正常停止持锁的 Host 或服务器监督器；若它无法退出，由管理员使用操作系统管理工具明确终止该持锁进程。维护工具不会自动杀进程。
  3. 独立核实可能遗留的 Worker、服务器及全部后代进程已终止，保存能对应原进程身份和故障时点的操作系统证据。原持锁进程 PID 消失或成功取得锁，都不能证明后代已停止；无法证明时保持 unknown，不继续备份或启动。
  4. 原持锁进程退出后，才执行下面的 process inspect。若仍有锁冲突，先查明持锁者；不要删锁或跳过检查。

恢复后的 profile 使用新目标下的 profile.json：

sh
./neomega-maintenance process inspect --profile /srv/neomega-restored/profile.json

在所有根之外保存私有证据 JSON。inspection 必须完整原样使用该命令的 JSON 输出，包括 profile、markers 与存在时的 server；不要重建或删除原记录。其余字段如下：

json
{
  "inspection": {},
  "operator": "维护者名称",
  "observed_at": "2026-10-03T12:00:00+08:00",
  "process_tree_termination": "说明如何确认原服务器及其全部子进程均已停止",
  "unparsed_records_explanation": "如有parse_error，说明原记录为何无法解析及采用的独立终止证据",
  "evidence": [{"path":"/private/termination-record.txt","sha256":"实际文件SHA256"}]
}

若 inspect 的 marker 或 server 含 parse_error，仍须保留输出中原始 content、sha256 与记录身份；不要修写损坏内容、补造旧 epoch 或重新登记覆盖它。此时 unparsed_records_explanation 必填，说明无法解析的原因及如何凭独立材料确认后代进程全部终止；没有解析错误时可省略该字段。缺少说明会使计划被拒绝。

把示例空对象替换为真实完整 inspection；终止说明必须有文件证据支持，观察时间晚于监督失败时点。管理员提供的终止判断与原工具监督结果是两类证据：原 unknown 记录仍保留，维护工具只验证管理员材料的绑定与完整性，不把它改称自动监督已证明终止。证据与计划文件都使用绝对路径，且位于所有 profile 根之外。生成并审阅计划，然后传入返回的摘要：

sh
./neomega-maintenance process reconcile-plan --profile /srv/neomega-restored/profile.json --evidence /private/process-evidence.json --plan /private/process-plan.json
./neomega-maintenance process reconcile-apply --profile /srv/neomega-restored/profile.json --evidence /private/process-evidence.json --plan /private/process-plan.json --digest PLAN_SHA256

apply 会重新核对完整根摘要及原标记身份，保留原 unknown / running 历史，只按明确停止证据处理进程状态。它不解除实例恢复围栏，不解除操作隔离，也不启动服务；继续完成本页的逐安装恢复对账。

若 apply 部分完成后报错，保留原记录、证据及仍在的围栏，重新 process inspect 取得当前状态，再用新的完整 inspection 和证据生成新计划。不要删除剩余标记或复用已过期计划绕过检查；进程对账成功也不替代实例恢复对账。

Neomega · 使用、开发与参考文档