From 921f1a71b6e4b6530e7e90fabc264bd74780d16d Mon Sep 17 00:00:00 2001 From: JusterZhu Date: Thu, 4 Jun 2026 01:45:22 +0800 Subject: [PATCH 1/5] docs: restructure website navigation and content MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove deprecated docs: GeneralTracer, GeneralClient.OSS, GeneralUpdate.Maui.OSS (3 langs) - Remove outdated guides: Architecture, Configuration, Driver, Pipeline, Security, Systemlog, System infomation (3 langs) - Remove outdated quickstart: Advanced cookbook, Quik start (3 langs) - Move GeneralUpdate.PacketTool from /doc to /quickstart (3 langs) - Merge Sample UI into Beginner cookbook (3 langs) - Rename /docs/guide to 帮助/Help (sidebar, _category_.json, i18n) - Add 商务 navbar dropdown with GeneralSpacestation + software outsourcing page (3 langs) - Add software outsourcing page (3 langs) - Update releaselog with v10.5.0-beta.2 entry (3 langs) - Update FAQ.md broken links to removed Architecture/Configuration/Pipeline/Security pages (3 langs) - Streamline sidebars.js to 4 categories: Quick Start, Components, 帮助, Release Log Co-Authored-By: Claude Opus 4.8 --- website/docs/doc/GeneralClient.OSS.md | 134 -- website/docs/doc/GeneralTracer.md | 64 - website/docs/doc/GeneralUpdate.Maui.OSS.md | 170 -- website/docs/doc/outsourcing.md | 37 + website/docs/guide/Architecture.md | 353 ---- website/docs/guide/Configuration.md | 530 ----- website/docs/guide/Driver.md | 139 -- website/docs/guide/FAQ.md | 8 +- website/docs/guide/Pipeline.md | 423 ---- website/docs/guide/Security.md | 427 ----- website/docs/guide/System infomation.md | 85 - website/docs/guide/Systemlog.md | 40 - website/docs/guide/_category_.json | 6 +- website/docs/quickstart/Advanced cookbook.md | 808 -------- website/docs/quickstart/Beginner cookbook.md | 21 +- .../GeneralUpdate.PacketTool.md | 0 website/docs/quickstart/Quik start.md | 77 - website/docs/quickstart/Sample UI.md | 20 - .../releaselog/GeneralUpdateReleaselog.md | 10 + website/docusaurus.config.js | 17 + .../current.json | 26 +- .../current/doc/GeneralClient.OSS.md | 133 -- .../current/doc/GeneralTracer.md | 64 - .../current/doc/GeneralUpdate.Maui.OSS.md | 170 -- .../current/doc/outsourcing.md | 37 + .../current/guide/Architecture.md | 228 --- .../current/guide/Configuration.md | 318 --- .../current/guide/Driver.md | 139 -- .../current/guide/FAQ.md | 8 +- .../current/guide/Pipeline.md | 254 --- .../current/guide/Security.md | 237 --- .../current/guide/System infomation.md | 85 - .../current/guide/Systemlog.md | 40 - .../current/guide/_category_.json | 6 +- .../current/quickstart/Advanced cookbook.md | 806 -------- .../current/quickstart/Beginner cookbook.md | 21 +- .../GeneralUpdate.PacketTool.md | 0 .../current/quickstart/Quik start.md | 79 - .../current/quickstart/Sample UI.md | 20 - .../releaselog/GeneralUpdateReleaselog.md | 26 +- .../en/docusaurus-theme-classic/navbar.json | 40 +- .../current.json | 26 +- .../current/doc/GeneralClient.OSS.md | 135 -- .../current/doc/GeneralTracer.md | 66 - .../current/doc/GeneralUpdate.Maui.OSS.md | 198 -- .../current/doc/outsourcing.md | 37 + .../current/guide/Driver.md | 146 -- .../current/guide/FAQ.md | 338 ++++ .../current/guide/System infomation.md | 84 - .../current/guide/Systemlog.md | 42 - .../current/guide/_category_.json | 6 +- .../current/quickstart/Advanced cookbook.md | 808 -------- .../current/quickstart/Beginner cookbook.md | 21 +- .../GeneralUpdate.PacketTool.md | 0 .../current/quickstart/Quik start.md | 79 - .../current/quickstart/Sample UI.md | 20 - .../releaselog/GeneralUpdateReleaselog.md | 1704 ++++++++--------- .../docusaurus-theme-classic/navbar.json | 26 +- website/sidebars.js | 76 +- 59 files changed, 1366 insertions(+), 8552 deletions(-) delete mode 100644 website/docs/doc/GeneralClient.OSS.md delete mode 100644 website/docs/doc/GeneralTracer.md delete mode 100644 website/docs/doc/GeneralUpdate.Maui.OSS.md create mode 100644 website/docs/doc/outsourcing.md delete mode 100644 website/docs/guide/Architecture.md delete mode 100644 website/docs/guide/Configuration.md delete mode 100644 website/docs/guide/Driver.md delete mode 100644 website/docs/guide/Pipeline.md delete mode 100644 website/docs/guide/Security.md delete mode 100644 website/docs/guide/System infomation.md delete mode 100644 website/docs/guide/Systemlog.md delete mode 100644 website/docs/quickstart/Advanced cookbook.md rename website/docs/{doc => quickstart}/GeneralUpdate.PacketTool.md (100%) delete mode 100644 website/docs/quickstart/Quik start.md delete mode 100644 website/docs/quickstart/Sample UI.md delete mode 100644 website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md delete mode 100644 website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md delete mode 100644 website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Maui.OSS.md create mode 100644 website/i18n/en/docusaurus-plugin-content-docs/current/doc/outsourcing.md delete mode 100644 website/i18n/en/docusaurus-plugin-content-docs/current/guide/Architecture.md delete mode 100644 website/i18n/en/docusaurus-plugin-content-docs/current/guide/Configuration.md delete mode 100644 website/i18n/en/docusaurus-plugin-content-docs/current/guide/Driver.md delete mode 100644 website/i18n/en/docusaurus-plugin-content-docs/current/guide/Pipeline.md delete mode 100644 website/i18n/en/docusaurus-plugin-content-docs/current/guide/Security.md delete mode 100644 website/i18n/en/docusaurus-plugin-content-docs/current/guide/System infomation.md delete mode 100644 website/i18n/en/docusaurus-plugin-content-docs/current/guide/Systemlog.md delete mode 100644 website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md rename website/i18n/en/docusaurus-plugin-content-docs/current/{doc => quickstart}/GeneralUpdate.PacketTool.md (100%) delete mode 100644 website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Quik start.md delete mode 100644 website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Sample UI.md delete mode 100644 website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md delete mode 100644 website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md delete mode 100644 website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Maui.OSS.md create mode 100644 website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/outsourcing.md delete mode 100644 website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/Driver.md create mode 100644 website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/FAQ.md delete mode 100644 website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/System infomation.md delete mode 100644 website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/Systemlog.md delete mode 100644 website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md rename website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/{doc => quickstart}/GeneralUpdate.PacketTool.md (100%) delete mode 100644 website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Quik start.md delete mode 100644 website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Sample UI.md diff --git a/website/docs/doc/GeneralClient.OSS.md b/website/docs/doc/GeneralClient.OSS.md deleted file mode 100644 index 9eab92c..0000000 --- a/website/docs/doc/GeneralClient.OSS.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -sidebar_position: 9 ---- - -### Definition - -Namespace: GeneralUpdate.Core - -Assembly: GeneralUpdate.Core.dll - - - -**OSS** - -OSS stands for Object Storage Service. For those developing server-side technology stacks, this term is likely familiar, as major cloud service providers offer similar services. Simply put, it's a file server. Examples include Alibaba Cloud OSS, Tencent Cloud COS, and Huawei Cloud OBS. While they have different names, their functionalities are quite similar. The new feature of this update component is implemented in a very similar manner, so we chose OSS to name this feature, making it easy for developers to quickly understand its purpose (requires the use of the GeneralUpdate.Core component). - - - -**GeneralClientOSS** - -The GeneralClientOSS class is another update mechanism. Unlike GeneralClientBootstrap, GeneralClientOSS does not require writing server-side code and directly updates based on the version information from the version.json file on the OSS file server, simplifying the threshold for beginners using this component. - -```c# -public sealed class GeneralClientOSS -``` - - - -### Example - -| Description | Address | -| --------------------------- | ------------------------------------------------------------ | -| Address of code example | [Enter](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/OSS) | -| Hashing algorithm (sha256) | [Enter](https://github.com/GeneralLibrary/GeneralUpdate/blob/master/src/c%23/GeneralUpdate.Core/Pipeline/HashMiddleware.cs) | -| Test script (oss_start.cmd) | [Enter](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src) | -| versions.json Making tool | [Enter](https://github.com/GeneralLibrary/GeneralUpdate.Tools) | - -#### OSS Process - -![](imgs/oss_flow.png) - -1. Prepare the version.json file for version information configuration, and update the file (update.zip) for packaging. The packaging can be done manually using compression software (such as 7zip, a free software). - -```json -[ - { - "PacketName": "packet_20250102230201638_1.0.0.1", - "Hash": "ad1a85a9169ca0083ab54ba390e085c56b9059efc3ca8aa1ec9ed857683cc4b1", - "Version": "1.0.0.1", - "Url": "http://localhost:5000/packages/packet_20250102230201638_1.0.0.1.zip", - "PubTime": "2025-01-02T23:48:21" - } -] -``` - - - -2. When the Client starts, it directly requests the OSS server or file server to download the version.json file. - -![](imgs/oss_util.png) - -3. After downloading to the local system, it parses the version information to determine if an update is needed. If so, it passes the information to Upgrade through a process launch (Client self-closes). - -4. After Upgrade starts, it directly downloads update.zip and extracts it locally to overwrite the local files. - -5. After the Upgrade completes, it starts the Client and self-closes. The update ends. Compared to the GeneralUpdateBootstrap function, the GeneralUpdateOSS function has a very low usage threshold. If the company does not have high requirements for automatic updates, this feature can be used. In summary, this function downloads the version.json and updates based on the content in the file, downloading each version's update package and extracting it to complete the update. - -6. Since the OSS functionality does not include a blacklist mechanism, when creating the update.zip, please ensure that the files used internally by the following components are not added to the package, or directly release them as a single file to avoid occupying space and reducing update complexity. - - -```json -"Microsoft.Bcl.AsyncInterfaces.dll", -"System.Collections.Immutable.dll", -"System.IO.Pipelines.dll", -"System.Text.Encodings.Web.dll", -"System.Text.Json.dll" -``` - - - -The following example defines methods, including the usage of GeneralClientOSS , GeneralUpdateOSS. - -GeneralClientOSS : - -```c# -using System.Text; -using GeneralUpdate.Core; - - -var paramsOSS = new GlobalConfigInfoOSS -{ - Url = "http://localhost:5000/packages/versions.json", - CurrentVersion = "1.0.0.0", - VersionFileName = "versions.json", - AppName = "OSSClientSample.exe", - Encoding = Encoding.UTF8.WebName -}; - -await GeneralClientOSS.Start(paramsOSS, "OSSUpgradeSample.exe"); -``` - -GeneralUpdateOSS : - -``` -using GeneralUpdate.Core; - -/* - * GeneralUpdateOSS will by default read the JSON content of GlobalConfigInfoOSS stored in the system environment variables by GeneralClientOSS - * , and developers do not need to be concerned with the entire process. - * - * Environment.GetEnvironmentVariable("GlobalConfigInfoOSS", EnvironmentVariableTarget.User); - * - * Typically, GeneralClientOSS and GeneralUpdateOSS appear as a pair. - */ -try -{ - await GeneralUpdateOSS.Start(); -} -catch (Exception ex) -{ - Console.WriteLine(ex.Message); -} -``` - - - -### Applicable to - -| Product | Version | -| -------------- | ------------- | -| .NET | 5, 6, 7, 8, 9, 10 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | \ No newline at end of file diff --git a/website/docs/doc/GeneralTracer.md b/website/docs/doc/GeneralTracer.md deleted file mode 100644 index 6e73a31..0000000 --- a/website/docs/doc/GeneralTracer.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -sidebar_position: 8 ---- - -### GeneralTracer - -> **合并说明**：`GeneralUpdate.Common` 已合并到 `GeneralUpdate.Core`。`GeneralTracer` 现在位于 `GeneralUpdate.Core` 命名空间内，引用 `GeneralUpdate.Core` 包即可自动获得，无需单独引用。 - -命名空间: `GeneralUpdate.Core` - -程序集: `GeneralUpdate.Core.dll` - -`GeneralTracer` 提供组件内部异常信息和执行流程的追踪输出。它默认启用，引用 `GeneralUpdate.Core` 时会自动包含。 - -```c# -public static class GeneralTracer -``` - - - -### Example - -This mechanism is **enabled by default**. It outputs the component's internal exception information and partial execution flow information, which can be viewed and analyzed simultaneously via the IDE console, log files, and Dbgview debugging tool. - -```c# -// Disable the Trace mechanism in production environments or when it is not needed; it is enabled by default. -GeneralTracer.SetTracingEnabled(false); - -// Call this method before the bootstrap class. -_ = await new GeneralClientBootstrap() - .LaunchAsync(); -``` - - - -#### IDE Console - -![](imgs\IDE.png) - - - -#### Log File - -This file is generated by default in the **Logs** folder under the running directory, with the naming format: `generalupdate-trace [today].log`. This log **does not depend on third-party components**. - -![](imgs\log.png) - - - -#### Dbgview Debugging Tool - -![](imgs\DebugView.png) - - - -### Application to - -| Product | Versions | -| -------------- | ----------------- | -| .NET | 5, 6, 7, 8, 9, 10 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | - diff --git a/website/docs/doc/GeneralUpdate.Maui.OSS.md b/website/docs/doc/GeneralUpdate.Maui.OSS.md deleted file mode 100644 index 5454b2a..0000000 --- a/website/docs/doc/GeneralUpdate.Maui.OSS.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -sidebar_position: 10 ---- - -### Definition - -Namespace: GeneralUpdate.Maui.OSS - -Assembly: GeneralUpdate.Maui.OSS.dll - - - -The GeneralUpdate.Maui.OSS component is used to implement the update mechanism for .NET MAUI, currently only supporting automatic upgrades on the Android platform. - -```c# -public sealed class GeneralUpdateOSS -``` - - - -### Example - -![](imgs/maui_android_upgrade.png) - -![](imgs/oss_maui_flow.png) - -1. Prepare the version.json configuration file and the update file (update.apk), which is the new version of the apk (or .abb). - -2. When the client starts, it directly requests the OSS server or file server to download the version.json file. - -```json -{ - "PubTime": 1680444916, - "Name": "com.companyname.generalupdate.ossclient", - "MD5": "9bf414990a67e74f11752d03f49b15d8", - "Version": "1.0.5", - "Url": "http://192.168.50.203/com.companyname.generalupdate.ossclient.apk" -} -``` - -3. After downloading locally, parse the version information content to determine if an update is needed. 4. If an update is needed, download update.apk. 5. After the download is complete, execute the installation, which is handled by the Android operating system. After execution, run the new version of the app. - -The following example defines methods, including how to use GeneralUpdateOSS. - -```c# -Task.Run(async () => -{ - var url = "http://192.168.50.203"; - var apk = "com.companyname.generalupdate.ossclient.apk"; - var authority = "com.generalupdate.oss.fileprovider"; - var currentVersion = "1.0.0.0"; - var versionFileName = "version.json"; - GeneralUpdateOSS.AddListenerDownloadProcess(OnOSSDownload); - GeneralUpdateOSS.AddListenerException(OnException); - await GeneralUpdateOSS.Start(new ParamsAndroid(url, apk, authority, currentVersion, versionFileName)); -}); -``` - -### Annotations - -GeneralUpdateOSS provides the following capabilities. - -#### Properties - -| Properties | Description | -| ------------- | ----------------------------------------------------- | -| ParamsAndroid | Update configuration parameters for Android platform. | - -#### Methods - -| Method | Description | -| ---------------------------- | ------------------------------------------ | -| Start() | Start the OSS update for Android platform. | -| AddListenerDownloadProcess() | Monitor download progress. | -| AddListenerException() | Listen for internal exception information. | - -### 🌴ParamsAndroid - -**Properties** - -**Url**: string - The API server request address. - -**Apk**: string - The Android apk name. - -**CurrentVersion**: string - The current version. - -**Authority**: string - The apk author. - -**VersionFileName**: string - The version file name. - -### 🌼Start() - -**Method** - -Start the OSS update for the Android platform. - -```c# -public static async Task Start(ParamsAndroid parameter) where TStrategy : AbstractStrategy, new(); -``` - -**Parameter Type** - -ParamsAndroid: Update configuration parameters for the Android platform. For detailed content, refer to this document 🌴ParamsAndroid. - -**Parameter** - -**parameter**: ParamsAndroid - Update configuration parameters for the Android platform. - -### 🌼AddListenerDownloadProcess() - -**Method** - -Monitor download progress. - -```c# -public static void AddListenerDownloadProcess(Action callbackAction); -``` - -**Parameter Type** - -**sender**: object - -Operation handle. - -**args**: OSSDownloadArgs - -Download progress notification parameters. - -**Parameter** - -```c# -callbackAction Action -``` - -Listen for current version download progress event callback parameters. - -### 🌼AddListenerException() - -**Method** - -Listen for internal exception information. - -```c# -public static void AddListenerException(Action callbackAction); -``` - -**Parameter Type** - -**sender**: object - -Operation handle. - -**args**: ExceptionEventArgs - -Update exception parameters. - -**Parameter** - -```c# -callbackAction Action -``` - -Listen for current version download progress event callback parameters. - -### Applies to - -| Product | Version | -| --------- | ---------------- | -| .NET | 7, 8, 9 | -| .NET MAUI | .NET 8 - Android | \ No newline at end of file diff --git a/website/docs/doc/outsourcing.md b/website/docs/doc/outsourcing.md new file mode 100644 index 0000000..ff77399 --- /dev/null +++ b/website/docs/doc/outsourcing.md @@ -0,0 +1,37 @@ +--- +sidebar_position: 99 +--- + +# 软件外包服务 + +GeneralLibrary 团队提供专业的 .NET 软件外包服务，涵盖以下领域： + +## 服务范围 + +| 服务类别 | 说明 | +| --- | --- | +| 自动更新系统集成 | 基于 GeneralUpdate 为企业级应用搭建完整的自动更新体系，包括版本管理、差分包生成、灰度发布、回滚策略 | +| 桌面应用开发 | WPF / WinForms / Avalonia / WinUI / MAUI 跨平台桌面应用开发 | +| Web 后端开发 | ASP.NET Core Web API、SignalR 实时通信、微服务架构设计与实现 | +| 驱动更新方案 | 基于 GeneralUpdate.Drivelution 的跨平台驱动更新方案设计与集成 | +| 插件/扩展系统 | 基于 GeneralUpdate.Extension 的插件生态搭建，支持远程查询、下载、安装、依赖管理 | +| CI/CD 流水线 | 基于 GitHub Actions / Azure DevOps 的自动化构建、测试、发布流水线 | +| 技术咨询 | 架构评审、性能优化、代码重构、安全审计 | + +## 技术栈 + +- **.NET**: .NET 8/9/10, ASP.NET Core, WPF, Avalonia, MAUI +- **数据库**: SQL Server, PostgreSQL, MySQL, Redis +- **云服务**: Azure, AWS, 阿里云 +- **DevOps**: GitHub Actions, Azure Pipelines, Docker, Kubernetes + +## 联系方式 + +| 渠道 | 信息 | +| --- | --- | +| GitHub | [GeneralLibrary](https://github.com/GeneralLibrary) | +| 邮箱 | 请通过 GitHub Issues 联系 | + +--- + +欢迎各行业企业客户洽谈合作，我们将根据您的具体需求提供定制化解决方案。 diff --git a/website/docs/guide/Architecture.md b/website/docs/guide/Architecture.md deleted file mode 100644 index 999214d..0000000 --- a/website/docs/guide/Architecture.md +++ /dev/null @@ -1,353 +0,0 @@ ---- -sidebar_position: 1 ---- - -# 系统架构 - -## 架构概览 - -GeneralUpdate 是一个跨平台 .NET 自动更新框架，采用**客户端-升级助手-服务端**三层架构。整个更新流程涉及多个独立进程和组件的协同工作。 - ---- - -## 整体架构 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ 服务端 (Server) │ -│ ┌─────────────┐ ┌──────────────┐ ┌───────────────────┐ │ -│ │ 版本验证 API │ │ 补丁包存储 │ │ UpgradeHub (推送) │ │ -│ │ /Verification│ │ /patch/*.zip │ │ SignalR Hub │ │ -│ └─────────────┘ └──────────────┘ └───────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ 客户端 (Client Process) │ -│ ┌──────────────────────────────────────────────────────┐ │ -│ │ GeneralUpdate.ClientCore │ │ -│ │ ┌──────────┐ ┌──────────┐ ┌────────────────────┐ │ │ -│ │ │ 版本检查 │ │ 下载管理 │ │ 事件通知/预检回调 │ │ │ -│ │ └──────────┘ └──────────┘ └────────────────────┘ │ │ -│ └──────────────────────────────────────────────────────┘ │ -│ │ │ -│ IPC (AES 加密参数传递) │ -│ ▼ │ -└─────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ 升级助手 (Upgrade Process) │ -│ ┌──────────────────────────────────────────────────────┐ │ -│ │ GeneralUpdate.Core │ │ -│ │ ┌────────────────────────────────────────────────┐ │ │ -│ │ │ Pipeline (中间件管道) │ │ │ -│ │ │ HashMiddleware → CompressMiddleware → │ │ │ -│ │ │ PatchMiddleware → DrivelutionMiddleware │ │ │ -│ │ └────────────────────────────────────────────────┘ │ │ -│ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ -│ │ │ 文件替换 │ │ 差分包应用│ │ 驱动更新 │ │ │ -│ │ └──────────┘ └──────────┘ └──────────────────┘ │ │ -│ └──────────────────────────────────────────────────────┘ │ -│ │ │ -│ 启动主程序 + Bowl 监控 │ -└─────────────────────────────────────────────────────────────┘ -``` - ---- - -## 组件关系 - -### 核心组件 - -| 组件 | NuGet 包 | 运行位置 | 职责 | -|------|----------|----------|------| -| **GeneralUpdate.ClientCore** | `GeneralUpdate.ClientCore` | 主程序进程 | 版本检查、下载管理、启动升级助手 | -| **GeneralUpdate.Core** | `GeneralUpdate.Core` | 独立升级进程 | 文件替换、差分包应用、驱动更新 | -| **GeneralUpdate.Differential** | `GeneralUpdate.Core` (内含) | 两个进程均可 | 二进制差分算法 (BSDiff/HDiffPatch) | -| **GeneralUpdate.Bowl** | `GeneralUpdate.Bowl` | 独立监控进程 | 崩溃监控、Dump 生成、诊断信息收集 | -| **GeneralUpdate.Drivelution** | `GeneralUpdate.Drivelution` | 升级进程 | 跨平台驱动更新 | -| **GeneralUpdate.Extension** | `GeneralUpdate.Extension` | 主程序进程 | 插件/扩展管理系统 | -| **GeneralUpdate.Tools** | 独立桌面应用 | 开发工具 | 补丁包构建、模拟更新、配置生成 | - -### 组件依赖关系 - -``` -GeneralUpdate.Tools ──→ GeneralUpdate.Core (DiffPipeline) - │ - ┌────────────┼────────────┐ - ▼ ▼ ▼ - GeneralUpdate GeneralUpdate GeneralUpdate - .Differential .Drivelution .Extension - │ - ▼ - GeneralUpdate.Core (Bootstrap, Pipeline, Download, Security) - │ - ▼ - GeneralUpdate.ClientCore (Client Bootstrap, Hub Service) - │ - ▼ - GeneralUpdate.Bowl (进程监控) -``` - ---- - -## 更新流程详解 - -### 完整更新时序 - -``` - 客户端 (Client) 服务端 (Server) 升级助手 (Upgrade) - ───────────── ──────────── ───────────────── - │ │ │ - │ 1. POST /Verification │ │ - │ ─────────────────────► │ │ - │ │ │ - │ 2. 返回版本列表 │ │ - │ ◄───────────────────── │ │ - │ │ │ - │ 3. 用户确认更新 │ │ - │ (AddListenerUpdatePrecheck) │ - │ │ │ - │ 4. GET /patch/v2.0.0 │ │ - │ ─────────────────────► │ │ - │ │ │ - │ 5. 下载补丁包 (.zip) │ │ - │ ◄───────────────────── │ │ - │ │ │ - │ 6. 下载完成，退出主程序│ │ - │ │ │ - │ 7. 启动升级助手 (IPC) │ │ - │ ──────────────────────────────────────────────► │ - │ │ │ - │ │ 8. 读取 IPC 参数 │ - │ │ 9. 验证 Hash │ - │ │ 10. 解压补丁包 │ - │ │ 11. 应用差分补丁 │ - │ │ 12. 安装驱动(可选) │ - │ │ 13. 替换文件 │ - │ │ │ - │ │ 14. 启动新版主程序 │ - │ ◄────────────────────────────────────────────── │ - │ │ │ - │ 15. POST /Report │ │ - │ ─────────────────────► │ │ - │ │ │ -``` - -### 阶段说明 - -#### 阶段 1：版本验证 (Version Verification) - -客户端向服务端发送当前版本信息，服务端返回可用的更新版本列表。 - -**请求：** -```json -POST /Upgrade/Verification -{ - "AppSecretKey": "your-secret-key", - "ClientVersion": "1.0.0.0", - "ProductId": "2d974e2a-31e6-4887-9bb1-b4689e98c77a" -} -``` - -**响应：** -```json -{ - "Code": 200, - "Body": [ - { - "Version": "1.0.1.0", - "Hash": "abc123...", - "UpdateLog": "修复了若干Bug", - "IsForcibly": false, - "ReleaseDate": "2025-06-01" - } - ] -} -``` - -#### 阶段 2：下载更新包 (Download) - -客户端根据版本列表下载更新包。支持： -- **多版本串行/并行下载**：多个版本可同时下载 -- **断点续传**：下载中断后从断点继续 -- **SHA256 校验**：下载完成后自动校验完整性 - -#### 阶段 3：IPC 参数传递 - -客户端将更新配置（版本列表、安装路径、文件格式、编码等）通过 AES-CBC 加密写入临时文件，升级助手通过环境变量定位并解密读取。 - -**IPC 数据流：** -``` -Client 写入: ProcessContract → JSON 序列化 → AES-256-CBC 加密 → 临时文件 - ↓ -Upgrade 读取: 临时文件 → AES-256-CBC 解密 → JSON 反序列化 → ProcessContract -``` - -#### 阶段 4：Pipeline 执行 - -升级助手通过中间件管道依次处理下载的更新包： - -1. **HashMiddleware** — SHA256 哈希校验 -2. **CompressMiddleware** — 解压 ZIP 更新包 -3. **PatchMiddleware** — 应用二进制差分补丁 (可选) -4. **DrivelutionMiddleware** — 安装驱动程序 (可选) - -#### 阶段 5：启动新版本 - -升级完成后，升级助手启动新版本的主程序。如果配置了 Bowl，会同时启动 Bowl 进程监控新程序的运行状态。 - ---- - -## 更新模式 - -### 全量更新模式 - -当 `Patch` 选项设置为 `false` 时，执行全量更新： - -``` -下载完整包 → 解压 → 覆盖安装 -``` - -**适用场景：** -- 首次安装 -- 版本差异过大，增量包可能不划算 -- 不需要保留旧版本文件 - -### 增量/差分更新模式 (默认) - -当 `Patch` 选项设置为 `true` 时（默认），执行增量更新： - -``` -下载差分包 → 解压 → 应用 BSDiff 补丁 → 删除过期文件 -``` - -**差分包结构：** -``` -patch_v1.0.1.zip -├── file1.dll.patch ← 二进制差分补丁 -├── file2.exe.patch ← 二进制差分补丁 -├── newfile.dll ← 新增文件(原样包含) -├── delete_files.json ← 待删除文件列表 -└── ... -``` - -**差分包优势：** -- 补丁包体积通常仅为全量包的 5%-20% -- 下载速度快 5-20 倍 -- 节省带宽和存储成本 - -### OSS 更新模式 - -基于对象存储服务（如阿里云 OSS、AWS S3、MinIO）的更新模式： - -``` -客户端 → 读取 version.json → 对比版本 → 下载差分包 → 升级 -``` - -**version.json 格式：** -```json -{ - "Records": [ - { - "PacketName": "patch_v1.0.1.zip", - "Hash": "sha256:abc123...", - "Version": "1.0.1.0", - "Url": "https://oss.example.com/packages/patch_v1.0.1.zip", - "ReleaseDate": "2025-06-01T00:00:00" - } - ] -} -``` - -OSS 模式**不需要服务端 API**，只需将 `version.json` 和补丁包上传到对象存储即可。 - ---- - -## 平台策略 (Strategy Pattern) - -GeneralUpdate 通过策略模式适配不同操作系统： - -| 平台 | 策略类 | 特殊处理 | -|------|--------|----------| -| Windows | `WindowsStrategy` | Bowl 集成、文件权限、PnPUtil 驱动安装 | -| Linux | `LinuxStrategy` | chmod 权限脚本、无 Bowl 支持 | -| macOS | `MacStrategy` | chmod 权限脚本、`ConfigureAwait(false)` | - -每个策略类实现 `IStrategy` 接口，负责： -- `Create(UpdateContext)` — 创建策略实例 -- `ExecuteAsync()` — 执行更新（模板方法） -- `StartAppAsync()` — 启动更新后的应用程序 - ---- - -## 扩展点 (Extension Points) - -GeneralUpdate 通过 `AbstractBootstrap` 的 CRTP 模式提供丰富的扩展点： - -### 可替换组件 - -| 扩展点 | 接口 | 默认实现 | 用途 | -|--------|------|----------|------| -| **Strategy** | `IStrategy` | `WindowsStrategy`/`LinuxStrategy`/`MacStrategy` | 平台策略 | -| **Hooks** | `IUpdateHooks` | `NoOpUpdateHooks` | 更新生命周期钩子 | -| **SSL Policy** | `ISslValidationPolicy` | `StrictSslValidationPolicy` | SSL 证书验证策略 | -| **Download Policy** | `IDownloadPolicy` | `DefaultDownloadPolicy` | 下载重试/超时策略 | -| **Download Executor** | `IDownloadExecutor` | `HttpDownloadExecutor` | 下载协议执行器 | -| **Download Source** | `IDownloadSource` | 默认 HTTP 源 | 下载数据源 | -| **Download Pipeline** | `IDownloadPipeline` | 默认管道 | 下载后处理 | -| **Auth Provider** | `IHttpAuthProvider` | `NoOpAuthProvider` | HTTP 认证提供者 | -| **Download Orchestrator** | `IDownloadOrchestrator` | `DefaultDownloadOrchestrator` | 批量下载调度器 | -| **Update Reporter** | `IUpdateReporter` | 默认上报器 | 更新状态上报 | - -### 扩展注册示例 - -```csharp -await new GeneralClientBootstrap() - // 自定义 SSL 验证策略 - .SslPolicy() - // 自定义下载重试策略 - .DownloadPolicy() - // 自定义认证提供者 - .HttpAuth() - // 生命周期钩子 - .Hooks() - .SetConfig(config) - .LaunchAsync(); -``` - ---- - -## 安全架构 - -### 多层安全机制 - -``` -┌─────────────────────────────────────────┐ -│ 传输安全 (HTTPS/TLS) │ -│ ┌─────────────────────────────────────┐│ -│ │ 身份认证 (Token/Scheme) ││ -│ │ ┌─────────────────────────────────┐││ -│ │ │ 数据完整性 (SHA256 哈希) │││ -│ │ │ ┌─────────────────────────────┐│││ -│ │ │ │ IPC 加密 (AES-256-CBC) ││││ -│ │ │ │ ┌─────────────────────────┐││││ -│ │ │ │ │ 文件校验 (签名/哈希) │││││ -│ │ │ │ └─────────────────────────┘││││ -│ │ │ └─────────────────────────────┘│││ -│ │ └─────────────────────────────────┘││ -│ └─────────────────────────────────────┘│ -└─────────────────────────────────────────┘ -``` - -详细的安全机制请参考 [安全指南](./Security.md)。 - ---- - -## 相关资源 - -- **[Pipeline 详解](./Pipeline.md)** — 中间件管道工作原理 -- **[配置参考](./Configuration.md)** — 完整配置选项 -- **[安全指南](./Security.md)** — 安全架构详解 -- **[快速入门](../quickstart/Quik start)** — 5 分钟快速上手 diff --git a/website/docs/guide/Configuration.md b/website/docs/guide/Configuration.md deleted file mode 100644 index 0f18904..0000000 --- a/website/docs/guide/Configuration.md +++ /dev/null @@ -1,530 +0,0 @@ ---- -sidebar_position: 2 ---- - -# 配置参考 - -本文档完整列出 GeneralUpdate 框架中所有可配置项、选项枚举和配置类。 - ---- - -## 一、ClientCore 配置 - -### Configinfo 类 - -客户端更新的核心配置类。 - -**命名空间：** `GeneralUpdate.Common.Shared.Object` - -```csharp -public class Configinfo -{ - /// 更新检查 API 地址 - public string UpdateUrl { get; set; } - - /// 更新状态报告 API 地址 - public string ReportUrl { get; set; } - - /// 需要启动的应用程序名称（升级程序） - public string AppName { get; set; } - - /// 需要启动的主应用程序名称 - public string MainAppName { get; set; } - - /// 更新日志网页地址 - public string UpdateLogUrl { get; set; } - - /// 应用密钥，与服务器约定用于身份验证和产品分支 - public string AppSecretKey { get; set; } - - /// 当前客户端版本号 - public string ClientVersion { get; set; } - - /// 当前升级客户端版本号 - public string UpgradeClientVersion { get; set; } - - /// 安装路径（用于更新文件逻辑） - public string InstallPath { get; set; } - - /// 黑名单文件列表 - public List BlackFiles { get; set; } - - /// 黑名单文件格式列表 - public List BlackFormats { get; set; } - - /// 需要跳过的目录路径列表 - public List SkipDirectorys { get; set; } - - /// 当前产品分支的唯一 ID - public string ProductId { get; set; } - - /// Bowl 监控进程路径 - public string Bowl { get; set; } - - /// HTTP 请求中用于传递 Token 的 Scheme（如 Bearer） - public string Scheme { get; set; } - - /// HTTP 请求中用于身份验证的 Token - public string Token { get; set; } - - /// Linux 平台下的权限脚本 - public string Script { get; set; } - - /// 驱动程序目录路径 - public string DriverDirectory { get; set; } -} -``` - -### ConfiginfoBuilder 零配置构建器 - -**命名空间：** `GeneralUpdate.Common.Shared.Object` - -从 `.csproj` 自动提取应用名称、版本号和发布者信息。 - -```csharp -// 最简配置：仅需 UpdateUrl、Token、Scheme -var config = ConfiginfoBuilder - .Create("https://api.example.com/updates", "your-token", "Bearer") - .Build(); - -// 自动提取规则 -// AssemblyName → AppName / MainAppName -// Version → ClientVersion / UpgradeClientVersion -// Company → ProductId -``` - -**可选覆盖方法：** - -| 方法 | 说明 | -|------|------| -| `SetAppName(string)` | 覆盖自动检测的 AppName | -| `SetClientVersion(string)` | 覆盖自动检测的 ClientVersion | -| `SetInstallPath(string)` | 覆盖自动检测的 InstallPath | - ---- - -## 二、UpdateOption 枚举 - -**命名空间：** `GeneralUpdate.Common.Internal` - -```csharp -public enum UpdateOption -{ - /// 更新包文件格式（默认为 Zip） - Format, - - /// 压缩编码格式 - Encoding, - - /// 下载超时时间（秒）。默认 30 秒 - DownloadTimeOut, - - /// 是否启用二进制差异更新。默认开启 - Patch, - - /// 是否在更新前启用备份功能。默认开启 - BackUp, - - /// 是否启用静默更新模式 - EnableSilentUpdate -} -``` - -### 使用示例 - -```csharp -await new GeneralClientBootstrap() - .Option(UpdateOption.DownloadTimeOut, 60) // 下载超时 60 秒 - .Option(UpdateOption.Encoding, Encoding.UTF8) // UTF-8 编码 - .Option(UpdateOption.Patch, true) // 启用差异更新 - .Option(UpdateOption.BackUp, true) // 启用备份 - .Option(UpdateOption.EnableSilentUpdate, true)// 启用静默更新 - .SetConfig(config) - .LaunchAsync(); -``` - ---- - -## 三、全局 Option 配置 - -**命名空间：** `GeneralUpdate.Common.Internal.Bootstrap` - -通过 `Option` 类的静态属性访问全局配置： - -```csharp -public class Option -{ - /// 应用类型：Client / Upgrade / OssClient / OssUpgrade - public static Option AppType { get; } - - /// 差分模式：Serial / Parallel - public static Option DiffMode { get; } - - /// 编码格式 - public static Option Encoding { get; } - - /// 压缩格式（目前仅 Zip） - public static Option Format { get; } - - /// 下载超时时间（秒） - public static Option DownloadTimeout { get; } - - /// 是否启用差分包 - public static Option PatchEnabled { get; } - - /// 是否启用备份 - public static Option BackupEnabled { get; } - - /// 是否启用静默更新 - public static Option Silent { get; } - - /// 静默更新轮询间隔（分钟），默认 20 - public static Option SilentPollIntervalMinutes { get; } - - /// 更新完成后是否启动客户端 - public static Option LaunchClientAfterUpdate { get; } - - /// 最大并发下载数 - public static Option MaxConcurrency { get; } - - /// 是否启用断点续传 - public static Option EnableResume { get; } - - /// 下载重试次数 - public static Option RetryCount { get; } - - /// 是否校验 SHA256 - public static Option VerifyChecksum { get; } - - /// 重试间隔（秒） - public static Option RetryInterval { get; } -} -``` - -### 全局配置使用 - -```csharp -// 设置全局配置 -Option.AppType.SetValue(AppType.Client); -Option.DownloadTimeout.SetValue(120); -Option.PatchEnabled.SetValue(true); -Option.MaxConcurrency.SetValue(5); -Option.RetryCount.SetValue(3); -``` - ---- - -## 四、AppType 枚举 - -```csharp -public enum AppType -{ - /// 标准客户端模式（需要服务端 API） - Client, - - /// 标准升级模式（需要服务端 API） - Upgrade, - - /// OSS 客户端模式（使用对象存储） - OssClient, - - /// OSS 升级模式（使用对象存储） - OssUpgrade -} -``` - ---- - -## 五、DiffMode 枚举 - -```csharp -public enum DiffMode -{ - /// 串行模式：逐个处理文件差分 - Serial, - - /// 并行模式：并发处理文件差分 - Parallel -} -``` - ---- - -## 六、Format 枚举 - -```csharp -public enum Format -{ - /// ZIP 压缩格式（目前唯一支持） - Zip -} -``` - ---- - -## 七、PlatformType 枚举 - -```csharp -public enum PlatformType -{ - Unknown, - Windows, - Linux, - MacOS -} -``` - ---- - -## 八、ReportType 常量 - -```csharp -public static class ReportType -{ - public const int None = 0; // 不报告 - public const int Success = 2; // 更新成功 - public const int Failure = 3; // 更新失败 -} -``` - ---- - -## 九、服务端 API 规范 - -### 版本验证接口 - -``` -POST /Upgrade/Verification -Content-Type: application/json - -Request: -{ - "AppSecretKey": "string", // 应用密钥 - "ClientVersion": "string", // 客户端版本号 - "ProductId": "string", // 产品分支 ID - "ClientType": 1 // 客户端类型：1=Client, 2=Upgrade -} - -Response: -{ - "Code": 200, - "Body": [ - { - "Version": "1.0.1.0", - "Hash": "sha256:abc123...", - "UpdateLog": "本次更新内容...", - "IsForcibly": false, - "ReleaseDate": "2025-06-01T00:00:00", - "Size": 1048576, - "Url": "/patch/patch_v1.0.1.zip" - } - ] -} -``` - -### 状态上报接口 - -``` -POST /Upgrade/Report -Content-Type: application/json - -Request: -{ - "AppSecretKey": "string", - "ClientVersion": "string", - "ReportType": 2, // 2=成功, 3=失败 - "ProductId": "string" -} -``` - -### 补丁包下载 - -``` -GET /patch/{filename} - -Response: application/octet-stream (补丁包 .zip 文件) -``` - ---- - -## 十、Bowl 配置 - -### MonitorParameter 类 - -```csharp -public class MonitorParameter -{ - /// 被监控的目录 - public string TargetPath { get; set; } - - /// 导出异常信息的目录 - public string FailDirectory { get; set; } - - /// 备份目录 - public string BackupDirectory { get; set; } - - /// 被监控进程的名称或 ID - public string ProcessNameOrId { get; set; } - - /// Dump 文件名 - public string DumpFileName { get; set; } - - /// 升级包版本信息（.json）文件名 - public string FailFileName { get; set; } - - /// 工作模式："Upgrade" 或 "Normal" - public string WorkModel { get; set; } = "Upgrade"; -} -``` - -### DumpType 枚举 - -```csharp -public enum DumpType -{ - Full = 0, // 完整转储 - Mini = 1, // 迷你转储 - Heap = 2 // 堆转储 -} -``` - ---- - -## 十一、Extension 配置 - -### ExtensionHostOptions - -```csharp -public class ExtensionHostOptions -{ - /// 扩展服务 API 地址 - public string ServerUrl { get; set; } - - /// 认证 Scheme - public string Scheme { get; set; } - - /// 认证 Token - public string Token { get; set; } - - /// 主机应用版本号 - public string HostVersion { get; set; } - - /// 扩展安装目录 - public string ExtensionsDirectory { get; set; } - - /// 扩展编目文件路径 - public string CatalogPath { get; set; } -} -``` - ---- - -## 十二、Drivelution 配置 - -### DrivelutionOptions - -```csharp -public class DrivelutionOptions -{ - /// 默认备份路径 - public string DefaultBackupPath { get; set; } - - /// 默认重试次数 - public int DefaultRetryCount { get; set; } = 3; - - /// 默认重试间隔（秒） - public int DefaultRetryIntervalSeconds { get; set; } = 5; - - /// 默认超时时间（秒） - public int DefaultTimeoutSeconds { get; set; } = 300; - - /// 调试模式：跳过签名验证 - public bool DebugModeSkipSignature { get; set; } - - /// 调试模式：跳过哈希验证 - public bool DebugModeSkipHash { get; set; } - - /// 权限失败时强制终止 - public bool ForceTerminateOnPermissionFailure { get; set; } - - /// 自动清理旧备份 - public bool AutoCleanupBackups { get; set; } = true; - - /// 保留的备份数量 - public int BackupsToKeep { get; set; } = 5; - - /// 使用指数退避重试 - public bool UseExponentialBackoff { get; set; } = true; - - /// 受信任的证书指纹列表 - public List TrustedCertificateThumbprints { get; set; } -} -``` - ---- - -## 十三、Blacklist (黑名单) 配置 - -### BlackPolicy - -```csharp -public record BlackPolicy -{ - /// 黑名单文件列表 - public List Files { get; init; } - - /// 黑名单格式列表（如 .log, .cache） - public List Formats { get; init; } - - /// 黑名单目录列表 - public List Directories { get; init; } - - /// 是否有黑名单规则 - public bool HasRules { get; } -} -``` - -### 默认黑名单 - -| 类型 | 默认值 | -|------|--------| -| 文件 | `System.*.dll` | -| 格式 | `.patch`, `.pdb`, `.rar`, `.tar`, `.json`, `.zip` | -| 目录 | `app-`, `fail` | - ---- - -## 十四、manifest.json 格式 - -客户端自动读取的清单文件 `generalupdate.manifest.json`： - -```json -{ - "MainAppName": "MyApp.exe", - "ClientVersion": "1.0.0.0", - "AppType": "Client", - "UpdateAppName": "UpgradeSample.exe", - "UpgradeClientVersion": "1.0.0.0", - "ProductId": "2d974e2a-31e6-4887-9bb1-b4689e98c77a", - "UpdatePath": "" -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `MainAppName` | string | 主应用名称 | -| `ClientVersion` | string | 客户端当前版本 | -| `AppType` | string | 应用类型 | -| `UpdateAppName` | string | 升级助手应用名称 | -| `UpgradeClientVersion` | string | 升级助手当前版本 | -| `ProductId` | string | 产品/分支 ID | -| `UpdatePath` | string | 自定义更新路径 | - ---- - -## 相关资源 - -- **[系统架构](./Architecture.md)** — 了解整体架构 -- **[Pipeline 详解](./Pipeline.md)** — 中间件管道工作原理 -- **[安全指南](./Security.md)** — 安全配置 -- **[GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool)** — 配置生成工具 diff --git a/website/docs/guide/Driver.md b/website/docs/guide/Driver.md deleted file mode 100644 index 8d147e4..0000000 --- a/website/docs/guide/Driver.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -sidebar_position: 3 ---- - -### Driver - -#### (1) Windows Platform - -##### Driver Installation - -The tool used for driver installation in this component is the Microsoft built-in tool PnPutil.exe or setupapi.dll. - -There are two key points to note when installing drivers: - -| Name | Description | -| ------- | ------------------------------------------------------------ | -| Install | Driver certificate installation should occur before the driver installation. | -| Version | Differentiate between x86 and x64 versions. | - -**PnPUtil Implementation:** - -PnPUtil is a command line utility that can be used to manage the Windows driver store. You can use it to add, delete, and list drivers. - -Here are the steps to install drivers using PnPUtil: - -1. Open Command Prompt as an administrator. - -2. Navigate to the directory containing the driver's INF file. - -3. Run the following command: - - `pnputil /add-driver ` - - For example, if your INF file name is `mydriver.inf`, you should run `pnputil /add-driver mydriver.inf`. - -4. PnPUtil will add the driver to the driver store and attempt to install the driver for any matching devices. - -Note that PnPUtil requires administrator privileges to run. - -In C#, you can use the System.Diagnostics.Process class to run PnPUtil. Here is an example: - -```c# -using System.Diagnostics; - -public class Program -{ - public static void Main() - { - string infPath = "Path to your INF file"; - - Process process = new Process(); - process.StartInfo.FileName = "pnputil.exe"; - process.StartInfo.Arguments = "/add-driver " + infPath; - process.StartInfo.Verb = "runas"; // Run as administrator - process.Start(); - - process.WaitForExit(); - } -} -``` - -**setupapi.dll Implementation:** - -```c# -using System; -using System.Runtime.InteropServices; - -public class Program -{ - // Define the P/Invoke signature for the SetupCopyOEMInf function - [DllImport("setupapi.dll", EntryPoint = "SetupCopyOEMInf", SetLastError = true)] - public static extern bool SetupCopyOEMInf( - string SourceInfFileName, - string OEMSourceMediaLocation, - int OEMSourceMediaType, - int CopyStyle, - string DestinationInfFileName, - int DestinationInfFileNameSize, - ref int RequiredSize, - string DestinationInfFileNameComponent - ); - - public static void Main() - { - string infPath = "Path to your INF file"; - bool result = SetupCopyOEMInf(infPath, null, 0, 0, null, 0, ref int size, null); - - if (!result) - { - Console.WriteLine("Failed to install driver. Error code: " + Marshal.GetLastWin32Error()); - } - } -} -``` - -##### Driver Certificate - -This component uses Windows certificate management tools (CertMgr.exe) or the X509Store class in the .NET framework. - -**CertMgr.exe Implementation:** - -`CertMgr.exe` is a command line tool that is part of the Microsoft .NET Framework. You can find it in the .NET Framework installation directory. - -For most systems, it is typically located in one of the following directories: - -- `C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Bin` -- `C:\Program Files\Microsoft SDKs\Windows\v7.0A\Bin` - -If you cannot find it, you can use Windows search to locate `CertMgr.exe`. - -Note that `CertMgr.exe` is a command line tool and must be run in Command Prompt or PowerShell. You can also call it in your C# code using the `System.Diagnostics.Process.Start()` method. - -**X509Store Implementation:** - -```c# -using System; -using System.Security.Cryptography.X509Certificates; - -public class Example -{ - public static void Main() - { - string CertificatePath = "Path to your certificate file"; - - // Create a new X509 certificate instance - X509Certificate2 certificate = new X509Certificate2(CertificatePath); - - // Open the current user's personal certificate store - X509Store store = new X509Store(StoreName.My, StoreLocation.CurrentUser); - - // Add the new certificate to the store - store.Open(OpenFlags.ReadWrite); - store.Add(certificate); - - store.Close(); - } -} -``` - diff --git a/website/docs/guide/FAQ.md b/website/docs/guide/FAQ.md index cdeff6f..096cdf3 100644 --- a/website/docs/guide/FAQ.md +++ b/website/docs/guide/FAQ.md @@ -332,7 +332,7 @@ await new GeneralClientBootstrap() ## 相关资源 -- **[系统架构](./Architecture.md)** — 了解整体架构 -- **[配置参考](./Configuration.md)** — 所有配置项 -- **[Pipeline 详解](./Pipeline.md)** — 中间件管道 -- **[安全指南](./Security.md)** — 安全最佳实践 +- **[GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)** — 核心更新引擎 +- **[入门实战手册](../quickstart/Beginner%20cookbook.md)** — 从零跑通更新闭环 +- **[GeneralUpdate.Tools](../quickstart/GeneralUpdate.PacketTool.md)** — 打包工具 +- **[GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl.md)** — 崩溃监控与回滚 diff --git a/website/docs/guide/Pipeline.md b/website/docs/guide/Pipeline.md deleted file mode 100644 index 956f919..0000000 --- a/website/docs/guide/Pipeline.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Pipeline 中间件管道 - -## 概述 - -GeneralUpdate 采用**中间件管道模式 (Middleware Pipeline Pattern)** 来处理更新包。每个下载完成的更新包都会依次经过管道中的各个中间件处理——从哈希校验到解压、差分包应用到驱动安装。 - -该模式的核心优势在于**关注点分离**和**可扩展性**：每个中间件只负责一个独立任务，开发者可以轻松添加自定义中间件。 - ---- - -## 管道架构 - -``` -下载完成 (.zip) - │ - ▼ -┌─────────────────┐ -│ HashMiddleware │ ← SHA256 哈希校验 -└────────┬────────┘ - │ 通过 - ▼ -┌─────────────────┐ -│CompressMiddleware│ ← 解压 ZIP 到目标路径 -└────────┬────────┘ - │ - ▼ -┌─────────────────┐ -│ PatchMiddleware │ ← 应用 BSDiff 差分包 (可选) -└────────┬────────┘ - │ - ▼ -┌─────────────────────┐ -│DrivelutionMiddleware│ ← 安装驱动程序 (可选) -└────────┬────────────┘ - │ - ▼ - 升级完成 -``` - ---- - -## 核心接口 - -### IMiddleware - -所有中间件必须实现的基础接口： - -```csharp -public interface IMiddleware -{ - /// - /// 执行中间件逻辑 - /// - /// 管道上下文，携带当前管道的所有状态 - Task InvokeAsync(PipelineContext context); -} -``` - -### PipelineBuilder - -不可变管道构建器，按 FIFO（先进先出）顺序执行中间件： - -```csharp -public class PipelineBuilder -{ - /// 注册中间件 - public PipelineBuilder UseMiddleware() where T : IMiddleware; - - /// 条件注册中间件 - public PipelineBuilder UseMiddlewareIf(bool? condition) where T : IMiddleware; - - /// 构建并执行管道 - public async Task Build(PipelineContext context); -} -``` - -### PipelineContext - -线程安全的键值存储，在中间件之间传递状态： - -```csharp -public class PipelineContext -{ - // 预定义的上下文键 - public const string Hash = "Hash"; // 期望的 SHA256 哈希值 - public const string Format = "Format"; // 压缩格式 - public const string Encoding = "Encoding"; // 编码 - public const string ZipFilePath = "ZipFilePath"; // 下载的 ZIP 文件路径 - public const string SourcePath = "SourcePath"; // 解压目标路径 - public const string PatchPath = "PatchPath"; // 差分解压路径 - public const string PatchEnabled = "PatchEnabled"; // 是否启用差分包 - public const string DiffPipeline = "DiffPipeline"; // 差分管道实例 -} -``` - ---- - -## 内置中间件详解 - -### 1. HashMiddleware — SHA256 哈希校验 - -**位置：** `GeneralUpdate.Core.Pipeline.HashMiddleware` - -**职责：** 对下载完成的 ZIP 更新包执行 SHA256 哈希校验，确保文件完整性。 - -**处理流程：** -``` -1. 从 PipelineContext 读取 "Hash" 和 "ZipFilePath" -2. 计算 ZIP 文件的 SHA256 哈希 -3. 与期望的哈希值比对 -4. 不匹配 → 抛出 CryptographicException -5. 匹配 → 传递给下一个中间件 -``` - -**错误处理：** -- 哈希不匹配时抛出 `CryptographicException` -- 上游调用方（`AbstractStrategy`）会捕获并触发错误回调 - ---- - -### 2. CompressMiddleware — 解压处理 - -**位置：** `GeneralUpdate.Core.Pipeline.CompressMiddleware` - -**职责：** 将 ZIP 格式的更新包解压到目标目录。 - -**处理流程：** -``` -1. 从 PipelineContext 读取压缩格式和路径信息 -2. 如果 PatchEnabled = true： - → 解压到 PatchPath（后续由 PatchMiddleware 处理） -3. 如果 PatchEnabled = false： - → 解压到 SourcePath（直接覆盖安装） -4. 使用 System.IO.Compression.ZipFile 解压 -``` - -**路径策略：** - -| PatchEnabled | 解压目标 | 后续处理 | -|-------------|----------|----------| -| `true` | `PatchPath`（临时目录） | PatchMiddleware 应用差分 | -| `false` | `SourcePath`（安装目录） | 直接完成，全量覆盖 | - ---- - -### 3. PatchMiddleware — 差分包应用 - -**位置：** `GeneralUpdate.Core.Pipeline.PatchMiddleware` - -**职责：** 将二进制差分补丁应用到当前安装的文件上。 - -**处理流程：** -``` -1. 检查 PipelineContext 中是否存在 "DiffPipeline" -2. 如果不存在 → 跳过（全量更新模式） -3. 如果存在 → - a. 调用 DiffPipeline.DirtyAsync() 应用补丁 - b. 处理 .patch 文件 → BSDiff/HdiffPatch 还原 - c. 复制新增文件到目标目录 - d. 根据 delete_files.json 删除过期文件 -4. 报告差分进度（通过 DiffProgressReporter） -``` - -**差分包目录结构：** -``` -PatchPath/ -├── MyApp.Core.dll.patch ← BSDiff 格式的二进制补丁 -├── MyApp.UI.exe.patch ← BSDiff 格式的二进制补丁 -├── NewFeature.dll ← 新增文件（非补丁，直接复制） -├── config/new_config.json ← 新增文件 -└── delete_files.json ← 待删除文件清单 -``` - -**delete_files.json 格式：** -```json -{ - "DeletedFiles": [ - "old_module.dll", - "deprecated/old_feature.exe" - ] -} -``` - ---- - -### 4. DrivelutionMiddleware — 驱动更新 - -**位置：** `GeneralUpdate.Core.Pipeline.DrivelutionMiddleware` - -**职责：** 在文件更新完成后，处理驱动程序更新。 - -**触发条件：** -- `PipelineContext` 中 `DriverDirectory` 不为空 -- 平台为 Windows 或 Linux - -**处理流程：** -``` -1. 扫描 DriverDirectory 中的驱动文件 -2. 调用 GeneralDrivelution 执行驱动更新管道： - Validate → Backup → Install → Verify -3. 错误时自动回滚 -``` - ---- - -## 管道构建 - -### 默认管道构建 - -在 `AbstractStrategy` 的子类中构建： - -```csharp -// WindowsStrategy / LinuxStrategy / MacStrategy 中的 BuildPipeline -protected override PipelineBuilder BuildPipeline(PipelineContext context) -{ - return new PipelineBuilder() - .UseMiddleware() // 步骤 1：哈希校验 - .UseMiddleware() // 步骤 2：解压 - .UseMiddlewareIf( // 步骤 3：差分包（条件） - context.Get(PipelineContext.PatchEnabled)) - .UseMiddlewareIf(// 步骤 4：驱动（条件） - !string.IsNullOrEmpty(context.Get("DriverDirectory"))); -} -``` - -### 自定义管道 - -开发者可以通过 `AbstractBootstrap` 的方法注入自定义中间件： - -```csharp -await new GeneralUpdateBootstrap() - .SetConfig(config) - // 注入自定义下载管道处理 - .DownloadPipeline() - .LaunchAsync(); -``` - ---- - -## 差分管道 (DiffPipeline) - -差分管道是在 `PatchMiddleware` 内部运行的子管道，专门处理二进制差分算法。 - -### 核心接口 - -```csharp -public interface IBinaryDiffer -{ - /// 应用补丁（客户端）：oldFile + patchFile → newFile - Task DirtyAsync(string oldFilePath, string newFilePath, - string patchFilePath, CancellationToken ct = default); - - /// 生成补丁（服务端/工具）：oldFile + newFile → patchFile - Task CleanAsync(string oldFilePath, string newFilePath, - string patchFilePath, CancellationToken ct = default); -} -``` - -### 差分算法 - -| 算法 | 实现类 | 特点 | -|------|--------|------| -| **BSDiff 4.0** | `BsdiffDiffer` | O(n log n) 后缀数组，高压缩比 | -| **Streaming Hdiff** | `StreamingHdiffDiffer` | FNV-1a 哈希预过滤，支持大文件流式处理 | - -### 压缩格式 - -差分补丁的元数据可以用不同算法压缩： - -| 压缩器 | FormatVersion | 兼容性 | -|--------|---------------|--------| -| **BZip2** | `0x00` | 传统 BSDiff 兼容，所有平台 | -| **Deflate** | `0x01` | .NET BCL DeflateStream，更快 | -| **Brotli** | `0x02` | .NET 6+ BrotliStream，最高压缩比 | - -### 差分匹配器 - -控制哪些文件需要差分处理： - -```csharp -// 客户端（应用补丁）— 决定哪些文件需要差分 -public interface IDirtyMatcher -{ - Task ShouldDirty(string relativeFilePath); -} - -// 服务端（生成补丁）— 决定哪些文件需要生成差分 -public interface ICleanMatcher -{ - Task ShouldClean(string relativeFilePath); -} -``` - ---- - -## 进度报告 - -### DiffProgressReporter - -桥接差分管道进度到事件系统： - -```csharp -public class DiffProgressReporter : IProgress -{ - public void Report(DiffProgress value) - { - EventManager.Instance.Dispatch(new ProgressEventArgs - { - Progress = new ProgressInfo { Diff = value } - }); - } -} -``` - -客户端通过事件监听差分进度： - -```csharp -await new GeneralClientBootstrap() - .AddListenerProgress((sender, args) => - { - if (args.Progress.Diff != null) - { - Console.WriteLine($"差分进度: {args.Progress.Diff.Percentage}%"); - } - }) - .SetConfig(config) - .LaunchAsync(); -``` - ---- - -## 管道执行流程 - -### 完整执行代码路径 - -``` -GeneralUpdateBootstrap.LaunchAsync() - → IStrategy.ExecuteAsync() - → AbstractStrategy.ExecuteAsync() - → 遍历每个需要更新的版本 - → CreatePipelineContext(version) - → BuildPipeline(context) - → pipeline.Build(context) ← 执行所有中间件 - → OnExecuteCompleteAsync() - → 所有版本处理完成 - → StartAppAsync() - → 启动新版本主程序 - → [可选] 启动 Bowl 监控 -``` - -### 错误处理与回滚 - -``` -中间件执行失败 - → AbstractStrategy.HandleExecuteException() - → 触发 Exception 事件 - → TryRollback() - → 从备份目录恢复文件 - → 清理临时文件 - → 上报失败状态 (ReportType.Failure) -``` - ---- - -## 自定义中间件示例 - -### 示例 1：文件扫描中间件 - -```csharp -public class FileScanMiddleware : IMiddleware -{ - public async Task InvokeAsync(PipelineContext context) - { - var sourcePath = context.Get(PipelineContext.SourcePath); - - // 扫描更新后的文件 - var files = Directory.GetFiles(sourcePath, "*.*", - SearchOption.AllDirectories); - - Console.WriteLine($"已更新 {files.Length} 个文件"); - - // 可在此添加病毒扫描、代码签名验证等逻辑 - } -} -``` - -### 示例 2：更新前后钩子中间件 - -```csharp -public class PrePostHookMiddleware : IMiddleware -{ - private readonly Action _onBefore; - private readonly Action _onAfter; - - public PrePostHookMiddleware(Action onBefore, Action onAfter) - { - _onBefore = onBefore; - _onAfter = onAfter; - } - - public async Task InvokeAsync(PipelineContext context) - { - var version = context.Get("Version"); - - _onBefore?.Invoke(version); - - // 执行完毕后的处理 - _onAfter?.Invoke(version); - } -} -``` - ---- - -## 相关资源 - -- **[系统架构](./Architecture.md)** — 了解整体架构与管道在其中的位置 -- **[GeneralUpdate.Differential](../doc/GeneralUpdate.Differential)** — BSDiff 差分算法详解 -- **[配置参考](./Configuration.md)** — 管道相关配置选项 diff --git a/website/docs/guide/Security.md b/website/docs/guide/Security.md deleted file mode 100644 index 5da6214..0000000 --- a/website/docs/guide/Security.md +++ /dev/null @@ -1,427 +0,0 @@ ---- -sidebar_position: 4 ---- - -# 安全指南 - -本文档详细说明 GeneralUpdate 框架的多层安全机制。 - ---- - -## 安全架构总览 - -GeneralUpdate 的安全体系采用**纵深防御 (Defense in Depth)** 策略，在传输、认证、数据完整性、进程间通信等层面建立多层防护。 - -``` -┌──────────────────────────────────────────────────┐ -│ 传输安全 (TLS) │ -│ ┌──────────────────────────────────────────────┐│ -│ │ 身份认证 (Token/Scheme) ││ -│ │ ┌──────────────────────────────────────────┐││ -│ │ │ 数据完整性 (SHA256 哈希) │││ -│ │ │ ┌──────────────────────────────────────┐│││ -│ │ │ │ IPC 加密 (AES-256-CBC) ││││ -│ │ │ │ ┌──────────────────────────────────┐││││ -│ │ │ │ │ 文件级校验 (签名/哈希) │││││ -│ │ │ │ └──────────────────────────────────┘││││ -│ │ │ └──────────────────────────────────────┘│││ -│ │ └──────────────────────────────────────────┘││ -│ └──────────────────────────────────────────────┘│ -└──────────────────────────────────────────────────┘ -``` - ---- - -## 一、传输安全 (TLS/SSL) - -### HTTPS 强制 - -GeneralUpdate 的 HTTP 客户端默认要求 HTTPS 连接。所有与服务端的通信（版本检查、下载、上报）都应通过 HTTPS 进行。 - -### SSL 证书验证策略 - -**接口：** `ISslValidationPolicy` - -```csharp -public interface ISslValidationPolicy -{ - bool ValidateCertificate( - X509Certificate2 certificate, - X509Chain chain, - SslPolicyErrors sslPolicyErrors); -} -``` - -**默认策略：** `StrictSslValidationPolicy` - -```csharp -public class StrictSslValidationPolicy : ISslValidationPolicy -{ - public bool ValidateCertificate(...) - { - // 任何 SSL 错误都拒绝连接 - return sslPolicyErrors == SslPolicyErrors.None; - } -} -``` - -**自定义 SSL 策略：** - -```csharp -// 开发环境：接受自签名证书 -public class DevelopmentSslPolicy : ISslValidationPolicy -{ - public bool ValidateCertificate( - X509Certificate2 certificate, - X509Chain chain, - SslPolicyErrors sslPolicyErrors) - { - // 仅在开发环境使用！ - return true; - } -} - -// 注册自定义策略 -await new GeneralClientBootstrap() - .SslPolicy() - .SetConfig(config) - .LaunchAsync(); -``` - -> **⚠️ 警告：** 切勿在生产环境禁用 SSL 验证！ - ---- - -## 二、身份认证 (Authentication) - -### HTTP 认证提供者 - -**接口：** `IHttpAuthProvider` - -```csharp -public interface IHttpAuthProvider -{ - Task ApplyAuthAsync(HttpRequestMessage request, - CancellationToken cancellationToken); -} -``` - -### 内置认证方案 - -#### 1. Bearer Token 认证 - -```csharp -// 客户端配置 -var config = new Configinfo -{ - Scheme = "Bearer", - Token = "your-access-token", - // ... -}; - -// 或者通过 AbstractBootstrap 注入 -await new GeneralClientBootstrap() - .HttpAuth() - .SetConfig(config) - .LaunchAsync(); -``` - -**HTTP 请求头：** -``` -Authorization: Bearer your-access-token -``` - -#### 2. API Key 认证 - -```csharp -public class ApiKeyAuthProvider : IHttpAuthProvider -{ - private readonly string _apiKey; - private readonly string _headerName; // 默认 "X-Api-Key" - - public ApiKeyAuthProvider(string apiKey, string headerName = "X-Api-Key") - { - _apiKey = apiKey; - _headerName = headerName; - } - - public Task ApplyAuthAsync(HttpRequestMessage request, - CancellationToken cancellationToken) - { - request.Headers.Add(_headerName, _apiKey); - return Task.CompletedTask; - } -} -``` - -**HTTP 请求头：** -``` -X-Api-Key: your-api-key -``` - -#### 3. HMAC 签名认证 - -```csharp -public class HmacAuthProvider : IHttpAuthProvider -{ - private readonly string _secretKey; - - public async Task ApplyAuthAsync(HttpRequestMessage request, - CancellationToken cancellationToken) - { - // 生成时间戳 - var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString(); - - // 读取请求体 - var body = request.Content != null - ? await request.Content.ReadAsStringAsync() - : string.Empty; - - // 计算 HMAC-SHA256 签名 - var payload = $"{body}|{timestamp}"; - var signature = ComputeHmacSha256(payload, _secretKey); - - // 添加请求头 - request.Headers.Add("X-Update-Timestamp", timestamp); - request.Headers.Add("X-Update-Signature", signature); - } - - private static string ComputeHmacSha256(string payload, string key) - { - using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(key)); - var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)); - return Convert.ToBase64String(hash); - } -} -``` - -**HTTP 请求头：** -``` -X-Update-Timestamp: 1717488000 -X-Update-Signature: base64_hmac_sha256_signature -``` - -#### 4. 无认证 (默认) - -```csharp -public class NoOpAuthProvider : IHttpAuthProvider -{ - public Task ApplyAuthAsync(HttpRequestMessage request, - CancellationToken cancellationToken) - { - return Task.CompletedTask; - } -} -``` - -### 工厂方法 - -```csharp -// 根据 Scheme 自动选择认证方案 -var authProvider = HttpAuthProviderFactory.Create( - scheme: "HMAC", - token: null, - secretKey: "your-secret-key"); -// → 返回 HmacAuthProvider 实例 -``` - -| Scheme | 创建的提供者 | -|--------|-------------| -| `"Bearer"` | `BearerTokenAuthProvider` | -| `"ApiKey"` | `ApiKeyAuthProvider` | -| `"HMAC"` | `HmacAuthProvider` | -| 其他 | `NoOpAuthProvider` | - ---- - -## 三、数据完整性 (Integrity) - -### SHA256 哈希校验 - -每个更新包下载完成后，管道中的 `HashMiddleware` 会自动计算并比对 SHA256 哈希值。 - -**流程：** -``` -1. 服务端返回版本信息时附带 Hash 字段 -2. 客户端下载更新包后，HashMiddleware 计算实际哈希 -3. 比对期望哈希 vs 实际哈希 -4. 不匹配 → CryptographicException → 回滚 + 上报失败 -``` - -**服务端哈希生成（GeneralUpdate.Tools）：** -``` -使用 Tools 的 OSS Config 模块 → 选择文件 → 计算哈希 → 填充到 version.json -``` - -### 差分补丁完整性 - -差分补丁本身也内嵌了完整性检查： -- BSDiff 格式包含控制区段的 CRC 校验 -- 补丁应用过程中任何数据损坏都会导致还原失败并回滚 - ---- - -## 四、IPC 进程间通信安全 - -ClientCore 与 Core 之间的参数传递通过 AES 加密的临时文件完成。 - -### 加密算法 - -| 参数 | 值 | -|------|-----| -| 算法 | AES-256-CBC | -| 密钥派生 | SHA256("GeneralUpdate.IPC.EnvironmentProvider.v1") | -| 密钥长度 | 256 bits | -| IV 长度 | 128 bits (CBC 模式) | -| 临时文件位置 | `%TEMP%/GeneralUpdate/ipc/` | -| 文件生命周期 | 写入 → 读取 → 自动删除 | - -### 环境变量传递 - -``` -ClientCore 写入: - 1. ProcessContract 对象 → JSON 序列化 - 2. JSON → AES-256-CBC 加密 - 3. 密文写入临时文件 → 路径写入环境变量 - -Core 读取: - 1. 从环境变量获取临时文件路径 - 2. 读取密文 → AES-256-CBC 解密 - 3. JSON 反序列化 → ProcessContract 对象 - 4. 自动删除临时文件 -``` - -### 安全考量 - -- 临时文件在 `%TEMP%` 目录中，文件名包含时间戳和 PID，难以猜测 -- 读取后立即删除，窗口期极短 -- AES-256-CBC 加密防止本地进程窃听 -- **局限性：** 固定密钥派生方式下，同一设备上运行的其他进程理论上可以解密。这是同机进程间通信的固有局限。 - -### 安全增强建议 - -对于高安全要求的场景： -1. 使用操作系统级别的安全 IPC 机制（如命名管道 + ACL） -2. 使用 DPAPI (Windows Data Protection API) 替代固定密钥 -3. 在 Linux 上使用 `shm_open` + 文件权限控制 - ---- - -## 五、备份与回滚 - -### 自动备份机制 - -更新前自动备份当前文件到备份目录： - -``` -{InstallPath}/ -├── app-1.0.0.0/ ← 备份目录（版本号命名） -│ ├── MyApp.exe -│ ├── MyApp.Core.dll -│ └── ... -├── app-1.0.1.0/ ← 另一个版本的备份 -└── MyApp.exe ← 当前运行的文件 -``` - -### 备份配置 - -```csharp -// 通过 UpdateOption 控制 -await new GeneralClientBootstrap() - .Option(UpdateOption.BackUp, true) // 启用自动备份 - .SetConfig(config) - .LaunchAsync(); -``` - -### 回滚触发条件 - -- 更新后主程序启动失败 -- 更新后 Bowl 检测到崩溃 -- 中间件执行异常 - -### 回滚流程 - -``` -1. 检测到故障 -2. 从备份目录恢复文件 -3. 清理临时文件和失败的更新 -4. 上报失败状态 (ReportType.Failure) -``` - -### 备份清理 - -```csharp -// StorageManager.CleanBackup 按版本号排序清理 -StorageManager.CleanBackup(installPath, keepVersions: 3); -// 保留最近 3 个版本的备份，删除更早的 -``` - ---- - -## 六、Bowl 进程安全监控 - -Bowl 在更新完成后监控新进程的运行状态： - -### 工作原理 - -``` -1. Bowl 使用 ProcDump（Windows）启动目标进程 -2. ProcDump 监控未处理异常 -3. 检测到崩溃： - a. 生成 Dump 文件（内存快照） - b. 导出驱动信息 (driverInfo.txt) - c. 导出系统信息 (systeminfo.txt) - d. 导出系统事件日志 (systemlog.evtx) - e. 生成崩溃报告 (fail.json) - f. 自动回滚到上一个版本 -``` - -### 安全注意事项 - -- Dump 文件包含完整内存快照，可能包含敏感信息（密钥、密码等） -- 确保 FailDirectory 的访问权限受限 -- 定期清理旧的 Dump 文件 - ---- - -## 七、API 安全最佳实践 - -### 服务端 - -1. **HTTPS 强制：** 所有 API 端点必须使用 HTTPS -2. **认证必须：** 使用 Token/HMAC 认证，不要暴露未认证的端点 -3. **输入验证：** 验证 `AppSecretKey`、`ClientVersion`、`ProductId` 格式 -4. **速率限制：** 对版本检查接口实施速率限制 -5. **日志审计：** 记录所有更新请求和结果 - -### 客户端 - -1. **证书固定：** 在自定义 `ISslValidationPolicy` 中实现证书固定 -2. **最小权限：** 仅在必要时请求管理员权限 -3. **配置保护：** 不要在代码中硬编码 `AppSecretKey` -4. **Dump 保护：** 确保 `.dmp` 文件不被未授权访问 - ---- - -## 八、安全清单 - -在生产环境部署前，请确认： - -- [ ] 所有通信使用 HTTPS -- [ ] 配置了合适的 `IHttpAuthProvider`（Bearer Token 或 HMAC） -- [ ] 生产环境使用 `StrictSslValidationPolicy`（默认） -- [ ] 更新包 SHA256 哈希已正确配置并在服务端维护 -- [ ] `AppSecretKey` 使用强随机 GUID 且每个产品唯一 -- [ ] 客户端应用以最小必要权限运行 -- [ ] Bowl 的 Dump 目录有适当的访问控制 -- [ ] 备份文件定期清理，避免磁盘占满 -- [ ] 已实现完整的异常监听和错误处理 - ---- - -## 相关资源 - -- **[系统架构](./Architecture.md)** — 了解安全机制在整体架构中的位置 -- **[配置参考](./Configuration.md)** — 安全相关配置项 -- **[GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl)** — Bowl 崩溃监控 -- **[GeneralUpdate.Core](../doc/GeneralUpdate.Core)** — 客户端配置与安全选项 diff --git a/website/docs/guide/System infomation.md b/website/docs/guide/System infomation.md deleted file mode 100644 index 1a57a26..0000000 --- a/website/docs/guide/System infomation.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -sidebar_position: 6 ---- - -### System Information - -#### (1) Windows Platform - -When an update fails, it might not be clear whether the failure is due to the operating system or other reasons. In such cases, you can use PsInfo to export information about the current operating system, which can help developers troubleshoot the issue. *PsInfo* is a command-line tool that can be used to collect critical information about local or remote Windows NT/2000 systems, including installation type, kernel version, registered organization and owner, number and type of processors, amount of physical memory, system installation date, and expiration date (if it is a trial version). - -#### Using PsInfo - -By default, *PsInfo* displays information about the local system. Specify a remote computer name to retrieve information from a remote system. Since *PsInfo* relies on remote registry access to gather its data, the remote system must have the remote registry service running, and the account running *PsInfo* must have access to the HKLM\System section of the remote registry. - -To assist in automating Service Pack updates, *PsInfo* returns the system's Service Pack number (e.g., 0 for no Service Pack, 1 for SP 1, etc.). - -**Usage: psinfo [[\\computer[,computer[,..] | @file [-u user [-p psswd]]] [-h] [-s] [-d] [-c [-t delimiter]] [filter]** - -| Parameter | Description | -| -------------- | ------------------------------------------------------------ | -| **\\computer** | Execute the command on the specified remote computer(s). If the computer name is omitted, the command runs on the local system. If a wildcard (\\*) is specified, the command runs on all computers in the current domain. | -| **@file** | Run the command on each computer listed in the specified text file. | -| **-u** | Specify an optional username for logging onto the remote computer. | -| **-p** | Specify an optional password for the username. If omitted, you will be prompted to enter a hidden password. | -| **-h** | Show a list of installed hotfixes. | -| **-s** | Show a list of installed applications. | -| **-d** | Show disk volume information. | -| **-c** | Print in CSV format. | -| **-t** | The default delimiter for the -c option is a comma, but you can specify a different character. | -| **filter** | PsInfo will only display data for fields that match the filter. For example, "psinfo service" will only list the service pack field. | - -#### Example Output - -When you run PsInfo, it will output information about the system in a structured format. This information can be used to diagnose and address any issues that may arise during the update process. - -```c# -C:\> psinfo \\development -h -d - -PsInfo v1.6 - local and remote system information viewer -Copyright (C) 2001-2004 Mark Russinovich -Sysinternals - www.sysinternals.com - - System information for \\DEVELOPMENT: - Uptime: 28 days, 0 hours, 15 minutes, 12 seconds - Kernel version: Microsoft Windows XP, Multiprocessor Free - Product type Professional - Product version: 5.1 - Service pack: 0 - Kernel build number: 2600 - Registered organization: Sysinternals - Registered owner: Mark Russinovich - Install date: 1/2/2002, 5:29:21 PM - Activation status: Activated - IE version: 6.0000 - System root: C:\WINDOWS - Processors: 2 - Processor speed: 1.0 GHz - Processor type: Intel Pentium III - Physical memory: 1024 MB - Volume Type Format Label Size Free Free - A: Removable 0% - C: Fixed NTFS WINXP 7.8 GB 1.3 GB 16% - D: Fixed NTFS DEV 10.7 GB 809.7 MB 7% - E: Fixed NTFS SRC 4.5 GB 1.8 GB 41% - F: Fixed NTFS MSDN 2.4 GB 587.5 MB 24% - G: Fixed NTFS GAMES 8.0 GB 1.0 GB 13% - H: CD-ROM CDFS JEDIOUTCAST 633.6 MB 0% - I: CD-ROM 0% - Q: Remote 0% - T: Fixed NTFS Test 502.0 MB 496.7 MB 99% - OS Hot Fix Installed - Q147222 1/2/2002 - Q309521 1/4/2002 - Q311889 1/4/2002 - Q313484 1/4/2002 - Q314147 3/6/2002 - Q314862 3/13/2002 - Q315000 1/8/2002 - Q315403 3/13/2002 - Q317277 3/20/2002 -``` - - - -References：https://learn.microsoft.com/zh-cn/sysinternals/downloads/psinfo \ No newline at end of file diff --git a/website/docs/guide/Systemlog.md b/website/docs/guide/Systemlog.md deleted file mode 100644 index 627b9e3..0000000 --- a/website/docs/guide/Systemlog.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -sidebar_position: 5 ---- - -### System Log - -When an upgrade fails, issues such as startup failures or driver installation failures may occur. The Sysmon tool can be used to export system event logs. *System Monitor* (*Sysmon*) is a Windows system service and device driver that, once installed on a system, remains resident across system reboots to monitor and log system activity to the Windows event log. It provides detailed information about process creations, network connections, and file creation time changes. By using [Windows Event Collection](https://msdn.microsoft.com/library/windows/desktop/bb427443(v=vs.85).aspx) or [SIEM](https://en.wikipedia.org/wiki/security_information_and_event_management) agents to collect the generated events, and then analyzing these events, you can identify malicious or anomalous activity and understand how intruders and malware operate on your network. The service runs as a [protected process](https://learn.microsoft.com/windows/win32/services/protecting-anti-malware-services-#system-protected-process), preventing broad user-mode interaction. - -### Sysmon Features Overview - -*Sysmon* includes the following features: - -- Logs processes created with their full command line, along with their parent process. -- Logs hashes of process image files using SHA1 (default), MD5, SHA256, or IMPHASH. -- Supports multiple hashes used simultaneously. -- Includes a process GUID in process creation events to allow correlation of events even when Windows reuses process IDs. -- Includes a session GUID in each event to allow correlation of events on the same logon session. -- Logs the loading of drivers or DLLs with their signatures and hashes. -- Logs raw read access attempts to disks and volumes. -- (Optional) Logs network connections, including source process, IP addresses, port numbers, hostnames, and port names for each connection. -- Detects file creation time changes to determine the true creation time of a file. Modifying file creation timestamps is a common malware tactic to hide its tracks. -- Automatically reloads configuration if changes are made to the registry. -- Performs rule filtering to dynamically include or exclude certain events. -- Generates events at the start of the process to capture activities performed by sophisticated kernel-mode malware. - -Sysmon can be a valuable tool for monitoring system activities and diagnosing issues that arise during system updates or when troubleshooting security incidents. - - - -#### （1）Windows - -address： https://download.sysinternals.com/files/Sysmon.zip - - - -#### （2）Linux - -address：https://github.com/Sysinternals/SysmonForLinux - -doc：https://learn.microsoft.com/zh-cn/sysinternals/downloads/sysmon diff --git a/website/docs/guide/_category_.json b/website/docs/guide/_category_.json index a1e16a4..60ddc82 100644 --- a/website/docs/guide/_category_.json +++ b/website/docs/guide/_category_.json @@ -1,8 +1,8 @@ { - "label": "Guides", - "position": 7, + "label": "帮助", + "position": 3, "link": { "type": "generated-index", - "description": "平台与运维指南。" + "description": "平台与运维帮助文档。" } } diff --git a/website/docs/quickstart/Advanced cookbook.md b/website/docs/quickstart/Advanced cookbook.md deleted file mode 100644 index 2676dd4..0000000 --- a/website/docs/quickstart/Advanced cookbook.md +++ /dev/null @@ -1,808 +0,0 @@ ---- -sidebar_position: 4 -title: 高级实战手册 ---- - -# GeneralUpdate 高级实战手册 - -> **目标读者**：已有基础使用经验的开发者，正在将 GeneralUpdate 集成到生产产品、CI/CD 流水线和企业级发布工作流中。 - -本手册与[入门实战手册](./Beginner cookbook.md)互补。入门手册带你跑通第一次更新闭环；本手册假设你已经跑通，直接进入生产级方案设计。 - ---- - -## 1. 生产更新架构设计 - -### 1.1 拓扑总览 - -``` -┌──────────┐ GET version ┌──────────┐ -│ Client │ ──────────────> │ Server │ -│ (主程序) │ <── version.json │ (更新服务) │ -└────┬─────┘ └────┬─────┘ - │ │ - │ 下载补丁 ZIP │ 读取 packages/ - ▼ ▼ -┌──────────┐ 启动并传参 ┌──────────┐ -│ Upgrade │ <──────────── │ Client │ -│ (独立进程) │ │ │ -└────┬─────┘ └──────────┘ - │ 应用补丁、上报状态 - ▼ -┌──────────┐ -│ 新版本 │ -│ 主程序 │ -└──────────┘ -``` - -### 1.2 各角色职责 - -| 角色 | 部署位置 | 职责 | 关键配置 | -|------|----------|------|----------| -| Client | 用户终端 | 版本检查、补丁下载、拉起 Upgrade | `UpdateUrl`、`AppSecretKey`、`ClientVersion` | -| Upgrade | 与 Client 同目录 | 独立升级进程，接收上下文并应用补丁 | 由 Client 通过 `GeneralUpdateBootstrap` 传递 | -| Server | 服务器 | 版本验证、补丁下载、状态上报 | `versions.json`、`/Upgrade/Verification`、`/File/Download` | -| Tools | 开发/CI 环境 | 生成补丁包、OSS 清单、Hash 计算 | 输入 old/new 目录，输出 `.zip` | -| Bowl | 与 Client 同目录 | 进程监控、崩溃检测、备份恢复 | `MonitorParameter`、dump 路径 | - -### 1.3 最小生产拓扑 - -对于大多数产品，推荐以下拓扑： - -- **开发端**：CI 环境运行 `generate_packages.ps1` + Tools 生成补丁 -- **服务端**：一台 HTTP Server 托管 `versions.json` 和 `.zip` 文件；可选 OSS 模式用静态存储 -- **客户端**：Client 和 Upgrade 统一引用 `GeneralUpdate.Core`（自最新版本起，原 `GeneralUpdate.ClientCore` 和 `GeneralUpdate.Common` 已合并到 `GeneralUpdate.Core`） - -```text -CI (GitHub Actions) Server (HTTP / OSS) -┌─────────────────┐ ┌──────────────────┐ -│ build + publish │ ── 推送补丁 ZIP ──> │ versions.json │ -│ gen_packages.ps1│ │ *.zip (补丁包) │ -│ Tools (可选) │ │ 静态文件服务 │ -└─────────────────┘ └──────────────────┘ -``` - ---- - -## 2. 标准化发布物 - -### 2.1 发布物类型 - -| 类型 | 生成方式 | 文件格式 | 适用场景 | -|------|----------|----------|----------| -| 全量包 (Full) | `ZipFile.CreateFromDirectory` 打包完整发布目录 | `packet_{timestamp}_{version}.zip` | 跨多个版本升级、首次安装 | -| 差分包 (Patch) | Tools Patch 页面或 `DifferentialCore.Clean` 对比 old/new | `patch_{timestamp}.zip` | 仅变更少量文件时减少下载量 | -| 扩展包 (Extension) | Tools Extension 页面 | `.zip`（含 manifest） | 插件/扩展独立分发与更新 | -| OSS 清单 | Tools OSS 页面 | `version.json` | OSS 模式更新，适合静态文件服务 | - -### 2.2 `versions.json` 字段说明 - -Samples Server 的 `versions.json` 每条记录控制一次版本匹配与下载： - -```json -{ - "PacketName": "packet_20260529221936_client_2.0.0.0", - "Hash": "a1b2c3...sha256", - "Version": "2.0.0.0", - "Url": "http://localhost:5000/File/Download/a1b2c3...", - "PubTime": "2026-05-29T14:19:36.0000000", - "AppType": 1, - "Platform": 1, - "ProductId": "2d974e2a-31e6-4887-9bb1-b4689e98c77a", - "IsForcibly": false, - "Format": ".zip", - "Size": 123456, - "IsFreeze": false, - "IsCrossVersion": true, - "FromVersion": "1.0.0.0", - "ToVersion": "2.0.0.0" -} -``` - -| 字段 | 说明 | -|------|------| -| `AppType` | `1` = Client（主程序），`2` = Upgrade（升级程序） | -| `Platform` | `1` = Windows，`2` = Linux，`3` = Mac | -| `IsCrossVersion` | `true` = 差分更新包（需要 `FromVersion`/`ToVersion`），`false` = 全量包 | -| `IsForcibly` | `true` = 强制更新，用户无法跳过 | -| `IsFreeze` | `true` = 冻结当前版本，Server 返回已是最新 | -| `ProductId` | 产品标识，与 Client 配置中的 `ProductId` 对应 | - -### 2.3 生成脚本的使用 - -Samples 提供了完整的 PowerShell 打包脚本： - -```powershell -# 生成全量包和差分包 -.\src\Server\generate_packages.ps1 - -# 仅生成全量包（快速模式，跳过 Differential） -.\src\Server\generate_packages.ps1 -FullOnly - -# 单独重建 versions.json -.\src\Server\create_versions_json.ps1 -``` - -脚本流程： -1. 扫描 `src/content_client/` 和 `src/content_upgrade/` 中的示例内容 -2. 为每个版本目录生成全量 ZIP -3. 调用 `PatchGenerator` C# 项目生成差分 ZIP -4. 计算每个 ZIP 的 SHA256 并写入 `versions.json` - -**生产环境建议**：将这些脚本改造为 CI 步骤，输入参数接受旧版本路径和新版本路径，输出到制品仓库。 - ---- - -## 3. CI/CD 集成 - -### 3.1 GitHub Actions 示例 - -```yaml -name: Generate Update Packages - -on: - push: - tags: - - 'v*.*.*' - -jobs: - generate-packages: - runs-on: windows-latest - steps: - - uses: actions/checkout@v4 - - - name: Setup .NET - uses: actions/setup-dotnet@v4 - with: - dotnet-version: '8.0.x' - - - name: Build release - run: dotnet publish src/Client/ClientSample.csproj -c Release -o publish/v${{ github.ref_name }} - - - name: Generate packages - shell: pwsh - run: | - $oldVersion = "publish/v1.0.0" # 从制品仓库下载上一个版本 - $newVersion = "publish/v${{ github.ref_name }}" - dotnet run --project src/PatchGenerator -- $oldVersion $newVersion packages/ - - - name: Upload artifacts - uses: actions/upload-artifact@v4 - with: - name: update-packages - path: packages/ -``` - -### 3.2 版本映射策略 - -**关键问题**：CI 不能假设所有历史版本都在构建机器上。 - -**推荐方案**： - -| 方案 | 描述 | 适用场景 | -|------|------|----------| -| 制品仓库缓存 | 每次发布后将 `publish/v{version}` 上传到制品仓库（如 GitHub Releases、Artifactory），CI 运行时下载需要对比的旧版本 | 中等规模，版本数量可控 | -| 基准版本 + 回退 | 每隔 N 个版本发布一次全量包，差分包只与最近 2-3 个版本比较 | 快速迭代的产品 | -| 按需下载 | Server 端对比版本时，按需从 OSS 下载旧版本包进行差分 | 版本很多的产品 | - -### 3.3 发布清单 - -每次版本发布前请确认： - -- [ ] `versions.json` 中新增的记录 `Hash` 与上传的 ZIP 文件一致 -- [ ] 差分包的 `FromVersion` 正确指向旧版本 -- [ ] 全量包的 `AppType` 区分了 Client 和 Upgrade -- [ ] 旧版本 `IsFreeze` 未设置为 `true`（除非需要冻结） -- [ ] 所有 ZIP 可通过 `GET /File/Download/{hash}` 正常下载 -- [ ] 测试 Client 从当前最新旧版本升级到新版本 - ---- - -## 4. 版本策略 - -### 4.1 版本号规范 - -GeneralUpdate 遵循[语义化版本](https://semver.org/lang/zh-CN/)（SemVer）规范的核心原则。在 SemVer `MAJOR.MINOR.PATCH` 的基础上，为兼容 .NET `System.Version`，扩展了第四个 `Revision` 段，形成 `Major.Minor.Build.Revision` 四段式版本号： - -```text -2.0.0.0 -│ │ │ └── Revision（修订号）— 对应 .NET 第四段，非 SemVer 标准 -│ │ └──── Build（构建号） — 对应 SemVer PATCH -│ └────── Minor（次版本号） — 对应 SemVer MINOR -└──────── Major（主版本号） — 对应 SemVer MAJOR -``` - -版本号规则： -- **Major**（主版本号）：不兼容的 API 修改时递增 -- **Minor**（次版本号）：向下兼容的功能新增时递增 -- **Build**（构建号/补丁号）：向下兼容的问题修正时递增 -- **Revision**（修订号）：内部修订，通常为 `0`，仅在 .NET 程序集版本中区分 - -Server 使用 `new Version(string)` 进行比较，因此请保持纯数字格式。更多细节参见 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/)。 - -### 4.2 更新模式 - -| 模式 | `UpgradeMode` | 行为 | -|------|---------------|------| -| 全量更新 | `1` (VersionChain) | 仅匹配 `IsCrossVersion = false` 的包，按版本号由低到高逐级升级 | -| 差分更新 | `2` (CrossVersion) | 仅匹配 `IsCrossVersion = true` 的包，要求 `FromVersion` 与客户端当前版本精确匹配 | - -### 4.3 渐进式发布 - -```text - ┌──────────────┐ -v1.0.0.0 ───────────>│ 全量 → 2.0.0.0 │ (跨版本跳跃) - └──────────────┘ - ┌──────────────┐ -v1.0.0.1 ───────────>│ 差分 → 2.0.0.0 │ (精确匹配 FromVersion) - └──────────────┘ - ┌──────────────┐ -v1.0.0.2 ───────────>│ 差分 → 2.0.0.0 │ - └──────────────┘ -``` - -**建议**： -- 重要版本发布同时提供全量包和差分包 -- 对最近 3 个活跃版本提供差分升级路径 -- 超过 3 个版本差距的用户走全量升级 - -### 4.4 强制更新 - -在 `versions.json` 中将 `IsForcibly` 设为 `true`： - -```json -{ "Version": "2.0.1.0", "IsForcibly": true } -``` - -Client 端配合 `AddListenerUpdatePrecheck` 处理： - -```csharp -// Client 端的预检回调 -bootstrap.AddListenerUpdatePrecheck(async (precheckArgs) => -{ - var forcedCount = precheckArgs.Versions.Count(v => v.IsForcibly); - if (forcedCount > 0) - { - // 强制更新：不弹出"跳过"按钮 - ShowDialog("检测到重要安全更新，必须立即更新。"); - return false; // false = 不跳过，继续更新 - } - // 可选更新：询问用户 - return await AskUserWhetherToSkip(); -}); -``` - -### 4.5 多版本顺序升级 - -当客户端版本落后多个版本时： - -1. Server 返回所有高于当前版本的记录（`IsCrossVersion = false` 的全量包） -2. Client 按版本号升序依次下载并应用 -3. 每完成一个版本的升级，Upgrade 重启 Client，Client 再次请求下一版本 - -**注意**：如果希望一次跳跃到最新版本，只提供一个全量包（版本号设为最新的目标版本）。 - ---- - -## 5. 差分策略 - -### 5.1 何时使用差分 - -| 场景 | 推荐方式 | 原因 | -|------|----------|------| -| 用户版本紧跟最新 | 差分更新 | 仅传输变更文件，节省带宽 | -| 用户版本落后 3+ 个版本 | 全量更新 | 累积变更可能超过全量下载 | -| 紧急安全补丁 | 差分更新 | 快速分发，减小攻击窗口 | -| 框架/运行时升级 | 全量更新 | 文件变化范围大，差分收益低 | -| 大文件更新（>100MB） | 差分更新 | 即使变更量大，也能显著减小下载 | - -### 5.2 差分生成与 `delete_files.json` - -Tools 或 `DifferentialCore.Clean` 生成的补丁包包含： - -``` -patch_20260529221936.zip -├── file1.dll.patch ← 二进制差分文件 -├── file2_new.dll ← 新增文件（直接复制） -└── generalupdate.delete.json ← 需要删除的文件清单 -``` - -`generalupdate.delete.json` 格式： - -```json -{ - "deleteFiles": [ - "old_plugin.dll", - "deprecated/config.json" - ] -} -``` - -Upgrade 端应用补丁时会自动处理： -1. 对 `.patch` 文件应用差分还原 -2. 复制新增文件 -3. 删除清单中的文件 - -### 5.3 黑名单配置 - -某些文件不应参与更新（用户数据、本地配置、日志等）： - -```csharp -// 在 Client 配置中使用黑名单 -new GeneralUpdateBootstrap() - .AddBlacklist(new List - { - "appsettings.json", // 用户本地配置 - "logs/", // 日志目录 - "*.user", // 用户文件 - "cache.db" // 本地数据库 - }) -``` - -C# 代码示例 — 通过 `IBinaryDiffer` 扩展点介入： - -```csharp -// 自定义差分策略，跳过大于 100MB 的单文件 -public class LargeFileAwareStrategy : DefaultCleanStrategy -{ - public override bool ShouldDiff(string relativePath, FileInfo oldFile, FileInfo newFile) - { - const long maxDiffSize = 100 * 1024 * 1024; - if (newFile.Length > maxDiffSize) - return false; // 直接复制新文件，不生成 patch - return base.ShouldDiff(relativePath, oldFile, newFile); - } -} -``` - -### 5.4 并行处理 - -Differential 默认使用并行处理（`StreamingHdiffDiffer`）提升性能。对于大目录（数千个文件），建议： - -- 控制并行度：`new ParallelOptions { MaxDegreeOfParallelism = Environment.ProcessorCount }` -- 对超大文件使用 bsdiff 算法（内存占用较低但速度稍慢） -- 对一般文件使用 hdiff 算法（速度快但内存占用较高） - ---- - -## 6. Bowl 可靠性设计 - -### 6.1 Bowl 在生命周期中的位置 - -```text -┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ -│ 更新完成 │ -> │ Bowl 启动 │ -> │ 启动主程序 │ -> │ 监控运行 │ -└──────────┘ └──────────┘ └──────────┘ └────┬─────┘ - │ - 进程异常退出 - │ - ▼ - ┌──────────┐ - │ 导出 Dump │ - │ 备份旧版本 │ - │ 写 Fail JSON│ - └──────────┘ -``` - -### 6.2 生产配置示例 - -```csharp -public static async Task GuardAsync(string appPath, string installPath) -{ - var lastVersion = "2.0.0.0"; - var processInfo = new MonitorParameter - { - ProcessNameOrId = "MyProduct.App.exe", - DumpFileName = $"{lastVersion}_fail.dmp", - FailFileName = $"{lastVersion}_fail.json", - TargetPath = installPath, - FailDirectory = Path.Combine(installPath, "fail", lastVersion), - BackupDirectory = Path.Combine(installPath, "backup", lastVersion), - WorkModel = "Normal" - }; - - Bowl.Launch(processInfo); -} -``` - -### 6.3 备份与回滚流程 - -1. **升级前**：Bowl 将当前运行的程序文件备份到 `BackupDirectory` -2. **升级后**：Bowl 启动新版本主程序 -3. **监控中**：Bowl 持续监控进程状态 -4. **异常时**： - - 导出 `.dmp` 文件 - - 写入 `fail.json`（包含版本、时间、系统信息、驱动信息） - - 如果 `WorkModel = "Normal"`，自动从备份目录恢复旧版本 -5. **恢复后**：Bowl 重新启动旧版本程序 - -### 6.4 平台差异处理 - -| 特性 | Windows | Linux | macOS | -|------|---------|-------|-------| -| Dump 导出 | MiniDumpWriteDump | 依赖环境（需 `dotnet-dump` 或 `createdump`） | 依赖环境 | -| 进程监控 | WMI / Win32 API | procfs (`/proc/{pid}`) | 类似 Linux | -| 备份恢复 | 文件复制 + 覆盖 | 文件复制 + 覆盖（注意权限） | 文件复制 + 覆盖 | -| 驱动信息 | `driverquery` | `lsmod` / `lspci` | `kextstat` | - -### 6.5 日志集成 - -Bowl 会自动输出以下信息到 `fail.json`： - -```json -{ - "version": "2.0.0.0", - "timestamp": "2026-05-29T14:30:00Z", - "processName": "MyProduct.App.exe", - "exitCode": -1073741819, - "systemInfo": { "os": "Windows 11", "arch": "x64" }, - "driverInfo": [], - "dumpPath": "fail/2.0.0.0/2.0.0.0_fail.dmp" -} -``` - -建议在产品中加入日志上传步骤，将 `fail.json` 和 `.dmp` 上报到服务端进行分析。 - ---- - -## 7. 扩展系统 - -### 7.1 扩展生命周期 - -```text -┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ -│ 查询可用 │ → │ 下载扩展 │ → │ 安装扩展 │ → │ 加载扩展 │ -│ 扩展列表 │ │ 包到本地 │ │ 到目录 │ │ 到运行时 │ -└──────────┘ └──────────┘ └──────────┘ └────┬─────┘ - │ - ┌────▼─────┐ - │ 更新/回滚 │ - │ 卸载扩展 │ - └──────────┘ -``` - -### 7.2 扩展 Manifest 规范 - -每个扩展包应包含 `extension.json`： - -```json -{ - "id": "com.mycompany.plugin.search", - "name": "Search Plugin", - "version": "1.2.0", - "author": "MyCompany", - "description": "Full-text search capability", - "dependencies": { - "com.mycompany.core": ">=1.0.0" - }, - "platforms": ["win-x64", "linux-x64"], - "minAppVersion": "2.0.0", - "type": "plugin" -} -``` - -### 7.3 查询与安装 - -```csharp -var manager = new ExtensionManager(options => -{ - options.ExtensionsRootPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "extensions"); - options.TempDownloadPath = Path.Combine(Path.GetTempPath(), "ext_downloads"); - options.ManifestFileName = "extension.json"; -}); - -// 查询远程可用扩展 -var available = await manager.QueryRemoteExtensionsAsync("https://extensions.example.com/api/v1/extensions"); - -// 安装 -await manager.InstallAsync("com.mycompany.plugin.search", "1.2.0", - progress => Console.WriteLine($"Downloading: {progress.Percentage}%")); - -// 更新 -await manager.UpdateAsync("com.mycompany.plugin.search", "1.3.0"); - -// 回滚 -await manager.RollbackAsync("com.mycompany.plugin.search", "1.2.0"); - -// 卸载 -await manager.UninstallAsync("com.mycompany.plugin.search"); -``` - -### 7.4 Tools 扩展包生成 - -使用 Tools 的 Extension Package 页面： - -| 输入 | 说明 | -|------|------| -| Extension Source Directory | 扩展文件的源目录 | -| Manifest File | `extension.json` 文件路径 | -| Output Directory | 扩展包 ZIP 输出目录 | - -生成的扩展包 ZIP 包含 manifest 和所有扩展文件，可直接推送到扩展服务器。 - -### 7.5 服务端 API 约定 - -扩展服务器需要提供以下端点： - -``` -GET /api/v1/extensions → 返回可用扩展列表 -GET /api/v1/extensions/{id} → 返回指定扩展详情和版本列表 -GET /api/v1/extensions/{id}/versions/{v} → 返回指定版本元数据和下载链接 -GET /api/v1/extensions/download/{hash} → 下载扩展包 -POST /api/v1/extensions/check → 批量兼容性检查 -``` - ---- - -## 8. 驱动更新 - -### 8.1 驱动更新与普通文件更新的区别 - -| 维度 | 应用文件更新 | 驱动更新 | -|------|-------------|----------| -| 文件位置 | 应用程序目录 | 系统驱动目录 | -| 权限要求 | 常规用户权限 | 管理员/root 权限 | -| 生效方式 | 重启应用程序 | 可能需要重启系统 | -| 签名要求 | 无 | 需要数字签名（Windows WHQL / Linux DKMS） | -| 回滚复杂度 | 直接替换文件 | 需卸载当前驱动，安装旧版本 | -| 兼容性检查 | 框架版本 | 内核版本、硬件 ID | - -### 8.2 Drivelution 更新流程 - -```csharp -var updater = new DriverUpdater(options => -{ - options.DriverStorePath = @"C:\ProgramData\MyProduct\Drivers"; - options.TempPath = Path.GetTempPath(); - options.RequireSignature = true; - options.BackupBeforeInstall = true; -}); - -// 1. 验证驱动包 -var validation = await updater.ValidatePackageAsync(driverPackagePath); -if (!validation.IsValid) -{ - Console.WriteLine($"Driver validation failed: {validation.Errors}"); - return; -} - -// 2. 备份当前驱动 -await updater.BackupCurrentDriverAsync("MyDeviceDriver"); - -// 3. 安装新驱动 -var result = await updater.InstallAsync(driverPackagePath); -if (!result.Success) -{ - // 4. 安装失败，自动回滚 - await updater.RollbackAsync("MyDeviceDriver"); - Console.WriteLine($"Install failed: {result.ErrorMessage}"); - return; -} - -// 5. 验证新驱动是否正常工作 -var health = await updater.HealthCheckAsync("MyDeviceDriver"); -Console.WriteLine($"Driver health: {health.Status}"); -``` - -### 8.3 Windows 驱动签名 - -生产环境中，Windows 驱动必须签名： - -1. 获取 EV Code Signing 证书 -2. 通过 WHQL（Windows Hardware Quality Labs）认证 -3. 在 `DriverUpdater` 中启用 `RequireSignature = true` - -### 8.4 Linux 驱动注意事项 - -- 使用 `dkms`（Dynamic Kernel Module Support）管理内核模块 -- 更新前检查内核版本兼容性 -- `/lib/modules/$(uname -r)/` 路径通常需要 root 权限 -- 更新后可能需要 `depmod` 和 `modprobe` - -### 8.5 批量/并行驱动更新 - -```csharp -var updaters = new[] -{ - new DriverUpdateTask { DeviceId = "PCI\\VEN_8086", PackagePath = @"drivers\gpu_2.1.0.zip" }, - new DriverUpdateTask { DeviceId = "USB\\VID_0BDA", PackagePath = @"drivers\wifi_1.5.0.zip" }, -}; - -// 并行更新多个驱动 -var results = await Parallel.ForEachAsync(updaters, - new ParallelOptions { MaxDegreeOfParallelism = 4 }, - async (task, ct) => - { - var updater = new DriverUpdater(/* ... */); - return await updater.InstallAsync(task.PackagePath); - }); - -foreach (var r in results) -{ - Console.WriteLine($"Driver {r.DeviceId}: {(r.Success ? "OK" : "FAILED")}"); -} -``` - ---- - -## 9. 安全与合规 - -### 9.1 Hash 校验 - -GeneralUpdate 在下载完成后自动校验 SHA256： - -```csharp -// Server 端：生成 Hash（PowerShell） -(Get-FileHash -Path .\packet.zip -Algorithm SHA256).Hash.ToLowerInvariant() - -// 或使用 Tools OSS 页面计算 -``` - -Client 端自动校验：下载完成后，Core 会对下载的文件计算 SHA256 并与 `versions.json` 中的 `Hash` 进行比对。不匹配则丢弃并重试（最多 3 次）。 - -### 9.2 认证下载 - -Server 支持在下载请求中传递 Token： - -```csharp -// Client 端：在请求中添加认证头 -new GeneralUpdateBootstrap() - .AddListenerDownloadConfig(config => - { - config.Headers = new Dictionary - { - ["Authorization"] = $"Bearer {GetAccessToken()}" - }; - }); -``` - -**生产环境建议**： -- 使用短期有效的 JWT Token -- 下载端点验证 Token 作用域（仅允许下载指定 `ProductId` 的包） -- 记录每次下载的 Token、IP、时间到审计日志 - -### 9.3 OSS 模式安全 - -OSS 模式使用静态文件服务（如阿里云 OSS、AWS S3）： - -``` -# 推荐的 OSS Bucket 策略 -{ - "Statement": [ - { - "Effect": "Allow", - "Principal": {"Anonymous": ["*"]}, - "Action": ["oss:GetObject"], - "Resource": ["acs:oss:my-bucket:packages/*.zip"], - "Condition": { - "IpAddress": {"acs:SourceIp": ["你的服务器 IP 段"]} - } - }, - { - "Effect": "Allow", - "Principal": {"Anonymous": ["*"]}, - "Action": ["oss:GetObject"], - "Resource": ["acs:oss:my-bucket:packages/versions.json"] - } - ] -} -``` - -### 9.4 发布审计清单 - -每次生产发布前请确认： - -- [ ] 所有 `versions.json` 中的 `Hash` 与上传 ZIP 的 SHA256 一致 -- [ ] 下载端点使用 HTTPS（生产环境禁止 HTTP） -- [ ] `AppSecretKey` 正确配置，防止未授权的版本查询 -- [ ] 旧版本的 `IsFreeze` 标记正确（不应冻结仍在使用中的版本） -- [ ] 差分包的 `FromVersion`/`ToVersion` 路径正确 -- [ ] 所有文件由 CI 签名，未被篡改 -- [ ] 生产发布记录已写入审计日志 - ---- - -## 10. 故障演练 - -### 10.1 场景一：下载失败 / 网络中断 - -**模拟方法**：在 Client 下载过程中拔掉网线或关闭 Server。 - -**预期行为**： -- Client 抛出 `DownloadException` -- 断点续传功能自动生效：下次启动继续下载 -- 下载进度通过 `AddListenerMultiDownloadStatistics` 回调报告 - -**验证方式**： -```csharp -bootstrap.AddListenerMultiDownloadError((version, exception) => -{ - Console.WriteLine($"[Download Error] {version.Version}: {exception.Message}"); - // 产品集成：告警上报 -}); -``` - -### 10.2 场景二：文件锁定 - -**模拟方法**：在 Upgrade 应用补丁前，手动打开目标目录中的某个 DLL（如用记事本打开）。 - -**预期行为**： -- Upgrade 尝试替换文件时遇到 `IOException` -- 重试 3 次（每次间隔 500ms） -- 仍失败则触发 `AddListenerException` 回调 -- 不破坏已更新的其他文件 - -### 10.3 场景三：升级后启动崩溃 - -**模拟方法**：将 `content_upgrade` 中的 `UpgradeSample.exe` 替换为一个会立即崩溃的假 exe。 - -**预期行为**： -- Client 完成更新后启动新版本 -- Bowl 检测到进程异常退出 -- Bowl 导出 `.dmp` 和 `fail.json` 到 `fail/{version}/` -- Bowl 从 `backup/{version}/` 恢复旧版本 -- 旧版本启动成功 - -**验证方式**： -1. 检查 `fail/` 目录中是否出现了 dump 和 JSON 文件 -2. 确认旧版本程序成功恢复并启动 -3. Server 收到 `/Upgrade/Report` 中的失败状态 - -### 10.4 场景四：补丁包损坏 - -**模拟方法**：手动修改 `packages/` 中的补丁 ZIP 文件（例如用文本编辑器打开并修改若干字节）。 - -**预期行为**： -- Client 下载完成后校验 SHA256 失败 -- 自动丢弃损坏文件并重新下载（最多 3 次） -- 3 次均失败后通过 `AddListenerMultiDownloadError` 通知 -- 不会应用损坏的补丁 - -### 10.5 场景五：权限不足 - -**模拟方法**：在 Linux 上以非 root 用户运行 Upgrade，目标目录的写权限被移除。 - -**预期行为**： -- Upgrade 尝试写入文件时遇到 `UnauthorizedAccessException` -- 通过 `AddListenerException` 通知 -- 不会部分更新（保持原子性） - -**预防措施**： -```csharp -// Client 在启动 Upgrade 前验证目标目录权限 -if (!HasWritePermission(installDirectory)) -{ - // 提示用户以管理员权限运行 - RequestAdminPrivilege(); - return; -} -``` - -### 10.6 故障演练时间表 - -建议每个发布周期执行一次完整的故障演练： - -| 演练项 | 频率 | 负责人 | 验证方式 | -|--------|------|--------|----------| -| 下载中断恢复 | 每次发布 | QA | 观察断点续传日志 | -| 文件锁定处理 | 每次发布 | QA | 检查回滚行为 | -| 启动崩溃恢复 | 每月 | DevOps | Bowl fail 目录 + Server 报告 | -| 补丁损坏校验 | 每次发布 | QA | 下载日志 SHA256 不匹配 | -| 权限不足处理 | 每次大版本 | DevOps | Linux 平台测试 | -| 差分包完整性 | 每次发布 | CI | 自动化测试对比文件树 | - ---- - -## 附录：相关资源 - -- [GeneralUpdate.Core 组件文档](../doc/GeneralUpdate.Core.md) -- [GeneralUpdate.Differential 组件文档](../doc/GeneralUpdate.Differential.md) -- [GeneralUpdate.Bowl 组件文档](../doc/GeneralUpdate.Bowl.md) -- [GeneralUpdate.Drivelution 组件文档](../doc/GeneralUpdate.Drivelution.md) -- [GeneralUpdate.Extension 组件文档](../doc/GeneralUpdate.Extension.md) -- [GeneralUpdate.Tools 工具文档](../doc/GeneralUpdate.PacketTool.md) -- [入门实战手册](./Beginner cookbook.md) -- [Samples 仓库](https://github.com/GeneralLibrary/GeneralUpdate-Samples) -- [Tools 仓库](https://github.com/GeneralLibrary/GeneralUpdate.Tools) - -> **贡献指南**：如果你在生产环境中积累了实战经验，欢迎通过 [Issue](https://github.com/GeneralLibrary/GeneralUpdate-Samples/issues) 或 Pull Request 贡献案例与最佳实践。 diff --git a/website/docs/quickstart/Beginner cookbook.md b/website/docs/quickstart/Beginner cookbook.md index 80d4d11..e60f34e 100644 --- a/website/docs/quickstart/Beginner cookbook.md +++ b/website/docs/quickstart/Beginner cookbook.md @@ -13,8 +13,8 @@ title: 入门实战手册 | --- | --- | --- | --- | | Hub | `src\Hub` | 交互式示例浏览器，通过菜单选择并运行各类更新场景 | [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md) | | Server | `src\Server` | 返回版本信息、接收更新报告、提供补丁下载 | [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md) | -| Packet | `src\Server\wwwroot\packages` | 可下载的 `.zip` 更新包和 `versions.json` 元数据 | [GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool.md) | -| Tools | GeneralUpdate.Tools 仓库 | 生成补丁包、Hash、OSS 清单、manifest 和仿真报告 | [GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool.md) | +| Packet | `src\Server\wwwroot\packages` | 可下载的 `.zip` 更新包和 `versions.json` 元数据 | [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md) | +| Tools | GeneralUpdate.Tools 仓库 | 生成补丁包、Hash、OSS 清单、manifest 和仿真报告 | [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md) | | Bowl | Hub Samples 中集成 | 监控进程异常并导出失败信息 | [GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl.md) | | Differential | Hub Samples + Core 默认集成 | 对 old/new 文件生成差分，并在更新阶段应用 | [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential.md) | @@ -240,7 +240,20 @@ Hub 提供了 9 个内置样例，覆盖了 GeneralUpdate 的主要使用场景 跑通这条链路后，建议按顺序阅读： 1. [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)：更新策略、事件通知、静默更新、manifest 极简配置。 -2. [GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool.md)：补丁包、Hash、OSS Config、Simulation。 +2. [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md)：补丁包、Hash、OSS Config、Simulation。 3. [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential.md)：差分算法、并行处理和 Clean/Dirty。 4. [GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl.md)：崩溃监控、备份和失败恢复。 -5. [高级实战手册](./Advanced cookbook.md)：生产环境部署、CI/CD 集成、企业级方案设计。 +5. [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md)：补丁包、Hash、OSS Config、Simulation。 + +## Sample UI + +示例程序界面预览： + +![](imgs\sampleclient.png) + +![](imgs\sampleupgrade.png) + +| 仓库地址 | +| --- | +| [ClientSample.sln](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/ClientSample.sln) | +| [UpgradeSample.sln](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/UpgradeSample.sln) | diff --git a/website/docs/doc/GeneralUpdate.PacketTool.md b/website/docs/quickstart/GeneralUpdate.PacketTool.md similarity index 100% rename from website/docs/doc/GeneralUpdate.PacketTool.md rename to website/docs/quickstart/GeneralUpdate.PacketTool.md diff --git a/website/docs/quickstart/Quik start.md b/website/docs/quickstart/Quik start.md deleted file mode 100644 index bec792a..0000000 --- a/website/docs/quickstart/Quik start.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -slug: quikstart -title: GeneralUpdate -authors: juster -tags: [quikstart] ---- - - - -## Step1 - -Download the Sample repository from GitHub. Before using the sample, make sure you have .NET 8 runtime environment installed locally. - -- https://github.com/GeneralLibrary/GeneralUpdate-Samples - -The repository directory contents are as follows: - -![](imgs\content.png) - -| Name | Description | -| ------------- | ------------------------------------- | -| Client | Main client sample program | -| Server | Server sample program | -| StartManager | Update process console | -| Upgrade | Upgrade client sample program | -| process.bat | Not required for attention | -| resource.bat | Not required for attention | -| start.cmd | Script to start the update sample | -| oss_start.cmd | Script to start the update OSS sample | - -## Step2 - -Locate the file directory and double-click (the start.cmd script resets the local directory each time it is launched, so manual directory management is unnecessary): - -```shell -...\GeneralUpdate-Samples\src\start.cmd -``` - -![](imgs\build.png) - - - -The automatic process will begin compiling and copying all related project bin directories to the app directory: - -``` -...\GeneralUpdate-Samples\src\run\app -``` - -![](imgs\build.png) - - - -Upon entering the app directory, you will see the setup prior to the upgrade. - -![](imgs\rundir.png) - - - -## Step3 - -After checking the app directory: - -- Enter option 1 and press Enter -- The server sample program will start -- The main client sample program will start, initiating the update request (once the main client program update is complete, it will close automatically). - -![](imgs\upgrade.png) - - - -Once the main client program closes automatically, check the run\app directory again. You will notice a new backup directory named "app-1.0.0.0" and a file named "Congratulations on the update.txt". - -![](imgs\rundir2.png) - -Seeing this indicates that you have successfully completed an upgrade. Congratulations! - -![](imgs\result.png) diff --git a/website/docs/quickstart/Sample UI.md b/website/docs/quickstart/Sample UI.md deleted file mode 100644 index 5910f59..0000000 --- a/website/docs/quickstart/Sample UI.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -slug: sampleui -title: UI -authors: juster -tags: [sampleui] ---- - -## Sample UI - -![](imgs\sampleclient.png) - -![](imgs\sampleupgrade.png) - - - -| 仓库地址 | -| ------------------------------------------------------------ | -| https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/ClientSample.sln | -| https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/UpgradeSample.sln | - diff --git a/website/docs/releaselog/GeneralUpdateReleaselog.md b/website/docs/releaselog/GeneralUpdateReleaselog.md index 4ae8c3d..18409e2 100644 --- a/website/docs/releaselog/GeneralUpdateReleaselog.md +++ b/website/docs/releaselog/GeneralUpdateReleaselog.md @@ -7,6 +7,16 @@ tags: [log] # 📒Release log +### 📍2026-05-20 — v10.5.0-beta.2 + +- **GeneralUpdate.Core**: 统一 `GeneralUpdateBootstrap` 入口，合并原 ClientCore 和 Core 能力；新增 `SetSource()` 轻配置入口与 `generalupdate.manifest.json` 极简接入；重构下载子系统为可替换的 5 层模型（Source/Policy/Executor/Pipeline/Orchestrator）；扩展点体系增至 10 个可替换接口 +- **GeneralUpdate.Bowl**: `BowlContext` 配置 API 稳定；优化 Windows/Linux/macOS ProcDump 集成 +- **GeneralUpdate.Differential**: 稳定 `IBinaryDiffer` 抽象；BSDIFF 4.0 + Streaming HDiff 双算法；BZip2 / Deflate 压缩 +- **GeneralUpdate.Drivelution**: 稳定跨平台驱动更新流水线；Windows pnputil / Linux insmod-dpkg-rpm / macOS kextload-installer +- **GeneralUpdate.Extension**: 稳定 `IExtensionHost` 抽象；Zip Slip 安全解压；拓扑排序依赖解析 +- **文档**: 重构全部 5 个组件文档为统一模板；新增入门实战手册；新增软件外包服务页面 +- **Samples**: Hub 示例浏览器 9 个场景覆盖完整更新/OSS/静默/推送/差分/压缩/扩展/Bowl/驱动 + ### 📍2026-04-10 - Add `AddListenerUpdatePrecheck(Func)` to `GeneralClientBootstrap` — unified entry that receives the full version info and returns `true` to skip or `false` to proceed; replaces the combined use of `AddListenerUpdateInfo` + `SetCustomSkipOption`. Forced-update (`IsForcibly`) versions always proceed regardless of the callback return value. diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 575efb3..f2a762e 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -80,6 +80,23 @@ const config = { position: 'left', label: 'Doc', }, + { + type: 'dropdown', + label: '商务', + position: 'left', + items: [ + { + type: 'doc', + docId: 'doc/GeneralSpacestation', + label: 'GeneralSpacestation', + }, + { + type: 'doc', + docId: 'doc/outsourcing', + label: '软件外包服务', + }, + ], + }, { href: 'https://github.com/GeneralLibrary', label: 'GitHub', diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current.json b/website/i18n/en/docusaurus-plugin-content-docs/current.json index 7f15ff4..f45eb00 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/en/docusaurus-plugin-content-docs/current.json @@ -7,33 +7,13 @@ "message": "Quick Start", "description": "The label for category Quick Start in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Advanced Cookbook": { - "message": "Advanced Cookbook", - "description": "The label for category Advanced Cookbook in sidebar tutorialSidebar" - }, "sidebar.tutorialSidebar.category.Components": { "message": "Components", "description": "The label for category Components in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Tools": { - "message": "Tools", - "description": "The label for category Tools in sidebar tutorialSidebar" - }, - "sidebar.tutorialSidebar.category.Infrastructure": { - "message": "Infrastructure", - "description": "The label for category Infrastructure in sidebar tutorialSidebar" - }, - "sidebar.tutorialSidebar.category.OSS Update Mode": { - "message": "OSS Update Mode", - "description": "The label for category OSS Update Mode in sidebar tutorialSidebar" - }, - "sidebar.tutorialSidebar.category.Utilities": { - "message": "Utilities", - "description": "The label for category Utilities in sidebar tutorialSidebar" - }, - "sidebar.tutorialSidebar.category.Guides": { - "message": "Guides", - "description": "The label for category Guides in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.帮助": { + "message": "Help", + "description": "The label for category 帮助 in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Release Log": { "message": "Release Log", diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md deleted file mode 100644 index 7441252..0000000 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -sidebar_position: 9 ---- - -### Definition - -Namespace: GeneralUpdate.Core - -Assembly: GeneralUpdate.Core.dll - - - -**OSS** - -OSS stands for Object Storage Service. For those developing server-side technology stacks, this term is likely familiar, as major cloud service providers offer similar services. Simply put, it's a file server. Examples include Alibaba Cloud OSS, Tencent Cloud COS, and Huawei Cloud OBS. While they have different names, their functionalities are quite similar. The new feature of this update component is implemented in a very similar manner, so we chose OSS to name this feature, making it easy for developers to quickly understand its purpose (requires the use of the GeneralUpdate.Core component). - - - -**GeneralClientOSS** - -The GeneralClientOSS class is another update mechanism. Unlike GeneralClientBootstrap, GeneralClientOSS does not require writing server-side code and directly updates based on the version information from the version.json file on the OSS file server, simplifying the threshold for beginners using this component. - -```c# -public sealed class GeneralClientOSS -``` - - - -### Example - -| Description | Address | -| --------------------------- | ------------------------------------------------------------ | -| Address of code example | [Enter](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/OSS) | -| Hashing algorithm (sha256) | [Enter](https://github.com/GeneralLibrary/GeneralUpdate/blob/master/src/c%23/GeneralUpdate.Core/Pipeline/HashMiddleware.cs) | -| Test script (oss_start.cmd) | [Enter](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src) | -| versions.json Making tool | [Enter](https://github.com/GeneralLibrary/GeneralUpdate.Tools) | - -#### OSS Process - -![](imgs/oss_flow.png) - -1. Prepare the version.json file for version information configuration, and update the file (update.zip) for packaging. The packaging can be done manually using compression software (such as 7zip, a free software). - -```json -[ - { - "PacketName": "packet_20250102230201638_1.0.0.1", - "Hash": "ad1a85a9169ca0083ab54ba390e085c56b9059efc3ca8aa1ec9ed857683cc4b1", - "Version": "1.0.0.1", - "Url": "http://localhost:5000/packages/packet_20250102230201638_1.0.0.1.zip", - "PubTime": "2025-01-02T23:48:21" - } -] -``` - - - -2. When the Client starts, it directly requests the OSS server or file server to download the version.json file. - -![](imgs/oss_util.png) - -3. After downloading to the local system, it parses the version information to determine if an update is needed. If so, it passes the information to Upgrade through a process launch (Client self-closes). - -4. After Upgrade starts, it directly downloads update.zip and extracts it locally to overwrite the local files. - -5. After the Upgrade completes, it starts the Client and self-closes. The update ends. Compared to the GeneralUpdateBootstrap function, the GeneralUpdateOSS function has a very low usage threshold. If the company does not have high requirements for automatic updates, this feature can be used. In summary, this function downloads the version.json and updates based on the content in the file, downloading each version's update package and extracting it to complete the update. - -6. Since the OSS functionality does not include a blacklist mechanism, when creating the update.zip, please ensure that the files used internally by the following components are not added to the package, or directly release them as a single file to avoid occupying space and reducing update complexity. - -```json -"Microsoft.Bcl.AsyncInterfaces.dll", -"System.Collections.Immutable.dll", -"System.IO.Pipelines.dll", -"System.Text.Encodings.Web.dll", -"System.Text.Json.dll" -``` - - - -The following example defines methods, including the usage of GeneralClientOSS , GeneralUpdateOSS. - -GeneralClientOSS : - -```c# -using System.Text; -using GeneralUpdate.Core; - - -var paramsOSS = new GlobalConfigInfoOSS -{ - Url = "http://localhost:5000/packages/versions.json", - CurrentVersion = "1.0.0.0", - VersionFileName = "versions.json", - AppName = "OSSClientSample.exe", - Encoding = Encoding.UTF8.WebName -}; - -await GeneralClientOSS.Start(paramsOSS, "OSSUpgradeSample.exe"); -``` - -GeneralUpdateOSS : - -``` -using GeneralUpdate.Core; - -/* - * GeneralUpdateOSS will by default read the JSON content of GlobalConfigInfoOSS stored in the system environment variables by GeneralClientOSS - * , and developers do not need to be concerned with the entire process. - * - * Environment.GetEnvironmentVariable("GlobalConfigInfoOSS", EnvironmentVariableTarget.User); - * - * Typically, GeneralClientOSS and GeneralUpdateOSS appear as a pair. - */ -try -{ - await GeneralUpdateOSS.Start(); -} -catch (Exception ex) -{ - Console.WriteLine(ex.Message); -} -``` - - - -### Applicable to - -| Product | Version | -| -------------- | ------------- | -| .NET | 5, 6, 7, 8, 9, 10 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | \ No newline at end of file diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md deleted file mode 100644 index 8f07cce..0000000 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -sidebar_position: 8 ---- - -### GeneralTracer - -> **Merge notice**: `GeneralUpdate.Common` has been merged into `GeneralUpdate.Core`. `GeneralTracer` now lives in the `GeneralUpdate.Core` namespace and is automatically included when you reference the `GeneralUpdate.Core` package — no separate reference needed. - -Namespace: `GeneralUpdate.Core` - -Assembly: `GeneralUpdate.Core.dll` - -`GeneralTracer` provides trace output of internal exception information and execution flow. It is enabled by default and is included automatically when you reference `GeneralUpdate.Core`. - -```c# -public static class GeneralTracer -``` - - - -### Example - -This mechanism is **enabled by default**. It outputs the component's internal exception information and partial execution flow information, which can be viewed and analyzed simultaneously via the IDE console, log files, and Dbgview debugging tool. - -```c# -// Disable the Trace mechanism in production environments or when it is not needed; it is enabled by default. -GeneralTracer.SetTracingEnabled(false); - -// Call this method before the bootstrap class. -_ = await new GeneralClientBootstrap() - .LaunchAsync(); -``` - - - -#### IDE Console - -![](imgs\IDE.png) - - - -#### Log File - -This file is generated by default in the **Logs** folder under the running directory, with the naming format: `generalupdate-trace [today].log`. This log **does not depend on third-party components**. - -![](imgs\log.png) - - - -#### Dbgview Debugging Tool - -![](imgs\DebugView.png) - - - -### Application to - -| Product | Versions | -| -------------- | ----------------- | -| .NET | 5, 6, 7, 8, 9, 10 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | - diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Maui.OSS.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Maui.OSS.md deleted file mode 100644 index 5454b2a..0000000 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Maui.OSS.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -sidebar_position: 10 ---- - -### Definition - -Namespace: GeneralUpdate.Maui.OSS - -Assembly: GeneralUpdate.Maui.OSS.dll - - - -The GeneralUpdate.Maui.OSS component is used to implement the update mechanism for .NET MAUI, currently only supporting automatic upgrades on the Android platform. - -```c# -public sealed class GeneralUpdateOSS -``` - - - -### Example - -![](imgs/maui_android_upgrade.png) - -![](imgs/oss_maui_flow.png) - -1. Prepare the version.json configuration file and the update file (update.apk), which is the new version of the apk (or .abb). - -2. When the client starts, it directly requests the OSS server or file server to download the version.json file. - -```json -{ - "PubTime": 1680444916, - "Name": "com.companyname.generalupdate.ossclient", - "MD5": "9bf414990a67e74f11752d03f49b15d8", - "Version": "1.0.5", - "Url": "http://192.168.50.203/com.companyname.generalupdate.ossclient.apk" -} -``` - -3. After downloading locally, parse the version information content to determine if an update is needed. 4. If an update is needed, download update.apk. 5. After the download is complete, execute the installation, which is handled by the Android operating system. After execution, run the new version of the app. - -The following example defines methods, including how to use GeneralUpdateOSS. - -```c# -Task.Run(async () => -{ - var url = "http://192.168.50.203"; - var apk = "com.companyname.generalupdate.ossclient.apk"; - var authority = "com.generalupdate.oss.fileprovider"; - var currentVersion = "1.0.0.0"; - var versionFileName = "version.json"; - GeneralUpdateOSS.AddListenerDownloadProcess(OnOSSDownload); - GeneralUpdateOSS.AddListenerException(OnException); - await GeneralUpdateOSS.Start(new ParamsAndroid(url, apk, authority, currentVersion, versionFileName)); -}); -``` - -### Annotations - -GeneralUpdateOSS provides the following capabilities. - -#### Properties - -| Properties | Description | -| ------------- | ----------------------------------------------------- | -| ParamsAndroid | Update configuration parameters for Android platform. | - -#### Methods - -| Method | Description | -| ---------------------------- | ------------------------------------------ | -| Start() | Start the OSS update for Android platform. | -| AddListenerDownloadProcess() | Monitor download progress. | -| AddListenerException() | Listen for internal exception information. | - -### 🌴ParamsAndroid - -**Properties** - -**Url**: string - The API server request address. - -**Apk**: string - The Android apk name. - -**CurrentVersion**: string - The current version. - -**Authority**: string - The apk author. - -**VersionFileName**: string - The version file name. - -### 🌼Start() - -**Method** - -Start the OSS update for the Android platform. - -```c# -public static async Task Start(ParamsAndroid parameter) where TStrategy : AbstractStrategy, new(); -``` - -**Parameter Type** - -ParamsAndroid: Update configuration parameters for the Android platform. For detailed content, refer to this document 🌴ParamsAndroid. - -**Parameter** - -**parameter**: ParamsAndroid - Update configuration parameters for the Android platform. - -### 🌼AddListenerDownloadProcess() - -**Method** - -Monitor download progress. - -```c# -public static void AddListenerDownloadProcess(Action callbackAction); -``` - -**Parameter Type** - -**sender**: object - -Operation handle. - -**args**: OSSDownloadArgs - -Download progress notification parameters. - -**Parameter** - -```c# -callbackAction Action -``` - -Listen for current version download progress event callback parameters. - -### 🌼AddListenerException() - -**Method** - -Listen for internal exception information. - -```c# -public static void AddListenerException(Action callbackAction); -``` - -**Parameter Type** - -**sender**: object - -Operation handle. - -**args**: ExceptionEventArgs - -Update exception parameters. - -**Parameter** - -```c# -callbackAction Action -``` - -Listen for current version download progress event callback parameters. - -### Applies to - -| Product | Version | -| --------- | ---------------- | -| .NET | 7, 8, 9 | -| .NET MAUI | .NET 8 - Android | \ No newline at end of file diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/outsourcing.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/outsourcing.md new file mode 100644 index 0000000..53a3ee3 --- /dev/null +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/outsourcing.md @@ -0,0 +1,37 @@ +--- +sidebar_position: 99 +--- + +# Software Outsourcing Services + +The GeneralLibrary team provides professional .NET software outsourcing services covering the following areas: + +## Services + +| Service | Description | +| --- | --- | +| Auto-Update System Integration | Build complete auto-update systems for enterprise applications using GeneralUpdate, including version management, differential packaging, canary releases, and rollback strategies | +| Desktop Application Development | Cross-platform desktop apps with WPF / WinForms / Avalonia / WinUI / MAUI | +| Web Backend Development | ASP.NET Core Web API, SignalR real-time communication, microservice architecture | +| Driver Update Solutions | Cross-platform driver update solutions based on GeneralUpdate.Drivelution | +| Plugin/Extension Systems | Plugin ecosystem using GeneralUpdate.Extension with remote query, download, install, and dependency management | +| CI/CD Pipelines | Automated build, test, and release pipelines with GitHub Actions / Azure DevOps | +| Technical Consulting | Architecture review, performance optimization, code refactoring, security audit | + +## Tech Stack + +- **.NET**: .NET 8/9/10, ASP.NET Core, WPF, Avalonia, MAUI +- **Databases**: SQL Server, PostgreSQL, MySQL, Redis +- **Cloud**: Azure, AWS, Alibaba Cloud +- **DevOps**: GitHub Actions, Azure Pipelines, Docker, Kubernetes + +## Contact + +| Channel | Info | +| --- | --- | +| GitHub | [GeneralLibrary](https://github.com/GeneralLibrary) | +| Email | Please reach out via GitHub Issues | + +--- + +We welcome enterprise clients from all industries. We provide customized solutions based on your specific needs. diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Architecture.md b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Architecture.md deleted file mode 100644 index 603b565..0000000 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Architecture.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -sidebar_position: 1 ---- - -# System Architecture - -## Architecture Overview - -GeneralUpdate is a cross-platform .NET automatic update framework using a **Client-Upgrade-Server** three-tier architecture. The entire update process involves multiple independent processes and components working together. - ---- - -## Overall Architecture - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Server │ -│ ┌──────────────┐ ┌──────────────┐ ┌───────────────────┐ │ -│ │ Verification │ │ Patch Store │ │ UpgradeHub (Push) │ │ -│ │ API │ │ /patch/*.zip │ │ SignalR Hub │ │ -│ └──────────────┘ └──────────────┘ └───────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ Client Process │ -│ ┌──────────────────────────────────────────────────────┐ │ -│ │ GeneralUpdate.ClientCore │ │ -│ │ ┌──────────┐ ┌──────────┐ ┌────────────────────┐ │ │ -│ │ │Version │ │Download │ │Event/Precheck │ │ │ -│ │ │Check │ │Manager │ │Notifications │ │ │ -│ │ └──────────┘ └──────────┘ └────────────────────┘ │ │ -│ └──────────────────────────────────────────────────────┘ │ -│ │ │ -│ IPC (AES encrypted parameters) │ -│ ▼ │ -└─────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ Upgrade Process │ -│ ┌──────────────────────────────────────────────────────┐ │ -│ │ GeneralUpdate.Core │ │ -│ │ ┌────────────────────────────────────────────────┐ │ │ -│ │ │ Pipeline (Middleware Chain) │ │ │ -│ │ │ HashMiddleware → CompressMiddleware → │ │ │ -│ │ │ PatchMiddleware → DrivelutionMiddleware │ │ │ -│ │ └────────────────────────────────────────────────┘ │ │ -│ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ -│ │ │ File │ │ Patch │ │ Driver Update │ │ │ -│ │ │ Replace │ │ Apply │ │ │ │ │ -│ │ └──────────┘ └──────────┘ └──────────────────┘ │ │ -│ └──────────────────────────────────────────────────────┘ │ -│ │ │ -│ Start main app + Bowl monitoring │ -└─────────────────────────────────────────────────────────────┘ -``` - ---- - -## Component Relationships - -### Core Components - -| Component | NuGet Package | Process | Responsibility | -|-----------|-------------|---------|----------------| -| **GeneralUpdate.ClientCore** | `GeneralUpdate.ClientCore` | Main app | Version check, download, launch upgrade | -| **GeneralUpdate.Core** | `GeneralUpdate.Core` | Separate upgrade process | File replacement, patch apply, driver update | -| **GeneralUpdate.Differential** | `GeneralUpdate.Core` (included) | Both | Binary diff algorithms (BSDiff/HDiffPatch) | -| **GeneralUpdate.Bowl** | `GeneralUpdate.Bowl` | Separate monitor process | Crash monitoring, dump generation, diagnostics | -| **GeneralUpdate.Drivelution** | `GeneralUpdate.Drivelution` | Upgrade process | Cross-platform driver update | -| **GeneralUpdate.Extension** | `GeneralUpdate.Extension` | Main app | Plugin/extension management | -| **GeneralUpdate.Tools** | Standalone desktop app | Dev tool | Patch building, simulation, config generation | - -### Component Dependencies - -``` -GeneralUpdate.Tools ──→ GeneralUpdate.Core (DiffPipeline) - │ - ┌────────────┼────────────┐ - ▼ ▼ ▼ - GeneralUpdate GeneralUpdate GeneralUpdate - .Differential .Drivelution .Extension - │ - ▼ - GeneralUpdate.Core (Bootstrap, Pipeline, Download, Security) - │ - ▼ - GeneralUpdate.ClientCore (Client Bootstrap, Hub Service) - │ - ▼ - GeneralUpdate.Bowl (Process Monitoring) -``` - ---- - -## Update Flow - -### Complete Update Sequence - -``` - Client Server Upgrade - ────── ────── ─────── - │ │ │ - │ 1. POST /Verification│ │ - │ ─────────────────────► │ │ - │ │ │ - │ 2. Return version list│ │ - │ ◄───────────────────── │ │ - │ │ │ - │ 3. User confirms │ │ - │ (AddListenerUpdatePrecheck) │ - │ │ │ - │ 4. GET /patch/v2.0.0 │ │ - │ ─────────────────────► │ │ - │ │ │ - │ 5. Download patch │ │ - │ ◄───────────────────── │ │ - │ │ │ - │ 6. Exit main app │ │ - │ │ │ - │ 7. Launch Upgrade (IPC)│ │ - │ ──────────────────────────────────────────────► │ - │ │ │ - │ │ 8. Read IPC params │ - │ │ 9. Verify hash │ - │ │ 10. Decompress │ - │ │ 11. Apply patches │ - │ │ 12. Install drivers │ - │ │ 13. Replace files │ - │ │ │ - │ │ 14. Launch new app │ - │ ◄────────────────────────────────────────────── │ - │ │ │ - │ 15. POST /Report │ │ - │ ─────────────────────► │ │ -``` - -### IPC Data Flow - -``` -Client writes: ProcessContract → JSON serialize → AES-256-CBC encrypt → temp file - ↓ -Upgrade reads: temp file → AES-256-CBC decrypt → JSON deserialize → ProcessContract -``` - ---- - -## Update Modes - -### Full Update - -When `Patch` option is `false`: - -``` -Download full package → Decompress → Overwrite install -``` - -### Incremental/Differential Update (Default) - -When `Patch` option is `true` (default): - -``` -Download patch → Decompress → Apply BSDiff → Delete expired files -``` - -**Patch package structure:** -``` -patch_v1.0.1.zip -├── file1.dll.patch ← BSDiff binary patch -├── file2.exe.patch ← BSDiff binary patch -├── newfile.dll ← New file (included as-is) -├── delete_files.json ← Files to delete -└── ... -``` - -### OSS Update Mode - -Object Storage Service based updates — no server API required: - -``` -Client → read version.json → compare versions → download patches → upgrade -``` - ---- - -## Platform Strategy - -| Platform | Strategy Class | Special Handling | -|----------|---------------|------------------| -| Windows | `WindowsStrategy` | Bowl integration, PnPUtil driver install | -| Linux | `LinuxStrategy` | chmod permission scripts, no Bowl support | -| macOS | `MacStrategy` | chmod scripts, `ConfigureAwait(false)` | - ---- - -## Extension Points - -GeneralUpdate provides rich extensibility through `AbstractBootstrap`'s CRTP pattern: - -| Extension Point | Interface | Default | Purpose | -|----------------|-----------|---------|---------| -| **Strategy** | `IStrategy` | Platform-specific | OS strategy | -| **Hooks** | `IUpdateHooks` | `NoOpUpdateHooks` | Lifecycle hooks | -| **SSL Policy** | `ISslValidationPolicy` | `StrictSslValidationPolicy` | Certificate validation | -| **Download Policy** | `IDownloadPolicy` | `DefaultDownloadPolicy` | Retry/timeout logic | -| **Download Executor** | `IDownloadExecutor` | `HttpDownloadExecutor` | Protocol executor | -| **Auth Provider** | `IHttpAuthProvider` | `NoOpAuthProvider` | HTTP authentication | -| **Download Orchestrator** | `IDownloadOrchestrator` | `DefaultDownloadOrchestrator` | Batch download | - -```csharp -await new GeneralClientBootstrap() - .SslPolicy() - .DownloadPolicy() - .HttpAuth() - .Hooks() - .SetConfig(config) - .LaunchAsync(); -``` - ---- - -## Related Resources - -- **[Pipeline Guide](./Pipeline.md)** — Middleware pipeline internals -- **[Configuration Reference](./Configuration.md)** — All configuration options -- **[Security Guide](./Security.md)** — Security architecture -- **[Quick Start](../quickstart/Quik start)** — 5-minute quickstart diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Configuration.md b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Configuration.md deleted file mode 100644 index d9a3b5f..0000000 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Configuration.md +++ /dev/null @@ -1,318 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Configuration Reference - -This document provides a complete listing of all configurable items, option enums, and configuration classes in the GeneralUpdate framework. - ---- - -## 1. ClientCore Configuration - -### Configinfo Class - -Core configuration class for client updates. - -**Namespace:** `GeneralUpdate.Common.Shared.Object` - -| Property | Type | Description | -|----------|------|-------------| -| `UpdateUrl` | `string` | Update check API endpoint | -| `ReportUrl` | `string` | Status report API endpoint | -| `AppName` | `string` | Application name (upgrade program) | -| `MainAppName` | `string` | Main application name | -| `UpdateLogUrl` | `string` | Update changelog web URL | -| `AppSecretKey` | `string` | Application secret key for server auth & product branching | -| `ClientVersion` | `string` | Current client version | -| `UpgradeClientVersion` | `string` | Current upgrade client version | -| `InstallPath` | `string` | Installation path for file operations | -| `BlackFiles` | `List` | Files to exclude from updates | -| `BlackFormats` | `List` | File formats to exclude from updates | -| `SkipDirectorys` | `List` | Directories to skip during update | -| `ProductId` | `string` | Product branch unique identifier | -| `Bowl` | `string` | Bowl process path for crash monitoring | -| `Scheme` | `string` | HTTP auth scheme (e.g., Bearer) | -| `Token` | `string` | HTTP auth token | -| `Script` | `string` | Linux permission script path | -| `DriverDirectory` | `string` | Driver files directory path | - -### ConfiginfoBuilder (Zero-Config Builder) - -**Namespace:** `GeneralUpdate.Common.Shared.Object` - -Auto-extracts app name, version, and publisher from `.csproj`: - -```csharp -// Minimal config: just UpdateUrl, Token, Scheme -var config = ConfiginfoBuilder - .Create("https://api.example.com/updates", "your-token", "Bearer") - .Build(); -``` - -**Auto-extraction rules:** - -| Config Item | Source | csproj Field | Maps To | -|-------------|--------|-------------|----------| -| App name | Project file | `` or filename | `AppName`, `MainAppName` | -| Version | Project file | `` | `ClientVersion`, `UpgradeClientVersion` | -| Publisher | Project file | `` or `` | `ProductId` | -| Install path | Runtime directory | — | `InstallPath` | - -**Optional overrides:** `SetAppName()`, `SetClientVersion()`, `SetInstallPath()` - ---- - -## 2. UpdateOption Enum - -**Namespace:** `GeneralUpdate.Common.Internal` - -| Value | Description | Default | -|-------|-------------|---------| -| `Format` | Package file format | `Zip` | -| `Encoding` | Compression encoding | — | -| `DownloadTimeOut` | Download timeout (seconds) | 30 | -| `Patch` | Enable binary differential updates | `true` | -| `BackUp` | Enable pre-update backup | `true` | -| `EnableSilentUpdate` | Enable silent update mode | `false` | - -```csharp -await new GeneralClientBootstrap() - .Option(UpdateOption.DownloadTimeOut, 60) - .Option(UpdateOption.Encoding, Encoding.UTF8) - .Option(UpdateOption.Patch, true) - .Option(UpdateOption.BackUp, true) - .Option(UpdateOption.EnableSilentUpdate, true) - .SetConfig(config) - .LaunchAsync(); -``` - ---- - -## 3. Global Option Class - -**Namespace:** `GeneralUpdate.Common.Internal.Bootstrap` - -Static properties for global configuration via `Option.ValueOf(name, default)`: - -| Property | Type | Description | -|----------|------|-------------| -| `AppType` | `Option` | Application role | -| `DiffMode` | `Option` | Serial or Parallel diff | -| `Encoding` | `Option` | Character encoding | -| `Format` | `Option` | Compression format | -| `DownloadTimeout` | `Option` | Download timeout (seconds) | -| `PatchEnabled` | `Option` | Enable differential patches | -| `BackupEnabled` | `Option` | Enable file backup | -| `Silent` | `Option` | Silent update mode | -| `SilentPollIntervalMinutes` | `Option` | Poll interval for silent updates (default 20) | -| `LaunchClientAfterUpdate` | `Option` | Auto-launch client after update | -| `MaxConcurrency` | `Option` | Max concurrent downloads | -| `EnableResume` | `Option` | Enable download resume | -| `RetryCount` | `Option` | Download retry count | -| `VerifyChecksum` | `Option` | Verify SHA256 checksum | -| `RetryInterval` | `Option` | Retry interval (seconds) | - ---- - -## 4. AppType Enum - -| Value | Description | -|-------|-------------| -| `Client` | Standard client mode (requires server API) | -| `Upgrade` | Standard upgrade mode (requires server API) | -| `OssClient` | OSS client mode (uses object storage) | -| `OssUpgrade` | OSS upgrade mode (uses object storage) | - ---- - -## 5. DiffMode Enum - -| Value | Description | -|-------|-------------| -| `Serial` | Process file diffs sequentially | -| `Parallel` | Process file diffs concurrently | - ---- - -## 6. PlatformType Enum - -| Value | Description | -|-------|-------------| -| `Unknown` | Unknown platform | -| `Windows` | Microsoft Windows | -| `Linux` | Linux distributions | -| `MacOS` | Apple macOS | - ---- - -## 7. ReportType Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `None` | 0 | Do not report | -| `Success` | 2 | Update succeeded | -| `Failure` | 3 | Update failed | - ---- - -## 8. Server API Specification - -### Version Verification - -``` -POST /Upgrade/Verification -Content-Type: application/json - -Request: -{ - "AppSecretKey": "string", - "ClientVersion": "string", - "ProductId": "string", - "ClientType": 1 -} - -Response: -{ - "Code": 200, - "Body": [ - { - "Version": "1.0.1.0", - "Hash": "sha256:abc123...", - "UpdateLog": "Update description...", - "IsForcibly": false, - "ReleaseDate": "2025-06-01T00:00:00", - "Size": 1048576, - "Url": "/patch/patch_v1.0.1.zip" - } - ] -} -``` - -### Status Reporting - -``` -POST /Upgrade/Report - -Request: -{ - "AppSecretKey": "string", - "ClientVersion": "string", - "ReportType": 2, - "ProductId": "string" -} -``` - -### Patch Download - -``` -GET /patch/{filename} -Response: application/octet-stream -``` - ---- - -## 9. Bowl Configuration - -### MonitorParameter Class - -| Property | Type | Description | -|----------|------|-------------| -| `TargetPath` | `string` | Monitored directory | -| `FailDirectory` | `string` | Crash data export directory | -| `BackupDirectory` | `string` | Backup directory | -| `ProcessNameOrId` | `string` | Monitored process name or ID | -| `DumpFileName` | `string` | Dump file name | -| `FailFileName` | `string` | Crash report file name | -| `WorkModel` | `string` | "Upgrade" or "Normal" | - -### DumpType Enum - -| Value | Description | -|-------|-------------| -| `Full` | Full memory dump | -| `Mini` | Mini dump | -| `Heap` | Heap dump | - ---- - -## 10. Extension Configuration - -### ExtensionHostOptions - -| Property | Type | Description | -|----------|------|-------------| -| `ServerUrl` | `string` | Extension API server URL | -| `Scheme` | `string` | Auth scheme | -| `Token` | `string` | Auth token | -| `HostVersion` | `string` | Host application version | -| `ExtensionsDirectory` | `string` | Extension installation directory | -| `CatalogPath` | `string` | Extension catalog file path | - ---- - -## 11. Drivelution Configuration - -### DrivelutionOptions - -| Property | Type | Default | Description | -|----------|------|---------|-------------| -| `DefaultBackupPath` | `string` | — | Default backup path | -| `DefaultRetryCount` | `int` | 3 | Default retry count | -| `DefaultRetryIntervalSeconds` | `int` | 5 | Retry interval | -| `DefaultTimeoutSeconds` | `int` | 300 | Operation timeout | -| `DebugModeSkipSignature` | `bool` | false | Skip signature validation (debug) | -| `DebugModeSkipHash` | `bool` | false | Skip hash validation (debug) | -| `ForceTerminateOnPermissionFailure` | `bool` | false | Force terminate on permission failure | -| `AutoCleanupBackups` | `bool` | true | Auto-cleanup old backups | -| `BackupsToKeep` | `int` | 5 | Number of backups to retain | -| `UseExponentialBackoff` | `bool` | true | Use exponential backoff for retries | -| `TrustedCertificateThumbprints` | `List` | — | Trusted certificate thumbprints | - ---- - -## 12. Blacklist Configuration - -### BlackPolicy Record - -| Property | Type | Description | -|----------|------|-------------| -| `Files` | `List` | Blacklisted file names | -| `Formats` | `List` | Blacklisted file extensions | -| `Directories` | `List` | Blacklisted directory names | -| `HasRules` | `bool` | Whether any rules are configured | - -### Default Blacklist - -| Category | Default Values | -|----------|---------------| -| Files | `System.*.dll` | -| Formats | `.patch`, `.pdb`, `.rar`, `.tar`, `.json`, `.zip` | -| Directories | `app-`, `fail` | - ---- - -## 13. manifest.json Format - -Auto-generated configuration file `generalupdate.manifest.json`: - -```json -{ - "MainAppName": "MyApp.exe", - "ClientVersion": "1.0.0.0", - "AppType": "Client", - "UpdateAppName": "UpgradeSample.exe", - "UpgradeClientVersion": "1.0.0.0", - "ProductId": "2d974e2a-31e6-4887-9bb1-b4689e98c77a", - "UpdatePath": "" -} -``` - ---- - -## Related Resources - -- **[Architecture](./Architecture.md)** — Overall system architecture -- **[Pipeline Guide](./Pipeline.md)** — Middleware pipeline internals -- **[Security Guide](./Security.md)** — Security configuration -- **[GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool)** — Config generation tool diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Driver.md b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Driver.md deleted file mode 100644 index 8d147e4..0000000 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Driver.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -sidebar_position: 3 ---- - -### Driver - -#### (1) Windows Platform - -##### Driver Installation - -The tool used for driver installation in this component is the Microsoft built-in tool PnPutil.exe or setupapi.dll. - -There are two key points to note when installing drivers: - -| Name | Description | -| ------- | ------------------------------------------------------------ | -| Install | Driver certificate installation should occur before the driver installation. | -| Version | Differentiate between x86 and x64 versions. | - -**PnPUtil Implementation:** - -PnPUtil is a command line utility that can be used to manage the Windows driver store. You can use it to add, delete, and list drivers. - -Here are the steps to install drivers using PnPUtil: - -1. Open Command Prompt as an administrator. - -2. Navigate to the directory containing the driver's INF file. - -3. Run the following command: - - `pnputil /add-driver ` - - For example, if your INF file name is `mydriver.inf`, you should run `pnputil /add-driver mydriver.inf`. - -4. PnPUtil will add the driver to the driver store and attempt to install the driver for any matching devices. - -Note that PnPUtil requires administrator privileges to run. - -In C#, you can use the System.Diagnostics.Process class to run PnPUtil. Here is an example: - -```c# -using System.Diagnostics; - -public class Program -{ - public static void Main() - { - string infPath = "Path to your INF file"; - - Process process = new Process(); - process.StartInfo.FileName = "pnputil.exe"; - process.StartInfo.Arguments = "/add-driver " + infPath; - process.StartInfo.Verb = "runas"; // Run as administrator - process.Start(); - - process.WaitForExit(); - } -} -``` - -**setupapi.dll Implementation:** - -```c# -using System; -using System.Runtime.InteropServices; - -public class Program -{ - // Define the P/Invoke signature for the SetupCopyOEMInf function - [DllImport("setupapi.dll", EntryPoint = "SetupCopyOEMInf", SetLastError = true)] - public static extern bool SetupCopyOEMInf( - string SourceInfFileName, - string OEMSourceMediaLocation, - int OEMSourceMediaType, - int CopyStyle, - string DestinationInfFileName, - int DestinationInfFileNameSize, - ref int RequiredSize, - string DestinationInfFileNameComponent - ); - - public static void Main() - { - string infPath = "Path to your INF file"; - bool result = SetupCopyOEMInf(infPath, null, 0, 0, null, 0, ref int size, null); - - if (!result) - { - Console.WriteLine("Failed to install driver. Error code: " + Marshal.GetLastWin32Error()); - } - } -} -``` - -##### Driver Certificate - -This component uses Windows certificate management tools (CertMgr.exe) or the X509Store class in the .NET framework. - -**CertMgr.exe Implementation:** - -`CertMgr.exe` is a command line tool that is part of the Microsoft .NET Framework. You can find it in the .NET Framework installation directory. - -For most systems, it is typically located in one of the following directories: - -- `C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Bin` -- `C:\Program Files\Microsoft SDKs\Windows\v7.0A\Bin` - -If you cannot find it, you can use Windows search to locate `CertMgr.exe`. - -Note that `CertMgr.exe` is a command line tool and must be run in Command Prompt or PowerShell. You can also call it in your C# code using the `System.Diagnostics.Process.Start()` method. - -**X509Store Implementation:** - -```c# -using System; -using System.Security.Cryptography.X509Certificates; - -public class Example -{ - public static void Main() - { - string CertificatePath = "Path to your certificate file"; - - // Create a new X509 certificate instance - X509Certificate2 certificate = new X509Certificate2(CertificatePath); - - // Open the current user's personal certificate store - X509Store store = new X509Store(StoreName.My, StoreLocation.CurrentUser); - - // Add the new certificate to the store - store.Open(OpenFlags.ReadWrite); - store.Add(certificate); - - store.Close(); - } -} -``` - diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/FAQ.md b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/FAQ.md index e20993b..cb1d12b 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/FAQ.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/FAQ.md @@ -279,7 +279,7 @@ Sample projects provide a simple server example. For production, implement your ## Related Resources -- **[Architecture](./Architecture.md)** — System architecture overview -- **[Configuration Reference](./Configuration.md)** — All configuration options -- **[Pipeline Guide](./Pipeline.md)** — Middleware pipeline -- **[Security Guide](./Security.md)** — Security best practices +- **[GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)** — Core update engine +- **[Beginner Cookbook](../quickstart/Beginner%20cookbook.md)** — Run through the full update loop +- **[GeneralUpdate.Tools](../quickstart/GeneralUpdate.PacketTool.md)** — Packaging tools +- **[GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl.md)** — Crash monitoring & rollback diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Pipeline.md b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Pipeline.md deleted file mode 100644 index 45149fa..0000000 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Pipeline.md +++ /dev/null @@ -1,254 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Pipeline Middleware - -## Overview - -GeneralUpdate uses a **Middleware Pipeline Pattern** to process update packages. Each downloaded package passes through middleware in sequence — from hash verification to decompression, patch application, and driver installation. - -The core advantages are **separation of concerns** and **extensibility**: each middleware handles one task, and developers can easily add custom middleware. - ---- - -## Pipeline Architecture - -``` -Download Complete (.zip) - │ - ▼ -┌─────────────────┐ -│ HashMiddleware │ ← SHA256 hash verification -└────────┬────────┘ - │ Pass - ▼ -┌─────────────────┐ -│CompressMiddleware│ ← Decompress ZIP to target path -└────────┬────────┘ - │ - ▼ -┌─────────────────┐ -│ PatchMiddleware │ ← Apply BSDiff patches (optional) -└────────┬────────┘ - │ - ▼ -┌─────────────────────┐ -│DrivelutionMiddleware│ ← Install drivers (optional) -└────────┬────────────┘ - │ - ▼ - Update Complete -``` - ---- - -## Core Interfaces - -### IMiddleware - -All middleware must implement: - -```csharp -public interface IMiddleware -{ - Task InvokeAsync(PipelineContext context); -} -``` - -### PipelineBuilder - -Immutable builder, executes middleware FIFO: - -```csharp -public class PipelineBuilder -{ - public PipelineBuilder UseMiddleware() where T : IMiddleware; - public PipelineBuilder UseMiddlewareIf(bool? condition) where T : IMiddleware; - public async Task Build(PipelineContext context); -} -``` - -### PipelineContext - -Thread-safe key-value store passed between middleware: - -```csharp -public class PipelineContext -{ - public const string Hash = "Hash"; - public const string Format = "Format"; - public const string Encoding = "Encoding"; - public const string ZipFilePath = "ZipFilePath"; - public const string SourcePath = "SourcePath"; - public const string PatchPath = "PatchPath"; - public const string PatchEnabled = "PatchEnabled"; - public const string DiffPipeline = "DiffPipeline"; -} -``` - ---- - -## Built-in Middleware - -### 1. HashMiddleware — SHA256 Verification - -**Location:** `GeneralUpdate.Core.Pipeline.HashMiddleware` - -1. Reads `"Hash"` and `"ZipFilePath"` from context -2. Computes SHA256 of the ZIP file -3. Compares with expected hash -4. Mismatch → throws `CryptographicException` -5. Match → passes to next middleware - -### 2. CompressMiddleware — Decompression - -**Location:** `GeneralUpdate.Core.Pipeline.CompressMiddleware` - -| `PatchEnabled` | Extract Target | Next Step | -|----------------|---------------|-----------| -| `true` | `PatchPath` (temp directory) | `PatchMiddleware` applies diffs | -| `false` | `SourcePath` (install directory) | Complete, full overwrite | - -### 3. PatchMiddleware — Differential Patch Application - -**Location:** `GeneralUpdate.Core.Pipeline.PatchMiddleware` - -1. Checks for `"DiffPipeline"` in context -2. Not present → skip (full update mode) -3. Present → call `DiffPipeline.DirtyAsync()` to: - - Apply `.patch` files via BSDiff/HDiffPatch - - Copy new files to target - - Delete files listed in `delete_files.json` - -### 4. DrivelutionMiddleware — Driver Update - -**Location:** `GeneralUpdate.Core.Pipeline.DrivelutionMiddleware` - -Triggered when `DriverDirectory` is set in context. Runs the driver update pipeline: Validate → Backup → Install → Verify. - ---- - -## Default Pipeline Construction - -```csharp -protected override PipelineBuilder BuildPipeline(PipelineContext context) -{ - return new PipelineBuilder() - .UseMiddleware() - .UseMiddleware() - .UseMiddlewareIf( - context.Get(PipelineContext.PatchEnabled)) - .UseMiddlewareIf( - !string.IsNullOrEmpty(context.Get("DriverDirectory"))); -} -``` - ---- - -## Differential Pipeline (DiffPipeline) - -### Core Interface - -```csharp -public interface IBinaryDiffer -{ - /// Apply patch (client): oldFile + patchFile → newFile - Task DirtyAsync(string oldFilePath, string newFilePath, - string patchFilePath, CancellationToken ct = default); - - /// Generate patch (server/tool): oldFile + newFile → patchFile - Task CleanAsync(string oldFilePath, string newFilePath, - string patchFilePath, CancellationToken ct = default); -} -``` - -### Algorithms - -| Algorithm | Implementation | Characteristics | -|-----------|---------------|-----------------| -| **BSDiff 4.0** | `BsdiffDiffer` | O(n log n) suffix array, high compression | -| **Streaming Hdiff** | `StreamingHdiffDiffer` | FNV-1a hash pre-filtering, streaming for large files | - -### Compression Providers - -| Provider | FormatVersion | Compatibility | -|----------|---------------|---------------| -| **BZip2** | `0x00` | Legacy BSDiff compatible, all platforms | -| **Deflate** | `0x01` | .NET BCL DeflateStream, faster | -| **Brotli** | `0x02` | .NET 6+ BrotliStream, highest compression | - -### Differential Matchers - -```csharp -// Client side — determines which files need patching -public interface IDirtyMatcher -{ - Task ShouldDirty(string relativeFilePath); -} - -// Server/Tool side — determines which files need diff generation -public interface ICleanMatcher -{ - Task ShouldClean(string relativeFilePath); -} -``` - ---- - -## Progress Reporting - -```csharp -await new GeneralClientBootstrap() - .AddListenerProgress((sender, args) => - { - if (args.Progress.Diff != null) - { - Console.WriteLine($"Diff progress: {args.Progress.Diff.Percentage}%"); - } - }) - .SetConfig(config) - .LaunchAsync(); -``` - ---- - -## Error Handling & Rollback - -``` -Middleware execution fails - → AbstractStrategy.HandleExecuteException() - → Fire Exception event - → TryRollback() - → Restore files from backup directory - → Clean up temp files - → Report failure (ReportType.Failure) -``` - ---- - -## Custom Middleware - -### Example: File Scanner - -```csharp -public class FileScanMiddleware : IMiddleware -{ - public async Task InvokeAsync(PipelineContext context) - { - var sourcePath = context.Get(PipelineContext.SourcePath); - var files = Directory.GetFiles(sourcePath, "*.*", - SearchOption.AllDirectories); - Console.WriteLine($"Updated {files.Length} files"); - // Add virus scanning, code signing verification, etc. - } -} -``` - ---- - -## Related Resources - -- **[Architecture](./Architecture.md)** — Pipeline within overall architecture -- **[GeneralUpdate.Differential](../doc/GeneralUpdate.Differential)** — BSDiff differential algorithm -- **[Configuration Reference](./Configuration.md)** — Pipeline-related config options diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Security.md b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Security.md deleted file mode 100644 index dbc663e..0000000 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Security.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Security Guide - -This document details the multi-layered security mechanisms of the GeneralUpdate framework. - ---- - -## Security Architecture Overview - -GeneralUpdate's security model adopts a **Defense in Depth** strategy, establishing multiple layers of protection across transport, authentication, data integrity, and inter-process communication. - ---- - -## 1. Transport Security (TLS/SSL) - -### HTTPS Enforcement - -GeneralUpdate's HTTP client requires HTTPS connections by default. All server communication (version check, download, reporting) should use HTTPS. - -### SSL Certificate Validation - -**Interface:** `ISslValidationPolicy` - -```csharp -public interface ISslValidationPolicy -{ - bool ValidateCertificate( - X509Certificate2 certificate, - X509Chain chain, - SslPolicyErrors sslPolicyErrors); -} -``` - -**Default Policy:** `StrictSslValidationPolicy` — rejects on any `SslPolicyErrors`. - -**Custom SSL Policy:** - -```csharp -// Development only: accept self-signed certificates -public class DevelopmentSslPolicy : ISslValidationPolicy -{ - public bool ValidateCertificate(...) - { - return true; // NEVER use in production! - } -} - -await new GeneralClientBootstrap() - .SslPolicy() - .SetConfig(config) - .LaunchAsync(); -``` - -> **⚠️ Warning:** Never disable SSL validation in production! - ---- - -## 2. Authentication - -### HTTP Auth Provider Interface - -```csharp -public interface IHttpAuthProvider -{ - Task ApplyAuthAsync(HttpRequestMessage request, - CancellationToken cancellationToken); -} -``` - -### Built-in Auth Schemes - -| Scheme | Provider Class | Header | -|--------|---------------|--------| -| **Bearer Token** | `BearerTokenAuthProvider` | `Authorization: Bearer {token}` | -| **API Key** | `ApiKeyAuthProvider` | `X-Api-Key: {key}` (configurable) | -| **HMAC** | `HmacAuthProvider` | `X-Update-Timestamp` + `X-Update-Signature` | -| **None** | `NoOpAuthProvider` | — | - -### HMAC Authentication - -The `HmacAuthProvider` computes HMAC-SHA256 over `body|timestamp`: - -``` -Signature = HMAC-SHA256(requestBody + "|" + timestamp, secretKey) -Headers: - X-Update-Timestamp: 1717488000 - X-Update-Signature: base64_signature -``` - -### Factory - -```csharp -// Auto-select auth scheme by name -var authProvider = HttpAuthProviderFactory.Create( - scheme: "HMAC", - token: null, - secretKey: "your-secret-key"); -``` - ---- - -## 3. Data Integrity - -### SHA256 Hash Verification - -Every downloaded update package is verified by `HashMiddleware` in the pipeline: - -1. Server returns expected hash with version info -2. `HashMiddleware` computes actual hash of downloaded file -3. Compare expected vs actual -4. Mismatch → `CryptographicException` → rollback + failure report - -### Differential Patch Integrity - -BSDiff patches include embedded CRC checksums in control sections. Any data corruption during patch application causes automatic rollback. - ---- - -## 4. IPC Security - -Parameters passed between ClientCore and Core are encrypted using AES-256-CBC. - -| Parameter | Value | -|-----------|-------| -| Algorithm | AES-256-CBC | -| Key Derivation | SHA256("GeneralUpdate.IPC.EnvironmentProvider.v1") | -| Key Length | 256 bits | -| IV Length | 128 bits | -| Temp File Location | `%TEMP%/GeneralUpdate/ipc/` | -| File Lifecycle | Write → Read → Auto-delete | - -### Data Flow - -``` -ClientCore writes: - 1. ProcessContract → JSON serialize - 2. JSON → AES-256-CBC encrypt - 3. Ciphertext → temp file → path to environment variable - -Core reads: - 1. Get temp file path from environment variable - 2. Read ciphertext → AES-256-CBC decrypt - 3. JSON deserialize → ProcessContract - 4. Auto-delete temp file -``` - ---- - -## 5. Backup & Rollback - -### Automatic Backup - -Files are backed up before update to version-named directory: - -``` -{InstallPath}/ -├── app-1.0.0.0/ ← Backup (version-named) -├── app-1.0.1.0/ ← Another version backup -└── MyApp.exe ← Current files -``` - -### Rollback Triggers - -- Main app fails to start after update -- Bowl detects crash -- Middleware execution exception - -### Rollback Flow - -``` -1. Detect failure -2. Restore files from backup directory -3. Clean up temp files -4. Report failure status (ReportType.Failure) -``` - ---- - -## 6. Bowl Process Security - -Bowl monitors the new process after update completion: - -1. Uses ProcDump (Windows) to launch the target process -2. Monitors for unhandled exceptions -3. On crash: - - Generate dump file (memory snapshot) - - Export driver info - - Export system info - - Export system event log - - Auto-rollback to previous version - -**⚠️ Dump files contain full memory snapshots including sensitive data. Restrict access to FailDirectory.** - ---- - -## 7. API Security Best Practices - -### Server Side - -1. **Enforce HTTPS** — All API endpoints must use HTTPS -2. **Require Authentication** — Use Token/HMAC, never expose unauthenticated endpoints -3. **Input Validation** — Validate `AppSecretKey`, `ClientVersion`, `ProductId` formats -4. **Rate Limiting** — Apply rate limits to verification endpoints -5. **Audit Logging** — Log all update requests and results - -### Client Side - -1. **Certificate Pinning** — Implement in custom `ISslValidationPolicy` -2. **Least Privilege** — Only request admin rights when necessary -3. **Config Protection** — Never hardcode `AppSecretKey` -4. **Dump Protection** — Ensure `.dmp` files are not accessible to unauthorized users - ---- - -## 8. Production Security Checklist - -- [ ] All communication uses HTTPS -- [ ] Appropriate `IHttpAuthProvider` configured (Bearer Token or HMAC) -- [ ] Production uses `StrictSslValidationPolicy` (default) -- [ ] Update package SHA256 hashes properly maintained on server -- [ ] `AppSecretKey` uses strong random GUID, unique per product -- [ ] Client app runs with least necessary privileges -- [ ] Bowl dump directory has proper access controls -- [ ] Backup files regularly cleaned to prevent disk exhaustion -- [ ] Complete exception monitoring and error handling implemented - ---- - -## Related Resources - -- **[Architecture](./Architecture.md)** — Security in overall architecture -- **[Configuration Reference](./Configuration.md)** — Security-related config options -- **[GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl)** — Crash monitoring -- **[GeneralUpdate.Core](../doc/GeneralUpdate.Core)** — Client security options diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/System infomation.md b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/System infomation.md deleted file mode 100644 index 1a57a26..0000000 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/System infomation.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -sidebar_position: 6 ---- - -### System Information - -#### (1) Windows Platform - -When an update fails, it might not be clear whether the failure is due to the operating system or other reasons. In such cases, you can use PsInfo to export information about the current operating system, which can help developers troubleshoot the issue. *PsInfo* is a command-line tool that can be used to collect critical information about local or remote Windows NT/2000 systems, including installation type, kernel version, registered organization and owner, number and type of processors, amount of physical memory, system installation date, and expiration date (if it is a trial version). - -#### Using PsInfo - -By default, *PsInfo* displays information about the local system. Specify a remote computer name to retrieve information from a remote system. Since *PsInfo* relies on remote registry access to gather its data, the remote system must have the remote registry service running, and the account running *PsInfo* must have access to the HKLM\System section of the remote registry. - -To assist in automating Service Pack updates, *PsInfo* returns the system's Service Pack number (e.g., 0 for no Service Pack, 1 for SP 1, etc.). - -**Usage: psinfo [[\\computer[,computer[,..] | @file [-u user [-p psswd]]] [-h] [-s] [-d] [-c [-t delimiter]] [filter]** - -| Parameter | Description | -| -------------- | ------------------------------------------------------------ | -| **\\computer** | Execute the command on the specified remote computer(s). If the computer name is omitted, the command runs on the local system. If a wildcard (\\*) is specified, the command runs on all computers in the current domain. | -| **@file** | Run the command on each computer listed in the specified text file. | -| **-u** | Specify an optional username for logging onto the remote computer. | -| **-p** | Specify an optional password for the username. If omitted, you will be prompted to enter a hidden password. | -| **-h** | Show a list of installed hotfixes. | -| **-s** | Show a list of installed applications. | -| **-d** | Show disk volume information. | -| **-c** | Print in CSV format. | -| **-t** | The default delimiter for the -c option is a comma, but you can specify a different character. | -| **filter** | PsInfo will only display data for fields that match the filter. For example, "psinfo service" will only list the service pack field. | - -#### Example Output - -When you run PsInfo, it will output information about the system in a structured format. This information can be used to diagnose and address any issues that may arise during the update process. - -```c# -C:\> psinfo \\development -h -d - -PsInfo v1.6 - local and remote system information viewer -Copyright (C) 2001-2004 Mark Russinovich -Sysinternals - www.sysinternals.com - - System information for \\DEVELOPMENT: - Uptime: 28 days, 0 hours, 15 minutes, 12 seconds - Kernel version: Microsoft Windows XP, Multiprocessor Free - Product type Professional - Product version: 5.1 - Service pack: 0 - Kernel build number: 2600 - Registered organization: Sysinternals - Registered owner: Mark Russinovich - Install date: 1/2/2002, 5:29:21 PM - Activation status: Activated - IE version: 6.0000 - System root: C:\WINDOWS - Processors: 2 - Processor speed: 1.0 GHz - Processor type: Intel Pentium III - Physical memory: 1024 MB - Volume Type Format Label Size Free Free - A: Removable 0% - C: Fixed NTFS WINXP 7.8 GB 1.3 GB 16% - D: Fixed NTFS DEV 10.7 GB 809.7 MB 7% - E: Fixed NTFS SRC 4.5 GB 1.8 GB 41% - F: Fixed NTFS MSDN 2.4 GB 587.5 MB 24% - G: Fixed NTFS GAMES 8.0 GB 1.0 GB 13% - H: CD-ROM CDFS JEDIOUTCAST 633.6 MB 0% - I: CD-ROM 0% - Q: Remote 0% - T: Fixed NTFS Test 502.0 MB 496.7 MB 99% - OS Hot Fix Installed - Q147222 1/2/2002 - Q309521 1/4/2002 - Q311889 1/4/2002 - Q313484 1/4/2002 - Q314147 3/6/2002 - Q314862 3/13/2002 - Q315000 1/8/2002 - Q315403 3/13/2002 - Q317277 3/20/2002 -``` - - - -References：https://learn.microsoft.com/zh-cn/sysinternals/downloads/psinfo \ No newline at end of file diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Systemlog.md b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Systemlog.md deleted file mode 100644 index 627b9e3..0000000 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Systemlog.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -sidebar_position: 5 ---- - -### System Log - -When an upgrade fails, issues such as startup failures or driver installation failures may occur. The Sysmon tool can be used to export system event logs. *System Monitor* (*Sysmon*) is a Windows system service and device driver that, once installed on a system, remains resident across system reboots to monitor and log system activity to the Windows event log. It provides detailed information about process creations, network connections, and file creation time changes. By using [Windows Event Collection](https://msdn.microsoft.com/library/windows/desktop/bb427443(v=vs.85).aspx) or [SIEM](https://en.wikipedia.org/wiki/security_information_and_event_management) agents to collect the generated events, and then analyzing these events, you can identify malicious or anomalous activity and understand how intruders and malware operate on your network. The service runs as a [protected process](https://learn.microsoft.com/windows/win32/services/protecting-anti-malware-services-#system-protected-process), preventing broad user-mode interaction. - -### Sysmon Features Overview - -*Sysmon* includes the following features: - -- Logs processes created with their full command line, along with their parent process. -- Logs hashes of process image files using SHA1 (default), MD5, SHA256, or IMPHASH. -- Supports multiple hashes used simultaneously. -- Includes a process GUID in process creation events to allow correlation of events even when Windows reuses process IDs. -- Includes a session GUID in each event to allow correlation of events on the same logon session. -- Logs the loading of drivers or DLLs with their signatures and hashes. -- Logs raw read access attempts to disks and volumes. -- (Optional) Logs network connections, including source process, IP addresses, port numbers, hostnames, and port names for each connection. -- Detects file creation time changes to determine the true creation time of a file. Modifying file creation timestamps is a common malware tactic to hide its tracks. -- Automatically reloads configuration if changes are made to the registry. -- Performs rule filtering to dynamically include or exclude certain events. -- Generates events at the start of the process to capture activities performed by sophisticated kernel-mode malware. - -Sysmon can be a valuable tool for monitoring system activities and diagnosing issues that arise during system updates or when troubleshooting security incidents. - - - -#### （1）Windows - -address： https://download.sysinternals.com/files/Sysmon.zip - - - -#### （2）Linux - -address：https://github.com/Sysinternals/SysmonForLinux - -doc：https://learn.microsoft.com/zh-cn/sysinternals/downloads/sysmon diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/_category_.json b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/_category_.json index 9f68035..de5a8e8 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/_category_.json +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/_category_.json @@ -1,8 +1,8 @@ { - "label": "Guides", - "position": 7, + "label": "Help", + "position": 3, "link": { "type": "generated-index", - "description": "Platform and operations guides." + "description": "Platform and operations help guides." } } diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md b/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md deleted file mode 100644 index 9abf13b..0000000 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md +++ /dev/null @@ -1,806 +0,0 @@ ---- -sidebar_position: 4 -title: Advanced cookbook ---- - -# GeneralUpdate advanced cookbook - -> **Target audience**: developers who have completed the beginner flow and are integrating GeneralUpdate into production products, CI/CD pipelines, and enterprise release workflows. - -This cookbook complements the [beginner cookbook](./Beginner cookbook.md). The beginner cookbook gets you through your first update loop; this one assumes you've done that and jumps straight into production-grade design. - ---- - -## 1. Production update architecture - -### 1.1 Topology overview - -``` -┌──────────┐ GET version ┌──────────┐ -│ Client │ ──────────────> │ Server │ -│ (main app)│ <── version.json │ (update) │ -└────┬─────┘ └────┬─────┘ - │ │ - │ download patch ZIP │ reads packages/ - ▼ ▼ -┌──────────┐ start + pass ┌──────────┐ -│ Upgrade │ <──────────── │ Client │ -│ (own proc)│ │ │ -└────┬─────┘ └──────────┘ - │ apply patch, report status - ▼ -┌──────────┐ -│ new │ -│ version │ -└──────────┘ -``` - -### 1.2 Role responsibilities - -| Role | Deployment | Responsibility | Key config | -|------|-----------|----------------|------------| -| Client | User endpoint | Version check, package download, launches Upgrade | `UpdateUrl`, `AppSecretKey`, `ClientVersion` | -| Upgrade | Same dir as Client | Independent updater, receives context and applies patch | Passed by Client via `GeneralUpdateBootstrap` | -| Server | Server | Version verification, package download, status reporting | `versions.json`, `/Upgrade/Verification`, `/File/Download` | -| Tools | Dev / CI | Generate patch packages, OSS manifests, hash computation | Input: old/new dirs, Output: `.zip` | -| Bowl | Same dir as Client | Process monitoring, crash detection, backup restore | `MonitorParameter`, dump path | - -### 1.3 Minimum production topology - -For most products: - -- **Dev side**: CI runs `generate_packages.ps1` + Tools to produce patches -- **Server side**: One HTTP Server hosting `versions.json` and `.zip` files; optionally OSS mode with static storage -- **Client side**: Both Client and Upgrade reference `GeneralUpdate.Core` (since the latest version, the former `GeneralUpdate.ClientCore` and `GeneralUpdate.Common` have been merged into `GeneralUpdate.Core`) - -```text -CI (GitHub Actions) Server (HTTP / OSS) -┌─────────────────┐ ┌──────────────────┐ -│ build + publish │ ── push ZIPs ────> │ versions.json │ -│ gen_packages.ps1│ │ *.zip (packages) │ -│ Tools (optional) │ │ static file host │ -└─────────────────┘ └──────────────────┘ -``` - ---- - -## 2. Standardized release artifacts - -### 2.1 Artifact types - -| Type | Generator | Format | Use case | -|------|-----------|--------|----------| -| Full package | `ZipFile.CreateFromDirectory` of full publish dir | `packet_{ts}_{version}.zip` | Cross-version upgrade, first install | -| Patch package | Tools Patch page or `DifferentialCore.Clean` comparing old/new | `patch_{ts}.zip` | Small change set to reduce download | -| Extension package | Tools Extension page | `.zip` (with manifest) | Plugin/extension standalone distribution & update | -| OSS manifest | Tools OSS page | `version.json` | OSS-mode update, suitable for static file hosting | - -### 2.2 `versions.json` field reference - -Each record in the Samples Server `versions.json` controls version matching and download: - -```json -{ - "PacketName": "packet_20260529221936_client_2.0.0.0", - "Hash": "a1b2c3...sha256", - "Version": "2.0.0.0", - "Url": "http://localhost:5000/File/Download/a1b2c3...", - "PubTime": "2026-05-29T14:19:36.0000000", - "AppType": 1, - "Platform": 1, - "ProductId": "2d974e2a-31e6-4887-9bb1-b4689e98c77a", - "IsForcibly": false, - "Format": ".zip", - "Size": 123456, - "IsFreeze": false, - "IsCrossVersion": true, - "FromVersion": "1.0.0.0", - "ToVersion": "2.0.0.0" -} -``` - -| Field | Description | -|-------|-------------| -| `AppType` | `1` = Client (main app), `2` = Upgrade (updater) | -| `Platform` | `1` = Windows, `2` = Linux, `3` = Mac | -| `IsCrossVersion` | `true` = differential package (requires `FromVersion`/`ToVersion`), `false` = full package | -| `IsForcibly` | `true` = forced update, user cannot skip | -| `IsFreeze` | `true` = freeze this version, Server responds "already latest" | -| `ProductId` | Product identifier, must match Client config `ProductId` | - -### 2.3 Packaging scripts - -Samples includes complete PowerShell packaging scripts: - -```powershell -# Generate both full and differential packages -.\src\Server\generate_packages.ps1 - -# Full-only mode (fast, skips Differential) -.\src\Server\generate_packages.ps1 -FullOnly - -# Rebuild versions.json from existing ZIPs -.\src\Server\create_versions_json.ps1 -``` - -Flow: -1. Scans `src/content_client/` and `src/content_upgrade/` for sample content -2. Produces full ZIPs for each version directory -3. Invokes `PatchGenerator` C# project to produce differential ZIPs -4. Computes SHA256 for each ZIP and writes `versions.json` - -**Production recommendation**: adapt these scripts as CI steps, accepting old-version and new-version paths as inputs, outputting to an artifact repository. - ---- - -## 3. CI/CD integration - -### 3.1 GitHub Actions example - -```yaml -name: Generate Update Packages - -on: - push: - tags: - - 'v*.*.*' - -jobs: - generate-packages: - runs-on: windows-latest - steps: - - uses: actions/checkout@v4 - - - name: Setup .NET - uses: actions/setup-dotnet@v4 - with: - dotnet-version: '8.0.x' - - - name: Build release - run: dotnet publish src/Client/ClientSample.csproj -c Release -o publish/v${{ github.ref_name }} - - - name: Generate packages - shell: pwsh - run: | - $oldVersion = "publish/v1.0.0" # download previous release from artifact store - $newVersion = "publish/v${{ github.ref_name }}" - dotnet run --project src/PatchGenerator -- $oldVersion $newVersion packages/ - - - name: Upload artifacts - uses: actions/upload-artifact@v4 - with: - name: update-packages - path: packages/ -``` - -### 3.2 Version mapping strategies - -**Key problem**: CI cannot assume every historical version lives on the build machine. - -**Recommended approaches**: - -| Approach | Description | Best for | -|----------|-------------|----------| -| Artifact repo cache | Upload `publish/v{version}` to an artifact store (GitHub Releases, Artifactory) on every release; CI downloads the versions it needs to diff against | Medium scale, manageable version count | -| Baseline + backfill | Publish a full package every N releases; diffs only compare against the last 2–3 versions | Fast-iterating products | -| On-demand download | Server downloads old-version packages from OSS on the fly for differential comparison | Products with many versions | - -### 3.3 Release checklist - -Confirm before every release: - -- [ ] `Hash` in the new `versions.json` entry matches the uploaded ZIP -- [ ] Differential package `FromVersion` correctly points to the old version -- [ ] Full packages distinguish Client (`AppType=1`) from Upgrade (`AppType=2`) -- [ ] Old versions do not have `IsFreeze` set to `true` (unless intentionally frozen) -- [ ] All ZIPs are downloadable via `GET /File/Download/{hash}` -- [ ] Smoke-test: Client upgrades from the latest old version to the new version - ---- - -## 4. Version strategy - -### 4.1 Version number conventions - -GeneralUpdate follows [Semantic Versioning](https://semver.org/) (SemVer) core principles. On top of SemVer `MAJOR.MINOR.PATCH`, a fourth `Revision` segment is added for .NET `System.Version` compatibility, forming the `Major.Minor.Build.Revision` four-part scheme: - -```text -2.0.0.0 -│ │ │ └── Revision — .NET 4th segment, not in SemVer standard -│ │ └──── Build — maps to SemVer PATCH -│ └────── Minor — maps to SemVer MINOR -└──────── Major — maps to SemVer MAJOR -``` - -Version rules: -- **Major**: incremented for incompatible API changes -- **Minor**: incremented for backwards-compatible new functionality -- **Build** (patch): incremented for backwards-compatible bug fixes -- **Revision**: internal revision, typically `0`; only distinguished in .NET assembly versions - -Server compares with `new Version(string)` — keep the numeric format. See [Semantic Versioning 2.0.0](https://semver.org/) for details. - -### 4.2 Update modes - -| Mode | `UpgradeMode` | Behavior | -|------|---------------|----------| -| Version chain (full) | `1` | Matches only `IsCrossVersion = false` packages; upgrades sequentially from low to high version | -| Cross version (diff) | `2` | Matches only `IsCrossVersion = true` packages; `FromVersion` must exactly match the client's current version | - -### 4.3 Staged rollout - -```text - ┌──────────────┐ -v1.0.0.0 ───────────>│ Full → 2.0.0.0 │ (cross-version jump) - └──────────────┘ - ┌──────────────┐ -v1.0.0.1 ───────────>│ Diff → 2.0.0.0 │ (exact FromVersion match) - └──────────────┘ - ┌──────────────┐ -v1.0.0.2 ───────────>│ Diff → 2.0.0.0 │ - └──────────────┘ -``` - -**Recommendations**: -- Major releases: provide both full and differential packages -- Provide differential upgrade paths for the 3 most recent active versions -- Users more than 3 versions behind go through full upgrade - -### 4.4 Forced updates - -Set `IsForcibly` to `true` in `versions.json`: - -```json -{ "Version": "2.0.1.0", "IsForcibly": true } -``` - -Client-side handling with `AddListenerUpdatePrecheck`: - -```csharp -bootstrap.AddListenerUpdatePrecheck(async (precheckArgs) => -{ - var forcedCount = precheckArgs.Versions.Count(v => v.IsForcibly); - if (forcedCount > 0) - { - // Forced update: don't show a "skip" button - ShowDialog("A critical security update is required."); - return false; // false = do not skip, proceed with update - } - // Optional update: ask the user - return await AskUserWhetherToSkip(); -}); -``` - -### 4.5 Multi-version sequential upgrade - -When the client is multiple versions behind: - -1. Server returns all records above the current version (`IsCrossVersion = false` full packages) -2. Client downloads and applies them in ascending version order -3. After each version upgrade, Upgrade restarts Client, and Client re-queries for the next version - -**Note**: to jump straight to the latest in one hop, provide a single full package (with the latest target version as its `Version`). - ---- - -## 5. Differential strategy - -### 5.1 When to use differential - -| Scenario | Recommendation | Reason | -|----------|---------------|--------| -| User on a recent version | Differential | Only changed files transferred, saves bandwidth | -| User 3+ versions behind | Full | Accumulated changes may exceed full download | -| Emergency security patch | Differential | Fast distribution, minimizes attack window | -| Framework/runtime upgrade | Full | Wide file changes, low diff benefit | -| Large file update (>100MB) | Differential | Significant size reduction even with many changes | - -### 5.2 Differential generation and `delete_files.json` - -A patch package produced by Tools or `DifferentialCore.Clean` contains: - -``` -patch_20260529221936.zip -├── file1.dll.patch ← binary diff file -├── file2_new.dll ← new file (copied directly) -└── generalupdate.delete.json ← files to delete -``` - -`generalupdate.delete.json` format: - -```json -{ - "deleteFiles": [ - "old_plugin.dll", - "deprecated/config.json" - ] -} -``` - -Upgrade applies the patch automatically: -1. Restore `.patch` files via differential application -2. Copy new files -3. Delete files listed in the manifest - -### 5.3 Blacklist configuration - -Some files should never participate in updates (user data, local config, logs, etc.): - -```csharp -new GeneralUpdateBootstrap() - .AddBlacklist(new List - { - "appsettings.json", // user local config - "logs/", // log directory - "*.user", // user-specific files - "cache.db" // local database - }) -``` - -Custom strategy via `IBinaryDiffer` extension point: - -```csharp -// Skip files larger than 100MB for differential — copy them directly instead -public class LargeFileAwareStrategy : DefaultCleanStrategy -{ - public override bool ShouldDiff(string relativePath, FileInfo oldFile, FileInfo newFile) - { - const long maxDiffSize = 100 * 1024 * 1024; - if (newFile.Length > maxDiffSize) - return false; // copy new file as-is, don't generate a .patch - return base.ShouldDiff(relativePath, oldFile, newFile); - } -} -``` - -### 5.4 Parallel processing - -Differential uses parallel processing by default (`StreamingHdiffDiffer`). For large directories (thousands of files): - -- Tune parallelism: `new ParallelOptions { MaxDegreeOfParallelism = Environment.ProcessorCount }` -- For very large files use bsdiff (lower memory, slightly slower) -- For typical files use hdiff (faster, higher memory) - ---- - -## 6. Bowl reliability design - -### 6.1 Bowl lifecycle placement - -```text -┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ -│ Update │ -> │ Bowl │ -> │ Start main│ -> │ Monitor │ -│ complete │ │ launches │ │ app │ │ process │ -└──────────┘ └──────────┘ └──────────┘ └────┬─────┘ - │ - Process exits abnormally - │ - ▼ - ┌──────────┐ - │ Dump file │ - │ Backup old│ - │ Fail JSON │ - └──────────┘ -``` - -### 6.2 Production configuration - -```csharp -public static async Task GuardAsync(string appPath, string installPath) -{ - var lastVersion = "2.0.0.0"; - var processInfo = new MonitorParameter - { - ProcessNameOrId = "MyProduct.App.exe", - DumpFileName = $"{lastVersion}_fail.dmp", - FailFileName = $"{lastVersion}_fail.json", - TargetPath = installPath, - FailDirectory = Path.Combine(installPath, "fail", lastVersion), - BackupDirectory = Path.Combine(installPath, "backup", lastVersion), - WorkModel = "Normal" - }; - - Bowl.Launch(processInfo); -} -``` - -### 6.3 Backup and rollback flow - -1. **Before upgrade**: Bowl backs up current program files to `BackupDirectory` -2. **After upgrade**: Bowl starts the new version of the main app -3. **During monitoring**: Bowl continuously watches the process -4. **On failure**: - - Writes `.dmp` file - - Writes `fail.json` (version, timestamp, system info, driver info) - - If `WorkModel = "Normal"`, auto-restores the old version from backup -5. **After restore**: Bowl relaunches the old version - -### 6.4 Platform differences - -| Feature | Windows | Linux | macOS | -|---------|---------|-------|-------| -| Dump export | MiniDumpWriteDump | Requires `dotnet-dump` or `createdump` | Requires `dotnet-dump` | -| Process monitoring | WMI / Win32 API | procfs (`/proc/{pid}`) | Similar to Linux | -| Backup/restore | File copy + overwrite | File copy + overwrite (watch permissions) | File copy + overwrite | -| Driver info | `driverquery` | `lsmod` / `lspci` | `kextstat` | - -### 6.5 Log integration - -Bowl outputs the following to `fail.json`: - -```json -{ - "version": "2.0.0.0", - "timestamp": "2026-05-29T14:30:00Z", - "processName": "MyProduct.App.exe", - "exitCode": -1073741819, - "systemInfo": { "os": "Windows 11", "arch": "x64" }, - "driverInfo": [], - "dumpPath": "fail/2.0.0.0/2.0.0.0_fail.dmp" -} -``` - -Add a log-upload step in your product to send `fail.json` and `.dmp` to your server for analysis. - ---- - -## 7. Extension system - -### 7.1 Extension lifecycle - -```text -┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ -│ Query │ → │ Download │ → │ Install │ → │ Load into│ -│ available │ │ package │ │ to dir │ │ runtime │ -└──────────┘ └──────────┘ └──────────┘ └────┬─────┘ - │ - ┌────▼─────┐ - │ Update / │ - │ Rollback │ - │ Uninstall │ - └──────────┘ -``` - -### 7.2 Extension manifest specification - -Each extension package should include `extension.json`: - -```json -{ - "id": "com.mycompany.plugin.search", - "name": "Search Plugin", - "version": "1.2.0", - "author": "MyCompany", - "description": "Full-text search capability", - "dependencies": { - "com.mycompany.core": ">=1.0.0" - }, - "platforms": ["win-x64", "linux-x64"], - "minAppVersion": "2.0.0", - "type": "plugin" -} -``` - -### 7.3 Query and install - -```csharp -var manager = new ExtensionManager(options => -{ - options.ExtensionsRootPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "extensions"); - options.TempDownloadPath = Path.Combine(Path.GetTempPath(), "ext_downloads"); - options.ManifestFileName = "extension.json"; -}); - -// Query remote available extensions -var available = await manager.QueryRemoteExtensionsAsync("https://extensions.example.com/api/v1/extensions"); - -// Install -await manager.InstallAsync("com.mycompany.plugin.search", "1.2.0", - progress => Console.WriteLine($"Downloading: {progress.Percentage}%")); - -// Update -await manager.UpdateAsync("com.mycompany.plugin.search", "1.3.0"); - -// Rollback -await manager.RollbackAsync("com.mycompany.plugin.search", "1.2.0"); - -// Uninstall -await manager.UninstallAsync("com.mycompany.plugin.search"); -``` - -### 7.4 Tools extension package generation - -Use the Extension Package page in Tools: - -| Input | Description | -|-------|-------------| -| Extension Source Directory | Source directory of extension files | -| Manifest File | `extension.json` path | -| Output Directory | Extension package ZIP output directory | - -The resulting ZIP contains the manifest and all extension files, ready to push to your extension server. - -### 7.5 Server API contracts - -The extension server should provide these endpoints: - -``` -GET /api/v1/extensions → returns available extension list -GET /api/v1/extensions/{id} → returns extension detail and version list -GET /api/v1/extensions/{id}/versions/{v} → returns version metadata and download link -GET /api/v1/extensions/download/{hash} → downloads the extension package -POST /api/v1/extensions/check → batch compatibility check -``` - ---- - -## 8. Driver updates - -### 8.1 Driver updates vs. application file updates - -| Dimension | App file update | Driver update | -|-----------|----------------|---------------| -| File location | Application directory | System driver directory | -| Permission | Normal user | Administrator / root | -| Activation | Restart application | May require system reboot | -| Signing | None required | Digital signature required (Windows WHQL / Linux DKMS) | -| Rollback complexity | Replace files directly | Uninstall current driver, install old version | -| Compatibility check | Framework version | Kernel version, hardware ID | - -### 8.2 Drivelution update flow - -```csharp -var updater = new DriverUpdater(options => -{ - options.DriverStorePath = @"C:\ProgramData\MyProduct\Drivers"; - options.TempPath = Path.GetTempPath(); - options.RequireSignature = true; - options.BackupBeforeInstall = true; -}); - -// 1. Validate driver package -var validation = await updater.ValidatePackageAsync(driverPackagePath); -if (!validation.IsValid) -{ - Console.WriteLine($"Driver validation failed: {validation.Errors}"); - return; -} - -// 2. Backup current driver -await updater.BackupCurrentDriverAsync("MyDeviceDriver"); - -// 3. Install new driver -var result = await updater.InstallAsync(driverPackagePath); -if (!result.Success) -{ - // 4. Install failed, auto-rollback - await updater.RollbackAsync("MyDeviceDriver"); - Console.WriteLine($"Install failed: {result.ErrorMessage}"); - return; -} - -// 5. Verify new driver health -var health = await updater.HealthCheckAsync("MyDeviceDriver"); -Console.WriteLine($"Driver health: {health.Status}"); -``` - -### 8.3 Windows driver signing - -Production Windows drivers must be signed: - -1. Obtain an EV Code Signing certificate -2. Pass WHQL (Windows Hardware Quality Labs) certification -3. Enable `RequireSignature = true` in `DriverUpdater` - -### 8.4 Linux driver considerations - -- Use `dkms` (Dynamic Kernel Module Support) for kernel module management -- Check kernel version compatibility before updating -- `/lib/modules/$(uname -r)/` typically requires root permissions -- May need `depmod` and `modprobe` after update - -### 8.5 Batch / parallel driver updates - -```csharp -var updaters = new[] -{ - new DriverUpdateTask { DeviceId = "PCI\\VEN_8086", PackagePath = @"drivers\gpu_2.1.0.zip" }, - new DriverUpdateTask { DeviceId = "USB\\VID_0BDA", PackagePath = @"drivers\wifi_1.5.0.zip" }, -}; - -var results = await Parallel.ForEachAsync(updaters, - new ParallelOptions { MaxDegreeOfParallelism = 4 }, - async (task, ct) => - { - var updater = new DriverUpdater(/* ... */); - return await updater.InstallAsync(task.PackagePath); - }); - -foreach (var r in results) -{ - Console.WriteLine($"Driver {r.DeviceId}: {(r.Success ? "OK" : "FAILED")}"); -} -``` - ---- - -## 9. Security and compliance - -### 9.1 Hash validation - -GeneralUpdate automatically validates SHA256 after download: - -```powershell -# Server-side: generate hash (PowerShell) -(Get-FileHash -Path .\packet.zip -Algorithm SHA256).Hash.ToLowerInvariant() - -# Or use the Tools OSS page -``` - -Client-side auto-validation: after download, Core computes SHA256 on the downloaded file and compares it against the `Hash` field in `versions.json`. Mismatch triggers discard and retry (up to 3 times). - -### 9.2 Authenticated downloads - -Server supports passing a token in download requests: - -```csharp -// Client-side: add auth header to requests -new GeneralUpdateBootstrap() - .AddListenerDownloadConfig(config => - { - config.Headers = new Dictionary - { - ["Authorization"] = $"Bearer {GetAccessToken()}" - }; - }); -``` - -**Production recommendations**: -- Use short-lived JWT tokens -- Download endpoint validates token scope (only allow download for the specified `ProductId`) -- Log every download's token, IP, and timestamp to an audit log - -### 9.3 OSS mode security - -OSS mode uses static file services (Alibaba Cloud OSS, AWS S3, etc.): - -``` -# Recommended OSS bucket policy -{ - "Statement": [ - { - "Effect": "Allow", - "Principal": {"Anonymous": ["*"]}, - "Action": ["oss:GetObject"], - "Resource": ["acs:oss:my-bucket:packages/*.zip"], - "Condition": { - "IpAddress": {"acs:SourceIp": ["your-server-ip-range"]} - } - }, - { - "Effect": "Allow", - "Principal": {"Anonymous": ["*"]}, - "Action": ["oss:GetObject"], - "Resource": ["acs:oss:my-bucket:packages/versions.json"] - } - ] -} -``` - -### 9.4 Release audit checklist - -Confirm before every production release: - -- [ ] All `Hash` values in `versions.json` match the SHA256 of uploaded ZIPs -- [ ] Download endpoint uses HTTPS (HTTP is prohibited in production) -- [ ] `AppSecretKey` is correctly configured to prevent unauthorized version queries -- [ ] `IsFreeze` flag on old versions is correct (don't freeze versions still in active use) -- [ ] Differential package `FromVersion`/`ToVersion` paths are correct -- [ ] All files are CI-signed and untampered -- [ ] Production release record written to audit log - ---- - -## 10. Failure drills - -### 10.1 Scenario: download failure / network interruption - -**How to simulate**: disconnect the network or stop the Server during Client download. - -**Expected behavior**: -- Client throws `DownloadException` -- Resume-from-breakpoint kicks in automatically: download continues on next launch -- Download progress reported via `AddListenerMultiDownloadStatistics` - -**Verification**: -```csharp -bootstrap.AddListenerMultiDownloadError((version, exception) => -{ - Console.WriteLine($"[Download Error] {version.Version}: {exception.Message}"); - // Production integration: alerting -}); -``` - -### 10.2 Scenario: file lock - -**How to simulate**: before Upgrade applies the patch, manually open a DLL in the target directory (e.g., with Notepad). - -**Expected behavior**: -- Upgrade encounters `IOException` when attempting to replace the file -- Retries 3 times (500ms intervals) -- If still failing, fires `AddListenerException` callback -- Other already-updated files are not corrupted - -### 10.3 Scenario: post-upgrade startup crash - -**How to simulate**: replace `UpgradeSample.exe` in `content_upgrade` with a fake exe that crashes immediately. - -**Expected behavior**: -- Client completes update and launches the new version -- Bowl detects abnormal process exit -- Bowl writes `.dmp` and `fail.json` to `fail/{version}/` -- Bowl restores the old version from `backup/{version}/` -- Old version starts successfully - -**Verification**: -1. Check `fail/` directory for dump and JSON files -2. Confirm old version was restored and launched -3. Server receives failure status via `/Upgrade/Report` - -### 10.4 Scenario: corrupted patch package - -**How to simulate**: manually modify a patch ZIP in `packages/` (e.g., open with a text editor and tweak a few bytes). - -**Expected behavior**: -- Client validates SHA256 after download — mismatch detected -- Automatically discards the corrupted file and re-downloads (up to 3 times) -- After 3 failures, notifies via `AddListenerMultiDownloadError` -- Corrupted patch is never applied - -### 10.5 Scenario: insufficient permissions - -**How to simulate**: on Linux, run Upgrade as a non-root user with write permissions removed from the target directory. - -**Expected behavior**: -- Upgrade encounters `UnauthorizedAccessException` when trying to write -- Notified via `AddListenerException` -- No partial update (atomicity preserved) - -**Prevention**: -```csharp -// Client validates target directory permissions before launching Upgrade -if (!HasWritePermission(installDirectory)) -{ - RequestAdminPrivilege(); - return; -} -``` - -### 10.6 Failure drill schedule - -Run a full failure drill once per release cycle: - -| Drill | Frequency | Owner | Verification | -|-------|-----------|-------|-------------| -| Download resume | Every release | QA | Check resume-from-breakpoint logs | -| File lock handling | Every release | QA | Check rollback behavior | -| Startup crash recovery | Monthly | DevOps | Bowl fail dir + Server report | -| Patch corruption validation | Every release | QA | Download log SHA256 mismatch | -| Permission handling | Every major version | DevOps | Linux platform test | -| Diff package integrity | Every release | CI | Automated tree comparison test | - ---- - -## Appendix: related resources - -- [GeneralUpdate.Core component docs](../doc/GeneralUpdate.Core.md) -- [GeneralUpdate.Differential component docs](../doc/GeneralUpdate.Differential.md) -- [GeneralUpdate.Bowl component docs](../doc/GeneralUpdate.Bowl.md) -- [GeneralUpdate.Drivelution component docs](../doc/GeneralUpdate.Drivelution.md) -- [GeneralUpdate.Extension component docs](../doc/GeneralUpdate.Extension.md) -- [GeneralUpdate.Tools reference](../doc/GeneralUpdate.PacketTool.md) -- [Beginner cookbook](./Beginner cookbook.md) -- [Samples repository](https://github.com/GeneralLibrary/GeneralUpdate-Samples) -- [Tools repository](https://github.com/GeneralLibrary/GeneralUpdate.Tools) - -> **Contributing**: if you have production experience to share, PRs and issues are welcome at [GeneralUpdate-Samples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/issues). diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Beginner cookbook.md b/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Beginner cookbook.md index 1d73899..aec4cab 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Beginner cookbook.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Beginner cookbook.md @@ -13,8 +13,8 @@ This cookbook is for first-time GeneralUpdate users. The goal is not to explain | --- | --- | --- | --- | | Hub | `src\Hub` | Interactive sample browser; run update scenarios via menu | [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md) | | Server | `src\Server` | Returns version metadata, accepts reports, and serves package downloads | [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md) | -| Packet | `src\Server\wwwroot\packages` | Downloadable `.zip` packages and `versions.json` metadata | [GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool.md) | -| Tools | GeneralUpdate.Tools repository | Generates patch packages, hashes, OSS manifests, and simulation reports | [GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool.md) | +| Packet | `src\Server\wwwroot\packages` | Downloadable `.zip` packages and `versions.json` metadata | [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md) | +| Tools | GeneralUpdate.Tools repository | Generates patch packages, hashes, OSS manifests, and simulation reports | [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md) | | Bowl | Integrated in Hub Samples | Monitors process failures and exports failure data | [GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl.md) | | Differential | Hub Samples + Core default integration | Generates old/new binary differences and applies them during updates | [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential.md) | @@ -240,7 +240,20 @@ Try running each sample and observe the results in the `mock_app` directory. After this flow works, read these pages in order: 1. [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md): update strategies, event notifications, silent updates, and manifest-based minimal configuration. -2. [GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool.md): patch packages, Hash, OSS Config, and Simulation. +2. [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md): patch packages, Hash, OSS Config, and Simulation. 3. [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential.md): differential algorithms, parallel processing, and Clean/Dirty. 4. [GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl.md): crash monitoring, backup, and failure recovery. -5. [Advanced Cookbook](./Advanced cookbook.md): production deployment, CI/CD integration, enterprise solution design. +5. [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md): patch packages, Hash, OSS Config, and Simulation. + +## Sample UI + +Sample application interface preview: + +![](imgs\sampleclient.png) + +![](imgs\sampleupgrade.png) + +| Repository | +| --- | +| [ClientSample.sln](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/ClientSample.sln) | +| [UpgradeSample.sln](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/UpgradeSample.sln) | diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.PacketTool.md b/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/GeneralUpdate.PacketTool.md similarity index 100% rename from website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.PacketTool.md rename to website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/GeneralUpdate.PacketTool.md diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Quik start.md b/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Quik start.md deleted file mode 100644 index c8cc4df..0000000 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Quik start.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -slug: quikstart -title: GeneralUpdate -authors: juster -tags: [quikstart] ---- - - - -## Step1 - -Download the Sample repository from GitHub. Before using the sample, make sure you have .NET 8 runtime environment installed locally. - -- https://github.com/GeneralLibrary/GeneralUpdate-Samples - -The repository directory contents are as follows: - -![](imgs/content.png) - -| Name | Description | -| ------------- | ------------------------------------- | -| Client | Main client sample program | -| Server | Server sample program | -| StartManager | Update process console | -| Upgrade | Upgrade client sample program | -| process.bat | Not required for attention | -| resource.bat | Not required for attention | -| start.cmd | Script to start the update sample | -| oss_start.cmd | Script to start the update OSS sample | - - - -## Step2 - -Locate the file directory and double-click (the start.cmd script resets the local directory each time it is launched, so manual directory management is unnecessary): - -```shell -...\GeneralUpdate-Samples\src\start.cmd -``` - -![](imgs/build.png) - - - -The automatic process will begin compiling and copying all related project bin directories to the app directory: - -``` -...\GeneralUpdate-Samples\src\run\app -``` - -![](imgs/build.png) - - - -Upon entering the app directory, you will see the setup prior to the upgrade. - -![](imgs/rundir.png) - - - -## Step3 - -After checking the app directory: - -- Enter option 1 and press Enter -- The server sample program will start -- The main client sample program will start, initiating the update request (once the main client program update is complete, it will close automatically). - -![](imgs/upgrade.png) - - - -Once the main client program closes automatically, check the run\app directory again. You will notice a new backup directory named "app-1.0.0.0" and a file named "Congratulations on the update.txt". - -![](imgs/rundir2.png) - -Seeing this indicates that you have successfully completed an upgrade. Congratulations! - -![](imgs/result.png) diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Sample UI.md b/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Sample UI.md deleted file mode 100644 index 844822c..0000000 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/Sample UI.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -slug: sampleui -title: UI -authors: juster -tags: [sampleui] ---- - -## Sample UI - -![](imgs/sampleclient.png) - -![](imgs/sampleupgrade.png) - - - -| Repository URL | -| ------------------------------------------------------------ | -| https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/ClientSample.sln | -| https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/UpgradeSample.sln | - diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/releaselog/GeneralUpdateReleaselog.md b/website/i18n/en/docusaurus-plugin-content-docs/current/releaselog/GeneralUpdateReleaselog.md index 4d77b8a..18409e2 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/releaselog/GeneralUpdateReleaselog.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/releaselog/GeneralUpdateReleaselog.md @@ -7,6 +7,16 @@ tags: [log] # 📒Release log +### 📍2026-05-20 — v10.5.0-beta.2 + +- **GeneralUpdate.Core**: 统一 `GeneralUpdateBootstrap` 入口，合并原 ClientCore 和 Core 能力；新增 `SetSource()` 轻配置入口与 `generalupdate.manifest.json` 极简接入；重构下载子系统为可替换的 5 层模型（Source/Policy/Executor/Pipeline/Orchestrator）；扩展点体系增至 10 个可替换接口 +- **GeneralUpdate.Bowl**: `BowlContext` 配置 API 稳定；优化 Windows/Linux/macOS ProcDump 集成 +- **GeneralUpdate.Differential**: 稳定 `IBinaryDiffer` 抽象；BSDIFF 4.0 + Streaming HDiff 双算法；BZip2 / Deflate 压缩 +- **GeneralUpdate.Drivelution**: 稳定跨平台驱动更新流水线；Windows pnputil / Linux insmod-dpkg-rpm / macOS kextload-installer +- **GeneralUpdate.Extension**: 稳定 `IExtensionHost` 抽象；Zip Slip 安全解压；拓扑排序依赖解析 +- **文档**: 重构全部 5 个组件文档为统一模板；新增入门实战手册；新增软件外包服务页面 +- **Samples**: Hub 示例浏览器 9 个场景覆盖完整更新/OSS/静默/推送/差分/压缩/扩展/Bowl/驱动 + ### 📍2026-04-10 - Add `AddListenerUpdatePrecheck(Func)` to `GeneralClientBootstrap` — unified entry that receives the full version info and returns `true` to skip or `false` to proceed; replaces the combined use of `AddListenerUpdateInfo` + `SetCustomSkipOption`. Forced-update (`IsForcibly`) versions always proceed regardless of the callback return value. @@ -22,11 +32,11 @@ tags: [log] -- ### 📍2026-01-06 10.0.0 +### 📍2026-01-06 10.0.0 - - Adapt to .NET 10 upgrade and update the versions of referenced components. - - Add scripted execution of GeneralUpdate via `dotnet run x.cs` for .NET 10. - - Refactor part of the functions. +- Adapt to .NET 10 upgrade and update the versions of referenced components. +- Add scripted execution of GeneralUpdate via `dotnet run x.cs` for .NET 10. +- Refactor part of the functions. @@ -45,9 +55,9 @@ tags: [log] -## 📍2025-01-13 9.1.5 +## 📍2025-01-14 9.1.5 -- Fix the issue with incorrect value retrieval for LastVersion. +- Fix the issue with incorrect value retrieval for LastVersion. @@ -86,7 +96,7 @@ tags: [log] -## 📍2024-11-28 +## 📍2024-11-28 9.0.0 - Upgrade all components to C# 13 syntax. @@ -1027,7 +1037,7 @@ namespace MyProcessSample { class MyProcess { - // This code is from MSDN + //此段代码来自于msdn // Opens the Internet Explorer application. void OpenApplication(string myFavoritesPath) { diff --git a/website/i18n/en/docusaurus-theme-classic/navbar.json b/website/i18n/en/docusaurus-theme-classic/navbar.json index a2897c6..0f49d31 100644 --- a/website/i18n/en/docusaurus-theme-classic/navbar.json +++ b/website/i18n/en/docusaurus-theme-classic/navbar.json @@ -7,40 +7,24 @@ "message": "GeneralLibrary Logo", "description": "The alt text of navbar logo" }, - "item.label.文档": { - "message": "文档", - "description": "Navbar item with label 文档" - }, - "item.label.生态伙伴": { - "message": "生态伙伴", - "description": "Navbar item with label 生态伙伴" - }, - "item.label.企业合作": { - "message": "企业合作", - "description": "Navbar item with label 企业合作" + "item.label.Doc": { + "message": "Doc", + "description": "Navbar item with label Doc" }, - "item.label.关于": { - "message": "关于", - "description": "Navbar item with label 关于" + "item.label.商务": { + "message": "Business", + "description": "Navbar item with label 商务" }, "item.label.GitHub": { "message": "GitHub", "description": "Navbar item with label GitHub" }, - "item.label.Doc": { - "message": "Doc", - "description": "Navbar item with label Doc" - }, - "item.label.Ecological partners": { - "message": "Ecological partners", - "description": "Navbar item with label Ecological partners" - }, - "item.label.Cooperative enterprises": { - "message": "Cooperative enterprises", - "description": "Navbar item with label Cooperative enterprises" + "item.label.GeneralSpacestation": { + "message": "GeneralSpacestation", + "description": "Navbar item with label GeneralSpacestation" }, - "item.label.About": { - "message": "About", - "description": "Navbar item with label About" + "item.label.软件外包服务": { + "message": "Software Outsourcing", + "description": "Navbar item with label 软件外包服务" } } diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json index 01830c6..aacdb71 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json @@ -7,33 +7,13 @@ "message": "快速入门", "description": "The label for category Quick Start in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Advanced Cookbook": { - "message": "高级实战手册", - "description": "The label for category Advanced Cookbook in sidebar tutorialSidebar" - }, "sidebar.tutorialSidebar.category.Components": { "message": "组件文档", "description": "The label for category Components in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Tools": { - "message": "工具", - "description": "The label for category Tools in sidebar tutorialSidebar" - }, - "sidebar.tutorialSidebar.category.Infrastructure": { - "message": "基础设施", - "description": "The label for category Infrastructure in sidebar tutorialSidebar" - }, - "sidebar.tutorialSidebar.category.OSS Update Mode": { - "message": "OSS 更新模式", - "description": "The label for category OSS Update Mode in sidebar tutorialSidebar" - }, - "sidebar.tutorialSidebar.category.Utilities": { - "message": "工具类", - "description": "The label for category Utilities in sidebar tutorialSidebar" - }, - "sidebar.tutorialSidebar.category.Guides": { - "message": "指南", - "description": "The label for category Guides in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.帮助": { + "message": "帮助", + "description": "The label for category 帮助 in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Release Log": { "message": "发布日志", diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md deleted file mode 100644 index 89dea99..0000000 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -sidebar_position: 9 ---- - -### 定义 - -命名空间：GeneralUpdate.Core - -程序集：GeneralUpdate.Core.dll - - - -**OSS** - -OSS的全称是对象存储服务（Object Storage Service），做服务端技术栈开发的小伙伴肯定对这个不陌生在 各大云服务器厂商都会提供类似的服务,说简单点就是一个文件服务器。例如：阿里云OSS、腾讯云COS、华为云OBS，其实它们只是名字不一样功能服务都差不多。然后本更新组件新功能的实现思路非常相似那么就 选择了OSS来为该功能命名，而且方便开发者一眼能get到这个功能的作用（需要使用组件 GeneralUpdate.Core）。 - - - -**GeneralClientOSS** - -GeneralClientOSS类是另外一种更新机制与GeneralClientBootstrap不同的是，GeneralClientOSS不需要编写服务端的代码直接根据OSS文件服务器的version.josn的版本信息进行更新，简化了新手使用本组件的门槛。 - -```c# -public sealed class GeneralClientOSS -``` - - - -### 示例 - -| 说明 | 地址 | -| ------------------------- | ------------------------------------------------------------ | -| 代码示例地址 | [进入](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/OSS) | -| 哈希算法（sha256） | [进入](https://github.com/GeneralLibrary/GeneralUpdate/blob/master/src/c%23/GeneralUpdate.Core/Pipeline/HashMiddleware.cs) | -| 测试脚本（oss_start.cmd） | [进入](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src) | -| versions.json 制作工具 | [进入](https://github.com/GeneralLibrary/GeneralUpdate.Tools) | - - - -#### OSS流程 - -![](imgs/oss_flow.png) - -1.准备version.json版本信息配置文件，更新文件（update.zip）打包可以直接通过压缩软件（7zip等免费软件）进行手动打包。 - -```json -[ - { - "PacketName": "packet_20250102230201638_1.0.0.1", - "Hash": "ad1a85a9169ca0083ab54ba390e085c56b9059efc3ca8aa1ec9ed857683cc4b1", - "Version": "1.0.0.1", - "Url": "http://localhost:5000/packages/packet_20250102230201638_1.0.0.1.zip", - "PubTime": "2025-01-02T23:48:21" - } -] -``` - -2.Client启动时直接请求OSS服务器或文件服务器，下载version.json文件。 - -![](imgs/oss_util.png) - -3.下载到本地之后解析版本信息内容判断是否需要更新，如果将信息通过进程启动传递Upgrade（Client自我 关闭）。 - -4.Upgrade启动之后直接去下载update.zip，下载到本地之后直接解压覆盖本地文件。 - -5.Upgrade更新完成之后把Client启动起来，自我关闭。更新结束。 GeneralUpdateOSS的功能和GeneralUpdateBootstrap功能对比来说，使用的门槛非常低如果公司对自动 更新的要求不高的话可以使用这个功能。一句话概括这个功能就是下载version.json根据文件里的内容去逐 版本下载更新包，下载下来之后直接解压更新就结束了。 - -6.由于OSS功能没有包含黑名单机制，制作update.zip时需要注意请勿将以下组件内部使用的文件添加到包内，或直接发布成single file避免占用降低更新复杂度。 - -```json -"Microsoft.Bcl.AsyncInterfaces.dll", -"System.Collections.Immutable.dll", -"System.IO.Pipelines.dll", -"System.Text.Encodings.Web.dll", -"System.Text.Json.dll" -``` - - - -以下示例定义方法，包含GeneralClientOSS、GeneralUpdateOSS 使用示例： - -GeneralClientOSS： - -```c# -using System.Text; -using GeneralUpdate.Core; - - -var paramsOSS = new GlobalConfigInfoOSS -{ - Url = "http://localhost:5000/packages/versions.json", - CurrentVersion = "1.0.0.0", - VersionFileName = "versions.json", - AppName = "OSSClientSample.exe", - Encoding = Encoding.UTF8.WebName -}; - -await GeneralClientOSS.Start(paramsOSS, "OSSUpgradeSample.exe"); -``` - - - -GeneralUpdateOSS： - -``` -using GeneralUpdate.Core; - -/* - * GeneralUpdateOSS will by default read the JSON content of GlobalConfigInfoOSS stored in the system environment variables by GeneralClientOSS - * , and developers do not need to be concerned with the entire process. - * - * Environment.GetEnvironmentVariable("GlobalConfigInfoOSS", EnvironmentVariableTarget.User); - * - * Typically, GeneralClientOSS and GeneralUpdateOSS appear as a pair. - */ -try -{ - await GeneralUpdateOSS.Start(); -} -catch (Exception ex) -{ - Console.WriteLine(ex.Message); -} -``` - - - -### 适用于 - -| 产品 | 版本 | -| -------------- | ------------- | -| .NET | 5、6、7、8、9、10 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | \ No newline at end of file diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md deleted file mode 100644 index 20f2117..0000000 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -sidebar_position: 8 ---- - -### GeneralTracer - -> **合并说明**：`GeneralUpdate.Common` 已合并到 `GeneralUpdate.Core`。`GeneralTracer` 现在位于 `GeneralUpdate.Core` 命名空间内，引用 `GeneralUpdate.Core` 包即可自动获得，无需单独引用。 - -命名空间：`GeneralUpdate.Core` - -程序集：`GeneralUpdate.Core.dll` - -`GeneralTracer` 提供组件内部异常信息和执行流程的追踪输出。它默认启用，引用 `GeneralUpdate.Core` 时会自动包含。 - -```c# -public static class GeneralTracer -``` - - - -### Example - -该机制默认开启，将组件内部的异常信息、部分执行流程信息同时可通过IDE控制台、log文件、Dbgview调试工具进行查看和分析。 - -```c# -//如果在生产环境或不需要使用Trace机制，可通过以下方法关闭，默认开启。 -GeneralTracer.SetTracingEnabled(false); - -//在引导类之前调用即可。 - _ = await new GeneralClientBootstrap() - .LaunchAsync(); -``` - - - -#### IDE控制台 - -![](imgs\IDE.png) - - - -#### Log文件 - -```c# -该文件默认生成在运行目录下的Logs文件夹中，文件名格式为generalupdate-trace [today].log 该log未依赖第三方组件。 -``` - -![](imgs\log.png) - - - -#### Dbgview调试工具 - -![](imgs\DebugView.png) - - - -### 适用于 - -| Product | Versions | -| -------------- | ---------------- | -| .NET | 5, 6, 7, 8, 9, 10 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | - diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Maui.OSS.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Maui.OSS.md deleted file mode 100644 index 162b656..0000000 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Maui.OSS.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_position: 10 ---- - -### 定义 - -命名空间：GeneralUpdate.Maui.OSS - -程序集：GeneralUpdate.Maui.OSS.dll - - - -GeneralUpdate.Maui.OSS组件用来实现.NET MAUI更新的机制，目前只支持安卓平台的自动升级。 - -```c# -public sealed class GeneralUpdateOSS -``` - - - -### 示例 - -​ ![](imgs/maui_android_upgrade.png) - -![](imgs/oss_maui_flow.png) - -1.准备version.json版本信息配置文件，更新文件（update.apk）更新文件就直接是新版本的apk了 (或.abb)。 - -2.Client启动时直接请求OSS服务器或文件服务器，下载version.json文件。 - -```json -{ - "PubTime": 1680444916, - "Name": "com.companyname.generalupdate.ossclient", - "MD5": "9bf414990a67e74f11752d03f49b15d8", - "Version": "1.0.5", - "Url": "http://192.168.50.203/com.companyname.generalupdate.ossclient.apk" -} -``` - -3.下载到本地之后解析版本信息内容，判断是否需要更新。 4.需要更新则下载update.apk。 5.下载完成之后执行安装，这一步就交给了安卓操作系统执行。执行完成之后运行新版本app。 - - - -以下示例定义方法，包含GeneralUpdateOSS使用方法。 - -```c# -Task.Run(async () => -{ - var url = "http://192.168.50.203"; - var apk = "com.companyname.generalupdate.ossclient.apk"; - var authority = "com.generalupdate.oss.fileprovider"; - var currentVersion = "1.0.0.0"; - var versionFileName = "version.json"; - GeneralUpdateOSS.AddListenerDownloadProcess(OnOSSDownload); - GeneralUpdateOSS.AddListenerException(OnException); - await GeneralUpdateOSS.Start(new ParamsAndroid(url, apk, authority, currentVersion, versionFileName)); -}); -``` - - - -### 注解 - -GeneralUpdateOSS提供以下能力。 - -#### 属性 - -| Properties | | -| ------------- | ------------------------ | -| ParamsAndroid | 安卓平台的跟新配置参数。 | - - - -#### 方法 - -| Method | | -| ---------------------------- | --------------------------- | -| Start() | 开始针对安卓平台的OSS更新。 | -| AddListenerDownloadProcess() | 监控下载进度。 | -| AddListenerException() | 监听内部异常信息。 | - - - -### 🌴ParamsAndroid - -**属性** - -**Url** string http的api服务端请求地址。 - -**Apk** string 安卓apk名称。 - -**CurrentVersion** string 当前版本。 - -**Authority** string apk作者。 - -**VersionFileName** string 版本文件名称。 - - - -### 🌼Start() - -**方法** - -开始针对安卓平台的OSS更新。 - -```c# -public static async Task Start(ParamsAndroid parameter) where TStrategy : AbstractStrategy, new(); -``` - - - -**参数类型** - -ParamsAndroid 安卓平台的跟新配置参数，详细内容参考本文档 🌴ParamsAndroid。 - - - -**参数** - -**parameter** ParamsAndroid 安卓平台的跟新配置参数。 - - - -### 🌼AddListenerDownloadProcess() - -**方法** - -监控下载进度。 - -```c# -public static void AddListenerDownloadProcess(Action callbackAction); -``` - - - -**参数类型** - -**sender** object - -操作句柄。 - -**args** OSSDownloadArgs - -下载进度通知参数。 - - - -**参数** - -```c# -callbackAction Action -``` - -监听当前版本下载进度事件回传参数。 - - - -### 🌼AddListenerException() - -**方法** - -监听内部异常信息。 - -```c# -public static void AddListenerException(Action callbackAction); -``` - - - -**参数类型** - -**sender** object - -操作句柄。 - -**args** ExceptionEventArgs - -更新异常参数。 - - - -**参数** - -```c# -callbackAction Action -``` - -监听当前版本下载进度事件回传参数。 - - - -### 适用于 - -| 产品 | 版本 | -| --------- | ---------------- | -| .NET | 7、8、9 | -| .NET MAUI | .NET 8 - Android | \ No newline at end of file diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/outsourcing.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/outsourcing.md new file mode 100644 index 0000000..ff77399 --- /dev/null +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/outsourcing.md @@ -0,0 +1,37 @@ +--- +sidebar_position: 99 +--- + +# 软件外包服务 + +GeneralLibrary 团队提供专业的 .NET 软件外包服务，涵盖以下领域： + +## 服务范围 + +| 服务类别 | 说明 | +| --- | --- | +| 自动更新系统集成 | 基于 GeneralUpdate 为企业级应用搭建完整的自动更新体系，包括版本管理、差分包生成、灰度发布、回滚策略 | +| 桌面应用开发 | WPF / WinForms / Avalonia / WinUI / MAUI 跨平台桌面应用开发 | +| Web 后端开发 | ASP.NET Core Web API、SignalR 实时通信、微服务架构设计与实现 | +| 驱动更新方案 | 基于 GeneralUpdate.Drivelution 的跨平台驱动更新方案设计与集成 | +| 插件/扩展系统 | 基于 GeneralUpdate.Extension 的插件生态搭建，支持远程查询、下载、安装、依赖管理 | +| CI/CD 流水线 | 基于 GitHub Actions / Azure DevOps 的自动化构建、测试、发布流水线 | +| 技术咨询 | 架构评审、性能优化、代码重构、安全审计 | + +## 技术栈 + +- **.NET**: .NET 8/9/10, ASP.NET Core, WPF, Avalonia, MAUI +- **数据库**: SQL Server, PostgreSQL, MySQL, Redis +- **云服务**: Azure, AWS, 阿里云 +- **DevOps**: GitHub Actions, Azure Pipelines, Docker, Kubernetes + +## 联系方式 + +| 渠道 | 信息 | +| --- | --- | +| GitHub | [GeneralLibrary](https://github.com/GeneralLibrary) | +| 邮箱 | 请通过 GitHub Issues 联系 | + +--- + +欢迎各行业企业客户洽谈合作，我们将根据您的具体需求提供定制化解决方案。 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/Driver.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/Driver.md deleted file mode 100644 index 38e71be..0000000 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/Driver.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -sidebar_position: 3 ---- - -### Driver 驱动 - -#### （1）Windows平台 - -##### 驱动安装 - -本组件内置使用的驱动安装工具为微软自带的工具PnPutil.exe或使用setupapi.dll来实现。 - -驱动安装时需要注意的问题有两点： - -| 名称 | 说明 | -| ---- | ---------------------------------- | -| 安装 | 驱动证书安装，需要在驱动之前安装。 | -| 版本 | 区分x86 , x64版本。 | - -**PnPUtil实现：** - -PnPUtil是一个命令行实用程序，它可以用来管理Windows的驱动程序商店。你可以使用它来添加、删除和列出驱动程序。 - -以下是如何使用PnPUtil来安装驱动程序的步骤： - -1. 打开命令提示符（以管理员身份）。 - -2. 导航到包含驱动程序的INF文件的目录。 - -3. 运行以下命令： - - `pnputil /add-driver ` - - 例如，如果你的INF文件名为`mydriver.inf`，那么你应该运行`pnputil /add-driver mydriver.inf`。 - -4. PnPUtil将会添加驱动程序到驱动程序商店，并尝试为任何匹配的设备安装驱动程序。 - -注意，PnPUtil需要管理员权限才能运行。 - -在C#中，你可以使用System.Diagnostics.Process类来运行PnPUtil。以下是一个例子： - -```c# -using System.Diagnostics; - -public class Program -{ - public static void Main() - { - string infPath = "Path to your INF file"; - - Process process = new Process(); - process.StartInfo.FileName = "pnputil.exe"; - process.StartInfo.Arguments = "/add-driver " + infPath; - process.StartInfo.Verb = "runas"; // 运行为管理员 - process.Start(); - - process.WaitForExit(); - } -} -``` - - - -**setupapi.dll实现：** - -```c# -using System; -using System.Runtime.InteropServices; - -public class Program -{ - // 定义 SetupCopyOEMInf 函数的 P/Invoke 签名 - [DllImport("setupapi.dll", EntryPoint = "SetupCopyOEMInf", SetLastError = true)] - public static extern bool SetupCopyOEMInf( - string SourceInfFileName, - string OEMSourceMediaLocation, - int OEMSourceMediaType, - int CopyStyle, - string DestinationInfFileName, - int DestinationInfFileNameSize, - ref int RequiredSize, - string DestinationInfFileNameComponent - ); - - public static void Main() - { - string infPath = "Path to your INF file"; - bool result = SetupCopyOEMInf(infPath, null, 0, 0, null, 0, ref int size, null); - - if (!result) - { - Console.WriteLine("Failed to install driver. Error code: " + Marshal.GetLastWin32Error()); - } - } -} -``` - - - -##### 驱动证书 - -本组件内置使用Windows的证书管理工具（CertMgr.exe）或者使用.NET框架中的X509Store类来实现。 - -**CertMgr.exe实现：** - -`CertMgr.exe` 是一个命令行工具，它是微软的.NET Framework的一部分。你可以在.NET Framework的安装目录中找到它。 - -对于大多数系统，它的位置通常是在以下目录之一： - -- `C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Bin` -- `C:\Program Files\Microsoft SDKs\Windows\v7.0A\Bin` - -如果你找不到它，你可以使用Windows的搜索功能来搜索`CertMgr.exe`。 - -注意，`CertMgr.exe`是一个命令行工具，你需要在命令提示符或PowerShell中运行它。你也可以在你的C#代码中使用`System.Diagnostics.Process.Start()`方法来调用它。 - - - -**X509Store实现：** - -```c# -using System; -using System.Security.Cryptography.X509Certificates; - -public class Example -{ - public static void Main() - { - string CertificatePath = "Path to your certificate file"; - - // 创建一个新的X509证书实例 - X509Certificate2 certificate = new X509Certificate2(CertificatePath); - - // 打开当前用户的个人证书存储区 - X509Store store = new X509Store(StoreName.My, StoreLocation.CurrentUser); - - // 将新证书添加到存储区 - store.Open(OpenFlags.ReadWrite); - store.Add(certificate); - - store.Close(); - } -} - -``` - diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/FAQ.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/FAQ.md new file mode 100644 index 0000000..096cdf3 --- /dev/null +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/FAQ.md @@ -0,0 +1,338 @@ +--- +sidebar_position: 8 +--- + +# 常见问题 (FAQ) + +## 基础概念 + +### Q1: GeneralUpdate 是什么？ + +GeneralUpdate 是一个基于 .NET Standard 2.0 的跨平台自动更新框架。它提供了完整的应用程序更新解决方案，包括版本检查、下载管理、二进制差分更新、驱动更新、插件管理等功能。 + +### Q2: ClientCore 和 Core 有什么区别？ + +| | ClientCore | Core | +|---|---|---| +| **运行位置** | 主程序进程内 | 独立升级进程 | +| **职责** | 检查更新、下载包、启动升级助手 | 解压、打补丁、替换文件、启动新版本 | +| **依赖方向** | 引用 Core 的共享类型 | 被 ClientCore 启动（通过 IPC） | +| **NuGet 包** | `GeneralUpdate.ClientCore` | `GeneralUpdate.Core` | + +**简单来说：** ClientCore "检查和下载"，Core "安装和替换"。 + +### Q3: 什么是差分更新？为什么需要它？ + +差分更新只下载两个版本之间的**变化部分**，而不是下载完整的安装包。 + +- **全量更新：** 下载 50MB → 解压 50MB → 覆盖安装 +- **差分更新：** 下载 5MB (补丁) → 解压 → BSDiff 算法合并 → 仅 5MB 下载 + +对于频繁更新的应用，差分更新可节省 80%-95% 的带宽。 + +### Q4: GeneralUpdate 支持哪些平台？ + +| 操作系统 | 支持状态 | 备注 | +|----------|----------|------| +| Windows 10/11 | ✅ 完整支持 | 包括 WPF/WinForms/WinUI/Avalonia/Console | +| Linux (Ubuntu/Debian/Fedora) | ✅ 完整支持 | Avalonia/Console | +| macOS | ✅ 完整支持 | Avalonia/Console | +| Android | ✅ 通过 MAUI | 仅 OSS 模式 | +| 麒麟 V10 (飞腾/鲲鹏) | ✅ 已验证 | 国产化平台 | +| 统信 UOS | ✅ 已验证 | 国产化平台 | +| 龙芯 (LoongArch) | ✅ 已验证 | 国产化平台 | + +--- + +## 安装与配置 + +### Q5: 最简配置需要多少代码？ + +使用 `ConfiginfoBuilder` 零配置模式： + +```csharp +using GeneralUpdate.ClientCore; +using GeneralUpdate.Common.Shared.Object; + +var config = ConfiginfoBuilder + .Create("https://your-server.com/api/update/check", + "your-token", "Bearer") + .Build(); + +await new GeneralClientBootstrap() + .SetConfig(config) + .LaunchAsync(); +``` + +仅需 3 个参数，其它从 `.csproj` 自动提取。 + +### Q6: 如何配置黑名单？ + +```csharp +var config = new Configinfo +{ + // 跳过特定文件 + BlackFiles = new List { "appsettings.json", "userdata.db" }, + + // 跳过特定格式 + BlackFormats = new List { ".log", ".cache", ".tmp" }, + + // 跳过特定目录 + SkipDirectorys = new List { "logs", "temp", "userdata" } +}; +``` + +默认已跳过：`System.*.dll`、`.patch`、`.pdb`、`.rar`、`.tar`、`.json`、`.zip` 文件，以及 `app-`、`fail` 开头的目录。 + +### Q7: 静默更新如何配置？ + +```csharp +await new GeneralClientBootstrap() + .Option(UpdateOption.EnableSilentUpdate, true) + .SetConfig(config) + .LaunchAsync(); +``` + +启用后： +- 每 20 分钟（可配置）后台轮询检查新版本 +- 发现新版本后静默下载 +- 主程序退出时自动触发升级 +- 无需用户交互 + +--- + +## 版本管理 + +### Q8: 版本号格式要求是什么？ + +使用语义化版本（SemVer 2.0）格式：`Major.Minor.Patch.Build` + +- `1.0.0.0` ✓ +- `2.1.3.5` ✓ +- `1.0` ✗（不完整） +- `v1.0.0` ✗（含前缀） + +### Q9: 如何处理多版本跳级更新？ + +GeneralUpdate 自动支持逐版本更新。如果客户端版本是 `1.0.0.0`，服务端有 `1.0.1.0`、`1.0.2.0`、`1.1.0.0` 三个版本： + +``` +客户端 1.0.0.0 + → 下载 patch_v1.0.1.zip → 更新到 1.0.1.0 + → 下载 patch_v1.0.2.zip → 更新到 1.0.2.0 + → 下载 patch_v1.1.0.zip → 更新到 1.1.0.0 +``` + +按发布日期逐个升级，确保每步都经过完整校验。 + +### Q10: 可以实现强制更新吗？ + +可以。服务端在版本信息中设置 `IsForcibly: true`： + +```json +{ + "Version": "2.0.0.0", + "IsForcibly": true, + "UpdateLog": "重要安全更新，必须安装" +} +``` + +强制更新时，客户端的 `AddListenerUpdatePrecheck` 回调返回值会被忽略，更新一定执行。 + +--- + +## 下载与网络 + +### Q11: 支持断点续传吗？ + +支持。下载中断后，下次启动会从断点继续下载。通过 `EnableResume` 选项控制（默认启用）。 + +```csharp +await new GeneralClientBootstrap() + .Option(UpdateOption.EnableResume, true) + .SetConfig(config) + .LaunchAsync(); +``` + +### Q12: 下载超时如何配置？ + +```csharp +await new GeneralClientBootstrap() + .Option(UpdateOption.DownloadTimeOut, 120) // 120 秒超时 + .SetConfig(config) + .LaunchAsync(); +``` + +默认超时 30 秒。建议根据更新包大小和网络环境调整。 + +### Q13: 可以并发下载多个版本吗？ + +可以。通过 `MaxConcurrency` 全局选项配置： + +```csharp +Option.MaxConcurrency.SetValue(5); // 最多同时下载 5 个版本 +``` + +--- + +## 差分更新 + +### Q14: 差分更新 vs 全量更新，如何选择？ + +| 场景 | 建议模式 | +|------|----------| +| 日常小版本更新 | 差分更新（默认） | +| 大版本跨越（如 1.x → 2.x） | 全量更新 | +| 文件变化 < 20% | 差分更新 | +| 文件变化 > 80% | 全量更新 | +| 首次安装 | 全量更新 | + +```csharp +// 关闭差分更新 +await new GeneralClientBootstrap() + .Option(UpdateOption.Patch, false) + .SetConfig(config) + .LaunchAsync(); +``` + +### Q15: 补丁包是如何生成的？ + +使用 [GeneralUpdate.Tools](https://github.com/GeneralLibrary/GeneralUpdate.Tools) 的「补丁包」功能： + +1. 选择旧版本目录（如 `MyApp_v1.0.0`） +2. 选择新版本目录（如 `MyApp_v1.0.1`） +3. 设置输出目录 +4. 点击「构建」 + +工具自动： +- 对比两个目录的文件差异 +- 为修改的文件生成 BSDiff 补丁（`.patch`） +- 收集新增文件 +- 记录需要删除的文件（`delete_files.json`） +- 打包为 `.zip` + +--- + +## 文件与权限 + +### Q16: 更新时遇到文件被占用怎么办？ + +更新过程由独立的升级助手进程（Core）执行，主程序已退出，通常不会有文件占用问题。 + +如果仍有占用： +1. 检查是否有后台服务未关闭 +2. 使用 [文件占用指南](./File occupancy) 中的 `handle.exe` 排查 +3. 考虑使用强制重启后更新策略 + +### Q17: Linux/macOS 上文件权限怎么处理？ + +使用 `UnixPermissionHooks` 或 `CustomPermissionHooks`： + +```csharp +// 自动 chmod +x +await new GeneralClientBootstrap() + .Hooks() + .SetConfig(config) + .LaunchAsync(); +``` + +或通过 `Configinfo.Script` 指定自定义脚本： + +```csharp +var config = new Configinfo +{ + Script = "/path/to/permission-script.sh", + // ... +}; +``` + +--- + +## 故障排查 + +### Q18: 更新失败如何诊断？ + +1. **检查事件监听：** 确保注册了所有异常和错误监听器 +2. **查看 Bowl 日志：** 如果启用了 Bowl，检查 `fail/` 目录下的 Dump 和诊断文件 +3. **检查服务端日志：** 确认版本信息正确返回 +4. **检查网络：** 确认客户端可以访问服务端 API 和下载地址 +5. **检查版本号：** 确保客户端和服务端的版本号格式一致 + +### Q19: 如何实现回滚？ + +GeneralUpdate 有自动备份和回滚机制： + +```csharp +// 确保启用备份 +await new GeneralClientBootstrap() + .Option(UpdateOption.BackUp, true) + .SetConfig(config) + .LaunchAsync(); +``` + +更新失败或 Bowl 检测到崩溃时，自动从备份目录恢复文件。 + +### Q20: 如何在开发环境测试更新流程？ + +使用 [GeneralUpdate.Tools](https://github.com/GeneralLibrary/GeneralUpdate.Tools) 的「模拟更新」功能： + +1. 选择应用程序目录和补丁包 +2. 设置版本号和平台 +3. 点击「开始模拟」 + +工具自动： +- 启动本地模拟服务端 +- 发布并运行 ClientSample 和 UpgradeSample +- 执行完整更新流程 +- 生成测试报告 + +--- + +## 服务端 + +### Q21: 服务端 API 需要自己实现吗？ + +示例项目中提供了简单的服务端示例。生产环境需要自行实现或使用商业版本 [GeneralSpacestation](https://www.justerzhu.cn/)。 + +**需要实现的 API：** +1. `POST /Upgrade/Verification` — 版本验证 +2. `POST /Upgrade/Report` — 状态上报 +3. `GET /patch/{filename}` — 补丁包下载 + +### Q22: 可以和 CI/CD 集成吗？ + +可以。推荐集成方式： + +1. **CI 构建：** 编译新旧版本 +2. **Tools 命令行：** 使用 GeneralUpdate.Tools 生成补丁包（CLI 模式） +3. **上传：** 将补丁包和 `version.json` 上传到服务器/OSS +4. **更新清单：** 更新服务端版本数据库 + +--- + +## OSS 模式 + +### Q23: OSS 模式和标准模式有什么区别？ + +| | 标准模式 | OSS 模式 | +|---|---|---| +| **服务端** | 需要 HTTP API 服务 | 仅需对象存储（S3/OSS/MinIO） | +| **版本检查** | API 调用 | 读取 `version.json` 文件 | +| **适用场景** | 有后端服务的应用 | 客户端工具、桌面软件 | +| **成本** | 需要维护服务 | 仅存储和流量费用 | + +### Q24: 如何从标准模式迁移到 OSS 模式？ + +1. 生成 `version.json`（使用 GeneralUpdate.Tools OSS 配置模块） +2. 将 `version.json` 和补丁包上传到对象存储 +3. 客户端修改 `AppType` 为 `OssClient` +4. 配置 OSS 地址 + +--- + +## 相关资源 + +- **[GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)** — 核心更新引擎 +- **[入门实战手册](../quickstart/Beginner%20cookbook.md)** — 从零跑通更新闭环 +- **[GeneralUpdate.Tools](../quickstart/GeneralUpdate.PacketTool.md)** — 打包工具 +- **[GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl.md)** — 崩溃监控与回滚 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/System infomation.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/System infomation.md deleted file mode 100644 index 8f3e9ea..0000000 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/System infomation.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -sidebar_position: 6 ---- - -### System infomation 系统信息 - -#### （1）Windows平台 - -当更新失败时，并不清楚是因为操作系统的原因还是其他原因导致的启动失败。这个时候可以使用PsInfo导出当前操作系统的信息，供开发人员进行问题排查。*PsInfo* 是一个命令行工具，它可用于收集有关本地或远程 Windows NT/2000 系统的关键信息，包括安装类型、内核版本、已注册的组织和所有者、处理器数量及其类型、物理内存量、系统的安装日期以及到期日期（如果为试用版）。 - -#### 使用 PsInfo - -默认情况下，*PsInfo* 会显示本地系统的信息。 指定远程计算机名称以从远程系统获取信息。 由于 *PsInfo* 依赖于远程注册表访问来获取其数据，因此远程系统必须运行远程注册表服务，并且运行 *PsInfo* 的帐户必须有权访问远程注册表的 HKLM\System 部分。 - -为了帮助自动更新 Service Pack，*PsInfo* 会返回系统的 Service Pack 数的值（例如 0 表示无 Service Pack，1 表示 SP 1 等）。 - -**用法: psinfo [[\\computer[,computer[,..] | @file [-u user -[-p psswd]]] [-h] [-s] [-d] [-c [-t delimiter]] [filter]** - -| 参数 | 说明 | -| :------------- | :----------------------------------------------------------- | -| **\\computer** | 在指定的远程计算机上执行命令。 如果省略计算机名称，则命令在本地系统上运行，如果指定通配符 (\\*)，则命令将在当前域中的所有计算机上运行。 | -| **@file** | 在指定的文本文件中列出的每台计算机上运行命令。 | -| **-u** | 指定登录远程计算机的可选用户名。 | -| **-p** | 指定用户名的可选密码。 如果省略此内容，系统将提示你输入隐藏密码。 | -| **-h** | 显示已安装的修补程序的列表。 | -| **-s** | 显示已安装的应用程序的列表。 | -| **-d** | 显示磁盘卷信息。 | -| **-c** | 以 CSV 格式打印。 | -| **-t** | -c 选项的默认分隔符为逗号，但可以使用指定的字符替代。 | -| **filter** | Psinfo 将仅显示与筛选器匹配的字段的数据。 例如，“psinfo service”仅列出 service pack 字段。 | - -#### 示例输出 - -```c# -C:\> psinfo \\development -h -d - -PsInfo v1.6 - local and remote system information viewer -Copyright (C) 2001-2004 Mark Russinovich -Sysinternals - www.sysinternals.com - - System information for \\DEVELOPMENT: - Uptime: 28 days, 0 hours, 15 minutes, 12 seconds - Kernel version: Microsoft Windows XP, Multiprocessor Free - Product type Professional - Product version: 5.1 - Service pack: 0 - Kernel build number: 2600 - Registered organization: Sysinternals - Registered owner: Mark Russinovich - Install date: 1/2/2002, 5:29:21 PM - Activation status: Activated - IE version: 6.0000 - System root: C:\WINDOWS - Processors: 2 - Processor speed: 1.0 GHz - Processor type: Intel Pentium III - Physical memory: 1024 MB - Volume Type Format Label Size Free Free - A: Removable 0% - C: Fixed NTFS WINXP 7.8 GB 1.3 GB 16% - D: Fixed NTFS DEV 10.7 GB 809.7 MB 7% - E: Fixed NTFS SRC 4.5 GB 1.8 GB 41% - F: Fixed NTFS MSDN 2.4 GB 587.5 MB 24% - G: Fixed NTFS GAMES 8.0 GB 1.0 GB 13% - H: CD-ROM CDFS JEDIOUTCAST 633.6 MB 0% - I: CD-ROM 0% - Q: Remote 0% - T: Fixed NTFS Test 502.0 MB 496.7 MB 99% - OS Hot Fix Installed - Q147222 1/2/2002 - Q309521 1/4/2002 - Q311889 1/4/2002 - Q313484 1/4/2002 - Q314147 3/6/2002 - Q314862 3/13/2002 - Q315000 1/8/2002 - Q315403 3/13/2002 - Q317277 3/20/2002 -``` - - - -官方文档：https://learn.microsoft.com/zh-cn/sysinternals/downloads/psinfo \ No newline at end of file diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/Systemlog.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/Systemlog.md deleted file mode 100644 index fb48082..0000000 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/Systemlog.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -sidebar_position: 5 ---- - -### System log 系统日志 - -升级失败时可能会出现运行启动失败、驱动安装失败等问题。那么可以使用Sysmon工具导出系统事件日志。*系统监视器* (*Sysmon*) 是一项 Windows 系统服务，也是一个设备驱动程序，一旦安装在系统上，就会在系统重新启动后一直驻留，以监视系统活动并将其记录到 Windows 事件日志中。 它提供有关进程创建、网络连接和文件创建时间更改的详细信息。 通过使用 [Windows 事件收集](https://msdn.microsoft.com/library/windows/desktop/bb427443(v=vs.85).aspx)或 [SIEM](https://en.wikipedia.org/wiki/security_information_and_event_management) 代理收集生成的事件，然后对事件进行分析，你可识别恶意或异常活动，并了解入侵者和恶意软件如何在网络上运行。 该服务作为[受保护的进程](https://learn.microsoft.com/windows/win32/services/protecting-anti-malware-services-#system-protected-process)运行，从而禁止广泛的用户模式交互。 - - - -### Sysmon 功能概述 - -*Sysmon* 包括以下功能： - -- 记录当前进程和父进程中使用完整命令行创建的进程。 -- 记录使用 SHA1（默认）、MD5、SHA256 或 IMPHASH 的进程映像文件的哈希。 -- 可以同时使用多个哈希。 -- 在进程内创建事件之中包含一个进程 GUID，当 Windows 重新使用进程 ID 时，允许事件的相关性。 -- 在每个事件中包含会话 GUID，允许同一登录会话上事件的相关性。 -- 记录驱动程序或 DLL 的加载及其签名与哈希。 -- 记录磁盘和卷的原始读取访问打开次数。 -- （可选）记录网络连接，包括每个连接的源进程、IP 地址、端口数量、主机名和端口名称。 -- 检测文件创建时间的更改，以了解文件真正创建的时间。 修改文件创建时间戳是恶意软件惯用的伎俩来掩盖其轨道。 -- 如果注册表中发生更改，则自动化重新加载配置。 -- 进行规则筛选以动态包含或不包含某些事件。 -- 在启动进程之初生成事件，以捕获相当复杂的内核模式恶意软件进行的活动。 - - - -#### （1）Windows平台 - -下载地址： https://download.sysinternals.com/files/Sysmon.zip - - - -#### （2）Linux平台 - -下载地址：https://github.com/Sysinternals/SysmonForLinux - - - -官方文档：https://learn.microsoft.com/zh-cn/sysinternals/downloads/sysmon diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/_category_.json b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/_category_.json index 7611c29..60ddc82 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/_category_.json +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/_category_.json @@ -1,8 +1,8 @@ { - "label": "指南", - "position": 7, + "label": "帮助", + "position": 3, "link": { "type": "generated-index", - "description": "平台与运维指南。" + "description": "平台与运维帮助文档。" } } diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md deleted file mode 100644 index 2676dd4..0000000 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Advanced cookbook.md +++ /dev/null @@ -1,808 +0,0 @@ ---- -sidebar_position: 4 -title: 高级实战手册 ---- - -# GeneralUpdate 高级实战手册 - -> **目标读者**：已有基础使用经验的开发者，正在将 GeneralUpdate 集成到生产产品、CI/CD 流水线和企业级发布工作流中。 - -本手册与[入门实战手册](./Beginner cookbook.md)互补。入门手册带你跑通第一次更新闭环；本手册假设你已经跑通，直接进入生产级方案设计。 - ---- - -## 1. 生产更新架构设计 - -### 1.1 拓扑总览 - -``` -┌──────────┐ GET version ┌──────────┐ -│ Client │ ──────────────> │ Server │ -│ (主程序) │ <── version.json │ (更新服务) │ -└────┬─────┘ └────┬─────┘ - │ │ - │ 下载补丁 ZIP │ 读取 packages/ - ▼ ▼ -┌──────────┐ 启动并传参 ┌──────────┐ -│ Upgrade │ <──────────── │ Client │ -│ (独立进程) │ │ │ -└────┬─────┘ └──────────┘ - │ 应用补丁、上报状态 - ▼ -┌──────────┐ -│ 新版本 │ -│ 主程序 │ -└──────────┘ -``` - -### 1.2 各角色职责 - -| 角色 | 部署位置 | 职责 | 关键配置 | -|------|----------|------|----------| -| Client | 用户终端 | 版本检查、补丁下载、拉起 Upgrade | `UpdateUrl`、`AppSecretKey`、`ClientVersion` | -| Upgrade | 与 Client 同目录 | 独立升级进程，接收上下文并应用补丁 | 由 Client 通过 `GeneralUpdateBootstrap` 传递 | -| Server | 服务器 | 版本验证、补丁下载、状态上报 | `versions.json`、`/Upgrade/Verification`、`/File/Download` | -| Tools | 开发/CI 环境 | 生成补丁包、OSS 清单、Hash 计算 | 输入 old/new 目录，输出 `.zip` | -| Bowl | 与 Client 同目录 | 进程监控、崩溃检测、备份恢复 | `MonitorParameter`、dump 路径 | - -### 1.3 最小生产拓扑 - -对于大多数产品，推荐以下拓扑： - -- **开发端**：CI 环境运行 `generate_packages.ps1` + Tools 生成补丁 -- **服务端**：一台 HTTP Server 托管 `versions.json` 和 `.zip` 文件；可选 OSS 模式用静态存储 -- **客户端**：Client 和 Upgrade 统一引用 `GeneralUpdate.Core`（自最新版本起，原 `GeneralUpdate.ClientCore` 和 `GeneralUpdate.Common` 已合并到 `GeneralUpdate.Core`） - -```text -CI (GitHub Actions) Server (HTTP / OSS) -┌─────────────────┐ ┌──────────────────┐ -│ build + publish │ ── 推送补丁 ZIP ──> │ versions.json │ -│ gen_packages.ps1│ │ *.zip (补丁包) │ -│ Tools (可选) │ │ 静态文件服务 │ -└─────────────────┘ └──────────────────┘ -``` - ---- - -## 2. 标准化发布物 - -### 2.1 发布物类型 - -| 类型 | 生成方式 | 文件格式 | 适用场景 | -|------|----------|----------|----------| -| 全量包 (Full) | `ZipFile.CreateFromDirectory` 打包完整发布目录 | `packet_{timestamp}_{version}.zip` | 跨多个版本升级、首次安装 | -| 差分包 (Patch) | Tools Patch 页面或 `DifferentialCore.Clean` 对比 old/new | `patch_{timestamp}.zip` | 仅变更少量文件时减少下载量 | -| 扩展包 (Extension) | Tools Extension 页面 | `.zip`（含 manifest） | 插件/扩展独立分发与更新 | -| OSS 清单 | Tools OSS 页面 | `version.json` | OSS 模式更新，适合静态文件服务 | - -### 2.2 `versions.json` 字段说明 - -Samples Server 的 `versions.json` 每条记录控制一次版本匹配与下载： - -```json -{ - "PacketName": "packet_20260529221936_client_2.0.0.0", - "Hash": "a1b2c3...sha256", - "Version": "2.0.0.0", - "Url": "http://localhost:5000/File/Download/a1b2c3...", - "PubTime": "2026-05-29T14:19:36.0000000", - "AppType": 1, - "Platform": 1, - "ProductId": "2d974e2a-31e6-4887-9bb1-b4689e98c77a", - "IsForcibly": false, - "Format": ".zip", - "Size": 123456, - "IsFreeze": false, - "IsCrossVersion": true, - "FromVersion": "1.0.0.0", - "ToVersion": "2.0.0.0" -} -``` - -| 字段 | 说明 | -|------|------| -| `AppType` | `1` = Client（主程序），`2` = Upgrade（升级程序） | -| `Platform` | `1` = Windows，`2` = Linux，`3` = Mac | -| `IsCrossVersion` | `true` = 差分更新包（需要 `FromVersion`/`ToVersion`），`false` = 全量包 | -| `IsForcibly` | `true` = 强制更新，用户无法跳过 | -| `IsFreeze` | `true` = 冻结当前版本，Server 返回已是最新 | -| `ProductId` | 产品标识，与 Client 配置中的 `ProductId` 对应 | - -### 2.3 生成脚本的使用 - -Samples 提供了完整的 PowerShell 打包脚本： - -```powershell -# 生成全量包和差分包 -.\src\Server\generate_packages.ps1 - -# 仅生成全量包（快速模式，跳过 Differential） -.\src\Server\generate_packages.ps1 -FullOnly - -# 单独重建 versions.json -.\src\Server\create_versions_json.ps1 -``` - -脚本流程： -1. 扫描 `src/content_client/` 和 `src/content_upgrade/` 中的示例内容 -2. 为每个版本目录生成全量 ZIP -3. 调用 `PatchGenerator` C# 项目生成差分 ZIP -4. 计算每个 ZIP 的 SHA256 并写入 `versions.json` - -**生产环境建议**：将这些脚本改造为 CI 步骤，输入参数接受旧版本路径和新版本路径，输出到制品仓库。 - ---- - -## 3. CI/CD 集成 - -### 3.1 GitHub Actions 示例 - -```yaml -name: Generate Update Packages - -on: - push: - tags: - - 'v*.*.*' - -jobs: - generate-packages: - runs-on: windows-latest - steps: - - uses: actions/checkout@v4 - - - name: Setup .NET - uses: actions/setup-dotnet@v4 - with: - dotnet-version: '8.0.x' - - - name: Build release - run: dotnet publish src/Client/ClientSample.csproj -c Release -o publish/v${{ github.ref_name }} - - - name: Generate packages - shell: pwsh - run: | - $oldVersion = "publish/v1.0.0" # 从制品仓库下载上一个版本 - $newVersion = "publish/v${{ github.ref_name }}" - dotnet run --project src/PatchGenerator -- $oldVersion $newVersion packages/ - - - name: Upload artifacts - uses: actions/upload-artifact@v4 - with: - name: update-packages - path: packages/ -``` - -### 3.2 版本映射策略 - -**关键问题**：CI 不能假设所有历史版本都在构建机器上。 - -**推荐方案**： - -| 方案 | 描述 | 适用场景 | -|------|------|----------| -| 制品仓库缓存 | 每次发布后将 `publish/v{version}` 上传到制品仓库（如 GitHub Releases、Artifactory），CI 运行时下载需要对比的旧版本 | 中等规模，版本数量可控 | -| 基准版本 + 回退 | 每隔 N 个版本发布一次全量包，差分包只与最近 2-3 个版本比较 | 快速迭代的产品 | -| 按需下载 | Server 端对比版本时，按需从 OSS 下载旧版本包进行差分 | 版本很多的产品 | - -### 3.3 发布清单 - -每次版本发布前请确认： - -- [ ] `versions.json` 中新增的记录 `Hash` 与上传的 ZIP 文件一致 -- [ ] 差分包的 `FromVersion` 正确指向旧版本 -- [ ] 全量包的 `AppType` 区分了 Client 和 Upgrade -- [ ] 旧版本 `IsFreeze` 未设置为 `true`（除非需要冻结） -- [ ] 所有 ZIP 可通过 `GET /File/Download/{hash}` 正常下载 -- [ ] 测试 Client 从当前最新旧版本升级到新版本 - ---- - -## 4. 版本策略 - -### 4.1 版本号规范 - -GeneralUpdate 遵循[语义化版本](https://semver.org/lang/zh-CN/)（SemVer）规范的核心原则。在 SemVer `MAJOR.MINOR.PATCH` 的基础上，为兼容 .NET `System.Version`，扩展了第四个 `Revision` 段，形成 `Major.Minor.Build.Revision` 四段式版本号： - -```text -2.0.0.0 -│ │ │ └── Revision（修订号）— 对应 .NET 第四段，非 SemVer 标准 -│ │ └──── Build（构建号） — 对应 SemVer PATCH -│ └────── Minor（次版本号） — 对应 SemVer MINOR -└──────── Major（主版本号） — 对应 SemVer MAJOR -``` - -版本号规则： -- **Major**（主版本号）：不兼容的 API 修改时递增 -- **Minor**（次版本号）：向下兼容的功能新增时递增 -- **Build**（构建号/补丁号）：向下兼容的问题修正时递增 -- **Revision**（修订号）：内部修订，通常为 `0`，仅在 .NET 程序集版本中区分 - -Server 使用 `new Version(string)` 进行比较，因此请保持纯数字格式。更多细节参见 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/)。 - -### 4.2 更新模式 - -| 模式 | `UpgradeMode` | 行为 | -|------|---------------|------| -| 全量更新 | `1` (VersionChain) | 仅匹配 `IsCrossVersion = false` 的包，按版本号由低到高逐级升级 | -| 差分更新 | `2` (CrossVersion) | 仅匹配 `IsCrossVersion = true` 的包，要求 `FromVersion` 与客户端当前版本精确匹配 | - -### 4.3 渐进式发布 - -```text - ┌──────────────┐ -v1.0.0.0 ───────────>│ 全量 → 2.0.0.0 │ (跨版本跳跃) - └──────────────┘ - ┌──────────────┐ -v1.0.0.1 ───────────>│ 差分 → 2.0.0.0 │ (精确匹配 FromVersion) - └──────────────┘ - ┌──────────────┐ -v1.0.0.2 ───────────>│ 差分 → 2.0.0.0 │ - └──────────────┘ -``` - -**建议**： -- 重要版本发布同时提供全量包和差分包 -- 对最近 3 个活跃版本提供差分升级路径 -- 超过 3 个版本差距的用户走全量升级 - -### 4.4 强制更新 - -在 `versions.json` 中将 `IsForcibly` 设为 `true`： - -```json -{ "Version": "2.0.1.0", "IsForcibly": true } -``` - -Client 端配合 `AddListenerUpdatePrecheck` 处理： - -```csharp -// Client 端的预检回调 -bootstrap.AddListenerUpdatePrecheck(async (precheckArgs) => -{ - var forcedCount = precheckArgs.Versions.Count(v => v.IsForcibly); - if (forcedCount > 0) - { - // 强制更新：不弹出"跳过"按钮 - ShowDialog("检测到重要安全更新，必须立即更新。"); - return false; // false = 不跳过，继续更新 - } - // 可选更新：询问用户 - return await AskUserWhetherToSkip(); -}); -``` - -### 4.5 多版本顺序升级 - -当客户端版本落后多个版本时： - -1. Server 返回所有高于当前版本的记录（`IsCrossVersion = false` 的全量包） -2. Client 按版本号升序依次下载并应用 -3. 每完成一个版本的升级，Upgrade 重启 Client，Client 再次请求下一版本 - -**注意**：如果希望一次跳跃到最新版本，只提供一个全量包（版本号设为最新的目标版本）。 - ---- - -## 5. 差分策略 - -### 5.1 何时使用差分 - -| 场景 | 推荐方式 | 原因 | -|------|----------|------| -| 用户版本紧跟最新 | 差分更新 | 仅传输变更文件，节省带宽 | -| 用户版本落后 3+ 个版本 | 全量更新 | 累积变更可能超过全量下载 | -| 紧急安全补丁 | 差分更新 | 快速分发，减小攻击窗口 | -| 框架/运行时升级 | 全量更新 | 文件变化范围大，差分收益低 | -| 大文件更新（>100MB） | 差分更新 | 即使变更量大，也能显著减小下载 | - -### 5.2 差分生成与 `delete_files.json` - -Tools 或 `DifferentialCore.Clean` 生成的补丁包包含： - -``` -patch_20260529221936.zip -├── file1.dll.patch ← 二进制差分文件 -├── file2_new.dll ← 新增文件（直接复制） -└── generalupdate.delete.json ← 需要删除的文件清单 -``` - -`generalupdate.delete.json` 格式： - -```json -{ - "deleteFiles": [ - "old_plugin.dll", - "deprecated/config.json" - ] -} -``` - -Upgrade 端应用补丁时会自动处理： -1. 对 `.patch` 文件应用差分还原 -2. 复制新增文件 -3. 删除清单中的文件 - -### 5.3 黑名单配置 - -某些文件不应参与更新（用户数据、本地配置、日志等）： - -```csharp -// 在 Client 配置中使用黑名单 -new GeneralUpdateBootstrap() - .AddBlacklist(new List - { - "appsettings.json", // 用户本地配置 - "logs/", // 日志目录 - "*.user", // 用户文件 - "cache.db" // 本地数据库 - }) -``` - -C# 代码示例 — 通过 `IBinaryDiffer` 扩展点介入： - -```csharp -// 自定义差分策略，跳过大于 100MB 的单文件 -public class LargeFileAwareStrategy : DefaultCleanStrategy -{ - public override bool ShouldDiff(string relativePath, FileInfo oldFile, FileInfo newFile) - { - const long maxDiffSize = 100 * 1024 * 1024; - if (newFile.Length > maxDiffSize) - return false; // 直接复制新文件，不生成 patch - return base.ShouldDiff(relativePath, oldFile, newFile); - } -} -``` - -### 5.4 并行处理 - -Differential 默认使用并行处理（`StreamingHdiffDiffer`）提升性能。对于大目录（数千个文件），建议： - -- 控制并行度：`new ParallelOptions { MaxDegreeOfParallelism = Environment.ProcessorCount }` -- 对超大文件使用 bsdiff 算法（内存占用较低但速度稍慢） -- 对一般文件使用 hdiff 算法（速度快但内存占用较高） - ---- - -## 6. Bowl 可靠性设计 - -### 6.1 Bowl 在生命周期中的位置 - -```text -┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ -│ 更新完成 │ -> │ Bowl 启动 │ -> │ 启动主程序 │ -> │ 监控运行 │ -└──────────┘ └──────────┘ └──────────┘ └────┬─────┘ - │ - 进程异常退出 - │ - ▼ - ┌──────────┐ - │ 导出 Dump │ - │ 备份旧版本 │ - │ 写 Fail JSON│ - └──────────┘ -``` - -### 6.2 生产配置示例 - -```csharp -public static async Task GuardAsync(string appPath, string installPath) -{ - var lastVersion = "2.0.0.0"; - var processInfo = new MonitorParameter - { - ProcessNameOrId = "MyProduct.App.exe", - DumpFileName = $"{lastVersion}_fail.dmp", - FailFileName = $"{lastVersion}_fail.json", - TargetPath = installPath, - FailDirectory = Path.Combine(installPath, "fail", lastVersion), - BackupDirectory = Path.Combine(installPath, "backup", lastVersion), - WorkModel = "Normal" - }; - - Bowl.Launch(processInfo); -} -``` - -### 6.3 备份与回滚流程 - -1. **升级前**：Bowl 将当前运行的程序文件备份到 `BackupDirectory` -2. **升级后**：Bowl 启动新版本主程序 -3. **监控中**：Bowl 持续监控进程状态 -4. **异常时**： - - 导出 `.dmp` 文件 - - 写入 `fail.json`（包含版本、时间、系统信息、驱动信息） - - 如果 `WorkModel = "Normal"`，自动从备份目录恢复旧版本 -5. **恢复后**：Bowl 重新启动旧版本程序 - -### 6.4 平台差异处理 - -| 特性 | Windows | Linux | macOS | -|------|---------|-------|-------| -| Dump 导出 | MiniDumpWriteDump | 依赖环境（需 `dotnet-dump` 或 `createdump`） | 依赖环境 | -| 进程监控 | WMI / Win32 API | procfs (`/proc/{pid}`) | 类似 Linux | -| 备份恢复 | 文件复制 + 覆盖 | 文件复制 + 覆盖（注意权限） | 文件复制 + 覆盖 | -| 驱动信息 | `driverquery` | `lsmod` / `lspci` | `kextstat` | - -### 6.5 日志集成 - -Bowl 会自动输出以下信息到 `fail.json`： - -```json -{ - "version": "2.0.0.0", - "timestamp": "2026-05-29T14:30:00Z", - "processName": "MyProduct.App.exe", - "exitCode": -1073741819, - "systemInfo": { "os": "Windows 11", "arch": "x64" }, - "driverInfo": [], - "dumpPath": "fail/2.0.0.0/2.0.0.0_fail.dmp" -} -``` - -建议在产品中加入日志上传步骤，将 `fail.json` 和 `.dmp` 上报到服务端进行分析。 - ---- - -## 7. 扩展系统 - -### 7.1 扩展生命周期 - -```text -┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ -│ 查询可用 │ → │ 下载扩展 │ → │ 安装扩展 │ → │ 加载扩展 │ -│ 扩展列表 │ │ 包到本地 │ │ 到目录 │ │ 到运行时 │ -└──────────┘ └──────────┘ └──────────┘ └────┬─────┘ - │ - ┌────▼─────┐ - │ 更新/回滚 │ - │ 卸载扩展 │ - └──────────┘ -``` - -### 7.2 扩展 Manifest 规范 - -每个扩展包应包含 `extension.json`： - -```json -{ - "id": "com.mycompany.plugin.search", - "name": "Search Plugin", - "version": "1.2.0", - "author": "MyCompany", - "description": "Full-text search capability", - "dependencies": { - "com.mycompany.core": ">=1.0.0" - }, - "platforms": ["win-x64", "linux-x64"], - "minAppVersion": "2.0.0", - "type": "plugin" -} -``` - -### 7.3 查询与安装 - -```csharp -var manager = new ExtensionManager(options => -{ - options.ExtensionsRootPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "extensions"); - options.TempDownloadPath = Path.Combine(Path.GetTempPath(), "ext_downloads"); - options.ManifestFileName = "extension.json"; -}); - -// 查询远程可用扩展 -var available = await manager.QueryRemoteExtensionsAsync("https://extensions.example.com/api/v1/extensions"); - -// 安装 -await manager.InstallAsync("com.mycompany.plugin.search", "1.2.0", - progress => Console.WriteLine($"Downloading: {progress.Percentage}%")); - -// 更新 -await manager.UpdateAsync("com.mycompany.plugin.search", "1.3.0"); - -// 回滚 -await manager.RollbackAsync("com.mycompany.plugin.search", "1.2.0"); - -// 卸载 -await manager.UninstallAsync("com.mycompany.plugin.search"); -``` - -### 7.4 Tools 扩展包生成 - -使用 Tools 的 Extension Package 页面： - -| 输入 | 说明 | -|------|------| -| Extension Source Directory | 扩展文件的源目录 | -| Manifest File | `extension.json` 文件路径 | -| Output Directory | 扩展包 ZIP 输出目录 | - -生成的扩展包 ZIP 包含 manifest 和所有扩展文件，可直接推送到扩展服务器。 - -### 7.5 服务端 API 约定 - -扩展服务器需要提供以下端点： - -``` -GET /api/v1/extensions → 返回可用扩展列表 -GET /api/v1/extensions/{id} → 返回指定扩展详情和版本列表 -GET /api/v1/extensions/{id}/versions/{v} → 返回指定版本元数据和下载链接 -GET /api/v1/extensions/download/{hash} → 下载扩展包 -POST /api/v1/extensions/check → 批量兼容性检查 -``` - ---- - -## 8. 驱动更新 - -### 8.1 驱动更新与普通文件更新的区别 - -| 维度 | 应用文件更新 | 驱动更新 | -|------|-------------|----------| -| 文件位置 | 应用程序目录 | 系统驱动目录 | -| 权限要求 | 常规用户权限 | 管理员/root 权限 | -| 生效方式 | 重启应用程序 | 可能需要重启系统 | -| 签名要求 | 无 | 需要数字签名（Windows WHQL / Linux DKMS） | -| 回滚复杂度 | 直接替换文件 | 需卸载当前驱动，安装旧版本 | -| 兼容性检查 | 框架版本 | 内核版本、硬件 ID | - -### 8.2 Drivelution 更新流程 - -```csharp -var updater = new DriverUpdater(options => -{ - options.DriverStorePath = @"C:\ProgramData\MyProduct\Drivers"; - options.TempPath = Path.GetTempPath(); - options.RequireSignature = true; - options.BackupBeforeInstall = true; -}); - -// 1. 验证驱动包 -var validation = await updater.ValidatePackageAsync(driverPackagePath); -if (!validation.IsValid) -{ - Console.WriteLine($"Driver validation failed: {validation.Errors}"); - return; -} - -// 2. 备份当前驱动 -await updater.BackupCurrentDriverAsync("MyDeviceDriver"); - -// 3. 安装新驱动 -var result = await updater.InstallAsync(driverPackagePath); -if (!result.Success) -{ - // 4. 安装失败，自动回滚 - await updater.RollbackAsync("MyDeviceDriver"); - Console.WriteLine($"Install failed: {result.ErrorMessage}"); - return; -} - -// 5. 验证新驱动是否正常工作 -var health = await updater.HealthCheckAsync("MyDeviceDriver"); -Console.WriteLine($"Driver health: {health.Status}"); -``` - -### 8.3 Windows 驱动签名 - -生产环境中，Windows 驱动必须签名： - -1. 获取 EV Code Signing 证书 -2. 通过 WHQL（Windows Hardware Quality Labs）认证 -3. 在 `DriverUpdater` 中启用 `RequireSignature = true` - -### 8.4 Linux 驱动注意事项 - -- 使用 `dkms`（Dynamic Kernel Module Support）管理内核模块 -- 更新前检查内核版本兼容性 -- `/lib/modules/$(uname -r)/` 路径通常需要 root 权限 -- 更新后可能需要 `depmod` 和 `modprobe` - -### 8.5 批量/并行驱动更新 - -```csharp -var updaters = new[] -{ - new DriverUpdateTask { DeviceId = "PCI\\VEN_8086", PackagePath = @"drivers\gpu_2.1.0.zip" }, - new DriverUpdateTask { DeviceId = "USB\\VID_0BDA", PackagePath = @"drivers\wifi_1.5.0.zip" }, -}; - -// 并行更新多个驱动 -var results = await Parallel.ForEachAsync(updaters, - new ParallelOptions { MaxDegreeOfParallelism = 4 }, - async (task, ct) => - { - var updater = new DriverUpdater(/* ... */); - return await updater.InstallAsync(task.PackagePath); - }); - -foreach (var r in results) -{ - Console.WriteLine($"Driver {r.DeviceId}: {(r.Success ? "OK" : "FAILED")}"); -} -``` - ---- - -## 9. 安全与合规 - -### 9.1 Hash 校验 - -GeneralUpdate 在下载完成后自动校验 SHA256： - -```csharp -// Server 端：生成 Hash（PowerShell） -(Get-FileHash -Path .\packet.zip -Algorithm SHA256).Hash.ToLowerInvariant() - -// 或使用 Tools OSS 页面计算 -``` - -Client 端自动校验：下载完成后，Core 会对下载的文件计算 SHA256 并与 `versions.json` 中的 `Hash` 进行比对。不匹配则丢弃并重试（最多 3 次）。 - -### 9.2 认证下载 - -Server 支持在下载请求中传递 Token： - -```csharp -// Client 端：在请求中添加认证头 -new GeneralUpdateBootstrap() - .AddListenerDownloadConfig(config => - { - config.Headers = new Dictionary - { - ["Authorization"] = $"Bearer {GetAccessToken()}" - }; - }); -``` - -**生产环境建议**： -- 使用短期有效的 JWT Token -- 下载端点验证 Token 作用域（仅允许下载指定 `ProductId` 的包） -- 记录每次下载的 Token、IP、时间到审计日志 - -### 9.3 OSS 模式安全 - -OSS 模式使用静态文件服务（如阿里云 OSS、AWS S3）： - -``` -# 推荐的 OSS Bucket 策略 -{ - "Statement": [ - { - "Effect": "Allow", - "Principal": {"Anonymous": ["*"]}, - "Action": ["oss:GetObject"], - "Resource": ["acs:oss:my-bucket:packages/*.zip"], - "Condition": { - "IpAddress": {"acs:SourceIp": ["你的服务器 IP 段"]} - } - }, - { - "Effect": "Allow", - "Principal": {"Anonymous": ["*"]}, - "Action": ["oss:GetObject"], - "Resource": ["acs:oss:my-bucket:packages/versions.json"] - } - ] -} -``` - -### 9.4 发布审计清单 - -每次生产发布前请确认： - -- [ ] 所有 `versions.json` 中的 `Hash` 与上传 ZIP 的 SHA256 一致 -- [ ] 下载端点使用 HTTPS（生产环境禁止 HTTP） -- [ ] `AppSecretKey` 正确配置，防止未授权的版本查询 -- [ ] 旧版本的 `IsFreeze` 标记正确（不应冻结仍在使用中的版本） -- [ ] 差分包的 `FromVersion`/`ToVersion` 路径正确 -- [ ] 所有文件由 CI 签名，未被篡改 -- [ ] 生产发布记录已写入审计日志 - ---- - -## 10. 故障演练 - -### 10.1 场景一：下载失败 / 网络中断 - -**模拟方法**：在 Client 下载过程中拔掉网线或关闭 Server。 - -**预期行为**： -- Client 抛出 `DownloadException` -- 断点续传功能自动生效：下次启动继续下载 -- 下载进度通过 `AddListenerMultiDownloadStatistics` 回调报告 - -**验证方式**： -```csharp -bootstrap.AddListenerMultiDownloadError((version, exception) => -{ - Console.WriteLine($"[Download Error] {version.Version}: {exception.Message}"); - // 产品集成：告警上报 -}); -``` - -### 10.2 场景二：文件锁定 - -**模拟方法**：在 Upgrade 应用补丁前，手动打开目标目录中的某个 DLL（如用记事本打开）。 - -**预期行为**： -- Upgrade 尝试替换文件时遇到 `IOException` -- 重试 3 次（每次间隔 500ms） -- 仍失败则触发 `AddListenerException` 回调 -- 不破坏已更新的其他文件 - -### 10.3 场景三：升级后启动崩溃 - -**模拟方法**：将 `content_upgrade` 中的 `UpgradeSample.exe` 替换为一个会立即崩溃的假 exe。 - -**预期行为**： -- Client 完成更新后启动新版本 -- Bowl 检测到进程异常退出 -- Bowl 导出 `.dmp` 和 `fail.json` 到 `fail/{version}/` -- Bowl 从 `backup/{version}/` 恢复旧版本 -- 旧版本启动成功 - -**验证方式**： -1. 检查 `fail/` 目录中是否出现了 dump 和 JSON 文件 -2. 确认旧版本程序成功恢复并启动 -3. Server 收到 `/Upgrade/Report` 中的失败状态 - -### 10.4 场景四：补丁包损坏 - -**模拟方法**：手动修改 `packages/` 中的补丁 ZIP 文件（例如用文本编辑器打开并修改若干字节）。 - -**预期行为**： -- Client 下载完成后校验 SHA256 失败 -- 自动丢弃损坏文件并重新下载（最多 3 次） -- 3 次均失败后通过 `AddListenerMultiDownloadError` 通知 -- 不会应用损坏的补丁 - -### 10.5 场景五：权限不足 - -**模拟方法**：在 Linux 上以非 root 用户运行 Upgrade，目标目录的写权限被移除。 - -**预期行为**： -- Upgrade 尝试写入文件时遇到 `UnauthorizedAccessException` -- 通过 `AddListenerException` 通知 -- 不会部分更新（保持原子性） - -**预防措施**： -```csharp -// Client 在启动 Upgrade 前验证目标目录权限 -if (!HasWritePermission(installDirectory)) -{ - // 提示用户以管理员权限运行 - RequestAdminPrivilege(); - return; -} -``` - -### 10.6 故障演练时间表 - -建议每个发布周期执行一次完整的故障演练： - -| 演练项 | 频率 | 负责人 | 验证方式 | -|--------|------|--------|----------| -| 下载中断恢复 | 每次发布 | QA | 观察断点续传日志 | -| 文件锁定处理 | 每次发布 | QA | 检查回滚行为 | -| 启动崩溃恢复 | 每月 | DevOps | Bowl fail 目录 + Server 报告 | -| 补丁损坏校验 | 每次发布 | QA | 下载日志 SHA256 不匹配 | -| 权限不足处理 | 每次大版本 | DevOps | Linux 平台测试 | -| 差分包完整性 | 每次发布 | CI | 自动化测试对比文件树 | - ---- - -## 附录：相关资源 - -- [GeneralUpdate.Core 组件文档](../doc/GeneralUpdate.Core.md) -- [GeneralUpdate.Differential 组件文档](../doc/GeneralUpdate.Differential.md) -- [GeneralUpdate.Bowl 组件文档](../doc/GeneralUpdate.Bowl.md) -- [GeneralUpdate.Drivelution 组件文档](../doc/GeneralUpdate.Drivelution.md) -- [GeneralUpdate.Extension 组件文档](../doc/GeneralUpdate.Extension.md) -- [GeneralUpdate.Tools 工具文档](../doc/GeneralUpdate.PacketTool.md) -- [入门实战手册](./Beginner cookbook.md) -- [Samples 仓库](https://github.com/GeneralLibrary/GeneralUpdate-Samples) -- [Tools 仓库](https://github.com/GeneralLibrary/GeneralUpdate.Tools) - -> **贡献指南**：如果你在生产环境中积累了实战经验，欢迎通过 [Issue](https://github.com/GeneralLibrary/GeneralUpdate-Samples/issues) 或 Pull Request 贡献案例与最佳实践。 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Beginner cookbook.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Beginner cookbook.md index 80d4d11..e60f34e 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Beginner cookbook.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Beginner cookbook.md @@ -13,8 +13,8 @@ title: 入门实战手册 | --- | --- | --- | --- | | Hub | `src\Hub` | 交互式示例浏览器，通过菜单选择并运行各类更新场景 | [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md) | | Server | `src\Server` | 返回版本信息、接收更新报告、提供补丁下载 | [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md) | -| Packet | `src\Server\wwwroot\packages` | 可下载的 `.zip` 更新包和 `versions.json` 元数据 | [GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool.md) | -| Tools | GeneralUpdate.Tools 仓库 | 生成补丁包、Hash、OSS 清单、manifest 和仿真报告 | [GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool.md) | +| Packet | `src\Server\wwwroot\packages` | 可下载的 `.zip` 更新包和 `versions.json` 元数据 | [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md) | +| Tools | GeneralUpdate.Tools 仓库 | 生成补丁包、Hash、OSS 清单、manifest 和仿真报告 | [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md) | | Bowl | Hub Samples 中集成 | 监控进程异常并导出失败信息 | [GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl.md) | | Differential | Hub Samples + Core 默认集成 | 对 old/new 文件生成差分，并在更新阶段应用 | [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential.md) | @@ -240,7 +240,20 @@ Hub 提供了 9 个内置样例，覆盖了 GeneralUpdate 的主要使用场景 跑通这条链路后，建议按顺序阅读： 1. [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)：更新策略、事件通知、静默更新、manifest 极简配置。 -2. [GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool.md)：补丁包、Hash、OSS Config、Simulation。 +2. [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md)：补丁包、Hash、OSS Config、Simulation。 3. [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential.md)：差分算法、并行处理和 Clean/Dirty。 4. [GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl.md)：崩溃监控、备份和失败恢复。 -5. [高级实战手册](./Advanced cookbook.md)：生产环境部署、CI/CD 集成、企业级方案设计。 +5. [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md)：补丁包、Hash、OSS Config、Simulation。 + +## Sample UI + +示例程序界面预览： + +![](imgs\sampleclient.png) + +![](imgs\sampleupgrade.png) + +| 仓库地址 | +| --- | +| [ClientSample.sln](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/ClientSample.sln) | +| [UpgradeSample.sln](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/UpgradeSample.sln) | diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.PacketTool.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/GeneralUpdate.PacketTool.md similarity index 100% rename from website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.PacketTool.md rename to website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/GeneralUpdate.PacketTool.md diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Quik start.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Quik start.md deleted file mode 100644 index 9a30f6a..0000000 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Quik start.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -slug: quikstart -title: GeneralUpdate -authors: juster -tags: [quikstart] ---- - - - -## Step1 - -在Github上下载Sample仓库，使用示例前请确保本地安装了.NET 8的运行环境。 - -- https://github.com/GeneralLibrary/GeneralUpdate-Samples - -仓库目录内容如下： - -![](imgs\content.png) - -| 名称 | 说明 | -| ------------- | --------------------- | -| Client | 主客户端示例程序 | -| Server | 服务端示例程序 | -| StartManager | 更新流程控制台 | -| Upgrade | 升级端示例程序 | -| process.bat | 无需关注 | -| resource.bat | 无需关注 | -| start.cmd | 启动更新示例的脚本 | -| oss_start.cmd | 启动OSS更新示例的脚本 | - - - -## Step2 - -找到文件目录，并双击（每次启动start.cmd脚本都会重置本地目录所以无需手动管理文件目录）： - -```shell -...\GeneralUpdate-Samples\src\start.cmd -``` - -![](imgs\build.png) - - - -如下图所示，自动开始编译并拷贝所有相关项目的bin目录到app目录下： - -``` -...\GeneralUpdate-Samples\src\run\app -``` - -![](imgs\build.png) - - - -我们进入到app目录之后，可以看到这是没有升级之前的目录。 - -![](imgs\rundir.png) - - - -## Step3 - -检查完app目录之后： - -- 输入选项1然后回车 -- 服务端示例程序启动 -- 主客户端示例程序启动，开始请求更新（主客户端程序更新完成之后会自动关闭）。 - -![](imgs\upgrade.png) - - - -看到主客户端程序自动关闭，我们再去检查一下run\app目录。会发现多了一个备份目录“app-1.0.0.0”和一个“Congratulations on the update.txt”。 - -![](imgs\rundir2.png) - -看到这里代表您已经成功的完成了一次升级，Congratulations！ - -![](imgs\result.png) diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Sample UI.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Sample UI.md deleted file mode 100644 index 1c72ec1..0000000 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/Sample UI.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -slug: sampleui -title: UI -authors: juster -tags: [sampleui] ---- - -## 示例 UI - -![](imgs\sampleclient.png) - -![](imgs\sampleupgrade.png) - - - -| 仓库地址 | -| ------------------------------------------------------------ | -| https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/ClientSample.sln | -| https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/UpgradeSample.sln | - diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/releaselog/GeneralUpdateReleaselog.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/releaselog/GeneralUpdateReleaselog.md index 19ba0b8..18409e2 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/releaselog/GeneralUpdateReleaselog.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/releaselog/GeneralUpdateReleaselog.md @@ -5,56 +5,66 @@ authors: juster tags: [log] --- -# 📒更新日志 +# 📒Release log -## 📍2026-04-10 +### 📍2026-05-20 — v10.5.0-beta.2 -- 新增 `AddListenerUpdatePrecheck(Func)` 到 `GeneralClientBootstrap` —— 统一的更新预检入口，接收完整版本信息并通过返回值决定是否跳过（`true` = 跳过，`false` = 继续）；替代旧的 `AddListenerUpdateInfo` + `SetCustomSkipOption` 组合。强制更新（`IsForcibly`）时，回调返回值被忽略，更新始终执行。 -- 移除已废弃的 `SetCustomSkipOption`。 -- 新增 `AddListenerUpdateInfo(Action)` 到 `GeneralClientBootstrap` 和 `GeneralUpdateBootstrap` —— 在版本验证完成后立即触发；`VersionInfo` 新增 `UpdateLog` 字段用于携带版本更新日志。 -- 新增静默更新模式（`UpdateOption.EnableSilentUpdate`）—— 在后台每 20 分钟轮询检测新版本，静默准备更新包，在主程序退出后自动启动升级流程。 -- 新增 `ConfiginfoBuilder` —— `Configinfo` 的零配置构建器，仅需 `UpdateUrl`、`Token`、`Scheme` 三个参数，其他字段自动从 `.csproj` 文件和运行时平台（Windows / Linux / macOS）检测。 -- 新增 `DriverDirectory` 字段到 `Configinfo` / `BaseConfigInfo`，并通过 `ConfigurationMapper`、`ProcessInfo`、`PipelineContext` 传递至 `DrivelutionMiddleware`，以支持驱动更新功能。 -- 移除 `GeneralUpdateBootstrap` 中已废弃的 `SetFieldMappings` 方法。 -- 为 `GeneralUpdate.Bowl`、`GeneralUpdate.Extension`、`GeneralUpdate.Core`、`GeneralUpdate.ClientCore`、`GeneralUpdate.Drivelution` 补充完整的生命周期追踪（`GeneralTracer`）。 -- 修复 `DefaultCleanMatcher.Match` 对不同目录下同名文件错误返回 `null` 的问题。 -- 修复 `BinaryHandler.Dirty` 中遗留临时文件导致重复更新时补丁失败的问题。 +- **GeneralUpdate.Core**: 统一 `GeneralUpdateBootstrap` 入口，合并原 ClientCore 和 Core 能力；新增 `SetSource()` 轻配置入口与 `generalupdate.manifest.json` 极简接入；重构下载子系统为可替换的 5 层模型（Source/Policy/Executor/Pipeline/Orchestrator）；扩展点体系增至 10 个可替换接口 +- **GeneralUpdate.Bowl**: `BowlContext` 配置 API 稳定；优化 Windows/Linux/macOS ProcDump 集成 +- **GeneralUpdate.Differential**: 稳定 `IBinaryDiffer` 抽象；BSDIFF 4.0 + Streaming HDiff 双算法；BZip2 / Deflate 压缩 +- **GeneralUpdate.Drivelution**: 稳定跨平台驱动更新流水线；Windows pnputil / Linux insmod-dpkg-rpm / macOS kextload-installer +- **GeneralUpdate.Extension**: 稳定 `IExtensionHost` 抽象；Zip Slip 安全解压；拓扑排序依赖解析 +- **文档**: 重构全部 5 个组件文档为统一模板；新增入门实战手册；新增软件外包服务页面 +- **Samples**: Hub 示例浏览器 9 个场景覆盖完整更新/OSS/静默/推送/差分/压缩/扩展/Bowl/驱动 +### 📍2026-04-10 +- Add `AddListenerUpdatePrecheck(Func)` to `GeneralClientBootstrap` — unified entry that receives the full version info and returns `true` to skip or `false` to proceed; replaces the combined use of `AddListenerUpdateInfo` + `SetCustomSkipOption`. Forced-update (`IsForcibly`) versions always proceed regardless of the callback return value. +- Remove deprecated `SetCustomSkipOption` from `GeneralClientBootstrap`. +- Add `AddListenerUpdateInfo(Action)` to `GeneralClientBootstrap` and `GeneralUpdateBootstrap` — dispatched immediately after version validation; each `VersionInfo` entry now carries a new `UpdateLog` field for release notes. +- Add opt-in silent update mode (`UpdateOption.EnableSilentUpdate`) to `GeneralClientBootstrap` — polls every 20 minutes in the background, prepares the update package silently, and launches the updater only after the host process exits. +- Add `ConfiginfoBuilder` — zero-configuration builder for `Configinfo`; only `UpdateUrl`, `Token`, and `Scheme` are required; all other fields are auto-detected from the `.csproj` file and the runtime platform (Windows / Linux / macOS). +- Add `DriverDirectory` field to `Configinfo` / `BaseConfigInfo` and propagate it through `ConfigurationMapper`, `ProcessInfo`, and `PipelineContext` to `DrivelutionMiddleware` for driver update support. +- Remove `SetFieldMappings` from `GeneralUpdateBootstrap`. +- Add full lifecycle tracing (`GeneralTracer`) across `GeneralUpdate.Bowl`, `GeneralUpdate.Extension`, `GeneralUpdate.Core`, `GeneralUpdate.ClientCore`, and `GeneralUpdate.Drivelution`. +- Fix `DefaultCleanMatcher.Match` incorrectly returning `null` for same-name files in different directories. +- Fix orphaned temp files in `BinaryHandler.Dirty` causing patch failures on repeated update runs. -## 📍2026-01-06 10.0.0 -- 适配.NET10升级引用组件版本。 -- 新增.NET 10 dotnet run x.cs脚本化运行GeneralUpdate。 -- 重构部分功能。 +### 📍2026-01-06 10.0.0 +- Adapt to .NET 10 upgrade and update the versions of referenced components. +- Add scripted execution of GeneralUpdate via `dotnet run x.cs` for .NET 10. +- Refactor part of the functions. -## 📍2026-01-01 9.5.10 -- 修复BinaryHandler中File.Move(_newfilePath, _oldfilePath);文件占用问题。 -- 修复在 linux 下 Environments.GetEnvironmentVariable("ProcessInfo") 为空问题。 -- 新增在Linux 中给更新后的文件设置可执行程序权限。 -- 重构部分功能。 + +### 📍2026-01-01 9.5.10 + +- Fix the file occupation issue in `BinaryHandler` caused by `File.Move(_newfilePath, _oldfilePath)`. +- Fix the null value issue of `Environments.GetEnvironmentVariable("ProcessInfo")` on Linux. +- Add the function to set executable permissions for updated files on Linux. +- Refactor part of the functions. ## 📍2025-02-20 9.1.6 -- 修复OSS无需更新的时候直接关闭当前进程。 +- Fix OSS to directly terminate the current process when no update is required. -## 📍2025-01-13 9.1.5 +## 📍2025-01-14 9.1.5 -- 修复LastVersion取值错误问题 +- Fix the issue with incorrect value retrieval for LastVersion. ## 📍2025-01-13 9.1.4 -- 修复Environment.SetEnvironmentVariable函数带来的执行缓慢问题。 -- 在黑名单中添加了以下ClientCore 和 Core共同引用的文件（整个打包、升级流程都不会操作这些文件）： +- Fix the execution slowness issue caused by the `Environment.SetEnvironmentVariable` function. +- Added the following files common to ClientCore and Core to the blacklist (these files will not be operated on during the entire packaging and upgrade process): ```c# "Microsoft.Bcl.AsyncInterfaces.dll", @@ -66,321 +76,290 @@ tags: [log] -## 📍2025-01-05 9.1.2 +## 📍2025-01-05 Version 9.1.2 -- 修复hash校验异常继续执行更新问题 -- 解除Common组件和Differential组件与Bowl / ClientCore / Core引用，解决相互升级出现dll占用问题。 +- Fixed the issue where updates would continue despite hash verification exceptions. +- Removed the references of the Common and Differential components from Bowl / ClientCore / Core to resolve the DLL usage issue during mutual upgrades. -- 说明Common和Differential仅存在于GeneralUpdate解决方案中更新迭代，不再更新至Nuget平台。Common组件和Differential组件所有用的能力通过代码文件引用的方式继续存在于Bowl / ClientCore / Core组件中。开发者无需再关心Common和Differential组件是否引用。 +- Note: The Common and Differential components will only be updated and iterated within the GeneralUpdate solution and will no longer be updated on the NuGet platform. The capabilities provided by the Common and Differential components will continue to exist in the Bowl / ClientCore / Core components through code file references. Developers no longer need to worry about whether the Common and Differential components are referenced. ## 📍2025-01-04 9.1.0 -- 添加屏蔽指定文件夹跳过功能（指定参数会流转Client、Upgrade）。 -- 添加http请求头传入Scheme 和 Token参数。 -- 修复OSS Samples 更新失败问题。 -- 修改OSS 功能更新完成不删除更新包问题。 -- 修复 Samples 中 Client 和 Upgrade 只启动Client更新问题。（出现循环更新的现象是因为没有修改本地版本号） -- 所有Sample 从9.0.0升级库至9.1.0。 +- Add a feature to skip specified folders (specified parameters will be passed through Client and Upgrade). +- Add Scheme and Token parameters to the HTTP request headers. +- Fix the issue of OSS Samples failing to update. +- Modify the OSS feature to not delete the update package upon completion. +- Fix the issue in Samples where only the Client updates, not the Upgrade. (The looping update occurred because the local version number was not changed) +- Upgrade all Samples from version 9.0.0 to 9.1.0. ## 📍2024-11-28 9.0.0 -- 更新所有组件C#语法均升级至C#13。 - -- 优化、重构、精简代码，以最少的代码实现功能降低代码阅读难度。 - -- 简化了GeneralClientBootstrap的传入参数复杂度。 - -- 移除Strategys参数设置，内置在组件内可自推断所在操作系统平台切换更新策略，开发者无需再关心更新策略设置。 +- Upgrade all components to C# 13 syntax. -- 新增驱动更新、备份、安装功能。 +- Optimize, refactor, and simplify code to achieve functionality with minimal code, reducing the difficulty of code reading. -- 优化了自动升级流程，更新状态的四种工作流： +- Simplified the complexity of input parameters for GeneralClientBootstrap. - 1.客户端需要升级、升级端需要升级 +- Removed Strategys parameter settings; these are now built into the component, automatically deducing the operating system platform to switch update strategies, so developers no longer need to manage update strategy settings. - 2.客户端不需要升级、升级端不需要升级 +- Added features for driver updates, backups, and installations. - 3.客户端不需要升级、升级端需要升级 +- Optimized the automatic upgrade process with four types of update workflows: - 4.客户端需要升级、升级端不需要升级 + 1. Client needs an upgrade, update server needs an upgrade. + + 2. Client does not need an upgrade, update server does not need an upgrade. + + 3. Client does not need an upgrade, update server needs an upgrade. + + 4. Client needs an upgrade, update server does not need an upgrade. -- 如果更新失败的版本将会存储在本地，回滚之后再遇到失败版本则跳过更新。 +- If an update fails, the version will be stored locally, and upon rollback, the failed version will be skipped on subsequent attempts. -- GeneralUpdate的OSS功能目前仅支持windows，仅支持zip压缩格式。 +- GeneralUpdate's OSS feature currently supports only Windows and only the zip compression format. -- 移除GeneralUpdateOSS通知所有事件。 +- Removed all event notifications from GeneralUpdateOSS. -- 新增GeneralUpdate.Bowl组件 +- Introduced the GeneralUpdate.Bowl component. -- GeneralUpdate.Bowl包含回滚、监测、导出dump功能（Only windows，linux会陆续开放）。 +- GeneralUpdate.Bowl includes rollback, monitoring, and dump export functionalities (Only for Windows; Linux support will be added gradually). -- 新增GeneralUpdate.Common组件 +- Introduced the GeneralUpdate.Common component. -- 移除GeneralUpdate.Zip组件 +- Removed the GeneralUpdate.Zip component. -- 移除GeneralUpdate.AspnetCore组件 +- Removed the GeneralUpdate.AspnetCore component. -- 移除MultiDownloadProgressChangedEvent，将该事件的通知内容合并至MultiDownloadStatisticsEvent。 +- Removed the MultiDownloadProgressChangedEvent, merging its notification content into the MultiDownloadStatisticsEvent. -- 移除遗言功能，由GeneralUpdate.Bowl代替。 +- Removed the legacy feature, replaced by GeneralUpdate.Bowl. -- 移除7z压缩格式支持，仅支持zip压缩格式。 +- Removed support for the 7z compression format; only zip compression is supported now. -- 移除ProgressType几种工作模式通知事件参数。 +- Removed ProgressType notification event parameters for various working modes. -- 移除VersionHub，由UpgradeHubService替代（推送功能）。 +- Replaced VersionHub with UpgradeHubService (push functionality). -- 更新组件内所有Hash值相关校验、生成均为SHA256算法，移除MD5算法。 +- Updated all hash value-related checks and generation within components to the SHA256 algorithm, removing the MD5 algorithm. -- 新增更新前备份当前程序所有文件内容。 +- Added functionality to back up all current program files before updating. -- 支持Ubuntu操作系统。 +- Added support for the Ubuntu operating system. -- 兼容并支持AOT编译，移除或重构所有不利于AOT编译或使用的代码。 +- Compatible with and supports AOT compilation, removing or refactoring all code detrimental to AOT compilation or usage. -- 所有组件版本号跟随.NET Core的框架版本号。并且统一共享一个版本号，不再各自维护单独的版本号。 +- All component version numbers follow the .NET Core framework version number, sharing a unified version number instead of maintaining separate ones. -- 更新Sample示例更新，使用bat脚本一键生成。 +- Updated Sample example updates, allowing for one-click generation using bat scripts. -- 修复了若干issue中提出的bug。 +- Fixed several bugs reported in issues. -- 转移GeneralUpdate.Maui.OSS和GeneralUpdate.OSS类库至新仓库GeneralUpdate.Maui。 +- Moved GeneralUpdate.Maui.OSS and GeneralUpdate.OSS libraries to a new repository GeneralUpdate.Maui. -- GeneralUpdate.Differential移除GeneralUpdate.Zip引用，并且移除所有压缩包处理能力。 +- GeneralUpdate.Differential removed the GeneralUpdate.Zip reference and all compression package handling capabilities. -- 新增升级流程上报服务器升级状态，升级状态为待更新、更新失败、更新成功。 +- Added reporting of the upgrade process to the server with statuses like pending update, update failed, and update successful. -- 重构GeneralUpdate.Tools为Avalonia版本，适配在Linux操作系统上制作差分补丁包。 +- Refactored GeneralUpdate.Tools to an Avalonia version, adapting it for creating differential patch packages on Linux operating systems. ## 📍2023-08-05 -在企业产品发布到市场之前需要对功能进行测试，在大部分公司里自动升级功能不像产品功能一样有需求文档或者业务说明等文档。通常的要求就是能正常升级公司产品或能增量更新节约流量即可。这时候对测试经验不足的人员来说测试不充分或者大家都没有考虑到将会造成很多麻烦。（这里只是提供一种测试的思路，并非专业测试指导请辩证看待） +Before releasing an enterprise product to the market, it's crucial to test its features. In many companies, the auto-update feature often lacks documentation such as requirement documents or business specifications, unlike other product features. Typically, the main requirement is that the product can be updated smoothly or incrementally to save bandwidth. For testers with insufficient experience, this can lead to inadequate testing or overlooked issues, causing numerous problems. (This is just a testing approach and not professional testing guidance, so please consider it critically.) -1.测试版本升级顺序 +1. **Testing Version Upgrade Order** -假设市场上所有的客户现在使用的程序版本是v1.0.0.0，我们即将发布v2.0.0.0。在发布之前就需要在测试环境中将两个版本升级测试一下。 + Assume all customers are currently using version v1.0.0.0, and we are about to release v2.0.0.0. Before release, both versions need to be tested in a test environment. -- 下载更新包时 -- 正在更新文件时 -- 强制中断程序运行、断网、直接断电、模拟弱网、模拟崩溃等 + - While downloading the update package + - During file updates + - Simulate program interruption, network disconnection, power outages, weak network conditions, crashes, etc. -2.加密文件无法升级 +2. **Encrypted Files Cannot Be Upgraded** -在GeneralUpdate中在两个版本中提取二进制差分更新补丁文件时，会出现加密文件无法被差分算法识别的情况这个时候需要考虑在生成差分补丁包时，将加密过的文件加入到（SetBlacklist）黑名单中或者考虑直接覆盖（直接打在压缩包里）。 + In GeneralUpdate, when extracting binary differential update patches between two versions, encrypted files may not be recognized by the differential algorithm. Consider adding encrypted files to a blacklist (SetBlacklist) or directly including them in the compressed package. -3.失败回滚或者重新升级？ +3. **Failure Rollback or Re-upgrade?** -这方面也是企业中大家最在意的一点，自动升级虽然能带来诸多好处。但是升级失败会直接导致客户端根本没法使用这是非常致命的，后续我会考虑在GeneralUpdate中新增两种策略来解决这个问题。 + This is a major concern in enterprises. While auto-updates offer many benefits, a failed update can render the client unusable, which is critical. I plan to add two strategies in GeneralUpdate to address this issue. -- 策略一 + - **Strategy One:** + Back up files or directories to be updated before the upgrade. If the update fails, the backup files will be restored upon the second startup, and the auto-update will be disabled to prevent further updates after restoration. -升级之前将需要被更新的文件或目录进行备份，如果更新失败第二次启动则会将备份文件还原至原来的目录，并关闭自动升级的开关以防止文件还原之后再次进行自动升级。 + - **Strategy Two:** + This is my preferred method. The essence of auto-updates is to upgrade, not roll back. The initial idea is to introduce a "last words" mechanism. To handle exceptions during updates that may corrupt files, the program should report the update status to the server after each update. If the client doesn't respond within 30 minutes, it is considered a destructive update failure (file corruption). Upon each startup, the upgrade program reads the last update's status. If the previous update failed, it automatically downloads and installs the client package (compressed package). Alternatively, introduce an update daemon process to receive real-time push notifications for automated downloads and installations. -- 策略二 +4. **Project Structure Adjustments** -这个是我内心中比较推荐的升级方式，因为自动升级程序的意义就是升级而不是回滚。目前初步的想法是新增遗言机制。为解决在更新时遇到异常情况，导致文件损坏更新的问题。1.每次更新完成，需返回给服务器更新状态。如果客户端在30分钟内没有任何反馈则判定为毁坏性更新失败。（文件损坏）2.升级程序每次启动时会读取上一次更新的遗言，如果上次更新为失败自动化下载、安装客户端安装包（压缩包）3.或者新增更新守护进程接收实时推送自动化下载、安装客户端安装包（压缩包） + If developers make structural changes to the project, such as moving or renaming modules in a client program based on IoC principles (e.g., Prism framework), it may lead to exceptions where the IoC container can't find the DLL after an update. Consider file path changes during updates, and testers should routinely inquire about such changes. -4.项目结构调整 +5. **Final Testing as a Closed-Loop Process** -如果开发人员对项目结构发生了一些结构性质的修改。例如基于IoC思想搭建的客户端程序，例如Prism框架如果开发人员把其中的一个Module更换了文件夹的位置或者文件夹名称修改了，导致用户的客户端更新了之后IoC容器启动之后找不到该DLL的异常情况。更新时需要考虑到文件路径变化的问题。测试人员也有责任例行询问是否有该种类的变化。 + This is crucial. If auto-updates are tested early, subsequent bug fixes or changes may introduce unknown issues. Therefore, conducting tests as the final closed-loop process is recommended (adjust as needed for special cases). -5.作为最后闭环流程再测试 +6. **Weak Network Environment Testing** -这个事项是非常需要注意的，如果前面就把自动升级先测试了。如果后续有bug修复或者其他变动都有可能会造成未知的异常情况出现。所以作为最后的闭环流程进行测试是比较推荐的（如有特殊情况按需要调整即可）。 + Use tools like NetLimiter and Clumsy to simulate weak network conditions. For detailed usage, refer to my article: [Link](https://mp.weixin.qq.com/s?__biz=MzI5MTg4NzIyNg==&mid=2247486705&idx=1&sn=b2eac543ea7f738bdbe8c3cc63da3488&chksm=ec088de4db7f04f25e5603d2309d61279b0f94ee6eef34129801755a86cf406f863896214b3c&token=1809721461&lang=zh_CN#rd). -6.弱网环境测试 +7. **Gray Release** -弱网环境模拟可以借助NetLimiter和Clumsy来进行测试，具体使用方法可以参考我的这篇文章。 + Before releasing a version, thorough testing is necessary. -[https://mp.weixin.qq.com/s?__biz=MzI5MTg4NzIyNg==&mid=2247486705&idx=1&sn=b2eac543ea7f738bdbe8c3cc63da3488&chksm=ec088de4db7f04f25e5603d2309d61279b0f94ee6eef34129801755a86cf406f863896214b3c&token=1809721461&lang=zh_CN#rd](https://mp.weixin.qq.com/s?__biz=MzI5MTg4NzIyNg==&mid=2247486705&idx=1&sn=b2eac543ea7f738bdbe8c3cc63da3488&chksm=ec088de4db7f04f25e5603d2309d61279b0f94ee6eef34129801755a86cf406f863896214b3c&token=1809721461&lang=zh_CN&scene=21#wechat_redirect) + - For large customer bases, conduct a small-scale gray release before full release to all customers. + - For gray upgrades, avoid setting the version as mandatory; let users choose whether to upgrade. -7.灰度发布 +8. **Targeted Upgrades** -版本发布之前就需要做好测试。 + GeneralUpdate currently supports receiving push notifications of the latest version updates via Signal R. If a client with multiple devices has one device experiencing issues due to hardware or software environment problems, targeted fixes are necessary. In this case, use one-to-one upgrades for precise updates on the problematic device. -- 如果面对的客户群体庞大则需要小范围的灰度发布，如果没有问题再选择发布给市场上所有客户。 -- 如果是灰度升级版本，这个时候就不要设置为强制更新的版本了。让用户自己选择是否升级。 +9. **Compatibility of Old Configurations with New Versions** -8.精准升级 + When different branches of a version exist in the market, consider local configuration files during auto-update upgrades. If the new version's program requires reading configuration files, incompatible old version configurations may cause issues. Testers should be aware of this scenario. -在GeneralUpdate中目前已有的基于Signal R接收推送最新版本更新的方式。假设在市场上有很多客户，每个客户有很多台设备。那么其中客户A有10台电脑，只有其中一台电脑因为硬件或者软件环境出现了问题导致客户端的功能异常。这个时候需要紧急针对该台设备的情况进行修复，这个时候并不清楚这个修改会不会对现在已经正常运行的客户端程序有影响。这个时候可以考虑使用一对一的升级方式精准升级某台出问题的电脑。 + To avoid such issues, store frequently changing configurations on the server to be read at each login, while storing stable configurations locally. -9.老配置兼容新版本 +10. **Automated Testing** -在市场上如果存在各个分支的版本时，每次自动更新升级还需要考虑到本地配置文件的问题。如果升级到新版本的程序之后需要读配置文件这个时候，老版本的配置文件兼容不了也会造成问题。这个时候测试人员也需要注意该种场景。 - -规避这种问题的方式可以把大部分容易变动的配置放到服务端每次登录的时候去读取。把不容易变化的配置保存到本地。 - -10.自动化测试 - -自动升级的自动测试化测试的脚本编写也非常重要，在多分支、多版本的升级测试中节省时间,增加测试的准确性。 + Writing scripts for automated testing of auto-updates is crucial. It saves time and increases accuracy in multi-branch and multi-version upgrade testing. ## 📍2023-07-23 -开发者提问： - -- （1）在更新过程中出现了断网、断电、电脑死机、突然蓝屏、程序假死等意外情况，导致应用程序无法正常进行更新或者无法正常启动如何解决？能否让更新程序回滚到这次更新之前？ - -答：这个问题分两块回答，（1）意外情况可以尝试重启应用程序断点下载更新，目前的情况来说如果在更新过程中出现文件损坏无法只能重新安装。后续会考虑增加一种机制处理更新异常情况无法启动客户端应用程序的问题。（2）不能，因为目前的想法来说自动升级程序的核心意义就是升级，如果回滚回去了升级可能就失去了意义。可能会希望及时发现问题，然后紧急更新一个安全的更新包让客户端逐版本更新直到成功。 +Developer Questions: +1. **What should be done if unexpected situations like network disconnection, power outage, computer crash, sudden blue screen, or program freeze occur during the update process, causing the application to fail to update or start properly? Can the update program roll back to the previous version?** + **Answer:** This question can be divided into two parts: + + (1) In the event of unexpected situations, you can try restarting the application to resume the update download from the breakpoint. Currently, if files become corrupted during the update, reinstallation is the only option. In the future, we plan to introduce a mechanism to handle situations where the client application cannot start due to update anomalies. + + (2) Rolling back is not possible because the core purpose of the auto-update program is to facilitate updates. Rolling back could negate the purpose of the update. It is preferable to quickly identify issues and urgently release a safe update package to allow clients to update incrementally until successful. -- （2）如果更新包打包本身（更新包里本身就有异常文件）就有问题，更新完成之后程序无法正常启动。能不能回滚或者备份？ +2. **What if the update package itself contains issues (e.g., abnormal files), causing the program to fail to start after the update? Can it roll back or back up?** - 答：不能，在该版本发布之前就需要做好测试。如果面对的客户群体庞大则需要小范围的灰度发布，如果没有问题再选择发布给市场上所有客户。 - - - -- （3）如果客户端本地保存了一些数据文件，在保留之前的数据的文件基础上需要新增一些内容，例如sqlite的.db文件更新之后被之前的.db文件被覆盖，如何解决？或者增量更新是否可以正常更新这些文件？ - -答：之前有开发过这样的功能，效果不好暂时下线了；后续需要重新设计再启用该类功能。组件目前的功能完成度暂时无法解决这个问题，只能覆盖。增量更新也有极大的可能更新不了这种情况。 + **Answer:** No, comprehensive testing must be conducted before the version is released. For a large customer base, a small-scale gray release should be conducted first. If no issues arise, then the release can be extended to all customers in the market. +3. **If the client locally stores some data files and needs to add new content while retaining previous data (e.g., updating a SQLite .db file without overwriting the old .db file), how can this be resolved? Can incremental updates handle such files?** + **Answer:** We previously developed such a feature, but it was ineffective and has been temporarily discontinued. It will require a redesign before being reinstated. Currently, the component's functionality cannot address this issue, and the only option is to overwrite. Incremental updates are also unlikely to handle this situation effectively. ## 📍2023-04-23 -使用技术更新 - -黑名单功能，OSS新功能发布，针对windows和.NET MAUI Android 版本。修复了部分bug和重构了组件整体的事件管理通知机制。 - -1.发布内容 - -| 组件名称 | 版本号（old） | 版本号（new） | 状态 | -| -------------------------- | ------------- | ------------- | ------ | -| GeneralUpdate.AspNetCore | 1.4.1 | - | - | -| GeneralUpdate.ClientCore | 2.8.9 | 2.12.9 | 新版本 | -| GeneralUpdate.Core | 4.11.18 | 4.14.18 | 新版本 | -| GeneralUpdate.Differential | 1.3.0 | 1.4.1 | 新版本 | -| GeneralUpdate.Zip | 1.3.0 | - | - | -| GeneralUpdate.Tool | 2.2.5 | 2.3.5 | 新版本 | -| GeneralUpdate.Single | 1.0.0 | - | - | -| GeneralUpdate.Maui.OSS | 1.0.0 | 1.0.0 | 新版本 | - +### Technical Update Overview +**New Features: Blacklist Functionality and OSS Support for Windows and .NET MAUI Android Versions** -【1】组件GeneralUpdate.ClientCore +This update focuses on bug fixes and a complete refactoring of the event management notification system across components. -1.新增OSS更新功能 +#### Release Details -2.新增黑名单功能 +| Component Name | Version (Old) | Version (New) | Status | +| -------------------------- | ------------- | ------------- | ------- | +| GeneralUpdate.AspNetCore | 1.4.1 | - | - | +| GeneralUpdate.ClientCore | 2.8.9 | 2.12.9 | Updated | +| GeneralUpdate.Core | 4.11.18 | 4.14.18 | Updated | +| GeneralUpdate.Differential | 1.3.0 | 1.4.1 | Updated | +| GeneralUpdate.Zip | 1.3.0 | - | - | +| GeneralUpdate.Tool | 2.2.5 | 2.3.5 | Updated | +| GeneralUpdate.Single | 1.0.0 | - | - | +| GeneralUpdate.Maui.OSS | 1.0.0 | 1.0.0 | New | -3.重构事件，添加事件管理机制 +#### Component Updates -4.修复，增量包只能识别新增，不能识别删除 +**1. GeneralUpdate.ClientCore** +- Added OSS update functionality. +- Introduced blacklist functionality. +- Refactored events with a new event management mechanism. +- Fixed issue where incremental packages could only recognize additions, not deletions. +**2. GeneralUpdate.Core** -【2】组件GeneralUpdate.Core +- Added OSS update functionality. +- Refactored events with a new event management mechanism. +- Fixed issue where incremental packages could only recognize additions, not deletions. -1.新增OSS更新功能 +**3. GeneralUpdate.Differential** -2.重构事件，添加事件管理机制 +- Fixed issue where incremental packages could only recognize additions, not deletions. -3.修复，增量包只能识别新增，不能识别删除 +#### Changes in GeneralUpdate.ClientCore and GeneralUpdate.Core +1. **Event Subscription Mechanism** + - The event subscription mechanism is refactored. Instead of using `event +=`, events are now managed through an `EventManager`. This requires minimal code changes for developers and reduces the component's codebase by favoring composition over inheritance. +2. **Blacklist Management** + - Added the `SetBlacklist` method to manage files you don't want to update. The component has built-in default blacklist files: `{ "Newtonsoft.Json.dll" }` and default blacklist file extensions: `{ ".patch", ".7z", ".zip", ".rar", ".tar" , ".json" }`. -【3】组件GeneralUpdate.Differential - -1.修复，增量包只能识别新增，不能识别删除 - -2.1 组件GeneralUpdate.ClientCore、组件GeneralUpdate.Core改动 - -1.事件订阅机制重构之后不再使用event+=订阅方式，通过事件EventManger添加事件监听。对于开发者来说只需要轻微的代码修改即可适应新版本。对于组件本身而言减少大量的代码，组合优于继承。 - -2.添加黑名单管理SetBlacklist方法，可以设置不想更新的某个具体文件或者某个类型的文件，组件内置默认黑名单文件：{ "Newtonsoft.Json.dll" } 默认黑名单文件扩展名：{ ".patch", ".7z", ".zip", ".rar", ".tar" , ".json" }。 - -```c# - Task.Run(async () => - { - //ClientStrategy该更新策略将完成1.自动升级组件自更新 2.启动更新组件 3.配置好ClientParameter无需再像之前的版本写args数组进程通讯了。 - //generalClientBootstrap.Config(baseUrl, "B8A7FADD-386C-46B0-B283-C9F963420C7C"). - var configinfo = GetWindowsConfiginfo(); - var generalClientBootstrap = await new GeneralClientBootstrap() - //单个或多个更新包下载通知事件 - .AddListenerMultiDownloadProgress(OnMultiDownloadProgressChanged) - //单个或多个更新包下载速度、剩余下载事件、当前下载版本信息通知事件 - .AddListenerMultiDownloadStatistics(OnMultiDownloadStatistics) - //单个或多个更新包下载完成 - .AddListenerMultiDownloadCompleted(OnMultiDownloadCompleted) - //完成所有的下载任务通知 - .AddListenerMultiAllDownloadCompleted(OnMultiAllDownloadCompleted) - //下载过程出现的异常通知 - .AddListenerMultiDownloadError(OnMultiDownloadError) - //整个更新过程出现的任何问题都会通过这个事件通知 - .AddListenerException(OnException) - .Config(configinfo) - .Option(UpdateOption.DownloadTimeOut, 60) - .Option(UpdateOption.Encoding, Encoding.Default) - .Option(UpdateOption.Format, Format.ZIP) - .Strategy() - //注入一个func让用户决定是否跳过本次更新，如果是强制更新则不生效 - .SetCustomOption(ShowCustomOption) - //默认黑名单文件：{ "Newtonsoft.Json.dll" } 默认黑名单文件扩展名：{ ".patch", ".7z", ".zip", ".rar", ".tar" , ".json" } - //如果不需要扩展，需要重新传入黑名单集合来覆盖。 - .SetBlacklist(GetBlackFiles(), GetBlackFormats()) - .LaunchTaskAsync(); - }); +```csharp +Task.Run(async () => +{ + var configinfo = GetWindowsConfiginfo(); + var generalClientBootstrap = await new GeneralClientBootstrap() + .AddListenerMultiDownloadProgress(OnMultiDownloadProgressChanged) + .AddListenerMultiDownloadStatistics(OnMultiDownloadStatistics) + .AddListenerMultiDownloadCompleted(OnMultiDownloadCompleted) + .AddListenerMultiAllDownloadCompleted(OnMultiAllDownloadCompleted) + .AddListenerMultiDownloadError(OnMultiDownloadError) + .AddListenerException(OnException) + .Config(configinfo) + .Option(UpdateOption.DownloadTimeOut, 60) + .Option(UpdateOption.Encoding, Encoding.Default) + .Option(UpdateOption.Format, Format.ZIP) + .Strategy() + .SetCustomOption(ShowCustomOption) + .SetBlacklist(GetBlackFiles(), GetBlackFormats()) + .LaunchTaskAsync(); +}); ``` +#### New OSS Functionality +**OSS (Object Storage Service)** is a familiar concept for backend developers, provided by major cloud service providers like Alibaba Cloud OSS, Tencent Cloud COS, and Huawei Cloud OBS. The update component adopts OSS for its naming and functionality, making it intuitive for developers to understand its purpose. -1.新增OSS功能 - -OSS的全称是对象存储服务（Object Storage Service），做服务端技术栈开发的小伙伴肯定对这个不陌生在各大云服务器厂商都会提供类似的服务,说简单点就是一个文件服务器。例如：阿里云OSS、腾讯云COS、华为云OBS，其实它们只是名字不一样功能服务都差不多。然后本更新组件新功能的实现思路非常相似那么就选择了OSS来为该功能命名，而且方便开发者一眼能get到这个功能的作用（需要使用组件GeneralUpdate.ClientCore、GeneralUpdate.Core）。 +**GeneralUpdate.OSS Operation Principle:** - - -2.GeneralUpdate.OSS运行原理 - -1.准备version.json版本信息配置文件，更新文件（update.zip）更新文件和之前的打包方式一样。 +1. Prepare a `version.json` configuration file and an update file (`update.zip`) as usual. ```json [ -{ -"PubTime": 1680443321, -"Name": "generalupdate.ossclient", -"MD5": "9bf414990a67e74f11752d03f49b15d8", -"Version": "1.0.4", -"Url": "http://192.168.50.203/update.zip" -}, -{ -"PubTime": 1680444916, -"Name": "generalupdate.ossclient", -"MD5": "JXC122DFXCZXZNMRFf11752d03f49b15d8", -"Version": "1.0.5", -"Url": "http://192.168.50.203/update2.zip" -} + { + "PubTime": 1680443321, + "Name": "generalupdate.ossclient", + "MD5": "9bf414990a67e74f11752d03f49b15d8", + "Version": "1.0.4", + "Url": "http://192.168.50.203/update.zip" + }, + { + "PubTime": 1680444916, + "Name": "generalupdate.ossclient", + "MD5": "JXC122DFXCZXZNMRFf11752d03f49b15d8", + "Version": "1.0.5", + "Url": "http://192.168.50.203/update2.zip" + } ] ``` -2.Client启动时直接请求OSS服务器或文件服务器，下载version.json文件。 +2. The client requests the OSS server or file server to download the `version.json` file at startup. +3. Upon downloading, it parses the version information to decide if an update is necessary. If so, it passes the info through the process to start `Upgrade` (the client self-closes). +4. `Upgrade` then downloads `update.zip`, extracts it, and overwrites local files. +5. Once the update completes, `Upgrade` restarts the client and self-closes. The update is finished. -3.下载到本地之后解析版本信息内容判断是否需要更新，如果将信息通过进程启动传递Upgrade（Client自我关闭）。 +**GeneralUpdateOSS** is easier to use compared to GeneralUpdateBootstrap. It downloads `version.json` and updates incrementally based on its content. -4.Upgrade启动之后直接去下载update.zip，下载到本地之后直接解压覆盖本地文件。 +#### Quick Start -5.Upgrade更新完成之后把Client启动起来，自我关闭。更新结束。 +**Client (Main Client) Code Example:** -GeneralUpdateOSS的功能和GeneralUpdateBootstrap功能对比来说，使用的门槛非常低如果公司对自动更新的要求不高的话可以使用这个功能。一句话概括这个功能就是下载version.json根据文件里的内容去逐版本下载更新包，下载下来之后直接解压更新就结束了。 - - - -3.快速启动 - -Client（主客户端）使用代码示例： - -```c# +```csharp Task.Run(async () => { var url = "http://192.168.50.203"; @@ -392,75 +371,54 @@ Task.Run(async () => }); ``` +**Upgrade (Upgrade Assistant) Code Example:** - -Upgrade(升级助手)使用代码示例： - -```c# +```csharp private static void Main(string[] args) { - Task.Run(async () => - { - //var url = "http://192.168.50.203"; - //var appName = "GeneralUpdate.Client"; - //var version = "1.0.0"; - //var versionFileName = "version.json"; - //SerializeUtil.Deserialize(args[0]); - //ParamsOSS @params = new ParamsOSS(url, appName, version, versionFileName); - ParamsOSS @params = SerializeUtil.Deserialize(args[0]); - await GeneralUpdateOSS.Start(@params,Encoding.Default); - }); + Task.Run(async () => + { + ParamsOSS @params = SerializeUtil.Deserialize(args[0]); + await GeneralUpdateOSS.Start(@params, Encoding.Default); + }); } ``` +**Event Notification Subscription:** - -4.事件通知订阅 - -在OSS的更新过程中，保留了更新事件的参数和之前一样。 - -```c# -//code... +```csharp GeneralUpdateOSS.AddListenerMultiDownloadStatistics(OnMultiDownloadStatistics); private static void OnMultiDownloadStatistics(object sender, MultiDownloadStatisticsEventArgs e) { - Console.WriteLine($" {e.Speed} , {e.Remaining.ToShortTimeString()}"); + Console.WriteLine($" {e.Speed} , {e.Remaining.ToShortTimeString()}"); } ``` +#### .NET MAUI OSS +The MAUI OSS functionality is similar to the OSS described above but is specifically for .NET MAUI, focusing on the Android platform. -2.3 .NET MAUI OSS - -MAUI OSS功能介绍和 11.OSS中介绍的是一样的。但是它是针对.NET MAUI编写的更新，使用的组件库是GeneralUpdate.Maui.OSS。目前只实现了MAUI Andorid平台的自动更新。 - -1.准备version.json版本信息配置文件，更新文件（update.apk）更新文件就直接是新版本的apk了(或.abb)。 +1. Prepare a `version.json` configuration file and an update file (`update.apk`), which is the new version's APK. ```json { -"PubTime": 1680444916, -"Name": "com.companyname.generalupdate.ossclient", -"MD5": "9bf414990a67e74f11752d03f49b15d8", -"Version": "1.0.5", -"Url": "http://192.168.50.203/com.companyname.generalupdate.ossclient.apk" + "PubTime": 1680444916, + "Name": "com.companyname.generalupdate.ossclient", + "MD5": "9bf414990a67e74f11752d03f49b15d8", + "Version": "1.0.5", + "Url": "http://192.168.50.203/com.companyname.generalupdate.ossclient.apk" } ``` -2.Client启动时直接请求OSS服务器或文件服务器，下载version.json文件。 - -3.下载到本地之后解析版本信息内容，判断是否需要更新。 - -4.需要更新则下载update.apk。 +2. The client requests the OSS server or file server to download the `version.json` file at startup. +3. After downloading, it parses the version information to decide if an update is necessary. +4. If an update is needed, it downloads `update.apk`. +5. Upon download completion, the Android OS handles the installation, and the new app version runs. -5.下载完成之后执行安装，这一步就交给了安卓操作系统执行。执行完成之后运行新版本app。 +**Quick Start:** - - -2.快速启动 - -```c# -//http://192.168.50.203/version.json +```csharp string url = "http://192.168.50.203"; string appName = "MainApplication.exe"; string currentVersion = "1.1.1.1"; @@ -470,272 +428,179 @@ GeneralUpdateOSS.AddListenerException(OnException); await GeneralUpdateOSS.Start(new ParamsAndroid(url, appName, "123456789", currentVersion, versionFileName)); ``` +**Event Notification Subscription:** - -3.事件通知订阅 - -```c# +```csharp GeneralUpdateOSS.AddListenerDownloadProcess(OnOSSDownload); GeneralUpdateOSS.AddListenerException(OnException); private void OnOSSDownload(object sender, OSSDownloadArgs e) { - Console.WriteLine($"{e.ReadLength},{e.TotalLength}"); + Console.WriteLine($"{e.ReadLength},{e.TotalLength}"); } private void OnException(object sender, ExceptionEventArgs exception) { - Console.WriteLine(exception.Exception.Message); + Console.WriteLine(exception.Exception.Message); } ``` +**Guidance Articles for .NET MAUI Android Related Queries:** +- [Blog Post on .NET MAUI Android](https://www.cnblogs.com/MASA/p/16612541.html) +- [Microsoft Documentation on .NET MAUI Android Deployment](https://learn.microsoft.com/zh-cn/dotnet/maui/android/deployment/?view=net-maui-7.0) +- [Stack Overflow: Android 8 Cleartext HTTP Traffic Not Permitted](https://stackoverflow.com/questions/45940861/android-8-cleartext-http-traffic-not-permitted) +- [Youdao Note](https://note.youdao.com/ynoteshare/mobile.html?id=5c5d5cf8fe1d67419b09024255ff239c) -4. .NET MAUI Android 相关疑问处理引导文章 - -https://www.cnblogs.com/MASA/p/16612541.html - -https://learn.microsoft.com/zh-cn/dotnet/maui/android/deployment/?view=net-maui-7.0 - -https://stackoverflow.com/questions/45940861/android-8-cleartext-http-traffic-not-permitted - -https://note.youdao.com/ynoteshare/mobile.html?id=5c5d5cf8fe1d67419b09024255ff239c - - - -5.运行效果 - -目前已运行测试机型、平台 。 - -1.在华为荣耀Px30非鸿蒙系统手机可运行。 - -2.Visual studio 2022 preview Pixe 5 - API33 (Android 13.0 - API 33) 可运行。 - +**Current Testing Devices and Platforms:** +1. Huawei Honor Px30 (non-HarmonyOS) - operational. +2. Visual Studio 2022 Preview on Pixel 5 - API 33 (Android 13.0 - API 33) - operational. ## 📍2023-01-17 -开源项目调整 +### Open Source Project Reorganization -在github和gitee的两个开源平台分别建立了General开源组织，会将具有一定代码贡献的小伙伴邀请到组织中来并分配奖励。 +We have established the "General" open source organization on both GitHub and Gitee platforms. Contributors with significant code contributions will be invited to join the organization and receive rewards. -将原有的GeneralUpdate 拆分成了三个项目，分别是： +The original GeneralUpdate project has been split into three separate projects: -- https://gitee.com/GeneralLibrary +1. **GeneralLibrary on Gitee:** + - Main organization page: [GeneralLibrary](https://gitee.com/GeneralLibrary) -- 自动升级项目 https://gitee.com/GeneralLibrary/GeneralUpdate -- 差分补丁包打包工具 https://gitee.com/GeneralLibrary/GeneralUpdate.Tools -- 使用示例 https://gitee.com/GeneralLibrary/GeneralUpdate-Samples +2. **Projects under GeneralLibrary:** + - **Automatic Update Project:** [GeneralUpdate](https://gitee.com/GeneralLibrary/GeneralUpdate) + - **Differential Patch Packaging Tool:** [GeneralUpdate.Tools](https://gitee.com/GeneralLibrary/GeneralUpdate.Tools) + - **Usage Examples:** [GeneralUpdate-Samples](https://gitee.com/GeneralLibrary/GeneralUpdate-Samples) ## 📍2022-10-09 -发布内容 - -| 组件名称 | 版本号（old） | 版本号（new） | 状态 | -| -------------------------- | ------------- | ------------- | ---- | -| GeneralUpdate.AspNetCore | 1.1.0 | 1.4.1 | 正常 | -| GeneralUpdate.ClientCore | 2.3.6 | 2.8.9 | 正常 | -| GeneralUpdate.Core | 4.10.12 | 4.11.18 | 正常 | -| GeneralUpdate.Differential | 1.0.0 | 1.3.0 | 正常 | -| GeneralUpdate.Zip | 1.0.0 | 1.3.0 | 正常 | -| GeneralUpdate.Tool | 1.0.0 | 2.1.5 | 正常 | -| GeneralUpdate.Single | 1.0.0 | - | 正常 | - - - -【1】组件GeneralUpdate.AspNetCore - -（1）重构：将之前的version和validate方法合并为Update方法，将这一个方法完成版本验证和返回更新信息功能。 - -（2）新增：为配合GeneralUpdate.PacktTool自动上传发布功能，新增了upload方法。完成版本信息入库和更新包落文件服务器。 - -GeneralUpdate.AspNetCore组件添加文件上传接口 · Issue #I55NFC · Juster.zhu/GeneralUpdate - Gitee.com - -（3）新增：该方法是为了配合客户端即使推送重要版本或服务端服务之间的更新，新增的push调用一次之后会通过Signal R推送更新信息。 - - - -【2】组件GeneralUpdate.ClientCore - -（1）修复：AutoUpdate.Core与AutoUpdate.ClientCore文件冲突问题 · Issue #I5F2YM · Juster.zhu/GeneralUpdate - Gitee.com - -（2）修复：更新组件无需更新报错 · Issue #I5F1VN · Juster.zhu/GeneralUpdate - Gitee.com - -（3）重构：更新机制需适配多个操作系统平台 · Issue #I5LYQZ · Juster.zhu/GeneralUpdate - Gitee.com - -（4）重构：重构版本验证机制 · Issue #I5LYQY · Juster.zhu/GeneralUpdate - Gitee.com - -（5）新增：配置适应MAUI - Windows machice · Issue #I4TGJC · Juster.zhu/GeneralUpdate - Gitee.com - -（6）修复：当主程序已经是最新时，是不是应该先判断，这时候就不用启动升级软件吧？ · Issue #I5O53P · Juster.zhu/GeneralUpdate - Gitee.com - -（7）重构： - -将 - -``` -public GeneralClientBootstrap Config(ClientParmeter info) -``` - -修改为： - -``` -public GeneralClientBootstrap Config(Configinfo info) -``` - -只是改变了类名称，字段内容删除validaterul和versionurl。 - -（8）新增： - -用户自定义方法，决定是否跳过本次更新的Task版本方法。 - -```c# -public GeneralClientBootstrap SetCustomOption(Func> func) -``` - -（9）新增： - -在更新配置中新增了枚举，将原来的字符串“.zip”修改为枚举Format.ZIP，防止用户输入字符串错误。 - -```c# -Option(UpdateOption.Format, Format.ZIP) -``` - - - -【3】组件GeneralUpdate.Core - -（1）重构：更新机制需适配多个操作系统平台 · Issue #I5LYQZ · Juster.zhu/GeneralUpdate - Gitee.com - -（2）重构：重构版本验证机制 · Issue #I5LYQY · Juster.zhu/GeneralUpdate - Gitee.com - -（3）修复：当主程序已经是最新时，是不是应该先判断，这时候就不用启动升级软件吧？ · Issue #I5O53P · Juster.zhu/GeneralUpdate - Gitee.com - -（4）修复：BUG: "GeneralUpdate.Core\Utils\FileUtil.cs" GetFileMD5 函数异常 · Issue #I5J0KA · Juster.zhu/GeneralUpdate - Gitee.com - -（5）修复：多级文件夹结构更新失败问题 · Issue #I59QRI · Juster.zhu/GeneralUpdate - Gitee.com - -（6）新增：在更新体系中添加客户端唯一标识 · Issue #I55NFP · Juster.zhu/GeneralUpdate - Gitee.com - -（7）下线：json配置文件更新功能，将直接覆盖。等待重构完成再次上线。影响范围如下： - -老哥，一点点建议 · Issue #I556BK · Juster.zhu/GeneralUpdate - Gitee.com - -报错 · Issue #I53XYX · Juster.zhu/GeneralUpdate - Gitee.com - -（8）调研：可行。 - -调研Mac环境下是否可以正常运行 · Issue #I4TGKK · Juster.zhu/GeneralUpdate - Gitee.com - -（9）修复：bug："GeneralUpdate\src\GeneralUpdate.Core\Download\AbstractTask.cs" 第143行 · Issue #I4WQQ0 · Juster.zhu/GeneralUpdate - Gitee.com - - - -【4】组件GeneralUpdate.Differential - -重构：递归查找需更新文件，防止一些文件没有更新检测到。添加树形结构管理更新文件目录结构。 - -修复：只能更新第一层文件bug，现在可以递归更新所有目录下的文件夹和子文件夹内的文件列表。 - -修复：打包工具打包文件包含两个名称相同但后缀不同的文件时会出错 · Issue #I5O4OD · Juster.zhu/GeneralUpdate - Gitee.com - - - -【5】组件GeneralUpdate.Zip - -（1）修复：关于文件压缩的几个问题 · Issue #I5J4Y6 · Juster.zhu/GeneralUpdate - Gitee.com - -（2）修复：word文件乱码 · Issue #I5O4S6 · Juster.zhu/GeneralUpdate - Gitee.com - -（3）修复：下载包解压在C盘下Program Files (x86)时，没有权限操作怎么处理？ · Issue #I4ZKQ4 · Juster.zhu/GeneralUpdate - Gitee.com - - - -【6】GeneralUpdate.PacketTool - -（1）修复：打包工具打包时，没有考虑有子文件夹的问题 · Issue #I5O4P8 · Juster.zhu/GeneralUpdate - Gitee.com - -（2）重构：重构文件功能体系 · Issue #I59Q5W · Juster.zhu/GeneralUpdate - Gitee.com - -（3）重构：打包工具迁移到MAUI · Issue #I5QOLG · Juster.zhu/GeneralUpdate - Gitee.com - -（4）新增：GeneralUpdate.Tool添加上传功能 · Issue #I55NF1 · Juster.zhu/GeneralUpdate - Gitee.com - -（5）修复：当只修改文件内容时，PacketTool打包功能无效 · Issue #I5BERJ · Juster.zhu/GeneralUpdate - Gitee.com - -（6）修复：文件解压后中文名显示乱码 · Issue #I502QQ · Juster.zhu/GeneralUpdate - Gitee.com - - - -【7】测试用例 、示例代码 - -示例代码： +Release Notes -src/c#/GeneralUpdate.Api/Program.cs · Juster.zhu/GeneralUpdate - Gitee.com - -src/c#/GeneralUpdate.Client/MainPage.xaml.cs · Juster.zhu/GeneralUpdate - Gitee.com - -src/c#/GeneralUpdate.Upgrad/Program.cs · Juster.zhu/GeneralUpdate - Gitee.com - -测试用例（还在完善）： - -src/c#/TestClientCore/UnitTest1.cs · Juster.zhu/GeneralUpdate - Gitee.com - -src/c#/TestDifferential/UnitTest1.cs · Juster.zhu/GeneralUpdate - Gitee.com - -src/c#/TestMD5/UnitTest1.cs · Juster.zhu/GeneralUpdate - Gitee.com - -src/c#/TestService/Program.cs · Juster.zhu/GeneralUpdate - Gitee.com - -src/c#/TestZIP/UnitTest1.cs · Juster.zhu/GeneralUpdate - Gitee.com +| Component Name | Version (old) | Version (new) | Status | +| -------------------------- | ------------- | ------------- | ------ | +| GeneralUpdate.AspNetCore | 1.1.0 | 1.4.1 | Normal | +| GeneralUpdate.ClientCore | 2.3.6 | 2.8.9 | Normal | +| GeneralUpdate.Core | 4.10.12 | 4.11.18 | Normal | +| GeneralUpdate.Differential | 1.0.0 | 1.3.0 | Normal | +| GeneralUpdate.Zip | 1.0.0 | 1.3.0 | Normal | +| GeneralUpdate.Tool | 1.0.0 | 2.1.5 | Normal | +| GeneralUpdate.Single | 1.0.0 | - | Normal | + +**[1] Component GeneralUpdate.AspNetCore** + +1. Refactor: Merged previous version and validate methods into a single Update method to perform version validation and return update information. +2. New: Added an upload method to support the automatic upload release function of GeneralUpdate.PacktTool. This method completes the storage of version information and the placement of update packages on the file server. +3. New: Added a push method to support immediate push of important versions or updates between server services to the client, using Signal R to push update information after a single call. + +**[2] Component GeneralUpdate.ClientCore** + +1. Fix: Resolved file conflict issue between AutoUpdate.Core and AutoUpdate.ClientCore. +2. Fix: Resolved error when components do not require an update. +3. Refactor: Updated mechanism to support multiple operating system platforms. +4. Refactor: Refactored version validation mechanism. +5. New: Configuration adaptation for MAUI - Windows machine. +6. Fix: When the main program is already the latest, should it first check to avoid launching the upgrade software unnecessarily? +7. Refactor: Changed the method signature for configuration from `public GeneralClientBootstrap Config(ClientParmeter info)` to `public GeneralClientBootstrap Config(Configinfo info)`, removing the fields validaterul and versionurl. +8. New: Added a user-defined method to decide whether to skip the current update using a Task version method. +9. New: Added an enumeration to the update configuration, changing the original string ".zip" to the enumeration Format.ZIP to prevent user input errors. + +**[3] Component GeneralUpdate.Core** + +1. Refactor: Updated mechanism to support multiple operating system platforms. +2. Refactor: Refactored version validation mechanism. +3. Fix: When the main program is already the latest, should it first check to avoid launching the upgrade software unnecessarily? +4. Fix: Bug in "GeneralUpdate.Core\Utils\FileUtil.cs" GetFileMD5 function. +5. Fix: Issue with multi-level folder structure updates failing. +6. New: Added a unique client identifier in the update system. +7. Offline: JSON configuration file update function will be directly overwritten. Will be back online after refactoring. Affected areas include: + - Suggestions from users. + - Error reports. +8. Research: Feasibility of running normally in a Mac environment. +9. Fix: Bug in "GeneralUpdate\src\GeneralUpdate.Core\Download\AbstractTask.cs" at line 143. + +**[4] Component GeneralUpdate.Differential** + +- Refactor: Recursively search for files to update to prevent missing update detections. Added a tree structure to manage the update file directory structure. +- Fix: Bug where only the first layer of files could be updated. Now all directories and subdirectories can be recursively updated. +- Fix: Error when the packaging tool includes two files with the same name but different extensions. + +**[5] Component GeneralUpdate.Zip** + +1. Fix: Several issues related to file compression. +2. Fix: Garbled characters in Word files. +3. Fix: Permission issues when extracting downloaded packages in C:\Program Files (x86). + +**[6] GeneralUpdate.PacketTool** + +1. Fix: Packaging tool did not consider subfolder issues during packaging. +2. Refactor: Refactored the file functionality system. +3. Refactor: Migrated packaging tool to MAUI. +4. New: Added upload functionality to GeneralUpdate.Tool. +5. Fix: PacketTool's packaging function was ineffective when only file content was modified. +6. Fix: Garbled characters in Chinese filenames after file extraction. + +**[7] Test Cases and Example Code** + +Example Code: +- src/c#/GeneralUpdate.Api/Program.cs +- src/c#/GeneralUpdate.Client/MainPage.xaml.cs +- src/c#/GeneralUpdate.Upgrad/Program.cs + +Test Cases (still in progress): +- src/c#/TestClientCore/UnitTest1.cs +- src/c#/TestDifferential/UnitTest1.cs +- src/c#/TestMD5/UnitTest1.cs +- src/c#/TestService/Program.cs +- src/c#/TestZIP/UnitTest1.cs ## 📍2022-04-03 -（1）主程序和升级程序之间是否支持相互升级？ +(1) Does the main program support mutual upgrades with the update program? -答：支持。 +Answer: Yes, it does. -（2）是否需要开发者写代码关闭进程的时机或者其他代码？ +(2) Do developers need to write code to manage the timing of process closure or any other code? -答：不需要，组件已经将整个更新流程考虑到了。所以除了组件代码以外，不需要开发者额外多写任何辅助代码。 +Answer: No, they don't. The component already considers the entire update process, so developers don't need to write any additional auxiliary code beyond the component code. -（3）更新程序是否需要和主程序放在同一个目录下？ +(3) Does the update program need to be in the same directory as the main program? -答：是的，需要。但一定要保持升级程序不能引用主程序的里的任何代码。否则会更新失败。 +Answer: Yes, it does. However, make sure that the update program does not reference any code from the main program; otherwise, the update will fail. -（4）更新完成之后会删除更新包的补丁文件吗？ +(4) Will the update package's patch files be deleted after the update is complete? -答：会的，组件更新完成之后会保证文件列表干净，不会出现冗余文件污染、磁盘空间占用的情况。 +Answer: Yes, they will. The component ensures a clean file list after the update, avoiding redundant files and unnecessary disk space usage. -（5）可以运用在服务端吗？就是服务与服务之间的升级。 +(5) Can this be used on the server side, for instance, for upgrades between services? -答：理论上支持的，作者没有实际这么使用过。据反馈有的小伙伴已经这么干了。本次分享是针对C/S架构的场景。 +Answer: Theoretically, it is supported, although the author has not used it this way personally. Feedback indicates that some users have done this. This sharing is focused on C/S architecture scenarios. -（6）怎么获取更新包的MD5码？ +(6) How can I get the MD5 checksum of the update package? -答：使用项目源码里的，AutoUpdate.MD5工程。 +Answer: Use the AutoUpdate.MD5 project from the source code. -（7）怎么制作一个更新包？ +(7) How do I create an update package? -答：使用GeneralUpdate.PacketTool工具生成即可。在源码仓库的release中可以看到打包好的安装程序。 +Answer: Use the GeneralUpdate.PacketTool to generate it. You can find the packaged installation program in the release section of the source code repository. -（8）关于组件的其他内容如何了解到？ +(8) How can I learn more about other aspects of the component? -答：可以通过官方网站、或者相关Q群、以及我gitee或github的issue中与我交流。 +Answer: You can learn more through the official website, relevant QQ groups, or by discussing with me on Gitee or GitHub issues. -（9）下载包解压在C盘下Program Files (x86)时，没有权限操作怎么处理？ +(9) How to handle lack of permissions when extracting the download package in C:\Program Files (x86)? -答：https://gitee.com/Juster-zhu/GeneralUpdate/issues/I4ZKQ4 +Answer: [Link to issue](https://gitee.com/Juster-zhu/GeneralUpdate/issues/I4ZKQ4) -（10）更新文件较小时，下载速度显示为：0B/S 。 +(10) When the update file is small, the download speed shows as 0B/S. -答：https://gitee.com/Juster-zhu/GeneralUpdate/issues/I3POMG +Answer: [Link to issue](https://gitee.com/Juster-zhu/GeneralUpdate/issues/I3POMG) @@ -743,36 +608,32 @@ src/c#/TestZIP/UnitTest1.cs · Juster.zhu/GeneralUpdate - Gitee.com ## 📍2022-03-23 -说明 - -- 在线帮助文档：http://justerzhu.cn/ （后续将会按组件拆分成对应的文档） -- Nuget版本管理参考标准：https://docs.microsoft.com/zh-cn/nuget/concepts/package-versioning -- 应用程序集版本管理参考标准：https://docs.microsoft.com/zh-cn/dotnet/standard/assembly/versioning （被组件更新的客户端程序，说通俗点就是你公司的产品；组件的操作将按照这个标准执行。） -- 本次版本发布会有很多改变，不是平滑升级（追求稳定或不想改动慎用）。本项目正在逐渐稳定后续将会平滑升级避免开发者再度修改。 -- 如果发生“乌龙事件” 例如：发布更新包内容自身错误或更新过程中发生意外，不可回滚。目前解决方案（1）重新请求更新，（2）通过推送机制发送紧急修复版本更新包；来解决此类问题。 -- 关于“不可回滚”这个问题，如果有更好的办法希望各位可以直接在issues中提出您的看法；目前社区中有两种声音（1）出现意外情况希望组件可以将本地程序回滚至原来的版本，保证哪怕更新失败也要用户可用。（2）更新组件的意义就是将组件推向新的版本让本次的版本发布有效，如果更新失败那么让它更新成功为止；只许前进不许退 +Instructions +- Online Help Documentation: [http://justerzhu.cn/](http://justerzhu.cn/) (Will be divided into separate documents by component in the future) +- NuGet Versioning Standards Reference: [NuGet Package Versioning](https://docs.microsoft.com/en-us/nuget/concepts/package-versioning) +- Application Assembly Versioning Standards Reference: [Assembly Versioning](https://docs.microsoft.com/en-us/dotnet/standard/assembly/versioning) (The client program updated by the component is essentially your company's product; the component's operations will follow this standard.) +- This release includes many changes and is not a smooth upgrade (use with caution if stability is crucial or if modifications are undesirable). The project is gradually stabilizing, and future updates will aim for smooth upgrades to avoid requiring further developer modifications. +- In case of a "blunder" such as incorrect update package content or unforeseen events during the update, rollback is not currently supported. The current solutions are (1) request the update again, or (2) send an emergency fix update package via the push mechanism. +- Regarding the "non-rollback" issue, if you have better solutions, please share your thoughts in the issues section. Currently, there are two opinions in the community: (1) In case of unexpected events, the component should roll back the local program to the previous version to ensure usability even if the update fails. (2) The purpose of the update component is to push the component to a new version, making the release effective. If the update fails, it should continue until it succeeds; only forward, no retreat. +Release Content -发布内容 +Let's first look at the version numbers and the changes made in this major release (8 sections in total). -这里先看看发布的版本号以及这次大版本的更新发生了哪些改动（共8个部分）。 +| Component Name | Version (old) | Version (new) | Status | +| -------------------------- | ------------- | ------------- | ------- | +| GeneralUpdate.AspNetCore | 1.0.0 | 1.1.0 | Normal | +| GeneralUpdate.ClientCore | 1.1.2 | 2.3.6 | Normal | +| GeneralUpdate.Core | 3.6.10 | 4.10.12 | Normal | +| GeneralUpdate.Differential | - | 1.0.0 | Normal | +| GeneralUpdate.Common | 1.0.0 | - | Removed | -| 组件名称 | 版本号（old） | 版本号（new） | 状态 | -| -------------------------- | ------------- | ------------- | ---- | -| GeneralUpdate.AspNetCore | 1.0.0 | 1.1.0 | 正常 | -| GeneralUpdate.ClientCore | 1.1.2 | 2.3.6 | 正常 | -| GeneralUpdate.Core | 3.6.10 | 4.10.12 | 正常 | -| GeneralUpdate.Differential | - | 1.0.0 | 正常 | -| GeneralUpdate.Common | 1.0.0 | - | 移除 | +**[1] Component GeneralUpdate.AspNetCore** +1. [NEW] Added latest version push functionality with the VersionHub object. This primarily addresses the need to push urgent bug fix versions temporarily. - -【1】组件GeneralUpdate.AspNetCore - -（1）[NEW] 添加了最新版本推送功能，VersionHub对象。主要解决临时需要推送紧急修复重大bug的版本。 - -```c# +```csharp var builder = WebApplication.CreateBuilder(args); builder.Services.AddSingleton(); builder.Services.AddSignalR(); @@ -796,59 +657,44 @@ async Task CommonHubContextMethod(IHubContext context) } ``` +**[2] Component GeneralUpdate.ClientCore** +1. [NEW] Overloaded configuration method in GeneralClientBootstrap, simplifying it to require only the remote server address, such as http://127.0.0.1, and the update program name, reducing developer concern over parameters as they are automatically obtained within the component. -【2】组件GeneralUpdate.ClientCore - -（1）[NEW] 在GeneralClientBootstrap中重载了配置方式，该方法简化为只需要传递远程服务器地址例如http://127.0.0.1 和更新程序名称即可，简化了开发者需要关心的参数组件内自动获取。 - -```c# +```csharp public GeneralClientBootstrap Config(string url, string appName = "AutoUpdate.Core"); ``` -（2）[NEW] 添加了最新版本接收推送功能，VersionHub对象。主要解决临时需要接收紧急修复重大bug的版本，可以在GetMessage回调函数中可添加更新操作。 +2. [NEW] Added latest version reception push functionality with the VersionHub object. This primarily addresses the need to receive urgent bug fix versions temporarily, allowing update operations in the GetMessage callback function. -```c# +```csharp VersionHub.Instance.Subscribe($"{ baseUrl }/{ hubName }", "TESTNAME", new Action(GetMessage)); ``` +**[3] Component GeneralUpdate.Core** +1. [FIX] Fixed issue where a download interruption due to network disconnection did not throw an exception after the timeout period. +2. [REFACTOR] Refactored multi-task download design. +3. [FIX] Fixed issue where FileUtil.Update32Or64Libs would throw exceptions under certain conditions. +4. [REFACTOR] Refactored default update strategy design. +5. [NEW] Added latest version reception push functionality with the VersionHub object. This primarily addresses the need to receive urgent bug fix versions temporarily, allowing update operations in the GetMessage callback function. -【3】组件GeneralUpdate.Core - -（1）[FIX] 修复下载中途断网，到达超时时间没有异常上抛问题。 - -（2）[REFACTOR] 重构多任务下载设计。 - -（3）[FIX] 修复FileUtil.Update32Or64Libs在某些情况下会抛出异常。 - -（4）[REFACTOR] 重构默认更新策略设计。 - -（5）[NEW] 添加了最新版本接收推送功能，VersionHub对象。主要解决临时需要接收紧急修复重大bug的版本。开发者可以在GetMessage回调函数中可添加更新操作。 - -```c# +```csharp VersionHub.Instance.Subscribe($"{ baseUrl }/{ hubName }", "TESTNAME", new Action(GetMessage)); ``` -（6）[NEW] 支持7z压缩包的解压功能。 - -（7）[REMOVE] 移除了GeneralUpdate.Core与GeneralUpdate.ClientCore 中重复代码，通用代码通过链接文件解决冗余问题。 - -（8）[NEW] 支持增量更新功能，例如：只更新了一个文件，那么就只将该文件打包。 - -（9）[NEW] 支持二进制差分功能，例如：temp.dll 发生了修改产生了新版本的文件，那么将会把temp.dll的新版本文件和老版本文件做一个差分。最后生成一个.patch的补丁文件，按照正常项目迭代那么这个.patch的补丁将会是kb级的。再配合7z的高压缩将更新包的大小做到目前状态下的极致节省流量和带宽占用。特别需要说明的是，如果在新版本中添加了新文件还是会将新增文件原封不动的打包到更新包中。 - +6. [NEW] Added support for extracting 7z compressed files. +7. [REMOVE] Removed duplicate code between GeneralUpdate.Core and GeneralUpdate.ClientCore, addressing redundancy through linked files. +8. [NEW] Added support for incremental updates. For example, if only one file is updated, only that file will be packaged. +9. [NEW] Added support for binary differential functionality. For example, if a file like temp.dll is modified to create a new version, a .patch file will be created from the differences between the new and old versions. With normal project iteration, this .patch file will typically be only a few kilobytes. Combined with 7z's high compression, the update package size is minimized to save bandwidth and data usage. It should be noted that if new files are added in the new version, they will be included in the update package as they are. +**[4] Component [NEW] GeneralUpdate.Differential** -【4】组件[NEW]GeneralUpdate.Differential +Added the Differential component in GeneralUpdate, which mainly provides the following functionalities: -在GeneralUpdate中新增组件Differential，该组件主要提供以下功能： - -（1）[NEW] 新增二进制差分更新,生成.patch补丁文件。 - -（2）[NEW] 新增增量更新，例如：version 1.1.1.1原有10个文件这次版本发布修改了其中3个文件那么只会将修改的文件进行打包。 - -（3）[NEW] 更新配置文件（目前只支持.json配置文件且内容深度为1级），例如：客户端程序使用.json格式文件作为配置文件，那么将会保留客户端原有配置内容的前提下更新配置文件内容。假设客户端原有配置文件（.json）中包含内容： +1. [NEW] Added binary differential updates, generating .patch files. +2. [NEW] Added incremental updates. For example, if version 1.1.1.1 originally had 10 files and this release modified 3 of them, only the modified files will be packaged. +3. [NEW] Updated configuration files (currently only supports .json configuration files with a depth of 1 level). For example, if the client program uses a .json file as a configuration file, the original configuration content will be preserved while updating the configuration file. Assuming the client's original configuration file (.json) contains: ```json { @@ -857,7 +703,7 @@ VersionHub.Instance.Subscribe($"{ baseUrl }/{ hubName }", "TESTNAME", ne } ``` -服务端新的配置文件结构为： +The server's new configuration file structure is: ```json { @@ -867,7 +713,7 @@ VersionHub.Instance.Subscribe($"{ baseUrl }/{ hubName }", "TESTNAME", ne } ``` -那么将会把，“path”字段更新到客户端本地配置文件中并保留原有内容为： +The "path" field will be updated into the client's local configuration file, preserving the original content as: ```json { @@ -877,31 +723,22 @@ VersionHub.Instance.Subscribe($"{ baseUrl }/{ hubName }", "TESTNAME", ne } ``` +**[5] Component GeneralUpdate.Zip** +1. [REFACTOR] Refactored compression component design to support .zip and .7z archive formats. +2. [NEW] Added 7z extraction functionality. -【5】组件GeneralUpdate.Zip - -（1）[REFACTOR] 重构压缩组件设计，将支持.zip和.7z压缩包格式。 - -（2）[NEW] 添加7z解压功能。 - - - -【6】组件[REMOVE]GeneralUpdate.Common - -（1）移除该组件，解除GeneralUpdate.Core与GeneralUpdate.ClientCore 耦合，发现目前版本并不需要。 +**[6] Component [REMOVE] GeneralUpdate.Common** +1. Removed this component, decoupling GeneralUpdate.Core and GeneralUpdate.ClientCore as it was deemed unnecessary for the current version. +**[7] Component GeneralUpdate.Single** -【7】组件GeneralUpdate.Single +No functional updates in this release. -本次未更新实际功能。 +**[8] Test Cases Example** - - -【8】测试用例 Example - -为简化开发者在验证、测试过程中编写用例开发工作。在GeneralUpdate解决方案中添加了以下测试用例： +To simplify developers' work in writing test cases during validation and testing, the following test cases have been added to the GeneralUpdate solution: - AutoUpdate.ClientCore - AutoUpdate.Core @@ -913,44 +750,40 @@ VersionHub.Instance.Subscribe($"{ baseUrl }/{ hubName }", "TESTNAME", ne - - ## 📍2022-02-16 -目前框架支持 - -理论支撑：https://docs.microsoft.com/zh-cn/dotnet/standard/net-standard - -| 框架名称 | 是否支持 | -| ------------------------------------- | ---------------- | -| .NET Core 2.0 | 支持 | -| .NET 5 6 7 | 支持 | -| .NET Framework 4.6.1 | 支持 | -| Mono 5.4 | 理论支持，未验证 | -| Xamarin.iOS | 理论支持，未验证 | -| Xamarin.Mac | 理论支持，未验证 | -| Xamarin.Android | 理论支持，未验证 | -| Universal Windows Platform 10.0.16299 | 理论支持，未验证 | -| Unity 2018.1 | 理论支持，未验证 | - -| UI框架名称 | 是否支持 | -| ----------------- | ------------------ | -| WPF | 支持 | -| UWP | 未验证，等待反馈 | -| MAUI | 暂不支持，正在兼容 | -| Avalonia | 未验证，等待反馈 | -| WinUI | 未验证，等待反馈 | -| Console（控制台） | 支持 | - -| 操作系统名称 | 是否支持 | -| ------------ | -------- | -| Windows | 支持 | -| Linux | 未验证 | -| Mac | 未验证 | -| iOS | 暂不支持 | -| Android | 暂不支持 | - - +Current Framework Support + +Theoretical Support: [Microsoft .NET Standard Documentation](https://docs.microsoft.com/en-us/dotnet/standard/net-standard) + +| Framework Name | Support Status | +| ------------------------------------- | ----------------------------------- | +| .NET Core 2.0 | Supported | +| .NET 5, 6, 7 | Supported | +| .NET Framework 4.6.1 | Supported | +| Mono 5.4 | Theoretically supported, unverified | +| Xamarin.iOS | Theoretically supported, unverified | +| Xamarin.Mac | Theoretically supported, unverified | +| Xamarin.Android | Theoretically supported, unverified | +| Universal Windows Platform 10.0.16299 | Theoretically supported, unverified | +| Unity 2018.1 | Theoretically supported, unverified | + +| UI Framework Name | Support Status | +| ----------------- | -------------------------------------------- | +| WPF | Supported | +| UWP | Unverified, awaiting feedback | +| MAUI | Not supported, in progress for compatibility | +| Avalonia | Unverified, awaiting feedback | +| WinUI | Unverified, awaiting feedback | +| Console | Supported | + +| Operating System Name | Support Status | +| --------------------- | -------------- | +| Windows | Supported | +| Linux | Unverified | +| Mac | Unverified | +| iOS | Not supported | +| Android | Not supported | @@ -958,201 +791,196 @@ VersionHub.Instance.Subscribe($"{ baseUrl }/{ hubName }", "TESTNAME", ne Notice -- 预计会使用Blazor开发GeneralUpdate官网，介绍组件结构、更新流程、快速启动、参数等内容。 - -![图片](imgs/udpate_flow.jpg) - - 1.主程序启动时检测升级程序是否需要更新 - 2.需要更新则把升级程序版本号上传并逐版本更新 - 3.升级程序更完成后或不需要更新，则进行判断主程序 - 是否需要更新如果需要更新则启动升级程序 - 4.请求主程序更新版本 - 5.请求到主版本多个更新包并逐版本更新 - 6.更新完成后关闭升级程序启动主程序 +- The GeneralUpdate website is expected to be developed using Blazor. It will introduce component structure, update processes, quick start guides, parameters, and more. -![图片](imgs/supporting_relationships.jpg) +![Image](imgs/udpate_flow.jpg) -- 以上更新、下载过程均支持断点续传和逐版本更新。 -- 逐版本下载功能是根据版本发布时间进行排序的发布时间越早的版本越先更新（具体信息见源码中的sql脚本字段内容）。 -- 逐版本下载的更新包最大测试过1G更新内容。 + 1. When the main program starts, it checks if the updater needs to be updated. + 2. If an update is needed, it uploads the version number of the updater and updates it incrementally. + 3. Once the updater is updated or if no update is needed, it checks if the main program needs an update. If so, the updater is launched. + 4. Requests the main program update version. + 5. Receives multiple update packages for the main version and updates incrementally. + 6. After updating, the updater is closed, and the main program is started. +![Image](imgs/supporting_relationships.jpg) +- The above update and download processes support resuming from breakpoints and incremental updates. +- Incremental download functionality is sorted by the release date of versions, with earlier versions being updated first (see the SQL script field content in the source code for details). +- The maximum tested update content for incremental downloads is 1GB. -2.Nuget +2. Nuget -- (New)https://www.nuget.org/packages/GeneralUpdate.Common/ -- (New)https://www.nuget.org/packages/GeneralUpdate.ClientCore/ -- (New)https://www.nuget.org/packages/GeneralUpdate.AspNetCore/ +- (New) https://www.nuget.org/packages/GeneralUpdate.Common/ +- (New) https://www.nuget.org/packages/GeneralUpdate.ClientCore/ +- (New) https://www.nuget.org/packages/GeneralUpdate.AspNetCore/ - https://www.nuget.org/packages/GeneralUpdate.Zip/ - https://www.nuget.org/packages/GeneralUpdate.Single/ -- (Update)https://www.nuget.org/packages/GeneralUpdate.Core/ +- (Update) https://www.nuget.org/packages/GeneralUpdate.Core/ -3.Issues & Git 、Gitee +3. Issues & Git, Gitee -欢迎在以下地址提出issues提出时尽可能的描述清楚异常发生的原因或缺陷详情，check周期为每周的周五。 +Feel free to raise issues at the following addresses. Please describe the cause of the anomaly or defect details as clearly as possible. The checking cycle is every Friday. - https://gitee.com/Juster-zhu/GeneralUpdate - https://github.com/WELL-E/AutoUpdater/tree/autoupdate2 - https://github.com/WELL-E/AutoUpdater/issues - https://gitee.com/Juster-zhu/GeneralUpdate/issues -4.New - -- GeneralUpdate.Core添加逐版本更新功能 -- GeneralUpdate.Core新增事件ExceptionEvent、MutiDownloadStatisticsEvent、MutiDownloadErrorEvent、MutiDownloadCompletedEvent、MutiDownloadProgressEvent、MutiAllDownloadCompletedEvent。 -- GeneralUpdate.Core新增RemoteAddressBase64方法。 -- 新增ClientParameter类，用于组件之间进程通讯传递参数。 -- 新增组件GeneralUpdate.AspNetCore,具有根据升级类型返回更新版本信息的功能并支持管道依赖注入使用，但需要自己编写查库的方法。 -- 新增组件GeneralUpdate.ClientCore, - - (1)具有更新升级组件版本功能（更新程序更新自己） - - (2)支持升级组件的逐版本更新(多更新包同时下载) - - (3)便捷启动升级程序，摆脱之前的繁琐进程启动和传参。 -- 新增组件GeneralUpdate.Common 该库整合了组件内使用的所有公共类和辅助方法（该组件为必须组件，该组件更新频率非常低不推荐打包在更新包中）。 -- 新增mysql脚本，用于创建GeneralUpdate.AspNetCore服务端使用的update_version表。 - -5.Remove - -- 移除GeneralUpdate.Core中所有的通知事件替换为MutixxxxEvent. -- 移除GeneralUpdate.Core中GeneralUpdateBootstrap启动中通过进程传递参数的方法RemoteAddress方法。 -- 移除更新失败版本回滚功能，该功能导致在C盘回滚更新时因权限不够发生致命异常问题，该功能考虑后续开放。 - -6.Fix - -- 修复https ssl访问失败问题。 -- 修复其他.net框架版本注册事件begininvoke通知异常问题。 -- 修改多处类名单词拼写错误问题。 -- 对若干Model类删除了不必要字段。 - -7.Quick Start - -**（1） Example GeneralUpdate.ClientCore** - -``` - //Clinet version. - var mainVersion = "1.1.1"; - var mianType = 1; - - //Updater version - clientParameter = new ClientParameter(); - clientParameter.ClientVersion = "1.1.1"; - clientParameter.ClientType = 2; - clientParameter.AppName = "AutoUpdate.ConsoleApp"; - clientParameter.MainAppName = "AutoUpdate.Test"; - clientParameter.InstallPath = @"D:\update_test"; - clientParameter.UpdateLogUrl = "https://www.baidu.com/"; - clientParameter.ValidateUrl = $"https://127.0.0.1:5001/api/update/getUpdateValidate/{ clientParameter.ClientType }/{ clientParameter.ClientVersion }"; - clientParameter.UpdateUrl = $"https://127.0.0.1:5001/api/update/getUpdateVersions/{ clientParameter.ClientType }/{ clientParameter.ClientVersion }"; - clientParameter.MainValidateUrl = $"https://127.0.0.1:5001/api/update/getUpdateValidate/{ mianType }/{ mainVersion }"; - clientParameter.MainUpdateUrl = $"https://127.0.0.1:5001/api/update/getUpdateVersions/{ mianType }/{ mainVersion }"; - - generalClientBootstrap = new GeneralClientBootstrap(); - generalClientBootstrap.MutiDownloadProgressChanged += OnMutiDownloadProgressChanged; - generalClientBootstrap.MutiDownloadStatistics += OnMutiDownloadStatistics; - generalClientBootstrap.MutiDownloadCompleted += OnMutiDownloadCompleted; - generalClientBootstrap.MutiAllDownloadCompleted += OnMutiAllDownloadCompleted; - generalClientBootstrap.MutiDownloadError += OnMutiDownloadError; - generalClientBootstrap.Exception += OnException; - generalClientBootstrap.Config(clientParameter). - Strategy(); - await generalClientBootstrap.LaunchTaskAsync(); +4. New + +- GeneralUpdate.Core adds incremental update functionality. +- GeneralUpdate.Core introduces new events: ExceptionEvent, MutiDownloadStatisticsEvent, MutiDownloadErrorEvent, MutiDownloadCompletedEvent, MutiDownloadProgressEvent, MutiAllDownloadCompletedEvent. +- GeneralUpdate.Core adds the RemoteAddressBase64 method. +- A new ClientParameter class is added for inter-process communication to pass parameters between components. +- A new component, GeneralUpdate.AspNetCore, is added, which provides update version information based on update type and supports pipeline dependency injection. However, you need to write your own methods for database queries. +- A new component, GeneralUpdate.ClientCore, is added: + - (1) It can update the version of the update component itself. + - (2) It supports incremental updates for update components (multiple update packages can be downloaded simultaneously). + - (3) It simplifies the launch of the updater, eliminating the previous cumbersome process of starting and passing parameters. +- A new component, GeneralUpdate.Common, is added. This library integrates all common classes and helper methods used within the components (this component is mandatory, and its update frequency is very low, so it's not recommended to package it in update packages). +- A new MySQL script is added to create the update_version table for the GeneralUpdate.AspNetCore server. + +5. Remove + +- All notification events in GeneralUpdate.Core are replaced with MutiXXXXEvent. +- The method RemoteAddress in GeneralUpdateBootstrap for passing parameters through processes is removed from GeneralUpdate.Core. +- The feature for rolling back failed updates is removed, as it caused fatal exceptions due to insufficient permissions when rolling back updates on the C drive. This feature may be reopened in the future. + +6. Fix + +- Fixed the issue with HTTPS SSL access failures. +- Fixed notification exceptions related to event registration with begininvoke in other .NET framework versions. +- Corrected multiple class name spelling errors. +- Removed unnecessary fields from several Model classes. + +7. Quick Start + +**(1) Example GeneralUpdate.ClientCore** + +```csharp +// Client version. +var mainVersion = "1.1.1"; +var mianType = 1; + +// Updater version +clientParameter = new ClientParameter(); +clientParameter.ClientVersion = "1.1.1"; +clientParameter.ClientType = 2; +clientParameter.AppName = "AutoUpdate.ConsoleApp"; +clientParameter.MainAppName = "AutoUpdate.Test"; +clientParameter.InstallPath = @"D:\update_test"; +clientParameter.UpdateLogUrl = "https://www.baidu.com/"; +clientParameter.ValidateUrl = $"https://127.0.0.1:5001/api/update/getUpdateValidate/{ clientParameter.ClientType }/{ clientParameter.ClientVersion }"; +clientParameter.UpdateUrl = $"https://127.0.0.1:5001/api/update/getUpdateVersions/{ clientParameter.ClientType }/{ clientParameter.ClientVersion }"; +clientParameter.MainValidateUrl = $"https://127.0.0.1:5001/api/update/getUpdateValidate/{ mianType }/{ mainVersion }"; +clientParameter.MainUpdateUrl = $"https://127.0.0.1:5001/api/update/getUpdateVersions/{ mianType }/{ mainVersion }"; + +generalClientBootstrap = new GeneralClientBootstrap(); +generalClientBootstrap.MutiDownloadProgressChanged += OnMutiDownloadProgressChanged; +generalClientBootstrap.MutiDownloadStatistics += OnMutiDownloadStatistics; +generalClientBootstrap.MutiDownloadCompleted += OnMutiDownloadCompleted; +generalClientBootstrap.MutiAllDownloadCompleted += OnMutiAllDownloadCompleted; +generalClientBootstrap.MutiDownloadError += OnMutiDownloadError; +generalClientBootstrap.Exception += OnException; +generalClientBootstrap.Config(clientParameter). + Strategy(); +await generalClientBootstrap.LaunchTaskAsync(); ``` -**（2） Example GeneralUpdate.Core** +**(2) Example GeneralUpdate.Core** -``` - static void Main(string[] args) - { - var resultBase64 = args[0]; - var bootstrap = new GeneralUpdateBootstrap(); - bootstrap.Exception += OnException; - bootstrap.MutiDownloadError += OnMutiDownloadError; - bootstrap.MutiDownloadCompleted += OnMutiDownloadCompleted; - bootstrap.MutiDownloadStatistics += OnMutiDownloadStatistics; - bootstrap.MutiDownloadProgressChanged += OnMutiDownloadProgressChanged; - bootstrap.MutiAllDownloadCompleted += OnMutiAllDownloadCompleted; - bootstrap.Strategy(). - Option(UpdateOption.DownloadTimeOut, 60). - RemoteAddressBase64(resultBase64). - LaunchAsync(); - } +```csharp +static void Main(string[] args) +{ + var resultBase64 = args[0]; + var bootstrap = new GeneralUpdateBootstrap(); + bootstrap.Exception += OnException; + bootstrap.MutiDownloadError += OnMutiDownloadError; + bootstrap.MutiDownloadCompleted += OnMutiDownloadCompleted; + bootstrap.MutiDownloadStatistics += OnMutiDownloadStatistics; + bootstrap.MutiDownloadProgressChanged += OnMutiDownloadProgressChanged; + bootstrap.MutiAllDownloadCompleted += OnMutiAllDownloadCompleted; + bootstrap.Strategy(). + Option(UpdateOption.DownloadTimeOut, 60). + RemoteAddressBase64(resultBase64). + LaunchAsync(); +} ``` -**（3） Example GeneralUpdate.AspNetCore** +**(3) Example GeneralUpdate.AspNetCore** -```c# - Startup.cs - public void ConfigureServices(IServiceCollection services) - { - services.AddControllers(); - services.AddSingleton(); - } +```csharp +Startup.cs +public void ConfigureServices(IServiceCollection services) +{ + services.AddControllers(); + services.AddSingleton(); +} - UpdateController.cs +UpdateController.cs - private readonly ILogger _logger; - private readonly IUpdateService _updateService; +private readonly ILogger _logger; +private readonly IUpdateService _updateService; - public UpdateController(ILogger logger, IUpdateService updateService) - { - _logger = logger; - _updateService = updateService; - } +public UpdateController(ILogger logger, IUpdateService updateService) +{ + _logger = logger; + _updateService = updateService; +} - /// - /// https://localhost:5001/api/update/getUpdateVersions/1/1.1.1 - /// - /// 1:ClientApp 2:UpdateApp - /// - /// - [HttpGet("getUpdateVersions/{clientType}/{clientVersion}")] - public async Task GetUpdateVersions(int clientType, string clientVersion) - { - _logger.LogInformation("Client request 'GetUpdateVersions'."); - var resultJson = await _updateService.UpdateVersionsTaskAsync(clientType, clientVersion, UpdateVersions); - return Ok(resultJson); - } +/// +/// https://localhost:5001/api/update/getUpdateVersions/1/1.1.1 +/// +/// 1:ClientApp 2:UpdateApp +/// +/// +[HttpGet("getUpdateVersions/{clientType}/{clientVersion}")] +public async Task GetUpdateVersions(int clientType, string clientVersion) +{ + _logger.LogInformation("Client request 'GetUpdateVersions'."); + var resultJson = await _updateService.UpdateVersionsTaskAsync(clientType, clientVersion, UpdateVersions); + return Ok(resultJson); +} - /// - /// https://localhost:5001/api/update/getUpdateValidate/1/1.1.1 - /// - /// 1:ClientApp 2:UpdateApp - /// - /// - [HttpGet("getUpdateValidate/{clientType}/{clientVersion}")] - public async Task GetUpdateValidate(int clientType, string clientVersion) - { - _logger.LogInformation("Client request 'GetUpdateValidate'."); - var lastVersion = GetLastVersion(); - var resultJson = await _updateService.UpdateValidateTaskAsync(clientType, clientVersion, lastVersion, true, GetValidateInfos); - return Ok(resultJson); - } +/// +/// https://localhost:5001/api/update/getUpdateValidate/1/1.1.1 +/// +/// 1:ClientApp 2:UpdateApp +/// +/// +[HttpGet("getUpdateValidate/{clientType}/{clientVersion}")] +public async Task GetUpdateValidate(int clientType, string clientVersion) +{ + _logger.LogInformation("Client request 'GetUpdateValidate'."); + var lastVersion = GetLastVersion(); + var resultJson = await _updateService.UpdateValidateTaskAsync(clientType, clientVersion, lastVersion, true, GetValidateInfos); + return Ok(resultJson); +} ``` ## 📍2021-03-18 -声明 +Statement -1. 本组件将支持以下框架开发的应用程序。.NET Framework 4.6.1 | .NET Core 2.0 | .NET 5 -2. GeneralUpdate.Single组件目前仅支持wpf和.NET Framework框架。 +1. This component will support applications developed with the following frameworks: .NET Framework 4.6.1, .NET Core 2.0, and .NET 5. +2. The GeneralUpdate.Single component currently only supports WPF and the .NET Framework. -新增 +Additions -1. GeneralUpdate.Core-3.2.1版本，新增更新失败回滚功能。 -2. 新增了组件 GeneralUpdate.Zip-1.0.0，它将为程序带来压缩文件和解压压缩包的功能且能独立使用。 +1. GeneralUpdate.Core version 3.2.1 introduces a new feature for rollback on update failure. +2. A new component, GeneralUpdate.Zip version 1.0.0, has been added, providing functionality for compressing and decompressing files, and it can be used independently. -修复、修改 +Fixes and Modifications -1. 修复事件多线程操作时，不通知问题。 -2. 组件的框架版本从.NET Framework4.5.2修改为.net standard 2.0。（支持框架参考：https://docs.microsoft.com/zh-cn/dotnet/standard/net-standard） - -移除 - -1. 移除7zip第三方组件的依赖 -2. 移除RegistryUtil工具类 +1. Fixed the issue where events were not being notified during multithreaded operations. +2. The component framework version has been changed from .NET Framework 4.5.2 to .NET Standard 2.0. (Supported frameworks reference: https://docs.microsoft.com/en-us/dotnet/standard/net-standard) +Removals +1. Removed the dependency on the third-party component 7zip. +2. Removed the RegistryUtil utility class. GeneralUpdate Quick start @@ -1181,26 +1009,24 @@ GeneralUpdate Quick start ## 📍2020-08-30 -新增内容 - -1. 在新的发布中，GeneralUpdate.Core-2.1.0版本新增断点续传功能。 -2. 在新的发布中，新增了组件 GeneralUpdate.Single-1.0.0，它将为程序带来单例运行功能，防止自动更新程序开启多个。 +New Additions -更新流程 +1. In the new release, GeneralUpdate.Core version 2.1.0 adds support for resuming downloads. +2. In the new release, a new component, GeneralUpdate.Single version 1.0.0, has been added. It provides singleton functionality to prevent multiple instances of the auto-update program from starting. -1.客户端程序启动，向服务器获取更新信息解析并比对是否需要更新。 +Update Process -2.解析进程传参。例如：本机版本号、最新版本号、下载地址、解压路径、安装路径等。 +1. The client program starts and retrieves update information from the server, then parses and compares it to determine if an update is needed. -3.客户端程序启动更新程序（GeneralUpdate），关闭自身（客户端把自己关掉）。 +2. Parses process parameters, such as local version number, latest version number, download URL, extraction path, installation path, etc. -4.自动更新程序（GeneralUpdate）根据传递的更新信息进行， （1）下载、（2）MD5校验、（3）解压、（4）删除更新文件、（5）替换更新文件、（6）关闭更新程序自身、（7）启动客户端。 +3. The client program launches the updater (GeneralUpdate) and closes itself. -5.完成更新 +4. The auto-update program (GeneralUpdate) performs the following based on the passed update information: (1) download, (2) MD5 checksum, (3) extraction, (4) delete update files, (5) replace update files, (6) close the update program itself, (7) start the client program. +5. Update is completed. - -进程之间相互调用 +Inter-process Communication ``` using System; @@ -1264,89 +1090,84 @@ namespace MyProcessSample } ``` - - -GeneralUpdate.Core-2.1.0使用方式 - -```c# - #region Launch1 - args = new string[6] { - "0.0.0.0", - "1.1.1.1", - "https://github.com/WELL-E", - "http://192.168.50.225:7000/update.zip", - @"E:\PlatformPath", - "509f0ede227de4a662763a4abe3d8470", - }; - - GeneralUpdateBootstrap bootstrap = new GeneralUpdateBootstrap();//自动更新引导类 - bootstrap.DownloadStatistics += OnDownloadStatistics;//下载进度通知事件 - bootstrap.ProgressChanged += OnProgressChanged;//更新进度通知事件 - bootstrap.Strategy().//注册策略，可自定义更新流程 - Option(UpdateOption.Format, "zip").//指定更新包的格式，目前只支持zip - Option(UpdateOption.MainApp, "your application name").//指定更新完成后需要启动的主程序名称不需要加.exe直接写名称即可 - Option(UpdateOption.DownloadTimeOut,60).//下载超时时间（单位：秒）,如果不指定则默认超时时间为30秒。 - RemoteAddress(args).//这里的参数保留了之前的参数数组集合 - Launch();//启动更新 - - #endregion - - #region Launch2 - - /* - * Launch2 - * 新增了第二种启动方式 - * 流程： - * 1.指定更新地址，https://api.com/GeneralUpdate?version=1.0.0.1 在webapi中传入客户端当前版本号 - * 2.如果需要更新api返回给你所有的更新信息（详情内容参考 /Models/UpdateInfo.cs） - * 3.拿到更新信息之后则开始http请求更新包 - * 4.下载 - * 5.解压 - * 6.更新本地文件 - * 7.关闭更新程序 - * 8.启动配置好主程序 - * 更新程序必须跟主程序放在同级目录下 - */ - - //GeneralUpdateBootstrap bootstrap2 = new GeneralUpdateBootstrap(); - //bootstrap2.DownloadStatistics += OnDownloadStatistics; - //bootstrap2.ProgressChanged += OnProgressChanged; - //bootstrap2.Strategy(). - // Option(UpdateOption.Format, "zip"). - // Option(UpdateOption.MainApp, ""). - // Option(UpdateOption.DownloadTimeOut,60).//下载超时时间（单位：秒）,如果不指定则默认超时时间为30秒。 - // RemoteAddress(@"https://api.com/GeneralUpdate?version=1.0.0.1").//指定更新地址 - // Launch(); - - #endregion - - private static void OnProgressChanged(object sender, ProgressChangedEventArgs e) +Using GeneralUpdate.Core-2.1.0 + +```csharp +#region Launch1 +args = new string[6] { + "0.0.0.0", + "1.1.1.1", + "https://github.com/WELL-E", + "http://192.168.50.225:7000/update.zip", + @"E:\PlatformPath", + "509f0ede227de4a662763a4abe3d8470", +}; + +GeneralUpdateBootstrap bootstrap = new GeneralUpdateBootstrap(); // Auto-update bootstrap class +bootstrap.DownloadStatistics += OnDownloadStatistics; // Download progress notification event +bootstrap.ProgressChanged += OnProgressChanged; // Update progress notification event +bootstrap.Strategy() // Register strategy, can customize update process + .Option(UpdateOption.Format, "zip") // Specify the format of the update package, currently only zip is supported + .Option(UpdateOption.MainApp, "your application name") // Specify the main program name to start after the update, no need to add .exe, just the name + .Option(UpdateOption.DownloadTimeOut, 60) // Download timeout (seconds), default is 30 seconds if not specified + .RemoteAddress(args) // Use the previous parameter array + .Launch(); // Start the update +#endregion + +#region Launch2 + +/* + * Launch2 + * Added a second launch method + * Process: + * 1. Specify the update address, e.g., https://api.com/GeneralUpdate?version=1.0.0.1, passing the current client version in the web API + * 2. If an update is needed, the API returns all update information (details in /Models/UpdateInfo.cs) + * 3. After obtaining the update information, start the HTTP request for the update package + * 4. Download + * 5. Extract + * 6. Update local files + * 7. Close the update program + * 8. Start the configured main program + * The update program must be placed in the same directory as the main program + */ + +//GeneralUpdateBootstrap bootstrap2 = new GeneralUpdateBootstrap(); +//bootstrap2.DownloadStatistics += OnDownloadStatistics; +//bootstrap2.ProgressChanged += OnProgressChanged; +//bootstrap2.Strategy() +// .Option(UpdateOption.Format, "zip") +// .Option(UpdateOption.MainApp, "") +// .Option(UpdateOption.DownloadTimeOut, 60) // Download timeout (seconds), default is 30 seconds if not specified +// .RemoteAddress(@"https://api.com/GeneralUpdate?version=1.0.0.1") // Specify update address +// .Launch(); + +#endregion + +private static void OnProgressChanged(object sender, ProgressChangedEventArgs e) +{ + if (e.Type == ProgressType.Updatefile) { - if (e.Type == ProgressType.Updatefile) - { - var str = $"当前更新第：{e.ProgressValue}个,更新文件总数：{e.TotalSize}"; - Console.WriteLine(str); - } - - if (e.Type == ProgressType.Done) - { - Console.WriteLine("更新完成"); - } + var str = $"Currently updating file: {e.ProgressValue}, total files to update: {e.TotalSize}"; + Console.WriteLine(str); } - private static void OnDownloadStatistics(object sender, DownloadStatisticsEventArgs e) + if (e.Type == ProgressType.Done) { - Console.WriteLine($"下载速度：{e.Speed}，剩余时间：{e.Remaining.Minute}:{e.Remaining.Second}"); + Console.WriteLine("Update completed"); } -``` - +} +private static void OnDownloadStatistics(object sender, DownloadStatisticsEventArgs e) +{ + Console.WriteLine($"Download speed: {e.Speed}, remaining time: {e.Remaining.Minute}:{e.Remaining.Second}"); +} +``` -GeneralUpdate.Single-1.0.0使用方式 +Using GeneralUpdate.Single-1.0.0 -``` +```csharp /// -/// App.xaml 的交互逻辑 +/// Interaction logic for App.xaml /// public partial class App : Application, ISingleInstanceApp { @@ -1360,13 +1181,13 @@ public partial class App : Application, ISingleInstanceApp if (e.Args == null || e.Args.Length == 0) { resultArgs = new string[6] { - "0.0.0.0", - "1.1.1.1", - "https://github.com/WELL-E", - "http://192.168.50.225:7000/update.zip", - @"E:\PlatformPath", - "509f0ede227de4a662763a4abe3d8470", - }; + "0.0.0.0", + "1.1.1.1", + "https://github.com/WELL-E", + "http://192.168.50.225:7000/update.zip", + @"E:\PlatformPath", + "509f0ede227de4a662763a4abe3d8470", + }; } else { @@ -1400,54 +1221,52 @@ public partial class App : Application, ISingleInstanceApp } ``` +Q&A +1. What should be done if there are multiple version iterations and cross-version updates? -问答Q&A - -1.如果版本迭代多次，跨版本更新，该怎么办呢？ - -​ 只要不是框架级别的更新都是可以更新的。不管你迭代多少次跨了多少个版本，你把最终的包放到服务器上就行了。这个里面没有涉及到增量更新，所以你更新多了直接把所有的新文件覆盖上去就行了。 - -2.GeneralUpdate是跟客户端是一个整体吗？ + As long as it's not a framework-level update, updates can be applied. Regardless of how many iterations or versions you cross, you just need to place the final package on the server. There is no incremental update involved here, so if there are many updates, you can simply overwrite all the new files. -​ 不是，GeneralUpdate是一个独立于客户端的程序。 +2. Is GeneralUpdate integrated with the client as a whole? -3.能不能增量更新、失败自动回滚、更新本地数据或配置文件? + No, GeneralUpdate is a program independent of the client. -​ 目前不能。（该功能已在开发计划当中）。 +3. Can it perform incremental updates, automatic rollback on failure, or update local data or configuration files? -4.GeneralUpdate是如何更新的? - -​ 更新的方式为把本地原有的客户端文件进行覆盖。 + Currently, it cannot. (This feature is in the development plan.) +4. How does GeneralUpdate perform updates? + The update method involves overwriting the existing client files locally. ## 📍2020-05-03 -1.简洁启动代码 如下：Launch1 Launch2 +Here is the translation of your content into English: -| 名称 | 类型 | 备注 | -| ---------------------- | -------- | ---------------------------------- | -| UpdateOption.Format | 配置参数 | 更新包的压缩格式（目前只支持zip） | -| UpdateOption.MainApp | 配置参数 | 更新完成后需要启动的主程序名称 | -| DownloadStatistics | 事件 | 更新包下载通知事件 | -| ProgressChanged | 事件 | 更新进度通知事件 | -| Strategy() | 方法 | 策略注入 | -| RemoteAddress（） | 方法 | 远程地址配置，如果没有则传入args[] | -| Launch | 方法 | 启动更新 | -| GeneralUpdateBootstrap | 类 | 更新引导类 | +1. Concise launch code as follows: Launch1 Launch2 -2.新增Strategy（更新策略），更新策略是开放出来让大家可以在不改动源码的情况下自由扩展更新方式将不会仅限于默认的更新策略。 +| Name | Type | Remarks | +| ---------------------- | ---------------- | ------------------------------------------------------------ | +| UpdateOption.Format | Config Parameter | Compression format of the update package (currently only supports zip) | +| UpdateOption.MainApp | Config Parameter | Name of the main application to launch after the update | +| DownloadStatistics | Event | Event notification for update package download | +| ProgressChanged | Event | Event notification for update progress | +| Strategy() | Method | Strategy injection | +| RemoteAddress() | Method | Remote address configuration, pass in args[] if not available | +| Launch | Method | Start update | +| GeneralUpdateBootstrap | Class | Update bootstrap class | -3.更新本地文件时，会有更新通知事件。明确的告知更新文件总数和当前更新到第几个文件 +2. Added Strategy (update strategy), which is open for everyone to freely extend the update method without modifying the source code, not limited to the default update strategy. -4.新增更新状态 Check（检查更新），Donwload（下载更新包），Updatefile（更新文件），Done（更新完成），Fail（更新失败）。开发者可以直接通过一系列枚举值直接判断当前运行状态做出相应的处理 +3. When updating local files, there will be an update notification event, clearly indicating the total number of files to update and the current file being updated. -5.新增若干启动配置参数的验证 +4. Added new update statuses: Check (check for updates), Download (download update package), UpdateFile (update files), Done (update completed), Fail (update failed). Developers can directly use a series of enumeration values to determine the current running status and make corresponding handling. -```c# +5. Added validation for several startup configuration parameters. + +```csharp if (args != null) { if (args.Length == 0) @@ -1478,80 +1297,81 @@ if (string.IsNullOrWhiteSpace(InstallPath)) if (string.IsNullOrWhiteSpace(MD5)) { - throw new NullReferenceException("install path not set"); + throw new NullReferenceException("MD5 not set"); } ``` -6.下载更新进度通知事件，将会提供剩余下载时间（Remaining）和下载速度（Speed） - -```c# - #region Launch1 +6. Download update progress notification event will provide remaining download time (Remaining) and download speed (Speed). + +```csharp +#region Launch1 + +args = new string[6] { + "0.0.0.0", + "1.1.1.1", + "https://github.com/WELL-E", + "http://192.168.50.225:7000/update.zip", + @"E:\PlatformPath", + "509f0ede227de4a662763a4abe3d8470", +}; + +GeneralUpdateBootstrap bootstrap = new GeneralUpdateBootstrap(); +bootstrap.DownloadStatistics += OnDownloadStatistics; +bootstrap.ProgressChanged += OnProgressChanged; +bootstrap.Strategy(). + Option(UpdateOption.Format, "zip"). // Specify the format of the update package, currently only supports zip + Option(UpdateOption.MainApp, "your application name"). // Specify the name of the main application to launch after the update, no need to add .exe, just the name + RemoteAddress(args). // Retains the previous parameter array collection + Launch(); + +#endregion + +#region Launch2 + +/* + * Launch2 + * Added a second launch method + * Process: + * 1. Specify the update address, e.g., https://api.com/GeneralUpdate?version=1.0.0.1, passing the current client version to the web API + * 2. If an update is needed, the API returns all update information (refer to /Models/UpdateInfo.cs for details) + * 3. After obtaining the update information, start an HTTP request for the update package + * 4. Download + * 5. Unzip + * 6. Update local files + * 7. Close the update program + * 8. Start the configured main program + * The update program must be in the same directory as the main program + */ + +// GeneralUpdateBootstrap bootstrap2 = new GeneralUpdateBootstrap(); +// bootstrap2.DownloadStatistics += OnDownloadStatistics; +// bootstrap2.ProgressChanged += OnProgressChanged; +// bootstrap2.Strategy(). +// Option(UpdateOption.Format, "zip"). +// Option(UpdateOption.MainApp, "KGS.CPP"). +// RemoteAddress(@"https://api.com/GeneralUpdate?version=1.0.0.1"). // Specify the update address +// Launch(); + +#endregion + +private static void OnProgressChanged(object sender, ProgressChangedEventArgs e) +{ + if (e.Type == ProgressType.Updatefile) + { + var str = $"Currently updating file: {e.ProgressValue}, Total number of files to update: {e.TotalSize}"; + Console.WriteLine(str); + } - args = new string[6] { - "0.0.0.0", - "1.1.1.1", - "https://github.com/WELL-E", - "http://192.168.50.225:7000/update.zip", - @"E:\PlatformPath", - "509f0ede227de4a662763a4abe3d8470", - }; - - GeneralUpdateBootstrap bootstrap = new GeneralUpdateBootstrap(); - bootstrap.DownloadStatistics += OnDownloadStatistics; - bootstrap.ProgressChanged += OnProgressChanged; - bootstrap.Strategy(). - Option(UpdateOption.Format, "zip").//指定更新包的格式，目前只支持zip - Option(UpdateOption.MainApp, "your application name").//指定更新完成后需要启动的主程序名称不需要加.exe直接写名称即可 - RemoteAddress(args).//这里的参数保留了之前的参数数组集合 - Launch(); - - #endregion - - #region Launch2 - - /* - * Launch2 - * 新增了第二种启动方式 - * 流程： - * 1.指定更新地址，https://api.com/GeneralUpdate?version=1.0.0.1 在webapi中传入客户端当前版本号 - * 2.如果需要更新api返回给你所有的更新信息（详情内容参考 /Models/UpdateInfo.cs） - * 3.拿到更新信息之后则开始http请求更新包 - * 4.下载 - * 5.解压 - * 6.更新本地文件 - * 7.关闭更新程序 - * 8.启动配置好主程序 - * 更新程序必须跟主程序放在同级目录下 - */ - - //GeneralUpdateBootstrap bootstrap2 = new GeneralUpdateBootstrap(); - //bootstrap2.DownloadStatistics += OnDownloadStatistics; - //bootstrap2.ProgressChanged += OnProgressChanged; - //bootstrap2.Strategy(). - // Option(UpdateOption.Format, "zip"). - // Option(UpdateOption.MainApp, "KGS.CPP"). - // RemoteAddress(@"https://api.com/GeneralUpdate?version=1.0.0.1").//指定更新地址 - // Launch(); - - #endregion - - - private static void OnProgressChanged(object sender, ProgressChangedEventArgs e) - { - if (e.Type == ProgressType.Updatefile) - { - var str = $"当前更新第：{e.ProgressValue}个,更新文件总数：{e.TotalSize}"; - Console.WriteLine(str); - } - - if (e.Type == ProgressType.Done) - { - Console.WriteLine("更新完成"); - } - } + if (e.Type == ProgressType.Done) + { + Console.WriteLine("Update completed"); + } +} - private static void OnDownloadStatistics(object sender, DownloadStatisticsEventArgs e) - { - Console.WriteLine($"下载速度：{e.Speed}，剩余时间：{e.Remaining.Minute}:{e.Remaining.Second}"); - } +private static void OnDownloadStatistics(object sender, DownloadStatisticsEventArgs e) +{ + Console.WriteLine($"Download speed: {e.Speed}, Remaining time: {e.Remaining.Minutes}:{e.Remaining.Seconds}"); +} ``` + +Let me know if you need further assistance! diff --git a/website/i18n/zh-Hans/docusaurus-theme-classic/navbar.json b/website/i18n/zh-Hans/docusaurus-theme-classic/navbar.json index 177b56d..00e9acd 100644 --- a/website/i18n/zh-Hans/docusaurus-theme-classic/navbar.json +++ b/website/i18n/zh-Hans/docusaurus-theme-classic/navbar.json @@ -7,24 +7,24 @@ "message": "GeneralLibrary Logo", "description": "The alt text of navbar logo" }, - "item.label.文档": { + "item.label.Doc": { "message": "文档", - "description": "Navbar item with label 文档" + "description": "Navbar item with label Doc" }, - "item.label.生态伙伴": { - "message": "生态伙伴", - "description": "Navbar item with label 生态伙伴" - }, - "item.label.企业合作": { - "message": "企业合作", - "description": "Navbar item with label 企业合作" - }, - "item.label.关于": { - "message": "关于", - "description": "Navbar item with label 关于" + "item.label.商务": { + "message": "商务", + "description": "Navbar item with label 商务" }, "item.label.GitHub": { "message": "GitHub", "description": "Navbar item with label GitHub" + }, + "item.label.GeneralSpacestation": { + "message": "GeneralSpacestation", + "description": "Navbar item with label GeneralSpacestation" + }, + "item.label.软件外包服务": { + "message": "软件外包服务", + "description": "Navbar item with label 软件外包服务" } } diff --git a/website/sidebars.js b/website/sidebars.js index 2524f79..17e9c6e 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -4,41 +4,28 @@ * GeneralUpdate documentation sidebar. * * Pages are grouped by role: - * 1. Quick Start & Cookbooks — first-time user flow and advanced production guides - * 2. Components — non-firmware component reference (Core, Bowl, - * Differential, Drivelution, Extension) - * 3. Tools — GeneralUpdate.Tools usage and artifact reference - * 4. Infrastructure — server-side services (Spacestation, Hub) - * 5. OSS Update Mode — OSS-based update flows (.NET & MAUI) - * 6. Utilities — shared helpers (GeneralTracer) - * 7. Guides — operational / platform-specific guides - * 8. Release Log — changelog and roadmap + * 1. Quick Start — Beginner cookbook & Tools reference + * 2. Components — non-firmware component reference (Core, Bowl, + * Differential, Drivelution, Extension) + * 3. Help — operational / platform-specific guides + * 4. Release Log — changelog and roadmap */ /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { tutorialSidebar: [ - // ── 1. Quick Start & Cookbooks ────────────────────────────────── + // ── 1. Quick Start ────────────────────────────────────────────── { type: 'category', label: 'Quick Start', collapsed: false, items: [ - 'quickstart/Quik start', - 'quickstart/Sample UI', 'quickstart/Beginner cookbook', - ], - }, - { - type: 'category', - label: 'Advanced Cookbook', - collapsed: true, - items: [ - 'quickstart/Advanced cookbook', + 'quickstart/GeneralUpdate.PacketTool', ], }, - // ── 2. Components (non-firmware) ──────────────────────────────── + // ── 2. Components ─────────────────────────────────────────────── { type: 'category', label: 'Components', @@ -54,58 +41,17 @@ const sidebars = { ], }, - // ── 3. GeneralUpdate.Tools ────────────────────────────────────── - { - type: 'category', - label: 'Tools', - collapsed: true, - items: [ - 'doc/GeneralUpdate.PacketTool', - ], - }, - - // ── 4. Infrastructure ─────────────────────────────────────────── - { - type: 'category', - label: 'Infrastructure', - collapsed: true, - items: [ - 'doc/GeneralSpacestation', - ], - }, - - // ── 5. OSS Update Mode ────────────────────────────────────────── - { - type: 'category', - label: 'OSS Update Mode', - collapsed: true, - items: [ - 'doc/GeneralClient.OSS', - 'doc/GeneralUpdate.Maui.OSS', - ], - }, - - // ── 6. Utilities ──────────────────────────────────────────────── - { - type: 'category', - label: 'Utilities', - collapsed: true, - items: [ - 'doc/GeneralTracer', - ], - }, - - // ── 7. Guides ─────────────────────────────────────────────────── + // ── 3. Help ───────────────────────────────────────────────────── { type: 'category', - label: 'Guides', + label: '帮助', collapsed: true, items: [ { type: 'autogenerated', dirName: 'guide' }, ], }, - // ── 8. Release Log ────────────────────────────────────────────── + // ── 4. Release Log ────────────────────────────────────────────── { type: 'category', label: 'Release Log', From a74bd0b96c28f5ea5621c06f6b53b2e66bd7a4db Mon Sep 17 00:00:00 2001 From: JusterZhu Date: Thu, 4 Jun 2026 01:50:18 +0800 Subject: [PATCH 2/5] fix: resolve Docusaurus broken links after site restructure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Android auto-update (3 langs): replace deleted ./GeneralClient.OSS.md link - Drivelution (en): replace deleted ../guide/Driver.md link - PacketTool (3 langs): fix all ./ relative links → ../doc/ after move to quickstart/ - PacketTool (3 langs): remove references to deleted GeneralClient.OSS and Advanced cookbook Co-Authored-By: Claude Opus 4.8 --- website/docs/doc/Android auto-update.md | 2 +- website/docs/doc/GeneralUpdate.Drivelution.md | 2 +- .../docs/quickstart/GeneralUpdate.PacketTool.md | 14 ++++++-------- .../current/doc/Android auto-update.md | 2 +- .../current/doc/GeneralUpdate.Drivelution.md | 2 +- .../current/quickstart/GeneralUpdate.PacketTool.md | 14 ++++++-------- .../current/doc/Android auto-update.md | 2 +- .../current/quickstart/GeneralUpdate.PacketTool.md | 14 ++++++-------- 8 files changed, 23 insertions(+), 29 deletions(-) diff --git a/website/docs/doc/Android auto-update.md b/website/docs/doc/Android auto-update.md index 9364f13..5b8509b 100644 --- a/website/docs/doc/Android auto-update.md +++ b/website/docs/doc/Android auto-update.md @@ -419,5 +419,5 @@ Avalonia 采用**三阶段 API**，将下载验证与安装触发分离，给予 - [GeneralUpdate.Maui 仓库](https://github.com/GeneralLibrary/GeneralUpdate.Maui) - [GeneralUpdate.Avalonia 仓库](https://github.com/GeneralLibrary/GeneralUpdate.Avalonia) - [GeneralUpdate.Core 组件文档](./GeneralUpdate.Core.md) -- [OSS 更新模式文档](./GeneralClient.OSS.md) +- [GeneralUpdate.Core 组件文档](./GeneralUpdate.Core.md) - [入门实战手册](../quickstart/Beginner cookbook.md) diff --git a/website/docs/doc/GeneralUpdate.Drivelution.md b/website/docs/doc/GeneralUpdate.Drivelution.md index 50362ad..12b82aa 100644 --- a/website/docs/doc/GeneralUpdate.Drivelution.md +++ b/website/docs/doc/GeneralUpdate.Drivelution.md @@ -554,4 +554,4 @@ GeneralTracer.SetTracingEnabled(true); - [驱动更新示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Hub/Samples/ImDiskQuickInstallSample.cs) - [GeneralUpdate 仓库](https://github.com/GeneralLibrary/GeneralUpdate) -- [驱动指南](../guide/Driver.md) +- [GeneralUpdate.Drivelution 组件文档](../doc/GeneralUpdate.Drivelution.md) diff --git a/website/docs/quickstart/GeneralUpdate.PacketTool.md b/website/docs/quickstart/GeneralUpdate.PacketTool.md index f30cb13..c269482 100644 --- a/website/docs/quickstart/GeneralUpdate.PacketTool.md +++ b/website/docs/quickstart/GeneralUpdate.PacketTool.md @@ -144,7 +144,7 @@ dotnet run --project GeneralUpdate.Tools.csproj - Extension Host 调用 `ExtensionManager.QueryRemoteExtensionsAsync(...)` 获取扩展列表 - 安装时下载 ZIP，读取 `manifest.json` 进行兼容性检查和依赖解析 -- 详见 [GeneralUpdate.Extension](./GeneralUpdate.Extension.md) +- 详见 [GeneralUpdate.Extension](../doc/GeneralUpdate.Extension.md) --- @@ -189,7 +189,7 @@ dotnet run --project GeneralUpdate.Tools.csproj - 将 `oss_config.json` 上传到 OSS bucket 或静态文件服务器 - OSS 客户端读取此文件发现可用版本，下载后校验 Hash -- 详见 [GeneralClient.OSS](./GeneralClient.OSS.md) +- 详见 [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md) OSS 更新策略 --- @@ -349,9 +349,7 @@ Generate Sample 额外输出： ## 关联文档 -- [GeneralUpdate.Core](./GeneralUpdate.Core.md)：Client/Upgrade 更新主流程 -- [GeneralUpdate.Differential](./GeneralUpdate.Differential.md)：差分算法 Clean/Dirty 模式 -- [GeneralUpdate.Extension](./GeneralUpdate.Extension.md)：扩展包安装与版本管理 -- [GeneralClient.OSS](./GeneralClient.OSS.md)：OSS 更新链路 -- [入门实战手册](../quickstart/Beginner cookbook.md)：从零跑通完整更新闭环 -- [高级实战手册](../quickstart/Advanced cookbook.md)：CI/CD 集成与生产发布 +- [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)：Client/Upgrade 更新主流程 +- [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential.md)：差分算法 Clean/Dirty 模式 +- [GeneralUpdate.Extension](../doc/GeneralUpdate.Extension.md)：扩展包安装与版本管理 +- [入门实战手册](./Beginner%20cookbook.md)：从零跑通完整更新闭环 diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/Android auto-update.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/Android auto-update.md index dbde290..e1f888a 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/Android auto-update.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/Android auto-update.md @@ -419,5 +419,5 @@ Format: `{package-name}.{arbitrary-suffix}`, e.g. `com.example.app.generalupdate - [GeneralUpdate.Maui repository](https://github.com/GeneralLibrary/GeneralUpdate.Maui) - [GeneralUpdate.Avalonia repository](https://github.com/GeneralLibrary/GeneralUpdate.Avalonia) - [GeneralUpdate.Core component docs](./GeneralUpdate.Core.md) -- [OSS update mode docs](./GeneralClient.OSS.md) +- [GeneralUpdate.Core component docs](./GeneralUpdate.Core.md) - [Beginner cookbook](../quickstart/Beginner cookbook.md) diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Drivelution.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Drivelution.md index c386095..09a55a5 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Drivelution.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Drivelution.md @@ -354,4 +354,4 @@ GeneralTracer.SetTracingEnabled(true); // Re-enable for troubleshooting - [Driver Update Sample](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Hub/Samples/ImDiskQuickInstallSample.cs) - [GeneralUpdate Repository](https://github.com/GeneralLibrary/GeneralUpdate) -- [Driver Guide](../guide/Driver.md) +- [GeneralUpdate.Drivelution docs](../doc/GeneralUpdate.Drivelution.md) diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/GeneralUpdate.PacketTool.md b/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/GeneralUpdate.PacketTool.md index 3ab1930..4466b53 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/GeneralUpdate.PacketTool.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/quickstart/GeneralUpdate.PacketTool.md @@ -138,7 +138,7 @@ Example `manifest.json`: - Extension Host calls `ExtensionManager.QueryRemoteExtensionsAsync(...)` to list available extensions - On install, downloads the ZIP, reads `manifest.json` for compatibility checks and dependency resolution -- See [GeneralUpdate.Extension](./GeneralUpdate.Extension.md) for details +- See [GeneralUpdate.Extension](../doc/GeneralUpdate.Extension.md) for details --- @@ -183,7 +183,7 @@ If you use OSS mode updates (static file server), you need to maintain a `versio - Upload `oss_config.json` to your OSS bucket or static file server - OSS client reads this file to discover versions and validates Hash after download -- See [GeneralClient.OSS](./GeneralClient.OSS.md) +- See [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md) OSS update strategy --- @@ -338,9 +338,7 @@ This sequence chains the six modules into a complete release pipeline: ## Related docs -- [GeneralUpdate.Core](./GeneralUpdate.Core.md): Client/Upgrade main update flow -- [GeneralUpdate.Differential](./GeneralUpdate.Differential.md): Differential algorithm Clean/Dirty modes -- [GeneralUpdate.Extension](./GeneralUpdate.Extension.md): Extension install and version management -- [GeneralClient.OSS](./GeneralClient.OSS.md): OSS update flow -- [Beginner cookbook](../quickstart/Beginner cookbook.md): Complete end-to-end update walkthrough -- [Advanced cookbook](../quickstart/Advanced cookbook.md): CI/CD integration and production releases +- [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md): Client/Upgrade main update flow +- [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential.md): Differential algorithm Clean/Dirty modes +- [GeneralUpdate.Extension](../doc/GeneralUpdate.Extension.md): Extension install and version management +- [Beginner cookbook](./Beginner%20cookbook.md): Complete end-to-end update walkthrough diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/Android auto-update.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/Android auto-update.md index 9364f13..5b8509b 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/Android auto-update.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/Android auto-update.md @@ -419,5 +419,5 @@ Avalonia 采用**三阶段 API**，将下载验证与安装触发分离，给予 - [GeneralUpdate.Maui 仓库](https://github.com/GeneralLibrary/GeneralUpdate.Maui) - [GeneralUpdate.Avalonia 仓库](https://github.com/GeneralLibrary/GeneralUpdate.Avalonia) - [GeneralUpdate.Core 组件文档](./GeneralUpdate.Core.md) -- [OSS 更新模式文档](./GeneralClient.OSS.md) +- [GeneralUpdate.Core 组件文档](./GeneralUpdate.Core.md) - [入门实战手册](../quickstart/Beginner cookbook.md) diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/GeneralUpdate.PacketTool.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/GeneralUpdate.PacketTool.md index f30cb13..c269482 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/GeneralUpdate.PacketTool.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/quickstart/GeneralUpdate.PacketTool.md @@ -144,7 +144,7 @@ dotnet run --project GeneralUpdate.Tools.csproj - Extension Host 调用 `ExtensionManager.QueryRemoteExtensionsAsync(...)` 获取扩展列表 - 安装时下载 ZIP，读取 `manifest.json` 进行兼容性检查和依赖解析 -- 详见 [GeneralUpdate.Extension](./GeneralUpdate.Extension.md) +- 详见 [GeneralUpdate.Extension](../doc/GeneralUpdate.Extension.md) --- @@ -189,7 +189,7 @@ dotnet run --project GeneralUpdate.Tools.csproj - 将 `oss_config.json` 上传到 OSS bucket 或静态文件服务器 - OSS 客户端读取此文件发现可用版本，下载后校验 Hash -- 详见 [GeneralClient.OSS](./GeneralClient.OSS.md) +- 详见 [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md) OSS 更新策略 --- @@ -349,9 +349,7 @@ Generate Sample 额外输出： ## 关联文档 -- [GeneralUpdate.Core](./GeneralUpdate.Core.md)：Client/Upgrade 更新主流程 -- [GeneralUpdate.Differential](./GeneralUpdate.Differential.md)：差分算法 Clean/Dirty 模式 -- [GeneralUpdate.Extension](./GeneralUpdate.Extension.md)：扩展包安装与版本管理 -- [GeneralClient.OSS](./GeneralClient.OSS.md)：OSS 更新链路 -- [入门实战手册](../quickstart/Beginner cookbook.md)：从零跑通完整更新闭环 -- [高级实战手册](../quickstart/Advanced cookbook.md)：CI/CD 集成与生产发布 +- [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)：Client/Upgrade 更新主流程 +- [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential.md)：差分算法 Clean/Dirty 模式 +- [GeneralUpdate.Extension](../doc/GeneralUpdate.Extension.md)：扩展包安装与版本管理 +- [入门实战手册](./Beginner%20cookbook.md)：从零跑通完整更新闭环 From 2bbbbadea14d01e6cb1bcbc074d9ca38db9192a5 Mon Sep 17 00:00:00 2001 From: JusterZhu Date: Thu, 4 Jun 2026 01:55:07 +0800 Subject: [PATCH 3/5] fix: resolve remaining broken links to deleted Architecture and Quik start pages - Packaging (source + en): replace ./Architecture.md and ../quickstart/Quik start links - Core (source + en): replace ../guide/Architecture.md and ../quickstart/Quik start links - Verified zero links to any deleted files across all .md files Co-Authored-By: Claude Opus 4.8 --- website/docs/doc/GeneralUpdate.Core.md | 4 ++-- website/docs/guide/Packaging.md | 4 ++-- .../current/doc/GeneralUpdate.Core.md | 4 ++-- .../docusaurus-plugin-content-docs/current/guide/Packaging.md | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/website/docs/doc/GeneralUpdate.Core.md b/website/docs/doc/GeneralUpdate.Core.md index 876446d..0554ed6 100644 --- a/website/docs/doc/GeneralUpdate.Core.md +++ b/website/docs/doc/GeneralUpdate.Core.md @@ -881,5 +881,5 @@ GeneralTracer.Dispose(); - [GeneralUpdate 仓库](https://github.com/GeneralLibrary/GeneralUpdate) - [Samples 示例代码](https://github.com/GeneralLibrary/GeneralUpdate-Samples) - [GeneralUpdate.Tools](https://github.com/GeneralLibrary/GeneralUpdate.Tools) -- [快速开始](../quickstart/Quik%20start.md) -- [架构指南](../guide/Architecture.md) +- [入门实战手册](../quickstart/Beginner%20cookbook.md) +- [组件文档](./GeneralUpdate.Core.md) diff --git a/website/docs/guide/Packaging.md b/website/docs/guide/Packaging.md index 1e3dfda..2131634 100644 --- a/website/docs/guide/Packaging.md +++ b/website/docs/guide/Packaging.md @@ -281,5 +281,5 @@ jobs: - **[GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool)** — 补丁包和配置生成工具 - **[权限指南](./Permission.md)** — Windows UAC 权限处理 -- **[快速入门](../quickstart/Quik start)** — 5 分钟快速上手 -- **[系统架构](./Architecture.md)** — 了解整体打包部署架构 +- **[入门实战手册](../quickstart/Beginner%20cookbook.md)** — 从零跑通更新闭环 +- **[GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)** — 核心更新引擎架构 diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Core.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Core.md index 226fd93..b79af76 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Core.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Core.md @@ -664,5 +664,5 @@ GeneralTracer.Dispose(); - [GeneralUpdate Repository](https://github.com/GeneralLibrary/GeneralUpdate) - [Samples Code](https://github.com/GeneralLibrary/GeneralUpdate-Samples) - [GeneralUpdate.Tools](https://github.com/GeneralLibrary/GeneralUpdate.Tools) -- [Quick Start](../quickstart/Quik%20start.md) -- [Architecture Guide](../guide/Architecture.md) +- [Beginner Cookbook](../quickstart/Beginner%20cookbook.md) +- [Component docs](./GeneralUpdate.Core.md) diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Packaging.md b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Packaging.md index 35fff77..f487979 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Packaging.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Packaging.md @@ -217,5 +217,5 @@ Before deploying, verify: - **[GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool)** — Patch and config generation tool - **[Permission Guide](./Permission.md)** — Windows UAC permission handling -- **[Quick Start](../quickstart/Quik start)** — 5-minute quickstart -- **[Architecture](./Architecture.md)** — Overall deployment architecture +- **[Beginner Cookbook](../quickstart/Beginner%20cookbook.md)** — Complete update walkthrough +- **[GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)** — Core update engine architecture From 8c992dc50f0586c051c0ab9d53157b0097457ef4 Mon Sep 17 00:00:00 2001 From: JusterZhu Date: Thu, 4 Jun 2026 02:03:02 +0800 Subject: [PATCH 4/5] fix: zh-Hans Drivelution still had old Driver.md link Co-Authored-By: Claude Opus 4.8 --- .../current/doc/GeneralUpdate.Drivelution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Drivelution.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Drivelution.md index 50362ad..12b82aa 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Drivelution.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Drivelution.md @@ -554,4 +554,4 @@ GeneralTracer.SetTracingEnabled(true); - [驱动更新示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Hub/Samples/ImDiskQuickInstallSample.cs) - [GeneralUpdate 仓库](https://github.com/GeneralLibrary/GeneralUpdate) -- [驱动指南](../guide/Driver.md) +- [GeneralUpdate.Drivelution 组件文档](../doc/GeneralUpdate.Drivelution.md) From b4b38b916490eeff1a24d3d7dc0fc78cc80d45c1 Mon Sep 17 00:00:00 2001 From: JusterZhu Date: Thu, 4 Jun 2026 02:05:57 +0800 Subject: [PATCH 5/5] =?UTF-8?q?fix:=20update=20Packaging=20links=20to=20Pa?= =?UTF-8?q?cketTool=20(moved=20doc=E2=86=92quickstart)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- website/docs/guide/Packaging.md | 4 ++-- .../docusaurus-plugin-content-docs/current/guide/Packaging.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/guide/Packaging.md b/website/docs/guide/Packaging.md index 2131634..0329db7 100644 --- a/website/docs/guide/Packaging.md +++ b/website/docs/guide/Packaging.md @@ -24,7 +24,7 @@ sidebar_position: 6 6. 填写包名和版本号 7. 点击「构建」 -详细说明请参考 [GeneralUpdate.Tools 文档](../doc/GeneralUpdate.PacketTool)。 +详细说明请参考 [GeneralUpdate.Tools 文档](../quickstart/GeneralUpdate.PacketTool)。 ### 使用 Differential API 编程生成 @@ -279,7 +279,7 @@ jobs: ## 相关资源 -- **[GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool)** — 补丁包和配置生成工具 +- **[GeneralUpdate.Tools](../quickstart/GeneralUpdate.PacketTool)** — 补丁包和配置生成工具 - **[权限指南](./Permission.md)** — Windows UAC 权限处理 - **[入门实战手册](../quickstart/Beginner%20cookbook.md)** — 从零跑通更新闭环 - **[GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)** — 核心更新引擎架构 diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Packaging.md b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Packaging.md index f487979..ad4fb28 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Packaging.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/guide/Packaging.md @@ -23,7 +23,7 @@ This guide covers how to package your application with its update system for dis 6. Enter package name and version 7. Click "Build" -See the [GeneralUpdate.Tools documentation](../doc/GeneralUpdate.PacketTool) for details. +See the [GeneralUpdate.Tools documentation](../quickstart/GeneralUpdate.PacketTool) for details. ### Using the Differential API Programmatically @@ -215,7 +215,7 @@ Before deploying, verify: ## Related Resources -- **[GeneralUpdate.Tools](../doc/GeneralUpdate.PacketTool)** — Patch and config generation tool +- **[GeneralUpdate.Tools](../quickstart/GeneralUpdate.PacketTool)** — Patch and config generation tool - **[Permission Guide](./Permission.md)** — Windows UAC permission handling - **[Beginner Cookbook](../quickstart/Beginner%20cookbook.md)** — Complete update walkthrough - **[GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)** — Core update engine architecture