zclaw_openfang/docs/deployment/saas-deployment.md

ZCLAW SaaS 后端部署指南

系统要求

组件	最低要求	推荐配置
CPU	2 核	4 核
内存	2 GB	4 GB
磁盘	10 GB SSD	20 GB SSD
PostgreSQL	15+	16
Docker	24+	最新

快速部署 (Docker Compose)

1. 准备配置

# 进入项目目录
cd zclaw-saas

# 复制环境变量模板
cp saas-env.example .env

# 编辑 .env，填入实际值
# 必须修改: POSTGRES_PASSWORD, ZCLAW_SAAS_JWT_SECRET, ZCLAW_SAAS_FIELD_ENCRYPTION_KEY

2. 生成密钥

# JWT 密钥
openssl rand -base64 48

# AES-256-GCM 字段加密密钥
openssl rand -hex 32

3. 配置 CORS

编辑 saas-config.toml，设置允许的来源：

[server]
cors_origins = ["https://your-admin-domain.com", "https://your-app-domain.com"]

4. 启动服务

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

# 查看日志
docker compose logs -f saas

# 查看状态
docker compose ps

5. 验证部署

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

# API 版本
curl http://localhost:8080/api/v1/relay/models

手动部署 (无 Docker)

1. 安装依赖

• Rust 1.75+ (推荐 rustup)
• PostgreSQL 16
• OpenSSL 开发头文件 (libssl-dev on Ubuntu)

2. 数据库初始化

# 创建数据库
createdb zclaw

# 启动 SaaS 服务 (首次启动自动创建表结构)
ZCLAW_SAAS_JWT_SECRET=xxx \
ZCLAW_SAAS_FIELD_ENCRYPTION_KEY=xxx \
DATABASE_URL=postgres://user:pass@localhost:5432/zclaw \
cargo run --release --package zclaw-saas

3. 环境变量

变量	必需	说明
DATABASE_URL	是	PostgreSQL 连接 URL
ZCLAW_SAAS_JWT_SECRET	是	JWT 签名密钥 (>=32 字符)
ZCLAW_SAAS_FIELD_ENCRYPTION_KEY	是*	AES-256-GCM 密钥 (64 字符 hex)
ZCLAW_SAAS_CONFIG	否	配置文件路径 (默认 ./saas-config.toml)
ZCLAW_SAAS_DEV	否	开发模式 (true/1)

*生产环境必需。开发环境设置 ZCLAW_SAAS_DEV=true 可自动生成临时密钥。

4. 配置文件 (saas-config.toml)

[server]
host = "0.0.0.0"
port = 8080
cors_origins = ["https://admin.example.com"]

[database]
url = "postgres://user:pass@localhost:5432/zclaw"

[auth]
jwt_expiration_hours = 24
totp_issuer = "ZCLAW SaaS"

[relay]
max_queue_size = 1000
max_concurrent_per_provider = 5
batch_window_ms = 50
retry_delay_ms = 1000
max_attempts = 3

[rate_limit]
requests_per_minute = 60
burst = 10

安全加固清单

• ZCLAW_SAAS_JWT_SECRET 使用强随机密钥
• ZCLAW_SAAS_FIELD_ENCRYPTION_KEY 已设置 (数据库 API Key 加密)
• ZCLAW_SAAS_DEV 未设置或为 false
• cors_origins 配置为实际域名
• PostgreSQL 使用独立密码，不使用默认密码
• 防火墙仅开放 8080 端口
• HTTPS 反向代理 (Nginx/Caddy) 配置在 SaaS 前面

Nginx 反向代理示例

server {
    listen 443 ssl;
    server_name saas-api.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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_read_timeout 300s;
        proxy_buffering off;
    }
}

运维命令

# 使用 Makefile
make saas-build        # 编译
make saas-run          # 启动
make saas-test         # 运行测试
make saas-clippy       # 代码检查
make saas-docker-up    # Docker 启动
make saas-docker-down  # Docker 停止

# 或手动
cargo build --release --package zclaw-saas
cargo run --release --package zclaw-saas
cargo test --package zclaw-saas
cargo clippy --package zclaw-saas

故障排查

问题	排查步骤
启动失败 "DATABASE_URL 未配置"	检查 .env 中 DATABASE_URL 是否设置
启动失败 "ZCLAW_SAAS_JWT_SECRET 未设置"	设置环境变量或 ZCLAW_SAAS_DEV=true
请求 429 Too Many Requests	调整 saas-config.toml 中 rate_limit 配置
中转 502 Bad Gateway	检查 provider URL 是否可达、API Key 是否有效
SSE 流中断	检查反向代理超时设置，确保 proxy_read_timeout >= 300s