# 部署指南

<cite>
**本文引用的文件**
- `package.json`
- `angular.json`
- `src-tauri/Cargo.toml`
- `src-tauri/tauri.conf.json`
- `src-tauri/build.rs`
- `scripts/build-mac-store.sh`
- `scripts/upload-release.mjs`
- `upload.config.json`
- `README.md`
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向生产环境部署 GSDJGXApp（基于 Angular 22 + Tauri 2 + Rust 的跨平台桌面应用）。内容涵盖前端产物构建（pnpm build）、后端编译（Cargo）、跨平台打包（pnpm tauri build）、多平台部署策略、应用打包配置、自动更新机制、安全配置、性能优化、部署监控与日志收集、故障排除与应急响应，以及 CI/CD 流水线配置。

## 项目结构
项目采用前后端分离的桌面应用架构：
- 前端：Angular 22 应用，产物输出至 dist/gsdjgxapp/browser
- 后端：Rust + Tauri 2，通过 Cargo 管理依赖与构建
- 打包：Tauri 配置驱动多平台安装包生成
- 自动更新：基于 Tauri Updater 插件与 Cloudflare R2 存储

```mermaid
graph TB
subgraph "前端"
NG["Angular 应用<br/>dist/gsdjgxapp/browser"]
end
subgraph "后端"
RS["Rust 应用<br/>src-tauri/Cargo.toml"]
TAURI["Tauri 运行时<br/>src-tauri/tauri.conf.json"]
end
subgraph "打包与分发"
TAURI_CLI["Tauri CLI<br/>pnpm tauri build"]
R2["Cloudflare R2<br/>最新版本清单 latest.json"]
end
NG --> TAURI
RS --> TAURI
TAURI --> TAURI_CLI
TAURI_CLI --> R2
```

**图表来源**
- `angular.json#L14-L46`
- `src-tauri/Cargo.toml#L26-L65`
- `src-tauri/tauri.conf.json#L6-L11`
- `scripts/upload-release.mjs#L47-L99`

**章节来源**
- `README.md#L1-L118`
- `angular.json#L1-L79`
- `src-tauri/tauri.conf.json#L1-L70`

## 核心组件
- 前端构建：Angular 生产构建，启用输出哈希与体积预算
- 后端编译：Rust 依赖与特性开关，包含数据库、HTTP、日志等插件
- 打包配置：Tauri 配置定义窗口样式、安全策略、打包目标与更新源
- 自动更新：Tauri Updater 插件 + R2 最新版本清单
- 平台脚本：macOS App Store 专用签名与打包脚本

**章节来源**
- `package.json#L1-L90`
- `src-tauri/Cargo.toml#L26-L65`
- `src-tauri/tauri.conf.json#L30-L68`
- `scripts/build-mac-store.sh#L1-L492`

## 架构概览
下图展示生产构建与部署的关键流程：前端构建 → 后端编译 → Tauri 打包 → 产物上传 R2 → 客户端自动更新。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant FE as "前端构建(pnpm build)"
participant BE as "后端编译(Cargo)"
participant PKG as "打包(Tauri)"
participant R2 as "R2 存储"
participant App as "桌面应用"
Dev->>FE : 触发前端构建
FE-->>Dev : 生成 dist/gsdjgxapp/browser
Dev->>BE : 触发后端编译
BE-->>Dev : 生成 Rust 二进制
Dev->>PKG : 执行 pnpm tauri build
PKG-->>Dev : 生成各平台安装包
Dev->>R2 : 上传安装包与签名文件
R2-->>Dev : 生成 latest.json
App->>R2 : 检查更新(基于 endpoint)
R2-->>App : 返回最新版本信息
App->>App : 下载并验证签名
App-->>Dev : 完成升级
```

**图表来源**
- `angular.json#L14-L46`
- `src-tauri/Cargo.toml#L26-L65`
- `src-tauri/tauri.conf.json#L60-L67`
- `scripts/upload-release.mjs#L183-L242`

## 详细组件分析

### 前端构建流程（Angular 生产构建）
- 输出目录：dist/gsdjgxapp
- 生产配置：启用输出哈希、初始包体积预算、关闭源映射
- 开发配置：开启源映射与调试
- Tauri 集成：devUrl 与前端构建产物路径

```mermaid
flowchart TD
Start(["开始"]) --> Build["pnpm build (生产)"]
Build --> Dist["生成 dist/gsdjgxapp"]
Dist --> TauriConf["Tauri 配置 frontendDist 指向 dist/gsdjgxapp/browser"]
TauriConf --> End(["结束"])
```

**图表来源**
- `angular.json#L14-L46`
- `src-tauri/tauri.conf.json#L6-L11`

**章节来源**
- `angular.json#L14-L46`
- `src-tauri/tauri.conf.json#L6-L11`

### 后端编译流程（Rust + Tauri）
- 依赖管理：Cargo.toml 定义 Tauri、数据库、HTTP、日志、SQL 等插件
- 功能特性：启用 macOS 私有 API、devtools；针对非移动端启用 Updater 插件
- 构建入口：build.rs 调用 tauri_build::build()

```mermaid
flowchart TD
Start(["开始"]) --> Cargo["Cargo.toml 依赖解析"]
Cargo --> Features["启用特性: macOS 私有 API / devtools / Updater(非移动端)"]
Features --> BuildRS["build.rs 调用 tauri_build::build()"]
BuildRS --> End(["结束"])
```

**图表来源**
- `src-tauri/Cargo.toml#L26-L65`
- `src-tauri/build.rs#L1-L4`

**章节来源**
- `src-tauri/Cargo.toml#L26-L65`
- `src-tauri/build.rs#L1-L4`

### 跨平台打包配置（Tauri）
- 打包目标：Windows NSIS（可扩展至其他平台）
- 图标资源：icons 目录下的多尺寸 PNG 与 icns/ico
- 安全策略：CSP 设为 null（允许内联脚本/样式）
- 更新配置：启用 Updater 插件，配置 endpoint 与公钥
- 深链接：注册自定义协议 gsdjgxapp

```mermaid
flowchart TD
Config["tauri.conf.json"] --> Targets["targets: nsis"]
Config --> Icons["icon: 多尺寸图标"]
Config --> Security["security.csp: null"]
Config --> Updater["plugins.updater: endpoint + pubkey"]
Config --> DeepLink["plugins.deep-link: gsdjgxapp"]
Config --> Windows["windows: 窗口样式与透明度"]
```

**图表来源**
- `src-tauri/tauri.conf.json#L30-L68`

**章节来源**
- `src-tauri/tauri.conf.json#L30-L68`

### 自动更新机制
- 版本检测：客户端定期访问 endpoint 获取最新版本信息
- 增量更新：官方更新工件（.sig 配对）上传 R2，客户端下载并校验签名
- 回滚策略：应用内可配置对话框与公钥验证，失败时保持当前版本

```mermaid
sequenceDiagram
participant App as "桌面应用"
participant EP as "更新端点"
participant R2 as "R2 存储"
App->>EP : 请求最新版本信息
EP-->>App : 返回 latest.json (版本/签名/URL)
App->>R2 : 下载对应平台工件
R2-->>App : 返回工件与签名
App->>App : 验证签名(pubkey)
App-->>App : 安装并重启
```

**图表来源**
- `src-tauri/tauri.conf.json#L60-L67`
- `scripts/upload-release.mjs#L183-L242`

**章节来源**
- `src-tauri/tauri.conf.json#L60-L67`
- `scripts/upload-release.mjs#L183-L242`

### 多平台部署策略

#### Windows
- 打包目标：NSIS 安装器
- WebView 安装模式：嵌入引导程序
- 安装语言选择器：启用多语言安装界面

**章节来源**
- `src-tauri/tauri.conf.json#L43-L50`

#### macOS
- 通用二进制：支持 Intel + Apple Silicon
- 代码签名：应用与框架分别使用父/子权限清单
- Provisioning Profile：可嵌入并校验 application-identifier
- App Store 提交：Info.plist 分类、Bundle ID 替换、.pkg 打包

**章节来源**
- `scripts/build-mac-store.sh#L323-L325`
- `scripts/build-mac-store.sh#L358-L363`
- `scripts/build-mac-store.sh#L369-L378`
- `scripts/build-mac-store.sh#L423-L431`
- `scripts/build-mac-store.sh#L454-L465`

#### Linux
- 打包目标：AppImage（由 Tauri Updater 产物推断）
- 平台识别：根据文件名后缀区分 x86_64 与 aarch64

**章节来源**
- `scripts/upload-release.mjs#L224-L231`

### 安全配置
- 代码签名：macOS 使用 Apple 分发证书与安装包证书；Windows 未在配置中显式声明签名（建议在 CI 中配置）
- 权限声明：macOS entitlements 由脚本动态生成并注入；Windows 权限在打包配置中未显式声明
- 沙箱配置：CSP 设为 null，允许内联脚本/样式；建议在生产中收紧 CSP
- 深链接：仅注册 gsdjgxapp 协议，避免不必要的 URI 泄露

**章节来源**
- `scripts/build-mac-store.sh#L189-L220`
- `src-tauri/tauri.conf.json#L26-L28`
- `src-tauri/tauri.conf.json#L52-L67`

### 性能优化建议
- 启动时间优化：延迟初始化非关键模块、预加载关键资源、减少主线程阻塞
- 内存使用优化：合理释放大对象、避免内存泄漏、使用 Web Workers 处理重型计算
- 文件大小压缩：启用生产构建输出哈希、移除未使用依赖、拆分代码与懒加载路由
- 网络请求优化：缓存策略、连接复用、压缩传输

**章节来源**
- `angular.json#L29-L43`

### 部署监控与日志收集
- 日志插件：Rust 侧使用 tauri-plugin-log；前端可结合 @tauri-apps/plugin-log
- 收集策略：本地日志文件轮转、远程日志上报（建议在 CI 中配置）
- 监控指标：应用启动耗时、崩溃率、更新成功率、网络请求失败率

**章节来源**
- `src-tauri/Cargo.toml#L58-L58`
- `package.json#L59-L59`

### 故障排除指南
- 构建失败：检查 Node.js、pnpm、Rust 工具链版本；确保 Xcode Command Line Tools 安装
- 签名失败：确认 Apple 证书与 Team ID；校验 entitlements 与 application-identifier
- 更新失败：核对 endpoint 与 pubkey；检查 latest.json 与工件签名配对
- 权限问题：macOS entitlements 仅声明必要权限；Windows 需在 CI 中配置代码签名

**章节来源**
- `README.md#L35-L44`
- `scripts/build-mac-store.sh#L207-L228`
- `src-tauri/tauri.conf.json#L60-L67`

### CI/CD 流水线配置
- 触发条件：版本提交（包含 [version:x.y.z]）自动更新版本
- 关键步骤：安装依赖 → 前端构建 → 后端编译 → Tauri 打包 → 上传 R2 → 生成 latest.json
- 密钥管理：upload.config.json 与环境变量（CI 中通过 secrets 注入）

```mermaid
flowchart TD
Push["推送/PR"] --> Version["检测版本提交标记"]
Version --> Install["安装依赖(pnpm)"]
Install --> FE["前端构建(pnpm build)"]
FE --> BE["后端编译(Cargo)"]
BE --> PKG["Tauri 打包(pnpm tauri build)"]
PKG --> Upload["上传 R2 与签名"]
Upload --> Latest["生成 latest.json"]
Latest --> Done["完成"]
```

**图表来源**
- `README.md#L107-L107`
- `scripts/upload-release.mjs#L15-L35`
- `scripts/upload-release.mjs#L247-L261`

**章节来源**
- `README.md#L107-L107`
- `scripts/upload-release.mjs#L15-L35`
- `scripts/upload-release.mjs#L247-L261`

## 依赖关系分析

```mermaid
graph TB
Pkg["package.json<br/>脚本与依赖"] --> FE["Angular 依赖"]
Pkg --> CLI["@tauri-apps/cli"]
Cargo["Cargo.toml<br/>Rust 依赖与特性"] --> TauriDep["tauri / plugins"]
Cargo --> DB["sea-orm / sqlite"]
Cargo --> Net["reqwest / http"]
Conf["tauri.conf.json<br/>打包与更新配置"] --> Pkg
Conf --> Cargo
Script["upload-release.mjs<br/>上传与签名"] --> R2["R2 存储"]
Conf --> Updater["Updater 插件"]
```

**图表来源**
- `package.json#L19-L88`
- `src-tauri/Cargo.toml#L26-L65`
- `src-tauri/tauri.conf.json#L30-L68`
- `scripts/upload-release.mjs#L104-L163`

**章节来源**
- `package.json#L19-L88`
- `src-tauri/Cargo.toml#L26-L65`
- `src-tauri/tauri.conf.json#L30-L68`
- `scripts/upload-release.mjs#L104-L163`

## 性能考虑
- 构建优化：启用生产输出哈希与体积预算，减少包体大小
- 运行时优化：延迟初始化重型模块，避免主线程阻塞
- 网络优化：连接复用、压缩传输、缓存策略
- 存储优化：SQLite 查询优化与索引设计

**章节来源**
- `angular.json#L29-L43`

## 故障排除指南
- 构建失败：检查 Node.js、pnpm、Rust 版本与 Xcode CLT
- 签名失败：确认 Apple 证书与 Team ID，校验 entitlements
- 更新失败：核对 endpoint、pubkey、latest.json 与签名配对
- 权限问题：macOS entitlements 仅声明必要权限

**章节来源**
- `README.md#L35-L44`
- `scripts/build-mac-store.sh#L207-L228`
- `src-tauri/tauri.conf.json#L60-L67`

## 结论
本指南提供了 GSDJGXApp 生产环境部署的完整路径：从前端构建、后端编译到跨平台打包与自动更新。通过 Tauri 配置与脚本化流程，结合 R2 存储与签名验证，可实现稳定可靠的桌面应用分发。建议在 CI 中完善密钥管理与签名流程，并持续优化性能与安全配置。

## 附录
- 版本号：2.1.498
- 产品名称：gsdjgxapp
- 标识符：com.guaishoudejia.gxapp
- 更新端点：https://r2.guaishoudejia.com/gxapp/latest.json
- 公钥：dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IDgzODZERjYxOEUyQ0FDODYKUldTR3JDeU9ZZCtHZytlOTlWbytxaDRsb01EN1BKQ3RwWFI5cHFmSG9CMFdHVmd1dUNKRUR1UmgK

**章节来源**
- `package.json#L3-L3`
- `src-tauri/tauri.conf.json#L3-L6`
- `src-tauri/tauri.conf.json#L63-L66`
- `upload.config.json#L7-L7`