SkillSpace/archives/cloud-deploy-2.0/SKILL.md

---
name: cloud-deploy
version: "2.0"
description: 一键部署本地项目到云服务器。通过 API 网关模式部署，Token 认证，无需 SSH 私钥。
  使用场景包括：(1) 部署前端静态页面，(2) 快速预览开发成果，(3) 分享可访问的 URL 给他人，(4) 安装服务器环境。
  触发语句如："部署这个项目"、"推到云服务器上"、"给我个访问链接"、"发布这个静态页面"。
  Namespace 规则：使用用户的 contactId 作为命名空间，实现用户隔离
---

# 云部署技能 (Cloud Deploy) v2.0

> v2.0 重大升级：SSH 直连 → API 网关模式，Token 认证，无需私钥

## 核心变化（v1.0 → v2.0）

| 项目 | v1.0 | v2.0 |
|------|------|------|
| 连接方式 | SSH + 私钥 | HTTPS + Token |
| 认证 | 私钥文件 | Token（可撤销） |
| 部署方式 | rsync + 远程脚本 | API 上传 + 远程执行 |
| 环境安装 | SSH 手动执行 | /api/exec 远程执行 |
| 安全性 | 私钥扩散风险 | Token 独立管控 |
| 审计 | 无 | 全量日志 |

## 核心功能

- 🚀 一键部署静态页面到云服务器
- 🔑 Token 认证，首次使用自动注册
- 🛡️ 危险命令拦截 + 全量审计日志
- 👥 Namespace 自动隔离（contactId）
- 🎲 自动生成随机目录名
- 🌐 生成可访问的 URL 地址
- 🔧 支持远程执行命令（安装环境等）

## 配置

### 环境变量（首次初始化时需要）

| 变量 | 说明 | 必填 |
|------|------|------|
| DEPLOY_API_URL | API 网关地址 | 是 |
| DEPLOY_REGISTRATION_KEY | 注册码 | 是 |
| DEPLOY_AGENT_ID | Agent ID | 否 |
| DEPLOY_INSTANCE_NAME | 实例名称 | 否 |

### 配置文件

初始化后保存在 `~/.openclaw/cloud-deploy.json`：

```json
{
  "apiUrl": "<API网关地址>",
  "registrationKey": "<注册码>",
  "token": null,
  "agentId": ""
}
```

部署时替换占位符：
- `<API网关地址>` — 部署的 API 服务地址（如 https://your-domain.com/api）
- `<注册码>` — 服务端配置的 registrationKey

---

## 工作流程

### 步骤 0：初始化配置（首次使用）

```bash
DEPLOY_API_URL="<API网关地址>" \
DEPLOY_REGISTRATION_KEY="<注册码>" \
bash scripts/init-config.sh
```

### 步骤 1：Token 自注册（首次使用自动执行）

**触发条件**：本地配置中 token 为空

```bash
bash scripts/register.sh [contactId]
```

注册成功后 token 自动保存到配置文件。

### 步骤 2：获取用户 contactId

从 `user_index.json` 获取当前用户的 contactId 作为 namespace。

### 步骤 3：部署

```bash
bash scripts/deploy.sh <项目目录> <contactId> <项目名>
```

脚本自动执行：打包 → 上传 → 部署 → 返回 URL

### 步骤 4：返回结果

```
✅ 部署成功！

🌐 访问地址：https://<域名>/<contactId>/<目录名>/
📂 目录名：<随机ID>-<项目名>-<时间戳>
⏱️ 部署耗时：X 秒
```

---

## 远程命令执行（安装环境等）

```bash
bash scripts/exec.sh "<命令>" [超时毫秒]
```

**安全限制**：
- 危险命令会被拦截（rm -rf /、shutdown 等）
- 操作目录受限
- 每条命令都有审计日志

---

## API 接口一览

| 接口 | 方法 | 权限 | 用途 | 脚本 |
|------|------|------|------|------|
| /api/auth/register | POST | 注册码 | 自注册 | register.sh |
| /api/deploy | POST | deploy | 一键部署 | deploy.sh |
| /api/upload | POST | deploy | 上传文件 | upload.sh |
| /api/exec | POST | exec | 执行命令 | exec.sh |
| /api/deployments | GET | list | 查看部署列表 | list.sh |
| /api/deploy/{id} | DELETE | delete | 删除部署 | delete.sh |
| /api/health | GET | 无 | 健康检查 | health.sh |

---

## 脚本说明

| 脚本 | 功能 |
|------|------|
| `scripts/init-config.sh` | 初始化配置文件（环境变量驱动） |
| `scripts/register.sh` | Token 自注册 |
| `scripts/deploy.sh` | 主部署脚本（打包+上传+部署） |
| `scripts/pack.sh` | 打包项目为 tar.gz |
| `scripts/exec.sh` | 远程执行命令 |
| `scripts/upload.sh` | 上传文件到指定路径 |
| `scripts/list.sh` | 查看部署列表 |
| `scripts/delete.sh` | 删除指定部署 |
| `scripts/health.sh` | 健康检查 |

---

## 用户交互模式

### 模式 1：部署静态页面（最常用）

```
用户：部署这个静态页面

AI：🔍 检测到项目：landing-page（静态页面）
    🔑 Token 已就绪
    👥 Namespace：<contactId>

    正在部署...
    📦 打包文件中...（15 个文件，2.3MB）
    🚀 上传并部署中...
    
    ✅ 部署成功！
    🌐 访问地址：https://<域名>/<contactId>/<目录名>/
    ⏱️ 部署耗时：5 秒
```

### 模式 2：首次使用（自动注册）

```
用户：部署这个项目

AI：🔍 检测到首次使用云部署，正在初始化...
    📝 配置文件已创建
    🔑 注册成功，Token 已保存
    
    继续部署...
    （后续同模式 1）
```

### 模式 3：安装环境

```
用户：服务器上需要装 Python

AI：🔧 正在执行远程命令...
    > sudo apt update && sudo apt install -y python3 python3-pip
    
    ✅ 执行完成（耗时 12 秒）
```

### 模式 4：查看部署列表

```
用户：看看已部署的项目

AI：📋 你的部署列表（共 N 个）：

    1. <目录名>
       🌐 <URL>
       ⏰ <部署时间>
```

### 模式 5：删除部署

```
用户：删掉第一个项目

AI：🗑️ 已删除 <目录名>
    文件已清理
```

---

## 安全设计

### Token 机制

| 要素 | 说明 |
|------|------|
| 注册码 | 技能配置时注入，只用于注册 |
| Token | 每个 AI 助理独立，可单独撤销 |
| 权限 | deploy / exec / list / delete |
| 审计 | 每次操作都记录到服务端日志 |

### 危险命令拦截

以下命令会被服务端拦截：
- rm -rf /（删除根目录）
- shutdown / reboot（关机重启）
- mkfs / dd if=（格式化磁盘）
- iptables -F / ufw disable（关闭防火墙）
- systemctl stop nginx（停止 Nginx）
- curl|bash / wget|bash（远程执行）

### 路径保护

/api/exec 和 /api/upload 只允许操作服务端配置的允许目录。

### 管理员操作（仅 owner）

| 操作 | 接口 |
|------|------|
| 查看所有 Token | GET /api/admin/tokens |
| 撤销 Token | DELETE /api/admin/tokens/{prefix} |
| 查看审计日志 | GET /api/admin/audit?date=YYYY-MM-DD |

---

## 服务端部署

API 网关服务端部署说明见 `references/server-setup.md`

---

## 目录结构

```
skills/cloud-deploy/
├── SKILL.md              # 技能说明（本文件）
├── README.md             # 快速入门
├── QUICKSTART.sh         # 快速启动脚本
├── scripts/              # 客户端脚本
│   ├── init-config.sh
│   ├── register.sh
│   ├── deploy.sh
│   ├── pack.sh
│   ├── exec.sh
│   ├── upload.sh
│   ├── list.sh
│   ├── delete.sh
│   ├── health.sh
│   └── legacy/           # v1.0 旧脚本（保留备查）
├── references/           # 参考文档
│   ├── server-setup.md   # 服务端部署指南
│   └── security-guide.md # 安全指南
└── assets/
    └── templates/
```

---

_版本：v2.0 | 更新：2026-04-21（SSH → API 网关模式）_
_v1.0 备份：skills/cloud-deploy-v1.0-backup/_