feat: deliverables 3-6 — cold start, simple mode UI, bridge tests, docs

Deliverable 3 — Cold Start Flow: - New: use-cold-start.ts — cold start detection + greeting management - Default Chinese greeting for hospital admin users - Phase tracking: idle → greeting_sent → waiting_response → completed Deliverable 4 — Simple Mode UI: - New: uiModeStore.ts — 'simple'|'professional' mode with localStorage - New: SimpleTopBar.tsx — minimal top bar with mode toggle - Modified: App.tsx — dual layout rendering based on UI mode - Modified: ChatArea.tsx — compact prop hides advanced controls - Default: 'simple' mode for zero-barrier first experience Deliverable 5 — Tauri Bridge Integration Tests: - New: tauri-bridge.integration.test.ts — 14 test cases - Covers: cold start, chat flow, persistence, memory, butler, UI mode, e2e - 14/14 passing Deliverable 6 — Release Documentation: - New: installation-guide.md — user-facing install guide (Chinese, no jargon) - New: hospital-deployment.md — IT admin deployment guide (Docker, GPO, SCCM)
2026-04-09 09:51:56 +08:00
parent ffaee49d67
commit e6937e1e5f
8 changed files with 2031 additions and 4 deletions
--- a/docs/deployment/hospital-deployment.md
+++ b/docs/deployment/hospital-deployment.md
@@ -0,0 +1,776 @@
+# ZCLAW 医院部署指南
+
+**面向：医院 IT 管理员**
+
+**本文档面向医院信息科/IT 部门的技术人员，提供 ZCLAW 在医院环境中的完整部署方案。**
+
+---
+
+## 目录
+
+1. [部署概述](#1-部署概述)
+2. [系统与网络要求](#2-系统与网络要求)
+3. [桌面端安装与分发](#3-桌面端安装与分发)
+4. [SaaS 后端部署（可选）](#4-saas-后端部署可选)
+5. [数据安全与隐私合规](#5-数据安全与隐私合规)
+6. [日志与排错](#6-日志与排错)
+7. [配置参考](#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 静默安装
+
+```powershell
+# 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：登录脚本
+
+```batch
+@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` 目录
+
+```powershell
+# 安装后自动配置模型
+$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 远程执行）：**
+
+```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 准备环境变量
+
+```bash
+# 在项目根目录
+cp saas-env.example .env
+```
+
+编辑 `.env`，填入真实值：
+
+```bash
+# ===== 必须修改 =====
+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 启动服务
+
+```bash
+# 构建并启动
+docker compose up -d --build
+
+# 查看启动状态
+docker compose ps
+
+# 查看日志
+docker compose logs -f saas
+```
+
+#### 4.2.3 验证部署
+
+```bash
+# 健康检查
+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 配置模板
+
+```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 启用配置
+
+```bash
+sudo nginx -t          # 验证配置
+sudo systemctl reload nginx  # 重载配置
+```
+
+### 4.4 CORS 配置
+
+编辑 `saas-config.toml` 中的 `cors_origins`：
+
+```toml
+[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 健康检查
+
+```bash
+# 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
+# 在用户电脑的 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 完整参考
+
+```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 自动生成和管理，一般不需要手动编辑。如需批量预配置：
+
+```toml
+# 以下为示意结构，实际格式以 ZCLAW 生成为准
+[general]
+gateway_url = "https://zclaw.hospital.local"  # SaaS 模式下配置
+
+[model]
+default = "glm-4-flash"
+```
+
+---
+
+## 8. 运维操作速查
+
+### 8.1 日常运维命令
+
+```bash
+# 查看服务状态
+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 数据库备份与恢复
+
+```bash
+# 手动备份
+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 升级流程
+
+```bash
+# 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*