# ZCLAW SaaS 后端部署指南

## 系统要求

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

## 快速部署 (Docker Compose)

### 1. 准备配置

```bash
# 进入项目目录
cd zclaw-saas

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

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

### 2. 生成密钥

```bash
# JWT 密钥
openssl rand -base64 48

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

### 3. 配置 CORS

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

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

### 4. 启动服务

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

# 查看日志
docker compose logs -f saas

# 查看状态
docker compose ps
```

### 5. 验证部署

```bash
# 健康检查
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. 数据库初始化

```bash
# 创建数据库
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)

```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 反向代理示例

```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;
    }
}
```

## 运维命令

```bash
# 使用 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` |