From 642b20efb0a224843d69c38b84d81ffd40076b59 Mon Sep 17 00:00:00 2001 From: Adekabang Date: Wed, 30 Jul 2025 23:48:36 -0400 Subject: [PATCH] Translate Garage Web UI project management documentation from Chinese to English and update content for clarity and consistency. --- docs/api-upgrade-report.md | 134 +++---- docs/garage-admin-api.md | 446 ++++++++++----------- docs/garage-webui-管理文档.md | 731 +++++++++++++++++----------------- 3 files changed, 654 insertions(+), 657 deletions(-) diff --git a/docs/api-upgrade-report.md b/docs/api-upgrade-report.md index 474990d..faf3036 100644 --- a/docs/api-upgrade-report.md +++ b/docs/api-upgrade-report.md @@ -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. diff --git a/docs/garage-admin-api.md b/docs/garage-admin-api.md index c703c8c..2e68f4e 100644 --- a/docs/garage-admin-api.md +++ b/docs/garage-admin-api.md @@ -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 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 节点 -- **请求体**: 节点地址数组 `["@"]` +- **Endpoint**: `POST /v2/ConnectClusterNodes` +- **Description**: Instructs the current node to connect to other Garage nodes. +- **Request Body**: An array of node addresses `["@"]` -### 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": }` +- **Endpoint**: `POST /v2/ApplyClusterLayout` +- **Description**: Applies staged layout changes to the cluster. +- **Request Body**: `{"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=` -- **认证**: 无需认证 -- **描述**: 用于反向代理(如 Caddy)的按需 TLS 证书验证 +- **Endpoint**: `GET /check?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"} ``` -## 错误处理 +## 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) diff --git a/docs/garage-webui-管理文档.md b/docs/garage-webui-管理文档.md index e24805e..7b38b0e 100644 --- a/docs/garage-webui-管理文档.md +++ b/docs/garage-webui-管理文档.md @@ -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.