Metadata-Version: 2.4
Name: rmqadm
Version: 0.1.0
Summary: RabbitMQ Management CLI Tool
Author-email: Your Name <your.email@example.com>
Requires-Python: >=3.12
Requires-Dist: fire>=0.7.1
Requires-Dist: requests>=2.32.5
Requires-Dist: rich>=14.3.3
Description-Content-Type: text/markdown

# rmqadm

RabbitMQ 管理命令行工具，基于 [Management HTTP API](https://www.rabbitmq.com/docs/management) 实现，参考 rabbitmqadmin v2 的命令设计，支持多集群配置切换。

## 特性

- 支持配置文件管理多个集群，通过 `-c <name>` 一键切换
- 涵盖用户、vhost、队列、交换机、绑定、策略、权限、健康检查等全部常用操作
- 使用 [rich](https://github.com/Textualize/rich) 渲染彩色表格输出，支持 `--format=json` 输出原始数据
- 基于 Python 3.12+，使用 [uv](https://docs.astral.sh/uv/) 管理依赖

## 安装

```bash
# 克隆仓库
git clone https://github.com/yourname/rmqadm.git
cd rmqadm

# 安装依赖（会自动创建 .venv）
uv sync

# 安装为可执行命令
uv pip install -e .
```

安装后直接使用 `rmqadm`；也可以不安装，用 `uv run rmqadm` 运行。

## Claude Code Skill 安装

本项目提供 Claude Code Skill，让 AI 助手完全掌握 rmqadm 的配置和使用。

### 方法 1：使用 Makefile（推荐）

```bash
# 打包并安装 skill 到 Claude Code
make skill-install

# 仅打包（生成 rmqadm.skill 文件）
make skill-build

# 清理打包产物
make skill-clean
```

### 方法 2：通过 Claude Code 界面

1. 打包 skill：`make skill-build`
2. 打开 Claude Code → 设置 → Skills
3. 点击 "Import Skill"，选择 `rmqadm.skill` 文件

### 方法 3：手动安装

```bash
# 打包
make skill-build

# 解压到 Claude Code 技能目录
mkdir -p ~/.claude/skills
unzip rmqadm.skill -d ~/.claude/skills/rmqadm
```

安装后，当你向 Claude Code 提出 RabbitMQ 管理相关问题时，AI 会自动加载这个技能并提供专业指导。

## 配置文件

默认配置文件路径：`~/.config/rabbitmq/admin.json`

```json
[
  {
    "name": "dev",
    "description": "本地开发环境",
    "host": "localhost",
    "port": 15672,
    "username": "guest",
    "password": "guest",
    "vhost": "/",
    "scheme": "http"
  },
  {
    "name": "prod",
    "description": "生产环境",
    "host": "rmq.example.com",
    "port": 443,
    "username": "admin",
    "password": "your-password",
    "vhost": "/",
    "scheme": "https"
  }
]
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `name` | 是 | 集群别名，用于 `-c` 参数 |
| `description` | 否 | 集群描述，仅展示用 |
| `host` | 是 | Management API 主机地址 |
| `port` | 是 | Management API 端口（HTTP 默认 15672，HTTPS 常用 443） |
| `username` | 是 | 登录用户名 |
| `password` | 是 | 登录密码 |
| `vhost` | 否 | 默认 Virtual Host（默认 `/`） |
| `scheme` | 否 | `http` 或 `https`（默认 `http`） |

## 使用方式

### 全局参数

```
rmqadm [全局参数] <命令组> <子命令> [参数]
```

| 参数 | 简写 | 默认值 | 说明 |
|---|---|---|---|
| `--cluster` | `-c` | — | 集群别名（从配置文件加载） |
| `--host` | `-h` | `localhost` | 手动指定主机 |
| `--port` | | `15672` | 手动指定端口 |
| `--username` | `-u` | `guest` | 手动指定用户名 |
| `--password` | | `guest` | 手动指定密码 |
| `--vhost` | `-v` | `/` | 默认 vhost |
| `--scheme` | `-s` | `http` | 协议：`http` 或 `https` |
| `--profile` | `-p` | `~/.config/rabbitmq/admin.json` | 自定义配置文件路径 |

> `-c` 与手动参数可以混用：`-c prod` 加载配置后，额外传入的参数会覆盖配置文件中的值。

### 查看集群列表

```bash
rmqadm clusters
rmqadm clusters --format=json
```

### 连接示例

```bash
# 推荐：通过配置文件选择集群
rmqadm -c dev users list
rmqadm -c prod vhosts list

# 手动指定连接参数
rmqadm --host localhost --port 15672 --username guest --password guest users list

# 使用自定义配置文件
rmqadm -p /path/to/custom.json -c staging queues list
```

---

## 命令参考

所有列表类命令均支持 `--format=json` 参数输出原始 JSON 数据。

### clusters — 集群配置

```bash
rmqadm clusters                   # 列出所有已配置的集群
rmqadm clusters --format=json     # JSON 格式（密码自动脱敏）
```

### overview — 集群概览

```bash
rmqadm -c dev overview
rmqadm -c dev overview --format=json
```

### users — 用户管理

```bash
rmqadm -c dev users list
rmqadm -c dev users show <name>
rmqadm -c dev users whoami
rmqadm -c dev users create <name> --password=<pwd> --tags=administrator
rmqadm -c dev users delete <name>
```

### vhosts — Virtual Host 管理

```bash
rmqadm -c dev vhosts list
rmqadm -c dev vhosts show <name>
rmqadm -c dev vhosts create <name> --description="my vhost"
rmqadm -c dev vhosts delete <name>
```

### queues — 队列管理

```bash
rmqadm -c dev queues list
rmqadm -c dev queues list --vhost=my-vhost
rmqadm -c dev queues show <name>
rmqadm -c dev queues show <name> --vhost=my-vhost
rmqadm -c dev queues create <name> --durable=true
rmqadm -c dev queues create <name> --queue-type=quorum --vhost=my-vhost
rmqadm -c dev queues purge <name>
rmqadm -c dev queues delete <name>
```

### exchanges — 交换机管理

```bash
rmqadm -c dev exchanges list
rmqadm -c dev exchanges list --vhost=my-vhost
rmqadm -c dev exchanges show <name>
rmqadm -c dev exchanges create <name> --exchange-type=topic
rmqadm -c dev exchanges delete <name>
```

### bindings — 绑定管理

```bash
rmqadm -c dev bindings list
rmqadm -c dev bindings list --vhost=my-vhost
rmqadm -c dev bindings create <exchange> <queue> --routing-key=my.key
rmqadm -c dev bindings delete <exchange> <queue> --routing-key=my.key
```

### streams — Stream 队列管理

```bash
rmqadm -c dev streams list
rmqadm -c dev streams show <name>
rmqadm -c dev streams declare <name> --max-age=7D
rmqadm -c dev streams declare <name> --max-length-bytes=1073741824
rmqadm -c dev streams delete <name>
```

### connections — 连接管理

```bash
rmqadm -c dev connections list
rmqadm -c dev connections show <name>
rmqadm -c dev connections close <name>
rmqadm -c dev connections close <name> --reason="maintenance"
```

### channels — Channel 查看

```bash
rmqadm -c dev channels list
rmqadm -c dev channels show <name>
```

### consumers — 消费者查看

```bash
rmqadm -c dev consumers list
rmqadm -c dev consumers list --vhost=my-vhost
```

### nodes — 节点信息

```bash
rmqadm -c dev nodes list
rmqadm -c dev nodes show rabbit@hostname
```

### permissions — 权限管理

```bash
rmqadm -c dev permissions list
rmqadm -c dev permissions show <user> --vhost=/
rmqadm -c dev permissions set <user> --vhost=/ --configure=".*" --write=".*" --read=".*"
rmqadm -c dev permissions delete <user> --vhost=/
```

### policies — 策略管理

```bash
rmqadm -c dev policies list
rmqadm -c dev policies list --vhost=my-vhost
rmqadm -c dev policies show <name>
rmqadm -c dev policies declare <name> <pattern> <definition> --apply-to=all
# 示例：为所有队列设置 HA 镜像策略
rmqadm -c dev policies declare ha-all ".*" '{"ha-mode":"all"}' --apply-to=queues
rmqadm -c dev policies delete <name>
```

### operator_policies — Operator 策略管理

```bash
rmqadm -c dev operator_policies list
rmqadm -c dev operator_policies declare <name> <pattern> <definition>
rmqadm -c dev operator_policies delete <name>
```

### parameters — 运行时参数

```bash
rmqadm -c dev parameters list
rmqadm -c dev parameters list --component=federation-upstream
rmqadm -c dev parameters set <name> <component> <value>
rmqadm -c dev parameters clear <name> <component>
```

### global_parameters — 全局参数

```bash
rmqadm -c dev global_parameters list
rmqadm -c dev global_parameters set <name> <value>
rmqadm -c dev global_parameters clear <name>
```

### vhost_limits — VHost 资源限制

```bash
rmqadm -c dev vhost_limits list
rmqadm -c dev vhost_limits list --vhost=my-vhost
rmqadm -c dev vhost_limits set max-connections 100 --vhost=my-vhost
rmqadm -c dev vhost_limits set max-queues 500 --vhost=my-vhost
rmqadm -c dev vhost_limits delete max-connections --vhost=my-vhost
```

### user_limits — 用户资源限制

```bash
rmqadm -c dev user_limits list
rmqadm -c dev user_limits list --username=alice
rmqadm -c dev user_limits set alice max-connections 10
rmqadm -c dev user_limits set alice max-channels 50
rmqadm -c dev user_limits delete alice max-connections
```

### definitions — 定义导入/导出

```bash
# 导出集群全量定义（打印到终端）
rmqadm -c dev definitions export

# 导出到文件
rmqadm -c dev definitions export --file=backup.json

# 仅导出指定 vhost 的定义
rmqadm -c dev definitions export --vhost=my-vhost --file=vhost-backup.json

# 从文件导入
rmqadm -c dev definitions import_file --file=backup.json

# 导入到指定 vhost
rmqadm -c dev definitions import_file --file=vhost-backup.json --vhost=my-vhost
```

### health_check — 健康检查

检查失败时返回非零退出码，可集成到监控脚本中。

```bash
rmqadm -c dev health_check local_alarms
rmqadm -c dev health_check cluster_wide_alarms
rmqadm -c dev health_check node_is_quorum_critical
rmqadm -c dev health_check virtual_hosts
rmqadm -c dev health_check port_listener 5672
rmqadm -c dev health_check protocol_listener amqp
```

### feature_flags — Feature Flag 管理

```bash
rmqadm -c dev feature_flags list
rmqadm -c dev feature_flags enable <name>
rmqadm -c dev feature_flags enable_all
```

### rebalance — 队列 Leader 重平衡

```bash
rmqadm -c dev rebalance queues
rmqadm -c dev rebalance queues --vhost=my-vhost
```

---

## 开发

```bash
# 安装依赖
uv sync

# 开发模式运行（���需安装）
uv run rmqadm -c dev users list

# 安装为可编辑模式
uv pip install -e .
```

### 项目结构

```
src/
├── rmqadm/             # Python 包源码
│   ├── cli.py              # 入口，RmqAdm 类，挂载所有命令组
│   ├── client.py           # HTTP 客户端封装
│   ├── config.py           # 配置文件加载（多集群支持）
│   ├── formatter.py        # rich 表格 / JSON 输出
│   └── commands/
│       ├── users.py
│       ├── vhosts.py
│       ├── queues.py
│       ├── exchanges.py
│       ├── bindings.py
│       ├── streams.py
│       ├── connections.py
│       ├── channels.py
│       ├── consumers.py
│       ├── nodes.py
│       ├── permissions.py
│       ├── policies.py
│       ├── operator_policies.py
│       ├── parameters.py   # parameters + global_parameters
│       ├── limits.py       # vhost_limits + user_limits
│       ├── definitions.py
│       ├── health_check.py
│       ├── feature_flags.py
│       └── rebalance.py
└── skills/             # Claude Code Skill 源码
    └── rmqadm/
        ├── SKILL.md            # Skill 主文件
        ├── references/
        │   └── commands.md     # 完整命令参考
        └── assets/
            └── admin.json      # 配置文件模板
```

### Skill 开发

Skill 源码位于 `src/skills/rmqadm/`，修改后重新打包：

```bash
make skill-build
make skill-install
```

## 依赖

## 依赖

| 包 | 用途 |
|---|---|
| [fire](https://github.com/google/python-fire) | 将 Python 类自动映射为 CLI 命令 |
| [requests](https://docs.python-requests.org) | HTTP API 请求 |
| [rich](https://github.com/Textualize/rich) | 终端彩色表格输出 |
