zclaw_openfang/docs/deployment/hospital-deployment.md

ZCLAW 医院部署指南

面向：医院 IT 管理员

本文档面向医院信息科/IT 部门的技术人员，提供 ZCLAW 在医院环境中的完整部署方案。

---

目录

1. 部署概述
2. 系统与网络要求
3. 桌面端安装与分发
4. SaaS 后端部署（可选）
5. 数据安全与隐私合规
6. 日志与排错
7. 配置参考

---

1. 部署概述

1.1 架构说明

ZCLAW 采用 Tauri 桌面应用架构，核心能力集成在客户端内部：

┌─────────────────────────────────────────────────────────────────┐
│                       ZCLAW 桌面应用                             │
├─────────────────────────────────────────────────────────────────┤
│  React 前端              │  Tauri 后端 (Rust)                    │
│  ├─ UI 组件              │  ├─ zclaw-kernel (核心)                │
│  ├─ Zustand 状态管理     │  ├─ LLM Drivers (多模型驱动)          │
│  └─ KernelClient         │  └─ SQLite (本地存储)                 │
└─────────────────────────────────────────────────────────────────┘
         │                                    │
         │  HTTPS 出站                         │  可选
         ▼                                    ▼
    LLM API 服务                         SaaS 后端 (Axum)
    (智谱/千问/DeepSeek 等)              PostgreSQL

1.2 部署模式

模式	适用场景	组件	说明
纯客户端模式	小规模（< 50 人）	仅桌面端	AI 服务直连 LLM API，数据存本地 SQLite
SaaS 模式	中大规模（50+ 人）	桌面端 + SaaS 后端	集中管理用户、配额、审计日志

建议： 大多数医院初期可使用纯客户端模式，后续按需部署 SaaS 后端。

1.3 部署检查清单

[ ] 确认部署模式（纯客户端 / SaaS）
[ ] 网络出口白名单已配置
[ ] 桌面端安装包已准备
[ ] LLM API 凭据已获取
[ ] （SaaS 模式）服务器已准备
[ ] （SaaS 模式）PostgreSQL 已部署
[ ] （SaaS 模式）域名与 SSL 证书已准备
[ ] 终端用户安装指南已分发

---

2. 系统与网络要求

2.1 终端电脑要求

组件	最低要求	推荐配置
操作系统	Windows 10 64-bit (版本 1809+)	Windows 11 64-bit
处理器	双核心 x64	四核心 x64
内存	8 GB	16 GB
磁盘空间	500 MB	1 GB SSD
WebView2	自带（Tauri 内置）	Edge WebView2 Runtime

注意： ZCLAW 内置 WebView2 Runtime，无需单独安装 Microsoft Edge。

2.2 网络出站要求

ZCLAW 桌面端需要访问外部 LLM API 服务。以下域名需要加入防火墙白名单：

LLM 服务商	域名	用途
智谱 GLM	open.bigmodel.cn	默认推荐（国内服务）
通义千问	dashscope.aliyuncs.com	备选
DeepSeek	api.deepseek.com	备选
Kimi/Moonshot	api.kimi.com	备选
OpenAI	api.openai.com	需特殊网络条件

端口要求：

方向	端口	协议	说明
出站	443	HTTPS	LLM API 通信
出站	80	HTTP	证书验证（可选）

2.3 SaaS 后端服务器要求（仅 SaaS 模式）

组件	最低要求	推荐配置
CPU	2 核	4 核
内存	4 GB	8 GB
磁盘	40 GB	100 GB SSD
操作系统	Ubuntu 22.04 / CentOS 8+	Ubuntu 24.04 LTS
Docker	24.0+	最新稳定版
Docker Compose	v2.0+	最新稳定版

---

3. 桌面端安装与分发

3.1 安装包说明

ZCLAW 桌面端提供以下安装格式：

格式	文件名模式	适用场景
NSIS 安装包	ZCLAW-Setup-{version}-x64.exe	标准安装（推荐）
便携版	ZClaw.exe + resources/	无需安装，U 盘运行

3.2 单机安装

标准安装步骤：

1. 双击 ZCLAW-Setup-{version}-x64.exe
2. 安装向导引导完成（默认安装到 C:\Program Files\ZCLAW）
3. 桌面创建快捷方式

安装完成后进行模型配置：

1. 启动 ZCLAW
2. 点击左下角"设置" -> "模型与 API"
3. 点击"添加自定义模型"
4. 填入配置：

字段	值（以智谱 GLM 为例）
服务商	智谱 GLM
模型 ID	glm-4-flash
API Key	由 IT 部门统一申请
Base URL	https://open.bigmodel.cn/api/paas/v4

5. 点击"设为默认"

3.3 批量安装方案

方案 A：MSI 静默安装

# NSIS 安装包支持静默安装参数
# 在管理员 PowerShell 中执行：
Start-Process -Wait -FilePath "ZCLAW-Setup-0.1.0-x64.exe" -ArgumentList "/S"

方案 B：组策略分发（GPO）

1. 将 NSIS 安装包放到网络共享目录，如 \\fileserver\software\ZCLAW\
2. 打开"组策略管理"控制台
3. 创建新的 GPO 或编辑现有 GPO
4. 导航到：计算机配置 -> 策略 -> 软件设置 -> 软件安装
5. 右键 -> 新建 -> 程序包
6. 选择网络共享中的安装包
7. 部署模式选择"已分配"
8. 将 GPO 链接到目标 OU

方案 C：SCCM / Intune 分发

参数	值
安装命令	ZCLAW-Setup-0.1.0-x64.exe /S
卸载命令	C:\Program Files\ZCLAW\uninstall.exe /S
检测规则	文件存在：C:\Program Files\ZCLAW\ZClaw.exe
安装行为	系统上下文

方案 D：登录脚本

@echo off
REM ZCLAW 安装检查脚本 -- 放到登录脚本或启动脚本中

set "INSTALL_PATH=C:\Program Files\ZCLAW\ZClaw.exe"
set "SETUP_PATH=\\fileserver\software\ZCLAW\ZCLAW-Setup-0.1.0-x64.exe"

if not exist "%INSTALL_PATH%" (
    echo Installing ZCLAW...
    start /wait "" "%SETUP_PATH%" /S
    echo ZCLAW installed successfully.
) else (
    echo ZCLAW already installed.
)

3.4 预配置模型（批量部署推荐）

批量部署时，建议预先配置好模型设置，避免每个用户手动操作。

用户配置文件位置：

%USERPROFILE%\.zclaw\zclaw.toml

可以通过以下方式预配置：

1. 在一台电脑上完成 ZCLAW 安装和模型配置
2. 将 %USERPROFILE%\.zclaw\zclaw.toml 复制为模板
3. 在批量安装脚本中，安装完成后自动复制模板到每个用户的 .zclaw 目录

# 安装后自动配置模型
$zclawDir = "$env:USERPROFILE\.zclaw"
if (-not (Test-Path $zclawDir)) {
    New-Item -ItemType Directory -Path $zclawDir -Force
}
Copy-Item -Path "\\fileserver\software\ZCLAW\config\zclaw.toml" -Destination "$zclawDir\zclaw.toml" -Force

3.5 杀毒软件排除

部分杀毒软件可能误报 ZCLAW。建议在终端防护策略中添加排除项：

排除路径	说明
C:\Program Files\ZCLAW\	安装目录
C:\Program Files\ZCLAW\ZClaw.exe	主程序
%USERPROFILE%\.zclaw\	用户数据目录

Windows Defender 排除步骤：

1. Windows 安全中心 -> 病毒和威胁防护 -> 管理设置
2. 滚动到"排除项" -> 添加或删除排除项
3. 添加"文件夹"排除 -> 选择 ZCLAW 安装目录

企业级排除（PowerShell 远程执行）：

Add-MpPreference -ExclusionPath "C:\Program Files\ZCLAW\"

---

4. SaaS 后端部署（可选）

4.1 何时需要 SaaS 后端

需求	纯客户端	SaaS 模式
用户数 < 50	推荐	不必要
集中管理用户账号	不支持	支持
使用配额控制	不支持	支持
集中审计日志	不支持	支持
管理后台	不支持	支持（Admin V2）
SSO 单点登录	不支持	可集成

4.2 Docker Compose 部署

4.2.1 准备环境变量

# 在项目根目录
cp saas-env.example .env

编辑 .env，填入真实值：

# ===== 必须修改 =====
POSTGRES_USER=zclaw
POSTGRES_PASSWORD=<使用 openssl rand -hex 16 生成>
POSTGRES_DB=zclaw_saas

ZCLAW_DATABASE_URL=postgres://zclaw:<与上面密码一致>@postgres:5432/zclaw_saas
ZCLAW_SAAS_JWT_SECRET=<使用 openssl rand -hex 32 生成>
ZCLAW_TOTP_ENCRYPTION_KEY=<使用 openssl rand -hex 32 生成>

# ===== 管理员账号 =====
ZCLAW_ADMIN_USERNAME=admin
ZCLAW_ADMIN_PASSWORD=<设置强密码>

# ===== 生产环境标志 =====
ZCLAW_SAAS_DEV=false

安全警告： 所有密钥必须使用随机生成，不要使用可猜测的值。生成命令：openssl rand -hex 32

4.2.2 启动服务

# 构建并启动
docker compose up -d --build

# 查看启动状态
docker compose ps

# 查看日志
docker compose logs -f saas

4.2.3 验证部署

# 健康检查
curl http://localhost:8080/health

# 预期返回 HTTP 200

4.3 Nginx 反向代理 + HTTPS

4.3.1 SSL 证书

医院环境通常使用内部 CA 签发证书。将证书文件放到服务器：

/etc/nginx/ssl/zclaw.crt    # 证书文件
/etc/nginx/ssl/zclaw.key    # 私钥文件

4.3.2 Nginx 配置模板

server {
    listen 443 ssl http2;
    server_name zclaw.hospital.local;  # 改为实际域名

    ssl_certificate     /etc/nginx/ssl/zclaw.crt;
    ssl_certificate_key /etc/nginx/ssl/zclaw.key;
    ssl_protocols       TLSv1.2 TLSv1.3;

    # 安全头
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header Strict-Transport-Security "max-age=31536000" always;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE 流式响应支持
        proxy_buffering off;
        proxy_read_timeout 300s;
        proxy_cache off;

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

# HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name zclaw.hospital.local;
    return 301 https://$host$request_uri;
}

4.3.3 启用配置

sudo nginx -t          # 验证配置
sudo systemctl reload nginx  # 重载配置

4.4 CORS 配置

编辑 saas-config.toml 中的 cors_origins：

[server]
cors_origins = ["https://zclaw.hospital.local"]

或通过环境变量覆盖。生产环境中必须配置为实际域名，不允许包含 localhost。

4.5 客户端连接 SaaS 后端

桌面端配置 SaaS 连接：

1. 启动 ZCLAW
2. 进入"设置" -> "通用"
3. 在 Gateway URL 中填入：https://zclaw.hospital.local
4. 保存并重新连接

批量部署时，可在 zclaw.toml 模板中预配置此地址。

4.6 管理后台

SaaS 模式下提供 Admin V2 管理后台（admin-v2/ 目录），功能包括：

• 用户管理（创建、禁用、重置密码）
• 订阅与配额管理
• 审计日志查看
• 系统配置

访问地址：https://zclaw.hospital.local/admin（需要管理员账号登录）

---

5. 数据安全与隐私合规

5.1 数据存储架构

┌──────────────────────────────────────────────────────────────────┐
│                        纯客户端模式                                │
│                                                                  │
│  终端电脑 A          终端电脑 B          终端电脑 C                │
│  ┌────────────┐     ┌────────────┐     ┌────────────┐           │
│  │ ZCLAW      │     │ ZCLAW      │     │ ZCLAW      │           │
│  │ SQLite     │     │ SQLite     │     │ SQLite     │           │
│  └────────────┘     └────────────┘     └────────────┘           │
│       隔离               隔离               隔离                  │
│                                                                  │
│  用户 A 的数据    用户 B 的数据    用户 C 的数据                    │
│  完全独立          完全独立         完全独立                        │
└──────────────────────────────────────────────────────────────────┘

关键安全特性：

特性	说明
本地存储	所有聊天记录存储在本地 SQLite 文件中
用户隔离	每个终端用户的数据完全隔离，互不可见
不跨用户共享	默认无任何数据共享机制
API Key 加密	LLM API Key 使用系统级加密存储

5.2 数据流向

用户输入 → ZCLAW 桌面端 → (HTTPS加密) → LLM API 服务
                                        ↓
                               AI 生成回复
                                        ↓
用户屏幕 ← ZCLAW 桌面端 ← (HTTPS加密) ←

本地 SQLite 持久化聊天记录（仅存储在用户电脑上）

数据不经过的路径：

• 不经过 ZCLAW 开发者的服务器
• 不经过任何第三方中间服务器
• 不经过其他同事的电脑

5.3 医疗隐私合规要点

合规要求	ZCLAW 的应对措施
患者数据不出院	聊天记录存储在终端本地，SaaS 模式下存储在院内服务器
数据加密传输	所有 LLM API 调用使用 HTTPS 加密
操作可追溯	SaaS 模式提供完整审计日志
数据最小化	ZCLAW 仅发送用户输入的文字，不自动采集系统信息
访问控制	SaaS 模式支持基于角色的权限管理

5.4 安全建议

对终端用户的要求（建议在培训中传达）：

1. 不在 ZCLAW 中输入患者真实姓名、身份证号、病历号等 PHI（受保护健康信息）
2. 如需处理医疗数据，先进行脱敏处理
3. 离开工位时关闭或锁定 ZCLAW 窗口
4. 不将 API Key 告知他人

对 IT 部门的要求：

1. 使用国内 LLM 服务商（数据不出境）
2. SaaS 模式下确保数据库服务器在院内网络
3. 定期备份数据库
4. 定期审查审计日志
5. 及时更新 ZCLAW 版本

5.5 数据本地化

纯客户端模式下，数据文件位置：

%USERPROFILE%\.zclaw\
├── zclaw.toml          # 配置文件（含加密后的 API Key）
├── data\
│   └── zclaw.db        # SQLite 数据库（聊天记录、会话历史）
└── logs\
    └── app.log         # 应用日志

SaaS 模式下，数据库运行在 Docker 容器内的 PostgreSQL 中，数据卷为 postgres_data。

---

6. 日志与排错

6.1 日志位置

日志类型	位置	内容
应用日志	%USERPROFILE%\.zclaw\logs\app.log	运行状态、错误信息
SaaS 日志	docker compose logs saas	后端 API 日志
PostgreSQL 日志	docker compose logs postgres	数据库日志
Nginx 日志	/var/log/nginx/	访问日志、错误日志

6.2 常见错误码

桌面端错误

错误现象	可能原因	解决方法
启动闪退	缺少 VC++ 运行库	winget install Microsoft.VCRedist.2015+.x64
启动闪退	配置文件损坏	删除 %USERPROFILE%\.zclaw 后重启
"连接失败"	网络不通	检查出站 443 端口和白名单
"请先配置模型"	未配置 LLM	在设置中添加模型和 API Key
AI 不回复	API Key 无效或过期	重新获取 API Key
AI 不回复	防火墙拦截	添加 ZCLAW 到防火墙白名单
窗口空白/白屏	WebView2 异常	安装最新 Edge WebView2 Runtime

SaaS 后端错误

错误码/日志	可能原因	解决方法
connection refused	PostgreSQL 未就绪	docker compose ps postgres 检查状态
authentication failed	数据库密码错误	核对 .env 中密码一致性
JWT secret required	未设置 JWT 密钥	设置 ZCLAW_SAAS_JWT_SECRET
502 Bad Gateway	SaaS 后端未运行	docker compose restart saas
SSE 中断	Nginx 缓冲未关闭	确认 proxy_buffering off

6.3 健康检查

# SaaS 后端健康检查
curl http://localhost:8080/health

# PostgreSQL 状态
docker compose exec postgres pg_isready -U zclaw

# Docker 容器状态
docker compose ps

# 资源使用
docker stats --no-stream zclaw-saas zclaw-postgres

# 数据库大小
docker compose exec postgres psql -U zclaw -c \
  "SELECT pg_size_pretty(pg_database_size('zclaw_saas'));"

6.4 收集诊断信息

当用户报告问题且无法远程定位时，请用户收集以下信息：

# 在用户电脑的 PowerShell 中执行

# 1. 系统信息
systeminfo | findstr /C:"OS Name" /C:"OS Version" /C:"System Type" /C:"Total Physical Memory"

# 2. 应用日志（最近 100 行）
Get-Content "$env:USERPROFILE\.zclaw\logs\app.log" -Tail 100

# 3. 网络连通性测试（替换为实际 LLM API 域名）
Test-NetConnection open.bigmodel.cn -Port 443

# 4. 进程状态
Get-Process -Name "ZClaw" -ErrorAction SilentlyContinue | Format-List

将以上输出保存为文本文件，发送给支持团队。

---

7. 配置参考

7.1 saas-config.toml 完整参考

# ZCLAW SaaS 配置文件
# 敏感配置请通过环境变量覆盖，不要在文件中明文写入密码

config_version = 1

[server]
host = "0.0.0.0"                    # 监听地址，生产环境保持 0.0.0.0（由 Nginx 控制外部访问）
port = 8080                          # 监听端口
cors_origins = ["https://zclaw.hospital.local"]  # CORS 白名单，必须改为实际域名

[database]
# 生产环境必须通过 ZCLAW_DATABASE_URL 环境变量设置
url = "postgres://zclaw:${DB_PASSWORD}@localhost:5432/zclaw"
max_connections = 100                # 最大连接数
min_connections = 10                 # 最小空闲连接
acquire_timeout_secs = 8             # 获取连接超时
idle_timeout_secs = 180              # 空闲连接回收时间
max_lifetime_secs = 900              # 连接最大存活时间
worker_concurrency = 20              # 后台任务并发上限

[auth]
jwt_expiration_hours = 24            # JWT 有效期（小时）
totp_issuer = "ZCLAW SaaS"           # TOTP 应用名称

[relay]
max_queue_size = 1000                # 消息队列上限
max_concurrent_per_provider = 5      # 单 Provider 并发上限
batch_window_ms = 50                 # 批处理窗口
retry_delay_ms = 1000                # 重试间隔
max_attempts = 3                     # 最大重试次数

[rate_limit]
requests_per_minute = 60             # 全局默认限流
burst = 10                           # 突发请求数

7.2 环境变量优先级

环境变量优先于 saas-config.toml 中的配置。关键环境变量：

变量	说明	必填
ZCLAW_DATABASE_URL	数据库连接字符串（含密码）	是
ZCLAW_SAAS_JWT_SECRET	JWT 签名密钥（>= 32 字符）	是
ZCLAW_TOTP_ENCRYPTION_KEY	TOTP 加密密钥（64 字符 hex）	是
ZCLAW_ADMIN_USERNAME	初始管理员用户名	否（默认 admin）
ZCLAW_ADMIN_PASSWORD	初始管理员密码	否
ZCLAW_SAAS_DEV	开发模式标志，生产必须为 false	否
DB_PASSWORD	数据库密码（用于 TOML 插值）	是
POSTGRES_USER	PostgreSQL 用户名	是
POSTGRES_PASSWORD	PostgreSQL 密码	是
POSTGRES_DB	PostgreSQL 数据库名	是

7.3 客户端 zclaw.toml 参考

%USERPROFILE%\.zclaw\zclaw.toml

此文件由 ZCLAW 自动生成和管理，一般不需要手动编辑。如需批量预配置：

# 以下为示意结构，实际格式以 ZCLAW 生成为准
[general]
gateway_url = "https://zclaw.hospital.local"  # SaaS 模式下配置

[model]
default = "glm-4-flash"

---

8. 运维操作速查

8.1 日常运维命令

# 查看服务状态
docker compose ps

# 查看实时日志
docker compose logs -f saas

# 重启 SaaS 后端（不影响数据库）
docker compose restart saas

# 重启所有服务
docker compose restart

# 停止所有服务
docker compose down

# 启动所有服务
docker compose up -d

8.2 数据库备份与恢复

# 手动备份
docker compose exec postgres pg_dump -U zclaw zclaw_saas \
  > backup_$(date +%Y%m%d_%H%M%S).sql

# 自动每日备份（加入 crontab）
echo "0 3 * * * docker compose -f /opt/zclaw/docker-compose.yml exec -T \
  postgres pg_dump -U zclaw zclaw_saas | gzip > \
  /opt/backups/zclaw_\$(date +\%Y\%m\%d).sql.gz" | crontab -

# 从备份恢复
gunzip -c /opt/backups/zclaw_20260408.sql.gz | \
  docker compose exec -T postgres psql -U zclaw -d zclaw_saas

8.3 升级流程

# 1. 备份数据库（见上方）

# 2. 拉取新版本
cd /opt/zclaw
git pull origin main

# 3. 重新构建并启动
docker compose up -d --build

# 4. 验证
docker compose ps
curl http://localhost:8080/health

# 5. 检查日志确认无异常
docker compose logs --tail=50 saas

8.4 桌面端升级

桌面端升级方式取决于部署方式：

部署方式	升级方法
手动安装	重新运行新版安装包（自动覆盖旧版）
GPO 分发	更新软件包路径，重新部署
SCCM/Intune	更新应用包，推送更新
登录脚本	更新网络共享中的安装包，脚本检测版本自动安装

---

9. 附录

9.1 部署前检查清单

终端电脑检查
[ ] Windows 10 (1809+) 或 Windows 11
[ ] 8 GB+ 内存
[ ] 500 MB+ 可用磁盘空间
[ ] 网络可访问 LLM API 服务域名
[ ] 杀毒软件已添加排除项

SaaS 后端检查（如适用）
[ ] 服务器 4 GB+ 内存，40 GB+ 磁盘
[ ] Docker 24.0+ 已安装
[ ] Docker Compose v2+ 已安装
[ ] PostgreSQL 16+ 可用（Docker 内置或外部）
[ ] SSL 证书已准备
[ ] Nginx 已安装
[ ] .env 已配置（所有密钥为随机值）
[ ] CORS 白名单已配置实际域名
[ ] ZCLAW_SAAS_DEV=false 或未设置

网络检查
[ ] 终端出站 443 端口已放行
[ ] LLM API 域名已加入白名单
[ ] SaaS 后端仅绑定 127.0.0.1
[ ] PostgreSQL 端口未暴露到外部

安全检查
[ ] 所有密钥使用随机生成
[ ] .env 文件权限 600
[ ] 防火墙仅开放 22/80/443
[ ] 安全头已配置（HSTS, X-Frame-Options）

9.2 用户培训要点

向终端用户（医院行政管理人员）传达以下内容：

1. ZCLAW 是 AI 助手，生成的文字需要人工审核后才能正式使用
2. 不要在 ZCLAW 中输入患者个人信息
3. 遇到问题首先尝试关闭并重新打开 ZCLAW
4. 无法解决的问题联系 IT 部门
5. 配套分发《安装与使用指南》（docs/installation-guide.md）

---

本指南基于 ZCLAW v0.1.0 编写，最后更新：2026-04-08