d0ae7d2770
Multi-stage Docker build for zclaw-saas with dependency caching, environment variable template with security defaults, Nginx reverse proxy with SSE/WebSocket support and HTTPS, and comprehensive Chinese-language production deployment documentation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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. 安装依赖
# 克隆仓库
git clone <repository-url>
cd ZCLAW
# 安装根目录依赖
pnpm install
# 安装桌面端依赖
cd desktop
pnpm install
2. 开发模式
# 从根目录启动开发环境
pnpm start:dev
# 或仅启动桌面端
cd desktop
pnpm tauri:dev
3. 生产构建
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 安装包（推荐）
- 下载
ZCLAW-Setup-{version}.exe - 双击运行安装程序
- 按照向导完成安装
- 首次启动时配置 API Key
便携版
- 复制
ZClaw.exe及相关文件 - 放置到任意目录
- 直接运行
ZClaw.exe
配置说明
配置文件位置
| 文件 | 位置 |
|---|---|
| 主配置 | %USERPROFILE%\.zclaw\zclaw.toml |
| 环境变量 | %USERPROFILE%\.zclaw\.env |
| 数据库 | %USERPROFILE%\.zclaw\data\zclaw.db |
| 日志 | %USERPROFILE%\.zclaw\logs\ |
首次启动配置
- 启动 ZCLAW
- 进入「设置」→「模型与 API」
- 选择 LLM 提供商
- 输入 API Key
- 选择默认模型
- 点击「保存」
环境变量（可选）
参考 .env.example 文件：
# 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. 启动失败
症状：双击图标后无响应
解决方案：
- 检查是否被杀毒软件拦截
- 检查端口 50051 是否被占用
- 查看日志文件
logs/error.log
2. API 连接失败
症状：发送消息后无响应
解决方案：
- 检查网络连接
- 验证 API Key 是否有效
- 检查 API 端点配置
3. 数据库错误
症状：无法保存设置或历史记录
解决方案：
- 检查数据目录权限
- 备份后删除
data/zclaw.db - 重启应用
日志收集
# 查看最新日志
type %USERPROFILE%\.zclaw\logs\app.log | more
更新流程
手动更新
- 下载最新版本安装包
- 关闭正在运行的 ZCLAW
- 运行新版本安装程序
- 启动 ZCLAW
数据迁移
配置和数据存储在用户目录，更新时自动保留。
安全建议
- API Key 保护：不要分享 API Key
- 定期备份：备份
.zclaw目录 - 网络隔离：建议在可信网络使用
- 权限控制：限制对配置目录的访问
技术支持
- 文档：
docs/ - 故障排查：
docs/knowledge-base/troubleshooting.md - 用户手册：
docs/USER_MANUAL.md