项目更新
要点
- 版本一律向 Mirror 酱查询(只查版本、不带 CDK);下载源按托管
Update.Source分 Mirror 酱 / GitHub。没有mirrorchyan_rid的项目无法检查更新。 - 一个组只更新一次:谱系锁内先同步到组 → 发现 → 下载一次 → 在暂存目录用当前载荷 + 更新包建新载荷 → 预检一次 → 登记 → 切触发托管 → 同组空闲托管立即切,运行中的跑完再切。
- 视图与旧载荷全程不动:失败、预检不过、取消都只是丢掉暂存目录,没有回滚,也没有中断恢复。
- 下载源、CDK、渠道、时机只看托管级
Update.*;唯一带全局兜底的是代理;GitHub 加速镜像只有全局一项。 - GitHub 源按 HTTP Range 区间差量,结果与整包逐字节一致;任何一步失败都在同一次更新里退回整包。
更新触发路径
| 路径 | 时机 | 特点 |
|---|---|---|
| 运行前(MFW 新建托管默认) | 运行前检查之后、账号任务之前 | 进度写进任务日志(下载每 5%、套包每 25% 一行);停止按阶段取消(#943) |
| 手动(托管页「检查更新 / 更新」) | /api/scripts/maafw/update | 托管运行中拒绝;整段持有本视图的预约,切换后在预约内确认一次运行环境再放手;手动更新等于强制重试(忽略预检备忘) |
旧配置中的 AfterRun 兼容为运行前更新,界面不再提供运行后更新选项。收尾只可能同步到同组其他托管已准备好的版本,并在报告发出后补环境确认,不启动新一轮下载。更新和环境准备耗时不计入账号任务时限。
手动更新为什么要在后端接运行环境确认:编辑页已准备过环境的话,前端随后那次准备请求会被短路,交给前端就等于没人确认。
编排
由 MaaFW/tools/embedded/view_update.py 的 run_view_update 完成,自动与手动更新共用。
| 步骤 | 设计 |
|---|---|
| 同步到组 | 谱系锁内先把触发托管切到组的最新版,再照常联网发现(当前版本取组版本) |
| 发现 | 查版本不带 CDK——带 CDK 会换下载地址、扣 Mirror 酱当日额度;预检备忘的闸门在「确认有新版本」之后、带 CDK 二次查询之前 |
| 下载一次 | project_update/transport.py 的 download_resumable:取消令牌、镜像、按触发托管解析的代理、进度全部透传;断点续传;下载缓存按来源 + 版本 + 文件名命中 |
| 建新载荷 | 在暂存目录从当前载荷克隆再套用更新包(payloads.build_from_package);逐条目解压可取消、有进度,安全检查在写盘前做完(#1106) |
| 预检 | 在暂存目录上真建运行环境,再把大文件并入共用库,见下文 |
| 登记 | payloads.register:写清单、换入、更新该渠道的最新版(只前进) |
| 切换与传播 | 切触发托管;同组空闲托管立即切并在后台确认运行环境;运行中的托管在它自己的下一次运行前检查或正常收尾时兑现 |
- 传播结果只写进触发托管的任务日志;被带着切换的托管在视图标记里留下「由谁、何时切换」,下次运行前打一行日志后清掉——它没有自己的任务上下文,发不了通知。
- 下载完成之后、登记之前取消 = 丢弃暂存目录;登记之后不再响应取消(切换只要约 2 秒)。
下载源、凭据与代理
| 设计 | 为什么 |
|---|---|
下载源、CDK、渠道、时机只看托管级 Update.*,不用全局兜底(update_credentials.py);全局的 CDK 与渠道服务的是 MAS 自身更新 | 各项目各管各的 |
| 编辑页加载时托管级 CDK 为空就预填全局 CDK 并保存(前端行为),后端仍只看托管级(#843) | 方便填写,不改后端口径 |
更新检查从不验证 CDK;编辑页 CDK 输入框下的剩余天数 / CDK 状态走单独的 /api/scripts/maafw/mirror-cdk(updater.query_mirrorchyan_cdk_status):先不带 CDK 查到最新版本,再带 CDK、把 current_version 写成这个最新版本查一次(#1330) | 已是最新时服务端不签发下载地址、不扣当日额度,但照样校验 CDK;第二次的 current_version 不能改回项目版本。CDK 只放在请求体里,日志只记有没有 |
代理 Update.ProxyAddress 留空跟随全局、填了只走自己的,同时管更新下载与运行环境安装;日志只说「脚本级 / 全局 / 未配置」(原文),不打印地址(#943) | 地址里可能带用户名与密码 |
| 渠道只有稳定版 / 测试版;Mirror 酱的 alpha 渠道故意不开放 | — |
GitHub 加速镜像只有全局 Update.GitHubMirror(自动 / 关闭),清单与前端镜像服务同源;只对 GitHub Release 下载生效;没有 sha256 摘要时不走镜像;镜像回错误页在动断点之前就判不可用(#945) | Mirror 酱的签名地址加镜像前缀会失效;第三方转发的字节必须能校验 |
| 直连失败重试 5 次、退避 1/3/9/27 秒;没有整体超时,只有每次读取 30 秒超时 | 慢但还在传的下载不该被砍 |
全量与差量
| 设计 | 为什么 |
|---|---|
| 只有「由更新得来」的载荷才要差量包(清单逐文件记着包内哈希、载荷不可变);本地导入的、旧投影规则建的、被标为损坏的、还留着旧布局原生库的,一律全量 | 差量基线必须可信 |
落盘条目只从 apply.build_package_plan 枚举(按投影白名单过滤);唯一旁路是区间差量,改枚举口径要同步 range_delta._check_layout | 「哪些文件落盘」只改一处 |
全量包清掉的旧文件 = 上一个包带来、新包没有的 ∪ 导入带来、位于新 interface 资源目录内、新包没有的 ∪ 被新包淘汰的外壳原生库位置 ∪ 新包整体接管的目录(原生库目录、MaaAgentBinary/、项目自带解释器目录)里新包没有的(#659、#1144、#1157) | 不清会新旧版本混装;用户在资源目录之外放的东西(例如写在 preset/ 的预设)一直保留 |
| 与资源目录、agent 代码目录相等、包含或落在其内的目录不算接管目录 | agent 解释器可能就放在 agent/ 下 |
| 代价:导入时用户手动装进自带解释器的包,第一次全量更新就会被删,MAS 不负责重装 | 与全新安装新版本结果相同 |
| 项目热更新改过的受管文件:以新版本为准,旧内容留档,不拒绝更新(#810) | 有项目每次运行都改写自己的数据文件,原来的 fail-closed 让项目永远停在旧版本 |
GitHub 区间差量
| 设计 | 为什么 |
|---|---|
| 要全量包时(GitHub 源一律如此),先用 HTTP Range 读发行包的中央目录,按 CRC32 与大小和当前载荷比对,只取回变了的条目,其余从当前载荷搬,拼成一个虚拟全量包再按全量语义建新载荷;结果与整包逐字节一致、载荷 id 相同(#1157) | 一次小版本更新通常只需几 MB,而整包上百 MB |
| 不采用下载 tag 源码包的「源码热更新」 | 实测与发行包对不上:换行符不同、原生库停在旧版、interface 要自己拼 |
只直连 github.com、不走镜像 | 区间读取只有条目级 CRC,没有整包摘要可校验 |
| 任何一步失败(服务器不支持 Range、CRC 错、超时、需要取回的超过资产大小 40% 或 3000 个条目……)都丢掉这一批,同一次更新里改下整包(可走镜像) | 先保守 |
有镜像可退时加直连速度保护:按花在网络上的时间估算,超过 120 秒或已用 180 秒就放弃区间(range_delta.RangeSpeedGuard) | 国内直连 GitHub 常常很慢,不如走镜像下整包 |
环境变量 AUTO_MAS_MAAFW_FORCE_FULL_PACKAGE=1 一律下全量包,不进配置、不上界面 | 供比对与应急 |
核心包报 delta,宿主对外统一成 incremental(界面显示「增量」) | 前端只认全量 / 增量两种 |
预检与备忘
| 设计 | 为什么 |
|---|---|
| 提交更新前在新版本的暂存目录上真建运行环境(不是 dry-run),建不出来就放弃新版本、继续跑旧版本(#901) | 曾出现「更新成功、环境建不出来、之后每次运行必挂」 |
| 预检用独立的隔离 venv 根,结果不写环境缓存;永远不对载荷目录跑准备 | 准备过程会重建唯一那份 agent venv |
预检同时做 agent 导入静态检查:用项目自己的解释器以 ast 解析 agent 启动时必然执行的导入,确认项目自己的模块是否存在;不执行任何项目代码;第三方包、条件导入只提示——宁可漏报不误拒(agent_env/import_check.py,#1117) | 新版本缺 agent 模块时原来只有运行时才发现 |
预检备忘按谱系 + 目标版本记,组共有:一个托管预检某版本失败,组里谁也不再为它自动下包(project_update/precheck_memo.py) | 不重复白下 |
| 因 PyPI 缺 binding 版本而失败的,每次运行前轻量探测一次,可得了就正常更新;其他原因的失败不探测;手动更新等于强制重试 | — |
投影规则改版与补齐
| 设计 | 为什么 |
|---|---|
投影规则改动会让已登记的载荷缺文件时,规则版本 PROJECTION_REVISION 加一,并保留上一版规则的复刻(projection_legacy.py) | 已装好的项目不会自己恢复(同版本不重建) |
运行前检查与手动检查更新时,按「新规则保留、旧规则剔掉、载荷里没有」比出缺口,依次从导入目录、下载缓存、GitHub 发行包(Range)只取缺的文件,建同版本的超集载荷、登记并整组切换(view_heal.py、projection_heal.py,#1110、#1117) | 自动补回,不需要用户手动打补丁 |
| 每个载荷只查一次;暂时性失败最多 3 次、间隔 6 小时;整次最多 45 秒,超时照常运行 | 不挡运行 |
更新面板
| 设计 | 为什么 |
|---|---|
| 更新区左列「当前版本」「GitHub」两格,右侧「更新过程」面板;「检查更新 / 更新」按钮在面板标题行右侧(#843、#943) | — |
| 结论就是日志最后一行,整行一个强调色;不加状态词、不加进度条、不另弹提示 | 一个地方看结论 |
| 「检查更新」与「更新」互斥 | 更新中再检查会冲掉面板 |
| 自动更新下拉的「不更新」只表示这个托管自己不联网查;组推进时它照样跟着切换(文案保持不变) | 没有钉住;保持与既有界面一致 |
| 各阶段(解压、比对、复制、套用、预检、入库、清单)都写开始与结束日志,收尾一行总用时(#1106) | 长时间静默会被当成卡死 |
| 忙碌原因分「项目正在更新」「脚本正在运行」「项目正被占用」(提示原文) | — |
限制
- 没有
mirrorchyan_rid的项目无法检查更新,只能手动解压新版本后新建托管导入。 - 手动更新目前不能中途停止,离开页面后也看不到进度。