# fa_queue

**Repository Path**: json_decode/fa_queue

## Basic Information

- **Project Name**: fa_queue
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-27
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Queue Light

适用于 ThinkPHP / FastAdmin 的轻量队列组件，基于 Redis List（`rPush/lPop/lLen`），支持后台可视化管理、命令行调度与 worker 进程管理。

## 功能清单

- 轻量队列：Redis 入队 / 出队 / 长度监控
- 任务管理：启动 / 停止 / 重启 / 删除 / 备注
- 调度管理：`ql:dispatch` 自动补齐 worker 并发
- 进程心跳：在线状态、版本控制、异常退出感知
- FastAdmin 页面：队列状态、按钮操作、任务注册

## 环境要求

- PHP >= 7.4
- `ext-redis`
- ThinkPHP >= 5.1
- 可访问的 Redis 服务

## 安装方式

### 方式 1：Gitee / Git 仓库安装（推荐）

业务项目 `composer.json`：

```json
{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://gitee.com/<your-org>/queue-light.git"
    }
  ],
  "require": {
    "jay/queue-light": "dev-master"
  }
}
```

然后执行 `composer update jay/queue-light`。

### 方式 2：本地 path 联调（开发场景）

业务项目 `composer.json`：

```json
{
  "repositories": [
    {
      "type": "path",
      "url": "packages/queue-light"
    }
  ],
  "require": {
    "jay/queue-light": "*"
  }
}
```

然后执行 `composer update jay/queue-light`。

> Composer 安装后会自动处理包的自动加载，不需要在业务项目里手动加 `QueueLight\\` 的 PSR-4 映射。

安装完成后会自动执行安装脚本（前提：业务项目配置了 composer scripts）：

- 自动写入命令注册（`application/command.php`）
- 自动创建 `application/admin/controller/task/QueueScheduler.php`（仅不存在时）
- 自动发布 FastAdmin 视图与 JS
- 自动创建 `application/extra/queue_light.php`（仅在不存在时）
- 自动发布 `docs/queue_light.sql` 与 `docs/queue_light_usage.md`

推荐在业务项目中加入以下脚本（兼容 vendor 安装与 path 联调）：

```json
{
  "scripts": {
    "post-install-cmd": [
      "[ -f vendor/jay/queue-light/bin/install.php ] && php vendor/jay/queue-light/bin/install.php --project-root=. || ( [ -f packages/queue-light/bin/install.php ] && php packages/queue-light/bin/install.php --project-root=. || true )"
    ],
    "post-update-cmd": [
      "[ -f vendor/jay/queue-light/bin/install.php ] && php vendor/jay/queue-light/bin/install.php --project-root=. || ( [ -f packages/queue-light/bin/install.php ] && php packages/queue-light/bin/install.php --project-root=. || true )"
    ]
  }
}
```

## 配置

在业务项目创建或更新 `application/extra/queue_light.php`：

```php
<?php

use think\Env;

return [
    'seed_from_registry' => false,
    'redis' => [
        'host' => Env::get('queue_light.redis_host', 'redis'),
        'port' => Env::get('queue_light.redis_port', 6379),
        'socket' => Env::get('queue_light.redis_socket', ''),
        'password' => Env::get('queue_light.redis_password', ''),
        'select' => Env::get('queue_light.redis_select', 0),
        'timeout' => Env::get('queue_light.redis_timeout', 1.5),
    ],
    'state_driver' => 'db', // db | redis | file
    'state_prefix' => 'ql:',
    'file_state_path' => RUNTIME_PATH . 'queue_light_state.json',
    'db_task_table' => 'queue_light_task',
    'db_dispatch_table' => 'queue_light_dispatch',
    'dispatch_interval' => 3,
    'heartbeat_interval' => 5,
    'heartbeat_timeout' => 20,
    'idle_sleep_us' => 300000,
    'consume_batch' => 100,
    'auto_die_seconds' => 600,
];
```

`.env` 示例：

```ini
[queue_light]
redis_host = redis
redis_port = 6379
redis_password = 12345678
redis_select = 0
redis_timeout = 1.5
```

## 数据库初始化（`state_driver=db` 时）

执行包内 SQL：

- vendor 安装：`vendor/jay/queue-light/database/queue_light.sql`
- path 联调：`packages/queue-light/database/queue_light.sql`

安装脚本也会同步发布一份到业务项目：`docs/queue_light.sql`。

## 命令使用

- 启动调度器：`php think ql:dispatch`
- 单轮调度：`php think ql:dispatch --once`
- 静默调度：`php think ql:dispatch --quiet`
- 查看状态：`php think ql:status`
- 控制任务：`php think ql:control --action=start --task=all`
- 发布 FastAdmin 资源：`php think ql:publish-fastadmin`

## FastAdmin 页面

访问：

- `task/queue_scheduler/index`

支持：

- 注册队列（队列名、消费者类、并发数、备注）
- 行级操作（启动/停止/重启/删除）
- 全部操作（全部启动/全部停止/全部重启）

## 消费者开发规范

消费者类需实现：

- `QueueLight\Contract\QueueConsumerInterface`

示例：

```php
use QueueLight\Contract\QueueConsumerInterface;

class VerifyHomePage implements QueueConsumerInterface
{
    public function handle($payload): void
    {
        // 处理消息
    }
}
```

## 常见问题排查

- Redis 有数据但不消费：
  - 检查 `php think ql:status` 的 `alive` 是否为 0
  - 确保 `ql:dispatch` 在运行
- Docker 环境连接拒绝：
  - 容器内不要用 `127.0.0.1`，应使用 Redis 服务名（如 `redis`）
  - 校验 `redis_password`
- 命令冲突：
  - 本组件统一使用 `ql:*` 前缀，避免和官方 `queue:*` 混淆

## 详细文档

- 包内文档：`vendor/jay/queue-light/docs/usage.md`（或 path 模式 `packages/queue-light/docs/usage.md`）
- 发布到业务项目后的文档：`docs/queue_light_usage.md`