# 安装指南

> 本文档介绍如何安装和使用 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)。