0d4fa96b82
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
重构所有代码和文档中的项目名称，将OpenFang统一更新为ZCLAW。包括： - 配置文件中的项目名称 - 代码注释和文档引用 - 环境变量和路径 - 类型定义和接口名称 - 测试用例和模拟数据 同时优化部分代码结构，移除未使用的模块，并更新相关依赖项。
189 lines
3.4 KiB
Markdown
189 lines
3.4 KiB
Markdown
# 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%\.zclaw\zclaw.toml` |
|
||
| 环境变量 | `%USERPROFILE%\.zclaw\.env` |
|
||
| 数据库 | `%USERPROFILE%\.zclaw\data\zclaw.db` |
|
||
| 日志 | `%USERPROFILE%\.zclaw\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%\.zclaw\logs\app.log | more
|
||
```
|
||
|
||
## 更新流程
|
||
|
||
### 手动更新
|
||
|
||
1. 下载最新版本安装包
|
||
2. 关闭正在运行的 ZCLAW
|
||
3. 运行新版本安装程序
|
||
4. 启动 ZCLAW
|
||
|
||
### 数据迁移
|
||
|
||
配置和数据存储在用户目录，更新时自动保留。
|
||
|
||
## 安全建议
|
||
|
||
1. **API Key 保护**：不要分享 API Key
|
||
2. **定期备份**：备份 `.zclaw` 目录
|
||
3. **网络隔离**：建议在可信网络使用
|
||
4. **权限控制**：限制对配置目录的访问
|
||
|
||
## 技术支持
|
||
|
||
- 文档：`docs/`
|
||
- 故障排查：`docs/knowledge-base/troubleshooting.md`
|
||
- 用户手册：`docs/USER_MANUAL.md`
|