gsadmin/rustfs
1
0
Fork 0
mirror of https://github.com/rustfs/rustfs.git synced 2026-08-31 09:18:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: simplify crates README files and enforce PR-only workflow (#110)

Browse Source 
* docs: simplify all crates README files

- Remove extensive code examples and detailed documentation
- Convert to minimal module introductions with core feature lists
- Direct users to main RustFS repository for comprehensive docs
- Updated 20 crate README files for consistency and brevity

Files updated:
- crates/rio/README.md (415→15 lines)
- crates/s3select-api/README.md (592→15 lines)
- crates/s3select-query/README.md (658→15 lines)
- crates/signer/README.md (407→15 lines)
- crates/utils/README.md (395→15 lines)
- crates/workers/README.md (463→15 lines)
- crates/zip/README.md (408→15 lines)

* docs: restore original headers in crates README files

- Add back RustFS logo image and CI badges
- Restore formatted headers and structured layout
- Keep simplified content with module introductions
- Maintain consistent documentation structure across all crates

All 20 crate README files now have proper headers while keeping
the simplified content that directs users to the main repository.

* rules: enforce PR-only workflow for main branch

- Strengthen rule that ALL changes must go through pull requests
- Explicitly forbid direct commits to main branch under any circumstances
- Add comprehensive PR requirements and enforcement guidelines
- Clarify that PRs are the ONLY way to merge to main branch
- Add requirement for PR approval before merging
- Include enforcement mechanisms for branch protection
This commit is contained in:
安正超
2025-07-08 21:10:07 +08:00
committed by GitHub
parent 49f480d346
commit 3dbcaaa221
22 changed files with 227 additions and 8348 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/madmin/README.md
+10 -324
View File
@@ -3,7 +3,7 @@
# RustFS MadAdmin - Administrative Interface
<p align="center">
<strong>Administrative interface and management APIs for RustFS distributed object storage</strong>
<strong>Advanced administrative interface and management tools for RustFS distributed object storage</strong>
</p>
<p align="center">
@@ -17,335 +17,21 @@
## 📖 Overview
**RustFS MadAdmin** provides comprehensive administrative interfaces and management APIs for the [RustFS](https://rustfs.com) distributed object storage system. It enables cluster management, monitoring, configuration, and administrative operations through both programmatic APIs and interactive interfaces.
> **Note:** This is a core submodule of RustFS that provides essential administrative capabilities for the distributed object storage system. For the complete RustFS experience, please visit the [main RustFS repository](https://github.com/rustfs/rustfs).
**RustFS MadAdmin** provides advanced administrative interface and management tools for the [RustFS](https://rustfs.com) distributed object storage system. For the complete RustFS experience, please visit the [main RustFS repository](https://github.com/rustfs/rustfs).
## ✨ Features
### 🎛️ Cluster Management
- **Node Management**: Add, remove, and monitor cluster nodes
- **Service Discovery**: Automatic service discovery and registration
- **Load Balancing**: Distribute load across cluster nodes
- **Health Monitoring**: Real-time cluster health monitoring
### 📊 System Monitoring
- **Performance Metrics**: CPU, memory, disk, and network metrics
- **Storage Analytics**: Capacity planning and usage analytics
- **Alert Management**: Configurable alerts and notifications
- **Dashboard Interface**: Web-based monitoring dashboard
### ⚙️ Configuration Management
- **Dynamic Configuration**: Runtime configuration updates
- **Policy Management**: Access control and bucket policies
- **User Management**: User and group administration
- **Backup Configuration**: Backup and restore settings
### 🔧 Administrative Operations
- **Data Migration**: Cross-cluster data migration
- **Healing Operations**: Data integrity repair and healing
- **Rebalancing**: Storage rebalancing operations
- **Maintenance Mode**: Graceful maintenance operations
## 📦 Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
rustfs-madmin = "0.1.0"
```
## 🔧 Usage
### Basic Admin Client
```rust
use rustfs_madmin::{AdminClient, AdminConfig, ServerInfo};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create admin client
let config = AdminConfig {
endpoint: "https://admin.rustfs.local:9001".to_string(),
access_key: "admin".to_string(),
secret_key: "password".to_string(),
region: "us-east-1".to_string(),
};
let client = AdminClient::new(config).await?;
// Get server information
let server_info = client.server_info().await?;
println!("Server Version: {}", server_info.version);
println!("Uptime: {}", server_info.uptime);
Ok(())
}
```
### Cluster Management
```rust
use rustfs_madmin::{AdminClient, AddServerRequest, RemoveServerRequest};
async fn cluster_management(client: &AdminClient) -> Result<(), Box<dyn std::error::Error>> {
// List cluster nodes
let nodes = client.list_servers().await?;
for node in nodes {
println!("Node: {} - Status: {}", node.endpoint, node.state);
}
// Add new server to cluster
let add_request = AddServerRequest {
endpoint: "https://new-node.rustfs.local:9000".to_string(),
access_key: "node-key".to_string(),
secret_key: "node-secret".to_string(),
};
client.add_server(add_request).await?;
println!("New server added successfully");
// Remove server from cluster
let remove_request = RemoveServerRequest {
endpoint: "https://old-node.rustfs.local:9000".to_string(),
};
client.remove_server(remove_request).await?;
println!("Server removed successfully");
Ok(())
}
```
### System Monitoring
```rust
use rustfs_madmin::{AdminClient, MetricsRequest, AlertConfig};
async fn monitoring_operations(client: &AdminClient) -> Result<(), Box<dyn std::error::Error>> {
// Get system metrics
let metrics = client.get_metrics(MetricsRequest::default()).await?;
println!("CPU Usage: {:.2}%", metrics.cpu_usage);
println!("Memory Usage: {:.2}%", metrics.memory_usage);
println!("Disk Usage: {:.2}%", metrics.disk_usage);
// Get storage information
let storage_info = client.storage_info().await?;
println!("Total Capacity: {} GB", storage_info.total_capacity / 1024 / 1024 / 1024);
println!("Used Capacity: {} GB", storage_info.used_capacity / 1024 / 1024 / 1024);
// Configure alerts
let alert_config = AlertConfig {
name: "high-cpu-usage".to_string(),
condition: "cpu_usage > 80".to_string(),
notification_endpoint: "https://webhook.example.com/alerts".to_string(),
enabled: true,
};
client.set_alert_config(alert_config).await?;
Ok(())
}
```
### User and Policy Management
```rust
use rustfs_madmin::{AdminClient, UserInfo, PolicyDocument};
async fn user_management(client: &AdminClient) -> Result<(), Box<dyn std::error::Error>> {
// Create user
let user_info = UserInfo {
access_key: "user123".to_string(),
secret_key: "user-secret".to_string(),
status: "enabled".to_string(),
policy: Some("readwrite-policy".to_string()),
};
client.add_user("new-user", user_info).await?;
// List users
let users = client.list_users().await?;
for (username, info) in users {
println!("User: {} - Status: {}", username, info.status);
}
// Set user policy
let policy_doc = PolicyDocument {
version: "2012-10-17".to_string(),
statement: vec![/* policy statements */],
};
client.set_user_policy("new-user", policy_doc).await?;
Ok(())
}
```
### Data Operations
```rust
use rustfs_madmin::{AdminClient, HealRequest, RebalanceRequest};
async fn data_operations(client: &AdminClient) -> Result<(), Box<dyn std::error::Error>> {
// Start healing operation
let heal_request = HealRequest {
bucket: Some("important-bucket".to_string()),
prefix: Some("documents/".to_string()),
recursive: true,
dry_run: false,
};
let heal_result = client.heal(heal_request).await?;
println!("Healing started: {}", heal_result.heal_sequence);
// Check healing status
let heal_status = client.heal_status(&heal_result.heal_sequence).await?;
println!("Healing progress: {:.2}%", heal_status.progress);
// Start rebalancing
let rebalance_request = RebalanceRequest {
servers: vec![], // Empty means all servers
};
client.start_rebalance(rebalance_request).await?;
println!("Rebalancing started");
Ok(())
}
```
### Configuration Management
```rust
use rustfs_madmin::{AdminClient, ConfigUpdate, NotificationTarget};
async fn configuration_management(client: &AdminClient) -> Result<(), Box<dyn std::error::Error>> {
// Get current configuration
let config = client.get_config().await?;
println!("Current config version: {}", config.version);
// Update configuration
let config_update = ConfigUpdate {
region: Some("us-west-2".to_string()),
browser: Some(true),
compression: Some(true),
// ... other config fields
};
client.set_config(config_update).await?;
// Configure notification targets
let notification_target = NotificationTarget {
arn: "arn:aws:sns:us-east-1:123456789012:my-topic".to_string(),
target_type: "webhook".to_string(),
endpoint: "https://webhook.example.com/notifications".to_string(),
};
client.set_notification_target("bucket1", notification_target).await?;
Ok(())
}
```
## 🏗️ Architecture
### MadAdmin Architecture
```
MadAdmin Architecture:
┌─────────────────────────────────────────────────────────────┐
│ Admin API Layer │
├─────────────────────────────────────────────────────────────┤
│ Cluster Mgmt │ Monitoring │ User Management │
├─────────────────────────────────────────────────────────────┤
│ Data Ops │ Config Mgmt │ Notification │
├─────────────────────────────────────────────────────────────┤
│ HTTP/gRPC Client Layer │
├─────────────────────────────────────────────────────────────┤
│ Storage System Integration │
└─────────────────────────────────────────────────────────────┘
```
### Administrative Operations
| Category | Operations | Description |
|----------|------------|-------------|
| Cluster | Add/Remove nodes, Health checks | Cluster management |
| Monitoring | Metrics, Alerts, Dashboard | System monitoring |
| Data | Healing, Rebalancing, Migration | Data operations |
| Config | Settings, Policies, Notifications | Configuration |
| Users | Authentication, Authorization | User management |
## 🧪 Testing
Run the test suite:
```bash
# Run all tests
cargo test
# Test admin operations
cargo test admin_ops
# Test cluster management
cargo test cluster
# Test monitoring
cargo test monitoring
```
## 📋 Requirements
- **Rust**: 1.70.0 or later
- **Platforms**: Linux, macOS, Windows
- **Network**: Administrative access to RustFS cluster
- **Permissions**: Administrative credentials required
## 🌍 Related Projects
This module is part of the RustFS ecosystem:
- [RustFS Main](https://github.com/rustfs/rustfs) - Core distributed storage system
- [RustFS IAM](../iam) - Identity and access management
- [RustFS Policy](../policy) - Policy engine
- [RustFS Common](../common) - Common types and utilities
- Comprehensive cluster management and monitoring
- Real-time performance metrics and analytics
- Automated backup and disaster recovery tools
- User and permission management interface
- System health monitoring and alerting
- Configuration management and deployment tools
## 📚 Documentation
For comprehensive documentation, visit:
- [RustFS Documentation](https://docs.rustfs.com)
- [MadAdmin API Reference](https://docs.rustfs.com/madmin/)
- [Administrative Guide](https://docs.rustfs.com/admin/)
## 🔗 Links
- [Documentation](https://docs.rustfs.com) - Complete RustFS manual
- [Changelog](https://github.com/rustfs/rustfs/releases) - Release notes and updates
- [GitHub Discussions](https://github.com/rustfs/rustfs/discussions) - Community support
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](https://github.com/rustfs/rustfs/blob/main/CONTRIBUTING.md) for details.
For comprehensive documentation, examples, and usage guides, please visit the main [RustFS repository](https://github.com/rustfs/rustfs).
## 📄 License
Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/rustfs/rustfs/blob/main/LICENSE) for details.
---
<p align="center">
<strong>RustFS</strong> is a trademark of RustFS, Inc.<br>
All other trademarks are the property of their respective owners.
</p>
<p align="center">
Made with 🎛️ by the RustFS Team
</p>
This project is licensed under the Apache License 2.0 - see the [LICENSE](../../LICENSE) file for details.