必须分四步：先建vhost（如rabbitmqctl add_vhost /agent_vhost），再建用户（如rabbitmqctl add_user agent_admin 123456），接着设vhost权限（rabbitmqctl set_permissions -p /agent_vhost agent_admin ".*" ".*" ".*"），最后加角色标签（如rabbitmqctl set_user_tags agent_admin management）。
直接创建 vhost 并分配权限，必须分四步走：先建 vhost、再建用户、接着设 vhost 权限、最后加角色标签。漏掉任何一步，连接都会失败或无权限。
用 rabbitmqctl add_vhost 创建虚拟主机
虚拟主机是资源隔离的最小单位，不能省略斜杠前缀（如 /agent_vhost），也不能用空格或特殊字符命名。
- 正确命令：
rabbitmqctl add_vhost /agent_vhost（注意-p参数只在后续权限设置时用，这里不用） - 错误示例：
rabbitmqctl add_vhost agent_vhost→ 会创建名为agent_vhost的 vhost，但 Spring Boot 默认解析virtual-host: /agent_vhost时要求开头有斜杠，实际连接会 fallback 到默认/，导致队列创建失败 - Windows 下若报
Erlang distribution failed，大概率是.erlang.cookie文件不一致，需同步C:\Windows\System32\config\systemprofile\.erlang.cookie和当前用户目录下的该文件
用 rabbitmqctl set_permissions 绑定用户与 vhost 权限
这一步最容易出错：权限不是“赋予用户”，而是“赋予用户在某个 vhost 下的操作能力”，且必须显式指定 -p 参数指向 vhost。
RabbitMQ 4.2.3
下载
RabbitMQ 4.2.3 是 2026 年初发布的重要稳定更新版本，重点修复了 Khepri 元数据存储相关问题，并改进了监控性能。对于使用 Docker、Kubernetes 或微服务架构的开发团队来说，该版本兼容性和稳定性表现较好。
- 命令格式：
rabbitmqctl set_permissions -p /agent_vhost agent_admin ".*" ".*" ".*" - 三个正则参数顺序固定：第一个是
configure（声明/删除 exchange/queue），第二个是write（publish 消息），第三个是read（consume 消息） - 如果只给
"^my-queue$"这类窄匹配，应用启动时自动声明 queue 会失败——因为 Spring AMQP 默认用随机名或带前缀的队列名，需放宽为"^my-.*"或保留".*" - 执行后不会输出成功提示，用
rabbitmqctl list_permissions -p /agent_vhost验证是否生效
用 rabbitmqctl set_user_tags 补充管理角色
角色决定能否登录 Web 控制台或执行集群操作，和 vhost 权限无关，但生产环境通常要配。
-
management标签：能登录:15672界面，查看自己有权限的 vhost 下的 queues/exchanges，但不能删节点或改策略 -
administrator标签：可操作所有 vhost + 全局设置，慎用；普通服务账号建议保持none标签 - 一个用户可同时拥有多个标签，例如：
rabbitmqctl set_user_tags agent_admin management policymaker - 标签修改后立即生效，无需重启服务
Spring Boot 连接时 virtual-host 配置必须带前导斜杠
这是最常被忽略的细节：YAML 中写 virtual-host: /agent_vhost 是对的，写成 virtual-host: agent_vhost 或 virtual-host: "/agent_vhost"（引号内多空格）会导致连接建立在默认 / vhost 上。
- 验证方式：启动日志里出现
amqp://agent_admin@ip:5672//agent_vhost（注意双斜杠）才表示 vhost 生效 - 如果使用 Docker 部署 RabbitMQ，确保
RABBITMQ_DEFAULT_VHOST环境变量没覆盖你的自定义 vhost —— 它只影响默认 vhost 初始化，不影响add_vhost命令 - 防火墙必须放行
5672（AMQP）端口；15672（管理界面）仅用于人工排查，应用运行不依赖它
