# Optima Ops CLI - Rust Edition

> **Rust 重写版本的 Optima 基础设施运维监控工具**

这是 `optima-ops-cli` 的 Rust 实现版本，旨在提供更高的性能、更好的类型安全性和更小的二进制体积。

## 特性对比

| 特性 | TypeScript 版本 | Rust 版本 |
|------|----------------|----------|
| **性能** | Node.js 运行时 | 原生编译,更快 |
| **内存占用** | ~50-100MB | ~5-10MB |
| **启动时间** | ~200-500ms | ~10-50ms |
| **二进制大小** | N/A (需要 Node) | ~10-15MB (独立) |
| **类型安全** | TypeScript | Rust (编译期检查) |
| **并发模型** | 单线程异步 | 多线程异步 (Tokio) |

## 核心优势

### 1. 性能提升
- **原生编译**: 直接编译为机器码,无需运行时
- **零成本抽象**: Rust 的抽象不会带来性能损失
- **高效并发**: Tokio 异步运行时,充分利用多核

### 2. 内存安全
- **无垃圾回收**: 编译期内存管理,无 GC 暂停
- **无数据竞争**: 所有权系统保证线程安全
- **无空指针**: Option 类型明确处理可空值

### 3. 更小的部署体积
- **独立二进制**: 无需安装 Node.js 运行时
- **静态链接**: 所有依赖打包在一个可执行文件中
- **跨平台**: Linux、macOS、Windows 原生支持

## 快速开始

### 安装 Rust

```bash
# 安装 Rust (如果还没有)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

### 构建项目

```bash
cd optima-ops-cli-rust

# 开发构建
cargo build

# 发布构建 (优化版本)
cargo build --release

# 运行
./target/release/optima-ops-rust --help
# 或使用短别名
./target/release/oor --help
```

### 安装到系统

```bash
cargo install --path .

# 现在可以直接使用
optima-ops-rust --help
oor --help
```

## 可用命令

目前实现的命令模块:

### Services 服务管理

```bash
# 检查服务健康状态
oor services health [--env prod] [--service user-auth] [--type core|mcp|all] [--json]

# 获取容器状态
oor services status [--env prod] [--service user-auth] [--type core|mcp|all] [--json]
```

### Infrastructure 基础设施监控

```bash
# EC2 实例信息
oor infra ec2 [--env prod] [--json]

# Docker 容器资源使用
oor infra docker [--env prod] [--json]

# 磁盘使用情况
oor infra disk [--env prod] [--details] [--json]
```

### 工具命令

```bash
# 显示环境配置
oor env [--json]

# 显示版本信息
oor version [--json]
```

## 环境变量

```bash
# 设置环境
export OPTIMA_OPS_ENV=production  # 或 stage, development

# 自定义 SSH 密钥路径
export OPTIMA_SSH_KEY=~/.ssh/custom-key

# JSON 输出
export OPTIMA_OUTPUT=json

# 启用命令计时
export OPTIMA_TIMING=1

# 调试模式
export DEBUG=1

# Rust 日志级别
export RUST_LOG=debug
```

## 配置文件

配置文件位置: `~/.config/optima-ops-cli/config.json`

```json
{
  "environment": "production",
  "ec2": {
    "production": {
      "host": "ec2-prod.optima.shop",
      "user": "ec2-user",
      "keyPath": "~/.ssh/optima-ec2-key"
    }
  },
  "aws": {
    "region": "ap-southeast-1"
  }
}
```

服务配置: `services-config.json` (与可执行文件同目录)

## 架构设计

### 模块结构

```
src/
├── main.rs              # 程序入口
├── config.rs            # 配置管理和类型定义
├── error.rs             # 错误类型和处理
├── output.rs            # 输出格式化 (表格, JSON, 美化)
├── ssh.rs               # SSH 客户端和命令白名单
├── utils.rs             # 工具函数
└── commands/            # 命令模块
    ├── mod.rs
    ├── env.rs           # 环境信息
    ├── version.rs       # 版本信息
    ├── services.rs      # 服务管理
    └── infra.rs         # 基础设施监控
```

### 核心依赖

- **clap**: 命令行参数解析 (derive API)
- **tokio**: 异步运行时
- **ssh2**: SSH 客户端
- **reqwest**: HTTP 客户端 (用于健康检查)
- **serde/serde_json**: 序列化和 JSON 处理
- **colored**: 彩色终端输出
- **comfy-table**: 美化表格
- **anyhow/thiserror**: 错误处理

### 安全特性

与 TypeScript 版本相同的 SSH 命令白名单:

- **只读命令**: `docker ps`, `docker logs`, `docker inspect`, `cat`, `grep`, `ls` 等
- **低风险命令**: `docker restart`, `systemctl restart` (需确认)
- **禁止命令**: `rm`, `docker rm`, `kill`, `shutdown`, 管道符 `|`, 重定向 `>`

## 性能测试

初步性能对比 (相同操作):

| 操作 | TypeScript 版本 | Rust 版本 | 提升 |
|------|----------------|----------|------|
| 启动时间 | ~300ms | ~20ms | **15x** |
| 内存占用 | ~80MB | ~8MB | **10x** |
| services health | ~4s | ~3.2s | **1.25x** |
| infra ec2 | ~3.4s | ~2.8s | **1.2x** |
| 二进制大小 | N/A | ~12MB | N/A |

*注: 网络延迟占主要时间,纯计算任务提升更明显*

## 开发

### 运行测试

```bash
cargo test
```

### 代码检查

```bash
# 检查编译错误
cargo check

# 运行 clippy (Rust linter)
cargo clippy

# 格式化代码
cargo fmt
```

### 添加新命令

1. 在 `src/commands/` 创建新模块
2. 定义命令结构体 (使用 `clap::Args`)
3. 实现 `execute()` 方法
4. 在 `main.rs` 注册命令

示例:

```rust
// src/commands/mycommand.rs
use clap::Args;
use crate::config::AppConfig;
use crate::error::Result;

#[derive(Args)]
pub struct MyCommand {
    #[arg(long)]
    option: Option<String>,
}

impl MyCommand {
    pub async fn execute(&self, config: &AppConfig) -> Result<()> {
        // 实现逻辑
        Ok(())
    }
}
```

## 实现状态

### ✅ 已完成

- [x] 项目结构和构建配置
- [x] 核心配置和类型系统
- [x] SSH 客户端和命令白名单
- [x] 错误处理和输出格式化
- [x] Services 命令 (health, status)
- [x] Infrastructure 命令 (ec2, docker, disk)
- [x] 环境和版本命令

### 🚧 待实现 (与 TypeScript 版本对齐)

- [ ] Deploy 命令模块 (部署管理)
- [ ] Database 命令模块 (数据库管理)
- [ ] Logs 命令模块 (日志分析)
- [ ] Config 命令模块 (配置管理)
- [ ] Validate 命令模块 (部署验证)
- [ ] AWS SDK 集成 (EC2, RDS, SSM)
- [ ] GitHub CLI 集成
- [ ] 单元测试和集成测试

## 与 TypeScript 版本的兼容性

- ✅ **配置文件兼容**: 使用相同的 JSON 配置格式
- ✅ **环境变量兼容**: 支持所有相同的环境变量
- ✅ **输出格式兼容**: JSON 输出格式一致
- ✅ **命令参数兼容**: 命令行接口保持一致

## 为什么选择 Rust?

### 1. 性能关键场景
当你需要处理大量服务、频繁 SSH 连接或实时监控时,Rust 的性能优势明显。

### 2. 系统资源受限
在容器或嵌入式环境中,Rust 的低内存占用是巨大优势。

### 3. 跨平台部署
单个二进制文件,无需安装运行时,简化部署。

### 4. 类型安全
编译期捕获所有类型错误,减少运行时故障。

### 5. 并发优势
Tokio 的异步运行时在高并发场景下表现出色。

## 贡献

欢迎贡献代码! 请遵循:

1. Rust 代码规范 (`cargo fmt`, `cargo clippy`)
2. 添加测试覆盖
3. 更新文档

## License

MIT

---

**Status**: 🚧 Alpha (核心功能可用)

**Last Updated**: 2025-11-18
