# ZCLAW 部署指南

本指南涵盖 ZCLAW 桌面应用的部署流程。

## 目录

- [系统要求](#系统要求)
- [构建流程](#构建流程)
- [安装方式](#安装方式)
- [配置说明](#配置说明)
- [故障排查](#故障排查)

## 系统要求

### 开发环境

| 组件 | 最低版本 | 推荐版本 |
|------|---------|---------|
| Node.js | 18.x | 20.x |
| pnpm | 8.x | 9.x |
| Rust | 1.70 | 1.80+ |
| Windows | 10 64-bit | 11 64-bit |

### 运行时环境

| 组件 | 要求 |
|------|------|
| 操作系统 | Windows 10/11 64-bit |
| 内存 | 8GB+ (推荐 16GB) |
| 磁盘空间 | 500MB+ |
| 网络 | 需要访问 LLM API |

## 构建流程

### 1. 安装依赖

```bash
# 克隆仓库
git clone <repository-url>
cd ZCLAW

# 安装根目录依赖
pnpm install

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

### 2. 开发模式

```bash
# 从根目录启动开发环境
pnpm start:dev

# 或仅启动桌面端
cd desktop
pnpm tauri:dev
```

### 3. 生产构建

```bash
cd desktop

# 标准构建
pnpm tauri:build

# 打包构建（包含运行时）
pnpm tauri:build:bundled
```

构建产物位于：
- `desktop/src-tauri/target/release/ZClaw.exe` - 可执行文件
- `desktop/src-tauri/target/release/bundle/nsis/` - NSIS 安装包

## 安装方式

### NSIS 安装包（推荐）

1. 下载 `ZCLAW-Setup-{version}.exe`
2. 双击运行安装程序
3. 按照向导完成安装
4. 首次启动时配置 API Key

### 便携版

1. 复制 `ZClaw.exe` 及相关文件
2. 放置到任意目录
3. 直接运行 `ZClaw.exe`

## 配置说明

### 配置文件位置

| 文件 | 位置 |
|------|------|
| 主配置 | `%USERPROFILE%\.openfang\openfang.toml` |
| 环境变量 | `%USERPROFILE%\.openfang\.env` |
| 数据库 | `%USERPROFILE%\.openfang\data\openfang.db` |
| 日志 | `%USERPROFILE%\.openfang\logs\` |

### 首次启动配置

1. 启动 ZCLAW
2. 进入「设置」→「模型与 API」
3. 选择 LLM 提供商
4. 输入 API Key
5. 选择默认模型
6. 点击「保存」

### 环境变量（可选）

参考 `.env.example` 文件：

```env
# AI Provider
ZCLAW_AI_PROVIDER=zhipu
ZCLAW_ZHIPU_API_KEY=your-api-key
ZCLAW_DEFAULT_MODEL=glm-4-flash

# Database
ZCLAW_DB_PATH=./data/zclaw.db
```

## 故障排查

### 常见问题

#### 1. 启动失败

**症状**：双击图标后无响应

**解决方案**：
1. 检查是否被杀毒软件拦截
2. 检查端口 50051 是否被占用
3. 查看日志文件 `logs/error.log`

#### 2. API 连接失败

**症状**：发送消息后无响应

**解决方案**：
1. 检查网络连接
2. 验证 API Key 是否有效
3. 检查 API 端点配置

#### 3. 数据库错误

**症状**：无法保存设置或历史记录

**解决方案**：
1. 检查数据目录权限
2. 备份后删除 `data/zclaw.db`
3. 重启应用

### 日志收集

```bash
# 查看最新日志
type %USERPROFILE%\.openfang\logs\app.log | more
```

## 更新流程

### 手动更新

1. 下载最新版本安装包
2. 关闭正在运行的 ZCLAW
3. 运行新版本安装程序
4. 启动 ZCLAW

### 数据迁移

配置和数据存储在用户目录，更新时自动保留。

## 安全建议

1. **API Key 保护**：不要分享 API Key
2. **定期备份**：备份 `.openfang` 目录
3. **网络隔离**：建议在可信网络使用
4. **权限控制**：限制对配置目录的访问

## 技术支持

- 文档：`docs/`
- 故障排查：`docs/knowledge-base/troubleshooting.md`
- 用户手册：`docs/USER_MANUAL.md`