> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/framework/upgrading.md).

# 自动升级

理解升级包、发现通道、应用内升级器与进程外部署器的协作。

自动升级把应用交付拆成包生产、发布发现、下载准备和停机部署。`framework/upgrading` 中的四个组件共享发布协议，但承担不同阶段的责任。

| 组件                            | 运行位置    | 职责                         |
| ----------------------------- | ------- | -------------------------- |
| `Zongsoft.Tools.Upgrader`     | 构建或发布环境 | 制作 ZIP 与 manifest、重算校验和、发布 |
| `Zongsoft.Upgrading.Web`      | 包管理服务器  | 管理发布元数据、包上传和发现筛选           |
| `Zongsoft.Upgrading.Upgrader` | 被升级的应用内 | 检查、下载、校验、解压、生成部署交接         |
| `Zongsoft.Upgrading.Deployer` | 应用外独立进程 | 等待应用退出、复制文件、执行部署命令并重启      |

首次接入建议先阅读本页，再按[升级接入与故障恢复](/framework/upgrading/workflow.md)配置隔离测试应用；制作包的参数见[升级工具](/tools/upgrader.md)。

## 为什么需要独立部署器

运行中的应用可能占用程序集和资源文件，应用退出后又无法继续执行自己的替换代码。因此应用内升级器只负责把包准备好，最后启动独立部署器并退出。

`.deployment` 是双方的交接描述，引用 manifest 和已解压文件目录。它的存在代表有待部署工作，不代表目标版本已经运行。部署器会等待原进程退出，并独占读取描述文件以避免竞争。

## 发布身份

一个发布由应用名、版本分发名、版本号、平台和架构识别。应用名必须匹配实际运行时名称，不要根据项目目录或历史打包脚本猜测。版本分发名可用于区分 `stable`、`community` 等发布系列；它与编译配置 `Debug/Release` 是不同维度。

选择发布时，还会考虑当前版本、可选最高目标版本、废弃状态，以及 Web 端的可见和已发布状态。只有上传了 ZIP，而没有匹配的元数据和发布状态，客户端可能仍然查不到更新。

## 全量与增量

| 类型      | 文件部署方式                         | 需要应用保证的事情              |
| ------- | ------------------------------ | ---------------------- |
| `Fully` | 先清理应用根目录，再复制新文件；保留部署器自身等交接所需内容 | 包含完整运行产物；持久数据必须有独立保存策略 |
| `Delta` | 将包内容覆盖到原目录                     | 需要的旧文件确实存在；删除旧文件要另行设计  |

客户端若选中全量发布，会以最新的匹配全量包为主干，再按版本升序应用更新的增量包；没有全量包时则按顺序应用匹配增量包。增量不是二进制差分算法，也不会自动找出应删除的旧文件。

{% hint style="danger" %}
🚨 全量部署可能删除应用根目录中的数据库、上传文件、日志和本地配置。将持久数据置于受控的独立位置，或在升级前完成可验证的备份与恢复安排。`Deploying` 执行器在清理之后运行，不能依靠它备份已经被清理的文件。
{% endhint %}

## 通道与信任边界

应用端支持 `File` 和 `Web` 通道。`File` 从配置的文件系统 URL 查找清单和包，可使用已经部署的文件系统提供者；`Web` 请求包管理器的发现接口。工具发布支持 `amazon.s3`（别名 `s3`）及 `web`，两端的通道名称不要混淆。

校验和用于检查包与 manifest 所声明内容是否一致，不等于发布者身份认证。应用仍需控制发布权限、存储写入权限及下载通道。manifest 中的执行器会进行文件操作，应当与应用程序一样来自受信任的发布流程。

## 完成条件

一轮升级只有在新进程启动、版本标识符合预期且业务健康检查通过后才算完成。包上传成功、下载成功和 `.deployment` 生成都只是中间阶段。框架当前的文件清理与覆盖流程不提供跨文件的原子切换，也不能据此承诺自动回滚。

源码入口：[升级组件](https://github.com/Zongsoft/framework/tree/main/upgrading)、[共享协议](https://github.com/Zongsoft/framework/tree/main/upgrading/.shared)。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zongsoft.com/framework/upgrading.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.