> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberun.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 调用容器服务

> 三种方式访问正在运行的容器服务 —— 透明代理、结构化 invoke、服务发现。

**容器服务**是托管在你团队代理上的长时运行容器（概念见
[容器服务](/zh/cloud/concepts/containers)，部署流程见
[部署容器服务](/zh/cloud/guides/deploy-container)）。

当服务进入 `running` 状态后，三个运行时端点可以访问它。
全部接受 JWT、`sk-`、`dk-` 作为 Bearer 凭证。

## 服务发现

列出你团队可见的服务：

```http theme={null}
GET /api/v1/r/containers HTTP/1.1
Authorization: Bearer sk-...
```

或按 slug 查询单个服务：

```http theme={null}
GET /api/v1/r/containers/{serviceSlug} HTTP/1.1
Authorization: Bearer sk-...
```

响应中的关键字段：

| 字段               | 含义                                                                |
| ---------------- | ----------------------------------------------------------------- |
| `service_slug`   | URL 安全的标识。用在代理和 invoke 路径中。                                       |
| `service_status` | `created`、`deploying`、`running`、`stopping`、`stopped`、`failed` 之一。 |
| `exposed_port`   | 容器内部监听的端口。                                                        |
| `service_type`   | `deployed`（运行在团队代理上）或 `external`（出口到外部 URL）。                      |
| `usage_prompt`   | 可选的面向 AI 代理的自然语言描述。能列出该服务的任何成员都能读到 —— 不要在这里放密钥。                   |
| `openapi_url`    | 可选的、容器上提供 OpenAPI 文档的路径。AI 客户端可在调用前抓取它取得 schema。                  |

## 透明代理

对于 shell 脚本、原始 HTTP 客户端、以及任何已经能讲容器协议的代码，
使用 catch-all 代理：

```
ANY /api/v1/r/containers/{serviceSlug}/*
```

slug 之后的路径会原样转发到容器，容器的响应也原样返回。

```bash theme={null}
# vLLM 暴露 OpenAI 兼容 API
curl -H "Authorization: Bearer sk-..." \
  https://core.cyberun.cloud/api/v1/r/containers/my-llm/v1/models

curl -X POST \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"llama3","messages":[{"role":"user","content":"hi"}]}' \
  https://core.cyberun.cloud/api/v1/r/containers/my-llm/v1/chat/completions
```

由于代理保留了 OpenAI 的请求和响应结构，你可以把任意 OpenAI 兼容
SDK 的 `baseURL` 直接指向代理：

```ts theme={null}
import OpenAI from 'openai';

const client = new OpenAI({
	apiKey: process.env.CYBERUN_KEY,
	baseURL: 'https://core.cyberun.cloud/api/v1/r/containers/my-llm'
});

const reply = await client.chat.completions.create({
	model: 'llama3',
	messages: [{ role: 'user', content: 'hi' }]
});
```

任何底层 HTTP 形状与容器暴露的协议匹配的厂商 SDK 都可以用同样的方式。

## 结构化 invoke（适合 MCP）

对于希望使用单一固定请求形状（而非 catch-all 路径）的程序化客户端
和 MCP 调用方：

```http theme={null}
POST /api/v1/r/invoke/{serviceSlug} HTTP/1.1
Authorization: Bearer sk-...
Content-Type: application/json

{
  "method": "POST",
  "path": "/v1/chat/completions",
  "headers": { "Content-Type": "application/json" },
  "body_base64": "eyJtb2RlbCI6Imxsb..."
}
```

请求体字段：

| 字段            | 必填 | 含义                                                                                   |
| ------------- | -- | ------------------------------------------------------------------------------------ |
| `method`      | 是  | HTTP 方法（`GET`、`POST`、`PUT`、`PATCH`、`DELETE`、`HEAD`、`OPTIONS`）。                       |
| `path`        | 是  | 容器上的路径，含开头的 `/`。允许查询串。绝对 URL 或协议相对 URL 会被拒绝。                                         |
| `body_base64` | 否  | 请求体，base64 编码以让二进制数据安全穿过 JSON。`GET` / `DELETE` 可省略。                                  |
| `headers`     | 否  | 要转发的请求头。逐跳头（`Host`、`Connection`、`Upgrade`、`Transfer-Encoding`、`TE`、`Trailer`）服务端会剥离。 |

响应：

```json theme={null}
{
  "status_code": 200,
  "headers": { "Content-Type": "application/json" },
  "body_base64": "eyJjaG9pY2VzIjpbey4uLn1dfQ=="
}
```

`/r/invoke/{slug}` 单独占用一条路径，而不是
`/r/containers/{slug}/invoke` —— 这样如果容器自身暴露了 `/invoke`
端点，它仍然可以通过 catch-all 代理访问。

### 何时用哪个

| 场景                                     | 用法               |
| -------------------------------------- | ---------------- |
| shell 脚本、`curl`、OpenAI SDK baseURL 重定向 | 透明代理             |
| 用固定请求形状把服务接进 MCP 工具                    | 结构化 `/r/invoke/` |
| 从非流式调用方转发二进制负载                         | 结构化 `/r/invoke/` |

## 状态码

两个端点都会在请求到达容器之前用这些代码暴露网关层错误：

| 状态码   | 含义                                                                            |
| ----- | ----------------------------------------------------------------------------- |
| `400` | 服务未处于 `running` 状态（仍在 `created`、`deploying`、`stopping`、`stopped` 或 `failed`）。 |
| `404` | 此团队中找不到该 service slug。                                                        |
| `502` | 代理或网关隧道与容器通信时返回错误。                                                            |
| `503` | 服务正在运行但不可用 —— 没有健康实例,或没有在线代理能访问它。                                             |

其他状态码都是容器自己返回的。

## 相关

* [容器服务](/zh/cloud/concepts/containers) —— 数据模型。
* [部署容器服务](/zh/cloud/guides/deploy-container) —— 创建与部署。
* [API 参考](/zh/api-reference/introduction) —— 完整端点列表。