khairul169/garage-webui
1
0
Fork 0
mirror of https://github.com/khairul169/garage-webui.git synced 2025-10-14 23:09: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 月 - **Completion Date**: December 2024
- 升级范围：前端 React hooks 中的所有 API 调用 - **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` - ✅ `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` - ✅ `useClusterStatus`: `/v1/status` → `/v2/GetClusterStatus`
- ✅ `useClusterLayout`: `/v1/layout` → `/v2/GetClusterLayout` - ✅ `useClusterLayout`: `/v1/layout` → `/v2/GetClusterLayout`
@ -25,19 +25,19 @@
- ✅ `useRevertChanges`: `/v1/layout/revert` → `/v2/RevertClusterLayout` - ✅ `useRevertChanges`: `/v1/layout/revert` → `/v2/RevertClusterLayout`
- ✅ `useApplyChanges`: `/v1/layout/apply` → `/v2/ApplyClusterLayout` - ✅ `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` - ✅ `useKeys`: `/v1/key?list` → `/v2/ListKeys`
- ✅ `useCreateKey`: `/v1/key` → `/v2/CreateKey` - ✅ `useCreateKey`: `/v1/key` → `/v2/CreateKey`
- ✅ `useCreateKey` (导入): `/v1/key/import` → `/v2/ImportKey` - ✅ `useCreateKey` (Import): `/v1/key/import` → `/v2/ImportKey`
- ✅ `useRemoveKey`: `/v1/key` → `/v2/DeleteKey` - ✅ `useRemoveKey`: `/v1/key` → `/v2/DeleteKey`
### 4. Buckets 页面 (`src/pages/buckets/hooks.ts`) ### 4. Buckets Page (`src/pages/buckets/hooks.ts`)
- ✅ `useBuckets`: `/buckets` → `/v2/ListBuckets` - ✅ `useBuckets`: `/buckets` → `/v2/ListBuckets`
- ✅ `useCreateBucket`: `/v1/bucket` → `/v2/CreateBucket` - ✅ `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` - ✅ `useBucket`: `/v1/bucket` → `/v2/GetBucketInfo`
- ✅ `useUpdateBucket`: `/v1/bucket` → `/v2/UpdateBucket` - ✅ `useUpdateBucket`: `/v1/bucket` → `/v2/UpdateBucket`
@ -47,11 +47,11 @@
- ✅ `useDenyKey`: `/v1/bucket/deny` → `/v2/DenyBucketKey` - ✅ `useDenyKey`: `/v1/bucket/deny` → `/v2/DenyBucketKey`
- ✅ `useRemoveBucket`: `/v1/bucket` → `/v2/DeleteBucket` - ✅ `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/health` | `/v2/GetClusterHealth` | ✅ |
| `/v1/status` | `/v2/GetClusterStatus` | ✅ | | `/v1/status` | `/v2/GetClusterStatus` | ✅ |
@ -74,84 +74,84 @@
| `/v1/bucket/allow` | `/v2/AllowBucketKey` | ✅ | | `/v1/bucket/allow` | `/v2/AllowBucketKey` | ✅ |
| `/v1/bucket/deny` | `/v2/DenyBucketKey` | ✅ | | `/v1/bucket/deny` | `/v2/DenyBucketKey` | ✅ |
### 升级数量 ### Upgrade Count
- **总计升级端点**: 18 个 - **Total Endpoints Upgraded**: 18
- **成功升级**: 18 个 (100%) - **Successfully Upgraded**: 18 (100%)
- **升级文件数**: 5 个 TypeScript hook 文件 - **Number of Files Upgraded**: 5 TypeScript hook files
## 后端兼容性 ## Backend Compatibility
✅ **后端无需修改**： ✅ **No Backend Modifications Required**:
- 后端使用反向代理 (`ProxyHandler`) 直接转发 API 请求到 Garage Admin API - The backend uses a reverse proxy (`ProxyHandler`) to directly forward API requests to the Garage Admin API.
- 所有 v2 API 请求会自动转发到正确的 Garage Admin 端点 - All v2 API requests are automatically forwarded to the correct Garage Admin endpoints.
- 无需修改 Go 后端代码 - No changes to the Go backend code were necessary.
## 编译验证 ## Build Verification
✅ **编译成功**： ✅ **Build Successful**:
- TypeScript 编译通过 - TypeScript compilation passed.
- Vite 打包成功 - 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` 类型替换为具体的接口定义 1. **Type Definition Optimization**: Replace `any` types with specific interface definitions.
2. **功能测试**: 在开发环境中测试所有升级的功能 2. **Functional Testing**: Test all upgraded features in a development environment.
3. **文档更新**: 更新项目文档以反映 v2 API 的使用 3. **Documentation Update**: Update project documentation to reflect the use of the v2 API.
4. **错误处理**: 根据 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 端点的实际调用 - Actual calls to all upgraded API endpoints.
- 错误响应的处理 - Handling of error responses.
- 新 API 参数格式的兼容性 - Compatibility of new API parameter formats.
## 回滚计划 ## Rollback Plan
如需回滚到 v1 API： To roll back to the v1 API if necessary:
1. 恢复所有 hook 文件中的 API 路径 1. Restore the API paths in all hook files.
2. 确保 Garage 服务器支持 v1 API 2. Ensure the Garage server supports the v1 API.
3. 重新编译和部署 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 ```http
Authorization: Bearer <token> Authorization: Bearer <token>
``` ```
### Token 类型 ### Token Types
1. **用户定义 Token**（推荐） 1. **User-defined Token** (Recommended)
- 可动态创建和管理 - Can be dynamically created and managed
- 支持作用域限制 - Supports scope limitations
- 支持过期时间设置 - Supports setting an expiration time
- 使用 `garage admin-token` 命令创建 - Created using the `garage admin-token` command
2. **主 Token**（已废弃） 2. **Master Token** (Deprecated)
- 在配置文件中指定 - Specified in the configuration file
- `admin_token`: 管理端点访问 - `admin_token`: For admin endpoint access
- `metrics_token`: 指标端点访问 - `metrics_token`: For metrics endpoint access
### 创建用户定义 Token 示例 ### Example of Creating a User-defined Token
```bash ```bash
garage admin-token create --expires-in 30d \ garage admin-token create --expires-in 30d \
@ -36,15 +36,15 @@ garage admin-token create --expires-in 30d \
my-token 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 ```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` - **Endpoint**: `POST /v2/ConnectClusterNodes`
- **描述**: 指示当前节点连接到其他 Garage 节点 - **Description**: Instructs the current node to connect to other Garage nodes.
- **请求体**: 节点地址数组 `["<node_id>@<net_address>"]` - **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 ```json
{ {
@ -101,47 +101,47 @@ garage admin-token create --expires-in 30d \
} }
``` ```
#### 应用布局变更 #### Apply Layout Changes
- **端点**: `POST /v2/ApplyClusterLayout` - **Endpoint**: `POST /v2/ApplyClusterLayout`
- **描述**: 将暂存的布局变更应用到集群 - **Description**: Applies staged layout changes to the cluster.
- **请求体**: `{"version": <layout_version>}` - **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` - **Endpoint**: `GET /v2/GetBucketInfo`
- **参数**: - **Parameters**:
- `id`: 存储桶 ID - `id`: Bucket ID
- `globalAlias`: 全局别名 - `globalAlias`: Global alias
- `search`: 搜索模式 - `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 ```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 ```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` - **Endpoint**: `POST /v2/CleanupIncompleteUploads`
- **请求体**: `{"bucketId": "bucket-id", "olderThanSecs": 86400}` - **Request Body**: `{"bucketId": "bucket-id", "olderThanSecs": 86400}`
#### 检查对象 #### Inspect Object
- **端点**: `GET /v2/InspectObject` - **Endpoint**: `GET /v2/InspectObject`
- **参数**: `bucketId`, `key` - **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` - **Endpoint**: `GET /v2/ListKeys`
- **描述**: 返回所有 API 访问密钥 - **Description**: Returns all API access keys.
#### 获取密钥信息 #### Get Key Information
- **端点**: `GET /v2/GetKeyInfo` - **Endpoint**: `GET /v2/GetKeyInfo`
- **参数**: - **Parameters**:
- `id`: 密钥 ID - `id`: Key ID
- `search`: 搜索模式 - `search`: Search pattern
- `showSecretKey`: 是否返回密钥（默认不返回） - `showSecretKey`: Whether to return the secret key (default is false).
#### 创建访问密钥 #### Create Access Key
- **端点**: `POST /v2/CreateKey` - **Endpoint**: `POST /v2/CreateKey`
- **请求体示例**: - **Request Body Example**:
```json ```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 ```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` - **Endpoint**: `GET /v2/GetAdminTokenInfo`
- **参数**: `id` 或 `search` - **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 ```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}` - **Endpoint**: `GET /v2/GetNodeInfo/{node}`
- **参数**: `node` - 节点 ID、`*`（所有节点）或 `self`（当前节点） - **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}` - **Endpoint**: `POST /v2/LaunchRepairOperation/{node}`
- **修复类型**: `tables`, `blocks`, `versions`, `multipartUploads`, `blockRefs`, `blockRc`, `rebalance`, `aliases` - **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}` - **Endpoint**: `POST /v2/GetBlockInfo/{node}`
- **请求体**: `{"blockHash": "hash-value"}` - **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` - **Endpoint**: `GET /health`
- **认证**: 无需认证 - **Authentication**: None required
- **描述**: 快速健康检查，返回 200 表示服务可用 - **Description**: Quick health check, returns 200 if the service is available.
#### Prometheus 指标 #### Prometheus Metrics
- **端点**: `GET /metrics` - **Endpoint**: `GET /metrics`
- **认证**: 可选（使用 metrics_token） - **Authentication**: Optional (using `metrics_token`)
- **描述**: 返回 Prometheus 格式的监控指标 - **Description**: Returns monitoring metrics in Prometheus format.
#### 按需 TLS 检查 #### On-Demand TLS Check
- **端点**: `GET /check?domain=<domain>` - **Endpoint**: `GET /check?domain=<domain>`
- **认证**: 无需认证 - **Authentication**: None required
- **描述**: 用于反向代理（如 Caddy）的按需 TLS 证书验证 - **Description**: Used for on-demand TLS certificate validation by reverse proxies (like Caddy).
## 使用示例 ## Usage Example
### 使用 curl ### Using curl
```bash ```bash
# 获取集群健康状态 # Get cluster health status
curl -H 'Authorization: Bearer YOUR_TOKEN' \ curl -H 'Authorization: Bearer YOUR_TOKEN' \
http://localhost:3903/v2/GetClusterHealth http://localhost:3903/v2/GetClusterHealth
# 创建存储桶 # Create a bucket
curl -X POST \ curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \ -H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \ -H 'Content-Type: application/json' \
-d '{"globalAlias": "my-bucket"}' \ -d '{"globalAlias": "my-bucket"}' \
http://localhost:3903/v2/CreateBucket http://localhost:3903/v2/CreateBucket
# 列出所有存储桶 # List all buckets
curl -H 'Authorization: Bearer YOUR_TOKEN' \ curl -H 'Authorization: Bearer YOUR_TOKEN' \
http://localhost:3903/v2/ListBuckets http://localhost:3903/v2/ListBuckets
``` ```
### 使用 Garage CLI ### Using the Garage CLI
```bash ```bash
# 通过内部 RPC 调用（无需认证） # Call via internal RPC (no authentication required)
garage json-api GetClusterHealth garage json-api GetClusterHealth
# 带参数的调用 # Call with parameters
garage json-api GetBucketInfo '{"globalAlias": "my-bucket"}' garage json-api GetBucketInfo '{"globalAlias": "my-bucket"}'
# 从标准输入读取参数 # Read parameters from standard input
garage json-api CreateBucket - garage json-api CreateBucket -
{"globalAlias": "test-bucket"} {"globalAlias": "test-bucket"}
<EOF> <EOF>
``` ```
## 错误处理 ## Error Handling
API 使用标准 HTTP 状态码： The API uses standard HTTP status codes:
- `200 OK` - 请求成功 - `200 OK` - Request successful
- `400 Bad Request` - 请求参数错误 - `400 Bad Request` - Invalid request parameters
- `401 Unauthorized` - 认证失败 - `401 Unauthorized` - Authentication failed
- `403 Forbidden` - 权限不足 - `403 Forbidden` - Insufficient permissions
- `404 Not Found` - 资源不存在 - `404 Not Found` - Resource not found
- `500 Internal Server Error` - 服务器内部错误 - `500 Internal Server Error` - Internal server error
错误响应通常包含详细的错误信息： Error responses typically include detailed error information:
```json ```json
{ {
@ -445,38 +445,38 @@ API 使用标准 HTTP 状态码：
} }
``` ```
## 权限作用域 ## Permission Scopes
管理员 Token 可以限制访问特定的 API 端点： Admin tokens can be restricted to specific API endpoints:
- `*` - 允许所有端点 - `*` - Allows all endpoints
- `ListBuckets` - 列出存储桶 - `ListBuckets` - List buckets
- `GetBucketInfo` - 获取存储桶信息 - `GetBucketInfo` - Get bucket information
- `CreateBucket` - 创建存储桶 - `CreateBucket` - Create a bucket
- `ListKeys` - 列出访问密钥 - `ListKeys` - List access keys
- `CreateKey` - 创建访问密钥 - `CreateKey` - Create an access key
- `AllowBucketKey` - 授予权限 - `AllowBucketKey` - Grant permissions
- `DenyBucketKey` - 拒绝权限 - `DenyBucketKey` - Deny permissions
- `Metrics` - 访问指标端点 - `Metrics` - Access the metrics endpoint
## 最佳实践 ## Best Practices
1. **使用用户定义 Token**：避免使用配置文件中的主 Token 1. **Use User-defined Tokens**: Avoid using the master token from the configuration file.
2. **设置适当的作用域**：只授予必要的权限 2. **Set Appropriate Scopes**: Grant only necessary permissions.
3. **设置过期时间**：定期轮换 Token 3. **Set Expiration Times**: Rotate tokens periodically.
4. **监控 API 使用**：通过 `/metrics` 端点监控 API 调用 4. **Monitor API Usage**: Monitor API calls via the `/metrics` endpoint.
5. **错误处理**：妥善处理各种错误情况 5. **Handle Errors**: Properly handle various error conditions.
6. **批量操作**：对于大量操作，考虑使用批量 API 或脚本 6. **Bulk Operations**: For a large number of operations, consider using bulk APIs or scripts.
## 版本历史 ## Version History
- **v0** - Garage v0.7.2 首次引入（已废弃） - **v0** - First introduced in Garage v0.7.2 (deprecated)
- **v1** - Garage v0.9.0 引入（已废弃） - **v1** - Introduced in Garage v0.9.0 (deprecated)
- **v2** - Garage v2.0.0 引入（当前版本） - **v2** - Introduced in Garage v2.0.0 (current version)
## 相关链接 ## Related Links
- [Garage 官方文档](https://garagehq.deuxfleurs.fr/documentation/) - [Garage Official Documentation](https://garagehq.deuxfleurs.fr/documentation/)
- [OpenAPI 规范 (HTML)](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html) - [OpenAPI Specification (HTML)](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html)
- [OpenAPI 规范 (JSON)](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.json) - [OpenAPI Specification (JSON)](https://garagehq.deuxfleurs.fr/api/garage-admin-v2.json)
- [Garage 源代码](https://git.deuxfleurs.fr/Deuxfleurs/garage) - [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 集群管理员和运维人员 - **Target Users**: Garage cluster administrators and operations personnel
- **核心价值**: 简化 Garage 集群的日常管理操作 - **Core Value**: Simplify the daily management operations of Garage clusters
- **技术栈**: TypeScript + React (前端) + Go (后端) - **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 访问密钥 - **Key List**: Displays all API access keys
- **密钥创建**: 创建新的 S3 兼容访问密钥 - **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 │ │ Web Browser │───▶│ Garage Web UI │───▶│ Garage Cluster │
│ (前端界面) │ │ (Go 后端服务) │ │ (Admin API) │ │ (Frontend UI) │ │ (Go Backend) │ │ (Admin API) │
└─────────────────┘ └──────────────────┘ └─────────────────┘ └─────────────────┘ └──────────────────┘ └─────────────────┘
``` ```
### 📁 项目结构 ### 📁 Project Structure
``` ```
garage-webui/ garage-webui/
├── src/ # React 前端源码 ├── src/ # React Frontend Source
│ ├── pages/ # 页面组件 │ ├── pages/ # Page Components
│ │ ├── home/ # 首页仪表板 │ │ ├── home/ # Home Dashboard
│ │ ├── cluster/ # 集群管理 │ │ ├── cluster/ # Cluster Management
│ │ ├── buckets/ # 存储桶管理 │ │ ├── buckets/ # Bucket Management
│ │ └── keys/ # 访问密钥管理 │ │ └── keys/ # Access Key Management
│ ├── components/ # 可复用组件 │ ├── components/ # Reusable Components
│ ├── hooks/ # React Hooks │ ├── hooks/ # React Hooks
│ └── lib/ # 工具库 │ └── lib/ # Utility Libraries
├── backend/ # Go 后端源码 ├── backend/ # Go Backend Source
│ ├── main.go # 服务入口 │ ├── main.go # Service Entrypoint
│ ├── router/ # API 路由 │ ├── router/ # API Routes
│ ├── utils/ # 工具函数 │ ├── utils/ # Utility Functions
│ └── schema/ # 数据结构 │ └── schema/ # Data Structures
├── docs/ # 项目文档 ├── docs/ # Project Documentation
└── misc/ # 截图等资源 └── misc/ # Screenshots and other resources
``` ```
### 🔌 后端服务架构 ### 🔌 Backend Service Architecture
#### 核心模块 #### Core Modules
1. **配置管理** (`utils/garage.go`) 1. **Configuration Management** (`utils/garage.go`)
- 自动读取 Garage 配置文件 (`garage.toml`) - Automatically reads the Garage configuration file (`garage.toml`)
- 提取管理 API 端点、认证信息等 - Extracts admin API endpoints, authentication information, etc.
- 支持环境变量覆盖配置 - Supports overriding configuration with environment variables
2. **API 代理** (`router/`) 2. **API Proxy** (`router/`)
- 代理前端请求到 Garage Admin API - Proxies frontend requests to the Garage Admin API
- 处理认证和错误转换 - Handles authentication and error translation
- 提供统一的 RESTful 接口 - 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`) 4. **Caching Mechanism** (`utils/cache.go`)
- API 响应缓存 - Caches API responses
- 减少对 Garage 集群的请求压力 - Reduces request pressure on the Garage cluster
## 部署方案 ## Deployment Scenarios
### 🐳 Docker 部署（推荐） ### 🐳 Docker Deployment (Recommended)
#### 1. 与 Garage 集群一起部署 #### 1. Deploying with a Garage Cluster
```yaml ```yaml
services: services:
@ -147,7 +147,7 @@ services:
S3_ENDPOINT_URL: "http://garage:3900" S3_ENDPOINT_URL: "http://garage:3900"
``` ```
#### 2. 独立部署 #### 2. Standalone Deployment
```bash ```bash
docker run -p 3909:3909 \ docker run -p 3909:3909 \
@ -157,18 +157,18 @@ docker run -p 3909:3909 \
khairul169/garage-webui:latest khairul169/garage-webui:latest
``` ```
### 🖥️ 二进制部署 ### 🖥️ Binary Deployment
```bash ```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 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 chmod +x garage-webui
# 运行服务 # Run the service
CONFIG_PATH=./garage.toml ./garage-webui CONFIG_PATH=./garage.toml ./garage-webui
``` ```
### 🔧 SystemD 服务 ### 🔧 SystemD Service
```ini ```ini
[Unit] [Unit]
@ -185,97 +185,97 @@ Restart=always
WantedBy=default.target 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 ```toml
# garage.toml # garage.toml
[admin] [admin]
api_bind_addr = "[::]:3903" api_bind_addr = "[::]:3903"
admin_token = "your-secure-admin-token" admin_token = "your-secure-admin-token"
metrics_token = "your-metrics-token" # 可选 metrics_token = "your-metrics-token" # Optional
``` ```
### 🌍 环境变量配置 ### 🌍 Environment Variable Configuration
| 变量名 | 描述 | 默认值 | | Variable Name | Description | Default Value |
| ----------------- | --------------------- | ------------------ | | ----------------- | ----------------------------- | -------------------- |
| `CONFIG_PATH` | Garage 配置文件路径 | `/etc/garage.toml` | | `CONFIG_PATH` | Path to Garage config file | `/etc/garage.toml` |
| `API_BASE_URL` | Garage Admin API 地址 | 从配置文件读取 | | `API_BASE_URL` | Garage Admin API address | Read from config file|
| `API_ADMIN_KEY` | Admin API 令牌 | 从配置文件读取 | | `API_ADMIN_KEY` | Admin API token | Read from config file|
| `S3_ENDPOINT_URL` | S3 API 地址 | 从配置文件读取 | | `S3_ENDPOINT_URL` | S3 API address | Read from config file|
| `S3_REGION` | S3 区域 | `garage` | | `S3_REGION` | S3 region | `garage` |
| `BASE_PATH` | Web UI 基础路径 | `/` | | `BASE_PATH` | Web UI base path | `/` |
| `PORT` | 服务端口 | `3909` | | `PORT` | Service port | `3909` |
| `HOST` | 绑定地址 | `0.0.0.0` | | `HOST` | Binding address | `0.0.0.0` |
### 🔐 认证配置 ### 🔐 Authentication Configuration
#### 启用 Web UI 认证 #### Enable Web UI Authentication
```bash ```bash
# 生成密码哈希 # Generate password hash
htpasswd -nbBC 10 "admin" "password" htpasswd -nbBC 10 "admin" "password"
# 设置环境变量 # Set environment variable
AUTH_USER_PASS="admin:$2y$10$DSTi9o..." AUTH_USER_PASS="admin:$2y$10$DSTi9o..."
``` ```
## 管理最佳实践 ## Management Best Practices
### 🚀 日常运维 ### 🚀 Daily Operations
#### 1. 集群健康监控 #### 1. Cluster Health Monitoring
- **定期检查**: 通过首页仪表板监控集群状态 - **Regular Checks**: Monitor cluster status via the home dashboard
- **告警设置**: 配置监控系统对接 `/metrics` 端点 - **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 ```bash
# 检查 Admin API 可访问性 # Check Admin API accessibility
curl -H "Authorization: Bearer YOUR_TOKEN" \ curl -H "Authorization: Bearer YOUR_TOKEN" \
http://garage-host:3903/v2/GetClusterHealth http://garage-host:3903/v2/GetClusterHealth
# 检查网络连通性 # Check network connectivity
telnet garage-host 3903 telnet garage-host 3903
``` ```
#### 2. 配置问题 #### 2. Configuration Issues
- 验证 `garage.toml` 配置正确性 - Verify the correctness of the `garage.toml` configuration
- 确认 Admin API 端口已开放 - Confirm that the Admin API port is open
- 检查防火墙和网络策略 - Check firewall and network policies
#### 3. 性能优化 #### 3. Performance Optimization
- 启用缓存机制减少 API 调用 - Enable caching to reduce API calls
- 使用反向代理（如 Nginx）提供 SSL 终止 - 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 ```yaml
# prometheus.yml # prometheus.yml
@ -287,364 +287,361 @@ scrape_configs:
bearer_token: "your-metrics-token" bearer_token: "your-metrics-token"
``` ```
#### 关键指标 #### Key Metrics
- `garage_cluster_health`: 集群健康状态 - `garage_cluster_health`: Cluster health status
- `garage_storage_usage`: 存储使用情况 - `garage_storage_usage`: Storage usage
- `garage_api_requests`: API 请求统计 - `garage_api_requests`: API request statistics
- `garage_replication_status`: 数据复制状态 - `garage_replication_status`: Data replication status
## 开发指南 ## Development Guide
### 🛠️ 开发环境搭建 ### 🛠️ Development Environment Setup
```bash ```bash
# 克隆项目 # Clone the project
git clone https://github.com/khairul169/garage-webui.git git clone https://github.com/khairul169/garage-webui.git
cd garage-webui cd garage-webui
# 安装前端依赖 # Install frontend dependencies
pnpm install pnpm install
# 安装后端依赖 # Install backend dependencies
cd backend && go mod download && cd .. cd backend && go mod download && cd ..
# 启动开发服务器 # Start the development server
pnpm run dev pnpm run dev
``` ```
### 🔧 技术选型说明 ### 🔧 Technology Choices
- **前端**: React 18 + TypeScript + Tailwind CSS - **Frontend**: React 18 + TypeScript + Tailwind CSS
- **状态管理**: React Query (TanStack Query) - **State Management**: React Query (TanStack Query)
- **路由**: React Router - **Routing**: React Router
- **UI 组件**: 自定义组件库 - **UI Components**: Custom component library
- **后端**: Go + Gin 框架 - **Backend**: Go + Gin framework
- **配置解析**: go-toml - **Configuration Parsing**: go-toml
### 📋 贡献指南 ### 📋 Contribution Guidelines
1. **代码规范**: 遵循项目的 ESLint 和 Go fmt 规范 1. **Coding Standards**: Follow the project's ESLint and Go fmt standards
2. **测试**: 新功能需要添加相应测试 2. **Testing**: New features require corresponding tests
3. **文档**: 更新相关文档和 API 说明 3. **Documentation**: Update relevant documents and API descriptions
4. **兼容性**: 确保与最新版本 Garage 兼容 4. **Compatibility**: Ensure compatibility with the latest version of Garage
## 安全考虑 ## Security Considerations
### 🔒 安全建议 ### 🔒 Security Recommendations
1. **网络安全** 1. **Network Security**
- 在生产环境中使用 HTTPS - Use HTTPS in production environments
- 限制 Admin API 的网络访问 - 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. **权限控制** 3. **Permission Control**
- 遵循最小权限原则 - Follow the principle of least privilege
- 定期审计访问权限 - Use a dedicated administrator token
- 使用专用的管理员 Token
## 未来规划 ## Future Plans
### 🚀 功能路线图 ### 🚀 Feature Roadmap
- **高级监控**: 集成更多性能指标和告警功能 - **Advanced Monitoring**: Integrate more performance metrics and alerting features
- **批量操作**: 支持批量管理存储桶和访问密钥 - **Bulk Operations**: Support bulk management of buckets and access keys
- **API 扩展**: 支持更多 Garage Admin API 功能 - **API Expansion**: Support more Garage Admin API features
- **国际化**: 多语言支持 - **Internationalization**: Multi-language support
- **主题系统**: 可定制的 UI 主题 - **Theming System**: Customizable UI themes
### 🔧 技术改进 ### 🔧 Technical Improvements
- **缓存优化**: 更智能的缓存策略 - **Cache Optimization**: Smarter caching strategies
- **实时更新**: WebSocket 支持实时状态更新 - **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
- 添加新节点到集群 - Adds new nodes to the cluster
- 修改节点配置（容量、区域、标签） - Modifies node configuration (capacity, zone, tags)
- 移除节点（设置 remove: true） - Removes nodes (by setting `remove: true`)
- **`POST /v1/connect`** - 连接集群节点 - **`POST /v1/connect`** - Connect cluster nodes
- 将新节点连接到集群 - Connects new nodes to the cluster
- 建立节点间的 RPC 连接 - 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` | ⚠️ 需升级 | | **Cluster Health Status** | `GET /v1/health` | `GET /v2/GetClusterHealth` | ⚠️ Upgrade Needed |
| **集群状态** | `GET /v1/status` | `GET /v2/GetClusterStatus` | ⚠️ 需升级 | | **Cluster Status** | `GET /v1/status` | `GET /v2/GetClusterStatus` | ⚠️ Upgrade Needed |
| **集群统计** | ❌ 未使用 | `GET /v2/GetClusterStatistics` | 🆕 新功能 | | **Cluster Statistics** | ❌ Not Used | `GET /v2/GetClusterStatistics` | 🆕 New Feature |
| **连接节点** | `POST /v1/connect` | `POST /v2/ConnectClusterNodes` | ⚠️ 需升级 | | **Connect Nodes** | `POST /v1/connect` | `POST /v2/ConnectClusterNodes` | ⚠️ Upgrade Needed |
| **获取布局** | `GET /v1/layout` | `GET /v2/GetClusterLayout` | ⚠️ 需升级 | | **Get Layout** | `GET /v1/layout` | `GET /v2/GetClusterLayout` | ⚠️ Upgrade Needed |
| **更新布局** | `POST /v1/layout` | `POST /v2/UpdateClusterLayout` | ⚠️ 需升级 | | **Update Layout** | `POST /v1/layout` | `POST /v2/UpdateClusterLayout` | ⚠️ Upgrade Needed |
| **应用布局** | `POST /v1/layout/apply` | `POST /v2/ApplyClusterLayout` | ⚠️ 需升级 | | **Apply Layout** | `POST /v1/layout/apply` | `POST /v2/ApplyClusterLayout` | ⚠️ Upgrade Needed |
| **回滚布局** | `POST /v1/layout/revert` | `POST /v2/RevertClusterLayout` | ⚠️ 需升级 | | **Revert Layout** | `POST /v1/layout/revert` | `POST /v2/RevertClusterLayout` | ⚠️ Upgrade Needed |
| **布局历史** | ❌ 未使用 | `GET /v2/GetClusterLayoutHistory` | 🆕 新功能 | | **Layout History** | ❌ Not Used | `GET /v2/GetClusterLayoutHistory` | 🆕 New Feature |
| **预览布局变更** | ❌ 未使用 | `POST /v2/PreviewClusterLayoutChanges` | 🆕 新功能 | | **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` | 参数格式不同 | | **List Buckets** | `GET /v1/bucket?list` | `GET /v2/ListBuckets` | Parameter format differs |
| **获取桶信息** | `GET /v1/bucket?id={id}` | `GET /v2/GetBucketInfo` | 支持更多查询方式 | | **Get Bucket Info** | `GET /v1/bucket?id={id}` | `GET /v2/GetBucketInfo` | Supports more query methods |
| **创建存储桶** | `POST /v1/bucket` | `POST /v2/CreateBucket` | v2 支持更多配置选项 | | **Create Bucket** | `POST /v1/bucket` | `POST /v2/CreateBucket` | v2 supports more configuration options |
| **更新存储桶** | `PUT /v1/bucket?id={id}` | `POST /v2/UpdateBucket/{id}` | HTTP 方法和路径不同 | | **Update Bucket** | `PUT /v1/bucket?id={id}` | `POST /v2/UpdateBucket/{id}` | HTTP method and path differ |
| **删除存储桶** | `DELETE /v1/bucket?id={id}` | `POST /v2/DeleteBucket/{id}` | HTTP 方法不同 | | **Delete Bucket** | `DELETE /v1/bucket?id={id}` | `POST /v2/DeleteBucket/{id}` | HTTP method differs |
| **添加别名** | `PUT /v1/bucket/alias/global` | `POST /v2/AddBucketAlias` | 支持本地别名 | | **Add Alias** | `PUT /v1/bucket/alias/global` | `POST /v2/AddBucketAlias` | Supports local aliases |
| **删除别名** | `DELETE /v1/bucket/alias/global` | `POST /v2/RemoveBucketAlias` | 支持本地别名 | | **Delete Alias** | `DELETE /v1/bucket/alias/global` | `POST /v2/RemoveBucketAlias` | Supports local aliases |
| **清理上传** | ❌ 未使用 | `POST /v2/CleanupIncompleteUploads` | 🆕 新功能 | | **Cleanup Uploads** | ❌ Not Used | `POST /v2/CleanupIncompleteUploads` | 🆕 New Feature |
| **检查对象** | ❌ 未使用 | `GET /v2/InspectObject` | 🆕 新功能 | | **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` | 参数格式不同 | | **List Keys** | `GET /v1/key?list` | `GET /v2/ListKeys` | Parameter format differs |
| **获取密钥信息** | ❌ 未使用 | `GET /v2/GetKeyInfo` | 🆕 新功能 | | **Get Key Info** | ❌ Not Used | `GET /v2/GetKeyInfo` | 🆕 New Feature |
| **创建密钥** | `POST /v1/key` | `POST /v2/CreateKey` | v2 支持更多选项 | | **Create Key** | `POST /v1/key` | `POST /v2/CreateKey` | v2 supports more options |
| **更新密钥** | ❌ 未使用 | `POST /v2/UpdateKey/{id}` | 🆕 新功能 | | **Update Key** | ❌ Not Used | `POST /v2/UpdateKey/{id}` | 🆕 New Feature |
| **删除密钥** | `DELETE /v1/key?id={id}` | `POST /v2/DeleteKey/{id}` | HTTP 方法不同 | | **Delete Key** | `DELETE /v1/key?id={id}` | `POST /v2/DeleteKey/{id}` | HTTP method differs |
| **导入密钥** | `POST /v1/key/import` | `POST /v2/ImportKey` | 路径结构不同 | | **Import Key** | `POST /v1/key/import` | `POST /v2/ImportKey` | Path structure differs |
| **授予权限** | `POST /v1/bucket/allow` | `POST /v2/AllowBucketKey` | 路径结构不同 | | **Grant Permission** | `POST /v1/bucket/allow` | `POST /v2/AllowBucketKey` | Path structure differs |
| **撤销权限** | `POST /v1/bucket/deny` | `POST /v2/DenyBucketKey` | 路径结构不同 | | **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/ListAdminTokens` - List all admin tokens
- `GET /v2/GetAdminTokenInfo` - 获取 Token 信息 - `GET /v2/GetAdminTokenInfo` - Get token information
- `GET /v2/GetCurrentAdminTokenInfo` - 获取当前 Token 信息 - `GET /v2/GetCurrentAdminTokenInfo` - Get current token information
- `POST /v2/CreateAdminToken` - 创建管理员 Token - `POST /v2/CreateAdminToken` - Create an admin token
- `POST /v2/UpdateAdminToken/{id}` - 更新管理员 Token - `POST /v2/UpdateAdminToken/{id}` - Update an admin token
- `POST /v2/DeleteAdminToken/{id}` - 删除管理员 Token - `POST /v2/DeleteAdminToken/{id}` - Delete an admin token
#### 2. 节点管理 #### 2. Node Management
- `GET /v2/GetNodeInfo/{node}` - 获取节点信息 - `GET /v2/GetNodeInfo/{node}` - Get node information
- `GET /v2/GetNodeStatistics/{node}` - 获取节点统计 - `GET /v2/GetNodeStatistics/{node}` - Get node statistics
- `POST /v2/CreateMetadataSnapshot/{node}` - 创建元数据快照 - `POST /v2/CreateMetadataSnapshot/{node}` - Create a metadata snapshot
- `POST /v2/LaunchRepairOperation/{node}` - 启动修复操作 - `POST /v2/LaunchRepairOperation/{node}` - Launch a repair operation
#### 3. 后台工作进程管理 #### 3. Worker Process Management
- `POST /v2/ListWorkers/{node}` - 列出工作进程 - `POST /v2/ListWorkers/{node}` - List worker processes
- `POST /v2/GetWorkerInfo/{node}` - 获取工作进程信息 - `POST /v2/GetWorkerInfo/{node}` - Get worker process information
- `POST /v2/GetWorkerVariable/{node}` - 获取工作进程变量 - `POST /v2/GetWorkerVariable/{node}` - Get a worker process variable
- `POST /v2/SetWorkerVariable/{node}` - 设置工作进程变量 - `POST /v2/SetWorkerVariable/{node}` - Set a worker process variable
#### 4. 数据块管理 #### 4. Block Management
- `POST /v2/GetBlockInfo/{node}` - 获取数据块信息 - `POST /v2/GetBlockInfo/{node}` - Get block information
- `GET /v2/ListBlockErrors/{node}` - 列出错误数据块 - `GET /v2/ListBlockErrors/{node}` - List block errors
- `POST /v2/RetryBlockResync/{node}` - 重试数据块同步 - `POST /v2/RetryBlockResync/{node}` - Retry a block resync
- `POST /v2/PurgeBlocks/{node}` - 清除数据块 - `POST /v2/PurgeBlocks/{node}` - Purge blocks
#### 5. 特殊端点 #### 5. Special Endpoints
- `GET /health` - 快速健康检查（无需认证） - `GET /health` - Quick health check (no authentication required)
- `GET /metrics` - Prometheus 指标 - `GET /metrics` - Prometheus metrics
- `GET /check` - 按需 TLS 检查 - `GET /check` - On-demand TLS check
### ⚡ 升级影响分析 ### ⚡ Upgrade Impact Analysis
#### 🔴 关键差异 #### 🔴 Key Differences
1. **API 路径结构** 1. **API Path Structure**
- v1: 使用查询参数 (`?id=xxx`) - v1: Uses query parameters (`?id=xxx`)
- v2: 使用 RESTful 路径 (`/{id}`) - v2: Uses RESTful paths (`/{id}`)
2. **HTTP 方法** 2. **HTTP Methods**
- v1: 混合使用 GET/POST/PUT/DELETE - v1: Uses a mix of GET/POST/PUT/DELETE
- v2: 主要使用 GET/POST - 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. **功能完整性** 4. **Feature Completeness**
- v2 提供更多高级管理功能 - v2 offers more advanced management features
- 更好的监控和维护能力 - Better monitoring and maintenance capabilities
#### 🟡 兼容性考虑 #### 🟡 Compatibility Considerations
- **向后兼容**: v1 API 在当前版本中仍然可用（已标记为废弃） - **Backward Compatibility**: The v1 API is still available in the current version (marked as deprecated)
- **迁移建议**: 逐步迁移到 v2 API - **Migration Recommendation**: Gradually migrate to the v2 API
- **功能增强**: 利用 v2 新增功能改善用户体验 - **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 - Upgrade core API calls from v1 to v2
- 更新前端 API 客户端 - 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. **监控增强** 2. **Monitoring Enhancements**
- 集成 Prometheus 指标显示 - 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% | | **Cluster Management** | 4 | 6 | 2 | 33% |
| **布局管理** | 5 | 7 | 5 | 71% | | **Layout Management** | 5 | 7 | 5 | 71% |
| **存储桶管理** | 7 | 9 | 5 | 56% | | **Bucket Management** | 7 | 9 | 5 | 56% |
| **权限管理** | 2 | 2 | 2 | 100% | | **Permission Management** | 2 | 2 | 2 | 100% |
| **密钥管理** | 4 | 6 | 4 | 67% | | **Key Management** | 4 | 6 | 4 | 67% |
| **高级功能** | 0 | 25+ | 0 | 0% | | **Advanced Features** | 0 | 25+ | 0 | 0% |
| **总体** | 22 | 55+ | 18 | 33% | | **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.