OpenClaw - 奥术 Docker 管理技能

概述

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

何时使用此技能

当用户提出以下任何请求时，使用此技能：

• 管理 Docker 容器（列出、启动、停止、重启、删除、检查）
• 管理 Docker Compose 堆栈（部署、更新、删除、查看日志）
• 处理 Docker 模板（创建、部署、管理）
• 管理 Docker 镜像（列出、拉取、删除、清理）
• 管理 Docker 网络和卷
• 监控系统资源和 Docker 统计信息
• 管理用户账户和 API 密钥
• 查看系统日志和事件

API 配置

基础 URL

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

认证

Arcane 支持两种认证方式：

1. 承载令牌 (JWT)：通过登录接口获取
2. API 密钥：使用X-API-Key请求头进行长期认证

获取承载令牌

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. 容器管理

列出容器

# Get all containers
curl -X GET "$BASE_URL/containers" \
  -H "Authorization: Bearer $TOKEN"

# Filter by status
curl -X GET "$BASE_URL/containers?status=running" \
  -H "Authorization: Bearer $TOKEN"

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

容器操作

# Start container
curl -X POST "$BASE_URL/containers/{id}/start" \
  -H "Authorization: Bearer $TOKEN"

# Stop container
curl -X POST "$BASE_URL/containers/{id}/stop" \
  -H "Authorization: Bearer $TOKEN"

# Restart container
curl -X POST "$BASE_URL/containers/{id}/restart" \
  -H "Authorization: Bearer $TOKEN"

# Remove container
curl -X DELETE "$BASE_URL/containers/{id}" \
  -H "Authorization: Bearer $TOKEN"

# Get container details
curl -X GET "$BASE_URL/containers/{id}" \
  -H "Authorization: Bearer $TOKEN"

# Get container logs
curl -X GET "$BASE_URL/containers/{id}/logs?tail=100" \
  -H "Authorization: Bearer $TOKEN"

# Get container stats
curl -X GET "$BASE_URL/containers/{id}/stats" \
  -H "Authorization: Bearer $TOKEN"

高级容器操作

# Execute command in container
curl -X POST "$BASE_URL/containers/{id}/exec" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": ["ls", "-la"],
    "workingDir": "/app"
  }'

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

# Update container resources
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\""
  }'

堆栈操作

# Get stack details
curl -X GET "$BASE_URL/stacks/{id}" \
  -H "Authorization: Bearer $TOKEN"

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

# Remove stack
curl -X DELETE "$BASE_URL/stacks/{id}" \
  -H "Authorization: Bearer $TOKEN"

# Start stack
curl -X POST "$BASE_URL/stacks/{id}/start" \
  -H "Authorization: Bearer $TOKEN"

# Stop stack
curl -X POST "$BASE_URL/stacks/{id}/stop" \
  -H "Authorization: Bearer $TOKEN"

# Restart stack
curl -X POST "$BASE_URL/stacks/{id}/restart" \
  -H "Authorization: Bearer $TOKEN"

# Get stack logs
curl -X GET "$BASE_URL/stacks/{id}/logs?tail=100" \
  -H "Authorization: Bearer $TOKEN"

# Pull latest images for stack
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": "Basic nginx web server",
    "content": "version: \"3.8\"\nservices:\n  web:\n    image: nginx:{{VERSION}}\n    ports:\n      - \"{{PORT}}:80\"",
    "variables": [
      {
        "name": "VERSION",
        "description": "Nginx version",
        "defaultValue": "latest"
      },
      {
        "name": "PORT",
        "description": "Host port",
        "defaultValue": "80"
      }
    ],
    "category": "web-servers",
    "tags": ["nginx", "web"]
  }'

模板操作

# Get template
curl -X GET "$BASE_URL/templates/{id}" \
  -H "Authorization: Bearer $TOKEN"

# Update template
curl -X PUT "$BASE_URL/templates/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated-template-name",
    "description": "Updated description"
  }'

# Delete template
curl -X DELETE "$BASE_URL/templates/{id}" \
  -H "Authorization: Bearer $TOKEN"

# Get template content with parsed variables
curl -X GET "$BASE_URL/templates/{id}/content" \
  -H "Authorization: Bearer $TOKEN"

全局模板变量

# Get global variables
curl -X GET "$BASE_URL/templates/global-variables" \
  -H "Authorization: Bearer $TOKEN"

# Update global variables
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"
  }'

镜像操作

# Get image details
curl -X GET "$BASE_URL/images/{id}" \
  -H "Authorization: Bearer $TOKEN"

# Remove image
curl -X DELETE "$BASE_URL/images/{id}" \
  -H "Authorization: Bearer $TOKEN"

# Prune unused images
curl -X POST "$BASE_URL/images/prune" \
  -H "Authorization: Bearer $TOKEN"

# Search images in registry
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
  }'

网络操作

# Get network details
curl -X GET "$BASE_URL/networks/{id}" \
  -H "Authorization: Bearer $TOKEN"

# Remove network
curl -X DELETE "$BASE_URL/networks/{id}" \
  -H "Authorization: Bearer $TOKEN"

# Connect container to network
curl -X POST "$BASE_URL/networks/{id}/connect" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "containerId": "container-id"
  }'

# Disconnect container from network
curl -X POST "$BASE_URL/networks/{id}/disconnect" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "containerId": "container-id"
  }'

# Prune unused networks
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"
    }
  }'

卷操作

# Get volume details
curl -X GET "$BASE_URL/volumes/{name}" \
  -H "Authorization: Bearer $TOKEN"

# Remove volume
curl -X DELETE "$BASE_URL/volumes/{name}" \
  -H "Authorization: Bearer $TOKEN"

# Prune unused volumes
curl -X POST "$BASE_URL/volumes/prune" \
  -H "Authorization: Bearer $TOKEN"

7. 系统监控

系统信息

# Get Docker system info
curl -X GET "$BASE_URL/system/info" \
  -H "Authorization: Bearer $TOKEN"

# Get Docker version
curl -X GET "$BASE_URL/system/version" \
  -H "Authorization: Bearer $TOKEN"

# Get system stats
curl -X GET "$BASE_URL/system/stats" \
  -H "Authorization: Bearer $TOKEN"

# Get disk usage
curl -X GET "$BASE_URL/system/df" \
  -H "Authorization: Bearer $TOKEN"

事件与日志

# Get system events (streaming)
curl -X GET "$BASE_URL/system/events" \
  -H "Authorization: Bearer $TOKEN"

# Get events with filters
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"
  }'

用户操作

# Get user details
curl -X GET "$BASE_URL/users/{userId}" \
  -H "Authorization: Bearer $TOKEN"

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

# Delete user
curl -X DELETE "$BASE_URL/users/{userId}" \
  -H "Authorization: Bearer $TOKEN"

# Change password
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 Pipeline Key",
    "description": "API key for automated deployments",
    "expiresAt": "2025-12-31T23:59:59Z"
  }'

API密钥操作

# Get API key details
curl -X GET "$BASE_URL/apikeys/{id}" \
  -H "Authorization: Bearer $TOKEN"

# Update API key
curl -X PUT "$BASE_URL/apikeys/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Key Name",
    "description": "Updated description"
  }'

# Delete API key
curl -X DELETE "$BASE_URL/apikeys/{id}" \
  -H "Authorization: Bearer $TOKEN"

实施指南

错误处理

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

{
  "success": true|false,
  "data": {...},
  "message": "Success or error message"
}

错误响应使用HTTP问题详情：

{
  "type": "about:blank",
  "title": "Error title",
  "status": 400,
  "detail": "Detailed error message"
}

分页

列表端点支持以下查询参数进行分页：

• 起始索引: 起始索引
• 限制: 每页项目数
• 排序: 排序依据的列
• 顺序排序方向（升序/降序，默认：升序）
• 搜索: 搜索查询

响应包含分页元数据：

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

使用 Python

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

import requests

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

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

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

# Deploy stack
stack_data = {
    "name": "my-stack",
    "templateId": "template-id",
    "envVars": {
        "PORT": "8080"
    }
}
response = requests.post(f"{BASE_URL}/stacks", headers=headers, json=stack_data)
result = response.json()

使用 Bash

对于简单操作，使用 curl 并处理错误：

#!/bin/bash

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

# Function to make authenticated requests
api_call() {
    local method=$1
    local endpoint=$2
    local data=$3
    
    if [ -z "$data" ]; then
        curl -s -X "$method" "$BASE_URL/$endpoint" \
            -H "Authorization: Bearer $TOKEN"
    else
        curl -s -X "$method" "$BASE_URL/$endpoint" \
            -H "Authorization: Bearer $TOKEN" \
            -H "Content-Type: application/json" \
            -d "$data"
    fi
}

# Example: List containers
containers=$(api_call GET "containers")
echo "$containers" | jq '.data[] | {id, name, status}'

常见工作流程

1. 部署应用栈

# 1. Create or select template
template_data = {
    "name": "webapp-template",
    "content": "version: '3.8'\nservices:\n  web:\n    image: myapp:{{VERSION}}\n    ports:\n      - '{{PORT}}:8080'",
    "variables": [
        {"name": "VERSION", "defaultValue": "latest"},
        {"name": "PORT", "defaultValue": "80"}
    ]
}
template = requests.post(f"{BASE_URL}/templates", headers=headers, json=template_data).json()

# 2. Deploy stack from template
stack_data = {
    "name": "production-webapp",
    "templateId": template["data"]["id"],
    "envVars": {
        "VERSION": "v1.2.3",
        "PORT": "8080"
    }
}
stack = requests.post(f"{BASE_URL}/stacks", headers=headers, json=stack_data).json()

# 3. Monitor deployment
stack_id = stack["data"]["id"]
logs = requests.get(f"{BASE_URL}/stacks/{stack_id}/logs?tail=50", headers=headers).json()

2. 扩展与监控容器

# Get running containers
containers = requests.get(f"{BASE_URL}/containers?status=running", headers=headers).json()

# Get stats for each container
for container in containers["data"]:
    stats = requests.get(f"{BASE_URL}/containers/{container['id']}/stats", headers=headers).json()
    print(f"{container['name']}: CPU {stats['data']['cpuPercent']:.2f}%, Memory {stats['data']['memoryPercent']:.2f}%")

# Update container resources if needed
update_data = {
    "cpuShares": 1024,
    "memory": 1073741824  # 1GB
}
requests.post(f"{BASE_URL}/containers/{container_id}/update", headers=headers, json=update_data)

3. 清理与维护

# Prune unused resources
requests.post(f"{BASE_URL}/images/prune", headers=headers)
requests.post(f"{BASE_URL}/volumes/prune", headers=headers)
requests.post(f"{BASE_URL}/networks/prune", headers=headers)

# Get disk usage before and after
df_before = requests.get(f"{BASE_URL}/system/df", headers=headers).json()
# ... perform cleanup ...
df_after = requests.get(f"{BASE_URL}/system/df", headers=headers).json()

最佳实践

1. 身份验证: 自动化脚本和服务始终使用 API 密钥。交互式会话使用 JWT 令牌。

2. 错误处理: 检查响应状态码并适当处理错误：

   • 200: 成功
   • 400: 错误请求（验证错误）
   • 401: 未授权
   • 403: 禁止访问
   • 404: 未找到
   • 500: 内部服务器错误

3. 资源管理:

   • 创建容器时务必指定资源限制
   • 使用标签来组织资源
   • 定期清理未使用的资源

4. 安全:

   • 安全存储API密钥和令牌（使用环境变量）
   • 生产环境使用HTTPS
   • 通过用户角色实施适当的访问控制
   • 定期轮换API密钥

5. 监控:

   • 定期监控容器状态
   • 设置资源使用告警
   • 定期审查系统日志

6. 模板:

   • 对可配置值使用变量
   • 明确文档模板变量
   • 对模板进行版本控制
   • 对共享配置使用全局变量

故障排除

常见问题

身份验证失败

• 验证令牌是否未过期（检查expiresAt）
• 使用刷新令牌获取新的访问令牌
• 验证API密钥是否正确且未过期

容器无法启动

• 检查容器日志：GET /containers/{id}/logs
• 检查容器：GET /containers/{id}
• 验证端口冲突和资源可用性

堆栈部署失败

• 验证compose文件语法
• 检查模板变量是否正确定义
• 查看堆栈日志：GET /stacks/{id}/logs

资源未找到

• 请确认资源ID是否正确
• 检查资源是否已被删除
• 确保具备相应权限

注意事项

• 所有时间戳均采用ISO 8601格式（UTC时区）
• 容器ID支持完整格式或短格式（前12个字符）
• 镜像名称支持完整注册表路径（registry.example.com/image:tag）
• 网络和存储卷名称必须保持唯一性
• 每个用户/项目中的堆栈名称必须唯一

参考链接

完整的API文档及模式定义，请参阅JSON模式中提供的OpenAPI规范。