自行部署

从版本与升级取得与机器匹配的完整运行包。开发工具包只用于编写插件，不能替代 Host；不需要克隆或编译框架源码。

选择平台与准备环境

系统与架构	运行包
Linux x86-64	neomega-runtime-linux-amd64.tar.gz
Linux ARM64	neomega-runtime-linux-arm64.tar.gz
Windows x86-64	neomega-runtime-windows-amd64.zip
macOS Intel	neomega-runtime-darwin-amd64.tar.gz
macOS Apple Silicon	neomega-runtime-darwin-arm64.tar.gz

Windows 需要 Windows 10 / Server 2016 或更高版本，以及允许创建和分配 Job Object 的运行环境。macOS 包未签名、未公证；按系统提示核对可信来源，不要全局关闭 Gatekeeper。

Go 插件运行不需要 Python；Python 插件与 runtime-admin.py 管理工具需要 Python 3.10+。维护工具 neomega-maintenance 是独立程序，不依赖 Python。运行包包含离线与 live Host、实例目录程序、制品检查器、维护工具和同批 Python / Go SDK，不要混用不同版本。

使用专用运行账户：程序目录可读和执行，实例状态目录可读写。插件属于受信任的本机代码，并非安全沙箱。状态目录不与其他实例共用，也不放入公开网站目录。

安装到新目录

先完整解压运行包。以下安装目标必须不存在，父目录须已存在；安装器核对 PLATFORM 和 SHA256SUMS，只复制清单中的程序文件，不启动服务。

Linux / macOS，在解压目录执行：

./install.sh "$HOME/neomega-runtime"
cd "$HOME/neomega-runtime"

Windows，在解压目录的 PowerShell 执行：

.\install.ps1 -Target "$HOME\neomega-runtime"
Set-Location "$HOME\neomega-runtime"

摘要不匹配或缺文件时，重新取得完整的同版本运行包。保留原压缩包和版本清单。

以下命令都在安装后的运行包目录执行。示例使用默认管理地址 http://127.0.0.1:18793 和令牌文件 state/token，它们只适用于当前机器的这个实例。

如果启动时修改过端口或数据目录，每条管理命令都要相应替换 --url 和 --token-file。管理工具只接受回环 HTTP 地址，不要把公网域名或实例发现服务的端口填进去。

1. 先做离线检查

Linux / macOS，使用 Python 插件：

export NEOMEGA_RUNTIME_PYTHON="$(command -v python3)"
./start.sh offline

Windows 使用 Python 插件时，显式指定已安装 CPython 的绝对路径，例如：

.\start.ps1 -Mode offline -PythonExe 'C:\Python312\python.exe'

不支持 Windows Store 执行别名。Linux / macOS 必须用 NEOMEGA_RUNTIME_PYTHON 显式指定解释器绝对路径，启动脚本不会自动选择 Python。后续管理命令的 python3 在 Windows 应替换为自己的 CPython，例如 & 'C:\Python312\python.exe'。

只运行 Go 插件时，不设置 Python 或 SDK 环境变量，显式启用插件管理：

unset NEOMEGA_RUNTIME_PYTHON NEOMEGA_RUNTIME_SDK
export NEOMEGA_RUNTIME_ADMIN=1
./start.sh offline

Windows PowerShell：

$env:NEOMEGA_RUNTIME_PYTHON = $null
$env:NEOMEGA_RUNTIME_SDK = $null
$env:NEOMEGA_RUNTIME_ADMIN = '1'
.\start.ps1 -Mode offline

Python CLI 是可选管理客户端；使用它仍须安装 Python 3.10+，不会因此要求 Go Worker 使用 Python。

保持这个终端运行，在第二个终端进入同一目录：

python3 runtime-admin.py --url http://127.0.0.1:18793 --token-file state/token status

离线模式下 in_game=false 是正常结果。依赖聊天或玩家事件的插件在此模式下无法启动；离线检查通过不代表已经连接服务器。

2. 配置游戏连接

在离线宿主终端按 Ctrl+C，等待进程正常退出。根据你使用的认证服务，在私有启动环境中填写：

环境变量	内容
NEOMEGA_AUTH_SERVER	你使用的认证服务地址
NEOMEGA_USER_TOKEN	该服务要求的用户令牌
NEOMEGA_SERVER	目标服务器号码
NEOMEGA_SERVER_PASSWORD	服务器进入密码；仅在需要时设置

认证服务使用用户名和密码时，可用 NEOMEGA_USER_NAME 与 NEOMEGA_USER_PASSWORD 替代用户令牌。不要把真实值写进插件代码、公开脚本或问题反馈。

确认同一服务器没有需要保留的机器人实例，再启动：

./start.sh live

Windows 使用 .\start.ps1 -Mode live；Python 插件继续传入同一个 -PythonExe。PowerShell 设置启动变量使用 $env:变量名 = '值'，Linux / macOS 使用 export 变量名='值'。

如果提示已有实例或租约冲突，先确认正在运行的实例，不删除租约文件来强行启动第二个进程。

3. 检查连接

在第二个终端执行：

python3 runtime-admin.py --url http://127.0.0.1:18793 --token-file state/token status

检查 in_game=true，并在游戏内确认机器人身份与目标服务器一致。ready=true 只说明宿主管理状态就绪，不能单独证明已进服。

默认登录不会自动调整创造模式或飞行。需要这些准备动作时，先确认符合你的服务器用途，再在启动前设置 NEOMEGA_PREPARE_BOT=true。只观察时设置 NEOMEGA_READ_ONLY=true，不要同时启用这两个选项。

4. 安装第一个插件

按管理插件完成安装、配置、授权、检查和启动。首次使用时先手动启动，确认功能后再设置随宿主自动启动。

数据与日常维护

默认 state/ 保存令牌、安装状态和插件数据。更新宿主或迁移机器前，正常停止进程并备份数据；不要让两个进程使用同一数据目录，也不要直接复制正在写入的数据库。

插件的 stop 只停止当前运行；disable 会停止插件并关闭其自动启动。维护时也可在宿主启动前设置 NEOMEGA_RUNTIME_AUTOSTART=0，检查完成后再逐个启动插件。

目录与凭据

start.sh / start.ps1 默认将 NEOMEGA_AGENT_STATE_DIR 设为当前运行包的 state/，并使用该包的 sdk/python。需要把数据放在独立目录时，在首次启动前设置 NEOMEGA_AGENT_STATE_DIR 为该实例的绝对路径，并在后续启动环境中保留同一值。

内容	默认位置与维护边界
管理令牌	state/token；可由 NEOMEGA_AGENT_TOKEN_FILE 指定。只提供给本实例管理工具，不打印内容；令牌文件保持仅运行账户可读写
离线状态	state/runtime-offline.db 与 state/plugins-offline/，和 live 状态分开
游戏连接状态	state/runtime-live/ 下按服务器区分数据库和插件目录；插件目录内 data/<安装名>/ 包含配置、密钥与业务文件
实例登记与租约	默认 state/instances/，可由 NEOMEGA_AGENT_INSTANCE_DIR 指定；不是可随意删除的缓存
额外私有材料	独立的启动环境、外置令牌、导出目录及插件明确使用的外部存储须分别记录与备份，不能假定都在 state/ 内

数据库、插件数据、备份目录只允许受信任的运行账户访问。不要直接复制正在写入的 SQLite，也不要只复制 .db 而遗漏同批 WAL 等相关文件。备份可能含凭据，不能加入插件包、下载目录或普通问题反馈。

升级已有 Host

先确认目标包满足插件的 Host API、Worker 协议与 SDK 要求。升级需要维护窗口：停止新业务、正常退出 Host，并暂停会自动拉起进程的服务管理器；保留旧包、启动参数与当前完整状态。

在旧安装目录执行。PROFILE 是备份与恢复中的维护配置；归档文件与新程序目录都必须尚不存在：

./upgrade.sh /private/host-profile.json /private/host-before-upgrade.tar.gz /path/to/new-package /path/to/new-install

Windows：

.\upgrade.ps1 -Profile 'C:\Private\host-profile.json' -BackupArchive 'C:\Private\host-before-upgrade.tar.gz' -NewPackage 'C:\Packages\new-package' -Target 'C:\Apps\new-install'

脚本先用维护工具备份，再调用新包安装器。它不会覆盖旧程序或旧状态，不自动迁移、恢复或启动服务。备份失败时不安装新包。接下来使用新包维护工具恢复到全新状态目录，按备份与恢复完成恢复围栏与逐安装对账，再显式启动所需插件。

旧二进制不保证能够打开新版数据库。回退应使用相容的旧运行包及配套备份，恢复到新目录，保留升级后的状态用于对账。不要直接换旧可执行文件试开现有数据库。

完整备份回退不会撤销已发送的游戏操作。保留原 operation / commit ID、回执和幂等键；unknown 不等于失败，不能换 ID 重试。单插件备份与插件恢复只覆盖该安装，不能替代整个 Host 或本地服务器备份。