| name | deployer |
| description | 处理 upgrading/deployer 下的 Zongsoft.Upgrading.Deployer Native AOT 可执行程序。用于修改或审查 .deployment 描述文件处理、完整/增量文件部署、清理/复制规则、部署执行器事件、服务/Web/终端重启启动器、平台相关发布脚本、Visual Studio 发布配置，或 Zongsoft 自动升级 deployer 文档。 |
Zongsoft Upgrading Deployer
入手位置
修改行为前，优先读取最小且有用的文件集合：
README.md：了解公开行为、参数、重启策略和发布说明。Program.cs：进程入口行为和 key=value 参数解析。Deployer.Deploy.cs：部署顺序和描述文件生命周期。Deployer.Helper.cs：清理、保留和复制行为。Launcher.cs、Launcher.*.cs：重启选择和平台相关启动行为。ILauncher.cs：修改启动器契约时读取。Executor.Initializer.cs：内置执行器命令注册。Zongsoft.Upgrading.Deployer.csproj：Native AOT、目标框架、链接的 .shared 文件和打包设置。publish.linux-x64.*、build.cake、Properties/PublishProfiles/*.pubxml：修改发布自动化或 AOT 单文件制作时读取。../../framework.linux-x64.yaml 和 ../../framework-start.cmd：制作 Linux x64 AOT 单文件或调整容器发布流程时读取；从 upgrading 目录视角对应 ../framework.linux-x64.yaml 和 ../framework-start.cmd。../.shared/*.cs：触碰部署描述文件、manifest/release 模型、执行器契约或共享命令时读取。
核心契约
除非任务明确要改变部署语义，否则保留以下顺序：
- 将
key=value 命令行参数解析为 Deployer.Argument。
- 等待
app.id 对应进程退出；如果缺失或为零则跳过。
- 以独占方式打开
.deployment 描述文件。
- 加载描述文件引用的 manifest。
- 对
Fully 发布，清理应用根目录，同时保留 deployer 目录和部署描述文件。
- 执行
Deploying 执行器。
- 将
Packages 中已解压的包文件复制到应用根目录。
- 执行
Deployed 执行器。
- 释放描述文件锁，并通过
app.type 选择的启动器重启宿主。
将 .deployment 视为 upgrader 向 deployer 交接的边界。它包含 Manifest 和 Packages，部署期间会被独占打开，并由部署描述文件生命周期删除。
跨项目契约
保持 deployer 兼容 Zongsoft.Upgrading.Upgrader 写入的 .deployment 文件，以及 Zongsoft.Tools.Upgrader 创建或 Zongsoft.Upgrading.Web 导入的 manifest。
修改 ../.shared/Deployer*.cs、Manifest、Release、Executor、命令实现、ReleaseKind、Platform 或 Architecture 可能影响 upgrader、tool 和 web 包管理器。共享契约变化时检查这些项目。
实现规则
保持 deployer 适合作为进程外升级部署程序：
- 避免引入不利于 Native AOT、trimming 或独立发布的依赖。
- 新增 API 时考虑
PublishAot、IsAotCompatible、StaticExecutable 和 InvariantGlobalization 假设。
- 完整发布时不要覆盖或清理
.deployer 目录。
- 保留严格的描述文件锁；它用于避免宿主和 deployer 竞争。
- 保持执行器名称与共享命令名一致：
Copy、Move、Link、Delete。
- 只在文档化的
Deploying 和 Deployed 阶段执行 manifest 执行器。
- 保持启动器行为感知平台：Windows Web 回收 IIS 应用池，Linux 或 FreeBSD 服务使用
systemctl start，Windows daemon 服务使用 sc start，terminal 或 universal 宿主使用直接进程启动。
- 将服务重启命令视为运维敏感操作；除非用户明确要求，否则不要在测试中运行它们。
- Windows terminal 验证时，部署后确认
.deployer\Zongsoft.Upgrading.Deployer.exe 仍存在；宿主 clean/deploy 可能清掉手工部署的 .deployer，可复用 bin/Release/net10.0/win-x64/publish 下已验证的 Native AOT 单文件产物。
- 验证 deployer 成功时，同时检查
.deployment 最终被清理、.version 更新为目标应用版本，以及 deployer 日志中出现 Terminal launcher 启动新宿主进程的记录。
AOT 单文件发布
deployer 的发布产物应保持为自包含、单文件、Native AOT 可执行程序。修改发布文档、脚本或配置时，保持 README.md、README.zh-Hans.md、publish.linux-x64.*、Visual Studio 发布配置和 Zongsoft.Upgrading.Deployer.csproj 的发布属性一致。
Native AOT 编译发布耗时较久，Linux x64 AOT 发布通常更慢。执行发布前先确认确实需要重新发布，预留足够时间，记录开始/结束时间和输出目录；在 .ai 工作流验证中，如果没有修改 deployer 相关代码、项目发布属性、发布脚本或目标 runtime，不需要重新编译和发布 AOT 程序，直接复用已验证的发布产物。
Windows x64 发布命令应保持包含这些关键属性：
dotnet publish "Zongsoft.Upgrading.Deployer.csproj" ^
-c Release ^
-f net10.0 ^
-r win-x64 ^
--self-contained true ^
-p:PublishSingleFile=true ^
-p:PublishReadyToRun=true ^
-p:PublishAot=true
Linux x64 AOT 单文件制作需要先启动 Podman 容器。优先参考 README.md 的 Publishing/Linux 章节，并保留以下流程：
- 从仓库根目录或
upgrading 工作目录启动 ../../framework-start.cmd 或 ../framework-start.cmd，它使用 framework.linux-x64.yaml 启动 zongsoft-framework 容器。
- 确认容器已完成加载：
podman ps -a --pod
podman logs zongsoft-framework
- 进入容器内发布：
podman exec --workdir /Zongsoft/framework/upgrading/deployer -it zongsoft-framework sh
./publish.linux-x64.sh
- 或者在容器运行期间，从宿主执行
publish.linux-x64.ps1 或 publish.linux-x64.cmd。
- 发布完成后按 README 指引停止容器。
不要把 Linux AOT 单文件发布简化为普通宿主机 dotnet publish，除非任务明确要求改变构建环境；该流程依赖 Linux Alpine/.NET SDK 容器环境。
常见任务
修改清理或复制行为时，验证 Fully 和 Delta 两种模式，并保留包目录遍历语义。
修改重启行为时，更新匹配的 launcher 文件，并确认 Launcher.Launch 仍按 app.type 的 Web、Daemon、Terminal 和 fallback 选择。
修改命令行参数时，更新 README.md，并保持兼容 upgrader 生成的参数：
app.id=12345
app.name=Zongsoft.Hosting.Terminal
app.type=Terminal
app.path=/opt/zongsoft/terminal
host.path=/opt/zongsoft/terminal/Zongsoft.Hosting.Terminal
host.args#0=...
deployment=/opt/zongsoft/terminal/.deployment
修改发布命令或发布配置时，让 Visual Studio、PowerShell、CMD、shell 脚本、Podman 容器流程和 README 示例在相同 runtime/framework 下保持一致。
文档
行为变化时同步更新文档：
- 更新
README.md 和 README.zh-Hans.md，说明公开参数、部署、重启或发布变化。
- 修改项目发布属性时，同步更新发布脚本/配置。
- 服务权限等运维要求只写入文档，不作为测试副作用。
验证
优先执行聚焦验证：
dotnet build Zongsoft.Upgrading.Deployer.slnx
发布相关变化时，在目标环境中检查或运行相关发布命令/脚本。Native AOT 敏感变化时，在可行情况下对目标 runtime 执行一次代表性的 dotnet publish；该步骤可能耗时较久，尤其 Linux AOT 发布，验证计划中要预留等待时间并记录耗时。
除非用户明确要求集成测试，否则不要真实重启服务或修改线上应用目录。验证部署行为时使用临时应用目录和描述文件。
