sdgoij/rustfs
1
0
Fork 0
mirror of https://github.com/rustfs/rustfs.git synced 2026-01-17 01:30:33 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
a26ddf3aaa62ced268603fbb88091b14ace0b3b4
rustfs/docs/README.md
Copilot 6da5766ea2 Implement adaptive buffer sizing with workload profiles - Production-Ready Implementation (#878) 
* Initial plan

* Add workload profiles module with adaptive buffer sizing

Co-authored-by: houseme <4829346+houseme@users.noreply.github.com>

* Add comprehensive adaptive buffer sizing documentation

Co-authored-by: houseme <4829346+houseme@users.noreply.github.com>

* Add implementation summary documentation

Co-authored-by: houseme <4829346+houseme@users.noreply.github.com>

* Implement Phase 2: Opt-In Usage for buffer profiles

- Add RUSTFS_BUFFER_PROFILE_ENABLE and RUSTFS_BUFFER_PROFILE config options
- Implement global buffer configuration with enable/disable flag
- Add WorkloadProfile::from_name() for parsing profile names
- Update put_object, put_object_extract, and upload_part to use opt-in function
- Add init_buffer_profile_system() in main.rs for initialization
- Add comprehensive tests for opt-in functionality
- Update documentation with Phase 2 usage examples

Co-authored-by: houseme <4829346+houseme@users.noreply.github.com>

* Implement Phase 3: Default Enablement for buffer profiles

- Change default to enabled with GeneralPurpose profile
- Replace --buffer-profile-enable with --buffer-profile-disable for opt-out
- Update init_buffer_profile_system() to reflect Phase 3 logic
- Add comprehensive Phase 3 documentation
- Create MIGRATION_PHASE3.md guide for smooth transition
- Add test for Phase 3 default behavior
- Update IMPLEMENTATION_SUMMARY.md to mark Phase 3 as complete

Co-authored-by: houseme <4829346+houseme@users.noreply.github.com>

* Implement Phase 4: Full Integration with deprecated legacy and metrics

- Deprecate get_adaptive_buffer_size() function (backward compatible)
- Implement profile-only buffer sizing in get_buffer_size_opt_in()
- Add performance metrics collection (optional, via metrics feature)
- Even disabled mode now uses GeneralPurpose profile (no hardcoded values)
- Add comprehensive Phase 4 documentation and guide
- Add test_phase4_full_integration() test
- Update IMPLEMENTATION_SUMMARY.md to mark Phase 4 as complete

Co-authored-by: houseme <4829346+houseme@users.noreply.github.com>

* Finalize adaptive buffer sizing: remove deprecated code and improve documentation

English:
- Remove deprecated get_adaptive_buffer_size() function
- Remove deprecated test cases (test_adaptive_buffer_size, Phase 3 legacy comparisons)
- Improve all code comments to be clear and professional English
- Add comprehensive bilingual implementation summary (COMPLETE_SUMMARY.md)
- Update buffer sizing comments in put_object, put_object_extract, upload_part
- Enhance init_buffer_profile_system documentation
- Clean up phase-specific references in comments

Chinese (中文):
- 移除已弃用的 get_adaptive_buffer_size() 函数
- 移除已弃用的测试用例（test_adaptive_buffer_size、Phase 3 旧版比较）
- 改进所有代码注释，使用清晰专业的英文
- 添加全面的双语实现摘要（COMPLETE_SUMMARY.md）
- 更新 put_object、put_object_extract、upload_part 中的缓冲区调整注释
- 增强 init_buffer_profile_system 文档
- 清理注释中的特定阶段引用

This commit completes the adaptive buffer sizing implementation by:
1. Removing all deprecated legacy code and tests
2. Improving code documentation quality
3. Providing comprehensive bilingual summary

本提交完成自适应缓冲区大小实现：
1. 移除所有已弃用的旧代码和测试
2. 提高代码文档质量
3. 提供全面的双语摘要

Co-authored-by: houseme <4829346+houseme@users.noreply.github.com>

* fmt

* fix

* fix

* fix

* fix

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: houseme <4829346+houseme@users.noreply.github.com>
Co-authored-by: houseme <housemecn@gmail.com>
2025-11-18 13:32:02 +08:00

251 lines
8.5 KiB
Markdown
Raw Blame History

# RustFS Documentation Center
Welcome to the RustFS distributed file system documentation center!
## 📚 Documentation Navigation
### ⚡ Performance Optimization
RustFS provides intelligent performance optimization features for different workloads.
| Document | Description | Audience |
|------|------|----------|
| [Adaptive Buffer Sizing](./adaptive-buffer-sizing.md) | Intelligent buffer sizing optimization for optimal performance across workload types | Developers and system administrators |
| [Phase 3 Migration Guide](./MIGRATION_PHASE3.md) | Migration guide from Phase 2 to Phase 3 (Default Enablement) | Operations and DevOps teams |
| [Phase 4 Full Integration Guide](./PHASE4_GUIDE.md) | Complete guide to Phase 4 features: deprecated legacy functions, performance metrics | Advanced users and performance engineers |
| [Performance Testing Guide](./PERFORMANCE_TESTING.md) | Performance benchmarking and optimization guide | Performance engineers |
### 🔐 KMS (Key Management Service)
RustFS KMS delivers enterprise-grade key management and data encryption.
| Document | Description | Audience |
|------|------|----------|
| [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. Deploy KMS in 5 Minutes
**Production (Vault backend)**
```bash
# 1. Enable the Vault feature flag
cargo build --features vault --release
# 2. Configure environment variables
export RUSTFS_VAULT_ADDRESS=https://vault.company.com:8200
export RUSTFS_VAULT_TOKEN=hvs.CAESIJ...
# 3. Launch the service
./target/release/rustfs server
```
**Development & Testing (Local backend)**
```bash
# 1. Build a release binary
cargo build --release
# 2. Configure local storage
export RUSTFS_KMS_BACKEND=Local
export RUSTFS_KMS_LOCAL_KEY_DIR=/tmp/rustfs-keys
# 3. Launch the service
./target/release/rustfs server
```
### 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
### Three-Layer KMS Security Architecture
```
┌─────────────────────────────────────────────────┐
│ Application Layer │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ S3 API │ │ REST API │ │
│ └─────────────┘ └─────────────┘ │
├─────────────────────────────────────────────────┤
│ Encryption Layer │
│ ┌─────────────┐ Encrypt ┌─────────────────┐ │
│ │ Object Data │ ◄──────► │ Data Key (DEK) │ │
│ └─────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────┤
│ Key Management Layer │
│ ┌─────────────────┐ Encrypt ┌──────────────┐ │
│ │ Data Key (DEK) │ ◄───────│ Master Key │ │
│ └─────────────────┘ │ (Vault/HSM) │ │
│ └──────────────┘ │
└─────────────────────────────────────────────────┘
```
### Key Features
- ✅ **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. 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. 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. 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. 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 the repository
git clone https://github.com/your-username/rustfs.git
# 2. Create a documentation branch
git checkout -b docs/improve-kms-guide
# 3. Edit the documentation
# Update Markdown files under docs/kms/
# 4. Commit the changes
git add docs/
git commit -m "docs: improve KMS configuration examples"
# 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
- **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
**Environment**
- RustFS version: v1.0.0
- Operating system: Ubuntu 20.04
- Rust version: 1.75.0
**Issue Description**
Summarize the problem you encountered...
**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 | 🎉 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
### Coming Soon (v1.1.0)
- [ ] 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
**Suggestions for improvement:**
Share specific ideas via GitHub Issues.
---
**Last Updated**: 2024-01-15
**Documentation Version**: v1.0.0
*Thank you for using RustFS! We are committed to delivering the best distributed file system solution.*
Reference in New Issue View Git Blame Copy Permalink