OpenClaw - Arcane Docker 管理技能

概述

此技能使您能够通过 Arcane Docker 管理 API 来管理 Docker 容器、Compose 堆栈、模板、网络、卷、镜像以及系统监控。Arcane 是一个功能全面的 Docker 管理平台，提供 REST API。

使用场景

当用户请求以下任何操作时，可使用此技能：
- 管理 Docker 容器（列出、启动、停止、重启、删除、检查）
- 管理 Docker Compose 堆栈（部署、更新、删除、查看日志）
- 处理 Docker 模板（创建、部署、管理）
- 管理 Docker 镜像（列出、拉取、删除、清理）
- 管理 Docker 网络和卷
- 监控系统资源和 Docker 统计信息
- 管理用户账户和 API 密钥
- 查看系统日志和事件

API 配置

基础 URL

API 基础 URL 应由用户配置。默认值：http://localhost:3552/api

认证

Arcane 支持两种认证方式：

1. Bearer Token (JWT)：通过登录端点获取
2. API 密钥：使用 X-API-Key 请求头进行长期认证

获取 Bearer Token

curl -X POST "$BASE_URL/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your_password"
  }'

响应包含 token、refreshToken 和 expiresAt。

使用 API 密钥

可通过 /apikeys 端点创建和管理 API 密钥。使用 X-API-Key 请求头进行认证。

核心功能

1. 容器管理

列出容器

# 获取所有容器
curl -X GET "$BASE_URL/containers" \
  -H "Authorization: Bearer $TOKEN"

# 按状态过滤
curl -X GET "$BASE_URL/containers?status=running" \
  -H "Authorization: Bearer $TOKEN"

# 搜索容器
curl -X GET "$BASE_URL/containers?search=nginx" \
  -H "Authorization: Bearer $TOKEN"

容器操作

# 启动容器
curl -X POST "$BASE_URL/containers/{id}/start" \
  -H "Authorization: Bearer $TOKEN"

# 停止容器
curl -X POST "$BASE_URL/containers/{id}/stop" \
  -H "Authorization: Bearer $TOKEN"

# 重启容器
curl -X POST "$BASE_URL/containers/{id}/restart" \
  -H "Authorization: Bearer $TOKEN"

# 删除容器
curl -X DELETE "$BASE_URL/containers/{id}" \
  -H "Authorization: Bearer $TOKEN"

# 获取容器详情
curl -X GET "$BASE_URL/containers/{id}" \
  -H "Authorization: Bearer $TOKEN"

# 获取容器日志
curl -X GET "$BASE_URL/containers/{id}/logs?tail=100" \
  -H "Authorization: Bearer $TOKEN"

# 获取容器统计信息
curl -X GET "$BASE_URL/containers/{id}/stats" \
  -H "Authorization: Bearer $TOKEN"

高级容器操作

# 在容器内执行命令
curl -X POST "$BASE_URL/containers/{id}/exec" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": ["ls", "-la"],
    "workingDir": "/app"
  }'

# 重命名容器
curl -X POST "$BASE_URL/containers/{id}/rename" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-container-name"
  }'

# 更新容器资源
curl -X POST "$BASE_URL/containers/{id}/update" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cpuShares": 512,
    "memory": 536870912,
    "restartPolicy": "unless-stopped"
  }'

2. Docker Compose 堆栈管理

列出堆栈

curl -X GET "$BASE_URL/stacks" \
  -H "Authorization: Bearer $TOKEN"

从模板部署堆栈

curl -X POST "$BASE_URL/stacks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-stack",
    "templateId": "template-id",
    "envVars": {
      "PORT": "8080",
      "DATABASE_URL": "postgres://..."
    }
  }'

从 Compose 文件部署堆栈

curl -X POST "$BASE_URL/stacks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-stack",
    "composeContent": "version: \"3.8\"\nservices:\n  web:\n    image: nginx:latest\n    ports:\n      - \"80:80\""
  }'

堆栈操作

# 获取堆栈详情
curl -X GET "$BASE_URL/stacks/{id}" \
  -H "Authorization: Bearer $TOKEN"

# 更新堆栈
curl -X PUT "$BASE_URL/stacks/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "envVars": {
      "PORT": "9090"
    }
  }'

# 删除堆栈
curl -X DELETE "$BASE_URL/stacks/{id}" \
  -H "Authorization: Bearer $TOKEN"

# 启动堆栈
curl -X POST "$BASE_URL/stacks/{id}/start" \
  -H "Authorization: Bearer $TOKEN"

# 停止堆栈
curl -X POST "$BASE_URL/stacks/{id}/stop" \
  -H "Authorization: Bearer $TOKEN"

# 重启堆栈
curl -X POST "$BASE_URL/stacks/{id}/restart" \
  -H "Authorization: Bearer $TOKEN"

# 获取堆栈日志
curl -X GET "$BASE_URL/stacks/{id}/logs?tail=100" \
  -H "Authorization: Bearer $TOKEN"

# 为堆栈拉取最新镜像
curl -X POST "$BASE_URL/stacks/{id}/pull" \
  -H "Authorization: Bearer $TOKEN"

3. 模板管理

列出模板

curl -X GET "$BASE_URL/templates" \
  -H "Authorization: Bearer $TOKEN"

创建模板

curl -X POST "$BASE_URL/templates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nginx-template",
    "description": "基础 nginx 网页服务器",
    "content": "version: \"3.8\"\nservices:\n  web:\n    image: nginx:{{VERSION}}\n    ports:\n      - \"{{PORT}}:80\"",
    "variables": [
      {
        "name": "VERSION",
        "description": "Nginx 版本",
        "defaultValue": "latest"
      },
      {
        "name": "PORT",
        "description": "主机端口",
        "defaultValue": "80"
      }
    ],
    "category": "web-servers",
    "tags": ["nginx", "web"]
  }'

模板操作

# 获取模板
curl -X GET "$BASE_URL/templates/{id}" \
  -H "Authorization: Bearer $TOKEN"

# 更新模板
curl -X PUT "$BASE_URL/templates/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated-template-name",
    "description": "更新后的描述"
  }'

# 删除模板
curl -X DELETE "$BASE_URL/templates/{id}" \
  -H "Authorization: Bearer $TOKEN"

# 获取已解析变量的模板内容
curl -X GET "$BASE_URL/templates/{id}/content" \
  -H "Authorization: Bearer $TOKEN"

全局模板变量

# 获取全局变量
curl -X GET "$BASE_URL/templates/global-variables" \
  -H "Authorization: Bearer $TOKEN"

# 更新全局变量
curl -X PUT "$BASE_URL/templates/global-variables" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "GLOBAL_DOMAIN": "example.com",
    "GLOBAL_NETWORK": "traefik-public"
  }'

4. 镜像管理

列出镜像

curl -X GET "$BASE_URL/images" \
  -H "Authorization: Bearer $TOKEN"

拉取镜像

curl -X POST "$BASE_URL/images/pull" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "nginx:latest"
  }'

镜像操作

# 获取镜像详情
curl -X GET "$BASE_URL/images/{id}" \
  -H "Authorization: Bearer $TOKEN"

# 删除镜像
curl -X DELETE "$BASE_URL/images/{id}" \
  -H "Authorization: Bearer $TOKEN"

# 清理未使用的镜像
curl -X POST "$BASE_URL/images/prune" \
  -H "Authorization: Bearer $TOKEN"

# 在注册表中搜索镜像
curl -X GET "$BASE_URL/images/search?term=nginx" \
  -H "Authorization: Bearer $TOKEN"

5. 网络管理

列出网络

curl -X GET "$BASE_URL/networks" \
  -H "Authorization: Bearer $TOKEN"

创建网络

curl -X POST "$BASE_URL/networks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-network",
    "driver": "bridge",
    "internal": false,
    "attachable": true
  }'

网络操作

# 获取网络详情
curl -X GET "$BASE_URL/networks/{id}" \
  -H "Authorization: Bearer $TOKEN"

# 删除网络
curl -X DELETE "$BASE_URL/networks/{id}" \
  -H "Authorization: Bearer $TOKEN"

# 将容器连接到网络
curl -X POST "$BASE_URL/networks/{id}/connect" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "containerId": "container-id"
  }'

# 将容器从网络断开连接
curl -X POST "$BASE_URL/networks/{id}/disconnect" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "containerId": "container-id"
  }'

# 清理未使用的网络
curl -X POST "$BASE_URL/networks/prune" \
  -H "Authorization: Bearer $TOKEN"

6. 卷管理

列出卷

curl -X GET "$BASE_URL/volumes" \
  -H "Authorization: Bearer $TOKEN"

创建卷

curl -X POST "$BASE_URL/volumes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-volume",
    "driver": "local",
    "labels": {
      "project": "my-app"
    }
  }'

卷操作

# 获取卷详情
curl -X GET "$BASE_URL/volumes/{name}" \
  -H "Authorization: Bearer $TOKEN"

# 删除卷
curl -X DELETE "$BASE_URL/volumes/{name}" \
  -H "Authorization: Bearer $TOKEN"

# 清理未使用的卷
curl -X POST "$BASE_URL/volumes/prune" \
  -H "Authorization: Bearer $TOKEN"

7. 系统监控

系统信息

# 获取 Docker 系统信息
curl -X GET "$BASE_URL/system/info" \
  -H "Authorization: Bearer $TOKEN"

# 获取 Docker 版本
curl -X GET "$BASE_URL/system/version" \
  -H "Authorization: Bearer $TOKEN"

# 获取系统统计信息
curl -X GET "$BASE_URL/system/stats" \
  -H "Authorization: Bearer $TOKEN"

# 获取磁盘使用情况
curl -X GET "$BASE_URL/system/df" \
  -H "Authorization: Bearer $TOKEN"

事件和日志

# 获取系统事件（流式）
curl -X GET "$BASE_URL/system/events" \
  -H "Authorization: Bearer $TOKEN"

# 使用过滤器获取事件
curl -X GET "$BASE_URL/system/events?since=1609459200&type=container" \
  -H "Authorization: Bearer $TOKEN"

8. 用户管理

列出用户

curl -X GET "$BASE_URL/users" \
  -H "Authorization: Bearer $TOKEN"

创建用户

curl -X POST "$BASE_URL/users" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "user@example.com",
    "password": "securepassword123",
    "role": "user"
  }'

用户操作

# 获取用户详情
curl -X GET "$BASE_URL/users/{userId}" \
  -H "Authorization: Bearer $TOKEN"

# 更新用户
curl -X PUT "$BASE_URL/users/{userId}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newemail@example.com",
    "role": "admin"
  }'

# 删除用户
curl -X DELETE "$BASE_URL/users/{userId}" \
  -H "Authorization: Bearer $TOKEN"

# 更改密码
curl -X PUT "$BASE_URL/auth/password" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "oldpassword",
    "newPassword": "newpassword123"
  }'

9. API 密钥管理

列出 API 密钥

curl -X GET "$BASE_URL/apikeys" \
  -H "Authorization: Bearer $TOKEN"

创建 API 密钥

curl -X POST "$BASE_URL/apikeys" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD 流水线密钥",
    "description": "用于自动化部署的 API 密钥",
    "expiresAt": "2025-12-31T23:59:59Z"
  }'

API 密钥操作

# 获取 API 密钥详情
curl -X GET "$BASE_URL/apikeys/{id}" \
  -H "Authorization: Bearer $TOKEN"

# 更新 API 密钥
curl -X PUT "$BASE_URL/apikeys/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "更新后的密钥名称",
    "description": "更新后的描述"
  }'

# 删除 API 密钥
curl -X DELETE "$BASE_URL/apikeys/{id}" \
  -H "Authorization: Bearer $TOKEN"

实现指南

错误处理

所有 API 响应遵循标准格式：

{
  "success": true|false,
  "data": {...},
  "message": "成功或错误消息"
}

错误响应使用 HTTP 问题详情 (RFC 7807)：

{
  "type": "about:blank",
  "title": "错误标题",
  "status": 400,
  "detail": "详细的错误消息"
}

分页

列表端点支持以下查询参数进行分页：
- start：起始索引（默认：0）
- limit：每页项目数（默认：20）
- sort：排序依据的列
- order：排序方向（asc/desc，默认：asc）
- search：搜索查询

响应包含分页元数据：

{
  "success": true,
  "data": [...],
  "pagination": {
    "start": 0,
    "limit": 20,
    "total": 100,
    "hasMore": true
  }
}

使用 Python

在 Python 中实现 Arcane 操作时，请使用 requests 库：

```python
import requests

BASE_URL = "http://localhost:3552/api"
TOKEN = "your-jwt-token"

headers = {
"Authorization": f"Bearer {TOKEN}",
"Content-Type": "application/json"
}

列出容器

response = requests.get(f"{BASE_URL}/containers", headers=headers)
containers = response.json()

部署堆栈

stack_data =