| name | upgrader |
| description | 处理 upgrading/upgrader 下的 Zongsoft.Upgrading.Upgrader 客户端组件。用于修改或审查自动升级发现、File/Web fetcher、发布选择、包下载与校验和验证、解压、.deployment 交接生成、worker 启动调度、deployer 启动行为、upgrader plugin/option/deploy 产物、执行器注册，或 Zongsoft 自动升级 upgrader 文档。 |
Zongsoft Upgrading Upgrader
入手位置
修改行为前，优先读取最小且有用的文件集合：
README.md：了解公开升级工作流、配置、通道和部署交接。Upgrader.cs：UpgradeAsync、worker 调度、并发保护、部署描述文件创建和关闭流程。Fetcher.cs、Fetcher.File.cs、Fetcher.Web.cs：发布发现、URL 构造、硬件指纹参数和选择逻辑。Downloader.cs、Downloader.File.cs、Downloader.Web.cs：包获取、本地复用、大小检查和校验和行为。Extractor.cs：将包解压到临时 .app 目录。Upgrader.Launcher.cs：deployer 进程启动细节和平台处理。Executor.Initializer.cs：内置执行器命令注册。Zongsoft.Upgrading.Upgrader.option、.plugin、.deploy：默认配置、启动注册和包产物。Zongsoft.Upgrading.Upgrader.csproj：链接的 .shared 文件、包产物和文档生成设置。../.shared/*.cs：触碰发布、manifest、部署描述文件、执行器、平台、架构或工具契约时读取。
核心契约
保留以下客户端流程：
- 如果部署描述文件已存在，则报告升级准备成功。
- 从配置的
File 或 Web 通道获取候选发布。
- 按应用名称、版本分支、平台、架构、当前版本、可选目标版本和废弃状态过滤发布。
- 如果存在完整发布，选择最新的完整发布作为主干，然后按版本升序追加更新的增量发布。
- 将每个选中的包下载到应用专用临时目录。
- 当发布元数据提供大小和校验和时，验证包大小和校验和。
- 将包解压到临时
.app 目录。
- 在应用目录中保存
.deployment 描述文件。
- 从
{ApplicationPath}/.deployer 启动 Zongsoft.Upgrading.Deployer，然后关闭宿主。
跨项目契约
保持 upgrader 兼容：
Zongsoft.Tools.Upgrader 生成的 manifest；Zongsoft.Upgrading.Web 返回的发现和下载响应；Zongsoft.Upgrading.Deployer 消费的 .deployment 文件；../.shared/commands 下实现的共享执行器命令。
修改 Manifest、Release、ReleaseKind、Deployer、Executor、Platform、Architecture、reader/writer 代码、checksum 辅助逻辑或 runtime 命名时，通常需要检查 tool、web 包管理器和 deployer。
通道说明
修改 File 通道时，保持 manifest 发现顺序兼容文档：
{root}/{application-name}/*.manifest
{root}/{application-type}/{application-name}/*.manifest
{root}/{application-type}/{application-name}*.manifest
{root}/{application-name}*.manifest
修改 Web 通道时，保持请求兼容 Web 包管理器端点：
{base-url}/{application-name}/{edition}?Name=...&Edition=...&Platform=...&Architecture=...&CurrentlyVersion=...
保留或扩展请求构造时包含硬件指纹参数；服务端评估器可能依赖这些字段。
实现规则
- 保持
File 和 Web 通道名称大小写不敏感，并兼容 /Upgrading 下的连接设置名称。
- 发布匹配必须严于包可用性：下载前先匹配应用身份和 runtime。
- 保持完整发布加增量发布链有序且确定。
- 在解压和部署交接前完成校验和验证。
- 只有当大小和校验和仍然匹配时，才能复用已下载的本地包文件。
- 保持
.deployment 创建为 deployer 继续执行的唯一信号。
- 保持 Linux deployer 启动足够脱离当前进程，使其能在宿主关闭后继续运行。
- 保留 interlocked 升级标志，避免并发 worker tick 阻塞或重入。
- 保持 plugin/option/deploy 产物与 NuGet 包布局一致。
- 发布名称必须匹配运行时
Application.ApplicationName。验证宿主升级时，先读部署目录 .version、启动代码或 upgrader/deployer 日志中的 app.name，不要只依赖打包脚本中的历史默认名称。
- 全量部署可能清理应用根目录下的
logs/，导致 upgrader 发现、下载、解压和启动 deployer 的成功日志在部署后消失；集成验证需要在观察循环中把 upgrader 日志快照复制到外部 .artifacts。
常见任务
修改发布选择时，测试只有增量发布、一个完整发布、多个完整发布，以及指定 UpgradingVersion 的组合。
修改下载行为时，验证本地文件复用、缺失文件下载、校验和不匹配和大小不匹配路径。
修改部署交接时，同时更新 upgrader 文档和 deployer 参数预期。
修改启动调度时，保留取消处理并避免并发运行多个升级准备流程。
文档
行为变化时同步更新文档：
- 更新
README.md 和 README.zh-Hans.md，说明公开工作流、配置、通道或交接变化。
- 包安装行为变化时，更新 option/plugin/deploy 产物。
- 如果请求形状、查询名称或硬件评估器输入变化，同步更新 Web 文档。
验证
优先执行聚焦验证：
dotnet build Zongsoft.Upgrading.Upgrader.slnx
行为变化时，如果周边解决方案有可用测试，添加或运行发布过滤、下载器校验路径、包解压、worker 调度和部署描述文件生成相关测试。Web 通道变化时，在本地包管理器可用的情况下验证文档化的 /Upgrading/Upgrader 端点。
