garage-webui/docs/garage-admin-api.md

Garage Admin API 文档

概述

Garage Administration API 是一个用于编程式管理 Garage 集群的 REST API，提供了完整的集群管理、存储桶管理、访问控制等功能。当前版本为 v2，API 基础地址通常为 http://localhost:3903。

认证方式

Bearer Token 认证

所有 API 请求都需要在 HTTP 头中包含认证信息：

Authorization: Bearer <token>

Token 类型

1. 用户定义 Token（推荐）

   • 可动态创建和管理
   • 支持作用域限制
   • 支持过期时间设置
   • 使用 garage admin-token 命令创建

2. 主 Token（已废弃）

   • 在配置文件中指定
   • admin_token: 管理端点访问
   • metrics_token: 指标端点访问

创建用户定义 Token 示例

garage admin-token create --expires-in 30d \
    --scope ListBuckets,GetBucketInfo,ListKeys,GetKeyInfo,CreateBucket,CreateKey,AllowBucketKey,DenyBucketKey \
    my-token

API 端点分类

1. 集群管理 (Cluster)

获取集群健康状态

• 端点: GET /v2/GetClusterHealth
• 描述: 返回集群全局状态，包括连接节点数、健康存储节点数、分区状态等
• 响应示例:

{
  "status": "healthy",
  "knownNodes": 3,
  "connectedNodes": 3,
  "storageNodes": 3,
  "storageNodesOk": 3,
  "partitions": 256,
  "partitionsQuorum": 256,
  "partitionsAllOk": 256
}

获取集群状态

• 端点: GET /v2/GetClusterStatus
• 描述: 返回详细的集群状态信息，包括节点信息和布局配置

获取集群统计

• 端点: GET /v2/GetClusterStatistics
• 描述: 获取集群级别的统计数据

连接集群节点

• 端点: POST /v2/ConnectClusterNodes
• 描述: 指示当前节点连接到其他 Garage 节点
• 请求体: 节点地址数组 ["<node_id>@<net_address>"]

2. 集群布局管理 (Cluster Layout)

获取集群布局

• 端点: GET /v2/GetClusterLayout
• 描述: 返回当前集群布局配置和待处理的变更

更新集群布局

• 端点: POST /v2/UpdateClusterLayout
• 描述: 提交集群布局变更到暂存区
• 请求体示例:

{
  "roles": [
    {
      "id": "node-id",
      "zone": "zone1",
      "capacity": 100000000000,
      "tags": ["tag1", "tag2"]
    }
  ]
}

应用布局变更

• 端点: POST /v2/ApplyClusterLayout
• 描述: 将暂存的布局变更应用到集群
• 请求体: {"version": <layout_version>}

预览布局变更

• 端点: POST /v2/PreviewClusterLayoutChanges
• 描述: 预览布局变更的影响，不实际应用

回滚布局变更

• 端点: POST /v2/RevertClusterLayout
• 描述: 清除所有暂存的布局变更

获取布局历史

• 端点: GET /v2/GetClusterLayoutHistory
• 描述: 获取集群布局的历史版本信息

3. 存储桶管理 (Bucket)

列出所有存储桶

• 端点: GET /v2/ListBuckets
• 描述: 返回集群中所有存储桶及其别名

获取存储桶信息

• 端点: GET /v2/GetBucketInfo
• 参数:
  • id: 存储桶 ID
  • globalAlias: 全局别名
  • search: 搜索模式
• 描述: 获取存储桶详细信息，包括权限、统计、配额等

创建存储桶

• 端点: POST /v2/CreateBucket
• 请求体示例:

{
  "globalAlias": "my-bucket",
  "localAlias": {
    "accessKeyId": "key-id",
    "alias": "local-name",
    "allow": {
      "read": true,
      "write": true,
      "owner": false
    }
  }
}

更新存储桶

• 端点: POST /v2/UpdateBucket/{id}
• 描述: 更新存储桶的网站配置和配额设置
• 请求体示例:

{
  "websiteAccess": {
    "enabled": true,
    "indexDocument": "index.html",
    "errorDocument": "error.html"
  },
  "quotas": {
    "maxSize": 1000000000,
    "maxObjects": 10000
  }
}

删除存储桶

• 端点: POST /v2/DeleteBucket/{id}
• 描述: 删除空存储桶（会删除所有关联别名）

清理未完成上传

• 端点: POST /v2/CleanupIncompleteUploads
• 请求体: {"bucketId": "bucket-id", "olderThanSecs": 86400}

检查对象

• 端点: GET /v2/InspectObject
• 参数: bucketId, key
• 描述: 获取对象的详细内部状态信息

4. 存储桶别名管理 (Bucket Alias)

添加存储桶别名

• 端点: POST /v2/AddBucketAlias
• 描述: 为存储桶添加全局或本地别名

移除存储桶别名

• 端点: POST /v2/RemoveBucketAlias
• 描述: 移除存储桶的别名

5. 访问密钥管理 (Access Key)

列出访问密钥

• 端点: GET /v2/ListKeys
• 描述: 返回所有 API 访问密钥

获取密钥信息

• 端点: GET /v2/GetKeyInfo
• 参数:
  • id: 密钥 ID
  • search: 搜索模式
  • showSecretKey: 是否返回密钥（默认不返回）

创建访问密钥

• 端点: POST /v2/CreateKey
• 请求体示例:

{
  "name": "my-key",
  "allow": {
    "createBucket": true
  }
}

更新访问密钥

• 端点: POST /v2/UpdateKey/{id}
• 描述: 更新密钥的名称、权限和过期时间

删除访问密钥

• 端点: POST /v2/DeleteKey/{id}
• 描述: 从集群中删除访问密钥

导入访问密钥

• 端点: POST /v2/ImportKey
• 描述: 导入已有的访问密钥（仅用于迁移和备份恢复）

6. 权限管理 (Permission)

授予权限

• 端点: POST /v2/AllowBucketKey
• 描述: 授予密钥对存储桶的操作权限
• 请求体示例:

{
  "bucketId": "bucket-id",
  "accessKeyId": "key-id",
  "permissions": {
    "read": true,
    "write": true,
    "owner": false
  }
}

拒绝权限

• 端点: POST /v2/DenyBucketKey
• 描述: 移除密钥对存储桶的操作权限

7. 管理员 Token 管理 (Admin API Token)

列出管理员 Token

• 端点: GET /v2/ListAdminTokens

获取 Token 信息

• 端点: GET /v2/GetAdminTokenInfo
• 参数: id 或 search

获取当前 Token 信息

• 端点: GET /v2/GetCurrentAdminTokenInfo

创建管理员 Token

• 端点: POST /v2/CreateAdminToken
• 请求体示例:

{
  "name": "my-admin-token",
  "expiration": "2025-12-31T23:59:59Z",
  "scope": ["ListBuckets", "GetBucketInfo", "CreateBucket"]
}

更新管理员 Token

• 端点: POST /v2/UpdateAdminToken/{id}

删除管理员 Token

• 端点: POST /v2/DeleteAdminToken/{id}

8. 节点管理 (Node)

获取节点信息

• 端点: GET /v2/GetNodeInfo/{node}
• 参数: node - 节点 ID、*（所有节点）或 self（当前节点）

获取节点统计

• 端点: GET /v2/GetNodeStatistics/{node}

创建元数据快照

• 端点: POST /v2/CreateMetadataSnapshot/{node}

启动修复操作

• 端点: POST /v2/LaunchRepairOperation/{node}
• 修复类型: tables, blocks, versions, multipartUploads, blockRefs, blockRc, rebalance, aliases

9. 后台工作进程管理 (Worker)

列出工作进程

• 端点: POST /v2/ListWorkers/{node}

获取工作进程信息

• 端点: POST /v2/GetWorkerInfo/{node}

获取工作进程变量

• 端点: POST /v2/GetWorkerVariable/{node}

设置工作进程变量

• 端点: POST /v2/SetWorkerVariable/{node}

10. 数据块管理 (Block)

获取数据块信息

• 端点: POST /v2/GetBlockInfo/{node}
• 请求体: {"blockHash": "hash-value"}

列出错误数据块

• 端点: GET /v2/ListBlockErrors/{node}

重试数据块同步

• 端点: POST /v2/RetryBlockResync/{node}

清除数据块

• 端点: POST /v2/PurgeBlocks/{node}
• 警告: 此操作会永久删除引用这些数据块的所有对象

11. 特殊端点 (Special Endpoints)

健康检查

• 端点: GET /health
• 认证: 无需认证
• 描述: 快速健康检查，返回 200 表示服务可用

Prometheus 指标

• 端点: GET /metrics
• 认证: 可选（使用 metrics_token）
• 描述: 返回 Prometheus 格式的监控指标

按需 TLS 检查

• 端点: GET /check?domain=<domain>
• 认证: 无需认证
• 描述: 用于反向代理（如 Caddy）的按需 TLS 证书验证

使用示例

使用 curl

# 获取集群健康状态
curl -H 'Authorization: Bearer YOUR_TOKEN' \
     http://localhost:3903/v2/GetClusterHealth

# 创建存储桶
curl -X POST \
     -H 'Authorization: Bearer YOUR_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"globalAlias": "my-bucket"}' \
     http://localhost:3903/v2/CreateBucket

# 列出所有存储桶
curl -H 'Authorization: Bearer YOUR_TOKEN' \
     http://localhost:3903/v2/ListBuckets

使用 Garage CLI

# 通过内部 RPC 调用（无需认证）
garage json-api GetClusterHealth

# 带参数的调用
garage json-api GetBucketInfo '{"globalAlias": "my-bucket"}'

# 从标准输入读取参数
garage json-api CreateBucket -
{"globalAlias": "test-bucket"}
<EOF>

错误处理

API 使用标准 HTTP 状态码：

• 200 OK - 请求成功
• 400 Bad Request - 请求参数错误
• 401 Unauthorized - 认证失败
• 403 Forbidden - 权限不足
• 404 Not Found - 资源不存在
• 500 Internal Server Error - 服务器内部错误

错误响应通常包含详细的错误信息：

{
  "error": "Bucket not found",
  "code": "BucketNotFound"
}

权限作用域

管理员 Token 可以限制访问特定的 API 端点：

• * - 允许所有端点
• ListBuckets - 列出存储桶
• GetBucketInfo - 获取存储桶信息
• CreateBucket - 创建存储桶
• ListKeys - 列出访问密钥
• CreateKey - 创建访问密钥
• AllowBucketKey - 授予权限
• DenyBucketKey - 拒绝权限
• Metrics - 访问指标端点

最佳实践

1. 使用用户定义 Token：避免使用配置文件中的主 Token
2. 设置适当的作用域：只授予必要的权限
3. 设置过期时间：定期轮换 Token
4. 监控 API 使用：通过 /metrics 端点监控 API 调用
5. 错误处理：妥善处理各种错误情况
6. 批量操作：对于大量操作，考虑使用批量 API 或脚本

版本历史

• v0 - Garage v0.7.2 首次引入（已废弃）
• v1 - Garage v0.9.0 引入（已废弃）
• v2 - Garage v2.0.0 引入（当前版本）

相关链接

• Garage 官方文档
• OpenAPI 规范 (HTML)
• OpenAPI 规范 (JSON)
• Garage 源代码