zclaw_openfang/docs/deployment/windows.md

# Windows 部署指南

本指南详细说明 ZCLAW 在 Windows 平台上的部署流程。

## 系统要求

| 组件 | 最低要求 | 推荐配置 |
|------|---------|---------|
| 操作系统 | Windows 10 64-bit (1809+) | Windows 11 64-bit |
| 处理器 | Intel Core i5 / AMD Ryzen 5 | Intel Core i7 / AMD Ryzen 7 |
| 内存 | 8 GB | 16 GB |
| 磁盘空间 | 500 MB | 1 GB |
| 网络 | 宽带连接 | 稳定宽带 |

## 构建步骤

### 1. 准备构建环境

```powershell
# 安装 Rust (如果未安装)
winget install Rustlang.Rust.MSVC

# 安装 Node.js (如果未安装)
winget install OpenJS.NodeJS.LTS

# 安装 pnpm
npm install -g pnpm

# 验证安装
rustc --version
node --version
pnpm --version
```

### 2. 获取源代码

```powershell
git clone <repository-url>
cd ZCLAW
```

### 3. 安装依赖

```powershell
# 根目录依赖
pnpm install

# 桌面端依赖
cd desktop
pnpm install
```

### 4. 执行构建

```powershell
cd desktop

# 开发构建（快速）
pnpm tauri:dev

# 生产构建
pnpm tauri:build

# 完整打包（包含运行时）
pnpm tauri:build:bundled
```

### 5. 查看构建产物

```powershell
# 可执行文件
dir src-tauri\target\release\ZClaw.exe

# NSIS 安装包
dir src-tauri\target\release\bundle\nsis\
```

## 安装选项

### NSIS 安装包

**优点**：
- 自动处理依赖
- 创建开始菜单快捷方式
- 支持卸载

**步骤**：
1. 双击 `ZCLAW-Setup-{version}-x64.exe`
2. 选择安装位置（默认：`C:\Program Files\ZCLAW`）
3. 选择是否创建桌面快捷方式
4. 点击「安装」
5. 完成后启动 ZCLAW

### 便携版

**优点**：
- 无需安装
- 可放在 U 盘运行
- 不修改系统设置

**步骤**：
1. 复制以下文件到目标目录：
   - `ZClaw.exe`
   - `resources/` 目录（如有）
2. 双击 `ZClaw.exe` 运行

## 配置

### 用户数据目录

ZCLAW 在以下位置存储用户数据：

```
%USERPROFILE%\.openfang\
├── openfang.toml     # 主配置文件
├── .env              # 环境变量（可选）
├── data/
│   └── openfang.db   # SQLite 数据库
└── logs/
    └── app.log       # 应用日志
```

### 防火墙配置

如果遇到网络问题，请确保 ZCLAW 可以通过 Windows 防火墙：

1. 打开「Windows Defender 防火墙」
2. 点击「允许应用通过防火墙」
3. 点击「更改设置」→「允许其他应用」
4. 添加 `ZClaw.exe`
5. 确保勾选「专用」和「公用」

### 杀毒软件排除

某些杀毒软件可能误报，建议添加排除项：

**Windows Defender**：
1. 打开「Windows 安全中心」
2. 选择「病毒和威胁防护」
3. 点击「管理设置」
4. 滚动到「排除项」→「添加或删除排除项」
5. 添加 ZCLAW 安装目录

## 常见问题

### 启动闪退

**可能原因**：
1. 缺少 Visual C++ 运行库
2. 配置文件损坏
3. 端口被占用

**解决方案**：
```powershell
# 安装 VC++ 运行库
winget install Microsoft.VCRedist.2015+.x64

# 重置配置
Remove-Item -Recurse -Force "$env:USERPROFILE\.openfang"

# 检查端口占用
netstat -ano | findstr :50051
```

### 更新后无法启动

**解决方案**：
1. 完全卸载旧版本
2. 删除 `%LOCALAPPDATA%\ZClaw` 目录
3. 重新安装新版本

### 权限问题

**症状**：无法保存设置

**解决方案**：
```powershell
# 检查目录权限
icacls "$env:USERPROFILE\.openfang"

# 修复权限
icacls "$env:USERPROFILE\.openfang" /grant:r "%USERNAME%:(OI)(CI)F"
```

## 卸载

### 通过安装程序卸载

1. 打开「设置」→「应用」→「已安装的应用」
2. 找到 ZCLAW
3. 点击「卸载」

### 手动卸载

1. 删除安装目录（默认：`C:\Program Files\ZCLAW`）
2. 删除用户数据（可选）：
   ```powershell
   Remove-Item -Recurse -Force "$env:USERPROFILE\.openfang"
   ```
3. 删除快捷方式

## 性能优化

### 启动速度

```powershell
# 禁用开机自启（如果不需要）
# 在任务管理器 → 启动 中禁用 ZCLAW
```

### 内存使用

- 关闭不使用的对话标签页
- 定期清理历史记录
- 减少保留的上下文长度

## 日志收集

用于问题排查：

```powershell
# 查看最新日志
Get-Content "$env:USERPROFILE\.openfang\logs\app.log" -Tail 50

# 导出日志
Copy-Item "$env:USERPROFILE\.openfang\logs" -Destination "C:\temp\zclaw-logs" -Recurse
```