# 使用 AI Agent 开发和部署站点

星图站点空间将 UCloud Sandbox 与 AI Agent 结合，您可以直接用自然语言描述需求，让 Codex、Claude Code 或 OpenCode 等 Agent 在云端站点中生成代码、安装依赖、启动服务并完成部署。

适合的场景包括：

- 仪表盘、数据大屏和运营看板
- 展示页、工具页和其他 Web 站点
- 基于星图管理 API 的模型用量、请求日志或账单数据面板
- 贪吃蛇等轻量互动游戏

> 本页使用 `<连接密钥>` 作为占位符。连接密钥只能用于访问对应站点，请勿将真实值写入代码仓库、截图或公开内容。

## 前置准备

开始前，请确保本机已安装：

- Node.js 和 `npx`，用于安装 Agent skill
- 一款支持 skill 的 AI Agent，例如 Codex、Claude Code 或 OpenCode

## 第一步：创建站点

登录星图平台，进入[站点空间](https://astraflow.ucloud.cn/modelverse/site-space)，点击【创建站点】。根据页面提示填写站点名称、环境变量、API Key 和访问码并完成创建。

![配置并创建站点](https://cdnv2-cache.udelivrs.com/2026/08/ef90a6930c10049462cebbf4fe3926e8_1787118901572.png)

## 第二步：获取远程开发指引

站点创建成功后，在站点列表中找到目标站点，点击【连接】。

![查看远程开发和站点连接指引](https://cdnv2-cache.udelivrs.com/2026/08/60d009175850c9b313d20d5545bda0df_1787118901569.png)

页面会显示当前站点的连接方法和连接密钥。后续需要将这个连接密钥提供给本地 AI Agent。

## 第三步：准备本地开发目录

在本机新建一个独立的开发目录，并进入该目录：

```bash
mkdir -p /path/to/site-dev
cd /path/to/site-dev
```

> 请将 `/path/to/site-dev` 替换为您实际使用的目录。建议为每个站点使用独立目录，避免 Agent 误读或修改其他项目。

## 第四步：安装 Agent skill

在开发目录中执行：

```bash
npx skills add ucloud/ucloud-sandbox-cli -s astraflow-api -s ucloud-sandbox-site
```

该命令会安装两个 skill：

| Skill | 用途 |
| --- | --- |
| `ucloud-sandbox-site` | 连接站点空间、管理文件、生成代码、启动服务和部署站点 |
| `astraflow-api` | 调用星图管理 API，查询模型、请求日志、账单和订单等数据 |

## 第五步：让 AI Agent 连接站点

在当前目录启动您使用的 Agent。例如，启动 Codex：

```bash
codex
```

在 Agent 中输入以下提示词，并将占位符替换为【远程开发】页面显示的连接密钥：

```text
连接星图站点 <连接密钥>
```

Agent 会根据 skill 指引完成 CLI 检查、站点身份校验和连接测试。当 Agent 确认连接成功后，即可继续描述站点需求。

## 第六步：描述您的站点需求

连接成功后，您可以直接使用自然语言提出需求。例如：

```text
帮我开发一个贪吃蛇小游戏。
```

可以在首次提示中一次说清页面用途、目标用户、期望风格、数据来源和主要交互，便于 Agent 更准确地完成开发。

Agent 会完成代码生成、依赖安装、构建、服务启动和访问验证。正常情况下，您无需手动执行这些步骤；如果 Agent 请求确认覆盖文件、删除内容或执行其他高风险操作，请在确认影响范围后再授权。

## 通过 MCP 管理和开发站点空间
站点空间 MCP 将站点创建、管理、开发与部署能力以 MCP 工具形式提供给 AI Agent，支持通过自然语言完成站点全生命周期操作，适用于企业级多站点开发与管理。 

- 当前仅支持cn-wlcb

MCP 支持以下两种部署方式：

- **UCloud托管服务**：直接连接 UCloud 提供的远程 MCP 地址，无需自行部署。
- **自托管服务**：通过 Docker 在本地或自己的服务器上运行 MCP 服务。

开始前，请准备站点所在地域、UCloud 项目 ID，以及 UCloud API 公钥和私钥。API 密钥可以在 [UCloud API 密钥管理](https://console.ucloud.cn/uapi/apikey)中创建或查看。

> UCloud API 私钥是高度敏感的凭证。不要将真实密钥提交到代码仓库，也不要出现在提示词、截图或日志中。建议使用权限范围满足当前任务的子账号密钥。

### 方式一：使用UCloud托管服务

将以下内容添加到 Agent 的 MCP 配置文件中，并把请求头中的占位符替换为实际值：

```json
{
  "mcpServers": {
    "ucloud-sandbox": {
      "type": "http",
      "url": "https://mcp.<region>.sandbox.ucloudai.com/mcp",
      "headers": {
        "X-UCLOUD-Region": "cn-wlcb",
        "X-UCLOUD-Project-Id": "org-xxx",
        "X-UCLOUD-Public-Key": "xxx",
        "X-UCLOUD-Private-Key": "xxx"
      }
    }
  }
}
```

| 参数 | 说明 |
| --- | --- |
| `url` | UCloud 托管的 MCP 服务地址。示例地址对应 `cn-wlcb` 地域。 |
| `X-UCLOUD-Region` | 站点所在地域，例如 `cn-wlcb`。 |
| `X-UCLOUD-Project-Id` | UCloud 项目 ID，例如 `org-xxx`。 |
| `X-UCLOUD-Public-Key` | UCloud API 公钥。 |
| `X-UCLOUD-Private-Key` | UCloud API 私钥。 |

### 方式二：使用 Docker 自托管

先在当前终端中设置 API 密钥环境变量：

```bash
export UCLOUD_PUBLIC_KEY='<您的 PublicKey>'
export UCLOUD_PRIVATE_KEY='<您的 PrivateKey>'
```

然后运行 MCP 服务：

```bash
docker run --rm \
  -p 8080:8080 \
  -e UCLOUD_REGION=cn-wlcb \
  -e UCLOUD_PROJECT_ID=org-xxxxxxxx \
  -e UCLOUD_PUBLIC_KEY="$UCLOUD_PUBLIC_KEY" \
  -e UCLOUD_PRIVATE_KEY="$UCLOUD_PRIVATE_KEY" \
  uhub.service.ucloud.cn/agent-sandbox/sandbox-mcp:latest
```

请将 `UCLOUD_REGION` 和 `UCLOUD_PROJECT_ID` 替换为实际值。该命令退出后容器会自动删除；API 密钥通过环境变量传入，不会写入命令示例或镜像。

服务启动后，将 Agent 的 MCP 地址配置为本机服务：

```json
{
  "mcpServers": {
    "ucloud-sandbox": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}
```

如果 MCP 服务运行在其他主机上，请将 `127.0.0.1` 替换为 Agent 可以访问的主机地址，并通过防火墙或反向代理限制访问范围。不要将未配置访问控制的 MCP 服务直接暴露到公网。

### 使用 MCP

配置完成后，重启或重新加载 Agent，即可通过自然语言调用 `ucloud-sandbox` MCP。例如：

```text
调用 ucloud-sandbox MCP，列出当前账号可用的站点。
```

也可以让 Agent 创建或管理站点：

```text
调用 ucloud-sandbox MCP，帮我创建一个站点。
```

Agent 会根据 MCP 提供的工具引导您选择 API Key、填写站点信息并确认操作。删除站点等不可恢复的操作，请先确认目标和影响范围再授权。

## 使用星图管理 API 构建数据面板

如果站点需要展示您账号下的模型用量、推理请求日志或账单等数据，可以让 Agent 通过 `astraflow-api` skill 调用星图管理 API。

### 1. 获取 UCloud API 密钥

前往 [UCloud API 密钥管理](https://console.ucloud.cn/uapi/apikey)创建或查看 `PublicKey` 和 `PrivateKey`。

> 这里使用的是 UCloud 账号级 `PublicKey`/`PrivateKey`，用于星图管理 API 的签名认证；它们不是连接密钥，也不是调用大模型时使用的 Bearer API Key。

### 2. 配置站点环境变量

创建或编辑站点时，在环境变量区域添加：

| 变量名 | 值 |
| --- | --- |
| `UCLOUD_PUBLIC_KEY` | UCloud API 公钥 |
| `UCLOUD_PRIVATE_KEY` | UCloud API 私钥 |

![为站点配置 UCloud API 公钥和私钥](https://cdnv2-cache.udelivrs.com/2026/08/ef90a6930c10049462cebbf4fe3926e8_1787118901572.png)

> `UCLOUD_PRIVATE_KEY` 是高度敏感的凭证。只通过站点环境变量注入，不要将它写入提示词、前端代码、代码仓库或日志。前端页面不应直接持有或使用私钥；应由站点后端读取环境变量、计算签名并调用 API。

星图管理 API 通常还需要业务地域 `Region` 和项目 ID `ProjectId`。您可以在提示词中告诉 Agent 实际值，或另行将它们配置为站点环境变量。如果不确定应使用哪个值，可让 Agent 先查询可用地域和项目列表；子账号必须提供 `ProjectId`。

### 3. 连接站点和星图 API

重新打开 Agent 时，可以使用以下提示词：

```text
连接星图站点 <连接密钥>，使用站点环境变量 UCLOUD_PUBLIC_KEY 和 UCLOUD_PRIVATE_KEY 连接星图管理 API。不要输出、记录或将密钥发送到前端。
```

连接后，即可提出数据面板需求。例如：

```text
请调用星图管理 API，开发一个面板页面，展示今天的模型消费情况，包括模型名称、请求数和消费趋势。请以 API 实际返回的日志或账单字段为准，对空数据和调用失败提供友好提示。
```

## 域名管理

如果需要使用自己的企业域名，可以在站点列表中点击【设置】，在【自定义域名】区域点击【绑定域名】。

绑定流程包括三个步骤：

1. **填写域名**：输入要绑定的域名，建议使用子域名，例如 `demo.example.com`。不要输入 `http://`、`https://` 或路径。
2. **配置 DNS**：点击【生成 DNS 记录】。页面会显示一条 CNAME 记录，复制到域名服务商后台的 DNS 解析页面。例如，`demo.example.com` 对应的主机记录为 `demo`，记录值为 `custom.cn-wlcb.sandbox.ucloudai.com`。
3. **验证并生效**：完成 DNS 配置后返回页面，点击【验证配置】。DNS 生效可能需要几分钟；验证成功后，站点会显示自定义域名访问地址。

![绑定自定义域名](https://cdnv2-cache.udelivrs.com/2026/08/55ad0edeff0fbd207188cd6e14a5bb5a_1787118901578.png)

使用该功能前，您需要拥有对应域名并能够管理其 DNS 记录，星图不会代为购买域名。平台通过 Let's Encrypt 的 ACME 协议免费签发并自动续期 HTTPS 证书。该证书为 DV 证书，不包含企业身份认证，**不建议用于支付、金融交易等敏感服务**。Let's Encrypt 对证书签发有频率限制，请避免频繁更换或重复绑定域名。

验证成功后，访问地址会切换为自定义域名；HTTPS 证书可能先显示为【等待签发】，签发完成后显示为【已启用】。点击【管理域名】可以查看以下状态：

- **HTTPS 证书**：等待签发或已生效。
- **DNS 状态**：例如 `CNAME · 配置正确`。
- **访问站点**：打开当前自定义域名。

如果需要更换域名，点击【更换域名】并重新配置、验证 DNS。新域名绑定成功前，当前域名仍可正常访问。

![管理已绑定的自定义域名](https://cdnv2-cache.udelivrs.com/2026/08/f7149303e173d12c43eec7078f9a6c98_1787118901573.png)

### 解除绑定

如果不再使用自定义域名，在【管理域名】中点击【解除绑定】：

1. 阅读提示，确认解除后访问者将无法再通过自定义域名访问站点；站点内容不会被删除，平台默认地址仍会保留。
2. 在域名服务商后台删除对应的 DNS 记录，避免域名继续指向星图。
3. 在确认框中输入 `解除绑定`，点击【确认解除】。

![确认解除自定义域名](https://cdnv2-cache.udelivrs.com/2026/08/d316f7f03a84bd0db26a5331e1bbe3ba_1787118901575.png)

## 访问控制

在站点列表中点击【设置】，可以在【访问设置】区域配置分享方式和 IP 限制。修改后需要点击【保存更改】才会生效。

### 分享方式

| 分享方式 | 访问规则 |
| --- | --- |
| 内部分享 | 仅获得站点链接和访问码的人员可以访问。访问码为 6～12 位字母或数字。 |
| 公开分享 | 任何获得站点链接的人都可以直接访问，且站点内容可被搜索引擎索引。公开分享前需要先绑定自定义域名。 |

### IP 限制

| 限制方式 | 访问规则 |
| --- | --- |
| 不限制 IP | 允许来自任何 IP 地址的访问请求。 |
| 自定义白名单 | 仅允许名单中的 IP 地址访问。 |
| 自定义黑名单 | 拒绝名单中的 IP 地址访问。 |

白名单和黑名单支持单个 IPv4 地址、IP 地址段和 CIDR 网段，每行填写一条，例如：

```text
192.168.1.1
192.168.1.10-192.168.1.100
192.168.1.0/24
```

![配置分享方式和 IP 限制](https://cdnv2-cache.udelivrs.com/2026/08/1e4dffda5901378faa3b43ae7218f6e9_1787118901566.png)

## 访问已部署的站点

Agent 完成部署后，会在站点内验证服务，并返回实际访问地址。在浏览器中打开该地址即可访问页面。

部署成功后，星图控制台中的站点状态会变为【已上线】，您也可以直接从控制台打开站点地址。

![站点状态为已上线](https://cdnv2-cache.udelivrs.com/2026/08/a465f61c1d4291c5fbdbf8e881e76768_1787118901583.png)

> 如果 Agent 返回了地址，但页面无法打开，请让 Agent 继续检查服务进程、80 端口、监听地址和服务日志，并在站点内访问成功后再确认部署完成。