# 服务端部署指南（API 网关）

> 本文档说明如何在云服务器上部署 Cloud Deploy API 网关服务

## 前置条件

- Ubuntu 20.04+ 服务器
- 域名已解析到服务器
- 80/443 端口可访问

## 部署步骤

### 1. 安装 Node.js

```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
```

### 2. 安装 PM2

```bash
sudo npm install -g pm2
```

### 3. 创建服务目录

```bash
sudo mkdir -p /data/disk/deploy-api/{logs,tmp}
sudo mkdir -p /data/disk/deployments
sudo chown -R $USER:$USER /data/disk/deploy-api
sudo chown -R $USER:$USER /data/disk/deployments
```

### 4. 部署服务文件

将以下文件放到 `/data/disk/deploy-api/`：
- server.js — 主服务
- package.json — 依赖
- config.json — 服务配置
- tokens.json — Token 存储
- security.json — 安全规则

### 5. 配置 config.json

```json
{
  "port": 3900,
  "domain": "your-domain.com",
  "deployDir": "/data/disk/deployments",
  "dataDir": "/data/disk/deploy-api",
  "maxUploadSize": "100mb",
  "execTimeout": 300000,
  "logRetainDays": 90
}
```

### 6. 配置 tokens.json

```json
{
  "registrationKey": "<生成一个随机注册码>",
  "tokens": {
    "<生成一个admin token>": {
      "agentId": "manual",
      "instanceName": "管理员",
      "contactId": "",
      "permissions": ["deploy", "exec", "list", "delete", "admin"],
      "active": true,
      "createdAt": "<当前时间>",
      "lastUsedAt": null
    }
  }
}
```

生成随机字符串：
```bash
# 注册码
echo "reg_$(openssl rand -hex 12)"
# Admin Token
echo "tok_admin_$(openssl rand -hex 16)"
```

### 7. 安装依赖并启动

```bash
cd /data/disk/deploy-api
npm install
pm2 start server.js --name deploy-api
pm2 save
pm2 startup
```

### 8. 配置 Nginx 反向代理

```nginx
server {
    listen 80;
    server_name your-domain.com;

    root /data/disk/deployments;
    index index.html index.htm;

    # API 反向代理
    location /api/ {
        proxy_pass http://127.0.0.1:3900/api/;
        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;
        client_max_body_size 100M;
        proxy_read_timeout 300s;
    }

    # 静态文件
    location / {
        try_files $uri $uri/ =404;
        autoindex on;
    }
}
```

### 9. 配置 HTTPS（可选）

```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
```

### 10. 验证

```bash
curl https://your-domain.com/api/health
```

## 日常维护

### 查看日志

```bash
# PM2 日志
pm2 logs deploy-api

# 审计日志
cat /data/disk/deploy-api/logs/audit-$(date +%Y-%m-%d).jsonl | python3 -m json.tool
```

### 重启服务

```bash
pm2 restart deploy-api
```

### 更新代码

```bash
cd /data/disk/deploy-api
# 替换 server.js
pm2 restart deploy-api
```

---

_Cloud Deploy v2.0 服务端部署指南_