RabbitMQ Guard

一个本地运行、完全只读的 RabbitMQ 诊断工具。它把 Management API 数据标准化后，通过透明规则输出“证据、判断、建议和官方依据”。当前不使用 LLM，也不执行任何修复动作。

14 天付费诊断试点

面向自建 RabbitMQ、缺少专职消息中间件 SRE、最近遇到过积压、重复投递、资源告警或集群维护风险的团队。

创始试点报价：人民币 1,999 元 / 14 天 / 1 个集群，正式开始前付款。 当前由个人提供服务，仅接受微信或支付宝个人收款，暂不提供发票；必须对公付款或必须取得发票的团队当前不匹配。

交付内容：

1. 一次客户本机生成的脱敏基线交付包审查。
2. 一份带证据、影响、排查顺序和 RabbitMQ 官方依据的风险报告。
3. 一次 60 分钟技术复盘与整改建议。
4. 一次整改后复测，以及已校验基线/复测包生成的差异报告。
5. 按约定删除试点期间收到的客户伪名化数据。

不包含 24/7 值班、自动修复、代改生产配置、无限咨询、事故赔付或可用性担保。试点开始前需要在私聊中书面确认服务范围、开始日期、付款方式、无发票状态、数据删除日期和取消/退款约定。

提交 14 天付费试点申请。申请表是公开 Issue，不要填写公司内部名称、联系方式、域名、IP、队列名、日志、快照、付款信息、凭据或其他客户数据。匹配后，维护者为申请人创建一个独立私有 GitHub 仓库并邀请其当前账号；双方只在私有 Issue 确认条款和交换微信，不上传客户数据。付款码和支付宝信息只在微信中发送，绝不进入仓库或 Issue。具体流程见 docs/PILOT_OPERATIONS.md。

已包含

• 10 类异常案例和 1 个健康基线，全部明确标注为合成数据
• 内存/磁盘告警、FD 压力、积压、低消费容量、unacked、重复投递、quorum 可用性和连接压力规则
• RabbitMQ Management API 只读采集器
• 使用本地密钥生成稳定伪名的快照脱敏器
• 一条命令生成可校验的客户诊断交付包
• 文本、JSON、Markdown 三种报告格式
• 历史诊断基线对比、整改复测结论和 Markdown 复测报告
• 可批量生成带标签 JSONL 变体的数据生成器
• 本地 RabbitMQ Docker 实验环境

案例依据和限制见 docs/case-catalog.md。

安装与直接试用

从 GitHub Releases 下载 wheel 和 SHA256SUMS，先校验文件，再安装：

shasum -a 256 -c SHA256SUMS
python3 -m pip install ./rabbitmq_guard-0.6.0-py3-none-any.whl

# 不需要 RabbitMQ，直接运行内置合成案例
rabbitmq-guard cases
rabbitmq-guard demo memory_alarm

Release 同时提供 GitHub build provenance attestation。软件按 Apache-2.0 开源；付费的是有明确范围的诊断与复测服务，不是运行本地核心的许可证。

从源码试用无需安装第三方 Python 包：

export PYTHONPATH=src

# 查看案例
python3 -m rabbitmq_guard cases

# 诊断内存告警案例
python3 -m rabbitmq_guard demo memory_alarm

# 生成 Markdown 报告
python3 -m rabbitmq_guard demo \
  redelivery_loop \
  --format markdown \
  --output report.md

# 每种基准案例生成 20 个数值扰动变体
python3 -m rabbitmq_guard generate \
  --count-per-case 20 \
  --output synthetic-dataset.jsonl

开发时也可以安装为 editable 命令：

python3 -m pip install -e .
rabbitmq-guard cases

启动诊断工作台

export PYTHONPATH=src
python3 -m rabbitmq_guard serve --enable-live

打开 http://127.0.0.1:8787。工作台支持演示案例、JSON 快照上传、实时只读连接、历史诊断和 Markdown 报告下载。任意历史记录都可以设为基线；打开同一集群的另一条记录后，工作台会展示新增、已解决和持续风险，并生成整改复测报告。诊断记录保存在 var/rabbitmq-guard.db，实时连接密码只用于当次请求，不写入数据库。

为了避免把带有网络访问能力的接口暴露出去，启用实时连接时服务只允许绑定回环地址。当前版本是本地付费试点工具，不应直接作为公网 SaaS 部署。正式安装默认把历史数据库写到操作系统的用户数据目录；可用 RABBITMQ_GUARD_DATA_DIR 指定其他客户批准的位置。

脱敏后再交付快照

客户不希望共享生产标识符时，可以在本机生成稳定伪名快照。密钥只从环境变量读取，不进入命令参数或输出文件；基线和复测使用同一密钥时，集群、节点、vhost、队列和连接等伪名保持一致。

# 首次生成后存入客户自己的密钥管理系统，后续复测继续使用同一值
export RABBITMQ_GUARD_REDACTION_KEY="$(openssl rand -hex 32)"

# 脱敏已有标准化快照
python3 -m rabbitmq_guard sanitize snapshot.json --output sanitized.json

# 采集时只落盘脱敏结果
python3 -m rabbitmq_guard collect \
  --url http://localhost:15672 \
  --username monitoring-user \
  --sanitize \
  --output sanitized.json

脱敏器会删除案例说明、队列参数和未知字段，并伪名化直接标识符；诊断所需的数值、布尔状态、时间戳和拓扑关系仍会保留。它降低误传客户标识的风险，但不是匿名化，工作负载规模、速率、时间和拓扑数量仍可能敏感。完整边界和共享检查见 docs/PRIVACY.md。

一次生成客户交付包

付费试点不需要手工串联采集、脱敏、诊断和报告。客户可以直接从 RabbitMQ 生成一个固定格式 ZIP；原始快照只在进程内存中存在，不落盘：

export RABBITMQ_PASSWORD='your-password'
export RABBITMQ_GUARD_REDACTION_KEY="$(openssl rand -hex 32)"

python3 -m rabbitmq_guard deliver \
  --url http://localhost:15672 \
  --username monitoring-user \
  --output rabbitmq-guard-delivery.zip

也可以从尚未脱敏的标准化快照生成：

python3 -m rabbitmq_guard deliver \
  --snapshot snapshot.json \
  --output rabbitmq-guard-delivery.zip

接收方校验固定文件清单、SHA-256、脱敏格式、诊断结果和报告一致性：

python3 -m rabbitmq_guard verify-delivery rabbitmq-guard-delivery.zip

整改完成后，客户使用同一脱敏密钥和同一 RabbitMQ Guard 版本生成复测包。顾问可以一条命令校验并比较两次交付，得到新增、已解决和持续风险：

python3 -m rabbitmq_guard compare-deliveries \
  baseline-delivery.zip \
  followup-delivery.zip \
  --output remediation-review.md

需要接入内部流程时可增加 --format json。比较器会在写报告前完整校验两个 ZIP，拒绝相同交付包、不同伪名集群、不同脱敏采集源、不同脱敏密钥或采集时间倒置；报告不会记录输入文件名。

交付包只包含脱敏快照、机器可读诊断结果、Markdown 报告和 manifest，不包含密码、密钥或原始快照。命令输出的整个 ZIP SHA-256 应通过另一个可信渠道发送给接收方核对。该哈希不是数字签名，不能单独证明生成者身份。格式、流程和失败处理见 docs/DELIVERY.md。

连接本地或测试集群

密码只从环境变量读取，不写入快照或命令历史：

export RABBITMQ_PASSWORD='your-password'

# 只采集，保存标准化快照
python3 -m rabbitmq_guard collect \
  --url http://localhost:15672 \
  --username monitoring-user \
  --output snapshot.json

# 采集并立即诊断
python3 -m rabbitmq_guard live \
  --url http://localhost:15672 \
  --username monitoring-user

生产环境建议创建只具备监控权限的专用用户。Management API 适合开发和早期验证；大规模生产采集应迁移到 RabbitMQ 官方推荐的 Prometheus 接口。

本地制造一个真实积压

下面只操作 lab 目录创建的本地容器：

docker compose -f lab/docker-compose.yml up -d
python3 lab/create_no_consumer_backlog.py

export RABBITMQ_PASSWORD='guard-local-only'
python3 -m rabbitmq_guard live \
  --url http://localhost:15673 \
  --username guard

预期会发现 guard.demo.no-consumers 有待处理消息但没有消费者。管理界面地址为 http://localhost:15673。实验环境使用 5673/15673/15693，避免碰到本机已有 RabbitMQ 的默认端口。

测试

make verify
make smoke

项目使用 Pull Request、自动 CI、快速冒烟测试和定期真实 RabbitMQ 集成测试维护。维护规则见 CONTRIBUTING.md 和 docs/MAINTENANCE.md。

设计边界

• 规则输出是诊断线索，不是自动修复授权。
• 单次 Management API 快照不能可靠判断趋势；积压规则因此标记为中等置信度。
• 固定阈值只是 MVP 默认值，必须根据队列业务基线校准。
• 合成案例用于开发和演示，不能替代真实环境的误报/漏报评估。
• 稳定脱敏输出可跨时间关联，不能当作匿名数据公开发布。

付费试点的客户画像、交付范围、价格假设和停止条件见 docs/paid-pilot.md。

社区问题、私密安全报告和付费服务的边界见 SUPPORT.md。