{"id":30833034,"url":"https://github.com/dingdangmaoup/mihomo-rs","last_synced_at":"2026-01-16T15:24:03.824Z","repository":{"id":313131742,"uuid":"1050162169","full_name":"DINGDANGMAOUP/mihomo-rs","owner":"DINGDANGMAOUP","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-05T07:32:46.000Z","size":20016,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-06T16:02:45.223Z","etag":null,"topics":["cil","mihomo","rust","sdk"],"latest_commit_sha":null,"homepage":"https://docs.rs/mihomo-rs","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DINGDANGMAOUP.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-04T03:26:52.000Z","updated_at":"2025-09-05T08:37:07.000Z","dependencies_parsed_at":"2025-09-06T16:02:45.077Z","dependency_job_id":null,"html_url":"https://github.com/DINGDANGMAOUP/mihomo-rs","commit_stats":null,"previous_names":["dingdangmaoup/mihomo-rs"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/DINGDANGMAOUP/mihomo-rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DINGDANGMAOUP%2Fmihomo-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DINGDANGMAOUP%2Fmihomo-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DINGDANGMAOUP%2Fmihomo-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DINGDANGMAOUP%2Fmihomo-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DINGDANGMAOUP","download_url":"https://codeload.github.com/DINGDANGMAOUP/mihomo-rs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DINGDANGMAOUP%2Fmihomo-rs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273927410,"owners_count":25192524,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cil","mihomo","rust","sdk"],"created_at":"2025-09-06T16:02:42.394Z","updated_at":"2025-12-29T03:59:44.255Z","avatar_url":"https://github.com/DINGDANGMAOUP.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mihomo-rs\n\n\u003cdiv align=\"center\"\u003e\n\n[![Crates.io](https://img.shields.io/crates/v/mihomo-rs.svg)](https://crates.io/crates/mihomo-rs)\n[![Documentation](https://docs.rs/mihomo-rs/badge.svg)](https://docs.rs/mihomo-rs)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n[Examples](./examples/) | [API Docs](https://docs.rs/mihomo-rs)\n\nEnglish | [简体中文](README_CN.md)\n\nA Rust SDK and CLI tool for [mihomo](https://github.com/MetaCubeX/mihomo) proxy management with service lifecycle management, configuration handling, and real-time monitoring.\n\n\u003c/div\u003e\n\n---\n\n## Features\n\n- 🔧 **Version Management** - Install, update, and switch between mihomo versions (rustup-like experience)\n- ⚙️ **Configuration Management** - Manage multiple configuration profiles with validation\n- 🚀 **Service Lifecycle** - Start, stop, restart mihomo service with PID management\n- 🔄 **Proxy Operations** - List, switch, and test proxy nodes and groups\n- 📊 **Real-time Monitoring** - Stream logs, traffic statistics, and memory usage\n- 🔌 **Connection Management** - Monitor, filter, and close active connections in real-time\n- 📦 **SDK Library** - Use as a library in your Rust applications\n- 🖥️ **CLI Tool** - Command-line interface for easy management\n\n## Installation\n\n### As a Library\n\nAdd to your `Cargo.toml`:\n\n```toml\n[dependencies]\nmihomo-rs = \"*\"\n```\n\n### As a CLI Tool\n\n```bash\ncargo install mihomo-rs\n```\n\n## Quick Start\n\n### SDK Usage\n\n```rust\nuse mihomo_rs::{Channel, ConfigManager, MihomoClient, ProxyManager, ServiceManager, VersionManager, ConnectionManager, Result};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c()\u003e {\n    // 1. Install mihomo\n    let vm = VersionManager::new()?;\n    vm.install_channel(Channel::Stable).await?;\n\n    // 2. Setup configuration\n    let cm = ConfigManager::new()?;\n    cm.ensure_default_config().await?;\n    let controller_url = cm.ensure_external_controller().await?;\n\n    // 3. Start service\n    let binary = vm.get_binary_path(None).await?;\n    let config = cm.get_current_path().await?;\n    let sm = ServiceManager::new(binary, config);\n    sm.start().await?;\n\n    // 4. Use proxy manager\n    let client = MihomoClient::new(\u0026controller_url, None)?;\n    let pm = ProxyManager::new(client.clone());\n\n    // List proxy groups\n    let groups = pm.list_groups().await?;\n    for group in groups {\n        println!(\"{}: {} ({})\", group.name, group.now, group.group_type);\n    }\n\n    // Switch proxy\n    pm.switch(\"GLOBAL\", \"proxy-name\").await?;\n\n    // 5. Monitor connections\n    let conn_mgr = ConnectionManager::new(client.clone());\n\n    // List active connections\n    let connections = conn_mgr.list().await?;\n    println!(\"Active connections: {}\", connections.len());\n\n    // Filter connections by host\n    let filtered = conn_mgr.filter_by_host(\"example.com\").await?;\n\n    // Close specific connection\n    if let Some(conn) = connections.first() {\n        conn_mgr.close(\u0026conn.id).await?;\n    }\n\n    // 6. Stream real-time traffic\n    let mut traffic_rx = client.stream_traffic().await?;\n    while let Some(traffic) = traffic_rx.recv().await {\n        println!(\"Upload: {} KB/s, Download: {} KB/s\",\n            traffic.up / 1024, traffic.down / 1024);\n    }\n\n    Ok(())\n}\n```\n\n### CLI Usage\n\n```bash\n# Install mihomo\nmihomo-rs install stable\n\n# Start service\nmihomo-rs start\n\n# List proxies\nmihomo-rs proxy list\n\n# Switch proxy\nmihomo-rs proxy switch GLOBAL proxy-name\n\n# Stream logs (with level filter)\nmihomo-rs logs --level info\n\n# Stream traffic statistics\nmihomo-rs traffic\n\n# Show memory usage\nmihomo-rs memory\n\n# List active connections\nmihomo-rs connection list\n\n# Show connection statistics\nmihomo-rs connection stats\n\n# Stream connections in real-time\nmihomo-rs connection stream\n\n# Close specific connection\nmihomo-rs connection close \u003cconnection-id\u003e\n\n# Close all connections\nmihomo-rs connection close-all --force\n```\n\n## Examples\n\nThe [examples/](./examples/) directory includes comprehensive examples:\n\n### Quick Start\n- [hello_mihomo.rs](./examples/hello_mihomo.rs) - Minimal example\n- [basic_workflow.rs](./examples/basic_workflow.rs) - Complete beginner workflow\n\n### Version Management\n- [install_version.rs](./examples/install_version.rs) - Install specific version\n- [install_by_channel.rs](./examples/install_by_channel.rs) - Install from channel\n- [list_versions.rs](./examples/list_versions.rs) - List installed versions\n- [manage_versions.rs](./examples/manage_versions.rs) - Version lifecycle\n\n### Configuration\n- [manage_profiles.rs](./examples/manage_profiles.rs) - Profile management\n- [custom_config.rs](./examples/custom_config.rs) - Custom configuration\n- [external_controller.rs](./examples/external_controller.rs) - Controller setup\n\n### Service Management\n- [service_lifecycle.rs](./examples/service_lifecycle.rs) - Start/stop/restart\n- [service_status.rs](./examples/service_status.rs) - Check status\n- [auto_restart.rs](./examples/auto_restart.rs) - Auto-restart logic\n\n### Proxy Operations\n- [list_proxies.rs](./examples/list_proxies.rs) - List all proxies\n- [list_groups.rs](./examples/list_groups.rs) - List proxy groups\n- [switch_proxy.rs](./examples/switch_proxy.rs) - Switch proxy\n- [test_delay.rs](./examples/test_delay.rs) - Test latency\n- [current_proxy.rs](./examples/current_proxy.rs) - Current selections\n\n### Monitoring\n- [stream_logs.rs](./examples/stream_logs.rs) - Real-time logs\n- [stream_logs_filtered.rs](./examples/stream_logs_filtered.rs) - Filtered logs\n- [stream_traffic.rs](./examples/stream_traffic.rs) - Traffic monitoring\n- [memory_usage.rs](./examples/memory_usage.rs) - Memory usage\n\n### Connection Management\n- [list_connections.rs](./examples/list_connections.rs) - List active connections with filtering\n- [close_connections.rs](./examples/close_connections.rs) - Close connections by ID, host, or process\n- [stream_connections.rs](./examples/stream_connections.rs) - Real-time connection monitoring\n\n### Advanced\n- [custom_home_dir.rs](./examples/custom_home_dir.rs) - Custom home directory\n- [complete_workflow.rs](./examples/complete_workflow.rs) - Full application\n- [error_handling.rs](./examples/error_handling.rs) - Error patterns\n- [concurrent_operations.rs](./examples/concurrent_operations.rs) - Parallel ops\n\n### Integration\n- [first_time_setup.rs](./examples/first_time_setup.rs) - First-time setup\n- [migration_helper.rs](./examples/migration_helper.rs) - Migration guide\n\nRun any example with:\n```bash\ncargo run --example hello_mihomo\n```\n\nSee [examples/README.md](./examples/README.md) for detailed documentation.\n\n## Architecture\n\n```\nmihomo-rs/\n├── src/\n│   ├── core/           # Core HTTP/WebSocket client and types\n│   │   ├── client.rs   # MihomoClient (HTTP + WebSocket)\n│   │   ├── types.rs    # Data structures\n│   │   ├── error.rs    # Error types\n│   │   ├── port.rs     # Port utilities\n│   │   └── home.rs     # Home directory management\n│   ├── version/        # Version management\n│   │   ├── manager.rs  # VersionManager\n│   │   ├── channel.rs  # Channel (Stable/Beta/Nightly)\n│   │   └── download.rs # Binary downloader\n│   ├── config/         # Configuration management\n│   │   ├── manager.rs  # ConfigManager\n│   │   └── profile.rs  # Profile struct\n│   ├── service/        # Service lifecycle\n│   │   ├── manager.rs  # ServiceManager\n│   │   └── process.rs  # Process utilities\n│   ├── proxy/          # Proxy operations\n│   │   ├── manager.rs  # ProxyManager\n│   │   └── test.rs     # Delay testing\n│   ├── connection/     # Connection management\n│   │   └── manager.rs  # ConnectionManager\n│   └── cli/            # CLI application\n├── examples/           # 31 comprehensive examples\n└── tests/              # Integration tests\n```\n\n## API Overview\n\n### Main Modules\n\n| Module | Description |\n|--------|-------------|\n| `MihomoClient` | HTTP/WebSocket client for mihomo API |\n| `VersionManager` | Install and manage mihomo versions |\n| `ConfigManager` | Manage configuration profiles |\n| `ServiceManager` | Control service lifecycle |\n| `ProxyManager` | High-level proxy operations |\n| `ConnectionManager` | Monitor and manage active connections |\n\n### Key Types\n\n| Type | Description |\n|------|-------------|\n| `Version` | Mihomo version information |\n| `ProxyNode` | Individual proxy node |\n| `ProxyGroup` | Proxy group (Selector, URLTest, etc.) |\n| `TrafficData` | Upload/download statistics |\n| `MemoryData` | Memory usage information |\n| `Channel` | Release channel (Stable/Beta/Nightly) |\n| `Connection` | Active connection information |\n| `ConnectionSnapshot` | Real-time connections snapshot |\n| `ConnectionMetadata` | Connection metadata (source, destination, process, etc.) |\n\n### Top-level Functions\n\n```rust\n// Convenience functions for common operations\nuse mihomo_rs::{install_mihomo, start_service, stop_service, switch_proxy};\n\n// Install mihomo\ninstall_mihomo(None).await?; // Latest stable\n\n// Service management\nstart_service(\u0026config_path).await?;\nstop_service(\u0026config_path).await?;\n\n// Proxy switching\nswitch_proxy(\"GLOBAL\", \"proxy-name\").await?;\n```\n\n## Configuration\n\n### Default Locations\n\nmihomo-rs stores data in `~/.config/mihomo-rs/` (or `$MIHOMO_HOME`):\n\n```\n~/.config/mihomo-rs/\n├── versions/           # Installed mihomo binaries\n│   ├── v1.18.0/\n│   └── v1.18.9/\n├── configs/            # Configuration profiles\n│   ├── default.yaml\n│   └── custom.yaml\n├── config.toml         # mihomo-rs settings\n└── mihomo.pid          # Service PID file\n```\n\n### Custom Home Directory\n\nSet via environment variable:\n\n```bash\nexport MIHOMO_HOME=/custom/path\n```\n\nOr programmatically:\n\n```rust\nuse mihomo_rs::{VersionManager, ConfigManager};\nuse std::path::PathBuf;\n\nlet home = PathBuf::from(\"/custom/path\");\nlet vm = VersionManager::with_home(home.clone())?;\nlet cm = ConfigManager::with_home(home)?;\n```\n\n### Example Configuration\n\n```yaml\n# ~/.config/mihomo-rs/configs/default.yaml\nport: 7890\nsocks-port: 7891\nallow-lan: false\nmode: rule\nlog-level: info\nexternal-controller: 127.0.0.1:9090\n\nproxies:\n  - name: \"proxy1\"\n    type: ss\n    server: server.example.com\n    port: 443\n    cipher: aes-256-gcm\n    password: password\n\nproxy-groups:\n  - name: \"GLOBAL\"\n    type: select\n    proxies:\n      - proxy1\n```\n\n## Development\n\n### Building from Source\n\n```bash\ngit clone https://github.com/DINGDANGMAOUP/mihomo-rs\ncd mihomo-rs\ncargo build --release\n```\n\n### Running Tests\n\n```bash\ncargo test\n```\n\n### Running Examples\n\n```bash\n# Enable logging for debugging\nRUST_LOG=debug cargo run --example basic_workflow\n```\n\n## Use Cases\n\n### 1. System Administrators\n- Automate mihomo deployment and updates\n- Monitor multiple mihomo instances\n- Centralized configuration management\n\n### 2. Application Developers\n- Integrate proxy management into applications\n- Real-time traffic monitoring\n- Programmatic proxy switching\n\n### 3. Power Users\n- Manage multiple mihomo versions\n- Quick proxy testing and switching\n- Custom automation scripts\n\n### 4. CI/CD Pipelines\n- Automated testing with proxies\n- Isolated test environments\n- Version-specific testing\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n1. Install Rust (1.70+)\n2. Clone the repository\n3. Run tests: `cargo test`\n4. Run clippy: `cargo clippy`\n5. Format code: `cargo fmt`\n\n## License\n\nMIT License - see [LICENSE](./LICENSE) for details.\n\n## Related Projects\n\n- [mihomo](https://github.com/MetaCubeX/mihomo) - Mihomo\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdingdangmaoup%2Fmihomo-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdingdangmaoup%2Fmihomo-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdingdangmaoup%2Fmihomo-rs/lists"}