ShaoHua
d53828c150
### 新增功能 - **Linux 官方支持**：新增 Hua.Todo.Avalonia 项目，正式适配 Linux 平台，同时支持 Windows 和 macOS - **Avalonia 桌面交互**：增加托盘菜单（显示/退出）、关闭隐藏到托盘、Windows 全局热键唤起主窗口、热键配置本地持久化 - **SQLite DateTime 兼容修复**：新增 LenientUtcDateTimeStringConverter，解决历史遗留的 DateTime 脏数据解析问题 - **用户文档完善**：新增 docs/manual/新手指南.md 和 docs/manual/用户指南.md - **部署文档**：新增 docs/manual/部署文档.md，详细说明多平台发布流程 ### 优化与修复 - **发布脚本整理**：拆分/对齐各平台发布入口，新增 publish.ps1 作为统一入口 - **Windows WebView2 优化**：数据目录调整到 %LocalAppData%\Hua.Todo\WebView2，修复 Runtime 误判问题 - **MAUI 多平台构建**：在 Windows 开发机上默认仅构建 Android + Windows 目标 - **SPA 路由回落**：修复 Release 模式下 /swagger 路径的 404 问题 - **Swagger 输出**：补齐 Dynamic API 端点，避免接口缺失 ### 文档更新 - **版本记录**：更新 v1.2.0 开发进度和功能列表 - **技术设计文档**：添加 Avalonia 项目架构和模块设计 - **项目结构**：更新 README.md 中的项目结构说明 ### 其他变更 - 新增 Directory.Build.props 和更新 Directory.Build.targets - 调整 src/Hua.Todo.Avalonia 项目配置和资源文件 - 更新 src/Hua.Todo.Web 前端资源文件 - 修复 src/Hua.Todo.Maui 相关配置和打包脚本
129 lines
4.2 KiB
Markdown
129 lines
4.2 KiB
Markdown
# Hua.Todo 构建与部署手册
|
||
|
||
本文档提供 Hua.Todo 项目的版本构建指南与多平台部署流程，侧重于如何产出可分发的版本并将其安装或部署到目标机器。
|
||
|
||
## 1. 🏗️ 版本构建流程 (Release Build)
|
||
|
||
在进行任何部署之前，必须先通过自动化脚本构建出 Release 版本的产物。
|
||
|
||
### 1.1 前提要求
|
||
|
||
- **环境检查**：已安装 .NET 10 SDK、Node.js 18+ 以及 Inno Setup 6（仅 Windows 打包需要）。
|
||
- **脚本入口**：位于根目录的 `publish.ps1` 系列脚本。
|
||
|
||
### 1.2 执行构建
|
||
|
||
根据目标平台执行对应的构建命令：
|
||
|
||
- **全平台一键构建**：
|
||
```powershell
|
||
.\publish.ps1 -Windows -Linux
|
||
```
|
||
- **Windows 版本构建**：
|
||
```powershell
|
||
.\publish-windows.ps1
|
||
```
|
||
- **Linux 版本构建**：
|
||
```powershell
|
||
.\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)
|
||
|
||
1. **分发文件**：将 `hua.todo-{version}-win-x64-setup.exe` 提供给终端用户。
|
||
2. **安装流程**：用户运行安装程序，程序将自动：
|
||
- 安装到 `%ProgramFiles%\Hua.Todo`（或用户自定义路径）。
|
||
- 创建桌面与开始菜单快捷方式。
|
||
- 写入注册表以支持卸载。
|
||
3. **静默安装**：支持 Inno Setup 标准静默参数 `/VERYSILENT /SUPPRESSMSGBOXES`。
|
||
|
||
### 2.2 绿色版部署
|
||
|
||
1. **分发文件**：将 `artifacts\windows\win-x64\publish\` 文件夹整体打包。
|
||
2. **运行要求**：目标机器需安装 **WebView2 Runtime**。
|
||
3. **启动程序**：运行 `Hua.Todo.Maui.exe`。
|
||
|
||
***
|
||
|
||
## 3. 🐧 Linux 客户端部署
|
||
|
||
目前提供基于 Avalonia 的 Linux 交付版本，采用 `.tar.gz` 压缩包形式。
|
||
|
||
### 3.1 解压部署
|
||
|
||
1. **解压**：
|
||
```bash
|
||
tar -xzf hua.todo-{version}-linux-x64.tar.gz -C /opt/hua-todo
|
||
```
|
||
2. **运行环境**：
|
||
- 确保系统安装了 `libwebkit2gtk-4.0-37`。
|
||
- 如果构建时未开启 `-SelfContained`，则需安装 .NET 10 Runtime。
|
||
3. **权限设置**：
|
||
```bash
|
||
chmod +x /opt/hua-todo/Hua.Todo.Avalonia
|
||
```
|
||
4. **启动**：直接运行 `/opt/hua-todo/Hua.Todo.Avalonia`。
|
||
|
||
***
|
||
|
||
## 4. ☁️ 云同步服务端部署 (Server)
|
||
|
||
`Hua.Todo.Host` 可作为中心服务端部署，用于任务的云端同步。
|
||
|
||
### 4.1 Docker 部署 (Recommended)
|
||
|
||
1. **上传代码**或将 `src/Hua.Todo.Host/Dockerfile` 复制到服务器。
|
||
2. **构建与启动**：
|
||
```bash
|
||
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)
|
||
|
||
1. **构建 Host**：`dotnet publish src/Hua.Todo.Host -c Release -o ./dist`。
|
||
2. **同步产物**：将 `./dist` 内容同步到服务器。
|
||
3. **配置 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` 给主程序执行权限。
|
||
|