khairul169/garage-webui
1
0
Fork 0
mirror of https://github.com/khairul169/garage-webui.git synced 2025-10-14 14:59:32 +07:00
Code Issues Actions Packages Projects Releases Wiki Activity

Translate Garage Web UI project management documentation from Chinese to English and update content for clarity and consistency.

Browse Source
This commit is contained in:
Adekabang 2025-07-30 23:48:36 -04:00
parent c5669a9cf7
commit 642b20efb0
3 changed files with 654 additions and 657 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
docs/api-upgrade-report.md
View File

@ -1,21 +1,21 @@
# Garage Web UI API 升级报告
# Garage Web UI API Upgrade Report
## 升级概述
## Upgrade Overview
已成功将 Garage Web UI 项目从 Garage Admin API v1 升级到 v2 版本。
The Garage Web UI project has been successfully upgraded from Garage Admin API v1 to v2.
## 升级时间
## Upgrade Timeline
- 完成时间：2024 年 12 月
- 升级范围：前端 React hooks 中的所有 API 调用
- **Completion Date**: December 2024
- **Scope of Upgrade**: All API calls within the frontend React hooks
## 升级详情
## Upgrade Details
### 1. Home 页面 (`src/pages/home/hooks.ts`)
### 1. Home Page (`src/pages/home/hooks.ts`)
- ✅ `useNodesHealth`: `/v1/health` → `/v2/GetClusterHealth`
### 2. Cluster 页面 (`src/pages/cluster/hooks.ts`)
### 2. Cluster Page (`src/pages/cluster/hooks.ts`)
- ✅ `useClusterStatus`: `/v1/status` → `/v2/GetClusterStatus`
- ✅ `useClusterLayout`: `/v1/layout` → `/v2/GetClusterLayout`
@ -25,19 +25,19 @@
- ✅ `useRevertChanges`: `/v1/layout/revert` → `/v2/RevertClusterLayout`
- ✅ `useApplyChanges`: `/v1/layout/apply` → `/v2/ApplyClusterLayout`
### 3. Keys 页面 (`src/pages/keys/hooks.ts`)
### 3. Keys Page (`src/pages/keys/hooks.ts`)
- ✅ `useKeys`: `/v1/key?list` → `/v2/ListKeys`
- ✅ `useCreateKey`: `/v1/key` → `/v2/CreateKey`
- ✅ `useCreateKey` (导入): `/v1/key/import` → `/v2/ImportKey`
- ✅ `useCreateKey` (Import): `/v1/key/import` → `/v2/ImportKey`
- ✅ `useRemoveKey`: `/v1/key` → `/v2/DeleteKey`
### 4. Buckets 页面 (`src/pages/buckets/hooks.ts`)
### 4. Buckets Page (`src/pages/buckets/hooks.ts`)
- ✅ `useBuckets`: `/buckets` → `/v2/ListBuckets`
- ✅ `useCreateBucket`: `/v1/bucket` → `/v2/CreateBucket`
### 5. Bucket 管理页面 (`src/pages/buckets/manage/hooks.ts`)
### 5. Bucket Management Page (`src/pages/buckets/manage/hooks.ts`)
- ✅ `useBucket`: `/v1/bucket` → `/v2/GetBucketInfo`
- ✅ `useUpdateBucket`: `/v1/bucket` → `/v2/UpdateBucket`
@ -47,11 +47,11 @@
- ✅ `useDenyKey`: `/v1/bucket/deny` → `/v2/DenyBucketKey`
- ✅ `useRemoveBucket`: `/v1/bucket` → `/v2/DeleteBucket`
## 升级统计
## Upgrade Statistics
### API 端点映射
### API Endpoint Mapping
| 原 v1 端点 | 新 v2 端点 | 状态 |
| Original v1 Endpoint | New v2 Endpoint | Status |
| ---------------------------------- | ----------------------------- | ---- |
| `/v1/health` | `/v2/GetClusterHealth` | ✅ |
| `/v1/status` | `/v2/GetClusterStatus` | ✅ |
@ -74,84 +74,84 @@
| `/v1/bucket/allow` | `/v2/AllowBucketKey` | ✅ |
| `/v1/bucket/deny` | `/v2/DenyBucketKey` | ✅ |
### 升级数量
### Upgrade Count
- **总计升级端点**: 18 个
- **成功升级**: 18 个 (100%)
- **升级文件数**: 5 个 TypeScript hook 文件
- **Total Endpoints Upgraded**: 18
- **Successfully Upgraded**: 18 (100%)
- **Number of Files Upgraded**: 5 TypeScript hook files
## 后端兼容性
## Backend Compatibility
✅ **后端无需修改**：
✅ **No Backend Modifications Required**:
- 后端使用反向代理 (`ProxyHandler`) 直接转发 API 请求到 Garage Admin API
- 所有 v2 API 请求会自动转发到正确的 Garage Admin 端点
- 无需修改 Go 后端代码
- The backend uses a reverse proxy (`ProxyHandler`) to directly forward API requests to the Garage Admin API.
- All v2 API requests are automatically forwarded to the correct Garage Admin endpoints.
- No changes to the Go backend code were necessary.
## 编译验证
## Build Verification
✅ **编译成功**：
✅ **Build Successful**:
- TypeScript 编译通过
- Vite 打包成功
- 无编译错误
- TypeScript compilation passed.
- Vite bundling was successful.
- No compilation errors.
⚠️ **代码质量警告**：
⚠️ **Code Quality Warnings**:
- 存在 ESLint `any` 类型警告（不影响功能）
- 建议后续优化类型定义
- ESLint `any` type warnings are present (do not affect functionality).
- It is recommended to optimize type definitions in the future.
## 新功能可用性
## New Feature Availability
升级到 v2 API 后，项目现在可以使用以下新功能：
After upgrading to the v2 API, the project can now use the following new features:
### 集群管理增强
### Enhanced Cluster Management
- 更详细的集群健康状态信息
- 改进的布局管理操作
- 更好的节点连接处理
- More detailed cluster health status information
- Improved layout management operations
- Better node connection handling
### 密钥管理增强
### Enhanced Key Management
- 支持更多密钥类型
- 改进的权限管理
- 更好的密钥导入导出
- Support for more key types
- Improved permission management
- Better key import/export functionality
### 存储桶管理增强
### Enhanced Bucket Management
- 更丰富的存储桶元数据
- 改进的别名管理
- 更精细的权限控制
- Richer bucket metadata
- Improved alias management
- Finer-grained permission control
## 下一步建议
## Next Step Recommendations
1. **类型定义优化**: 将 `any` 类型替换为具体的接口定义
2. **功能测试**: 在开发环境中测试所有升级的功能
3. **文档更新**: 更新项目文档以反映 v2 API 的使用
4. **错误处理**: 根据 v2 API 的响应格式调整错误处理逻辑
1. **Type Definition Optimization**: Replace `any` types with specific interface definitions.
2. **Functional Testing**: Test all upgraded features in a development environment.
3. **Documentation Update**: Update project documentation to reflect the use of the v2 API.
4. **Error Handling**: Adjust error handling logic based on the v2 API's response format.
## 风险评估
## Risk Assessment
### 低风险
### Low Risk
- API 路径升级成功
- 编译无错误
- 后端兼容性良好
- API path upgrade was successful.
- No compilation errors.
- Good backend compatibility.
### 需要测试的功能
### Features Requiring Testing
- 所有升级的 API 端点的实际调用
- 错误响应的处理
- 新 API 参数格式的兼容性
- Actual calls to all upgraded API endpoints.
- Handling of error responses.
- Compatibility of new API parameter formats.
## 回滚计划
## Rollback Plan
如需回滚到 v1 API：
To roll back to the v1 API if necessary:
1. 恢复所有 hook 文件中的 API 路径
2. 确保 Garage 服务器支持 v1 API
3. 重新编译和部署
1. Restore the API paths in all hook files.
2. Ensure the Garage server supports the v1 API.
3. Recompile and redeploy.
---
**升级完成**: Garage Web UI 现已成功升级到 Garage Admin API v2，具备更强的功能和更好的性能。
**Upgrade Complete**: The Garage Web UI has now been successfully upgraded to Garage Admin API v2, providing enhanced functionality and better performance.

446
docs/garage-admin-api.md
View File

@ -1,34 +1,34 @@
# Garage Admin API 文档
# Garage Admin API Documentation
## 概述
## Overview
Garage Administration API 是一个用于编程式管理 Garage 集群的 REST API，提供了完整的集群管理、存储桶管理、访问控制等功能。当前版本为 v2，API 基础地址通常为 `http://localhost:3903`。
The Garage Administration API is a REST API for programmatically managing a Garage cluster, providing complete functionality for cluster management, bucket management, access control, and more. The current version is v2, and the base API address is typically `http://localhost:3903`.
## 认证方式
## Authentication
### Bearer Token 认证
### Bearer Token Authentication
所有 API 请求都需要在 HTTP 头中包含认证信息：
All API requests must include authentication information in the HTTP header:
```http
Authorization: Bearer <token>
```
### Token 类型
### Token Types
1. **用户定义 Token**（推荐）
1. **User-defined Token** (Recommended)
- 可动态创建和管理
- 支持作用域限制
- 支持过期时间设置
- 使用 `garage admin-token` 命令创建
- Can be dynamically created and managed
- Supports scope limitations
- Supports setting an expiration time
- Created using the `garage admin-token` command
2. **主 Token**（已废弃）
- 在配置文件中指定
- `admin_token`: 管理端点访问
- `metrics_token`: 指标端点访问
2. **Master Token** (Deprecated)
- Specified in the configuration file
- `admin_token`: For admin endpoint access
- `metrics_token`: For metrics endpoint access
### 创建用户定义 Token 示例
### Example of Creating a User-defined Token
```bash
garage admin-token create --expires-in 30d \
@ -36,15 +36,15 @@ garage admin-token create --expires-in 30d \
my-token
```
## API 端点分类
## API Endpoint Categories
### 1. 集群管理 (Cluster)
### 1. Cluster Management
#### 获取集群健康状态
#### Get Cluster Health
- **端点**: `GET /v2/GetClusterHealth`
- **描述**: 返回集群全局状态，包括连接节点数、健康存储节点数、分区状态等
- **响应示例**:
- **Endpoint**: `GET /v2/GetClusterHealth`
- **Description**: Returns the global status of the cluster, including the number of connected nodes, healthy storage nodes, partition status, etc.
- **Response Example**:
```json
{
@ -59,34 +59,34 @@ garage admin-token create --expires-in 30d \
}
```
#### 获取集群状态
#### Get Cluster Status
- **端点**: `GET /v2/GetClusterStatus`
- **描述**: 返回详细的集群状态信息，包括节点信息和布局配置
- **Endpoint**: `GET /v2/GetClusterStatus`
- **Description**: Returns detailed cluster status information, including node information and layout configuration.
#### 获取集群统计
#### Get Cluster Statistics
- **端点**: `GET /v2/GetClusterStatistics`
- **描述**: 获取集群级别的统计数据
- **Endpoint**: `GET /v2/GetClusterStatistics`
- **Description**: Gets cluster-level statistics.
#### 连接集群节点
#### Connect Cluster Nodes
- **端点**: `POST /v2/ConnectClusterNodes`
- **描述**: 指示当前节点连接到其他 Garage 节点
- **请求体**: 节点地址数组 `["<node_id>@<net_address>"]`
- **Endpoint**: `POST /v2/ConnectClusterNodes`
- **Description**: Instructs the current node to connect to other Garage nodes.
- **Request Body**: An array of node addresses `["<node_id>@<net_address>"]`
### 2. 集群布局管理 (Cluster Layout)
### 2. Cluster Layout Management
#### 获取集群布局
#### Get Cluster Layout
- **端点**: `GET /v2/GetClusterLayout`
- **描述**: 返回当前集群布局配置和待处理的变更
- **Endpoint**: `GET /v2/GetClusterLayout`
- **Description**: Returns the current cluster layout configuration and pending changes.
#### 更新集群布局
#### Update Cluster Layout
- **端点**: `POST /v2/UpdateClusterLayout`
- **描述**: 提交集群布局变更到暂存区
- **请求体示例**:
- **Endpoint**: `POST /v2/UpdateClusterLayout`
- **Description**: Submits cluster layout changes to the staging area.
- **Request Body Example**:
```json
{
@ -101,47 +101,47 @@ garage admin-token create --expires-in 30d \
}
```
#### 应用布局变更
#### Apply Layout Changes
- **端点**: `POST /v2/ApplyClusterLayout`
- **描述**: 将暂存的布局变更应用到集群
- **请求体**: `{"version": <layout_version>}`
- **Endpoint**: `POST /v2/ApplyClusterLayout`
- **Description**: Applies staged layout changes to the cluster.
- **Request Body**: `{"version": <layout_version>}`
#### 预览布局变更
#### Preview Layout Changes
- **端点**: `POST /v2/PreviewClusterLayoutChanges`
- **描述**: 预览布局变更的影响，不实际应用
- **Endpoint**: `POST /v2/PreviewClusterLayoutChanges`
- **Description**: Previews the impact of layout changes without actually applying them.
#### 回滚布局变更
#### Revert Layout Changes
- **端点**: `POST /v2/RevertClusterLayout`
- **描述**: 清除所有暂存的布局变更
- **Endpoint**: `POST /v2/RevertClusterLayout`
- **Description**: Clears all staged layout changes.
#### 获取布局历史
#### Get Layout History
- **端点**: `GET /v2/GetClusterLayoutHistory`
- **描述**: 获取集群布局的历史版本信息
- **Endpoint**: `GET /v2/GetClusterLayoutHistory`
- **Description**: Gets the history of cluster layout versions.
### 3. 存储桶管理 (Bucket)
### 3. Bucket Management
#### 列出所有存储桶
#### List All Buckets
- **端点**: `GET /v2/ListBuckets`
- **描述**: 返回集群中所有存储桶及其别名
- **Endpoint**: `GET /v2/ListBuckets`
- **Description**: Returns all buckets and their aliases in the cluster.
#### 获取存储桶信息
#### Get Bucket Information
- **端点**: `GET /v2/GetBucketInfo`
- **参数**:
- `id`: 存储桶 ID
- `globalAlias`: 全局别名
- `search`: 搜索模式
- **描述**: 获取存储桶详细信息，包括权限、统计、配额等
- **Endpoint**: `GET /v2/GetBucketInfo`
- **Parameters**:
- `id`: Bucket ID
- `globalAlias`: Global alias
- `search`: Search pattern
- **Description**: Gets detailed bucket information, including permissions, statistics, quotas, etc.
#### 创建存储桶
#### Create Bucket
- **端点**: `POST /v2/CreateBucket`
- **请求体示例**:
- **Endpoint**: `POST /v2/CreateBucket`
- **Request Body Example**:
```json
{
@ -158,11 +158,11 @@ garage admin-token create --expires-in 30d \
}
```
#### 更新存储桶
#### Update Bucket
- **端点**: `POST /v2/UpdateBucket/{id}`
- **描述**: 更新存储桶的网站配置和配额设置
- **请求体示例**:
- **Endpoint**: `POST /v2/UpdateBucket/{id}`
- **Description**: Updates a bucket's website configuration and quota settings.
- **Request Body Example**:
```json
{
@ -178,53 +178,53 @@ garage admin-token create --expires-in 30d \
}
```
#### 删除存储桶
#### Delete Bucket
- **端点**: `POST /v2/DeleteBucket/{id}`
- **描述**: 删除空存储桶（会删除所有关联别名）
- **Endpoint**: `POST /v2/DeleteBucket/{id}`
- **Description**: Deletes an empty bucket (this will delete all associated aliases).
#### 清理未完成上传
#### Cleanup Incomplete Uploads
- **端点**: `POST /v2/CleanupIncompleteUploads`
- **请求体**: `{"bucketId": "bucket-id", "olderThanSecs": 86400}`
- **Endpoint**: `POST /v2/CleanupIncompleteUploads`
- **Request Body**: `{"bucketId": "bucket-id", "olderThanSecs": 86400}`
#### 检查对象
#### Inspect Object
- **端点**: `GET /v2/InspectObject`
- **参数**: `bucketId`, `key`
- **描述**: 获取对象的详细内部状态信息
- **Endpoint**: `GET /v2/InspectObject`
- **Parameters**: `bucketId`, `key`
- **Description**: Gets detailed internal status information for an object.
### 4. 存储桶别名管理 (Bucket Alias)
### 4. Bucket Alias Management
#### 添加存储桶别名
#### Add Bucket Alias
- **端点**: `POST /v2/AddBucketAlias`
- **描述**: 为存储桶添加全局或本地别名
- **Endpoint**: `POST /v2/AddBucketAlias`
- **Description**: Adds a global or local alias for a bucket.
#### 移除存储桶别名
#### Remove Bucket Alias
- **端点**: `POST /v2/RemoveBucketAlias`
- **描述**: 移除存储桶的别名
- **Endpoint**: `POST /v2/RemoveBucketAlias`
- **Description**: Removes a bucket's alias.
### 5. 访问密钥管理 (Access Key)
### 5. Access Key Management
#### 列出访问密钥
#### List Access Keys
- **端点**: `GET /v2/ListKeys`
- **描述**: 返回所有 API 访问密钥
- **Endpoint**: `GET /v2/ListKeys`
- **Description**: Returns all API access keys.
#### 获取密钥信息
#### Get Key Information
- **端点**: `GET /v2/GetKeyInfo`
- **参数**:
- `id`: 密钥 ID
- `search`: 搜索模式
- `showSecretKey`: 是否返回密钥（默认不返回）
- **Endpoint**: `GET /v2/GetKeyInfo`
- **Parameters**:
- `id`: Key ID
- `search`: Search pattern
- `showSecretKey`: Whether to return the secret key (default is false).
#### 创建访问密钥
#### Create Access Key
- **端点**: `POST /v2/CreateKey`
- **请求体示例**:
- **Endpoint**: `POST /v2/CreateKey`
- **Request Body Example**:
```json
{
@ -235,28 +235,28 @@ garage admin-token create --expires-in 30d \
}
```
#### 更新访问密钥
#### Update Access Key
- **端点**: `POST /v2/UpdateKey/{id}`
- **描述**: 更新密钥的名称、权限和过期时间
- **Endpoint**: `POST /v2/UpdateKey/{id}`
- **Description**: Updates a key's name, permissions, and expiration time.
#### 删除访问密钥
#### Delete Access Key
- **端点**: `POST /v2/DeleteKey/{id}`
- **描述**: 从集群中删除访问密钥
- **Endpoint**: `POST /v2/DeleteKey/{id}`
- **Description**: Deletes an access key from the cluster.
#### 导入访问密钥
#### Import Access Key
- **端点**: `POST /v2/ImportKey`
- **描述**: 导入已有的访问密钥（仅用于迁移和备份恢复）
- **Endpoint**: `POST /v2/ImportKey`
- **Description**: Imports an existing access key (only for migration and backup recovery).
### 6. 权限管理 (Permission)
### 6. Permission Management
#### 授予权限
#### Grant Permission
- **端点**: `POST /v2/AllowBucketKey`
- **描述**: 授予密钥对存储桶的操作权限
- **请求体示例**:
- **Endpoint**: `POST /v2/AllowBucketKey`
- **Description**: Grants a key permission to perform operations on a bucket.
- **Request Body Example**:
```json
{
@ -270,30 +270,30 @@ garage admin-token create --expires-in 30d \
}
```
#### 拒绝权限
#### Deny Permission
- **端点**: `POST /v2/DenyBucketKey`
- **描述**: 移除密钥对存储桶的操作权限
- **Endpoint**: `POST /v2/DenyBucketKey`
- **Description**: Removes a key's permission to perform operations on a bucket.
### 7. 管理员 Token 管理 (Admin API Token)
### 7. Admin API Token Management
#### 列出管理员 Token
#### List Admin Tokens
- **端点**: `GET /v2/ListAdminTokens`
- **Endpoint**: `GET /v2/ListAdminTokens`
#### 获取 Token 信息
#### Get Token Information
- **端点**: `GET /v2/GetAdminTokenInfo`
- **参数**: `id` 或 `search`
- **Endpoint**: `GET /v2/GetAdminTokenInfo`
- **Parameters**: `id` or `search`
#### 获取当前 Token 信息
#### Get Current Token Information
- **端点**: `GET /v2/GetCurrentAdminTokenInfo`
- **Endpoint**: `GET /v2/GetCurrentAdminTokenInfo`
#### 创建管理员 Token
#### Create Admin Token
- **端点**: `POST /v2/CreateAdminToken`
- **请求体示例**:
- **Endpoint**: `POST /v2/CreateAdminToken`
- **Request Body Example**:
```json
{
@ -303,140 +303,140 @@ garage admin-token create --expires-in 30d \
}
```
#### 更新管理员 Token
#### Update Admin Token
- **端点**: `POST /v2/UpdateAdminToken/{id}`
- **Endpoint**: `POST /v2/UpdateAdminToken/{id}`
#### 删除管理员 Token
#### Delete Admin Token
- **端点**: `POST /v2/DeleteAdminToken/{id}`
- **Endpoint**: `POST /v2/DeleteAdminToken/{id}`
### 8. 节点管理 (Node)
### 8. Node Management
#### 获取节点信息
#### Get Node Information
- **端点**: `GET /v2/GetNodeInfo/{node}`
- **参数**: `node` - 节点 ID、`*`（所有节点）或 `self`（当前节点）
- **Endpoint**: `GET /v2/GetNodeInfo/{node}`
- **Parameters**: `node` - Node ID, `*` (all nodes), or `self` (current node)
#### 获取节点统计
#### Get Node Statistics
- **端点**: `GET /v2/GetNodeStatistics/{node}`
- **Endpoint**: `GET /v2/GetNodeStatistics/{node}`
#### 创建元数据快照
#### Create Metadata Snapshot
- **端点**: `POST /v2/CreateMetadataSnapshot/{node}`
- **Endpoint**: `POST /v2/CreateMetadataSnapshot/{node}`
#### 启动修复操作
#### Launch Repair Operation
- **端点**: `POST /v2/LaunchRepairOperation/{node}`
- **修复类型**: `tables`, `blocks`, `versions`, `multipartUploads`, `blockRefs`, `blockRc`, `rebalance`, `aliases`
- **Endpoint**: `POST /v2/LaunchRepairOperation/{node}`
- **Repair Types**: `tables`, `blocks`, `versions`, `multipartUploads`, `blockRefs`, `blockRc`, `rebalance`, `aliases`
### 9. 后台工作进程管理 (Worker)
### 9. Worker Process Management
#### 列出工作进程
#### List Workers
- **端点**: `POST /v2/ListWorkers/{node}`
- **Endpoint**: `POST /v2/ListWorkers/{node}`
#### 获取工作进程信息
#### Get Worker Information
- **端点**: `POST /v2/GetWorkerInfo/{node}`
- **Endpoint**: `POST /v2/GetWorkerInfo/{node}`
#### 获取工作进程变量
#### Get Worker Variable
- **端点**: `POST /v2/GetWorkerVariable/{node}`
- **Endpoint**: `POST /v2/GetWorkerVariable/{node}`
#### 设置工作进程变量
#### Set Worker Variable
- **端点**: `POST /v2/SetWorkerVariable/{node}`
- **Endpoint**: `POST /v2/SetWorkerVariable/{node}`
### 10. 数据块管理 (Block)
### 10. Block Management
#### 获取数据块信息
#### Get Block Information
- **端点**: `POST /v2/GetBlockInfo/{node}`
- **请求体**: `{"blockHash": "hash-value"}`
- **Endpoint**: `POST /v2/GetBlockInfo/{node}`
- **Request Body**: `{"blockHash": "hash-value"}`
#### 列出错误数据块
#### List Block Errors
- **端点**: `GET /v2/ListBlockErrors/{node}`
- **Endpoint**: `GET /v2/ListBlockErrors/{node}`
#### 重试数据块同步
#### Retry Block Resync
- **端点**: `POST /v2/RetryBlockResync/{node}`
- **Endpoint**: `POST /v2/RetryBlockResync/{node}`
#### 清除数据块
#### Purge Blocks
- **端点**: `POST /v2/PurgeBlocks/{node}`
- **警告**: 此操作会永久删除引用这些数据块的所有对象
- **Endpoint**: `POST /v2/PurgeBlocks/{node}`
- **Warning**: This operation permanently deletes all objects that reference these blocks.
### 11. 特殊端点 (Special Endpoints)
### 11. Special Endpoints
#### 健康检查
#### Health Check
- **端点**: `GET /health`
- **认证**: 无需认证
- **描述**: 快速健康检查，返回 200 表示服务可用
- **Endpoint**: `GET /health`
- **Authentication**: None required
- **Description**: Quick health check, returns 200 if the service is available.
#### Prometheus 指标
#### Prometheus Metrics
- **端点**: `GET /metrics`
- **认证**: 可选（使用 metrics_token）
- **描述**: 返回 Prometheus 格式的监控指标
- **Endpoint**: `GET /metrics`
- **Authentication**: Optional (using `metrics_token`)
- **Description**: Returns monitoring metrics in Prometheus format.
#### 按需 TLS 检查
#### On-Demand TLS Check
- **端点**: `GET /check?domain=<domain>`
- **认证**: 无需认证
- **描述**: 用于反向代理（如 Caddy）的按需 TLS 证书验证
- **Endpoint**: `GET /check?domain=<domain>`
- **Authentication**: None required
- **Description**: Used for on-demand TLS certificate validation by reverse proxies (like Caddy).
## 使用示例
## Usage Example
### 使用 curl
### Using curl
```bash
# 获取集群健康状态
# Get cluster health status
curl -H 'Authorization: Bearer YOUR_TOKEN' \
http://localhost:3903/v2/GetClusterHealth
# 创建存储桶
# Create a bucket
curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"globalAlias": "my-bucket"}' \
http://localhost:3903/v2/CreateBucket
# 列出所有存储桶
# List all buckets
curl -H 'Authorization: Bearer YOUR_TOKEN' \
http://localhost:3903/v2/ListBuckets
```
### 使用 Garage CLI
### Using the Garage CLI
```bash
# 通过内部 RPC 调用（无需认证）
# Call via internal RPC (no authentication required)
garage json-api GetClusterHealth
# 带参数的调用
# Call with parameters
garage json-api GetBucketInfo '{"globalAlias": "my-bucket"}'
# 从标准输入读取参数
# Read parameters from standard input
garage json-api CreateBucket -
{"globalAlias": "test-bucket"}
<EOF>
```
## 错误处理
## Error Handling
API 使用标准 HTTP 状态码：
The API uses standard HTTP status codes:
- `200 OK` - 请求成功
- `400 Bad Request` - 请求参数错误
- `401 Unauthorized` - 认证失败
- `403 Forbidden` - 权限不足
- `404 Not Found` - 资源不存在
- `500 Internal Server Error` - 服务器内部错误
- `200 OK` - Request successful
- `400 Bad Request` - Invalid request parameters
- `401 Unauthorized` - Authentication failed
- `403 Forbidden` - Insufficient permissions
- `404 Not Found` - Resource not found
- `500 Internal Server Error` - Internal server error
错误响应通常包含详细的错误信息：
Error responses typically include detailed error information:
```json
{
@ -445,38 +445,38 @@ API 使用标准 HTTP 状态码：
}
```
## 权限作用域
## Permission Scopes
管理员 Token 可以限制访问特定的 API 端点：
Admin tokens can be restricted to specific API endpoints:
- `*` - 允许所有端点
- `ListBuckets` - 列出存储桶
- `GetBucketInfo` - 获取存储桶信息
- `CreateBucket` - 创建存储桶
- `ListKeys` - 列出访问密钥
- `CreateKey` - 创建访问密钥
- `AllowBucketKey` - 授予权限
- `DenyBucketKey` - 拒绝权限
- `Metrics` - 访问指标端点
- `*` - Allows all endpoints
- `ListBuckets` - List buckets
- `GetBucketInfo` - Get bucket information
- `CreateBucket` - Create a bucket
- `ListKeys` - List access keys
- `CreateKey` - Create an access key
- `AllowBucketKey` - Grant permissions
- `DenyBucketKey` - Deny permissions
- `Metrics` - Access the metrics endpoint
## 最佳实践
## Best Practices
1. **使用用户定义 Token**：避免使用配置文件中的主 Token
2. **设置适当的作用域**：只授予必要的权限
3. **设置过期时间**：定期轮换 Token
4. **监控 API 使用**：通过 `/metrics` 端点监控 API 调用
5. **错误处理**：妥善处理各种错误情况
6. **批量操作**：对于大量操作，考虑使用批量 API 或脚本
1. **Use User-defined Tokens**: Avoid using the master token from the configuration file.
2. **Set Appropriate Scopes**: Grant only necessary permissions.
3. **Set Expiration Times**: Rotate tokens periodically.
4. **Monitor API Usage**: Monitor API calls via the `/metrics` endpoint.
5. **Handle Errors**: Properly handle various error conditions.
6. **Bulk Operations**: For a large number of operations, consider using bulk APIs or scripts.
## 版本历史
## Version History
- **v0** - Garage v0.7.2 首次引入（已废弃）
- **v1** - Garage v0.9.0 引入（已废弃）
- **v2** - Garage v2.0.0 引入（当前版本）
- **v0** - First introduced in Garage v0.7.2 (deprecated)
- **v1** - Introduced in Garage v0.9.0 (deprecated)
- **v2** - Introduced in Garage v2.0.0 (current version)
## 相关链接
## Related Links
- [Garage 官方文档](https://garagehq.deuxfleurs.fr/documentation/)
- [OpenAPI 规范 (HTML)](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html)
- [OpenAPI 规范 (JSON)](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.json)
- [Garage 源代码](https://git.deuxfleurs.fr/Deuxfleurs/garage)
- [Garage Official Documentation](https://garagehq.deuxfleurs.fr/documentation/)
- [OpenAPI Specification (HTML)](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html)
- [OpenAPI Specification (JSON)](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.json)
- [Garage Source Code](https://git.deuxfleurs.fr/Deuxfleurs/garage)

731
docs/garage-webui-管理文档.md
View File

@ -1,126 +1,126 @@
# Garage Web UI 项目管理文档
# Garage Web UI Project Management Documentation
## 项目概述
## Project Overview
**Garage Web UI** 是一个用于管理 [Garage](https://garagehq.deuxfleurs.fr/) 分布式对象存储服务的现代化 Web 管理界面。该项目提供了一个简洁、直观的图形化界面来管理 Garage 集群，是 Garage 官方命令行工具的重要补充。
**Garage Web UI** is a modern web management interface for the [Garage](https://garagehq.deuxfleurs.fr/) distributed object storage service. This project provides a clean, intuitive graphical interface to manage Garage clusters, serving as an important supplement to the official Garage command-line tools.
### 🎯 项目定位
### 🎯 Project Positioning
- **目标用户**: Garage 集群管理员和运维人员
- **核心价值**: 简化 Garage 集群的日常管理操作
- **技术栈**: TypeScript + React (前端) + Go (后端)
- **Target Users**: Garage cluster administrators and operations personnel
- **Core Value**: Simplify the daily management operations of Garage clusters
- **Technology Stack**: TypeScript + React (Frontend) + Go (Backend)
## 功能特性
## Features
### 🏥 集群监控与管理
### 🏥 Cluster Monitoring and Management
#### 1. 健康状态监控
#### 1. Health Status Monitoring
- **实时集群状态**: 显示集群整体健康状况（健康/降级/不可用）
- **节点监控**: 实时监控已知节点数、连接节点数、存储节点状态
- **分区状态**: 监控数据分区的健康状况和仲裁状态
- **Real-time Cluster Status**: Displays the overall health of the cluster (Healthy/Degraded/Unavailable)
- **Node Monitoring**: Real-time monitoring of the number of known nodes, connected nodes, and storage node status
- **Partition Status**: Monitors the health and quorum status of data partitions
#### 2. 集群布局管理
#### 2. Cluster Layout Management
- **可视化布局**: 图形化显示集群节点分布和存储配置
- **节点配置**: 管理节点的区域、容量、标签等属性
- **布局变更**: 支持暂存、预览、应用和回滚布局变更
- **历史记录**: 查看集群布局的历史变更记录
- **Visual Layout**: Graphically displays the cluster node distribution and storage configuration
- **Node Configuration**: Manage node attributes such as zone, capacity, and tags
- **Layout Changes**: Supports staging, previewing, applying, and reverting layout changes
- **History**: View the history of cluster layout changes
### 🗄️ 存储桶管理
### 🗄️ Bucket Management
#### 1. 存储桶操作
#### 1. Bucket Operations
- **桶列表**: 显示所有存储桶及其基本信息
- **桶详情**: 查看存储桶的详细统计、配置和权限信息
- **桶创建**: 支持创建全局别名和本地别名的存储桶
- **桶配置**: 更新存储桶的网站配置、配额设置等
- **Bucket List**: Displays all buckets and their basic information
- **Bucket Details**: View detailed statistics, configuration, and permission information for a bucket
- **Bucket Creation**: Supports creating buckets with global and local aliases
- **Bucket Configuration**: Update bucket website configuration, quota settings, etc.
#### 2. 对象浏览器
#### 2. Object Browser
- **文件浏览**: 内置对象浏览器，支持文件夹结构浏览
- **文件操作**: 上传、下载、删除对象文件
- **分享功能**: 生成临时访问链接
- **批量操作**: 支持批量文件管理
- **File Browsing**: Built-in object browser that supports folder structure browsing
- **File Operations**: Upload, download, and delete object files
- **Sharing Functionality**: Generate temporary access links
- **Bulk Operations**: Supports bulk file management
### 🔑 访问控制管理
### 🔑 Access Control Management
#### 1. 访问密钥管理
#### 1. Access Key Management
- **密钥列表**: 显示所有 API 访问密钥
- **密钥创建**: 创建新的 S3 兼容访问密钥
- **权限配置**: 设置密钥的全局权限（如创建存储桶）
- **过期管理**: 设置密钥的过期时间
- **Key List**: Displays all API access keys
- **Key Creation**: Create new S3-compatible access keys
- **Permission Configuration**: Set global permissions for keys (e.g., creating buckets)
- **Expiration Management**: Set expiration times for keys
#### 2. 权限分配
#### 2. Permission Assignment
- **桶权限**: 为访问密钥分配对特定存储桶的权限
- **权限类型**: 支持读取、写入、所有者三种权限级别
- **权限撤销**: 灵活的权限授予和撤销机制
- **Bucket Permissions**: Assign permissions to access keys for specific buckets
- **Permission Types**: Supports Read, Write, and Owner permission levels
- **Permission Revocation**: Flexible mechanism for granting and revoking permissions
## 技术架构
## Technical Architecture
### 🏗️ 整体架构
### 🏗️ Overall Architecture
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Web Browser │───▶│ Garage Web UI │───▶│ Garage Cluster │
│ (前端界面) │ │ (Go 后端服务) │ │ (Admin API) │
│ (Frontend UI) │ │ (Go Backend) │ │ (Admin API) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
```
### 📁 项目结构
### 📁 Project Structure
```
garage-webui/
├── src/ # React 前端源码
│ ├── pages/ # 页面组件
│ │ ├── home/ # 首页仪表板
│ │ ├── cluster/ # 集群管理
│ │ ├── buckets/ # 存储桶管理
│ │ └── keys/ # 访问密钥管理
│ ├── components/ # 可复用组件
├── src/ # React Frontend Source
│ ├── pages/ # Page Components
│ │ ├── home/ # Home Dashboard
│ │ ├── cluster/ # Cluster Management
│ │ ├── buckets/ # Bucket Management
│ │ └── keys/ # Access Key Management
│ ├── components/ # Reusable Components
│ ├── hooks/ # React Hooks
│ └── lib/ # 工具库
├── backend/ # Go 后端源码
│ ├── main.go # 服务入口
│ ├── router/ # API 路由
│ ├── utils/ # 工具函数
│ └── schema/ # 数据结构
├── docs/ # 项目文档
└── misc/ # 截图等资源
│ └── lib/ # Utility Libraries
├── backend/ # Go Backend Source
│ ├── main.go # Service Entrypoint
│ ├── router/ # API Routes
│ ├── utils/ # Utility Functions
│ └── schema/ # Data Structures
├── docs/ # Project Documentation
└── misc/ # Screenshots and other resources
```
### 🔌 后端服务架构
### 🔌 Backend Service Architecture
#### 核心模块
#### Core Modules
1. **配置管理** (`utils/garage.go`)
1. **Configuration Management** (`utils/garage.go`)
- 自动读取 Garage 配置文件 (`garage.toml`)
- 提取管理 API 端点、认证信息等
- 支持环境变量覆盖配置
- Automatically reads the Garage configuration file (`garage.toml`)
- Extracts admin API endpoints, authentication information, etc.
- Supports overriding configuration with environment variables
2. **API 代理** (`router/`)
2. **API Proxy** (`router/`)
- 代理前端请求到 Garage Admin API
- 处理认证和错误转换
- 提供统一的 RESTful 接口
- Proxies frontend requests to the Garage Admin API
- Handles authentication and error translation
- Provides a unified RESTful interface
3. **会话管理** (`utils/session.go`)
3. **Session Management** (`utils/session.go`)
- 支持用户认证（可选）
- 会话状态管理
- Supports user authentication (optional)
- Session state management
4. **缓存机制** (`utils/cache.go`)
- API 响应缓存
- 减少对 Garage 集群的请求压力
4. **Caching Mechanism** (`utils/cache.go`)
- Caches API responses
- Reduces request pressure on the Garage cluster
## 部署方案
## Deployment Scenarios
### 🐳 Docker 部署（推荐）
### 🐳 Docker Deployment (Recommended)
#### 1. 与 Garage 集群一起部署
#### 1. Deploying with a Garage Cluster
```yaml
services:
@ -147,7 +147,7 @@ services:
S3_ENDPOINT_URL: "http://garage:3900"
```
#### 2. 独立部署
#### 2. Standalone Deployment
```bash
docker run -p 3909:3909 \
@ -157,18 +157,18 @@ docker run -p 3909:3909 \
khairul169/garage-webui:latest
```
### 🖥️ 二进制部署
### 🖥️ Binary Deployment
```bash
# 下载二进制文件
# Download the binary file
wget -O garage-webui https://github.com/khairul169/garage-webui/releases/download/1.0.9/garage-webui-v1.0.9-linux-amd64
chmod +x garage-webui
# 运行服务
# Run the service
CONFIG_PATH=./garage.toml ./garage-webui
```
### 🔧 SystemD 服务
### 🔧 SystemD Service
```ini
[Unit]
@ -185,97 +185,97 @@ Restart=always
WantedBy=default.target
```
## 配置管理
## Configuration Management
### 📝 Garage 配置要求
### 📝 Garage Configuration Requirements
Web UI 需要 Garage 集群启用 Admin API：
The Web UI requires the Garage cluster to have the Admin API enabled:
```toml
# garage.toml
[admin]
api_bind_addr = "[::]:3903"
admin_token = "your-secure-admin-token"
metrics_token = "your-metrics-token" # 可选
metrics_token = "your-metrics-token" # Optional
```
### 🌍 环境变量配置
### 🌍 Environment Variable Configuration
| 变量名 | 描述 | 默认值 |
| ----------------- | --------------------- | ------------------ |
| `CONFIG_PATH` | Garage 配置文件路径 | `/etc/garage.toml` |
| `API_BASE_URL` | Garage Admin API 地址 | 从配置文件读取 |
| `API_ADMIN_KEY` | Admin API 令牌 | 从配置文件读取 |
| `S3_ENDPOINT_URL` | S3 API 地址 | 从配置文件读取 |
| `S3_REGION` | S3 区域 | `garage` |
| `BASE_PATH` | Web UI 基础路径 | `/` |
| `PORT` | 服务端口 | `3909` |
| `HOST` | 绑定地址 | `0.0.0.0` |
| Variable Name | Description | Default Value |
| ----------------- | ----------------------------- | -------------------- |
| `CONFIG_PATH` | Path to Garage config file | `/etc/garage.toml` |
| `API_BASE_URL` | Garage Admin API address | Read from config file|
| `API_ADMIN_KEY` | Admin API token | Read from config file|
| `S3_ENDPOINT_URL` | S3 API address | Read from config file|
| `S3_REGION` | S3 region | `garage` |
| `BASE_PATH` | Web UI base path | `/` |
| `PORT` | Service port | `3909` |
| `HOST` | Binding address | `0.0.0.0` |
### 🔐 认证配置
### 🔐 Authentication Configuration
#### 启用 Web UI 认证
#### Enable Web UI Authentication
```bash
# 生成密码哈希
# Generate password hash
htpasswd -nbBC 10 "admin" "password"
# 设置环境变量
# Set environment variable
AUTH_USER_PASS="admin:$2y$10$DSTi9o..."
```
## 管理最佳实践
## Management Best Practices
### 🚀 日常运维
### 🚀 Daily Operations
#### 1. 集群健康监控
#### 1. Cluster Health Monitoring
- **定期检查**: 通过首页仪表板监控集群状态
- **告警设置**: 配置监控系统对接 `/metrics` 端点
- **性能观察**: 关注存储节点连接状态和分区健康度
- **Regular Checks**: Monitor cluster status via the home dashboard
- **Alerting Setup**: Configure monitoring systems to connect to the `/metrics` endpoint
- **Performance Observation**: Pay attention to storage node connection status and partition health
#### 2. 存储桶管理
#### 2. Bucket Management
- **命名规范**: 建立统一的存储桶命名规范
- **权限最小化**: 为访问密钥分配最小必要权限
- **配额管理**: 为重要业务设置适当的配额限制
- **Naming Conventions**: Establish uniform bucket naming conventions
- **Minimize Permissions**: Assign the minimum necessary permissions to access keys
- **Quota Management**: Set appropriate quota limits for important services
#### 3. 访问控制
#### 3. Access Control
- **定期轮换**: 定期轮换 API 访问密钥
- **权限审计**: 定期审查存储桶权限分配
- **密钥管理**: 为不同用途创建专用访问密钥
- **Regular Rotation**: Rotate API access keys periodically
- **Permission Audits**: Regularly review bucket permission assignments
- **Key Management**: Create dedicated access keys for different purposes
### 🔧 故障排查
### 🔧 Troubleshooting
#### 1. 连接问题
#### 1. Connection Issues
```bash
# 检查 Admin API 可访问性
# Check Admin API accessibility
curl -H "Authorization: Bearer YOUR_TOKEN" \
http://garage-host:3903/v2/GetClusterHealth
# 检查网络连通性
# Check network connectivity
telnet garage-host 3903
```
#### 2. 配置问题
#### 2. Configuration Issues
- 验证 `garage.toml` 配置正确性
- 确认 Admin API 端口已开放
- 检查防火墙和网络策略
- Verify the correctness of the `garage.toml` configuration
- Confirm that the Admin API port is open
- Check firewall and network policies
#### 3. 性能优化
#### 3. Performance Optimization
- 启用缓存机制减少 API 调用
- 使用反向代理（如 Nginx）提供 SSL 终止
- 监控资源使用情况
- Enable caching to reduce API calls
- Use a reverse proxy (like Nginx) for SSL termination
- Monitor resource usage
### 📊 监控集成
### 📊 Monitoring Integration
#### Prometheus 指标
#### Prometheus Metrics
Web UI 可以配置为监控 Garage 的 Prometheus 指标：
The Web UI can be configured to monitor Garage's Prometheus metrics:
```yaml
# prometheus.yml
@ -287,364 +287,361 @@ scrape_configs:
bearer_token: "your-metrics-token"
```
#### 关键指标
#### Key Metrics
- `garage_cluster_health`: 集群健康状态
- `garage_storage_usage`: 存储使用情况
- `garage_api_requests`: API 请求统计
- `garage_replication_status`: 数据复制状态
- `garage_cluster_health`: Cluster health status
- `garage_storage_usage`: Storage usage
- `garage_api_requests`: API request statistics
- `garage_replication_status`: Data replication status
## 开发指南
## Development Guide
### 🛠️ 开发环境搭建
### 🛠️ Development Environment Setup
```bash
# 克隆项目
# Clone the project
git clone https://github.com/khairul169/garage-webui.git
cd garage-webui
# 安装前端依赖
# Install frontend dependencies
pnpm install
# 安装后端依赖
# Install backend dependencies
cd backend && go mod download && cd ..
# 启动开发服务器
# Start the development server
pnpm run dev
```
### 🔧 技术选型说明
### 🔧 Technology Choices
- **前端**: React 18 + TypeScript + Tailwind CSS
- **状态管理**: React Query (TanStack Query)
- **路由**: React Router
- **UI 组件**: 自定义组件库
- **后端**: Go + Gin 框架
- **配置解析**: go-toml
- **Frontend**: React 18 + TypeScript + Tailwind CSS
- **State Management**: React Query (TanStack Query)
- **Routing**: React Router
- **UI Components**: Custom component library
- **Backend**: Go + Gin framework
- **Configuration Parsing**: go-toml
### 📋 贡献指南
### 📋 Contribution Guidelines
1. **代码规范**: 遵循项目的 ESLint 和 Go fmt 规范
2. **测试**: 新功能需要添加相应测试
3. **文档**: 更新相关文档和 API 说明
4. **兼容性**: 确保与最新版本 Garage 兼容
1. **Coding Standards**: Follow the project's ESLint and Go fmt standards
2. **Testing**: New features require corresponding tests
3. **Documentation**: Update relevant documents and API descriptions
4. **Compatibility**: Ensure compatibility with the latest version of Garage
## 安全考虑
## Security Considerations
### 🔒 安全建议
### 🔒 Security Recommendations
1. **网络安全**
1. **Network Security**
- 在生产环境中使用 HTTPS
- 限制 Admin API 的网络访问
- 使用防火墙规则保护敏感端口
- Use HTTPS in production environments
- Restrict network access to the Admin API
- Use firewall rules to protect sensitive ports
2. **认证安全**
2. **Authentication Security**
- 启用 Web UI 用户认证
- 使用强密码和定期轮换
- 考虑集成企业身份认证系统
- Consider integrating with an enterprise identity authentication system
3. **权限控制**
- 遵循最小权限原则
- 定期审计访问权限
- 使用专用的管理员 Token
3. **Permission Control**
- Follow the principle of least privilege
- Use a dedicated administrator token
## 未来规划
## Future Plans
### 🚀 功能路线图
### 🚀 Feature Roadmap
- **高级监控**: 集成更多性能指标和告警功能
- **批量操作**: 支持批量管理存储桶和访问密钥
- **API 扩展**: 支持更多 Garage Admin API 功能
- **国际化**: 多语言支持
- **主题系统**: 可定制的 UI 主题
- **Advanced Monitoring**: Integrate more performance metrics and alerting features
- **Bulk Operations**: Support bulk management of buckets and access keys
- **API Expansion**: Support more Garage Admin API features
- **Internationalization**: Multi-language support
- **Theming System**: Customizable UI themes
### 🔧 技术改进
### 🔧 Technical Improvements
- **缓存优化**: 更智能的缓存策略
- **实时更新**: WebSocket 支持实时状态更新
- **移动优化**: 改进移动端体验
- **性能提升**: 前端打包优化和懒加载
- **Cache Optimization**: Smarter caching strategies
- **Real-time Updates**: WebSocket support for real-time status updates
- **Mobile Optimization**: Improve the mobile experience
- **Performance Enhancements**: Frontend bundle optimization and lazy loading
## Garage Admin API 使用情况
## Garage Admin API Usage
### 🔌 当前项目调用的 API 功能
### 🔌 API Features Currently Used by the Project
基于代码分析，当前 Garage Web UI 项目调用了以下 Garage Admin API v1 功能：
Based on code analysis, the current Garage Web UI project calls the following Garage Admin API v1 features:
#### 1. 集群管理 API
#### 1. Cluster Management API
- **`GET /v1/health`** - 获取集群健康状态
- **`GET /v1/health`** - Get cluster health status
- 用于首页仪表板显示集群状态
- 监控节点连接数、存储节点状态、分区健康度
- Used on the home dashboard to display cluster status
- Monitors the number of connected nodes, storage node status, and partition health
- **`GET /v1/status`** - 获取集群详细状态
- 用于集群管理页面显示节点详情
- 展示集群拓扑和节点配置信息
- **`GET /v1/status`** - Get detailed cluster status
- Used on the cluster management page to display node details
- Shows cluster topology and node configuration information
#### 2. 集群布局管理 API
#### 2. Cluster Layout Management API
- **`GET /v1/layout`** - 获取集群布局配置
- **`GET /v1/layout`** - Get cluster layout configuration
- 显示当前集群布局和暂存变更
- 查看节点角色、容量、区域分配
- Displays the current cluster layout and staged changes
- Views node roles, capacity, and zone assignments
- **`POST /v1/layout`** - 更新集群布局
- **`POST /v1/layout`** - Update cluster layout
- 添加新节点到集群
- 修改节点配置（容量、区域、标签）
- 移除节点（设置 remove: true）
- Adds new nodes to the cluster
- Modifies node configuration (capacity, zone, tags)
- Removes nodes (by setting `remove: true`)
- **`POST /v1/connect`** - 连接集群节点
- **`POST /v1/connect`** - Connect cluster nodes
- 将新节点连接到集群
- 建立节点间的 RPC 连接
- Connects new nodes to the cluster
- Establishes RPC connections between nodes
- **`POST /v1/layout/apply`** - 应用布局变更
- **`POST /v1/layout/apply`** - Apply layout changes
- 将暂存的布局变更应用到集群
- 触发数据重新分布
- Applies staged layout changes to the cluster
- Triggers data redistribution
- **`POST /v1/layout/revert`** - 回滚布局变更
- 清除暂存的布局变更
- 恢复到上一个稳定状态
- **`POST /v1/layout/revert`** - Revert layout changes
- Clears staged layout changes
- Restores to the last stable state
#### 3. 存储桶管理 API
#### 3. Bucket Management API
- **`GET /v1/bucket?list`** - 列出所有存储桶
- **`GET /v1/bucket?list`** - List all buckets
- 获取集群中所有存储桶列表
- 显示桶的基本信息和别名
- Gets a list of all buckets in the cluster
- Displays basic bucket information and aliases
- **`GET /v1/bucket?id={id}`** - 获取存储桶详细信息
- **`GET /v1/bucket?id={id}`** - Get detailed bucket information
- 查看单个存储桶的完整配置
- 包含权限、统计、配额等信息
- Views the complete configuration of a single bucket
- Includes permissions, statistics, quota information, etc.
- **`POST /v1/bucket`** - 创建新存储桶
- **`POST /v1/bucket`** - Create a new bucket
- 支持设置全局别名和本地别名
- 配置初始权限和参数
- Supports setting global and local aliases
- Configures initial permissions and parameters
- **`PUT /v1/bucket?id={id}`** - 更新存储桶配置
- **`PUT /v1/bucket?id={id}`** - Update bucket configuration
- 修改存储桶的网站配置
- 设置或更新配额限制
- Modifies the bucket's website configuration
- Sets or updates quota limits
- **`DELETE /v1/bucket?id={id}`** - 删除存储桶
- 删除空的存储桶（需要桶为空）
- **`DELETE /v1/bucket?id={id}`** - Delete a bucket
- Deletes an empty bucket (the bucket must be empty)
#### 4. 存储桶别名管理 API
#### 4. Bucket Alias Management API
- **`PUT /v1/bucket/alias/global`** - 添加全局别名
- **`PUT /v1/bucket/alias/global`** - Add a global alias
- 为存储桶创建全局访问别名
- 支持多个别名指向同一个桶
- Creates a global access alias for a bucket
- Supports multiple aliases pointing to the same bucket
- **`DELETE /v1/bucket/alias/global`** - 删除全局别名
- 移除存储桶的全局别名
- 保持桶本身不受影响
- **`DELETE /v1/bucket/alias/global`** - Delete a global alias
- Removes a global alias from a bucket
- The bucket itself remains unaffected
#### 5. 权限管理 API
#### 5. Permission Management API
- **`POST /v1/bucket/allow`** - 授予存储桶权限
- **`POST /v1/bucket/allow`** - Grant bucket permissions
- 为访问密钥分配桶的操作权限
- 支持读取、写入、所有者权限
- Assigns bucket operation permissions to an access key
- Supports Read, Write, and Owner permissions
- **`POST /v1/bucket/deny`** - 撤销存储桶权限
- 移除访问密钥对桶的权限
- 灵活的权限控制机制
- **`POST /v1/bucket/deny`** - Revoke bucket permissions
- Removes an access key's permissions for a bucket
- Flexible permission control mechanism
#### 6. 访问密钥管理 API
#### 6. Access Key Management API
- **`GET /v1/key?list`** - 列出所有访问密钥
- **`GET /v1/key?list`** - List all access keys
- 获取集群中的所有 API 密钥
- 显示密钥的基本信息
- Gets all API keys in the cluster
- Displays basic key information
- **`POST /v1/key`** - 创建新的访问密钥
- **`POST /v1/key`** - Create a new access key
- 生成新的 S3 兼容访问密钥
- 设置密钥的初始权限
- Generates a new S3-compatible access key
- Sets initial permissions for the key
- **`POST /v1/key/import`** - 导入已有访问密钥
- **`POST /v1/key/import`** - Import an existing access key
- 用于迁移或恢复访问密钥
- 导入外部生成的密钥
- Used for migrating or restoring access keys
- Imports externally generated keys
- **`DELETE /v1/key?id={id}`** - 删除访问密钥
- 从集群中移除访问密钥
- 立即撤销所有相关权限
- **`DELETE /v1/key?id={id}`** - Delete an access key
- Removes an access key from the cluster
- Immediately revokes all related permissions
### ## API 版本对比分析
### ## API Version Comparison Analysis
### 📊 当前项目 vs 官方文档 API 差异
### 📊 API Differences: Current Project vs. Official Documentation
通过对比分析，发现当前项目使用的是 **Garage Admin API v1**，而官方最新文档推荐使用 **API v2**。以下是详细的差异对比：
A comparative analysis reveals that the current project uses **Garage Admin API v1**, while the latest official documentation recommends using **API v2**. Below is a detailed comparison of the differences:
#### 🔄 版本映射关系
#### 🔄 Version Mapping
| 功能类别 | 当前项目 (v1) | 官方推荐 (v2) | 状态 |
| Feature Category | Current Project (v1) | Official Recommendation (v2) | Status |
| ---------------- | ------------------------ | -------------------------------------- | --------- |
| **集群健康状态** | `GET /v1/health` | `GET /v2/GetClusterHealth` | ⚠️ 需升级 |
| **集群状态** | `GET /v1/status` | `GET /v2/GetClusterStatus` | ⚠️ 需升级 |
| **集群统计** | ❌ 未使用 | `GET /v2/GetClusterStatistics` | 🆕 新功能 |
| **连接节点** | `POST /v1/connect` | `POST /v2/ConnectClusterNodes` | ⚠️ 需升级 |
| **获取布局** | `GET /v1/layout` | `GET /v2/GetClusterLayout` | ⚠️ 需升级 |
| **更新布局** | `POST /v1/layout` | `POST /v2/UpdateClusterLayout` | ⚠️ 需升级 |
| **应用布局** | `POST /v1/layout/apply` | `POST /v2/ApplyClusterLayout` | ⚠️ 需升级 |
| **回滚布局** | `POST /v1/layout/revert` | `POST /v2/RevertClusterLayout` | ⚠️ 需升级 |
| **布局历史** | ❌ 未使用 | `GET /v2/GetClusterLayoutHistory` | 🆕 新功能 |
| **预览布局变更** | ❌ 未使用 | `POST /v2/PreviewClusterLayoutChanges` | 🆕 新功能 |
| **Cluster Health Status** | `GET /v1/health` | `GET /v2/GetClusterHealth` | ⚠️ Upgrade Needed |
| **Cluster Status** | `GET /v1/status` | `GET /v2/GetClusterStatus` | ⚠️ Upgrade Needed |
| **Cluster Statistics** | ❌ Not Used | `GET /v2/GetClusterStatistics` | 🆕 New Feature |
| **Connect Nodes** | `POST /v1/connect` | `POST /v2/ConnectClusterNodes` | ⚠️ Upgrade Needed |
| **Get Layout** | `GET /v1/layout` | `GET /v2/GetClusterLayout` | ⚠️ Upgrade Needed |
| **Update Layout** | `POST /v1/layout` | `POST /v2/UpdateClusterLayout` | ⚠️ Upgrade Needed |
| **Apply Layout** | `POST /v1/layout/apply` | `POST /v2/ApplyClusterLayout` | ⚠️ Upgrade Needed |
| **Revert Layout** | `POST /v1/layout/revert` | `POST /v2/RevertClusterLayout` | ⚠️ Upgrade Needed |
| **Layout History** | ❌ Not Used | `GET /v2/GetClusterLayoutHistory` | 🆕 New Feature |
| **Preview Layout Changes** | ❌ Not Used | `POST /v2/PreviewClusterLayoutChanges` | 🆕 New Feature |
#### 📦 存储桶管理 API 对比
#### 📦 Bucket Management API Comparison
| 功能 | 当前项目 (v1) | 官方推荐 (v2) | 差异说明 |
| Feature | Current Project (v1) | Official Recommendation (v2) | Difference Explanation |
| -------------- | -------------------------------- | ----------------------------------- | ------------------- |
| **列出存储桶** | `GET /v1/bucket?list` | `GET /v2/ListBuckets` | 参数格式不同 |
| **获取桶信息** | `GET /v1/bucket?id={id}` | `GET /v2/GetBucketInfo` | 支持更多查询方式 |
| **创建存储桶** | `POST /v1/bucket` | `POST /v2/CreateBucket` | v2 支持更多配置选项 |
| **更新存储桶** | `PUT /v1/bucket?id={id}` | `POST /v2/UpdateBucket/{id}` | HTTP 方法和路径不同 |
| **删除存储桶** | `DELETE /v1/bucket?id={id}` | `POST /v2/DeleteBucket/{id}` | HTTP 方法不同 |
| **添加别名** | `PUT /v1/bucket/alias/global` | `POST /v2/AddBucketAlias` | 支持本地别名 |
| **删除别名** | `DELETE /v1/bucket/alias/global` | `POST /v2/RemoveBucketAlias` | 支持本地别名 |
| **清理上传** | ❌ 未使用 | `POST /v2/CleanupIncompleteUploads` | 🆕 新功能 |
| **检查对象** | ❌ 未使用 | `GET /v2/InspectObject` | 🆕 新功能 |
| **List Buckets** | `GET /v1/bucket?list` | `GET /v2/ListBuckets` | Parameter format differs |
| **Get Bucket Info** | `GET /v1/bucket?id={id}` | `GET /v2/GetBucketInfo` | Supports more query methods |
| **Create Bucket** | `POST /v1/bucket` | `POST /v2/CreateBucket` | v2 supports more configuration options |
| **Update Bucket** | `PUT /v1/bucket?id={id}` | `POST /v2/UpdateBucket/{id}` | HTTP method and path differ |
| **Delete Bucket** | `DELETE /v1/bucket?id={id}` | `POST /v2/DeleteBucket/{id}` | HTTP method differs |
| **Add Alias** | `PUT /v1/bucket/alias/global` | `POST /v2/AddBucketAlias` | Supports local aliases |
| **Delete Alias** | `DELETE /v1/bucket/alias/global` | `POST /v2/RemoveBucketAlias` | Supports local aliases |
| **Cleanup Uploads** | ❌ Not Used | `POST /v2/CleanupIncompleteUploads` | 🆕 New Feature |
| **Inspect Object** | ❌ Not Used | `GET /v2/InspectObject` | 🆕 New Feature |
#### 🔑 访问密钥管理 API 对比
#### 🔑 Access Key Management API Comparison
| 功能 | 当前项目 (v1) | 官方推荐 (v2) | 差异说明 |
| Feature | Current Project (v1) | Official Recommendation (v2) | Difference Explanation |
| ---------------- | ------------------------ | ------------------------- | --------------- |
| **列出密钥** | `GET /v1/key?list` | `GET /v2/ListKeys` | 参数格式不同 |
| **获取密钥信息** | ❌ 未使用 | `GET /v2/GetKeyInfo` | 🆕 新功能 |
| **创建密钥** | `POST /v1/key` | `POST /v2/CreateKey` | v2 支持更多选项 |
| **更新密钥** | ❌ 未使用 | `POST /v2/UpdateKey/{id}` | 🆕 新功能 |
| **删除密钥** | `DELETE /v1/key?id={id}` | `POST /v2/DeleteKey/{id}` | HTTP 方法不同 |
| **导入密钥** | `POST /v1/key/import` | `POST /v2/ImportKey` | 路径结构不同 |
| **授予权限** | `POST /v1/bucket/allow` | `POST /v2/AllowBucketKey` | 路径结构不同 |
| **撤销权限** | `POST /v1/bucket/deny` | `POST /v2/DenyBucketKey` | 路径结构不同 |
| **List Keys** | `GET /v1/key?list` | `GET /v2/ListKeys` | Parameter format differs |
| **Get Key Info** | ❌ Not Used | `GET /v2/GetKeyInfo` | 🆕 New Feature |
| **Create Key** | `POST /v1/key` | `POST /v2/CreateKey` | v2 supports more options |
| **Update Key** | ❌ Not Used | `POST /v2/UpdateKey/{id}` | 🆕 New Feature |
| **Delete Key** | `DELETE /v1/key?id={id}` | `POST /v2/DeleteKey/{id}` | HTTP method differs |
| **Import Key** | `POST /v1/key/import` | `POST /v2/ImportKey` | Path structure differs |
| **Grant Permission** | `POST /v1/bucket/allow` | `POST /v2/AllowBucketKey` | Path structure differs |
| **Revoke Permission** | `POST /v1/bucket/deny` | `POST /v2/DenyBucketKey` | Path structure differs |
### 🚫 v2 独有功能（当前项目未使用）
### 🚫 v2-Exclusive Features (Not Used in the Current Project)
#### 1. 管理员 Token 管理
#### 1. Admin Token Management
- `GET /v2/ListAdminTokens` - 列出所有管理员 Token
- `GET /v2/GetAdminTokenInfo` - 获取 Token 信息
- `GET /v2/GetCurrentAdminTokenInfo` - 获取当前 Token 信息
- `POST /v2/CreateAdminToken` - 创建管理员 Token
- `POST /v2/UpdateAdminToken/{id}` - 更新管理员 Token
- `POST /v2/DeleteAdminToken/{id}` - 删除管理员 Token
- `GET /v2/ListAdminTokens` - List all admin tokens
- `GET /v2/GetAdminTokenInfo` - Get token information
- `GET /v2/GetCurrentAdminTokenInfo` - Get current token information
- `POST /v2/CreateAdminToken` - Create an admin token
- `POST /v2/UpdateAdminToken/{id}` - Update an admin token
- `POST /v2/DeleteAdminToken/{id}` - Delete an admin token
#### 2. 节点管理
#### 2. Node Management
- `GET /v2/GetNodeInfo/{node}` - 获取节点信息
- `GET /v2/GetNodeStatistics/{node}` - 获取节点统计
- `POST /v2/CreateMetadataSnapshot/{node}` - 创建元数据快照
- `POST /v2/LaunchRepairOperation/{node}` - 启动修复操作
- `GET /v2/GetNodeInfo/{node}` - Get node information
- `GET /v2/GetNodeStatistics/{node}` - Get node statistics
- `POST /v2/CreateMetadataSnapshot/{node}` - Create a metadata snapshot
- `POST /v2/LaunchRepairOperation/{node}` - Launch a repair operation
#### 3. 后台工作进程管理
#### 3. Worker Process Management
- `POST /v2/ListWorkers/{node}` - 列出工作进程
- `POST /v2/GetWorkerInfo/{node}` - 获取工作进程信息
- `POST /v2/GetWorkerVariable/{node}` - 获取工作进程变量
- `POST /v2/SetWorkerVariable/{node}` - 设置工作进程变量
- `POST /v2/ListWorkers/{node}` - List worker processes
- `POST /v2/GetWorkerInfo/{node}` - Get worker process information
- `POST /v2/GetWorkerVariable/{node}` - Get a worker process variable
- `POST /v2/SetWorkerVariable/{node}` - Set a worker process variable
#### 4. 数据块管理
#### 4. Block Management
- `POST /v2/GetBlockInfo/{node}` - 获取数据块信息
- `GET /v2/ListBlockErrors/{node}` - 列出错误数据块
- `POST /v2/RetryBlockResync/{node}` - 重试数据块同步
- `POST /v2/PurgeBlocks/{node}` - 清除数据块
- `POST /v2/GetBlockInfo/{node}` - Get block information
- `GET /v2/ListBlockErrors/{node}` - List block errors
- `POST /v2/RetryBlockResync/{node}` - Retry a block resync
- `POST /v2/PurgeBlocks/{node}` - Purge blocks
#### 5. 特殊端点
#### 5. Special Endpoints
- `GET /health` - 快速健康检查（无需认证）
- `GET /metrics` - Prometheus 指标
- `GET /check` - 按需 TLS 检查
- `GET /health` - Quick health check (no authentication required)
- `GET /metrics` - Prometheus metrics
- `GET /check` - On-demand TLS check
### ⚡ 升级影响分析
### ⚡ Upgrade Impact Analysis
#### 🔴 关键差异
#### 🔴 Key Differences
1. **API 路径结构**
1. **API Path Structure**
- v1: 使用查询参数 (`?id=xxx`)
- v2: 使用 RESTful 路径 (`/{id}`)
- v1: Uses query parameters (`?id=xxx`)
- v2: Uses RESTful paths (`/{id}`)
2. **HTTP 方法**
2. **HTTP Methods**
- v1: 混合使用 GET/POST/PUT/DELETE
- v2: 主要使用 GET/POST
- v1: Uses a mix of GET/POST/PUT/DELETE
- v2: Primarily uses GET/POST
3. **请求/响应格式**
3. **Request/Response Format**
- v2 提供更结构化的数据格式
- 更详细的错误信息和状态码
- v2 provides a more structured data format
- More detailed error messages and status codes
4. **功能完整性**
- v2 提供更多高级管理功能
- 更好的监控和维护能力
4. **Feature Completeness**
- v2 offers more advanced management features
- Better monitoring and maintenance capabilities
#### 🟡 兼容性考虑
#### 🟡 Compatibility Considerations
- **向后兼容**: v1 API 在当前版本中仍然可用（已标记为废弃）
- **迁移建议**: 逐步迁移到 v2 API
- **功能增强**: 利用 v2 新增功能改善用户体验
- **Backward Compatibility**: The v1 API is still available in the current version (marked as deprecated)
- **Migration Recommendation**: Gradually migrate to the v2 API
- **Feature Enhancement**: Utilize new v2 features to improve user experience
### 📋 升级建议
### 📋 Upgrade Recommendations
#### 🎯 短期计划（1-2 个月）
#### 🎯 Short-Term Plan (1-2 months)
1. **API 版本升级**
1. **API Version Upgrade**
- 将核心 API 调用从 v1 升级到 v2
- 更新前端 API 客户端
- 测试兼容性和功能一致性
- Upgrade core API calls from v1 to v2
- Update the frontend API client
- Test for compatibility and functional consistency
2. **基础功能增强**
- 添加集群统计功能
- 实现布局历史查看
- 支持布局变更预览
2. **Basic Feature Enhancements**
- Add cluster statistics functionality
- Implement layout history viewing
- Support layout change previews
#### 🚀 中期计划（3-6 个月）
#### 🚀 Medium-Term Plan (3-6 months)
1. **新功能集成**
1. **New Feature Integration**
- 管理员 Token 管理界面
- 节点详细信息和统计
- 对象检查和分析功能
- Admin token management interface
- Detailed node information and statistics
- Object inspection and analysis functionality
2. **监控增强**
- 集成 Prometheus 指标显示
- 实时健康状态监控
- 错误和告警系统
2. **Monitoring Enhancements**
- Integrate Prometheus metrics display
- Real-time health status monitoring
- Error and alerting system
#### 🎨 长期计划（6 个月以上）
#### 🎨 Long-Term Plan (6+ months)
1. **高级管理功能**
1. **Advanced Management Features**
- 数据块管理和修复工具
- 后台工作进程监控
- 自动化维护任务
- Block management and repair tools
- Worker process monitoring
- Automated maintenance tasks
2. **用户体验优化**
- 批量操作支持
- 实时数据更新
- 移动端适配改进
2. **User Experience Optimization**
- Bulk operations support
- Real-time data updates
- Improved mobile adaptation
### 📊 功能覆盖率分析
### 📊 Feature Coverage Analysis
| 功能分类 | v1 可用功能 | v2 总功能 | 当前使用 | 覆盖率 |
| Feature Category | v1 Available Features | v2 Total Features | Currently Used | Coverage |
| -------------- | ----------- | --------- | -------- | ------ |
| **集群管理** | 4 | 6 | 2 | 33% |
| **布局管理** | 5 | 7 | 5 | 71% |
| **存储桶管理** | 7 | 9 | 5 | 56% |
| **权限管理** | 2 | 2 | 2 | 100% |
| **密钥管理** | 4 | 6 | 4 | 67% |
| **高级功能** | 0 | 25+ | 0 | 0% |
| **总体** | 22 | 55+ | 18 | 33% |
| **Cluster Management** | 4 | 6 | 2 | 33% |
| **Layout Management** | 5 | 7 | 5 | 71% |
| **Bucket Management** | 7 | 9 | 5 | 56% |
| **Permission Management** | 2 | 2 | 2 | 100% |
| **Key Management** | 4 | 6 | 4 | 67% |
| **Advanced Features** | 0 | 25+ | 0 | 0% |
| **Overall** | 22 | 55+ | 18 | 33% |
**结论**: 当前项目仅使用了 Garage Admin API 约 33% 的功能，有很大的功能扩展空间。
**Conclusion**: The current project uses only about 33% of the Garage Admin API's features, leaving significant room for functional expansion.