---
title: 应用更新交付说明
doc_type: operations-runbook
domain: runtime
keywords:
  - 应用更新
  - 本地发包
  - 手动交付
  - 桌面分发
summary: 说明当前桌面端只保留本地 macOS 安装包和 Windows 自助构建包时的正式交付口径。
when_to_read:
  - 你准备把桌面端分享给朋友试用
  - 你要发布新版本并确认现在保留哪条交付链路
  - 你想确认 GitHub Actions 自动发版是否仍是正式能力
read_next:
  - ./README.md
  - ../overview/architecture.md
---
# 应用更新交付说明

这篇文档说明当前桌面端“交付与升级”能力的正式口径。

它解决 3 个问题：

- 朋友拿到安装包后，后续怎么升级
- 你每次发新版本时，最少需要准备什么
- 当前哪些远程发布能力已经不再保留

如果你想看系统分层里 updater 放在哪一层，再读 [项目架构](../overview/architecture.md)。如果你想先从运维文档入口找其他 runbook，回到 [运维与验证入口](./README.md)。

## 当前正式交付口径

当前仓库只保留 2 条正式交付能力：

1. 在本机生成 macOS 安装包
2. 为 Windows 用户提供自助构建包，让对方在自己的 Windows 机器上本地打包

一句话：

`当前正式能力是“本地 macOS 发包 + Windows 自助构建包”，不是远程自动多平台发版。`

## 当前分发前提

当前桌面端正式分发要求安装包内自带 `aktools` sidecar。

这意味着：

- 给朋友的正式安装包不能再依赖开发机里的 `.venv-aktools`
- 发布构建必须先产出当前平台对应的独立 sidecar 可执行文件
- sidecar 产物由 `npm run build:aktools-sidecar` 准备；执行 `npm run build` 或 `tauri build` 时会自动走这一步

一句话：

`开发环境可以继续使用本地 Python wrapper，正式分发必须使用随安装包交付的独立 sidecar。`

## 本机 macOS 发包

如果你要在本机直接打出 macOS 安装包，执行：

```bash
npm run build:local-release
```

如果你要打带签名的本地 macOS 包，当前脚本会读取：

- 私钥文件：`.local/tauri-updater/updater.key`
- 私钥密码：`.local/tauri-updater/password.txt`

这两个文件都属于本地敏感材料，不提交到仓库。

## Windows 自助构建包

如果你要交付 Windows 版本，当前正式口径不是“由你本机直接产出 Windows 安装包”，而是把当前仓库做成自助构建包交给 Windows 用户。

统一归集入口：

```bash
node scripts/assemble_release_bundle.mjs --mode local-release
```

这条命令会把：

- 当前宿主机的 macOS 产物
- 同版本 Windows 自助构建包

统一收口到：

- `.build/release-bundles/v<version>/`

Windows 用户后续按 [Windows 自助打包说明](./windows-self-build-for-testers.md) 执行仓库内 PowerShell 脚本。

## 本机测试发包

如果你只是要生成给朋友试用的安装包，不走正式 updater，执行：

```bash
npm run build:test
```

这条命令会使用：

- [tauri.test.conf.json](/Users/winkd/my-projects/ai-stock-assistant-project/ai-stock-assistant-desktop-tauri/src-tauri/tauri.test.conf.json)

它会关闭：

- `bundle.createUpdaterArtifacts`
- `plugins.updater.active`

这样做的目的有两个：

1. 不再要求 `TAURI_SIGNING_PRIVATE_KEY`
2. 避免测试安装包在启动时因为 updater 配置校验失败而直接崩溃

## 用户升级方式

给试用用户的推荐口径：

1. 维护者把新的 macOS 安装包或 Windows 自助构建包发给用户
2. macOS 用户直接下载新的 `dmg` 并覆盖安装
3. Windows 用户下载新的自助构建包，在本地重新执行打包脚本
4. 重新打开应用，原本的本地数据目录继续复用

## 发布者最少要做什么

每次发布新版本，至少保证这 4 件事：

1. 桌面端版本号递增
2. 本机生成 macOS 安装包
3. 生成同版本 Windows 自助构建包
4. 运行一次 `npm run verify:logic`

如果这些事没完成，这次版本就不算完整交付。

## 当前不再保留的链路

下面这些链路不再作为当前仓库的正式交付方式：

- GitHub Actions 自动构建并发布多平台安装包
- 基于 GitHub Releases 的自动发版链路
- 仓库内置的 release-server 上传链路
- 要求维护者长期维护 `latest.json` 的远程 updater 分发闭环

这意味着：

- 当前 tag 推送不再承担自动发布职责
- 当前仓库默认不要求维护发布服务器 secrets
- 正式交付口径回到“本地产物 + 人工分发”

## 发布前最小验收

在把安装包发给朋友前，至少补这 3 个检查：

1. 在干净机器上安装后无需额外安装 Python
2. 首次启动时 `aktools` sidecar 可以由桌面端自动拉起
3. 行情相关页面和任务能在默认配置下完成最小闭环

## 当前明确不支持什么

这 3 件事当前不属于正式能力：

- 自动远程发版
- 自动维护多平台安装包仓库
- 下载完成后自动退出并安装
- 后台静默自动更新
- 下载完成后自动替换当前安装

如果后续要升级到真正的应用内自动更新，需要再补：

- Rust 侧真实安装逻辑
- 前端下载/安装状态推进
- 对应平台的签名与分发闭环
