(without INSTANCE_ID)
// e.g., rest = "ENABLE" -> field_name="ENABLE", instance_id="" (Universal configuration `_ DEFAULT_DELIMITER`)
None => (instance_id_part.to_lowercase(), DEFAULT_DELIMITER.to_string()),
};
diff --git a/crates/obs/src/metrics/entry/subsystem.rs b/crates/obs/src/metrics/entry/subsystem.rs
index 0b081ae5..56413eb3 100644
--- a/crates/obs/src/metrics/entry/subsystem.rs
+++ b/crates/obs/src/metrics/entry/subsystem.rs
@@ -123,7 +123,7 @@ impl MetricSubsystem {
// Debug related subsystems
"/debug/go" => Self::DebugGo,
- // 集群相关子系统
+ // Cluster-related subsystems
"/cluster/health" => Self::ClusterHealth,
"/cluster/usage/objects" => Self::ClusterUsageObjects,
"/cluster/usage/buckets" => Self::ClusterUsageBuckets,
@@ -131,7 +131,7 @@ impl MetricSubsystem {
"/cluster/iam" => Self::ClusterIam,
"/cluster/config" => Self::ClusterConfig,
- // 其他服务相关子系统
+ // Other service-related subsystems
"/ilm" => Self::Ilm,
"/audit" => Self::Audit,
"/logger/webhook" => Self::LoggerWebhook,
@@ -139,7 +139,7 @@ impl MetricSubsystem {
"/notification" => Self::Notification,
"/scanner" => Self::Scanner,
- // 其他路径作为自定义处理
+ // Treat other paths as custom subsystems
_ => Self::Custom(path.to_string()),
}
}
diff --git a/crates/rio/src/hash_reader.rs b/crates/rio/src/hash_reader.rs
index 03f13864..eb9e773f 100644
--- a/crates/rio/src/hash_reader.rs
+++ b/crates/rio/src/hash_reader.rs
@@ -727,14 +727,14 @@ mod tests {
assert_eq!(final_data.len() as i64, actual_size);
assert_eq!(&final_data, &data);
} else {
- // 如果没有压缩，直接比较解密后的数据
+ // Without compression we can compare the decrypted bytes directly
assert_eq!(decrypted_data.len() as i64, actual_size);
assert_eq!(&decrypted_data, &data);
}
return;
}
- // 如果不加密，直接处理压缩/解压缩
+ // When encryption is disabled, only handle compression/decompression
if is_compress {
let decompress_reader =
DecompressReader::new(WarpReader::new(Cursor::new(compressed_data)), CompressionAlgorithm::Gzip);
@@ -749,7 +749,7 @@ mod tests {
assert_eq!(&compressed_data, &data);
}
- // 验证 etag（注意：压缩会改变数据，所以这里的 etag 验证可能需要调整）
+ // Validate the etag (compression alters the payload, so this may require adjustments)
println!("Test completed successfully with compression: {is_compress}, encryption: {is_encrypt}");
}
diff --git a/crates/utils/src/net.rs b/crates/utils/src/net.rs
index 5769d654..94bb89e3 100644
--- a/crates/utils/src/net.rs
+++ b/crates/utils/src/net.rs
@@ -620,7 +620,7 @@ mod test {
assert!(!is_socket_addr(&long_string));
// Test unicode characters
- assert!(!is_socket_addr("测试.example.com"));
+ assert!(!is_socket_addr("пример.example.com"));
// Test special characters
assert!(!is_socket_addr("test@example.com:8080"));
diff --git a/deploy/build/rustfs-zh.service b/deploy/build/rustfs-zh.service
index b6add428..1cc3373b 100644
--- a/deploy/build/rustfs-zh.service
+++ b/deploy/build/rustfs-zh.service
@@ -1,49 +1,48 @@
[Unit]
Description=RustFS Object Storage Server
-# 定义服务的描述，说明这是一个 RustFS 对象存储服务器，显示在 systemctl status 中。
+# Describe the RustFS object storage service as shown in `systemctl status`.
Documentation=https://rustfs.com/docs/
-# 提供服务的官方文档链接，方便管理员查阅，占位符需替换为实际 URL。
+# Provide a documentation link for operators.
After=network-online.target
-# 指定服务在 network-online.target（网络就绪）之后启动，确保网络可用。
+# Ensure the service starts only after the network is online.
Wants=network-online.target
-# 表示服务希望依赖 network-online.target，但不是强依赖，即使网络未就绪也尝试启动。
+# Express a soft dependency on `network-online.target` so we still attempt to start if the network is late.
# If you're using a database, you'll need to add the corresponding dependencies
-# 如果服务依赖数据库，可以添加数据库相关的依赖项（当前为注释，未启用）。
+# Uncomment these directives when a database is required.
# After=postgresql.service
-# 示例：若依赖 PostgreSQL，则在 PostgreSQL 服务后启动（当前未启用）。
+# Example: start after PostgreSQL when the dependency is needed.
# Requires=postgresql.service
-# 示例：若强制依赖 PostgreSQL，则要求其启动成功（当前未启用）。
+# Example: make PostgreSQL a hard requirement.
[Service]
Type=notify
-# 服务类型为 notify，表示服务通过 sd_notify 通知 systemd 其状态（如就绪）。
+# Use the `notify` type so the process reports readiness via `sd_notify`.
NotifyAccess=main
-# 指定只有主进程可以发送通知给 systemd，避免子进程干扰。
+# Only the main process can send notifications back to systemd.
User=rustfs
-# 以 rustfs 用户身份运行服务，需预先创建此用户，提升安全性。
+# Run as the dedicated `rustfs` user (create it ahead of time for security).
Group=rustfs
-# 以 rustfs 组身份运行服务，与 User 配合使用。
+# Use the matching `rustfs` group.
# working directory
WorkingDirectory=/opt/rustfs
-# 设置服务的工作目录为 /opt/rustfs，影响相对路径的解析。
+# Set the working directory so relative paths resolve consistently.
-# 定义环境变量配置，用于传递给服务程序。
+# Inline environment variables for authentication.
Environment=RUSTFS_ACCESS_KEY=rustfsadmin
-# 设置访问密钥为 rustfsadmin，用于 RustFS 的认证。
+# Access key used by RustFS authentication.
Environment=RUSTFS_SECRET_KEY=rustfsadmin
-# 设置秘密密钥为 rustfsadmin，与访问密钥配套使用。
+# Secret key that pairs with the access key.
ExecStart=/usr/local/bin/rustfs \
--address 0.0.0.0:9000 \
--volumes /data/rustfs/vol1,/data/rustfs/vol2 \
--console-enable
-# 定义启动命令，运行 /usr/local/bin/rustfs，带参数：
-# --address 0.0.0.0:9000：服务监听所有接口的 9000 端口。
-# --volumes：指定存储卷路径为 /data/rustfs/vol1 和 /data/rustfs/vol2。
-# --console-enable：启用控制台功能。
+# Launch RustFS with common arguments:
+# --address 0.0.0.0:9000 listens on every interface.
+# --volumes mounts /data/rustfs/vol1 and /data/rustfs/vol2.
+# --console-enable turns on the management console.
-# 定义环境变量配置，用于传递给服务程序，推荐使用且简洁
-# rustfs 示例文件 详见: `../config/rustfs-zh.env`
+# Optionally load additional environment variables (see ../config/rustfs-zh.env).
EnvironmentFile=-/etc/default/rustfs
ExecStart=/usr/local/bin/rustfs $RUSTFS_VOLUMES $RUSTFS_OPTS
@@ -53,50 +52,50 @@ StandardError=append:/data/deploy/rust/logs/rustfs-err.log
# resource constraints
LimitNOFILE=1048576
-# 设置文件描述符上限为 1048576，支持高并发连接。
+# Allow up to 1,048,576 file descriptors for high concurrency.
LimitNPROC=32768
-# 设置进程数上限为 32768，限制子进程数量。
+# Cap the number of processes at 32,768.
TasksMax=infinity
-# 允许服务创建无限数量的线程（谨慎使用，可能耗尽资源）。
+# Permit unlimited tasks (use carefully to avoid resource exhaustion).
# restart the policy
Restart=always
-# 服务异常退出时总是重启，提高可用性。
+# Always restart the service on failure to improve availability.
RestartSec=10s
-# 重启前等待 10 秒，避免频繁重启导致资源浪费。
+# Wait 10 seconds between restart attempts.
# graceful exit configuration
TimeoutStartSec=30s
-# 启动超时时间为 30 秒，若超时则认为启动失败。
+# Treat startups that exceed 30 seconds as failures.
TimeoutStopSec=30s
-# 停止超时时间为 30 秒，若超时则强制停止。
+# Force-stop the service if it does not exit within 30 seconds.
# security settings
NoNewPrivileges=true
-# 禁止服务提升权限，增强安全性。
+# Disable privilege escalation.
ProtectSystem=full
-# 保护系统目录（如 /usr、/boot、/etc）为只读，防止服务修改。
+# Mount critical system directories read-only.
ProtectHome=true
-# 保护用户主目录（如 /home、/root），禁止服务访问。
+# Prevent access to user home directories.
PrivateTmp=true
-# 为服务提供私有 /tmp 目录，隔离临时文件。
+# Provide a private /tmp namespace.
PrivateDevices=true
-# 禁止服务访问硬件设备（如 /dev），提升安全性。
+# Deny direct hardware device access.
ProtectClock=true
-# 保护系统时钟，禁止服务修改时间。
+# Block modifications to the system clock.
ProtectKernelTunables=true
-# 保护内核参数（/proc/sys），禁止服务修改。
+# Protect /proc/sys kernel tunables.
ProtectKernelModules=true
-# 禁止服务加载或卸载内核模块。
+# Prevent kernel module load/unload.
ProtectControlGroups=true
-# 保护控制组（cgroups），禁止服务修改。
+# Block cgroup modifications.
RestrictSUIDSGID=true
-# 禁止服务使用 SUID/SGID 文件，提升安全性。
+# Disallow SUID/SGID binaries.
RestrictRealtime=true
-# 禁止服务使用实时调度，防止资源滥用。
+# Disallow real-time scheduling.
ReadWritePaths=/data/rustfs
-# 允许服务对 /data/rustfs 目录读写，限制其他路径访问。
+# Grant read/write access only to /data/rustfs.
[Install]
WantedBy=multi-user.target
-# 服务在多用户模式下自动启动，配合 systemctl enable 使用。
\ No newline at end of file
+# Enable the service in multi-user mode (compatible with `systemctl enable`).
\ No newline at end of file
diff --git a/deploy/build/rustfs.run-zh.md b/deploy/build/rustfs.run-zh.md
index 9d70eaf8..ae4ae56c 100644
--- a/deploy/build/rustfs.run-zh.md
+++ b/deploy/build/rustfs.run-zh.md
@@ -1,89 +1,89 @@
-# RustFS 服务安装配置教程
+# RustFS Service Installation Guide
-## 1. 准备工作
+## 1. Preparation
-### 1.1 创建系统用户
+### 1.1 Create a system user
```bash
-# 创建 rustfs 系统用户和用户组，禁止登录shell
+# Create the rustfs system user and group without shell access
sudo useradd -r -s /sbin/nologin rustfs
```
-### 1.2 创建必要目录
+### 1.2 Create required directories
```bash
-# 创建程序目录
+# Application directory
sudo mkdir -p /opt/rustfs
-# 创建数据目录
+# Data directories
sudo mkdir -p /data/rustfs/{vol1,vol2}
-# 创建配置目录
+# Configuration directory
sudo mkdir -p /etc/rustfs
-# 设置目录权限
+# Assign ownership and permissions
sudo chown -R rustfs:rustfs /opt/rustfs /data/rustfs
sudo chmod 755 /opt/rustfs /data/rustfs
```
-## 2. 安装 RustFS
+## 2. Install RustFS
```bash
-# 复制 RustFS 二进制文件
+# Copy the RustFS binary
sudo cp rustfs /usr/local/bin/
sudo chmod +x /usr/local/bin/rustfs
-# 复制配置文件
+# Copy configuration files
sudo cp obs.yaml /etc/rustfs/
sudo chown -R rustfs:rustfs /etc/rustfs
```
-## 3. 配置 Systemd 服务
+## 3. Configure the systemd service
```bash
-# 复制服务单元文件
+# Install the service unit
sudo cp rustfs.service /etc/systemd/system/
-# 重新加载 systemd 配置
+# Reload systemd units
sudo systemctl daemon-reload
```
-## 4. 服务管理
+## 4. Service management
-### 4.1 启动服务
+### 4.1 Start the service
```bash
sudo systemctl start rustfs
```
-### 4.2 查看服务状态
+### 4.2 Check service status
```bash
sudo systemctl status rustfs
```
-### 4.3 启用开机自启
+### 4.3 Enable auto-start on boot
```bash
sudo systemctl enable rustfs
```
-### 4.4 查看服务日志
+### 4.4 Inspect logs
```bash
-# 查看实时日志
+# Follow live logs
sudo journalctl -u rustfs -f
-# 查看今天的日志
+# View today's logs
sudo journalctl -u rustfs --since today
```
-## 5. 验证安装
+## 5. Validate the installation
```bash
-# 检查服务端口
+# Confirm the service port
ss -tunlp | grep 9000
-# 测试服务可用性
+# Verify availability
curl -I http://localhost:9000
```
diff --git a/docs/PERFORMANCE_TESTING.md b/docs/PERFORMANCE_TESTING.md
index a980cd04..0fff3a51 100644
--- a/docs/PERFORMANCE_TESTING.md
+++ b/docs/PERFORMANCE_TESTING.md
@@ -1,139 +1,141 @@
-# RustFS 性能测试指南
+# RustFS Performance Testing Guide
-本文档提供了对 RustFS 进行性能测试和性能分析的完整方法和工具。
+This document describes the recommended tools and workflows for benchmarking RustFS and analyzing performance bottlenecks.
-## 概览
+## Overview
-RustFS 提供了多种性能测试和分析工具：
+RustFS exposes several complementary tooling options:
-1. **性能分析（Profiling）** - 使用内置的 pprof 接口收集 CPU 性能数据
-2. **负载测试（Load Testing）** - 使用多种客户端工具模拟高并发请求
-3. **监控和分析** - 查看性能指标和识别性能瓶颈
+1. **Profiling** – collect CPU samples through the built-in `pprof` endpoints.
+2. **Load testing** – drive concurrent requests with dedicated client utilities.
+3. **Monitoring and analysis** – inspect collected metrics to locate hotspots.
-## 前置条件
+## Prerequisites
-### 1. 启用性能分析
+### 1. Enable profiling support
-在启动 RustFS 时，需要设置环境变量启用性能分析功能：
+Set the profiling environment variable before launching RustFS:
```bash
export RUSTFS_ENABLE_PROFILING=true
./rustfs
```
-### 2. 安装依赖工具
+### 2. Install required tooling
-确保系统中安装了以下工具：
+Make sure the following dependencies are available:
```bash
-# 基础工具
-curl # HTTP 请求
-jq # JSON 处理 (可选)
+# Base tools
+curl # HTTP requests
+jq # JSON processing (optional)
-# 分析工具
-go # Go pprof 工具 (可选，用于 protobuf 格式)
-python3 # Python 负载测试脚本
+# Analysis tools
+go # Go pprof CLI (optional, required for protobuf output)
+python3 # Python load-testing scripts
-# macOS 用户
+# macOS users
brew install curl jq go python3
-# Ubuntu/Debian 用户
+# Ubuntu/Debian users
sudo apt-get install curl jq golang-go python3
```
-## 性能测试方法
+## Performance Testing Methods
-### 方法 1：使用专业脚本（推荐）
+### Method 1: Use the dedicated profiling script (recommended)
-项目提供了完整的性能分析脚本：
+The repository ships with a helper script for common profiling flows:
```bash
-# 查看脚本帮助
+# Show command help
./scripts/profile_rustfs.sh help
-# 检查性能分析状态
+# Check profiler status
./scripts/profile_rustfs.sh status
-# 收集火焰图（30秒）
+# Capture a 30 second flame graph
./scripts/profile_rustfs.sh flamegraph
-# 收集 protobuf 格式性能数据
+# Download protobuf-formatted samples
./scripts/profile_rustfs.sh protobuf
-# 收集两种格式的性能数据
+# Collect both formats
./scripts/profile_rustfs.sh both
-# 自定义参数
+# Provide custom arguments
./scripts/profile_rustfs.sh -d 60 -u http://192.168.1.100:9000 both
```
-### 方法 2：使用 Python 综合测试
+### Method 2: Run the Python end-to-end tester
-Python 脚本提供了负载测试和性能分析的一体化解决方案：
+A Python utility combines background load generation with profiling:
```bash
-# 运行综合性能分析
+# Launch the integrated test harness
python3 test_load.py
```
-此脚本会：
-1. 启动后台负载测试（多线程 S3 操作）
-2. 并行收集性能分析数据
-3. 生成火焰图用于分析
+The script will:
-### 方法 3：使用简单负载测试
+1. Launch multi-threaded S3 operations as load.
+2. Pull profiling samples in parallel.
+3. Produce a flame graph for investigation.
-对于快速测试，可以使用 bash 脚本：
+### Method 3: Simple shell-based load test
+
+For quick smoke checks, a lightweight bash script is also provided:
```bash
-# 运行简单负载测试
+# Execute a lightweight benchmark
./simple_load_test.sh
```
-## 性能分析输出格式
+## Profiling Output Formats
-### 1. 火焰图（SVG 格式）
+### 1. Flame graph (SVG)
-- **用途**: 可视化 CPU 使用情况
-- **文件**: `rustfs_profile_TIMESTAMP.svg`
-- **查看方式**: 使用浏览器打开 SVG 文件
-- **分析要点**:
- - 宽度表示 CPU 使用时间
- - 高度表示调用栈深度
- - 点击可以放大特定函数
+- **Purpose**: Visualize CPU time distribution.
+- **File name**: `rustfs_profile_TIMESTAMP.svg`
+- **How to view**: Open the SVG in a browser.
+- **Interpretation tips**:
+ - Width reflects CPU time per function.
+ - Height illustrates call-stack depth.
+ - Click to zoom into specific frames.
```bash
-# 在浏览器中打开
+# Example: open the file in a browser
open profiles/rustfs_profile_20240911_143000.svg
```
-### 2. Protobuf 格式
+### 2. Protobuf samples
-- **用途**: 使用 Go pprof 工具进行详细分析
-- **文件**: `rustfs_profile_TIMESTAMP.pb`
-- **分析工具**: `go tool pprof`
+- **Purpose**: Feed data to the `go tool pprof` command.
+- **File name**: `rustfs_profile_TIMESTAMP.pb`
+- **Tooling**: `go tool pprof`
```bash
-# 使用 Go pprof 分析
+# Analyze the protobuf output
go tool pprof profiles/rustfs_profile_20240911_143000.pb
-# pprof 常用命令
-(pprof) top # 显示 CPU 使用率最高的函数
-(pprof) list func # 显示指定函数的源代码
-(pprof) web # 生成 web 界面（需要 graphviz）
-(pprof) png # 生成 PNG 图片
-(pprof) help # 查看所有命令
+# Common pprof commands
+(pprof) top # Show hottest call sites
+(pprof) list func # Display annotated source for a function
+(pprof) web # Launch the web UI (requires graphviz)
+(pprof) png # Render a PNG flame chart
+(pprof) help # List available commands
```
-## API 接口使用
+## API Usage
-### 检查性能分析状态
+### Check profiling status
```bash
curl "http://127.0.0.1:9000/rustfs/admin/debug/pprof/status"
```
-返回示例：
+Sample response:
+
```json
{
"enabled": "true",
@@ -141,186 +143,187 @@ curl "http://127.0.0.1:9000/rustfs/admin/debug/pprof/status"
}
```
-### 收集性能数据
+### Capture profiling data
```bash
-# 收集 30 秒的火焰图
+# Fetch a 30-second flame graph
curl "http://127.0.0.1:9000/rustfs/admin/debug/pprof/profile?seconds=30&format=flamegraph" \
-o profile.svg
-# 收集 protobuf 格式数据
+# Fetch protobuf output
curl "http://127.0.0.1:9000/rustfs/admin/debug/pprof/profile?seconds=30&format=protobuf" \
-o profile.pb
```
-**参数说明**:
-- `seconds`: 收集时长（1-300 秒）
-- `format`: 输出格式（`flamegraph`/`svg` 或 `protobuf`/`pb`）
+**Parameters**
+- `seconds`: Duration between 1 and 300 seconds.
+- `format`: Output format (`flamegraph`/`svg` or `protobuf`/`pb`).
-## 负载测试场景
+## Load Testing Scenarios
-### 1. S3 API 负载测试
+### 1. S3 API workload
-使用 Python 脚本进行完整的 S3 操作负载测试：
+Use the Python harness to exercise a complete S3 workflow:
```python
-# 基本配置
+# Basic configuration
tester = S3LoadTester(
endpoint="http://127.0.0.1:9000",
- access_key="rustfsadmin",
+ access_key="rustfsadmin",
secret_key="rustfsadmin"
)
-# 运行负载测试
-# 4 个线程，每个线程执行 10 次操作
+# Execute the load test
+# Four threads, ten operations each
tester.run_load_test(num_threads=4, operations_per_thread=10)
```
-每次操作包括：
-1. 上传 1MB 对象
-2. 下载对象
-3. 删除对象
+Each iteration performs:
+1. Upload a 1 MB object.
+2. Download the object.
+3. Delete the object.
-### 2. 自定义负载测试
+### 2. Custom load scenarios
```bash
-# 创建测试桶
+# Create a test bucket
curl -X PUT "http://127.0.0.1:9000/test-bucket"
-# 并发上传测试
+# Concurrent uploads
for i in {1..10}; do
echo "test data $i" | curl -X PUT "http://127.0.0.1:9000/test-bucket/object-$i" -d @- &
done
wait
-# 并发下载测试
+# Concurrent downloads
for i in {1..10}; do
curl "http://127.0.0.1:9000/test-bucket/object-$i" > /dev/null &
done
wait
```
-## 性能分析最佳实践
+## Profiling Best Practices
-### 1. 测试环境准备
+### 1. Environment preparation
-- 确保 RustFS 已启用性能分析: `RUSTFS_ENABLE_PROFILING=true`
-- 使用独立的测试环境，避免其他程序干扰
-- 确保有足够的磁盘空间存储分析文件
+- Confirm that `RUSTFS_ENABLE_PROFILING=true` is set.
+- Use an isolated benchmark environment to avoid interference.
+- Reserve disk space for generated profile artifacts.
-### 2. 数据收集建议
+### 2. Data collection tips
-- **预热阶段**: 先运行 5-10 分钟的轻量负载
-- **数据收集**: 在稳定负载下收集 30-60 秒的性能数据
-- **多次采样**: 收集多个样本进行对比分析
+- **Warm-up**: Run a light workload for 5–10 minutes before sampling.
+- **Sampling window**: Capture 30–60 seconds under steady load.
+- **Multiple samples**: Take several runs to compare results.
-### 3. 分析重点
+### 3. Analysis focus areas
-在火焰图中重点关注：
+When inspecting flame graphs, pay attention to:
-1. **宽度最大的函数** - CPU 使用时间最长
-2. **平顶函数** - 可能的性能瓶颈
-3. **深度调用栈** - 可能的递归或复杂逻辑
-4. **意外的系统调用** - I/O 或内存分配问题
+1. **The widest frames** – most CPU time consumed.
+2. **Flat plateaus** – likely bottlenecks.
+3. **Deep call stacks** – recursion or complex logic.
+4. **Unexpected syscalls** – I/O stalls or allocation churn.
-### 4. 常见性能问题
+### 4. Common issues
-- **锁竞争**: 查找 `std::sync` 相关函数
-- **内存分配**: 查找 `alloc` 相关函数
-- **I/O 等待**: 查找文件系统或网络 I/O 函数
-- **序列化开销**: 查找 JSON/XML 解析函数
+- **Lock contention**: Investigate frames under `std::sync`.
+- **Memory allocation**: Search for `alloc`-related frames.
+- **I/O wait**: Review filesystem or network call stacks.
+- **Serialization overhead**: Look for JSON/XML parsing hotspots.
-## 故障排除
+## Troubleshooting
-### 1. 性能分析未启用
+### 1. Profiling disabled
-错误信息：`{"enabled":"false"}`
+Error: `{"enabled":"false"}`
+
+**Fix**:
-解决方案：
```bash
export RUSTFS_ENABLE_PROFILING=true
-# 重启 RustFS
+# Restart RustFS
```
-### 2. 连接被拒绝
+### 2. Connection refused
-错误信息：`Connection refused`
+Error: `Connection refused`
-检查项：
-- RustFS 是否正在运行
-- 端口是否正确（默认 9000）
-- 防火墙设置
+**Checklist**:
+- Confirm RustFS is running.
+- Ensure the port number is correct (default 9000).
+- Verify firewall rules.
-### 3. 分析文件过大
+### 3. Oversized profile output
-如果生成的分析文件过大：
-- 减少收集时间（如 15-30 秒）
-- 降低负载测试的并发度
-- 使用 protobuf 格式而非 SVG
+If artifacts become too large:
+- Shorten the capture window (e.g., 15–30 seconds).
+- Reduce load-test concurrency.
+- Prefer protobuf output instead of SVG.
-## 配置参数
+## Configuration Parameters
-### 环境变量
+### Environment variables
-| 变量 | 默认值 | 描述 |
+| Variable | Default | Description |
|------|--------|------|
-| `RUSTFS_ENABLE_PROFILING` | `false` | 启用性能分析 |
-| `RUSTFS_URL` | `http://127.0.0.1:9000` | RustFS 服务器地址 |
-| `PROFILE_DURATION` | `30` | 性能数据收集时长（秒） |
-| `OUTPUT_DIR` | `./profiles` | 输出文件目录 |
+| `RUSTFS_ENABLE_PROFILING` | `false` | Enable profiling support |
+| `RUSTFS_URL` | `http://127.0.0.1:9000` | RustFS endpoint |
+| `PROFILE_DURATION` | `30` | Profiling duration in seconds |
+| `OUTPUT_DIR` | `./profiles` | Output directory |
-### 脚本参数
+### Script arguments
```bash
./scripts/profile_rustfs.sh [OPTIONS] [COMMAND]
OPTIONS:
-u, --url URL RustFS URL
- -d, --duration SECONDS Profile duration
+ -d, --duration SECONDS Profile duration
-o, --output DIR Output directory
COMMANDS:
- status 检查状态
- flamegraph 收集火焰图
- protobuf 收集 protobuf 数据
- both 收集两种格式（默认）
+ status Check profiler status
+ flamegraph Collect a flame graph
+ protobuf Collect protobuf samples
+ both Collect both formats (default)
```
-## 输出文件位置
+## Output Locations
-- **脚本输出**: `./profiles/` 目录
-- **Python 脚本**: `/tmp/rustfs_profiles/` 目录
-- **文件命名**: `rustfs_profile_TIMESTAMP.{svg|pb}`
+- **Script output**: `./profiles/`
+- **Python script**: `/tmp/rustfs_profiles/`
+- **File naming**: `rustfs_profile_TIMESTAMP.{svg|pb}`
-## 示例工作流程
+## Example Workflow
-1. **启动 RustFS**:
+1. **Launch RustFS**
```bash
RUSTFS_ENABLE_PROFILING=true ./rustfs
```
-2. **验证性能分析可用**:
+2. **Verify profiling availability**
```bash
./scripts/profile_rustfs.sh status
```
-3. **开始负载测试**:
+3. **Start a load test**
```bash
python3 test_load.py &
```
-4. **收集性能数据**:
+4. **Collect samples**
```bash
./scripts/profile_rustfs.sh -d 60 both
```
-5. **分析结果**:
+5. **Inspect the results**
```bash
- # 查看火焰图
+ # Review the flame graph
open profiles/rustfs_profile_*.svg
-
- # 或使用 pprof 分析
+
+ # Or analyze the protobuf output
go tool pprof profiles/rustfs_profile_*.pb
```
-通过这个完整的性能测试流程，你可以系统地分析 RustFS 的性能特征，识别瓶颈，并进行有针对性的优化。
\ No newline at end of file
+Following this workflow helps you understand RustFS performance characteristics, locate bottlenecks, and implement targeted optimizations.
diff --git a/docs/README.md b/docs/README.md
index d9b2decb..142e3182 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,239 +1,239 @@
-# RustFS 文档中心
+# RustFS Documentation Center
-欢迎来到 RustFS 分布式文件系统文档中心！
+Welcome to the RustFS distributed file system documentation center!
-## 📚 文档导航
+## 📚 Documentation Navigation
-### 🔐 KMS (密钥管理服务)
+### 🔐 KMS (Key Management Service)
-RustFS KMS 提供企业级密钥管理和数据加密服务。
+RustFS KMS delivers enterprise-grade key management and data encryption.
-| 文档 | 描述 | 适用场景 |
+| Document | Description | Audience |
|------|------|----------|
-| [KMS 使用指南](./kms/README.md) | 完整的 KMS 使用文档，包含快速开始、配置和部署 | 所有用户必读 |
-| [HTTP API 接口](./kms/http-api.md) | HTTP REST API 接口文档和使用示例 | 管理员和运维 |
-| [编程 API 接口](./kms/api.md) | Rust 库编程接口和代码示例 | 开发者集成 |
-| [配置参考](./kms/configuration.md) | 完整的配置选项和环境变量说明 | 系统管理员 |
-| [故障排除](./kms/troubleshooting.md) | 常见问题诊断和解决方案 | 运维人员 |
-| [安全指南](./kms/security.md) | 安全最佳实践和合规指导 | 安全架构师 |
+| [KMS User Guide](./kms/README.md) | Comprehensive KMS guide with quick start, configuration, and deployment steps | Required reading for all users |
+| [HTTP API Reference](./kms/http-api.md) | HTTP REST API reference with usage examples | Administrators and operators |
+| [Programming API Reference](./kms/api.md) | Rust library APIs and code samples | Developers |
+| [Configuration Reference](./kms/configuration.md) | Complete configuration options and environment variables | System administrators |
+| [Troubleshooting](./kms/troubleshooting.md) | Diagnosis tips and solutions for common issues | Operations engineers |
+| [Security Guide](./kms/security.md) | Security best practices and compliance guidance | Security architects |
-## 🚀 快速开始
+## 🚀 Quick Start
-### 1. KMS 5分钟快速部署
+### 1. Deploy KMS in 5 Minutes
-**生产环境（使用 Vault）**
+**Production (Vault backend)**
```bash
-# 1. 启用 Vault 功能编译
+# 1. Enable the Vault feature flag
cargo build --features vault --release
-# 2. 配置环境变量
+# 2. Configure environment variables
export RUSTFS_VAULT_ADDRESS=https://vault.company.com:8200
export RUSTFS_VAULT_TOKEN=hvs.CAESIJ...
-# 3. 启动服务
+# 3. Launch the service
./target/release/rustfs server
```
-**开发测试（使用本地后端）**
+**Development & Testing (Local backend)**
```bash
-# 1. 编译测试版本
+# 1. Build a release binary
cargo build --release
-# 2. 配置本地存储
+# 2. Configure local storage
export RUSTFS_KMS_BACKEND=Local
export RUSTFS_KMS_LOCAL_KEY_DIR=/tmp/rustfs-keys
-# 3. 启动服务
+# 3. Launch the service
./target/release/rustfs server
```
-### 2. S3 兼容加密
+### 2. S3-Compatible Encryption
```bash
-# 上传加密文件
+# Upload an encrypted object
curl -X PUT https://rustfs.company.com/bucket/sensitive.txt \
-H "x-amz-server-side-encryption: AES256" \
--data-binary @sensitive.txt
-# 自动解密下载
+# Download with automatic decryption
curl https://rustfs.company.com/bucket/sensitive.txt
```
-## 🏗️ 架构概览
+## 🏗️ Architecture Overview
-### KMS 三层安全架构
+### Three-Layer KMS Security Architecture
```
┌─────────────────────────────────────────────────┐
-│ 应用层 │
+│ Application Layer │
│ ┌─────────────┐ ┌─────────────┐ │
-│ │ S3 API │ │ REST API │ │
+│ │ S3 API │ │ REST API │ │
│ └─────────────┘ └─────────────┘ │
├─────────────────────────────────────────────────┤
-│ 加密层 │
-│ ┌─────────────┐ 加密 ┌─────────────────┐ │
-│ │ 对象数据 │ ◄───► │ 数据密钥 (DEK) │ │
-│ └─────────────┘ └─────────────────┘ │
+│ Encryption Layer │
+│ ┌─────────────┐ Encrypt ┌─────────────────┐ │
+│ │ Object Data │ ◄──────► │ Data Key (DEK) │ │
+│ └─────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────┤
-│ 密钥管理层 │
-│ ┌─────────────────┐ 加密 ┌──────────────┐ │
-│ │ 数据密钥 (DEK) │ ◄────│ 主密钥 │ │
-│ └─────────────────┘ │ (Vault/HSM) │ │
-│ └──────────────┘ │
+│ Key Management Layer │
+│ ┌─────────────────┐ Encrypt ┌──────────────┐ │
+│ │ Data Key (DEK) │ ◄───────│ Master Key │ │
+│ └─────────────────┘ │ (Vault/HSM) │ │
+│ └──────────────┘ │
└─────────────────────────────────────────────────┘
```
-### 核心特性
+### Key Features
-- ✅ **多层加密**: Master Key → DEK → Object Data
-- ✅ **高性能**: 1MB 流式加密，支持大文件
-- ✅ **多后端**: Vault (生产) + Local (测试)
-- ✅ **S3 兼容**: 支持标准 SSE-S3/SSE-KMS 头
-- ✅ **企业级**: 审计、监控、合规支持
+- ✅ **Multi-layer encryption**: Master Key → DEK → Object Data
+- ✅ **High performance**: 1 MB streaming encryption with large file support
+- ✅ **Multiple backends**: Vault (production) + Local (testing)
+- ✅ **S3 compatibility**: Supports standard SSE-S3/SSE-KMS headers
+- ✅ **Enterprise-ready**: Auditing, monitoring, and compliance features
-## 📖 学习路径
+## 📖 Learning Paths
-### 👨💻 开发者
+### 👨💻 Developers
-1. 阅读 [编程 API 接口](./kms/api.md) 了解 Rust 库使用
-2. 查看代码示例学习集成方法
-3. 参考 [故障排除](./kms/troubleshooting.md) 解决问题
+1. Read the [Programming API Reference](./kms/api.md) to learn the Rust library
+2. Review the sample code to understand integration patterns
+3. Consult [Troubleshooting](./kms/troubleshooting.md) when issues occur
-### 👨💼 系统管理员
+### 👨💼 System Administrators
-1. 从 [KMS 使用指南](./kms/README.md) 开始
-2. 学习 [HTTP API 接口](./kms/http-api.md) 进行管理
-3. 详细阅读 [配置参考](./kms/configuration.md)
-4. 设置监控和日志
+1. Start with the [KMS User Guide](./kms/README.md)
+2. Learn the [HTTP API Reference](./kms/http-api.md) for management tasks
+3. Study the [Configuration Reference](./kms/configuration.md) in depth
+4. Configure monitoring and logging
-### 👨🔧 运维工程师
+### 👨🔧 Operations Engineers
-1. 熟悉 [HTTP API 接口](./kms/http-api.md) 进行日常管理
-2. 掌握 [故障排除](./kms/troubleshooting.md) 技能
-3. 了解 [安全指南](./kms/security.md) 要求
-4. 建立运维流程
+1. Become familiar with the [HTTP API Reference](./kms/http-api.md) for day-to-day work
+2. Master the [Troubleshooting](./kms/troubleshooting.md) procedures
+3. Understand the requirements in the [Security Guide](./kms/security.md)
+4. Establish operational runbooks
-### 🔒 安全架构师
+### 🔒 Security Architects
-1. 深入学习 [安全指南](./kms/security.md)
-2. 评估威胁模型和风险
-3. 制定安全策略
+1. Dive into the [Security Guide](./kms/security.md)
+2. Evaluate threat models and risk posture
+3. Define security policies
-## 🤝 贡献指南
+## 🤝 Contribution Guide
-我们欢迎社区贡献！
+We welcome community contributions!
-### 文档贡献
+### Documentation Contributions
```bash
-# 1. Fork 项目
+# 1. Fork the repository
git clone https://github.com/your-username/rustfs.git
-# 2. 创建文档分支
+# 2. Create a documentation branch
git checkout -b docs/improve-kms-guide
-# 3. 编辑文档
-# 编辑 docs/kms/ 下的 Markdown 文件
+# 3. Edit the documentation
+# Update Markdown files under docs/kms/
-# 4. 提交更改
+# 4. Commit the changes
git add docs/
git commit -m "docs: improve KMS configuration examples"
-# 5. 创建 Pull Request
+# 5. Open a Pull Request
gh pr create --title "Improve KMS documentation"
```
-### 文档规范
+### Documentation Guidelines
-- 使用清晰的标题和结构
-- 提供可运行的代码示例
-- 包含适当的警告和提示
-- 支持多种使用场景
-- 保持内容最新
+- Use clear headings and structure
+- Provide runnable code examples
+- Include warnings and tips where appropriate
+- Support multiple usage scenarios
+- Keep the content up to date
-## 📞 支持与反馈
+## 📞 Support & Feedback
-### 获取帮助
+### Getting Help
- **GitHub Issues**: https://github.com/rustfs/rustfs/issues
-- **讨论区**: https://github.com/rustfs/rustfs/discussions
-- **文档问题**: 在相关文档页面创建 Issue
-- **安全问题**: security@rustfs.com
+- **Discussion Forum**: https://github.com/rustfs/rustfs/discussions
+- **Documentation Questions**: Open an issue on the relevant document
+- **Security Concerns**: security@rustfs.com
-### 问题报告模板
+### Issue Reporting Template
-报告问题时请提供：
+When reporting a problem, please provide:
```markdown
-**环境信息**
-- RustFS 版本: v1.0.0
-- 操作系统: Ubuntu 20.04
-- Rust 版本: 1.75.0
+**Environment**
+- RustFS version: v1.0.0
+- Operating system: Ubuntu 20.04
+- Rust version: 1.75.0
-**问题描述**
-简要描述遇到的问题...
+**Issue Description**
+Summarize the problem you encountered...
-**重现步骤**
-1. 步骤一
-2. 步骤二
-3. 步骤三
+**Reproduction Steps**
+1. Step one
+2. Step two
+3. Step three
-**期望行为**
-描述期望的正确行为...
+**Expected Behavior**
+Describe what you expected to happen...
-**实际行为**
-描述实际发生的情况...
+**Actual Behavior**
+Describe what actually happened...
-**相关日志**
+**Relevant Logs**
```bash
-# 粘贴相关日志
+# Paste relevant log excerpts
```
-**附加信息**
-其他可能有用的信息...
+**Additional Information**
+Any other details that may help...
```
-## 📈 版本历史
+## 📈 Release History
-| 版本 | 发布日期 | 主要特性 |
+| Version | Release Date | Highlights |
|------|----------|----------|
-| v1.0.0 | 2024-01-15 | 🎉 首个正式版本，完整 KMS 功能 |
-| v0.9.0 | 2024-01-01 | 🔐 KMS 系统重构，性能优化 |
-| v0.8.0 | 2023-12-15 | ⚡ 流式加密，1MB 块大小优化 |
+| v1.0.0 | 2024-01-15 | 🎉 First official release with full KMS functionality |
+| v0.9.0 | 2024-01-01 | 🔐 KMS system refactor with performance optimizations |
+| v0.8.0 | 2023-12-15 | ⚡ Streaming encryption with 1 MB block size tuning |
-## 🗺️ 开发路线图
+## 🗺️ Roadmap
-### 即将发布 (v1.1.0)
+### Coming Soon (v1.1.0)
-- [ ] 密钥自动轮转
-- [ ] HSM 集成支持
-- [ ] Web UI 管理界面
-- [ ] 更多合规性支持 (SOC2, HIPAA)
+- [ ] Automatic key rotation
+- [ ] HSM integration support
+- [ ] Web UI management console
+- [ ] Additional compliance support (SOC2, HIPAA)
-### 长期规划
+### Long-Term Plans
-- [ ] 多租户密钥隔离
-- [ ] 密钥导入/导出工具
-- [ ] 性能基准测试套件
+- [ ] Multi-tenant key isolation
+- [ ] Key import/export tooling
+- [ ] Performance benchmarking suite
- [ ] Kubernetes Operator
-## 📋 文档反馈
+## 📋 Documentation Feedback
-帮助我们改进文档！
+Help us improve the documentation!
-**这些文档对您有帮助吗？**
-- 👍 很有帮助
-- 👌 基本满意
-- 👎 需要改进
+**Was this documentation helpful?**
+- 👍 Very helpful
+- 👌 Mostly satisfied
+- 👎 Needs improvement
-**改进建议**：
-请在 GitHub Issues 中提出具体的改进建议。
+**Suggestions for improvement:**
+Share specific ideas via GitHub Issues.
---
-**最后更新**: 2024-01-15
-**文档版本**: v1.0.0
+**Last Updated**: 2024-01-15
+**Documentation Version**: v1.0.0
-*感谢使用 RustFS！我们致力于为您提供最好的分布式文件系统解决方案。*
\ No newline at end of file
+*Thank you for using RustFS! We are committed to delivering the best distributed file system solution.*
diff --git a/docs/kms/frontend-api-guide-zh.md b/docs/kms/frontend-api-guide-zh.md
index 5106c611..2b919ac0 100644
--- a/docs/kms/frontend-api-guide-zh.md
+++ b/docs/kms/frontend-api-guide-zh.md
@@ -1,149 +1,145 @@
-# RustFS KMS 前端对接指南
+# RustFS KMS Frontend Integration Guide
-本文档专为前端开发者编写，提供了与 RustFS 密钥管理系统（KMS）交互的完整 API 规范。
+This document targets frontend engineers who need to integrate with the RustFS Key Management Service (KMS). It provides a complete API reference, usage notes, and example implementations.
-## 📋 目录
+## 📋 Contents
-1. [快速开始](#快速开始)
-2. [认证和权限](#认证和权限)
-3. [完整接口列表](#完整接口列表)
-4. [服务管理API](#服务管理api)
-5. [密钥管理API](#密钥管理api)
-6. [数据加密API](#数据加密api)
-7. [Bucket加密配置API](#bucket加密配置api)
-8. [监控和缓存API](#监控和缓存api)
-9. [通用错误码](#通用错误码)
-10. [数据类型定义](#数据类型定义)
-11. [实现示例](#实现示例)
+1. [Quick Start](#quick-start)
+2. [Authentication & Permissions](#authentication--permissions)
+3. [API Catalog](#api-catalog)
+4. [Service Management APIs](#service-management-apis)
+5. [Key Management APIs](#key-management-apis)
+6. [Data Encryption APIs](#data-encryption-apis)
+7. [Bucket Encryption Configuration APIs](#bucket-encryption-configuration-apis)
+8. [Monitoring & Cache APIs](#monitoring--cache-apis)
+9. [Common Error Codes](#common-error-codes)
+10. [Data Types](#data-types)
+11. [Implementation Examples](#implementation-examples)
-## 🚀 快速开始
+## Quick Start
-### API 基础信息
+### Base configuration
-| 配置项 | 值 |
-|--------|-----|
-| **基础URL** | `http://localhost:9000/rustfs/admin/v3` (本地开发) |
-| **生产URL** | `https://your-rustfs-domain.com/rustfs/admin/v3` |
-| **请求格式** | `application/json` |
-| **响应格式** | `application/json` |
-| **认证方式** | AWS SigV4 签名 |
-| **字符编码** | UTF-8 |
+| Setting | Value |
+|---------|-------|
+| **Base URL** | `http://localhost:9000/rustfs/admin/v3` (local development) |
+| **Production URL** | `https://your-rustfs-domain.com/rustfs/admin/v3` |
+| **Request format** | `application/json` |
+| **Response format** | `application/json` |
+| **Authentication** | AWS Signature Version 4 |
+| **Encoding** | UTF-8 |
-### 通用请求头
+### Common request headers
-| 头部字段 | 必需 | 值 |
-|----------|------|-----|
+| Header | Required | Value |
+|--------|----------|-------|
| `Content-Type` | ✅ | `application/json` |
| `Authorization` | ✅ | `AWS4-HMAC-SHA256 Credential=...` |
-| `X-Amz-Date` | ✅ | ISO8601 格式时间戳 |
+| `X-Amz-Date` | ✅ | ISO 8601 timestamp |
-## 🔐 认证和权限
+## Authentication & Permissions
-### 权限要求
+### Required IAM permissions
-调用 KMS API 需要账户具有以下权限：
-- `ServerInfoAdminAction` - 管理员操作权限
+Clients must have `ServerInfoAdminAction` to invoke KMS APIs.
-### AWS SigV4 签名
+### AWS SigV4 signing
-所有请求必须使用 AWS Signature Version 4 进行签名认证。
+All requests must be signed with SigV4.
-**签名参数**：
-- **Access Key ID**: 账户的访问密钥ID
-- **Secret Access Key**: 账户的私密访问密钥
-- **Region**: `us-east-1` (固定值)
-- **Service**: `execute-api`
+- **Access Key ID** – account access key
+- **Secret Access Key** – corresponding secret key
+- **Region** – `us-east-1`
+- **Service** – `execute-api`
-## 📋 完整接口列表
+## API Catalog
-### 服务管理接口
+### Service management
-| 方法 | 接口路径 | 描述 | 状态 |
-|------|----------|------|------|
-| `POST` | `/kms/configure` | 配置 KMS 服务 | ✅ 可用 |
-| `POST` | `/kms/start` | 启动 KMS 服务 | ✅ 可用 |
-| `POST` | `/kms/stop` | 停止 KMS 服务 | ✅ 可用 |
-| `GET` | `/kms/service-status` | 获取 KMS 服务状态 | ✅ 可用 |
-| `POST` | `/kms/reconfigure` | 重新配置 KMS 服务 | ✅ 可用 |
+| Method | Path | Description | Status |
+|--------|------|-------------|--------|
+| `POST` | `/kms/configure` | Configure the KMS service | ✅ Available |
+| `POST` | `/kms/start` | Start the service | ✅ Available |
+| `POST` | `/kms/stop` | Stop the service | ✅ Available |
+| `GET` | `/kms/service-status` | Retrieve service status | ✅ Available |
+| `POST` | `/kms/reconfigure` | Reconfigure and restart | ✅ Available |
-### 密钥管理接口
+### Key management
-| 方法 | 接口路径 | 描述 | 状态 |
-|------|----------|------|------|
-| `POST` | `/kms/keys` | 创建主密钥 | ✅ 可用 |
-| `GET` | `/kms/keys` | 列出密钥 | ✅ 可用 |
-| `GET` | `/kms/keys/{key_id}` | 获取密钥详情 | ✅ 可用 |
-| `DELETE` | `/kms/keys/delete` | 计划删除密钥 | ✅ 可用 |
-| `POST` | `/kms/keys/cancel-deletion` | 取消密钥删除 | ✅ 可用 |
+| Method | Path | Description | Status |
+|--------|------|-------------|--------|
+| `POST` | `/kms/keys` | Create a master key | ✅ Available |
+| `GET` | `/kms/keys` | List keys | ✅ Available |
+| `GET` | `/kms/keys/{key_id}` | Get key metadata | ✅ Available |
+| `DELETE` | `/kms/keys/delete` | Schedule key deletion | ✅ Available |
+| `POST` | `/kms/keys/cancel-deletion` | Cancel key deletion | ✅ Available |
-### 数据加密接口
+### Data encryption
-| 方法 | 接口路径 | 描述 | 状态 |
-|------|----------|------|------|
-| `POST` | `/kms/generate-data-key` | 生成数据密钥 | ✅ 可用 |
-| `POST` | `/kms/decrypt` | 解密数据密钥 | ⚠️ **未实现** |
+| Method | Path | Description | Status |
+|--------|------|-------------|--------|
+| `POST` | `/kms/generate-data-key` | Generate a data key | ✅ Available |
+| `POST` | `/kms/decrypt` | Decrypt a data key | ⚠️ Not implemented |
-### Bucket加密配置接口
+### Bucket encryption configuration
-| 方法 | 接口路径 | 描述 | 状态 |
-|------|----------|------|------|
-| `GET` | `/api/v1/buckets` | 列出所有buckets | ✅ 可用 |
-| `GET` | `/api/v1/bucket-encryption/{bucket}` | 获取bucket加密配置 | ✅ 可用 |
-| `PUT` | `/api/v1/bucket-encryption/{bucket}` | 设置bucket加密配置 | ✅ 可用 |
-| `DELETE` | `/api/v1/bucket-encryption/{bucket}` | 删除bucket加密配置 | ✅ 可用 |
+| Method | Path | Description | Status |
+|--------|------|-------------|--------|
+| `GET` | `/api/v1/buckets` | List buckets | ✅ Available |
+| `GET` | `/api/v1/bucket-encryption/{bucket}` | Get default encryption | ✅ Available |
+| `PUT` | `/api/v1/bucket-encryption/{bucket}` | Set default encryption | ✅ Available |
+| `DELETE` | `/api/v1/bucket-encryption/{bucket}` | Remove default encryption | ✅ Available |
-### 监控和缓存接口
+### Monitoring & cache
-| 方法 | 接口路径 | 描述 | 状态 |
-|------|----------|------|------|
-| `GET` | `/kms/config` | 获取 KMS 配置 | ✅ 可用 |
-| `POST` | `/kms/clear-cache` | 清除 KMS 缓存 | ✅ 可用 |
+| Method | Path | Description | Status |
+|--------|------|-------------|--------|
+| `GET` | `/kms/config` | Retrieve KMS configuration | ✅ Available |
+| `POST` | `/kms/clear-cache` | Clear the KMS cache | ✅ Available |
-### 兼容性接口（旧版本）
+### Legacy compatibility endpoints
-| 方法 | 接口路径 | 描述 | 状态 |
-|------|----------|------|------|
-| `POST` | `/kms/create-key` | 创建密钥（旧版） | ✅ 可用 |
-| `GET` | `/kms/describe-key` | 获取密钥详情（旧版） | ✅ 可用 |
-| `GET` | `/kms/list-keys` | 列出密钥（旧版） | ✅ 可用 |
-| `GET` | `/kms/status` | 获取 KMS 状态（旧版） | ✅ 可用 |
+| Method | Path | Description | Status |
+|--------|------|-------------|--------|
+| `POST` | `/kms/create-key` | Create key (legacy) | ✅ Available |
+| `GET` | `/kms/describe-key` | Describe key (legacy) | ✅ Available |
+| `GET` | `/kms/list-keys` | List keys (legacy) | ✅ Available |
+| `GET` | `/kms/status` | KMS status (legacy) | ✅ Available |
-**重要说明**：
-- ✅ **可用**：接口已实现且可正常使用
-- ⚠️ **未实现**：接口规范已定义但后端未实现，需要联系后端开发团队
-- 建议优先使用新版接口，旧版接口主要用于向后兼容
+> ✅ **Available** – implemented and usable.
+> ⚠️ **Not implemented** – API shape defined but backend missing.
+> Prefer the new endpoints; legacy routes exist for backwards compatibility.
-## 🔧 服务管理API
+## Service Management APIs
-### 1. 配置 KMS 服务
+### 1. Configure KMS
-**接口**: `POST /kms/configure`
+`POST /kms/configure`
-**请求参数**:
+Parameters:
-| 参数名 | 类型 | 必需 | 说明 |
-|--------|------|------|------|
-| `backend_type` | string | ✅ | 后端类型：`"local"` 或 `"vault"` |
-| `key_directory` | string | 条件 | Local后端：密钥存储目录路径 |
-| `default_key_id` | string | ✅ | 默认主密钥ID |
-| `enable_cache` | boolean | ❌ | 是否启用缓存，默认 `true` |
-| `cache_ttl_seconds` | integer | ❌ | 缓存TTL秒数，默认 `600` |
-| `timeout_seconds` | integer | ❌ | 操作超时秒数，默认 `30` |
-| `retry_attempts` | integer | ❌ | 重试次数，默认 `3` |
-| `address` | string | 条件 | Vault后端：Vault服务器地址 |
-| `auth_method` | object | 条件 | Vault后端：认证方法配置 |
-| `mount_path` | string | 条件 | Vault后端：Transit挂载路径 |
-| `kv_mount` | string | 条件 | Vault后端：KV存储挂载路径 |
-| `key_path_prefix` | string | 条件 | Vault后端：密钥路径前缀 |
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `backend_type` | string | ✅ | `"local"` or `"vault"` |
+| `key_directory` | string | Cond. | Local backend key directory |
+| `default_key_id` | string | ✅ | Default master key ID |
+| `enable_cache` | boolean | ❌ | Toggle cache (default `true`) |
+| `cache_ttl_seconds` | integer | ❌ | Cache TTL (default `600`) |
+| `timeout_seconds` | integer | ❌ | Operation timeout (default `30`) |
+| `retry_attempts` | integer | ❌ | Retry attempts (default `3`) |
+| `address` | string | Cond. | Vault server address |
+| `auth_method` | object | Cond. | Vault auth config |
+| `mount_path` | string | Cond. | Vault transit mount path |
+| `kv_mount` | string | Cond. | Vault KV mount |
+| `key_path_prefix` | string | Cond. | Vault key prefix |
-**Vault auth_method 对象**:
+Vault `auth_method` fields:
-| 参数名 | 类型 | 必需 | 说明 |
-|--------|------|------|------|
-| `token` | string | ✅ | Vault访问令牌 |
-
-**响应格式**:
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `token` | string | ✅ | Vault token |
+Response
```json
{
"success": boolean,
@@ -152,111 +148,27 @@
}
```
-**响应字段说明**:
+### 2. Start KMS
-| 字段名 | 类型 | 说明 |
-|--------|------|------|
-| `success` | boolean | 配置是否成功 |
-| `message` | string | 配置结果描述信息 |
-| `config_id` | string | 配置ID（如果成功） |
+`POST /kms/start`
-**调用示例**:
+Response fields: `success`, `message`, `status` (`Running`, `Stopped`, `Error`).
-```javascript
-// 配置本地 KMS 后端
-const localConfig = {
- backend_type: "local",
- key_directory: "/var/lib/rustfs/kms/keys",
- default_key_id: "default-master-key",
- enable_cache: true,
- cache_ttl_seconds: 600
-};
+### 3. Stop KMS
-const response = await callKMSAPI('POST', '/kms/configure', localConfig);
-// 响应: { "success": true, "message": "KMS configured successfully", "config_id": "config-123" }
+`POST /kms/stop`
-// 配置 Vault KMS 后端
-const vaultConfig = {
- backend_type: "vault",
- address: "https://vault.example.com:8200",
- auth_method: {
- token: "s.your-vault-token"
- },
- mount_path: "transit",
- kv_mount: "secret",
- key_path_prefix: "rustfs/kms/keys",
- default_key_id: "rustfs-master"
-};
+Same response structure as `/kms/start`.
-const vaultResponse = await callKMSAPI('POST', '/kms/configure', vaultConfig);
-```
+### 4. Service status
-### 2. 启动 KMS 服务
-
-**接口**: `POST /kms/start`
-
-**请求参数**: 无
-
-**响应格式**:
+`GET /kms/service-status`
+Response
```json
{
- "success": boolean,
- "message": string,
- "status": string
-}
-```
-
-**响应字段说明**:
-
-| 字段名 | 类型 | 可能值 | 说明 |
-|--------|------|--------|------|
-| `success` | boolean | `true`, `false` | 启动是否成功 |
-| `message` | string | - | 启动结果描述信息 |
-| `status` | string | `"Running"`, `"Stopped"`, `"Error"` | 服务当前状态 |
-
-### 3. 停止 KMS 服务
-
-**接口**: `POST /kms/stop`
-
-**请求参数**: 无
-
-**响应格式**:
-
-```json
-{
- "success": boolean,
- "message": string,
- "status": string
-}
-```
-
-**响应字段说明**: 同启动接口
-
-**调用示例**:
-
-```javascript
-// 启动 KMS 服务
-const startResponse = await callKMSAPI('POST', '/kms/start');
-// 响应: { "success": true, "message": "KMS service started successfully", "status": "Running" }
-
-// 停止 KMS 服务
-const stopResponse = await callKMSAPI('POST', '/kms/stop');
-// 响应: { "success": true, "message": "KMS service stopped successfully", "status": "Stopped" }
-```
-
-### 4. 获取 KMS 服务状态
-
-**接口**: `GET /kms/service-status`
-
-**请求参数**: 无
-
-**响应格式**:
-
-```json
-{
- "status": string,
- "backend_type": string,
+ "status": "Running" | "Stopped" | "NotConfigured" | "Error",
+ "backend_type": "local" | "vault",
"healthy": boolean,
"config_summary": {
"backend_type": string,
@@ -268,1010 +180,115 @@ const stopResponse = await callKMSAPI('POST', '/kms/stop');
}
```
-**响应字段说明**:
-
-| 字段名 | 类型 | 可能值 | 说明 |
-|--------|------|--------|------|
-| `status` | string | `"Running"`, `"Stopped"`, `"NotConfigured"`, `"Error"` | 服务状态 |
-| `backend_type` | string | `"local"`, `"vault"` | 后端类型 |
-| `healthy` | boolean | `true`, `false` | 服务健康状态 |
-| `config_summary` | object | - | 配置摘要信息 |
-
-**调用示例**:
-
-```javascript
-// 获取 KMS 服务状态
-const status = await callKMSAPI('GET', '/kms/service-status');
-console.log('KMS状态:', status);
-
-/* 响应示例:
-{
- "status": "Running",
- "backend_type": "vault",
- "healthy": true,
- "config_summary": {
- "backend_type": "vault",
- "default_key_id": "rustfs-master",
- "timeout_seconds": 30,
- "retry_attempts": 3,
- "enable_cache": true
- }
-}
-*/
-```
-
-### 5. 重新配置 KMS 服务
-
-**接口**: `POST /kms/reconfigure`
-
-**请求参数**: 同配置接口的参数
-
-**响应格式**:
-
-```json
-{
- "success": boolean,
- "message": string,
- "status": string
-}
-```
-
-**调用示例**:
-
-```javascript
-// 重新配置 KMS 服务（会停止当前服务并重新启动）
-const newConfig = {
- backend_type: "vault",
- address: "https://new-vault.example.com:8200",
- auth_method: {
- token: "s.new-vault-token"
- },
- mount_path: "transit",
- kv_mount: "secret",
- key_path_prefix: "rustfs/kms/keys",
- default_key_id: "new-master-key"
-};
-
-const reconfigureResponse = await callKMSAPI('POST', '/kms/reconfigure', newConfig);
-// 响应: { "success": true, "message": "KMS reconfigured and restarted successfully", "status": "Running" }
-```
-
-## 🔑 密钥管理API
-
-### 1. 创建主密钥
-
-**接口**: `POST /kms/keys`
-
-**请求参数**:
-
-| 参数名 | 类型 | 必需 | 说明 |
-|--------|------|------|------|
-| `KeyUsage` | string | ✅ | 密钥用途，固定值：`"ENCRYPT_DECRYPT"` |
-| `Description` | string | ❌ | 密钥描述，最长256字符 |
-| `Tags` | object | ❌ | 密钥标签，键值对格式 |
-
-**Tags 对象**: 任意键值对，值必须为字符串类型
-
-**响应格式**:
-
-```json
-{
- "key_id": string,
- "key_metadata": {
- "key_id": string,
- "description": string,
- "enabled": boolean,
- "key_usage": string,
- "creation_date": string,
- "rotation_enabled": boolean,
- "deletion_date": string?
- }
-}
-```
-
-**响应字段说明**:
-
-| 字段名 | 类型 | 说明 |
-|--------|------|------|
-| `key_id` | string | 生成的密钥唯一标识符（UUID格式） |
-| `key_metadata.key_id` | string | 密钥ID（与外层相同） |
-| `key_metadata.description` | string | 密钥描述 |
-| `key_metadata.enabled` | boolean | 密钥是否启用 |
-| `key_metadata.key_usage` | string | 密钥用途 |
-| `key_metadata.creation_date` | string | 创建时间（ISO8601格式） |
-| `key_metadata.rotation_enabled` | boolean | 是否启用轮换 |
-| `key_metadata.deletion_date` | string | 删除时间（如果已计划删除） |
-
-**调用示例**:
-
-```javascript
-// 创建主密钥
-const keyRequest = {
- KeyUsage: "ENCRYPT_DECRYPT",
- Description: "前端应用主密钥",
- Tags: {
- owner: "frontend-team",
- environment: "production",
- project: "user-data-encryption"
- }
-};
-
-const newKey = await callKMSAPI('POST', '/kms/keys', keyRequest);
-console.log('创建的密钥ID:', newKey.key_id);
-
-/* 响应示例:
-{
- "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
- "key_metadata": {
- "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
- "description": "前端应用主密钥",
- "enabled": true,
- "key_usage": "ENCRYPT_DECRYPT",
- "creation_date": "2024-09-19T07:10:42.012345Z",
- "rotation_enabled": false
- }
-}
-*/
-```
-
-### 2. 获取密钥详情
-
-**接口**: `GET /kms/keys/{key_id}`
-
-**路径参数**:
-
-| 参数名 | 类型 | 必需 | 说明 |
-|--------|------|------|------|
-| `key_id` | string | ✅ | 密钥ID（UUID格式） |
-
-**响应格式**:
-
-```json
-{
- "key_metadata": {
- "key_id": string,
- "description": string,
- "enabled": boolean,
- "key_usage": string,
- "creation_date": string,
- "rotation_enabled": boolean,
- "deletion_date": string?
- }
-}
-```
-
-**响应字段说明**: 同创建接口的 key_metadata 字段
-
-**调用示例**:
-
-```javascript
-// 获取密钥详情
-const keyId = "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85";
-const keyDetails = await callKMSAPI('GET', `/kms/keys/${keyId}`);
-console.log('密钥详情:', keyDetails.key_metadata);
-
-/* 响应示例:
-{
- "key_metadata": {
- "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
- "description": "前端应用主密钥",
- "enabled": true,
- "key_usage": "ENCRYPT_DECRYPT",
- "creation_date": "2024-09-19T07:10:42.012345Z",
- "rotation_enabled": false,
- "deletion_date": null
- }
-}
-*/
-```
-
-### 3. 列出密钥
-
-**接口**: `GET /kms/keys`
-
-**查询参数**:
-
-| 参数名 | 类型 | 必需 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| `limit` | integer | ❌ | `50` | 每页返回的密钥数量，最大1000 |
-| `marker` | string | ❌ | - | 分页标记，用于获取下一页 |
-
-**响应格式**:
-
-```json
-{
- "keys": [
- {
- "key_id": string,
- "description": string
- }
- ],
- "truncated": boolean,
- "next_marker": string?
-}
-```
-
-**响应字段说明**:
-
-| 字段名 | 类型 | 说明 |
-|--------|------|------|
-| `keys` | array | 密钥列表 |
-| `keys[].key_id` | string | 密钥ID |
-| `keys[].description` | string | 密钥描述 |
-| `truncated` | boolean | 是否还有更多数据 |
-| `next_marker` | string | 下一页的分页标记 |
-
-**调用示例**:
-
-```javascript
-// 列出所有密钥（分页）
-let allKeys = [];
-let marker = null;
-
-do {
- const params = new URLSearchParams({ limit: '50' });
- if (marker) params.append('marker', marker);
-
- const keysList = await callKMSAPI('GET', `/kms/keys?${params}`);
- allKeys.push(...keysList.keys);
- marker = keysList.next_marker;
-} while (marker);
-
-console.log('所有密钥:', allKeys);
-
-/* 响应示例:
-{
- "keys": [
- { "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85", "description": "前端应用主密钥" },
- { "key_id": "bb2cd4f1-3e4d-4a5b-b6c7-8d9e0f1a2b3c", "description": "用户数据密钥" }
- ],
- "truncated": false,
- "next_marker": null
-}
-*/
-```
-
-### 4. 计划删除密钥
-
-**接口**: `DELETE /kms/keys/delete`
-
-**请求参数**:
-
-| 参数名 | 类型 | 必需 | 说明 |
-|--------|------|------|------|
-| `key_id` | string | ✅ | 要删除的密钥ID |
-| `pending_window_in_days` | integer | ❌ | 待删除天数，范围 7-30，默认 7 |
-
-**响应格式**:
-
-```json
-{
- "key_id": string,
- "deletion_date": string,
- "pending_window_in_days": integer
-}
-```
-
-**响应字段说明**:
-
-| 字段名 | 类型 | 说明 |
-|--------|------|------|
-| `key_id` | string | 密钥ID |
-| `deletion_date` | string | 计划删除时间（ISO8601格式） |
-| `pending_window_in_days` | integer | 待删除天数 |
-
-**调用示例**:
-
-```javascript
-// 计划删除密钥（7天后删除）
-const deleteRequest = {
- key_id: "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
- pending_window_in_days: 7
-};
-
-const deleteResponse = await callKMSAPI('DELETE', '/kms/keys/delete', deleteRequest);
-console.log('密钥已计划删除:', deleteResponse);
-
-/* 响应示例:
-{
- "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
- "deletion_date": "2024-09-26T07:10:42.012345Z",
- "pending_window_in_days": 7
-}
-*/
-```
-
-### 5. 取消密钥删除
-
-**接口**: `POST /kms/keys/cancel-deletion`
-
-**请求参数**:
-
-| 参数名 | 类型 | 必需 | 说明 |
-|--------|------|------|------|
-| `key_id` | string | ✅ | 要取消删除的密钥ID |
-
-**响应格式**:
-
-```json
-{
- "key_id": string,
- "key_metadata": {
- "key_id": string,
- "description": string,
- "enabled": boolean,
- "key_usage": string,
- "creation_date": string,
- "rotation_enabled": boolean,
- "deletion_date": null
- }
-}
-```
-
-**响应字段说明**: 同创建接口，注意 `deletion_date` 将为 `null`
-
-**调用示例**:
-
-```javascript
-// 取消密钥删除
-const cancelRequest = {
- key_id: "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85"
-};
-
-const cancelResponse = await callKMSAPI('POST', '/kms/keys/cancel-deletion', cancelRequest);
-console.log('密钥删除已取消:', cancelResponse);
-
-/* 响应示例:
-{
- "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
- "key_metadata": {
- "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
- "description": "前端应用主密钥",
- "enabled": true,
- "key_usage": "ENCRYPT_DECRYPT",
- "creation_date": "2024-09-19T07:10:42.012345Z",
- "rotation_enabled": false,
- "deletion_date": null
- }
-}
-*/
-```
-
-## 🔒 数据加密API
-
-### 1. 生成数据密钥
-
-**接口**: `POST /kms/generate-data-key`
-
-**请求参数**:
-
-| 参数名 | 类型 | 必需 | 说明 |
-|--------|------|------|------|
-| `key_id` | string | ✅ | 主密钥ID（UUID格式） |
-| `key_spec` | string | ❌ | 数据密钥规格，默认 `"AES_256"` |
-| `encryption_context` | object | ❌ | 加密上下文，键值对格式 |
-
-**key_spec 可能值**:
-- `"AES_256"` - 256位AES密钥
-- `"AES_128"` - 128位AES密钥
-
-**encryption_context 对象**: 任意键值对，用于加密上下文，键和值都必须是字符串
-
-**响应格式**:
-
-```json
-{
- "key_id": string,
- "plaintext_key": string,
- "ciphertext_blob": string
-}
-```
-
-**响应字段说明**:
-
-| 字段名 | 类型 | 说明 |
-|--------|------|------|
-| `key_id` | string | 主密钥ID |
-| `plaintext_key` | string | 原始数据密钥（Base64编码） |
-| `ciphertext_blob` | string | 加密后的数据密钥（Base64编码） |
-
-**调用示例**:
-
-```javascript
-// 生成数据密钥用于文件加密
-const dataKeyRequest = {
- key_id: "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
- key_spec: "AES_256",
- encryption_context: {
- bucket: "user-uploads",
- object_key: "documents/report.pdf",
- user_id: "user123",
- department: "finance"
- }
-};
+### 5. Reconfigure
-const dataKey = await callKMSAPI('POST', '/kms/generate-data-key', dataKeyRequest);
-console.log('生成的数据密钥:', dataKey);
+`POST /kms/reconfigure`
-// 立即使用原始密钥进行数据加密
-const encryptedData = await encryptFileWithKey(fileData, dataKey.plaintext_key);
+Accepts the same payload as `/kms/configure` and restarts the service.
-// 安全地清理内存中的原始密钥
-dataKey.plaintext_key = null;
+## Key Management APIs
-// 保存加密后的密钥用于后续解密
-localStorage.setItem('encrypted_key', dataKey.ciphertext_blob);
+### 1. Create key
-/* 响应示例:
-{
- "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
- "plaintext_key": "sQW6qt0yS7CqD6c8hY7GZg==",
- "ciphertext_blob": "gAAAAABlLK4xQ8..."
-}
-*/
-```
+`POST /kms/keys`
-### 2. 解密数据密钥
+Parameters:
-⚠️ **注意：此接口当前未实现**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `KeyUsage` | string | ✅ | `"ENCRYPT_DECRYPT"` |
+| `Description` | string | ❌ | Description (≤256 chars) |
+| `Tags` | object | ❌ | Key/value tag map |
-根据代码分析，虽然底层 KMS 服务具有解密功能，但尚未暴露对应的 HTTP API 接口。这是一个重要的功能缺失。
+Response includes `key_id` and `key_metadata` (enabled, usage, creation date, etc.).
-**预期接口**: `POST /kms/decrypt`
-
-**预期请求参数**:
-
-| 参数名 | 类型 | 必需 | 说明 |
-|--------|------|------|------|
-| `ciphertext_blob` | string | ✅ | 加密的数据密钥（Base64编码） |
-| `encryption_context` | object | ❌ | 解密上下文（必须与加密时相同） |
+### 2. Key metadata
-**预期响应格式**:
+`GET /kms/keys/{key_id}` returns the `key_metadata` object.
-```json
-{
- "key_id": string,
- "plaintext": string
-}
-```
+### 3. List keys
-**预期响应字段说明**:
+`GET /kms/keys?limit=&marker=` with pagination support.
-| 字段名 | 类型 | 说明 |
-|--------|------|------|
-| `key_id` | string | 用于加密的主密钥ID |
-| `plaintext` | string | 解密后的原始数据密钥（Base64编码） |
+### 4. Schedule deletion
-**临时解决方案**:
+`DELETE /kms/keys/delete`
-目前前端需要通过其他方式处理数据密钥解密：
-
-```javascript
-// 临时解决方案：建议联系后端开发团队添加此接口
-console.error('解密数据密钥接口暂未实现，请联系后端开发团队');
+Parameters: `key_id`, optional `pending_window_in_days` (7–30, default 7).
-// 或者考虑使用以下替代方案：
-// 1. 在服务端完成数据加密/解密，前端只处理已解密的数据
-// 2. 等待后端团队实现 /kms/decrypt 接口
-
-/* 未来的调用示例:
-const encryptedKey = localStorage.getItem('encrypted_key');
-
-const decryptRequest = {
- ciphertext_blob: encryptedKey,
- encryption_context: {
- bucket: "user-uploads",
- object_key: "documents/report.pdf",
- user_id: "user123",
- department: "finance"
- }
-};
-
-const decryptedKey = await callKMSAPI('POST', '/kms/decrypt', decryptRequest);
-console.log('解密成功，主密钥ID:', decryptedKey.key_id);
-
-// 使用解密的密钥解密文件数据
-const decryptedData = await decryptFileWithKey(encryptedFileData, decryptedKey.plaintext);
-
-// 立即清理内存中的原始密钥
-decryptedKey.plaintext = null;
-*/
-```
-
-**建议**:
-
-1. **联系后端团队**：建议尽快实现 `POST /kms/decrypt` 接口
-2. **API 设计参考**：可参考 AWS KMS 的 Decrypt API 设计
-3. **安全考虑**：确保接口包含适当的认证和授权检查
-
-## 🪣 Bucket加密配置API
-
-### 概述
+### 5. Cancel deletion
-Bucket加密配置API提供了对存储桶级别默认加密设置的管理功能。这些API基于AWS S3兼容的bucket加密接口，支持SSE-S3和SSE-KMS两种加密方式。
+`POST /kms/keys/cancel-deletion`
-**重要说明**：这些接口使用AWS S3 SDK的标准接口，不是RustFS的自定义KMS接口。
-
-### 1. 列出所有buckets
-
-**接口**: AWS S3 `ListBuckets` 操作
-
-**AWS SDK调用方式**:
-```javascript
-import { ListBucketsCommand } from '@aws-sdk/client-s3';
-
-const listBuckets = async (s3Client) => {
- const command = new ListBucketsCommand({});
- return await s3Client.send(command);
-};
-```
-
-**响应格式**:
-```json
-{
- "Buckets": [
- {
- "Name": "my-bucket",
- "CreationDate": "2024-09-19T10:30:00.000Z"
- }
- ],
- "Owner": {
- "DisplayName": "owner-name",
- "ID": "owner-id"
- }
-}
-```
-
-**响应字段说明**:
-
-| 字段名 | 类型 | 说明 |
-|--------|------|------|
-| `Buckets` | array | Bucket列表 |
-| `Buckets[].Name` | string | Bucket名称 |
-| `Buckets[].CreationDate` | string | 创建时间（ISO8601格式） |
-| `Owner` | object | 所有者信息 |
-
-### 2. 获取bucket加密配置
-
-**接口**: AWS S3 `GetBucketEncryption` 操作
-
-**AWS SDK调用方式**:
-```javascript
-import { GetBucketEncryptionCommand } from '@aws-sdk/client-s3';
-
-const getBucketEncryption = async (s3Client, bucketName) => {
- const command = new GetBucketEncryptionCommand({
- Bucket: bucketName
- });
- return await s3Client.send(command);
-};
-```
-
-**响应格式**:
-```json
-{
- "ServerSideEncryptionConfiguration": {
- "Rules": [
- {
- "ApplyServerSideEncryptionByDefault": {
- "SSEAlgorithm": "aws:kms",
- "KMSMasterKeyID": "key-id-here"
- }
- }
- ]
- }
-}
-```
-
-**响应字段说明**:
-
-| 字段名 | 类型 | 可能值 | 说明 |
-|--------|------|--------|------|
-| `ServerSideEncryptionConfiguration` | object | - | 服务端加密配置 |
-| `Rules` | array | - | 加密规则列表 |
-| `Rules[].ApplyServerSideEncryptionByDefault` | object | - | 默认加密设置 |
-| `SSEAlgorithm` | string | `"aws:kms"`, `"AES256"` | 加密算法 |
-| `KMSMasterKeyID` | string | - | KMS主密钥ID（仅SSE-KMS时存在） |
-
-**错误处理**:
-- **404错误**: 表示bucket未配置加密，应视为"未配置"状态
-- **403错误**: 权限不足，无法访问bucket加密配置
-
-### 3. 设置bucket加密配置
-
-**接口**: AWS S3 `PutBucketEncryption` 操作
-
-**AWS SDK调用方式**:
-
-#### SSE-S3加密:
-```javascript
-import { PutBucketEncryptionCommand } from '@aws-sdk/client-s3';
-
-const putBucketEncryptionSSE_S3 = async (s3Client, bucketName) => {
- const command = new PutBucketEncryptionCommand({
- Bucket: bucketName,
- ServerSideEncryptionConfiguration: {
- Rules: [
- {
- ApplyServerSideEncryptionByDefault: {
- SSEAlgorithm: 'AES256'
- }
- }
- ]
- }
- });
- return await s3Client.send(command);
-};
-```
-
-#### SSE-KMS加密:
-```javascript
-const putBucketEncryptionSSE_KMS = async (s3Client, bucketName, kmsKeyId) => {
- const command = new PutBucketEncryptionCommand({
- Bucket: bucketName,
- ServerSideEncryptionConfiguration: {
- Rules: [
- {
- ApplyServerSideEncryptionByDefault: {
- SSEAlgorithm: 'aws:kms',
- KMSMasterKeyID: kmsKeyId
- }
- }
- ]
- }
- });
- return await s3Client.send(command);
-};
-```
-
-**请求参数**:
-
-| 参数名 | 类型 | 必需 | 说明 |
-|--------|------|------|------|
-| `Bucket` | string | ✅ | Bucket名称 |
-| `ServerSideEncryptionConfiguration` | object | ✅ | 加密配置对象 |
-| `Rules` | array | ✅ | 加密规则数组 |
-| `SSEAlgorithm` | string | ✅ | `"AES256"` 或 `"aws:kms"` |
-| `KMSMasterKeyID` | string | 条件 | KMS密钥ID（SSE-KMS时必需） |
-
-**响应**: 成功时返回HTTP 200，无响应体
-
-### 4. 删除bucket加密配置
-
-**接口**: AWS S3 `DeleteBucketEncryption` 操作
-
-**AWS SDK调用方式**:
-```javascript
-import { DeleteBucketEncryptionCommand } from '@aws-sdk/client-s3';
-
-const deleteBucketEncryption = async (s3Client, bucketName) => {
- const command = new DeleteBucketEncryptionCommand({
- Bucket: bucketName
- });
- return await s3Client.send(command);
-};
-```
-
-**请求参数**:
-
-| 参数名 | 类型 | 必需 | 说明 |
-|--------|------|------|------|
-| `Bucket` | string | ✅ | Bucket名称 |
-
-**响应**: 成功时返回HTTP 204，无响应体
-
-### 前端集成示例
-
-#### Vue.js Composable示例
-```javascript
-import { ref } from 'vue';
-
-export function useBucketEncryption() {
- const { listBuckets, getBucketEncryption, putBucketEncryption, deleteBucketEncryption } = useBucket({});
-
- const buckets = ref([]);
- const loading = ref(false);
- const error = ref(null);
-
- // 加载bucket列表和加密状态
- const loadBucketList = async () => {
- loading.value = true;
- error.value = null;
-
- try {
- const response = await listBuckets();
- if (response?.Buckets) {
- // 并行获取加密配置
- const bucketList = await Promise.all(
- response.Buckets.map(async (bucket) => {
- try {
- const encryptionConfig = await getBucketEncryption(bucket.Name);
-
- let encryptionStatus = 'Disabled';
- let encryptionType = '';
- let kmsKeyId = '';
-
- if (encryptionConfig?.ServerSideEncryptionConfiguration?.Rules?.length > 0) {
- const rule = encryptionConfig.ServerSideEncryptionConfiguration.Rules[0];
- if (rule.ApplyServerSideEncryptionByDefault) {
- encryptionStatus = 'Enabled';
- const algorithm = rule.ApplyServerSideEncryptionByDefault.SSEAlgorithm;
-
- if (algorithm === 'aws:kms') {
- encryptionType = 'SSE-KMS';
- kmsKeyId = rule.ApplyServerSideEncryptionByDefault.KMSMasterKeyID || '';
- } else if (algorithm === 'AES256') {
- encryptionType = 'SSE-S3';
- }
- }
- }
-
- return {
- name: bucket.Name,
- creationDate: bucket.CreationDate,
- encryptionStatus,
- encryptionType,
- kmsKeyId
- };
- } catch (encryptionError) {
- // 404表示未配置加密
- return {
- name: bucket.Name,
- creationDate: bucket.CreationDate,
- encryptionStatus: 'Disabled',
- encryptionType: '',
- kmsKeyId: ''
- };
- }
- })
- );
-
- buckets.value = bucketList;
- }
- } catch (err) {
- error.value = err.message;
- throw err;
- } finally {
- loading.value = false;
- }
- };
-
- // 配置bucket加密
- const configureBucketEncryption = async (bucketName, encryptionType, kmsKeyId = '') => {
- const encryptionConfig = {
- Rules: [
- {
- ApplyServerSideEncryptionByDefault: {
- SSEAlgorithm: encryptionType === 'SSE-KMS' ? 'aws:kms' : 'AES256',
- ...(encryptionType === 'SSE-KMS' && kmsKeyId && { KMSMasterKeyID: kmsKeyId })
- }
- }
- ]
- };
-
- await putBucketEncryption(bucketName, encryptionConfig);
- await loadBucketList(); // 刷新列表
- };
-
- // 移除bucket加密
- const removeBucketEncryption = async (bucketName) => {
- await deleteBucketEncryption(bucketName);
- await loadBucketList(); // 刷新列表
- };
-
- return {
- buckets,
- loading,
- error,
- loadBucketList,
- configureBucketEncryption,
- removeBucketEncryption
- };
-}
-```
-
-### 与KMS密钥管理的集成
-
-结合KMS密钥管理API，可以实现完整的加密密钥生命周期管理：
-
-```javascript
-// 完整的加密管理示例
-export function useEncryptionManagement() {
- const { loadBucketList, configureBucketEncryption } = useBucketEncryption();
- const { getKeyList, createKey } = useSSE();
-
- // 为bucket设置新的加密配置
- const setupBucketEncryption = async (bucketName, encryptionType, keyName) => {
- let kmsKeyId = null;
-
- if (encryptionType === 'SSE-KMS') {
- // 1. 获取现有KMS密钥列表
- const keysList = await getKeyList();
- let targetKey = keysList.keys.find(key =>
- key.tags?.name === keyName || key.description === keyName
- );
-
- // 2. 如果密钥不存在，创建新密钥
- if (!targetKey) {
- const newKeyResponse = await createKey({
- KeyUsage: 'ENCRYPT_DECRYPT',
- Description: `Bucket encryption key for ${bucketName}`,
- Tags: {
- name: keyName,
- bucket: bucketName,
- purpose: 'bucket-encryption'
- }
- });
- kmsKeyId = newKeyResponse.key_id;
- } else {
- kmsKeyId = targetKey.key_id;
- }
- }
-
- // 3. 配置bucket加密
- await configureBucketEncryption(bucketName, encryptionType, kmsKeyId);
-
- return { success: true, kmsKeyId };
- };
-
- return { setupBucketEncryption };
-}
-```
-
-### 安全最佳实践
-
-1. **权限控制**: 确保只有授权用户可以修改bucket加密配置
-2. **加密算法选择**:
- - **SSE-S3**: 由S3服务管理密钥，适合一般用途
- - **SSE-KMS**: 使用KMS管理密钥，提供更细粒度的访问控制
-3. **密钥管理**: 使用SSE-KMS时，确保KMS密钥具有适当的访问策略
-4. **审计日志**: 记录所有加密配置变更操作
-
-### 错误处理指南
-
-| 错误类型 | HTTP状态 | 处理建议 |
-|----------|----------|----------|
-| `NoSuchBucket` | 404 | Bucket不存在，检查bucket名称 |
-| `NoSuchBucketPolicy` | 404 | 未配置加密，视为正常状态 |
-| `AccessDenied` | 403 | 权限不足，检查IAM策略 |
-| `InvalidRequest` | 400 | 请求参数错误，检查加密配置格式 |
-| `KMSKeyNotFound` | 400 | KMS密钥不存在，验证密钥ID |
-
-## 📊 监控和缓存API
-
-### 1. 获取 KMS 配置
-
-**接口**: `GET /kms/config`
-
-**请求参数**: 无
-
-**响应格式**:
-
-```json
-{
- "backend": string,
- "cache_enabled": boolean,
- "cache_max_keys": integer,
- "cache_ttl_seconds": integer,
- "default_key_id": string?
-}
-```
-
-**响应字段说明**:
-
-| 字段名 | 类型 | 说明 |
-|--------|------|------|
-| `backend` | string | 后端类型 |
-| `cache_enabled` | boolean | 是否启用缓存 |
-| `cache_max_keys` | integer | 缓存最大密钥数量 |
-| `cache_ttl_seconds` | integer | 缓存TTL（秒） |
-| `default_key_id` | string | 默认密钥ID |
-
-**调用示例**:
-
-```javascript
-// 获取 KMS 配置
-const config = await callKMSAPI('GET', '/kms/config');
-console.log('KMS配置:', config);
-
-/* 响应示例:
-{
- "backend": "vault",
- "cache_enabled": true,
- "cache_max_keys": 1000,
- "cache_ttl_seconds": 300,
- "default_key_id": "rustfs-master"
-}
-*/
-```
-
-### 2. 清除 KMS 缓存
-
-**接口**: `POST /kms/clear-cache`
-
-**请求参数**: 无
-
-**响应格式**:
-
-```json
-{
- "status": string,
- "message": string
-}
-```
-
-**调用示例**:
-
-```javascript
-// 清除 KMS 缓存
-const clearResult = await callKMSAPI('POST', '/kms/clear-cache');
-console.log('缓存清除结果:', clearResult);
-
-/* 响应示例:
-{
- "status": "success",
- "message": "cache cleared successfully"
-}
-*/
-```
-
-### 3. 获取缓存统计信息
-
-**接口**: `GET /kms/status` (旧版接口，包含缓存统计)
-
-**请求参数**: 无
-
-**响应格式**:
-
-```json
-{
- "backend_type": string,
- "backend_status": string,
- "cache_enabled": boolean,
- "cache_stats": {
- "hit_count": integer,
- "miss_count": integer
- }?,
- "default_key_id": string?
-}
-```
-
-**调用示例**:
-
-```javascript
-// 获取详细的 KMS 状态（包含缓存统计）
-const detailedStatus = await callKMSAPI('GET', '/kms/status');
-console.log('详细状态:', detailedStatus);
-
-/* 响应示例:
-{
- "backend_type": "vault",
- "backend_status": "healthy",
- "cache_enabled": true,
- "cache_stats": {
- "hit_count": 1250,
- "miss_count": 48
- },
- "default_key_id": "rustfs-master"
-}
-*/
-```
-
-## ❌ 通用错误码
-
-### HTTP 状态码
-
-| 状态码 | 错误类型 | 说明 |
-|--------|----------|------|
-| `200` | - | 请求成功 |
-| `400` | `InvalidRequest` | 请求格式错误或参数无效 |
-| `401` | `AccessDenied` | 认证失败 |
-| `403` | `AccessDenied` | 权限不足 |
-| `404` | `NotFound` | 资源不存在 |
-| `409` | `Conflict` | 资源状态冲突 |
-| `500` | `InternalError` | 服务器内部错误 |
-
-### 错误响应格式
+Provide `key_id`; response returns updated metadata with `deletion_date = null`.
+
+## Data Encryption APIs
+
+### 1. Generate data key
+
+`POST /kms/generate-data-key`
+
+Parameters: `key_id`, optional `key_spec` (`AES_256` or `AES_128`), optional `encryption_context` map.
+
+Response contains `plaintext_key` (Base64) and `ciphertext_blob` (Base64).
+
+### 2. Decrypt data key
+
+`POST /kms/decrypt`
+
+> ⚠️ Not yet implemented. Expect parameters `ciphertext_blob` and optional `encryption_context`. A future response will expose `key_id` and `plaintext`.
+
+## Bucket Encryption Configuration APIs
+
+RustFS exposes S3-compatible endpoints via the AWS SDK.
+
+### 1. List buckets
+
+Use `ListBuckets` from the AWS SDK.
+
+### 2. Get default encryption
+
+`GetBucketEncryption` returns SSE rules (`SSEAlgorithm`, optional `KMSMasterKeyID`). A 404 indicates no configuration.
+
+### 3. Set default encryption
+
+`PutBucketEncryption` supports SSE-S3 (`AES256`) or SSE-KMS (`aws:kms` + key ID).
+
+### 4. Delete default encryption
+
+`DeleteBucketEncryption` removes the configuration.
+
+Example composable and helper utilities are provided in the original Chinese document; port them as needed.
+
+## Monitoring & Cache APIs
+
+### 1. Get KMS config
+
+`GET /kms/config` returns backend, cache settings, and default key ID.
+
+### 2. Clear cache
+
+`POST /kms/clear-cache` invalidates cached key metadata.
+
+### 3. Legacy status
+
+`GET /kms/status` (legacy) provides cache hit/miss stats.
+
+## Common Error Codes
+
+### HTTP status codes
+
+| Code | Error | Description |
+|------|-------|-------------|
+| 200 | – | Success |
+| 400 | `InvalidRequest` | Bad request or parameters |
+| 401 | `AccessDenied` | Authentication failure |
+| 403 | `AccessDenied` | Authorization failure |
+| 404 | `NotFound` | Resource not found |
+| 409 | `Conflict` | Resource conflict |
+| 500 | `InternalError` | Server error |
+
+### Error payload
```json
{
@@ -1283,1100 +300,73 @@ console.log('详细状态:', detailedStatus);
}
```
-### 具体错误码
+### Specific codes
-| 错误码 | HTTP状态 | 说明 | 处理建议 |
-|--------|----------|------|----------|
-| `InvalidRequest` | 400 | 请求参数错误 | 检查请求格式和参数 |
-| `AccessDenied` | 401/403 | 认证或授权失败 | 检查访问凭证和权限 |
-| `KeyNotFound` | 404 | 密钥不存在 | 验证密钥ID是否正确 |
-| `InvalidKeyState` | 400 | 密钥状态无效 | 检查密钥是否已启用 |
-| `ServiceNotConfigured` | 409 | KMS服务未配置 | 先配置KMS服务 |
-| `ServiceNotRunning` | 409 | KMS服务未运行 | 启动KMS服务 |
-| `BackendError` | 500 | 后端存储错误 | 检查后端服务状态 |
-| `EncryptionFailed` | 500 | 加密操作失败 | 重试操作或检查密钥状态 |
-| `DecryptionFailed` | 500 | 解密操作失败 | 检查密文和加密上下文 |
+- `InvalidRequest` – check payload
+- `AccessDenied` – verify credentials/permissions
+- `KeyNotFound` – key ID incorrect
+- `InvalidKeyState` – key disabled or invalid
+- `ServiceNotConfigured` – configure KMS first
+- `ServiceNotRunning` – start the service
+- `BackendError` – backend failure
+- `EncryptionFailed` / `DecryptionFailed` – inspect ciphertext/context
-## 📊 数据类型定义
+## Data Types
-### KeyMetadata 对象
+### `KeyMetadata`
-| 字段名 | 类型 | 必需 | 说明 |
-|--------|------|------|------|
-| `key_id` | string | ✅ | 密钥唯一标识符（UUID格式） |
-| `description` | string | ✅ | 密钥描述 |
-| `enabled` | boolean | ✅ | 密钥是否启用 |
-| `key_usage` | string | ✅ | 密钥用途，值为 `"ENCRYPT_DECRYPT"` |
-| `creation_date` | string | ✅ | 创建时间（ISO8601格式） |
-| `rotation_enabled` | boolean | ✅ | 是否启用自动轮换 |
-| `deletion_date` | string | ❌ | 计划删除时间（如果已计划删除） |
+| Field | Type | Description |
+|-------|------|-------------|
+| `key_id` | string | UUID |
+| `description` | string | Key description |
+| `enabled` | boolean | Whether the key is enabled |
+| `key_usage` | string | Always `ENCRYPT_DECRYPT` |
+| `creation_date` | string | ISO 8601 timestamp |
+| `rotation_enabled` | boolean | Rotation status |
+| `deletion_date` | string? | Scheduled deletion timestamp |
-### ConfigSummary 对象
+### `ConfigSummary`
-| 字段名 | 类型 | 必需 | 说明 |
-|--------|------|------|------|
-| `backend_type` | string | ✅ | 后端类型 |
-| `default_key_id` | string | ✅ | 默认主密钥ID |
-| `timeout_seconds` | integer | ✅ | 操作超时时间 |
-| `retry_attempts` | integer | ✅ | 重试次数 |
-| `enable_cache` | boolean | ✅ | 是否启用缓存 |
+| Field | Type | Description |
+|-------|------|-------------|
+| `backend_type` | string | `local` or `vault` |
+| `default_key_id` | string | Default master key |
+| `timeout_seconds` | integer | Operation timeout |
+| `retry_attempts` | integer | Retry attempts |
+| `enable_cache` | boolean | Cache toggle |
-### 枚举值定义
+### Enumerations
-**ServiceStatus（服务状态）**:
-- `"Running"` - 运行中
-- `"Stopped"` - 已停止
-- `"NotConfigured"` - 未配置
-- `"Error"` - 错误状态
+- `ServiceStatus` – `Running`, `Stopped`, `NotConfigured`, `Error`
+- `BackendType` – `local`, `vault`
+- `KeyUsage` – `ENCRYPT_DECRYPT`
+- `KeySpec` – `AES_256`, `AES_128`
-**BackendType（后端类型）**:
-- `"local"` - 本地文件系统后端
-- `"vault"` - Vault后端
+## Implementation Examples
-**KeyUsage（密钥用途）**:
-- `"ENCRYPT_DECRYPT"` - 加密解密
+The original guide included extensive code samples covering bucket encryption flows, Vue/React composables, and full application scaffolding. The key patterns are:
-**KeySpec（数据密钥规格）**:
-- `"AES_256"` - 256位AES密钥
-- `"AES_128"` - 128位AES密钥
+1. **Signed requests** – Use AWS SigV4 (via AWS SDK or manual signing) to call `/rustfs/admin/v3` endpoints.
+2. **Multipart encryption flow** – Request a data key, encrypt data locally, upload ciphertext, and store the encrypted key blob.
+3. **Bucket encryption lifecycle** – Use the S3 SDK to configure default SSE policies, optionally provisioning dedicated KMS keys per bucket.
+4. **Health monitoring** – Periodically poll `/kms/status` or `/kms/config` to ensure the service is healthy and cache hit ratios remain acceptable.
-## 💡 实现示例
+## Troubleshooting & Support
-### Bucket加密管理完整示例
+If issues arise:
-以下是一个完整的bucket加密管理实现，展示了如何在前端应用中集成KMS密钥管理和bucket加密配置：
+1. Verify the KMS service is healthy via `/kms/service-status`.
+2. Confirm Vault or local backend configuration.
+3. Inspect server logs for detailed error messages.
+4. Run `cargo test -p e2e_test kms:: -- --nocapture` to validate the setup.
+5. Ensure your AWS SDK version supports the required S3/KMS calls.
-```javascript
-// BucketEncryptionManager.js - 完整的bucket加密管理类
-import {
- ListBucketsCommand,
- GetBucketEncryptionCommand,
- PutBucketEncryptionCommand,
- DeleteBucketEncryptionCommand
-} from '@aws-sdk/client-s3';
+Common questions:
-class BucketEncryptionManager {
- constructor(s3Client, kmsAPI) {
- this.s3Client = s3Client;
- this.kmsAPI = kmsAPI;
- this.buckets = [];
- this.kmsKeys = [];
- }
-
- // 初始化 - 加载buckets和KMS密钥
- async initialize() {
- try {
- await Promise.all([
- this.loadBuckets(),
- this.loadKMSKeys()
- ]);
- console.log('Bucket加密管理器初始化完成');
- return { success: true };
- } catch (error) {
- console.error('初始化失败:', error);
- throw error;
- }
- }
-
- // 加载所有buckets及其加密状态
- async loadBuckets() {
- try {
- const listResult = await this.s3Client.send(new ListBucketsCommand({}));
-
- // 并行获取每个bucket的加密配置
- this.buckets = await Promise.all(
- listResult.Buckets.map(async (bucket) => {
- const encryptionInfo = await this.getBucketEncryptionInfo(bucket.Name);
- return {
- name: bucket.Name,
- creationDate: bucket.CreationDate,
- ...encryptionInfo
- };
- })
- );
-
- console.log(`已加载 ${this.buckets.length} 个buckets`);
- return this.buckets;
- } catch (error) {
- console.error('加载buckets失败:', error);
- throw error;
- }
- }
-
- // 获取单个bucket的加密信息
- async getBucketEncryptionInfo(bucketName) {
- try {
- const encryptionResult = await this.s3Client.send(
- new GetBucketEncryptionCommand({ Bucket: bucketName })
- );
-
- const rule = encryptionResult.ServerSideEncryptionConfiguration?.Rules?.[0];
- const defaultEncryption = rule?.ApplyServerSideEncryptionByDefault;
-
- if (!defaultEncryption) {
- return {
- encryptionStatus: 'Disabled',
- encryptionType: null,
- encryptionAlgorithm: null,
- kmsKeyId: null,
- kmsKeyName: null
- };
- }
-
- const isKMS = defaultEncryption.SSEAlgorithm === 'aws:kms';
- const kmsKeyId = defaultEncryption.KMSMasterKeyID;
- const kmsKeyName = isKMS ? this.getKMSKeyName(kmsKeyId) : null;
-
- return {
- encryptionStatus: 'Enabled',
- encryptionType: isKMS ? 'SSE-KMS' : 'SSE-S3',
- encryptionAlgorithm: isKMS ? 'AES-256 (KMS)' : 'AES-256 (S3)',
- kmsKeyId: kmsKeyId || null,
- kmsKeyName: kmsKeyName || null
- };
- } catch (error) {
- // 404或NoSuchBucketPolicy表示未配置加密
- if (error.name === 'NoSuchBucketPolicy' || error.$metadata?.httpStatusCode === 404) {
- return {
- encryptionStatus: 'Disabled',
- encryptionType: null,
- encryptionAlgorithm: null,
- kmsKeyId: null,
- kmsKeyName: null
- };
- }
- throw error;
- }
- }
-
- // 加载KMS密钥列表
- async loadKMSKeys() {
- try {
- const keysList = await this.kmsAPI.getKeyList();
- this.kmsKeys = keysList.keys || [];
- console.log(`已加载 ${this.kmsKeys.length} 个KMS密钥`);
- return this.kmsKeys;
- } catch (error) {
- console.error('加载KMS密钥失败:', error);
- // KMS密钥加载失败不应该阻止bucket加载
- this.kmsKeys = [];
- }
- }
-
- // 根据KMS密钥ID获取密钥名称
- getKMSKeyName(keyId) {
- if (!keyId || !this.kmsKeys.length) return null;
-
- const key = this.kmsKeys.find(k => k.key_id === keyId);
- return key?.tags?.name || key?.description || keyId.substring(0, 8) + '...';
- }
-
- // 配置bucket加密
- async configureBucketEncryption(bucketName, encryptionType, kmsKeyId = null) {
- try {
- const encryptionConfig = {
- Bucket: bucketName,
- ServerSideEncryptionConfiguration: {
- Rules: [
- {
- ApplyServerSideEncryptionByDefault: {
- SSEAlgorithm: encryptionType === 'SSE-KMS' ? 'aws:kms' : 'AES256',
- ...(encryptionType === 'SSE-KMS' && kmsKeyId && { KMSMasterKeyID: kmsKeyId })
- }
- }
- ]
- }
- };
-
- await this.s3Client.send(new PutBucketEncryptionCommand(encryptionConfig));
-
- // 更新本地缓存
- await this.refreshBucketInfo(bucketName);
-
- console.log(`Bucket ${bucketName} 加密配置成功: ${encryptionType}`);
- return { success: true };
- } catch (error) {
- console.error(`配置bucket加密失败 (${bucketName}):`, error);
- throw error;
- }
- }
-
- // 移除bucket加密配置
- async removeBucketEncryption(bucketName) {
- try {
- await this.s3Client.send(new DeleteBucketEncryptionCommand({ Bucket: bucketName }));
-
- // 更新本地缓存
- await this.refreshBucketInfo(bucketName);
-
- console.log(`Bucket ${bucketName} 加密配置已移除`);
- return { success: true };
- } catch (error) {
- console.error(`移除bucket加密失败 (${bucketName}):`, error);
- throw error;
- }
- }
-
- // 为bucket创建专用KMS密钥并配置加密
- async setupDedicatedEncryption(bucketName, keyName, keyDescription) {
- try {
- // 1. 创建专用KMS密钥
- const newKey = await this.kmsAPI.createKey({
- KeyUsage: 'ENCRYPT_DECRYPT',
- Description: keyDescription || `Dedicated encryption key for bucket: ${bucketName}`,
- Tags: {
- name: keyName,
- bucket: bucketName,
- purpose: 'bucket-encryption',
- created_by: 'bucket-manager',
- created_at: new Date().toISOString()
- }
- });
-
- // 2. 配置bucket使用新密钥
- await this.configureBucketEncryption(bucketName, 'SSE-KMS', newKey.key_id);
-
- // 3. 更新KMS密钥缓存
- await this.loadKMSKeys();
-
- console.log(`为bucket ${bucketName} 创建并配置专用密钥: ${newKey.key_id}`);
- return {
- success: true,
- keyId: newKey.key_id,
- keyName: keyName
- };
- } catch (error) {
- console.error(`设置专用加密失败 (${bucketName}):`, error);
- throw error;
- }
- }
-
- // 批量配置多个bucket的加密
- async batchConfigureEncryption(configurations) {
- const results = [];
-
- for (const config of configurations) {
- try {
- await this.configureBucketEncryption(
- config.bucketName,
- config.encryptionType,
- config.kmsKeyId
- );
- results.push({ bucketName: config.bucketName, success: true });
- } catch (error) {
- results.push({
- bucketName: config.bucketName,
- success: false,
- error: error.message
- });
- }
- }
-
- const successCount = results.filter(r => r.success).length;
- console.log(`批量配置完成: ${successCount}/${configurations.length} 成功`);
-
- return results;
- }
-
- // 刷新单个bucket信息
- async refreshBucketInfo(bucketName) {
- try {
- const bucketIndex = this.buckets.findIndex(b => b.name === bucketName);
- if (bucketIndex !== -1) {
- const encryptionInfo = await this.getBucketEncryptionInfo(bucketName);
- this.buckets[bucketIndex] = {
- ...this.buckets[bucketIndex],
- ...encryptionInfo
- };
- }
- } catch (error) {
- console.error(`刷新bucket信息失败 (${bucketName}):`, error);
- }
- }
-
- // 获取加密统计信息
- getEncryptionStats() {
- const total = this.buckets.length;
- const encrypted = this.buckets.filter(b => b.encryptionStatus === 'Enabled').length;
- const sseS3 = this.buckets.filter(b => b.encryptionType === 'SSE-S3').length;
- const sseKMS = this.buckets.filter(b => b.encryptionType === 'SSE-KMS').length;
- const unencrypted = total - encrypted;
-
- return {
- total,
- encrypted,
- unencrypted,
- sseS3,
- sseKMS,
- encryptionRate: total > 0 ? (encrypted / total * 100).toFixed(1) + '%' : '0%'
- };
- }
-
- // 搜索和过滤功能
- searchBuckets(query, filters = {}) {
- let filtered = [...this.buckets];
-
- // 名称搜索
- if (query) {
- const lowerQuery = query.toLowerCase();
- filtered = filtered.filter(bucket =>
- bucket.name.toLowerCase().includes(lowerQuery)
- );
- }
-
- // 加密状态过滤
- if (filters.encryptionStatus) {
- filtered = filtered.filter(bucket =>
- bucket.encryptionStatus === filters.encryptionStatus
- );
- }
-
- // 加密类型过滤
- if (filters.encryptionType) {
- filtered = filtered.filter(bucket =>
- bucket.encryptionType === filters.encryptionType
- );
- }
-
- return filtered;
- }
-
- // 获取可用的KMS密钥选项
- getKMSKeyOptions() {
- return this.kmsKeys.map(key => ({
- value: key.key_id,
- label: key.tags?.name || key.description || `Key: ${key.key_id.substring(0, 8)}...`,
- description: key.description,
- enabled: key.enabled,
- creationDate: key.creation_date
- }));
- }
-}
-
-// 使用示例
-async function bucketEncryptionExample() {
- // 1. 初始化S3客户端和KMS API
- const s3Client = new S3Client({
- region: 'us-east-1',
- endpoint: 'http://localhost:9000',
- forcePathStyle: true,
- credentials: {
- accessKeyId: 'your-access-key',
- secretAccessKey: 'your-secret-key'
- }
- });
-
- const kmsAPI = {
- createKey: async (params) => callKMSAPI('POST', '/kms/keys', params),
- getKeyList: async () => callKMSAPI('GET', '/kms/keys'),
- getKeyDetails: async (keyId) => callKMSAPI('GET', `/kms/keys/${keyId}`)
- };
-
- // 2. 创建管理器实例
- const bucketManager = new BucketEncryptionManager(s3Client, kmsAPI);
-
- try {
- // 3. 初始化
- await bucketManager.initialize();
-
- // 4. 查看当前加密状态
- const stats = bucketManager.getEncryptionStats();
- console.log('加密统计:', stats);
-
- // 5. 为特定bucket配置SSE-KMS加密
- await bucketManager.setupDedicatedEncryption(
- 'sensitive-data-bucket',
- 'sensitive-data-key',
- 'Encryption key for sensitive data bucket'
- );
-
- // 6. 为其他buckets配置SSE-S3加密
- const bucketConfigs = [
- { bucketName: 'public-assets', encryptionType: 'SSE-S3' },
- { bucketName: 'user-uploads', encryptionType: 'SSE-S3' },
- { bucketName: 'backup-data', encryptionType: 'SSE-S3' }
- ];
-
- const batchResults = await bucketManager.batchConfigureEncryption(bucketConfigs);
- console.log('批量配置结果:', batchResults);
-
- // 7. 搜索未加密的buckets
- const unencryptedBuckets = bucketManager.searchBuckets('', {
- encryptionStatus: 'Disabled'
- });
-
- if (unencryptedBuckets.length > 0) {
- console.log('发现未加密的buckets:', unencryptedBuckets.map(b => b.name));
- }
-
- // 8. 获取最终加密统计
- const finalStats = bucketManager.getEncryptionStats();
- console.log('最终加密统计:', finalStats);
-
- } catch (error) {
- console.error('Bucket加密管理示例执行失败:', error);
- }
-}
-
-// 启动示例
-bucketEncryptionExample();
-```
-
-### JavaScript 基础请求函数
-
-```javascript
-import AWS from 'aws-sdk';
-
-// 配置 AWS SDK
-const awsConfig = {
- accessKeyId: 'your-access-key',
- secretAccessKey: 'your-secret-key',
- region: 'us-east-1',
- endpoint: 'http://localhost:9000',
- s3ForcePathStyle: true
-};
-
-// 创建签名请求的函数
-function createSignedRequest(method, path, body = null) {
- const endpoint = new AWS.Endpoint(awsConfig.endpoint);
- const request = new AWS.HttpRequest(endpoint, awsConfig.region);
-
- request.method = method;
- request.path = `/rustfs/admin/v3${path}`;
- request.headers['Content-Type'] = 'application/json';
-
- if (body) {
- request.body = JSON.stringify(body);
- }
-
- const signer = new AWS.Signers.V4(request, 'execute-api');
- signer.addAuthorization(awsConfig, new Date());
-
- return request;
-}
-
-// 基础的 KMS API 调用函数
-async function callKMSAPI(method, path, body = null) {
- const signedRequest = createSignedRequest(method, path, body);
-
- const options = {
- method: signedRequest.method,
- headers: signedRequest.headers,
- body: signedRequest.body
- };
-
- const response = await fetch(signedRequest.endpoint.href + signedRequest.path, options);
- const data = await response.json();
-
- if (!response.ok) {
- throw new Error(`KMS API Error: ${data.error?.message || response.statusText}`);
- }
-
- return data;
-}
-
-// 文件加密函数（使用 Web Crypto API）
-async function encryptFileWithKey(fileData, plaintextKey) {
- // 将 Base64 密钥转换为 ArrayBuffer
- const keyData = Uint8Array.from(atob(plaintextKey), c => c.charCodeAt(0));
-
- // 导入密钥
- const cryptoKey = await crypto.subtle.importKey(
- 'raw',
- keyData,
- { name: 'AES-GCM' },
- false,
- ['encrypt']
- );
-
- // 生成随机 IV
- const iv = crypto.getRandomValues(new Uint8Array(12));
-
- // 加密数据
- const encryptedData = await crypto.subtle.encrypt(
- { name: 'AES-GCM', iv: iv },
- cryptoKey,
- fileData
- );
-
- return {
- encryptedData: new Uint8Array(encryptedData),
- iv: iv
- };
-}
-
-// 文件解密函数
-async function decryptFileWithKey(encryptedData, iv, plaintextKey) {
- const keyData = Uint8Array.from(atob(plaintextKey), c => c.charCodeAt(0));
-
- const cryptoKey = await crypto.subtle.importKey(
- 'raw',
- keyData,
- { name: 'AES-GCM' },
- false,
- ['decrypt']
- );
-
- const decryptedData = await crypto.subtle.decrypt(
- { name: 'AES-GCM', iv: iv },
- cryptoKey,
- encryptedData
- );
-
- return new Uint8Array(decryptedData);
-}
-```
-
-### React Hook 示例
-
-```javascript
-import { useState, useCallback } from 'react';
-
-export function useKMSService() {
- const [loading, setLoading] = useState(false);
- const [error, setError] = useState(null);
-
- const callAPI = useCallback(async (method, path, body) => {
- setLoading(true);
- setError(null);
-
- try {
- const result = await callKMSAPI(method, path, body);
- return result;
- } catch (err) {
- setError(err.message);
- throw err;
- } finally {
- setLoading(false);
- }
- }, []);
-
- return { callAPI, loading, error };
-}
-```
-
-### Vue.js Composable 示例
-
-```javascript
-import { ref } from 'vue';
-
-export function useKMSService() {
- const loading = ref(false);
- const error = ref(null);
-
- const callAPI = async (method, path, body) => {
- loading.value = true;
- error.value = null;
-
- try {
- return await callKMSAPI(method, path, body);
- } catch (err) {
- error.value = err.message;
- throw err;
- } finally {
- loading.value = false;
- }
- };
-
- return { callAPI, loading, error };
-}
-```
-
-### 完整的端到端使用示例
-
-#### 1. KMS 服务初始化
-
-```javascript
-// KMS 服务管理类
-class KMSServiceManager {
- constructor() {
- this.isConfigured = false;
- this.isRunning = false;
- }
-
- // 初始化 KMS 服务
- async initialize(backendType = 'local') {
- try {
- // 1. 配置 KMS 服务
- const config = backendType === 'local' ? {
- backend_type: "local",
- key_directory: "/var/lib/rustfs/kms/keys",
- default_key_id: "default-master-key",
- enable_cache: true,
- cache_ttl_seconds: 600
- } : {
- backend_type: "vault",
- address: "https://vault.example.com:8200",
- auth_method: { token: "s.your-vault-token" },
- mount_path: "transit",
- kv_mount: "secret",
- key_path_prefix: "rustfs/kms/keys",
- default_key_id: "rustfs-master"
- };
-
- const configResult = await callKMSAPI('POST', '/kms/configure', config);
- console.log('KMS 配置成功:', configResult);
- this.isConfigured = true;
-
- // 2. 启动 KMS 服务
- const startResult = await callKMSAPI('POST', '/kms/start');
- console.log('KMS 启动成功:', startResult);
- this.isRunning = true;
-
- // 3. 验证服务状态
- const status = await callKMSAPI('GET', '/kms/status');
- console.log('KMS 状态:', status);
-
- return { success: true, status };
- } catch (error) {
- console.error('KMS 初始化失败:', error);
- throw error;
- }
- }
-
- // 检查服务健康状态
- async checkHealth() {
- try {
- const status = await callKMSAPI('GET', '/kms/status');
- return status.healthy;
- } catch (error) {
- console.error('健康检查失败:', error);
- return false;
- }
- }
-}
-```
-
-#### 2. 密钥管理工具类
-
-```javascript
-// 密钥管理工具类
-class KMSKeyManager {
- constructor() {
- this.keys = new Map();
- }
-
- // 创建应用主密钥
- async createApplicationKey(description, tags = {}) {
- try {
- const keyRequest = {
- KeyUsage: "ENCRYPT_DECRYPT",
- Description: description,
- Tags: {
- ...tags,
- created_by: "frontend-app",
- created_at: new Date().toISOString()
- }
- };
-
- const result = await callKMSAPI('POST', '/kms/keys', keyRequest);
- this.keys.set(result.key_id, result.key_metadata);
-
- console.log(`密钥创建成功: ${result.key_id}`);
- return result;
- } catch (error) {
- console.error('密钥创建失败:', error);
- throw error;
- }
- }
-
- // 列出所有应用密钥
- async listApplicationKeys() {
- try {
- let allKeys = [];
- let marker = null;
-
- do {
- const params = new URLSearchParams({ limit: '50' });
- if (marker) params.append('marker', marker);
-
- const keysList = await callKMSAPI('GET', `/kms/keys?${params}`);
- allKeys.push(...keysList.keys);
- marker = keysList.next_marker;
- } while (marker);
-
- // 更新本地缓存
- allKeys.forEach(key => {
- this.keys.set(key.key_id, key);
- });
-
- return allKeys;
- } catch (error) {
- console.error('密钥列表获取失败:', error);
- throw error;
- }
- }
-
- // 获取密钥详情
- async getKeyDetails(keyId) {
- try {
- const details = await callKMSAPI('GET', `/kms/keys/${keyId}`);
- this.keys.set(keyId, details.key_metadata);
- return details;
- } catch (error) {
- console.error(`密钥详情获取失败 (${keyId}):`, error);
- throw error;
- }
- }
-
- // 安全删除密钥
- async safeDeleteKey(keyId, pendingDays = 7) {
- try {
- const deleteRequest = {
- key_id: keyId,
- pending_window_in_days: pendingDays
- };
-
- const result = await callKMSAPI('DELETE', '/kms/keys/delete', deleteRequest);
- console.log(`密钥已计划删除: ${keyId}, 删除日期: ${result.deletion_date}`);
- return result;
- } catch (error) {
- console.error(`密钥删除失败 (${keyId}):`, error);
- throw error;
- }
- }
-}
-```
-
-#### 3. 文件加密管理器
-
-```javascript
-// 文件加密管理器
-class FileEncryptionManager {
- constructor(keyManager) {
- this.keyManager = keyManager;
- this.encryptionCache = new Map();
- }
-
- // 加密文件
- async encryptFile(file, masterKeyId, metadata = {}) {
- try {
- // 1. 生成数据密钥
- const encryptionContext = {
- file_name: file.name,
- file_size: file.size.toString(),
- file_type: file.type,
- user_id: metadata.userId || 'unknown',
- ...metadata
- };
-
- const dataKeyRequest = {
- key_id: masterKeyId,
- key_spec: "AES_256",
- encryption_context: encryptionContext
- };
-
- const dataKey = await callKMSAPI('POST', '/kms/generate-data-key', dataKeyRequest);
-
- // 2. 读取文件数据
- const fileData = await this.readFileAsArrayBuffer(file);
-
- // 3. 加密文件数据
- const { encryptedData, iv } = await encryptFileWithKey(fileData, dataKey.plaintext_key);
-
- // 4. 立即清理内存中的原始密钥
- dataKey.plaintext_key = null;
-
- // 5. 创建加密文件信息
- const encryptedFileInfo = {
- encryptedData: encryptedData,
- iv: iv,
- ciphertextBlob: dataKey.ciphertext_blob,
- keyId: dataKey.key_id,
- encryptionContext: encryptionContext,
- originalFileName: file.name,
- originalSize: file.size,
- encryptedAt: new Date().toISOString()
- };
-
- // 6. 缓存加密信息
- const fileId = this.generateFileId();
- this.encryptionCache.set(fileId, encryptedFileInfo);
-
- console.log(`文件加密成功: ${file.name} -> ${fileId}`);
- return { fileId, encryptedFileInfo };
-
- } catch (error) {
- console.error(`文件加密失败 (${file.name}):`, error);
- throw error;
- }
- }
-
- // 解密文件
- async decryptFile(fileId) {
- try {
- // 1. 获取加密文件信息
- const encryptedFileInfo = this.encryptionCache.get(fileId);
- if (!encryptedFileInfo) {
- throw new Error('加密文件信息不存在');
- }
-
- // 2. 解密数据密钥
- const decryptRequest = {
- ciphertext_blob: encryptedFileInfo.ciphertextBlob,
- encryption_context: encryptedFileInfo.encryptionContext
- };
-
- const decryptedKey = await callKMSAPI('POST', '/kms/decrypt', decryptRequest);
-
- // 3. 解密文件数据
- const decryptedData = await decryptFileWithKey(
- encryptedFileInfo.encryptedData,
- encryptedFileInfo.iv,
- decryptedKey.plaintext
- );
-
- // 4. 立即清理内存中的原始密钥
- decryptedKey.plaintext = null;
-
- // 5. 创建解密后的文件对象
- const decryptedFile = new File(
- [decryptedData],
- encryptedFileInfo.originalFileName,
- { type: encryptedFileInfo.encryptionContext.file_type }
- );
-
- console.log(`文件解密成功: ${fileId} -> ${encryptedFileInfo.originalFileName}`);
- return decryptedFile;
-
- } catch (error) {
- console.error(`文件解密失败 (${fileId}):`, error);
- throw error;
- }
- }
-
- // 批量加密文件
- async encryptFiles(files, masterKeyId, metadata = {}) {
- const results = [];
-
- for (const file of files) {
- try {
- const result = await this.encryptFile(file, masterKeyId, {
- ...metadata,
- batch_id: this.generateBatchId(),
- file_index: results.length
- });
- results.push({ success: true, file: file.name, ...result });
- } catch (error) {
- results.push({ success: false, file: file.name, error: error.message });
- }
- }
-
- return results;
- }
-
- // 工具方法
- readFileAsArrayBuffer(file) {
- return new Promise((resolve, reject) => {
- const reader = new FileReader();
- reader.onload = () => resolve(reader.result);
- reader.onerror = () => reject(reader.error);
- reader.readAsArrayBuffer(file);
- });
- }
-
- generateFileId() {
- return 'file_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9);
- }
-
- generateBatchId() {
- return 'batch_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9);
- }
-}
-```
-
-#### 4. 完整的应用示例
-
-```javascript
-// 完整的 KMS 应用示例
-class KMSApplication {
- constructor() {
- this.serviceManager = new KMSServiceManager();
- this.keyManager = new KMSKeyManager();
- this.fileManager = null;
- this.appMasterKeyId = null;
- }
-
- // 初始化应用
- async initialize() {
- try {
- console.log('正在初始化 KMS 应用...');
-
- // 1. 初始化 KMS 服务
- await this.serviceManager.initialize('local');
-
- // 2. 创建应用主密钥
- const appKey = await this.keyManager.createApplicationKey(
- '文件加密应用主密钥',
- {
- application: 'file-encryption-app',
- version: '1.0.0',
- environment: 'production'
- }
- );
- this.appMasterKeyId = appKey.key_id;
-
- // 3. 初始化文件管理器
- this.fileManager = new FileEncryptionManager(this.keyManager);
-
- console.log('KMS 应用初始化完成');
- return { success: true, masterKeyId: this.appMasterKeyId };
-
- } catch (error) {
- console.error('KMS 应用初始化失败:', error);
- throw error;
- }
- }
-
- // 处理文件上传和加密
- async handleFileUpload(files, userMetadata = {}) {
- if (!this.fileManager || !this.appMasterKeyId) {
- throw new Error('应用未初始化');
- }
-
- try {
- console.log(`开始处理 ${files.length} 个文件的加密...`);
-
- const results = await this.fileManager.encryptFiles(
- files,
- this.appMasterKeyId,
- {
- ...userMetadata,
- upload_session: Date.now()
- }
- );
-
- const successCount = results.filter(r => r.success).length;
- console.log(`文件加密完成: ${successCount}/${files.length} 成功`);
-
- return results;
-
- } catch (error) {
- console.error('文件上传处理失败:', error);
- throw error;
- }
- }
-
- // 处理文件下载和解密
- async handleFileDownload(fileId) {
- if (!this.fileManager) {
- throw new Error('应用未初始化');
- }
-
- try {
- console.log(`开始解密文件: ${fileId}`);
- const decryptedFile = await this.fileManager.decryptFile(fileId);
-
- // 创建下载链接
- const url = URL.createObjectURL(decryptedFile);
- const a = document.createElement('a');
- a.href = url;
- a.download = decryptedFile.name;
- a.click();
-
- // 清理资源
- setTimeout(() => URL.revokeObjectURL(url), 100);
-
- console.log(`文件下载完成: ${decryptedFile.name}`);
- return decryptedFile;
-
- } catch (error) {
- console.error('文件下载处理失败:', error);
- throw error;
- }
- }
-
- // 健康检查
- async performHealthCheck() {
- try {
- const isHealthy = await this.serviceManager.checkHealth();
- const keyCount = this.keyManager.keys.size;
-
- return {
- kmsHealthy: isHealthy,
- keyCount: keyCount,
- masterKeyId: this.appMasterKeyId,
- timestamp: new Date().toISOString()
- };
- } catch (error) {
- console.error('健康检查失败:', error);
- return { kmsHealthy: false, error: error.message };
- }
- }
-}
-
-// 使用示例
-async function main() {
- const app = new KMSApplication();
-
- try {
- // 初始化应用
- await app.initialize();
-
- // 模拟文件上传
- const fileInput = document.getElementById('file-input');
- fileInput.addEventListener('change', async (event) => {
- const files = Array.from(event.target.files);
- const results = await app.handleFileUpload(files, {
- userId: 'user123',
- department: 'finance'
- });
-
- console.log('上传结果:', results);
- });
-
- // 定期健康检查
- setInterval(async () => {
- const health = await app.performHealthCheck();
- console.log('健康状态:', health);
- }, 30000);
-
- } catch (error) {
- console.error('应用启动失败:', error);
- }
-}
-
-// 启动应用
-main();
-```
-
-## 🔗 相关资源
-
-- [KMS 配置指南](configuration.md)
-- [服务端加密集成](sse-integration.md)
-- [安全最佳实践](security.md)
-- [故障排除指南](troubleshooting.md)
-
-## 📞 技术支持
-
-如果在对接过程中遇到问题，请：
-
-1. **KMS服务问题**: 检查 [故障排除指南](troubleshooting.md)
-2. **Bucket加密问题**: 验证S3客户端配置和权限设置
-3. **查看日志**: 检查服务器日志以获取详细错误信息
-4. **运行测试**: 验证KMS配置：`cargo test -p e2e_test kms:: -- --nocapture`
-5. **API兼容性**: 确保使用的AWS SDK版本支持相关操作
-
-### 常见问题解决
-
-**Q: Bucket加密配置失败，提示权限不足**
-A: 检查IAM策略是否包含以下权限：
-- `s3:GetBucketEncryption`
-- `s3:PutBucketEncryption`
-- `s3:DeleteBucketEncryption`
-- `kms:DescribeKey`（当使用SSE-KMS时）
-
-**Q: KMS密钥在bucket加密中无法选择**
-A: 确保：
-1. KMS服务状态为Running且健康
-2. 密钥状态为Enabled
-3. 密钥的KeyUsage为ENCRYPT_DECRYPT
-
-**Q: 前端显示加密状态错误**
-A: 这通常是由于：
-1. 获取bucket加密配置时发生404错误（正常，表示未配置）
-2. 网络延迟导致状态更新不及时，手动刷新即可
+- **Bucket encryption fails with insufficient permissions** – Ensure the IAM policy grants `s3:GetBucketEncryption`, `s3:PutBucketEncryption`, `s3:DeleteBucketEncryption`, and (for SSE-KMS) `kms:DescribeKey`.
+- **Unable to select a KMS key** – Confirm the KMS service is running, the key is enabled, and `KeyUsage` is `ENCRYPT_DECRYPT`.
+- **Frontend shows incorrect encryption state** – A 404 during `GetBucketEncryption` is normal (no configuration). Allow for network latency before refreshing the status.
---
-*本文档版本：v1.1 | 最后更新：2024-09-22 | 新增：Bucket加密配置API指南*
\ No newline at end of file
+_Last updated: 2024-09-22_
diff --git a/rustfs/README.md b/rustfs/README.md
index 8aaab788..af51aa5a 100644
--- a/rustfs/README.md
+++ b/rustfs/README.md
@@ -17,7 +17,7 @@
-English | 简体中文
+English | Simplified Chinese
RustFS is a high-performance distributed object storage software built using Rust, one of the most popular languages
diff --git a/scripts/run_scanner_benchmarks.sh b/scripts/run_scanner_benchmarks.sh
index 576acc9c..bbf68530 100755
--- a/scripts/run_scanner_benchmarks.sh
+++ b/scripts/run_scanner_benchmarks.sh
@@ -1,18 +1,18 @@
#!/bin/bash
-# Scanner性能优化基准测试运行脚本
-# 使用方法: ./scripts/run_scanner_benchmarks.sh [test_type] [quick]
+# Scanner performance benchmark runner
+# Usage: ./scripts/run_scanner_benchmarks.sh [test_type] [quick]
set -e
WORKSPACE_ROOT="/home/dandan/code/rust/rustfs"
cd "$WORKSPACE_ROOT"
-# 基本参数
+# Default parameters
QUICK_MODE=false
TEST_TYPE="all"
-# 解析命令行参数
+# Parse command-line arguments
if [[ "$1" == "quick" ]] || [[ "$2" == "quick" ]]; then
QUICK_MODE=true
fi
@@ -21,116 +21,116 @@ if [[ -n "$1" ]] && [[ "$1" != "quick" ]]; then
TEST_TYPE="$1"
fi
-# 快速模式的基准测试参数
+# Benchmark options for quick mode
if [[ "$QUICK_MODE" == "true" ]]; then
BENCH_ARGS="--sample-size 10 --warm-up-time 1 --measurement-time 2"
- echo "🚀 运行快速基准测试模式..."
+ echo "🚀 Running benchmarks in quick mode..."
else
BENCH_ARGS=""
- echo "🏃 运行完整基准测试模式..."
+ echo "🏃 Running the full benchmark suite..."
fi
-echo "📊 Scanner性能优化基准测试"
-echo "工作目录: $WORKSPACE_ROOT"
-echo "测试类型: $TEST_TYPE"
-echo "快速模式: $QUICK_MODE"
+echo "📊 Scanner performance benchmarks"
+echo "Working directory: $WORKSPACE_ROOT"
+echo "Selected benchmark group: $TEST_TYPE"
+echo "Quick mode: $QUICK_MODE"
echo "="
-# 检查编译状态
-echo "🔧 检查编译状态..."
+# Verify the workspace compiles
+echo "🔧 Checking compilation status..."
if ! cargo check --package rustfs-ahm --benches --quiet; then
- echo "❌ 基准测试编译失败"
+ echo "❌ Benchmark compilation failed"
exit 1
fi
-echo "✅ 编译检查通过"
+echo "✅ Compilation succeeded"
-# 基准测试函数
+# Helper to run an individual benchmark target
run_benchmark() {
local bench_name=$1
local description=$2
-
+
echo ""
- echo "🧪 运行 $description"
- echo "基准测试: $bench_name"
- echo "参数: $BENCH_ARGS"
-
+ echo "🧪 Running $description"
+ echo "Benchmark: $bench_name"
+ echo "Arguments: $BENCH_ARGS"
+
if timeout 300 cargo bench --package rustfs-ahm --bench "$bench_name" -- $BENCH_ARGS; then
- echo "✅ $description 完成"
+ echo "✅ $description finished"
else
- echo "⚠️ $description 运行超时或失败"
+ echo "⚠️ $description timed out or failed"
return 1
fi
}
-# 运行指定的基准测试
+# Dispatch benchmarks based on the requested test type
case "$TEST_TYPE" in
"business" | "business_io")
- run_benchmark "business_io_impact" "业务IO影响测试"
+ run_benchmark "business_io_impact" "Business I/O impact"
;;
"scanner" | "performance")
- run_benchmark "scanner_performance" "Scanner性能测试"
+ run_benchmark "scanner_performance" "Scanner performance"
;;
"resource" | "contention")
- run_benchmark "resource_contention" "资源竞争测试"
+ run_benchmark "resource_contention" "Resource contention"
;;
"adaptive" | "scheduling")
- run_benchmark "adaptive_scheduling" "智能调度测试"
+ run_benchmark "adaptive_scheduling" "Adaptive scheduling"
;;
"list")
- echo "📋 列出所有可用的基准测试:"
+ echo "📋 Available benchmarks:"
cargo bench --package rustfs-ahm -- --list
;;
"all")
- echo "🚀 运行所有基准测试..."
-
+ echo "🚀 Running the full benchmark suite..."
+
echo ""
- echo "=== 1/4 业务IO影响测试 ==="
- if ! run_benchmark "business_io_impact" "业务IO影响测试"; then
- echo "⚠️ 业务IO影响测试失败，继续运行其他测试..."
+ echo "=== 1/4 Business I/O impact ==="
+ if ! run_benchmark "business_io_impact" "Business I/O impact"; then
+ echo "⚠️ Business I/O impact benchmark failed, continuing..."
fi
-
+
echo ""
- echo "=== 2/4 Scanner性能测试 ==="
- if ! run_benchmark "scanner_performance" "Scanner性能测试"; then
- echo "⚠️ Scanner性能测试失败，继续运行其他测试..."
+ echo "=== 2/4 Scanner performance ==="
+ if ! run_benchmark "scanner_performance" "Scanner performance"; then
+ echo "⚠️ Scanner performance benchmark failed, continuing..."
fi
-
+
echo ""
- echo "=== 3/4 资源竞争测试 ==="
- if ! run_benchmark "resource_contention" "资源竞争测试"; then
- echo "⚠️ 资源竞争测试失败，继续运行其他测试..."
+ echo "=== 3/4 Resource contention ==="
+ if ! run_benchmark "resource_contention" "Resource contention"; then
+ echo "⚠️ Resource contention benchmark failed, continuing..."
fi
-
+
echo ""
- echo "=== 4/4 智能调度测试 ==="
- if ! run_benchmark "adaptive_scheduling" "智能调度测试"; then
- echo "⚠️ 智能调度测试失败"
+ echo "=== 4/4 Adaptive scheduling ==="
+ if ! run_benchmark "adaptive_scheduling" "Adaptive scheduling"; then
+ echo "⚠️ Adaptive scheduling benchmark failed"
fi
;;
*)
- echo "❌ 未知的测试类型: $TEST_TYPE"
+ echo "❌ Unknown test type: $TEST_TYPE"
echo ""
- echo "用法: $0 [test_type] [quick]"
+ echo "Usage: $0 [test_type] [quick]"
echo ""
- echo "测试类型:"
- echo " all - 运行所有基准测试 (默认)"
- echo " business|business_io - 业务IO影响测试"
- echo " scanner|performance - Scanner性能测试"
- echo " resource|contention - 资源竞争测试"
- echo " adaptive|scheduling - 智能调度测试"
- echo " list - 列出所有可用测试"
+ echo "Available test types:"
+ echo " all - run the entire benchmark suite (default)"
+ echo " business|business_io - business I/O impact benchmark"
+ echo " scanner|performance - scanner performance benchmark"
+ echo " resource|contention - resource contention benchmark"
+ echo " adaptive|scheduling - adaptive scheduling benchmark"
+ echo " list - list all benchmarks"
echo ""
- echo "选项:"
- echo " quick - 快速模式 (减少样本数和测试时间)"
+ echo "Options:"
+ echo " quick - quick mode (smaller sample size and duration)"
echo ""
- echo "示例:"
- echo " $0 business quick - 快速运行业务IO测试"
- echo " $0 all - 运行所有完整测试"
- echo " $0 list - 列出所有测试"
+ echo "Examples:"
+ echo " $0 business quick - run the business I/O benchmark in quick mode"
+ echo " $0 all - run every benchmark"
+ echo " $0 list - list available benchmarks"
exit 1
;;
esac
echo ""
-echo "🎉 基准测试脚本执行完成!"
-echo "📊 查看结果: target/criterion/ 目录下有详细的HTML报告"
\ No newline at end of file
+echo "🎉 Benchmark script finished!"
+echo "📊 Detailed HTML reports are available under target/criterion/"
\ No newline at end of file