yii2-queue Web面板需手动配置路由、模块和权限才能启用，推荐使用devgroup-ua/yii2-queue-monitor；需配置module、url规则、RBAC、CSRF处理及IP白名单，并注意敏感数据泄露风险。
yii2-queue 的 web 面板默认不启用，必须手动配置路由和权限
装完 yii2-queue 后访问 /queue 会直接 404，不是插件没装好，而是它压根没注册路由。官方扩展只提供后台处理逻辑，web 界面是可选模块，得自己拉进来。
实操建议：
- 确认已安装
yiisoft/yii2-queue和配套的yii2-queue-monitor（注意：不是官方主包自带，是第三方维护的常用监控面板，推荐用devgroup-ua/yii2-queue-monitor） - 在
config/web.php的modules中添加：'queue' => [ 'class' => 'devgroup\Yii2\Queue\Monitor\Module', ], - 在
urlManager的rules里补上路由：'queue' => 'queue/default/index',
- 检查 RBAC 或 access rules，
queue/default/index默认需要admin角色；若本地调试，可临时加'allow' => true测试
队列任务不显示、状态始终为 waiting，大概率是监听器没跑或驱动不匹配
页面能打开，但列表空、刷新也没变化，常见原因是任务根本没进队列，或进了但没被消费——web 面板只展示数据库/Redis 中的记录，不负责执行。
实操建议：
- 先确认队列驱动是否与监控模块兼容：
db驱动天然支持完整状态追踪；redis需开启asArray模式且依赖redis的 list + hash 结构，amqp等则基本不支持面板统计 - 运行
./yii queue/listen或./yii queue/run，确保至少有一个 worker 进程在运行（面板不触发执行，只是看结果） - 手动推一个测试任务：
\Yii::$app->queue->push(new \app\jobs\TestJob());
再查数据库queue表是否有新记录、status是否为0（waiting） - 如果任务执行后状态卡在
reserved，可能是 job 类抛异常未被捕获，导致事务回滚，面板就看不到完成态
点击重试/删除按钮没反应，控制台报 403 Forbidden 或 CSRF token mismatch
这是 Yii2 默认安全策略生效了——web 面板的管理操作走 AJAX，但没自动带 CSRF token，尤其在非标准 layout 或 API 模式下容易崩。
实操建议：
- 在
modules.queue.controllerMap中指定控制器并关闭 CSRF 验证（仅限内网环境）：'default' => [ 'class' => 'devgroup\Yii2\Queue\Monitor\controllers\DefaultController', 'enableCsrfValidation' => false, ] - 更稳妥的做法是在 layout 中确保
Yii::$app->request->csrfParam被注入到 JS 全局变量，然后让面板 AJAX 请求带上该 header - 检查
behaviors()里是否误加了全局AccessControl拦截了POST /queue/*路由 - 别用
curl直接调/queue/retry?id=123测试，它依赖 session 和 CSRF，必须走带 cookie 的浏览器请求
生产环境打开监控面板前，必须限制 IP 和关闭 debug 模式
这个面板能查看任务参数、堆栈、原始数据，甚至触发重试/删除——一旦暴露在公网，等于把队列控制台白送给攻击者。
实操建议：
- 在
modules.queue配置中加'ipWhitelist' => ['127.0.0.1', '192.168.10.0/24']（模块本身支持，不用自己写 filter） - 确保
YII_DEBUG为false，否则错误页可能泄露路径、环境变量、数据库配置 - 避免把
queue模块注册在生产config/main.php里，统一放到config/local.php或通过环境变量动态加载 - 如果用了 Nginx，可在 location 层再加一层 IP 限制：
allow 10.0.0.0/8; deny all;
最常被忽略的一点：监控面板的「查看详情」会直接 var_dump job 对象，如果 job 里存了敏感字段（比如 $this->userToken），这些内容会在页面源码里明文出现。别只盯着权限，还得审 job 类的数据结构。
