Skip to content

README.zh-CN.md

Latest commit

 

History

History
457 lines (309 loc) · 12.9 KB

README.zh-CN.md

File metadata and controls

457 lines (309 loc) · 12.9 KB

🛠️ GeneralUpdate.Tools

GeneralUpdate Logo

一个强大的桌面工具，用于管理软件更新和扩展 🚀

License .NET Avalonia

English | 简体中文

📖 什么是 GeneralUpdate.Tools？

GeneralUpdate.Tools 是一个用户友好的桌面应用程序，帮助开发者创建和管理软件更新包。它是 GeneralUpdate 生态系统的一部分 - 一个在应用程序中实现自动更新的完整解决方案。

可以把它看作你的**"更新包工作坊"** 🏭，你可以在这里：

  • 📦 创建差异更新包（只传输变化的内容！）
  • 📝 生成版本配置文件
  • 🧩 打包和管理应用程序扩展

✨ 为什么使用这个工具？

  • 💡 对新手友好：简单的可视化界面 - 无需复杂的命令行
  • ⚡ 节省带宽：创建只包含更改文件的差异包
  • 🎯 跨平台：适用于 Windows 和 Linux
  • 🔧 一体化：一个应用程序中的三个强大工具

🎯 核心功能

1️⃣ 差异包生成器 📦

为你的应用程序创建差异更新包。不需要再次传输整个应用程序，只包含更改的文件！

功能说明：

  • 比较旧版本和新版本
  • 识别仅变化的文件
  • 创建压缩更新包（.zip）
  • 可选包含驱动程序文件

适用于： 减少下载大小和更新时间

2️⃣ OSS 配置生成器 📝

生成 version.json 配置文件，告诉你的应用程序在哪里以及如何下载更新。

功能说明：

  • 创建 JSON 格式的版本配置
  • 指定更新包 URL 和元数据
  • 管理版本历史
  • 支持哈希验证以确保安全

适用于： 管理更新元数据和版本跟踪

3️⃣ 扩展管理器 🧩

将你的应用程序扩展打包成带有适当元数据的可分发包。

功能说明：

  • 将扩展目录压缩为 .zip 文件
  • 生成带有扩展元数据的 manifest.json
  • 支持自定义属性和依赖项
  • 平台特定目标（Windows/Linux/MacOS）

适用于： 创建插件系统和扩展市场

🚀 快速开始指南

前置要求

开始之前，请确保你有：

  • ✅ 操作系统：Windows 10+ 或 Linux（Ubuntu 20.04+）
  • ✅ .NET 运行时：.NET 8.0 SDK 或 Runtime
  • ✅ 磁盘空间：至少 200MB 可用空间

📥 安装

方式 1：下载预构建版本（推荐新手使用）

  1. 访问 Releases 页面
  2. 下载适合你平台的最新版本
  3. 将 ZIP 文件解压到一个文件夹
  4. 运行可执行文件：
    • Windows：双击 GeneralUpdate.Tool.Avalonia.exe
    • Linux：在终端中运行 ./GeneralUpdate.Tool.Avalonia

方式 2：从源码构建

# 1. 克隆仓库
git clone https://github.com/GeneralLibrary/GeneralUpdate.Tools.git
cd GeneralUpdate.Tools

# 2. 进入源码文件夹
cd src

# 3. 还原依赖项
dotnet restore

# 4. 构建项目
dotnet build

# 5. 运行应用程序
dotnet run

📚 使用教程（实战指南）

🍳 教程 1：创建你的第一个更新包

让我们一步步创建一个差异更新包！

场景： 你有应用程序的 1.0.0 版本，想要更新到 2.0.0 版本

步骤 1：准备你的目录

你需要三个文件夹：

  • 应用目录（📂 旧版本）：包含你的 1.0.0 版本文件
  • 发布目录（📂 新版本）：包含你的 2.0.0 版本文件
  • 补丁目录（📂 输出）：差异文件将保存在这里
示例结构：
C:/MyApp/v1.0.0/     ← 旧版本
C:/MyApp/v2.0.0/     ← 新版本
C:/MyApp/patch/      ← 临时输出文件夹

步骤 2：打开差异包生成器

  1. 启动 GeneralUpdate.Tools
  2. 点击顶部的 "Packet" 选项卡
  3. 你会看到一个带有多个字段的表单

步骤 3：配置你的包

填写字段：

字段 填写内容 示例
Name 包文件名 MyApp_Update_v2.0.0
App Directory 旧版本路径 C:/MyApp/v1.0.0/
Release Directory 新版本路径 C:/MyApp/v2.0.0/
Patch Directory 临时输出路径 C:/MyApp/patch/
Format 压缩格式 .zip（默认）
Encoding 文本编码 UTF-8（推荐）

步骤 4：可选 - 添加驱动文件

如果你的更新包含驱动文件：

  1. 点击 "Driver Directory" 旁边的 "Select"
  2. 选择包含驱动文件的文件夹
  3. 它们将自动放置在包内的 drivers/ 文件夹中

步骤 5：构建包！

  1. 点击 "Build" 按钮 🔨
  2. 等待处理（可能需要一些时间）
  3. 成功！🎉 你会看到消息 "Build success"
  4. 你的更新包保存在补丁目录的父目录中

结果： 你现在有了一个只包含更改文件的 .zip 文件！

🍳 教程 2：创建版本配置（OSS 配置）

现在让我们创建一个 version.json 文件，告诉你的应用程序可用的更新。

步骤 1：打开 OSS 配置生成器

  1. 点击 "OSS Packet" 选项卡
  2. 你会看到版本信息字段

步骤 2：输入版本信息

填写你的更新详细信息：

字段 填写内容 示例
Version 版本号 2.0.0.0
Packet Name .zip 文件名 MyApp_Update_v2.0.0.zip
URL 下载 URL https://updates.myapp.com/packages/MyApp_Update_v2.0.0.zip
Date 发布日期 2026-02-11
Time 发布时间 16:30:00

步骤 3：计算哈希值（安全性）

  1. 点击 "Hash" 按钮 🔒
  2. 选择你的 .zip 包文件
  3. 工具将计算 SHA256 哈希值
  4. 这确保下载没有被损坏或篡改

步骤 4：添加到配置

  1. 点击 "Append" ➕ 将此版本添加到列表
  2. 你可以添加多个版本（版本历史）
  3. JSON 预览将自动更新

步骤 5：保存配置

  1. 点击 "Build" 按钮 💾
  2. 选择保存 version.json 文件的位置
  3. 成功！你现在可以将此文件上传到服务器

结果： 你有一个如下所示的 version.json 文件：

[
  {
    "Version": "2.0.0.0",
    "PacketName": "MyApp_Update_v2.0.0.zip",
    "Url": "https://updates.myapp.com/packages/MyApp_Update_v2.0.0.zip",
    "Hash": "abc123def456...",
    "Date": "2026-02-11T16:30:00"
  }
]

🍳 教程 3：打包扩展

创建一个带有元数据的可分发扩展包。

步骤 1：准备你的扩展

确保你有：

  • 包含扩展文件的文件夹
  • 扩展元数据（名称、版本、描述）

步骤 2：打开扩展管理器

  1. 点击 "Extension" 选项卡
  2. 你会看到一个综合表单

步骤 3：填写基本信息

字段 填写内容 示例
Name 扩展标识符 MyAwesomePlugin
Display Name 用户友好名称 My Awesome Plugin
Version 版本号 1.0.0.0
Description 功能说明 为你的应用添加强大功能
Publisher 你的名字/公司 你的公司名称

步骤 4：选择目录

  1. Extension Directory：点击 "Select" 并选择你的扩展文件夹
  2. Export Path：点击 "Select" 并选择保存包的位置

步骤 5：配置平台和详细信息

  • Platform：选择目标平台（Windows/Linux/MacOS/All）
  • License：输入许可证类型（例如 "MIT"、"Apache-2.0"）
  • Categories：输入逗号分隔的类别（例如 "Tools, Productivity"）

步骤 6：高级选项（可选）

  • Dependencies：输入所需的扩展 ID（逗号分隔）
  • Min/Max Host Version：指定兼容的应用版本
  • Custom Properties：为额外的元数据添加键值对

步骤 7：生成包

  1. 点击 "Generate" 按钮 🎁
  2. 等待压缩
  3. 成功！你的扩展包已创建

结果： 你得到一个类似 MyAwesomePlugin_1.0.0.0.zip 的 .zip 文件，其中包含：

  • 所有扩展文件
  • 带有所有元数据的 manifest.json

🎨 理解界面

主窗口布局

┌─────────────────────────────────────┐
│  [Packet] [OSS Packet] [Extension]  │  ← 选项卡
├─────────────────────────────────────┤
│                                     │
│         功能内容区域                │
│                                     │
│  (选定功能的表单和控件              │
│   显示在这里)                       │
│                                     │
└─────────────────────────────────────┘

常用按钮

  • 🔨 Build/Generate：创建包/文件
  • 📁 Select：打开文件夹选择器
  • ➕ Append：将项目添加到列表
  • 🗑️ Clear：重置表单字段
  • 📋 Copy：复制内容到剪贴板
  • 🔒 Hash：计算文件哈希值

❓ 常见问题（FAQ）

问：'Packet' 和 'OSS Packet' 有什么区别？

答： 可以这样理解：

  • Packet Builder（差异包生成器） 创建实际的更新文件（.zip 包）
  • OSS Packet Builder（OSS 配置生成器） 创建告诉在哪里下载的配置

你两者都需要！首先创建包，然后创建配置文件。

问：我需要在更新包中包含所有文件吗？

答： 不需要！这就是差异更新的美妙之处。工具会自动：

  1. 比较旧版本与新版本
  2. 仅包含更改的/新的文件
  3. 在更新期间删除已删除的文件

这节省了带宽并加快了下载速度！🚀

问：哈希字段是用来做什么的？

答： 哈希值就像文件的指纹。它确保：

  • ✅ 文件在下载过程中没有损坏
  • ✅ 文件没有被篡改
  • ✅ 用户获得的正是你发布的内容

为了安全，请务必计算并包含哈希值！

问：我可以在商业项目中使用它吗？

答： 可以！该项目使用 Apache 2.0 许可证，允许商业使用。详情请参阅 LICENSE。

问：支持哪些平台？

答： 该工具可在以下平台上运行：

  • ✅ Windows 10 及更高版本
  • ✅ Linux（Ubuntu、Debian、Fedora 等）

生成的包可以针对：

  • ✅ Windows
  • ✅ Linux
  • ✅ MacOS（通过扩展管理器）

问：在哪里可以了解更多关于 GeneralUpdate 的信息？

答： 查看主项目：

🐛 故障排除

问题：出现 "Build fail" 消息

解决方案：

  1. ✅ 检查所有目录路径是否存在
  2. ✅ 确保你有写权限
  3. ✅ 确保磁盘有足够的可用空间
  4. ✅ 验证 .NET 8.0 是否正确安装

问题："Access denied" 错误

解决方案：

  1. ✅ 以管理员身份运行应用程序（Windows）
  2. ✅ 检查文件夹权限
  3. ✅ 确保文件没有被其他程序锁定

问题：应用程序无法启动

解决方案：

  1. ✅ 安装 .NET 8.0 Runtime
  2. ✅ 检查系统要求
  3. ✅ 尝试解压到不同的文件夹
  4. ✅ 暂时禁用杀毒软件（某些可能会阻止它）

问题：哈希值计算时间过长

解决方案：

  1. ✅ 对于大文件（>500MB）这是正常的
  2. ✅ 请耐心等待 - 这确保了安全！
  3. ✅ 考虑拆分非常大的包

🤝 贡献

我们欢迎贡献！无论你是：

  • 🐛 发现了一个 bug
  • 💡 有一个功能想法
  • 📝 想改进文档
  • 🔧 想提交代码

请：

  1. 检查 现有问题
  2. 打开一个新问题进行讨论
  3. Fork 仓库
  4. 提交拉取请求

📄 许可证

该项目采用 Apache License 2.0 许可 - 详情请参阅 LICENSE 文件。

你可以自由地：

  • ✅ 商业使用
  • ✅ 修改
  • ✅ 分发
  • ✅ 再许可

🌟 相关项目

📞 支持与社区

需要帮助？有问题？

由 GeneralUpdate 团队用 ❤️ 制作

⬆ 返回顶部