rustfs/crates/e2e_test/src/kms

KMS End-to-End Tests

本目录包含 RustFS KMS (Key Management Service) 的端到端集成测试，用于验证完整的 KMS 功能流程。

📁 测试文件说明

kms_local_test.rs

本地KMS后端的端到端测试，包含：

• 自动启动和配置本地KMS后端
• 通过动态配置API配置KMS服务
• 测试SSE-C（客户端提供密钥）加密流程
• 验证S3兼容的对象加密/解密操作
• 密钥生命周期管理测试

kms_vault_test.rs

Vault KMS后端的端到端测试，包含：

• 自动启动Vault开发服务器
• 配置Vault transit engine和密钥
• 通过动态配置API配置KMS服务
• 测试完整的Vault KMS集成
• 验证Token认证和加密操作

kms_comprehensive_test.rs

完整的KMS功能测试套件（当前因AWS SDK API兼容性问题暂时禁用），包含：

• Bucket加密配置: SSE-S3和SSE-KMS默认加密设置
• 完整的SSE加密模式测试:
  • SSE-S3: S3管理的服务端加密
  • SSE-KMS: KMS管理的服务端加密
  • SSE-C: 客户端提供密钥的服务端加密
• 对象操作测试: 上传、下载、验证三种SSE模式
• 分片上传测试: 多部分上传支持所有SSE模式
• 对象复制测试: 不同SSE模式间的复制操作
• 完整KMS API管理:
  • 密钥生命周期管理（创建、列表、描述、删除、取消删除）
  • 直接加密/解密操作
  • 数据密钥生成和操作
  • KMS服务管理（启动、停止、状态查询）

kms_integration_test.rs

综合性KMS集成测试，包含：

• 多后端兼容性测试
• KMS服务生命周期测试
• 错误处理和恢复测试
• 注意: 当前因AWS SDK API兼容性问题暂时禁用

🚀 如何运行测试

前提条件

1. 系统依赖：

   # macOS
   brew install vault awscurl
   
   # Ubuntu/Debian
   apt-get install vault
   pip install awscurl
   

2. 构建RustFS：

   # 在项目根目录
   cargo build
   

运行单个测试

本地KMS测试

cd crates/e2e_test
cargo test test_local_kms_end_to_end -- --nocapture

Vault KMS测试

cd crates/e2e_test
cargo test test_vault_kms_end_to_end -- --nocapture

高可用性测试

cd crates/e2e_test
cargo test test_vault_kms_high_availability -- --nocapture

完整功能测试（开发中）

cd crates/e2e_test
# 注意：以下测试因AWS SDK API兼容性问题暂时禁用
# cargo test test_comprehensive_kms_functionality -- --nocapture
# cargo test test_sse_modes_compatibility -- --nocapture  
# cargo test test_kms_api_comprehensive -- --nocapture

运行所有KMS测试

cd crates/e2e_test
cargo test kms -- --nocapture

串行运行（避免端口冲突）

cd crates/e2e_test
cargo test kms -- --nocapture --test-threads=1

🔧 测试配置

环境变量

# 可选：自定义端口（默认使用9050）
export RUSTFS_TEST_PORT=9050

# 可选：自定义Vault端口（默认使用8200）
export VAULT_TEST_PORT=8200

# 可选：启用详细日志
export RUST_LOG=debug

依赖的二进制文件路径

测试会自动查找以下二进制文件：

• ../../target/debug/rustfs - RustFS服务器
• vault - Vault (需要在PATH中)
• /Users/dandan/Library/Python/3.9/bin/awscurl - AWS签名工具

📋 测试流程说明

Local KMS测试流程

1. 环境准备：创建临时目录，设置KMS密钥存储路径
2. 启动服务：启动RustFS服务器，启用KMS功能
3. 等待就绪：检查端口监听和S3 API响应
4. 配置KMS：通过awscurl发送配置请求到admin API
5. 启动KMS：激活KMS服务
6. 功能测试：
   • 创建测试存储桶
   • 测试SSE-C加密（客户端提供密钥）
   • 验证对象加密/解密
7. 清理：终止进程，清理临时文件

Vault KMS测试流程

1. 启动Vault：使用开发模式启动Vault服务器
2. 配置Vault：
   • 启用transit secrets engine
   • 创建加密密钥（rustfs-master-key）
3. 启动RustFS：启用KMS功能的RustFS服务器
4. 配置KMS：通过API配置Vault后端，包含：
   • Vault地址和Token认证
   • Transit engine配置
   • 密钥路径设置
5. 功能测试：完整的加密/解密流程测试
6. 清理：终止所有进程

🛠️ 故障排除

常见问题

Q: 测试失败 "RustFS server failed to become ready"

A: 检查端口是否被占用：
lsof -i :9050
kill -9 <PID>  # 如果有进程占用端口

Q: Vault服务启动失败

A: 确保Vault已安装且在PATH中：
which vault
vault version

Q: awscurl认证失败

A: 检查awscurl路径是否正确：
ls /Users/dandan/Library/Python/3.9/bin/awscurl
# 或安装到不同路径：
pip install awscurl
which awscurl  # 然后更新测试中的路径

Q: 测试超时

A: 增加等待时间或检查日志：
RUST_LOG=debug cargo test test_local_kms_end_to_end -- --nocapture

调试技巧

1. 查看详细日志：

   RUST_LOG=rustfs_kms=debug,rustfs=info cargo test -- --nocapture
   

2. 保留临时文件： 修改测试代码，注释掉清理部分，检查生成的配置文件

3. 单步调试： 在测试中添加 std::thread::sleep 来暂停执行，手动检查服务状态

4. 端口检查：

   # 测试运行时检查端口状态
   netstat -an | grep 9050
   curl http://127.0.0.1:9050/minio/health/ready
   

📊 测试覆盖范围

功能覆盖

• ✅ KMS服务动态配置
• ✅ 本地和Vault后端支持
• ✅ AWS S3兼容加密接口
• ✅ 密钥管理和生命周期
• ✅ 错误处理和恢复
• ✅ 高可用性场景

加密模式覆盖

• ✅ SSE-C (Server-Side Encryption with Customer-Provided Keys)
• ✅ SSE-S3 (Server-Side Encryption with S3-Managed Keys)
• ✅ SSE-KMS (Server-Side Encryption with KMS-Managed Keys)

S3操作覆盖

• ✅ 对象上传/下载 (SSE-C模式)
• 🚧 分片上传 (需要AWS SDK兼容性修复)
• 🚧 对象复制 (需要AWS SDK兼容性修复)
• 🚧 Bucket加密配置 (需要AWS SDK兼容性修复)

KMS API覆盖

• ✅ 基础密钥管理 (创建、列表)
• 🚧 完整密钥生命周期 (需要AWS SDK兼容性修复)
• 🚧 直接加密/解密操作 (需要AWS SDK兼容性修复)
• 🚧 数据密钥生成和解密 (需要AWS SDK兼容性修复)
• ✅ KMS服务管理 (配置、启动、停止、状态)

认证方式覆盖

• ✅ Vault Token认证
• 🚧 Vault AppRole认证

🔄 持续集成

这些测试设计为可在CI/CD环境中运行：

# GitHub Actions 示例
- name: Run KMS E2E Tests
  run: |
    # 安装依赖
    sudo apt-get update
    sudo apt-get install -y vault
    pip install awscurl
    
    # 构建并测试
    cargo build
    cd crates/e2e_test
    cargo test kms -- --nocapture --test-threads=1

📚 相关文档

• KMS 配置文档 - KMS功能完整文档
• 动态配置API - REST API接口说明
• 故障排除指南 - 常见问题解决

---

这些测试确保KMS功能的稳定性和可靠性，为生产环境部署提供信心。