ShaoHua
65cee20006
- 新增 00-目录与导读.md 双入口导航 - 用户面(01-04)：项目介绍、安装指南、版本记录、其他信息 - 开发者面(05-10)：技术栈、构建、架构、云同步、代码规范、MCP - 拆分旧01为 01(用户)+05(开发者)；旧02为 02(用户)+06(开发者) - 合并旧08+09 MCP文档为 10-MCP服务集成 - 同步更新 README.md 与 .trae/rules/项目/ 交叉引用
109 lines
2.6 KiB
Markdown
109 lines
2.6 KiB
Markdown
# 安装指南
|
||
|
||
> 本文档介绍如何安装和使用 Hua.Todo 客户端，以及如何部署云同步服务端。
|
||
|
||
---
|
||
|
||
## 1. Windows 安装
|
||
|
||
### 1.1 安装包（推荐）
|
||
|
||
1. 下载 `Hua.Todo_Setup_vX.Y.Z.exe`
|
||
2. 运行安装程序，按向导完成安装
|
||
3. 安装完成后会在桌面和开始菜单创建快捷方式
|
||
|
||
> 静默安装：`Hua.Todo_Setup_vX.Y.Z.exe /VERYSILENT /SUPPRESSMSGBOXES`
|
||
|
||
### 1.2 绿色版
|
||
|
||
1. 下载绿色版压缩包并解压
|
||
2. 确保系统已安装 [WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2/)
|
||
3. 运行 `Hua.Todo.Maui.exe`
|
||
|
||
---
|
||
|
||
## 2. Linux 安装
|
||
|
||
### 2.1 解压部署
|
||
|
||
```bash
|
||
tar -xzf hua.todo-{version}-linux-x64.tar.gz -C /opt/hua-todo
|
||
```
|
||
|
||
### 2.2 环境依赖
|
||
|
||
- 确保系统安装了 `libwebkit2gtk-4.0-37`
|
||
- 如果版本未自带 .NET Runtime，需安装 .NET 10 Runtime
|
||
|
||
### 2.3 启动
|
||
|
||
```bash
|
||
chmod +x /opt/hua-todo/Hua.Todo.Avalonia
|
||
/opt/hua-todo/Hua.Todo.Avalonia
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 云同步服务端部署
|
||
|
||
如需使用云同步功能，需要部署 `Hua.Todo.Host` 服务端。
|
||
|
||
### 3.1 Docker 部署（推荐）
|
||
|
||
```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
|
||
```
|
||
|
||
### 3.2 直接部署
|
||
|
||
```bash
|
||
dotnet publish src/Hua.Todo.Host -c Release -o ./dist
|
||
# 将 ./dist 内容同步到服务器
|
||
# 可选：配置 Systemd 服务
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 配置云同步
|
||
|
||
1. 打开 Hua.Todo → 点击"云同步设置"
|
||
2. 输入服务端地址（如 `http://your-server:5173`）
|
||
3. 点击"保存并探测"确认可达
|
||
4. 输入用户名和密码登录
|
||
5. 登录成功后即可使用同步功能
|
||
|
||
---
|
||
|
||
## 5. 关键配置
|
||
|
||
### 5.1 数据位置
|
||
|
||
- **客户端**：数据默认存储在用户目录 `Hua.Todo/todo.db`
|
||
- **服务端**：数据存储在容器挂载卷或数据库连接字符串指定位置
|
||
|
||
### 5.2 端口
|
||
|
||
- 客户端本地端口默认 `5057`，可在 `appsettings.json` 中修改
|
||
- 服务端端口默认 `5173`
|
||
|
||
---
|
||
|
||
## 6. 常见问题
|
||
|
||
| 问题 | 解决方法 |
|
||
|---|---|
|
||
| Windows 客户端无法加载 UI | 安装 [WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2/) |
|
||
| Linux 客户端无法启动 | 安装 `libwebkit2gtk-4.0-37`；执行 `chmod +x` |
|
||
| 同步连接失败 | 确认服务端可达（访问 `/swagger`）；确认地址格式含 `http://` 或 `https://` |
|
||
| 端口被占用 | 修改 `appsettings.json` 中的 `WebServer.HostUrl` |
|
||
|
||
---
|
||
|
||
> 开发者如需从源码构建，见 [06-开发环境与构建](./06-开发环境与构建.md)。
|