feat.文档更新

docs/05-更新与发布/01-更新系统架构.md

@@ -0,0 +1,474 @@
+# 更新系统架构
+
+本文档描述阑山桌面的更新系统设计，包括增量更新、原子化安装、版本管理和回滚机制。
+
+## 更新系统概览
+
+### 核心特性
+
+- ✅ **增量更新** - 只下载变更文件，节省带宽
+- ✅ **原子化更新** - 保证完整性，失败自动回滚
+- ✅ **多版本共存** - 支持多版本并存和快速切换
+- ✅ **签名验证** - RSA 签名确保安全性
+- ✅ **版本回退** - 一键回退到上一版本
+- ✅ **更新频道** - Stable/Preview 频道切换
+- ✅ **后台下载** - 静默下载，不影响使用
+
+### 架构组件
+
+```
+┌──────────────────────────────────────────────┐
+│        LanMountainDesktop (Host)             │
+│                                              │
+│  ┌────────────────────────────────────────┐ │
+│  │     UpdateOrchestrator                 │ │
+│  │  (更新编排 - Host 拥有)                 │ │
+│  │  - 检查更新                             │ │
+│  │  - 下载更新                             │ │
+│  │  - 应用更新                             │ │
+│  │  - 回滚更新                             │ │
+│  └────────────────────────────────────────┘ │
+│                                              │
+│  ┌────────────────┐  ┌──────────────────┐  │
+│  │UpdateInstall   │  │UpdateRollback    │  │
+│  │  Gateway       │  │   Gateway        │  │
+│  └────────────────┘  └──────────────────┘  │
+└──────────────────────────────────────────────┘
+                    ↓ 写入 deployment.lock
+┌──────────────────────────────────────────────┐
+│            Launcher                          │
+│  (启动器 - 版本选择和清理)                     │
+│                                              │
+│  ┌────────────────────────────────────────┐ │
+│  │    DeploymentLocator                   │ │
+│  │  扫描和选择最佳版本                      │ │
+│  └────────────────────────────────────────┘ │
+└──────────────────────────────────────────────┘
+```
+
+## 目录结构
+
+### 版本目录布局
+
+```
+安装根目录/
+├── LanMountainDesktop.Launcher.exe     # 启动器
+├── app-1.0.0/                           # 旧版本
+│   ├── .destroy                         # 待删除标记
+│   ├── LanMountainDesktop.exe
+│   └── ...
+├── app-1.0.1/                           # 当前版本
+│   ├── .current                         # 当前版本标记
+│   ├── LanMountainDesktop.exe
+│   └── ...
+├── app-1.0.2/                           # 新版本（下载中）
+│   ├── .partial                         # 未完成标记
+│   └── ...
+└── .Launcher/                           # 启动器数据
+    ├── state/
+    │   └── oobe-state.json
+    ├── update/
+    │   ├── incoming/                    # 更新缓存
+    │   │   ├── deployment.lock          # 部署锁
+    │   │   ├── plonds-filemap.json      # 文件清单
+    │   │   ├── plonds-filemap.sig       # RSA 签名
+    │   │   └── objects/                 # 对象文件
+    │   ├── public-key.pem               # 公钥
+    │   └── snapshots/                   # 更新快照
+    │       └── snapshot-{id}.json
+    └── logs/
+```
+
+### 版本标记文件
+
+| 标记文件 | 含义 | 创建者 | 删除时机 |
+|---------|------|--------|---------|
+| `.current` | 当前使用版本 | Host UpdateInstallGateway | 切换到新版本时 |
+| `.partial` | 下载未完成 | Host UpdateInstallGateway | 安装成功或失败清理时 |
+| `.destroy` | 待删除版本 | Host UpdateInstallGateway | Launcher 下次启动清理 |
+
+## 更新流程
+
+### 完整更新流程
+
+```
+1. Host 后台检查更新
+   UpdateOrchestrator.CheckAsync()
+   - 调用 manifest provider (PLONDS/GitHub)
+   - 根据更新频道过滤版本
+   - 对比当前版本和最新版本
+         ↓
+2. 发现新版本
+   用户收到通知
+         ↓
+3. Host 下载更新
+   UpdateOrchestrator.DownloadAsync()
+   - 下载 plonds-filemap.json
+   - 下载 plonds-filemap.sig
+   - 下载对象文件
+   - 保存到 .Launcher/update/incoming/
+         ↓
+4. 写入 deployment.lock
+   {
+     "TargetVersion": "1.0.2",
+     "FromVersion": "1.0.1",
+     "FileMapPath": "...",
+     "SignaturePath": "...",
+     "ArchivePath": "..."
+   }
+         ↓
+5. Host 调用 UpdateInstallGateway
+   UpdateInstallGateway.InstallAsync()
+   - 验证签名 (UpdateSignatureVerifier)
+   - 创建目标目录 app-1.0.2/
+   - 标记 .partial
+   - 保存快照到 snapshots/
+         ↓
+6. 应用文件操作
+   PlondsUpdateApplier.ApplyFileMap()
+   For each file in filemap:
+     - action="replace" → 从对象解压
+     - action="reuse" → 从旧版本复制
+     - action="delete" → 跳过
+         ↓
+7. 验证所有文件哈希
+   For each file:
+     计算 SHA256
+     与 filemap 对比
+         ↓
+8. 激活新版本
+   DeploymentActivator.ActivateDeployment()
+   - 移除 app-1.0.2/.partial
+   - 添加 app-1.0.2/.current
+   - 移除 app-1.0.1/.current
+   - 添加 app-1.0.1/.destroy
+         ↓
+9. 更新快照状态 = "applied"
+         ↓
+10. 清理 incoming 缓存
+    IncomingArtifactsCleaner.Clean()
+         ↓
+11. 用户重启应用
+    Launcher 启动 app-1.0.2/
+         ↓
+12. Launcher 清理 .destroy 目录
+    删除 app-1.0.1/
+```
+
+### 增量包结构
+
+#### GitHub Release Assets
+
+```
+LanMountainDesktop-v1.0.2/
+├── LanMountainDesktop-Setup-1.0.2-x64.exe      # 完整安装包
+├── releases.win.json                            # VeloPack 清单
+├── LanMountainDesktop-1.0.2-win-x64.nupkg      # VeloPack 包
+├── RELEASES                                     # VeloPack 元数据
+└── (legacy) plonds-filemap-1.0.2.json          # 旧格式（可选）
+```
+
+#### plonds-filemap.json 格式
+
+```json
+{
+  "FromVersion": "1.0.1",
+  "ToVersion": "1.0.2",
+  "GeneratedAt": "2026-06-08T10:00:00Z",
+  "Files": [
+    {
+      "Path": "LanMountainDesktop.exe",
+      "Action": "replace",
+      "Sha256": "abc123...",
+      "Size": 1024000,
+      "ObjectPath": "objects/abc123"
+    },
+    {
+      "Path": "LanMountainDesktop.dll",
+      "Action": "reuse",
+      "Sha256": "def456...",
+      "Size": 512000
+    },
+    {
+      "Path": "OldPlugin.dll",
+      "Action": "delete"
+    }
+  ]
+}
+```
+
+### 文件操作类型
+
+| Action | 说明 | 处理方式 |
+|--------|------|----------|
+| `replace` | 新增或替换文件 | 从 objects/ 解压 |
+| `reuse` | 文件未变更 | 从旧版本目录复制 |
+| `delete` | 删除文件 | 不操作（新版本中不存在） |
+
+## 原子化保证
+
+### 失败场景处理
+
+| 失败场景 | 检测机制 | 恢复方式 |
+|---------|---------|---------|
+| **签名验证失败** | RSA 验证 | 拒绝安装，保留旧版本 |
+| **文件哈希不匹配** | SHA256 校验 | 自动回滚到旧版本 |
+| **磁盘空间不足** | 写入失败 | 自动回滚到旧版本 |
+| **进程崩溃** | .partial 标记 | Launcher 启动时清理 |
+| **断电/强制关机** | .partial 标记 | Launcher 启动时清理 |
+
+### 回滚机制
+
+```csharp
+private void TryRollbackOnFailure(SnapshotMetadata snapshot)
+{
+    try
+    {
+        // 1. 删除未完成的新版本目录
+        if (Directory.Exists(snapshot.TargetDirectory))
+        {
+            Directory.Delete(snapshot.TargetDirectory, true);
+        }
+        
+        // 2. 移除旧版本的 .destroy 标记
+        var destroyMarker = Path.Combine(
+            snapshot.SourceDirectory, 
+            ".destroy"
+        );
+        if (File.Exists(destroyMarker))
+        {
+            File.Delete(destroyMarker);
+        }
+        
+        // 3. 确保旧版本有 .current 标记
+        var currentMarker = Path.Combine(
+            snapshot.SourceDirectory,
+            ".current"
+        );
+        if (!File.Exists(currentMarker))
+        {
+            File.WriteAllText(currentMarker, string.Empty);
+        }
+        
+        // 4. 更新快照状态
+        snapshot.Status = "rolled_back";
+        SaveSnapshot(snapshotPath, snapshot);
+    }
+    catch (Exception ex)
+    {
+        _logger.LogError(ex, "Rollback failed");
+        // 记录错误但不抛出
+    }
+}
+```
+
+## 版本管理
+
+### 版本选择算法
+
+Launcher 启动时的版本选择逻辑：
+
+```csharp
+public string? FindBestVersion()
+{
+    var appDirs = Directory.GetDirectories(
+        _installRoot,
+        "app-*"
+    );
+    
+    // 1. 过滤掉标记为 .partial 或 .destroy 的版本
+    var validDirs = appDirs.Where(dir => 
+        !File.Exists(Path.Combine(dir, ".partial")) &&
+        !File.Exists(Path.Combine(dir, ".destroy"))
+    );
+    
+    // 2. 优先选择带 .current 标记的版本
+    var currentDir = validDirs.FirstOrDefault(dir =>
+        File.Exists(Path.Combine(dir, ".current"))
+    );
+    if (currentDir != null)
+        return currentDir;
+    
+    // 3. 否则选择版本号最高的
+    var sortedDirs = validDirs
+        .Select(dir => new {
+            Path = dir,
+            Version = ParseVersion(dir)
+        })
+        .Where(x => x.Version != null)
+        .OrderByDescending(x => x.Version)
+        .ToList();
+    
+    return sortedDirs.FirstOrDefault()?.Path;
+}
+```
+
+### 版本回退
+
+用户可以通过设置页手动回退到上一版本：
+
+```
+设置 → 更新 → 版本历史 → 回滚
+```
+
+**回退流程**:
+
+```
+1. Host 调用 UpdateRollbackGateway
+         ↓
+2. 读取最新快照 (snapshots/)
+         ↓
+3. 获取 SourceDirectory (旧版本)
+         ↓
+4. 激活旧版本
+   - 移除当前版本的 .current
+   - 添加 .current 到旧版本
+   - 移除旧版本的 .destroy
+   - 添加 .destroy 到当前版本
+         ↓
+5. 更新快照状态 = "manual_rollback"
+         ↓
+6. 提示用户重启应用
+```
+
+## 安全机制
+
+### RSA 签名
+
+#### 签名生成（CI 环境）
+
+```powershell
+# scripts/Sign-FileMap.ps1
+$privateKeyPem = Get-Content -Path $PrivateKeyPath -Raw
+$rsa = [System.Security.Cryptography.RSA]::Create()
+$rsa.ImportFromPem($privateKeyPem)
+
+$jsonBytes = [System.IO.File]::ReadAllBytes($FilesJsonPath)
+$signature = $rsa.SignData(
+    $jsonBytes,
+    [System.Security.Cryptography.HashAlgorithmName]::SHA256,
+    [System.Security.Cryptography.RSASignaturePadding]::Pkcs1
+)
+
+$signatureBase64 = [Convert]::ToBase64String($signature)
+Set-Content -Path "$FilesJsonPath.sig" -Value $signatureBase64
+```
+
+#### 签名验证（Launcher）
+
+```csharp
+private (bool Success, string Message) VerifySignature(
+    string fileMapPath,
+    string signaturePath)
+{
+    // 1. 读取公钥
+    var publicKeyPath = Path.Combine(
+        _launcherRoot,
+        "update",
+        "public-key.pem"
+    );
+    using var rsa = RSA.Create();
+    rsa.ImportFromPem(File.ReadAllText(publicKeyPath));
+    
+    // 2. 读取签名
+    var signatureBase64 = File.ReadAllText(signaturePath).Trim();
+    var signature = Convert.FromBase64String(signatureBase64);
+    
+    // 3. 验证
+    var jsonBytes = File.ReadAllBytes(fileMapPath);
+    var isValid = rsa.VerifyData(
+        jsonBytes,
+        signature,
+        HashAlgorithmName.SHA256,
+        RSASignaturePadding.Pkcs1
+    );
+    
+    return isValid
+        ? (true, "ok")
+        : (false, "Signature verification failed");
+}
+```
+
+### 文件完整性验证
+
+```csharp
+// 验证所有文件的 SHA256
+foreach (var file in fileMap.Files)
+{
+    if (file.Action == "delete")
+        continue;
+    
+    var fullPath = Path.Combine(targetDeployment, file.Path);
+    var actualHash = ComputeSha256Hex(fullPath);
+    
+    if (!string.Equals(
+        actualHash,
+        file.Sha256,
+        StringComparison.OrdinalIgnoreCase))
+    {
+        throw new InvalidOperationException(
+            $"File hash mismatch for '{file.Path}'."
+        );
+    }
+}
+```
+
+### 路径遍历防护
+
+```csharp
+private static void EnsurePathWithinRoot(
+    string targetPath,
+    string rootPath)
+{
+    var fullTarget = Path.GetFullPath(targetPath);
+    var fullRoot = Path.GetFullPath(rootPath);
+    
+    if (!fullTarget.StartsWith(
+        fullRoot,
+        StringComparison.OrdinalIgnoreCase))
+    {
+        throw new InvalidOperationException(
+            $"Path traversal detected: {targetPath}"
+        );
+    }
+}
+```
+
+## 更新频道
+
+### 频道类型
+
+| 频道 | 说明 | GitHub Release 过滤 |
+|------|------|---------------------|
+| **Stable** | 正式版，推荐大多数用户使用 | `prerelease=false` |
+| **Preview** | 预览版，包含最新功能和 Bug 修复 | 所有版本（包括 `prerelease=true`） |
+
+### 切换频道
+
+```
+设置 → 更新 → 更新频道 → 选择频道
+```
+
+切换后立即检查更新。
+
+## VeloPack 集成
+
+### 当前状态
+
+- ✅ CI 管道已生成 VeloPack 原生资产（`releases.win.json`, `*.nupkg`, `RELEASES`）
+- ✅ Host 拥有更新检查/下载/应用/回滚编排
+- ✅ Launcher 仅负责版本选择和启动
+- ⚠️ 旧的 `files.json` + `update.zip` 生成作为禁用的回退路径保留在 CI 中
+
+### 未来迁移
+
+计划完全迁移到 VeloPack：
+1. 移除旧格式支持
+2. 简化 CI 管道
+3. 利用 VeloPack 的增量更新算法
+
+## 相关文档
+
+- [打包与构建](../05-更新与发布/03-打包与构建.md) - 构建流程
+- [CI/CD 配置](../05-更新与发布/04-CICD配置.md) - 自动化构建
+- [启动器系统](02-启动器系统.md) - 启动器详细设计