Files

T

QWQLwToo cd2fd435a2 更新了update门户站点界面和部分功能

2026-06-26 20:17:48 +08:00

14 KiB

Raw Blame History

YMhut Box 中文项目说明

YMhut Box 是一个以 C#、.NET 和 WinUI 3 为核心的 Windows 原生工具箱项目。当前仓库同时保留了新版 WinUI 桌面端、核心工具逻辑、测试项目、辅助进程、统一管理服务、旧版 Electron 项目以及更新/反馈相关服务代码。

当前版本信息来自 version.json：

版本号：2.0.7
构建号：05
发布通道：stable

项目定位

本项目用于构建 YMhut Box 桌面工具箱，主要目标是把原有 Web/Electron 工具箱迁移到原生 Windows 桌面体验，并配套提供更新、反馈、资源管理和服务端管理能力。

核心能力包括：

WinUI 3 桌面壳、页面、窗口和托盘体验。
C#/.NET 核心工具目录、工具执行、设置、日志、反馈、下载和更新逻辑。
WebView2 内嵌页面，用于工具页、结果页、启动动画和 3D/可视化内容。
独立 Worker、插件宿主和下载宿主进程。
MSTest 单元测试。
MSIX 和传统 EXE 安装包构建流程。
Go 版本统一管理服务，兼容旧版更新 JSON、下载目录和反馈接口。
旧版 Electron 项目保留，便于历史对照和迁移。

技术栈

桌面端：

C# / .NET 10
WinUI 3
Windows App SDK
WebView2
Microsoft.Extensions.DependencyInjection
SQLite
MSTest

服务端：

Go
SQLite，部分路径支持 MySQL 配置
Vue 前端管理台和门户页
Rust WASM 辅助模块

旧版客户端：

Electron
Node.js
HTML/CSS/JavaScript

仓库结构

.
|-- src/
|   |-- box-winUI/                 # WinUI 3 桌面应用
|   |-- YMhut.Box.Core/            # 核心业务逻辑、工具系统、设置、日志、反馈、更新
|   |-- YMhut.Box.Tests/           # MSTest 测试项目
|   |-- YMhut.Box.Worker/          # 工具执行 Worker 进程
|   |-- YMhut.Box.PluginHost/      # 插件宿主进程
|   `-- YMhut.Box.DownloadHost/    # 下载宿主进程
|-- assets/                        # 图标、字体、图片、本地数据、太阳系纹理源素材
|-- server/
|   |-- unified-management/        # 统一管理服务，整合更新和反馈能力
|   |-- update/                    # 旧更新服务 Go 实现
|   `-- feedback-mailer/           # 旧反馈工单服务
|-- box-old/                       # 旧版 Electron 工具箱
|-- installer/                     # Inno Setup 安装脚本
|-- scripts/                       # 构建脚本
|-- docs/                          # 架构、贡献、迁移、插件文档
|-- update-notice/                 # 更新公告 JSON
|-- 新增工具文档/                  # 新增工具接口/需求说明
|-- build.bat                      # Windows 构建入口
|-- YMhut.Box.Native.sln           # Visual Studio 解决方案
|-- Directory.Build.props          # 统一版本注入
|-- NuGet.Config                   # NuGet 配置
|-- version.json                   # 项目版本源
`-- README.md                      # 英文简要说明

解决方案项目

YMhut.Box.Native.sln 包含以下项目：

YMhut.Box.Core：核心库，目标框架 net10.0。
YMhut.Box.WinUI：桌面主程序，目标框架 net10.0-windows10.0.19041.0。
YMhut.Box.Tests：测试项目，目标框架 net10.0。
YMhut.Box.Worker：独立工具执行进程。
YMhut.Box.PluginHost：插件宿主进程。
YMhut.Box.DownloadHost：下载宿主进程。

桌面端说明

主程序目录是 src/box-winUI/。

主要内容：

App.xaml、App.xaml.cs：应用入口和生命周期。
MainWindow.xaml、MainWindow.xaml.cs：主窗口。
Views/：主页面、设置页、工具箱页、媒体页、浏览器页、日志页、插件页等。
Views/Tools/：具体工具页面、工具注册表、工具页面基类和生成工具页。
Services/：下载、更新、托盘、启动、插件、WebView2、窗口状态等服务。
Controls/：天气、指标图表、信息条等自定义控件。
Assets/：桌面端图标、启动页、工具页 Web 资源、太阳系/地球 3D 资源。
Strings/zh-CN、Strings/en-US：中英文资源文件。

Release 构建时：

运行时标识为 win-x64。
使用 MSIX 包类型。
关闭 Appx 签名，由构建脚本处理本地证书和输出。
会复制 Worker、PluginHost、DownloadHost 输出到主程序输出目录。
会复制内置 WebView2 静态资源和工具数据。

核心库说明

核心库目录是 src/YMhut.Box.Core/。

主要模块：

Api/：API 端点和远程接口管理。
App/：应用路径、安装布局、运行时布局策略、开源参考资料。
Data/：本地参考数据加载。
DevEnvironments/：开发环境配置模型。
Downloads/：下载队列、下载模型、直接下载校验。
Feedback/：反馈码、反馈提交、反馈包加密、反馈记录。
Logging/：JSON、SQLite、弹性日志服务和日志展示本地化。
Media/：远程媒体目录、媒体解析、音量模型。
Net/：HTTP 服务和重定向解析。
Plugins/：内置插件、插件注册、插件状态和插件宿主协议。
Settings/：应用设置、语言、置顶工具、协议文档。
SolarSystem/：太阳系星历模型和服务。
Startup/：启动检查、安装完整性检查和启动初始化管线。
System/：硬件信息和系统指标。
Tools/：工具目录、工具执行、结果渲染、隐私清理、Worker 协议和布局计算。
Updates/：更新模型、版本比较、更新接口策略。

测试

测试项目在 src/YMhut.Box.Tests/。

测试覆盖方向包括：

设置读写和协议接受。
下载、开发环境、反馈服务。
安装布局、日志、媒体解析。
插件、工具目录、工具执行和 Worker。
远程工具排序、结果体验、Web payload 序列化。
敏感文本、启动检查、更新版本比较。

常用测试命令：

dotnet restore YMhut.Box.Native.sln --configfile NuGet.Config --ignore-failed-sources
dotnet test src\YMhut.Box.Tests\YMhut.Box.Tests.csproj -c Debug --no-restore

构建

推荐使用根目录的 build.bat：

build.bat --target=publish
build.bat --target=msix
build.bat --target=exe
build.bat --target=both

可选参数：

build.bat --target=both --configuration=Release --platform=x64
build.bat --target=both --skip-tests
build.bat --target=both --skip-exe
build.bat --target=exe --skip-msix

构建脚本实际入口是：

scripts\build-winui.ps1

主要输出目录：

build/winui/publish/：发布输出。
build/winui/msix-stage/：MSIX 临时目录。
build/winui/logs/：构建日志。
latest/：最新构建结果。
installer_output/：安装包、证书、更新信息。
server/update/public/downloads/：可被更新服务使用的下载包目录。

这些输出目录通常不提交到 Git。

发布和更新

构建脚本会使用以下默认地址生成下载和更新信息：

下载基础地址：https://update.ymhut.cn/downloads/
更新信息基础地址：https://update.ymhut.cn/update-info/

可通过环境变量覆盖：

$env:YMHUT_DOWNLOAD_BASE_URI="https://example.com/downloads/"
$env:YMHUT_UPDATE_BASE_URI="https://example.com/update-info/"

更新公告文件位于 update-notice/，用于维护不同版本的更新说明。

服务端

统一管理服务

server/unified-management/

它用于整合旧 server/update 和 server/feedback-mailer 的能力。

主要能力：

Go 后端，默认 SQLite。
可选 MySQL 配置。
兼容旧路由：update-info.json、tool-status.json、media-types.json、modules.json、下载文件和反馈接口。
提供 /api/client/bootstrap 客户端发现接口。
管理员登录、验证码、HttpOnly session cookie、CSRF 检查。
媒体源和数据源健康检查。
Vue 管理台、门户页和 Rust WASM 辅助模块。

运行：

cd server\unified-management
go mod tidy
go run main.go

或：

go run .\cmd\unified-management

测试：

go test ./...

默认监听地址：

:33550

常用环境变量：

YMHUT_LISTEN：监听地址。
PORT：端口，作为监听地址的简写来源。
YMHUT_BASE_URL：公开服务地址。
YMHUT_DB_PROVIDER：sqlite 或 mysql。
YMHUT_SQLITE_PATH：SQLite 数据库路径。
YMHUT_MYSQL_DSN：MySQL DSN。
YMHUT_UPDATE_PUBLIC_DIR：旧更新服务 public 目录。
YMHUT_DOWNLOADS_DIR：下载包目录。
YMHUT_SOURCE_CHECK_SECONDS：源健康检查间隔。

前端目录：

web/admin：Vue 管理台。
web/portal：Vue 公共门户。
web/setup：初始化/设置页面。
web/wasm：Rust WASM 辅助模块。

前端构建示例：

cd server\unified-management\web\admin
npm install
npm run build

cd ..\portal
npm install
npm run build

发布二进制：

cd server\unified-management
.\scripts\build-release.ps1 -Version 0.1.0

输出目录为 server/unified-management/dist-release/，该目录不提交。

更新服务

server/update/

该目录保留旧更新服务的 Go 实现，包括：

下载中心页面。
JSON API。
下载文件目录。
管理后台。
路由配置。
用户和认证模型。
静态资源和视图模板。

注意：server/update/public/downloads/ 存放安装包和 MSIX 等大文件，已在 .gitignore 中排除。

反馈服务

server/feedback-mailer/

该目录保留反馈工单服务，包括：

Go 后端。
SQLite 数据。
管理前端。
反馈包处理。
旧客户端兼容接口。

注意：config.json、生成的可执行文件和 storage/ 运行态目录已在 .gitignore 中排除。

旧版项目

旧版 Electron 项目保留在：

box-old/

它包含：

Electron 主进程和 preload。
旧版 Web UI。
旧版工具实现。
旧版工具状态和更新信息。
旧构建脚本和安装配置。

该目录主要用于历史保留、迁移参考和功能对照。

资源

资源目录：

assets/

主要内容：

icons/：应用图标。
images/：图片资源。
fonts/：字体资源。
data/：本地数据，如行政区划、三国杀皮肤配置、参考数据。
source-textures/solar/：太阳系纹理源文件。

桌面端运行时还会从 src/box-winUI/Assets/ 加载应用内静态资源，包括：

启动画面。
工具页 Web 资源。
工具结果页 Web 资源。
home globe 和太阳系可视化资源。

Git 和 Gitea 推送

当前远端仓库地址：

http://admin_gitea@git.ymhut.cn/admin_gitea/YMhut-box-C-.git

常用提交流程：

git status
git add .
git commit -m "提交说明"
git push

查看远端：

git remote -v

如果提示需要登录，请使用 Gitea 账号登录。不要把密码写进远端 URL，也不要把密码写进文档或提交记录。

如果 Git 使用了错误的缓存凭据，可以清理该站点凭据后重新推送：

@"
protocol=http
host=git.ymhut.cn

"@ | git credential reject

git push

不应提交的内容

.gitignore 已排除常见缓存、构建产物、运行态数据和大安装包。

主要包括：

.cache/
.codex/
.codex_state/
.agents/
.tmp/
.idea/
.vs/
build/
latest/
installer_output/
Release/
node_modules/
dist/
bin/
obj/
src/box-winUI/AppPackages/
server/update/build/
server/update/public/downloads/
server/unified-management/dist-release/
server/unified-management/storage/
server/feedback-mailer/storage/
server/feedback-mailer/config.json

如果执行 git status --ignored 看到这些路径前面是 !!，表示它们已被忽略，这是正常现象。

常见状态说明

git status 显示：

Your branch is up to date with 'origin/main'.

表示本地分支和远端分支同步。

显示：

Changes not staged for commit

表示有文件已修改，但还没有执行 git add。

显示：

LF will be replaced by CRLF

这是 Windows 换行提示，不是错误。它表示 Git 可能在工作区把 LF 换行转换成 CRLF。

显示：

Everything up-to-date

表示没有新的本地提交需要推送。

本地开发建议

推荐流程：

git pull
dotnet restore YMhut.Box.Native.sln --configfile NuGet.Config --ignore-failed-sources
dotnet build src\box-winUI\YMhut.Box.WinUI.csproj -c Debug -p:Platform=x64 --no-restore
dotnet test src\YMhut.Box.Tests\YMhut.Box.Tests.csproj -c Debug --no-restore

服务端开发：

cd server\unified-management
go test ./...
go run main.go

前端管理台开发：

cd server\unified-management\web\admin
npm install
npm run dev

门户页开发：

cd server\unified-management\web\portal
npm install
npm run dev

维护注意事项

修改版本号时优先更新 version.json，构建时会通过 Directory.Build.props 注入程序集版本。
提交前先看 git status，确认没有缓存、构建产物和本地数据库混入。
发布安装包、MSIX、下载包建议走构建脚本输出目录，不直接手动放入源码提交。
服务端默认账号、数据库路径、生产密钥和密码不要写入仓库。
大文件如果确实需要进入仓库，建议分批提交和推送，避免 HTTP 413。

许可证

仓库包含 LICENSE，当前为 GNU General Public License v3.0 文本。

14 KiB Raw Blame History Unescape Escape