客户端更新与远程升级
更新过程
管理员在「客户端」点击版本号,检查 GitHub 正式 Release,再下发升级。 新版面板保留升级窗口,依次显示接收、检查、下载、校验、安装、重启与上线确认。 已下发不等于升级完成:只有目标版本的控制连接和数据通道都重新就绪,且新版 客户端回传的任务编号匹配,才显示升级完成。超过 15 分钟仍未确认时显示 「未确认完成」,不会把超时当作成功。
更新包由 NPC 自己下载,不由 NPS 转发。NPC 需要能够访问 GitHub API、Release 下载站点及其重定向地址;命令行设置的出站代理、源 IP 和 ALL_PROXY 同样用于 远程下载。正式包必须通过 checksums.txt 中的 SHA-256 校验和 -version 可运行性检查。下载期间原连接保持运行,只在切换程序时短暂中断。
| 运行方式 | 切换行为 |
|---|---|
| Linux / macOS / FreeBSD 命令行或系统服务 | 原子替换实际运行路径,用 exec 保留进程 PID、参数、环境和工作目录;菜单直接粘贴的多个连接通过临时恢复文件重建 |
| Windows 系统服务 | 按运行 PID 查找实际 SCM 服务;先准备好更新包,再由独立更新器停止该服务、替换程序并直接启动服务,检查启动结果 |
| Windows 前台命令行 | 独立更新器就绪后原程序退出;更新器替换原路径并恢复启动参数 |
| NPC GUI | 更新器就绪后才退出旧 GUI,切换程序/完整 macOS 应用包;恢复升级前已运行及正在重试的连接,不依赖「记住客户端状态」,不会启动原本停止的项目 |
| Docker | 禁止容器内自替换,拉取镜像并重建容器 |
| Android APK / 未注册更新器的 SDK、嵌入端 | 由安装包或宿主应用更新;新版面板显示不可远程升级及原因 |
新程序无法启动或未在本地初始化确认期限内就绪时,独立更新器尝试回滚并重新 启动旧程序。Unix 的 exec 调用本身失败时恢复原文件并保留旧进程;如果新程序 已经 exec 成功后才崩溃,由系统服务管理器负责拉起,面板仍以实际重新上线为准。 回滚也可能因为磁盘、权限或系统服务故障而失败,必须查看日志,不能把回滚视为 无条件成功。
系统服务与菜单更新
推荐继续使用菜单安装系统服务。菜单 5、npc update 和 npc update-force 会读取已注册服务的真实程序路径,包括旧服务指向桌面或其他自定义目录的情况, 而不是只更新猜测的 /usr/bin/npc 或默认安装目录。
更新前列出相关服务、路径和状态,并询问是否重启原本运行中的服务;输入 y 后更新并重启这些服务,原本停止的服务保持停止。不确认则只更新磁盘文件,旧 进程仍使用旧版本,稍后可用菜单 9 重启。无法可靠识别服务配置时会报错, 不猜测或改写其他程序。自定义 shell 包装器等非标准服务配置需手动维护。
新菜单本身已经是最新版本,也可以修复仍指向旧程序副本的服务;普通更新不 覆盖已经更高的版本。update-force 明确允许强制覆盖为最新正式 Release。 更新后的菜单进程仍是原版本,关闭后重新打开即可使用新版菜单。
多个 VKey 与共享程序文件
- 一台电脑安装多个 VKey 服务继续支持。
- 服务端远程升级只重启本次连接所属的服务,不自动停止其他 VKey 服务。
- 多个服务共用同一程序文件时,文件会一起变新,但未重启的服务进程继续运行 原版本;需要统一升级时,在本机菜单确认重启相关服务。
- 同一 VKey 同时有多个在线实例时,远程升级拒绝下发,避免更新到错误设备。
- 同一安装路径使用系统文件锁串行更新,重复下发或并发替换会被拒绝。
权限、状态与日志
服务端 allow_remote_update=false 可全局关闭;NPC 的 -disable_remote_update=true 或配置文件 disable_remote_update=true 可本地拒绝。更新进程需要写入安装目录、创建相邻回滚备份,以及管理本次服务 的权限。请使用原服务账户/管理员终端,不要通过放宽程序目录到所有人可写来解决。
各平台的权限边界
所有自动更新都沿用当前进程身份,不会静默调用 UAC、sudo、pkexec、修改服务 账户或放宽安装目录。先在原程序目录创建、设置权限并重命名一个独立测试文件, 确认能保持原权限、保存回执后才继续;该探测不改原程序。权限也可能在检查后变化, 因此安装和恢复过程仍逐步检查错误,不能把预检查通过当成无条件更新保证。
| 端或部署方式 | 必要条件与失败行为 |
|---|---|
| Windows 系统服务 | 运行账户需要原程序目录的安全替换权限,以及本次服务的查询配置、查询状态、停止和启动权限。更新助手先核对服务 PID、程序路径和完整恢复权限,再报告就绪;未满足时不停止原服务。SCM 仅申请所需权限,不申请全局完全控制 |
| Windows 前台 CLI / GUI | 沿用当前账户;用户可写目录中的程序不必一律以管理员运行。Program Files、只读属性、受保护所有者或 ACL 无法保留时明确失败,需原安装账户手动维护 |
| Linux / FreeBSD / macOS CLI | 当前账户必须可读原程序、可写实际安装目录,且能保留属主、属组和原权限。root 并不是通用前提,但普通账户不能替换 root 所有的只读安装。Unix exec 保留 PID 与进程身份,不另起 root 进程 |
| Linux 自定义权限 | 保留原 mode、UID/GID、POSIX 访问 ACL 与 SELinux 标签;不能保留则拒绝切换。带 setuid/setgid、文件 capabilities、IMA/EVM 标记的程序不自动迁移这些特权/签名,需管理员手工验证;低端口能力建议由 systemd AmbientCapabilities 管理 |
| macOS GUI | 需要当前账户拥有可更新的 .app,保留应用包外层权限。磁盘映像 /Volumes/、App Translocation、不可写 Applications 目录和其他账户所有的应用包先拒绝更新;不要以 root 启动 GUI 来绕过。新包内部资源权限来自发布包;MDM、自定义 ACL/签名策略安装应走原安装器 |
| systemd 受限服务 | ProtectSystem、只读挂载、ReadOnlyPaths、目录不可写等会阻止自更新;原连接保持,使用部署流程更新,不建议为自更新解除整个服务的沙箱限制 |
| Docker / Android / SDK | 不因容器内 root 或宿主权限高就启用二进制自替换;仍由镜像、APK 或宿主维护 |
Windows 暂存目录、参数与恢复文件使用仅当前运行账户和 SYSTEM 可访问的受保护 ACL;Unix 使用 0700 私有目录与 0600 状态文件。跨账户接管一个更新任务不受支持。 GUI 的 npc_data.json 同样包含连接密钥:旧版 0644 文件在读取时收紧为当前 账户私有权限,新保存使用受保护的原子文件;无权读取或写入时返回错误,不用空 配置覆盖原文件,也不把保存失败当成功。符号链接形式的配置文件需要先手动整理。 /tmp 等暂存位置被设置为 noexec 时,新程序或更新器执行自检会失败,原程序 不会因该失败主动退出;需由运维指定允许执行且受保护的暂存位置,或手动更新。
独立更新器日志写在实际程序(macOS 为 .app)旁的 npc-updater.log。 Unix 直接更新错误也会进入原 NPC 日志。程序旁的 .update-lock 是保留的锁文件, 空文件不代表仍在升级;锁由操作系统随进程/句柄释放。CLI 的 <程序路径>.update-result.json、GUI 配置目录的 update-result.json 保存最近 启动回执;临时连接恢复文件权限为 0600,可能含连接密钥,请勿分享。
NPS 连接日志增加 bridge.update 终态记录,带任务编号、原/目标版本和结果, 前提是已配置连接日志落盘。面板进度保存在 NPS 内存中;NPS 重启后进度任务会 丢失,此时重新检查实际版本和连接日志,不会凭空显示完成。
老版本兼容与首次迁移
Bridge 登录握手和现有转发协议未改变,旧 NPC 仍可连接。更新协议由客户端 能力协商:只有明确上报新版更新能力时才发送带任务编号的消息;支持历史升级 的 NPC(1.1.23 及以上)仍收到原来的 updt,更早版本需要手动升级。 旧端无法提供下载进度或严格的任务回执,只能根据目标版本重新上线做兼容确认。
仅升级 NPS 不能修复已经安装在设备上的旧更新器。如果旧 Windows 服务、 旧 GUI 正在遭遇更新后不启动,请先手动替换为包含本次修复的 NPC/GUI 并启动 一次,之后才能完整使用新版升级流程。生产批量推广前,建议先选择一台 Windows 服务设备和一台 GUI 设备验证网络、权限、自动重连及日志。
