Files

T

ShaoHua 14868c45c7 feat: 实现v1.2.0云同步与实体重构核心功能

1.  重构用户与任务实体：UserEntity实现IUser<Guid>，TaskEntity继承ABP风格FullAuditedEntityWithUser，主键从int改为Guid
2.  新增云同步代理系统：嵌入式WebServer支持CloudSyncProxy转发云同步请求，新增配置API与持久化
3.  完善前端适配：新增Guid工具函数，更新任务类型定义与API交互逻辑，调整云同步设置弹窗适配本地代理
4.  文档与配置优化：更新文档结构，新增部署文档、版本记录，统一各项目配置项
5.  补充测试与迁移：新增单元测试，更新EF Core数据库迁移快照

2026-06-14 04:51:22 +08:00

4.2 KiB

Raw Blame History

Hua.Todo 构建与部署手册

本文档提供 Hua.Todo 项目的版本构建指南与多平台部署流程，侧重于如何产出可分发的版本并将其安装或部署到目标机器。

1. 🏗️ 版本构建流程 (Release Build)

在进行任何部署之前，必须先通过自动化脚本构建出 Release 版本的产物。

1.1 前提要求

环境检查：已安装 .NET 10 SDK、Node.js 18+ 以及 Inno Setup 6（仅 Windows 打包需要）。
脚本入口：位于根目录的 publish.ps1 系列脚本。

1.2 执行构建

根据目标平台执行对应的构建命令：

全平台一键构建：
```
.\publish.ps1 -Windows -Linux
```
Windows 版本构建：
```
.\publish-windows.ps1
```

Linux 版本构建：

.\publish-linux.ps1 -RuntimeIdentifier linux-x64 -SelfContained

1.3 产物输出位置

所有构建产物将按平台归类在根目录的 artifacts/ 文件夹下：

Windows: artifacts\windows\win-x64\installer\ (安装包) 与 publish\ (解压即用版)
Linux: artifacts\linux\linux-x64\ (.tar.gz 压缩包)

2. 🪟 Windows 客户端部署

2.1 安装包分发 (Recommended)

分发文件：将 hua.todo-{version}-win-x64-setup.exe 提供给终端用户。
安装流程：用户运行安装程序，程序将自动：
- 安装到 %ProgramFiles%\Hua.Todo（或用户自定义路径）。
- 创建桌面与开始菜单快捷方式。
- 写入注册表以支持卸载。
静默安装：支持 Inno Setup 标准静默参数 /VERYSILENT /SUPPRESSMSGBOXES。

2.2 绿色版部署

分发文件：将 artifacts\windows\win-x64\publish\ 文件夹整体打包。
运行要求：目标机器需安装 WebView2 Runtime。
启动程序：运行 Hua.Todo.Maui.exe。

3. 🐧 Linux 客户端部署

目前提供基于 Avalonia 的 Linux 交付版本，采用 .tar.gz 压缩包形式。

3.1 解压部署

解压：

tar -xzf hua.todo-{version}-linux-x64.tar.gz -C /opt/hua-todo

运行环境：
- 确保系统安装了 libwebkit2gtk-4.0-37。
- 如果构建时未开启 -SelfContained，则需安装 .NET 10 Runtime。

权限设置：

chmod +x /opt/hua-todo/Hua.Todo.Avalonia

启动：直接运行 /opt/hua-todo/Hua.Todo.Avalonia。

4. ☁️ 云同步服务端部署 (Server)

Hua.Todo.Host 可作为中心服务端部署，用于任务的云端同步。

4.1 Docker 部署 (Recommended)

上传代码或将 src/Hua.Todo.Host/Dockerfile 复制到服务器。

构建与启动：

docker build -t hua-todo-server -f src/Hua.Todo.Host/Dockerfile .
docker run -d \
  --name hua-todo-server \
  -p 5173:5173 \
  -v /data/hua-todo/db:/app/data \
  -e ASPNETCORE_ENVIRONMENT=Production \
  hua-todo-server

4.2 直接部署 (Binary)

构建 Host：dotnet publish src/Hua.Todo.Host -c Release -o ./dist。
同步产物：将 ./dist 内容同步到服务器。
配置 Systemd 服务（可选）：创建一个 hua-todo.service 文件，指向可执行程序并设置工作目录。

5. ⚙️ 关键配置校准

5.1 数据持久化

SQLite 路径：客户端数据默认存储在用户目录下的 Hua.Todo/todo.db；服务端数据存储在容器挂载卷或指定 appsettings.json 的连接字符串中。
备份建议：定期备份 todo.db 文件。

5.2 端口与访问

客户端本地端口：默认 5057。如果被占用，可在 appsettings.json 中修改 WebServer.HostUrl。
服务端访问：确保服务端防火墙已开放对应的 API 端口（默认 5173）。

6. 🛠️ 常见问题排查

客户端无法加载 UI：检查目标机器是否安装了 WebView2 Runtime（Windows）或 WebKitGTK（Linux）。
同步连接失败：
1. 确认服务端 API 是否可达（访问 /swagger 验证）。
2. 确认客户端配置的服务端地址格式（需包含 http:// 或 https://）。
权限问题：在 Linux 下运行前，务必执行 chmod +x 给主程序执行权限。

4.2 KiB Raw Blame History Unescape Escape