LanMountainDesktop/docs/BUILD_AND_DEPLOY.md

构建和部署指南

LanMountainDesktop 完整构建、打包和发布流程

目录

• 本地构建
• 发布构建
• 生成安装包
• CI/CD 流程
• 手动发布

本地构建

环境要求

• .NET SDK 10.0 或更高版本
• Windows 10/11 (推荐)
• Inno Setup 6 (仅生成安装包时需要)

快速构建

# 1. 还原依赖
dotnet restore LanMountainDesktop.slnx

# 2. 构建 Debug 版本
dotnet build LanMountainDesktop.slnx -c Debug

# 3. 运行主程序
dotnet run --project LanMountainDesktop/LanMountainDesktop.csproj

构建 Release 版本

dotnet build LanMountainDesktop.slnx -c Release

发布构建

Windows (x64, 自包含)

dotnet publish LanMountainDesktop/LanMountainDesktop.csproj `
  -c Release `
  -o ./publish/windows-x64 `
  --self-contained `
  -r win-x64 `
  -p:PublishSingleFile=false `
  -p:DebugType=none `
  -p:DebugSymbols=false

发布后的目录结构:

publish/windows-x64/
├── LanMountainDesktop.Launcher.exe  ← 入口
├── app-{version}/                    ← 主程序
│   ├── .current
│   ├── LanMountainDesktop.exe
│   └── ...

Linux (x64)

dotnet publish LanMountainDesktop/LanMountainDesktop.csproj `
  -c Release `
  -o ./publish/linux-x64 `
  --self-contained `
  -r linux-x64

macOS (arm64)

dotnet publish LanMountainDesktop/LanMountainDesktop.csproj `
  -c Release `
  -o ./publish/osx-arm64 `
  --self-contained `
  -r osx-arm64

生成安装包

Windows 安装包 (Inno Setup)

前提条件:

# 安装 Inno Setup
choco install innosetup -y

生成安装包:

# 1. 发布应用
dotnet publish LanMountainDesktop/LanMountainDesktop.csproj `
  -c Release `
  -o ./publish/windows-x64 `
  --self-contained `
  -r win-x64

# 2. 运行 Inno Setup 编译器
$version = "1.0.0"
$arch = "x64"

iscc.exe `
  /DMyAppVersion=$version `
  /DMyAppArch=$arch `
  /DPublishDir="publish\windows-x64" `
  /DMyOutputDir="build-installer" `
  LanMountainDesktop\installer\LanMountainDesktop.iss

输出:

build-installer/
└── LanMountainDesktop-Setup-1.0.0-x64.exe

Linux 包 (.deb)

# TODO: 添加 .deb 打包脚本

macOS 包 (.dmg)

# TODO: 添加 .dmg 打包脚本

CI/CD 流程

GitHub Actions 工作流

项目使用 GitHub Actions 自动化构建和发布。

触发条件:

• 推送 v* 标签 (例如: v1.0.0)
• 手动触发 (workflow_dispatch)

工作流文件: .github/workflows/release.yml

发布流程

1. prepare job
   ├─ 解析版本号
   └─ 设置构建变量

2. build-windows job
   ├─ 构建 x64 和 x86 版本
   ├─ 重组为 app-{version} 结构
   ├─ 生成增量包
   ├─ 生成 Inno Setup 安装包
   └─ 上传 artifacts

3. build-linux job
   ├─ 构建 x64 版本
   ├─ 生成 .deb 包
   └─ 上传 artifacts

4. build-macos job
   ├─ 构建 arm64 和 x64 版本
   ├─ 生成 .dmg 包
   └─ 上传 artifacts

5. release job
   ├─ 下载所有 artifacts
   ├─ 创建 GitHub Release
   └─ 上传所有安装包和增量包

发布产物

GitHub Release Assets:

LanMountainDesktop-v1.0.0/
├── LanMountainDesktop-Setup-1.0.0-x64.exe      # Windows 安装包
├── LanMountainDesktop-Setup-1.0.0-x86.exe
├── LanMountainDesktop-1.0.0-linux-x64.deb      # Linux 包
├── LanMountainDesktop-1.0.0-macos-arm64.dmg    # macOS 包
├── app-1.0.0.zip                                # 完整应用包
├── delta-0.9.9-to-1.0.0.zip                    # 增量包
├── files-1.0.0.json                             # 文件清单
└── files-1.0.0.json.sig                         # RSA 签名

手动发布

1. 准备发布

# 1. 更新版本号
# 编辑 Directory.Build.props 中的 <Version>

# 2. 更新 CHANGELOG.md
# 记录本次发布的变更

# 3. 提交变更
git add .
git commit -m "chore: prepare release v1.0.0"
git push

2. 创建 Release 标签

# 创建标签
git tag v1.0.0

# 推送标签 (触发 CI)
git push origin v1.0.0

3. 等待 CI 完成

访问 GitHub Actions 页面,等待构建完成:

https://github.com/YourOrg/LanMountainDesktop/actions

4. 验证 Release

1. 访问 Releases 页面
2. 检查所有安装包是否上传成功
3. 下载并测试安装包
4. 验证增量更新功能

5. 发布公告

• 在 GitHub Release 中编辑发布说明
• 发布到社区/论坛
• 更新官网下载链接

增量包生成

手动生成增量包

# 1. 准备两个版本的发布目录
dotnet publish ... -o ./publish/app-1.0.0
dotnet publish ... -o ./publish/app-1.0.1

# 2. 生成增量包
./scripts/Generate-DeltaPackage.ps1 `
  -PreviousVersion "1.0.0" `
  -CurrentVersion "1.0.1" `
  -PreviousDir "./publish/app-1.0.0" `
  -CurrentDir "./publish/app-1.0.1" `
  -OutputDir "./delta-output"

# 3. 签名文件清单
./scripts/Sign-FileMap.ps1 `
  -FilesJsonPath "./delta-output/files-1.0.1.json" `
  -PrivateKeyPath "./private-key.pem"

输出:

delta-output/
├── delta-1.0.0-to-1.0.1.zip
├── files-1.0.1.json
└── files-1.0.1.json.sig

生成 RSA 密钥对

# 生成私钥
openssl genrsa -out private-key.pem 2048

# 提取公钥
openssl rsa -in private-key.pem -pubout -out public-key.pem

重要:

• 私钥保存在安全位置 (GitHub Secrets)
• 公钥打包到 Launcher 中 (.launcher/update/public-key.pem)

版本号规范

遵循 Semantic Versioning 2.0.0:

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

例如:
- 1.0.0          (正式版)
- 1.0.1          (补丁版本)
- 1.1.0          (新功能)
- 2.0.0          (破坏性变更)
- 1.0.0-beta.1   (预览版)
- 1.0.0-rc.1     (候选版本)

版本号更新规则

• MAJOR: 破坏性 API 变更
• MINOR: 新功能,向后兼容
• PATCH: Bug 修复,向后兼容
• PRERELEASE: 预览版标识 (alpha, beta, rc)

故障排除

构建失败

问题: error NU1102: Unable to find package

解决:

dotnet restore --force
dotnet nuget locals all --clear

发布失败

问题: Launcher 目录不存在

解决: 检查 LanMountainDesktop.csproj 中的 CopyLauncherToPublish 目标是否正确执行。

安装包生成失败

问题: Inno Setup 找不到文件

解决: 确保 PublishDir 路径正确,且包含 app-{version}/ 目录结构。

相关文档

• 开发文档
• Launcher 架构
• 更新系统
• 故障排除