lizhuoran
599a917246
- 创建 QUEUE_SETUP.md 文档 - 说明队列系统的配置和使用方法 - 解释文档转换状态问题的原因 - 提供开发环境和生产环境的配置方案 - 包含常见问题和解决方案 - 说明如何使用 Supervisor 管理队列 - 说明如何使用 composer run dev 启动服务
205 lines
4.4 KiB
Markdown
205 lines
4.4 KiB
Markdown
# 队列系统设置指南
|
||
|
||
## 概述
|
||
|
||
本系统使用 Laravel 队列系统处理异步任务，包括：
|
||
- 文档转换（Word/Excel/PDF 转 Markdown）
|
||
- 终端配置同步
|
||
- 其他后台任务
|
||
|
||
## 重要说明
|
||
|
||
### 文档转换状态说明
|
||
|
||
如果看到文档转换状态一直是"等待转换"或"处理中"，可能的原因：
|
||
|
||
1. **队列处理器未运行**：需要启动队列处理器来执行转换任务
|
||
2. **测试数据无实际文件**：数据库中的测试文档记录没有对应的实际文件
|
||
3. **文件路径错误**：文档文件路径配置不正确
|
||
|
||
**解决方案**：
|
||
- 确保队列处理器正在运行（见下文）
|
||
- 上传真实的文档文件进行测试
|
||
- 删除无效的测试数据：`php artisan tinker --execute="\App\Models\Document::where('conversion_status', 'pending')->delete();"`
|
||
|
||
## 开发环境设置
|
||
|
||
### 方法一：使用 Supervisor（推荐用于生产环境）
|
||
|
||
1. 安装 Supervisor（macOS）：
|
||
```bash
|
||
brew install supervisor
|
||
```
|
||
|
||
2. 创建配置文件 `/usr/local/etc/supervisor.d/laravel-worker.ini`：
|
||
```ini
|
||
[program:laravel-worker]
|
||
process_name=%(program_name)s_%(process_num)02d
|
||
command=php /path/to/your/project/artisan queue:work --sleep=3 --tries=3 --max-time=3600
|
||
autostart=true
|
||
autorestart=true
|
||
stopasgroup=true
|
||
killasgroup=true
|
||
user=your-username
|
||
numprocs=1
|
||
redirect_stderr=true
|
||
stdout_logfile=/path/to/your/project/storage/logs/worker.log
|
||
stopwaitsecs=3600
|
||
```
|
||
|
||
3. 启动 Supervisor：
|
||
```bash
|
||
brew services start supervisor
|
||
supervisorctl reread
|
||
supervisorctl update
|
||
supervisorctl start laravel-worker:*
|
||
```
|
||
|
||
### 方法二：手动运行队列处理器（开发环境）
|
||
|
||
在单独的终端窗口中运行：
|
||
```bash
|
||
php artisan queue:work
|
||
```
|
||
|
||
或者使用 `queue:listen` 命令（会自动重载代码）：
|
||
```bash
|
||
php artisan queue:listen
|
||
```
|
||
|
||
### 方法三：使用 Octane + Swoole（本项目推荐）
|
||
|
||
本项目已配置 Octane + Swoole，可以同时处理 HTTP 请求和队列任务：
|
||
|
||
1. 启动 Octane 服务器：
|
||
```bash
|
||
php artisan octane:start --watch
|
||
```
|
||
|
||
2. 在另一个终端启动队列处理器：
|
||
```bash
|
||
php artisan queue:work
|
||
```
|
||
|
||
或者使用 Supervisor 配置（见方法一）。
|
||
|
||
## 使用 Composer 脚本
|
||
|
||
项目已配置了便捷的 Composer 脚本：
|
||
|
||
### 开发模式（启动 Octane + 队列）
|
||
```bash
|
||
composer run dev
|
||
```
|
||
|
||
这会启动：
|
||
- Octane HTTP 服务器（端口 8000）
|
||
- 队列处理器
|
||
|
||
### 仅启动 Octane
|
||
```bash
|
||
composer run octane
|
||
```
|
||
|
||
### 仅启动队列处理器
|
||
```bash
|
||
composer run queue
|
||
```
|
||
|
||
## 检查队列状态
|
||
|
||
### 查看队列中的任务
|
||
```bash
|
||
php artisan queue:work --once
|
||
```
|
||
|
||
### 查看失败的任务
|
||
```bash
|
||
php artisan queue:failed
|
||
```
|
||
|
||
### 重试失败的任务
|
||
```bash
|
||
php artisan queue:retry all
|
||
```
|
||
|
||
### 清空失败的任务
|
||
```bash
|
||
php artisan queue:flush
|
||
```
|
||
|
||
## 队列配置
|
||
|
||
队列配置文件位于 `config/queue.php`。
|
||
|
||
当前使用的队列驱动：`database`
|
||
|
||
可以在 `.env` 文件中修改：
|
||
```env
|
||
QUEUE_CONNECTION=database
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 1. 文档转换状态一直是"等待转换"
|
||
|
||
**原因**：队列处理器没有运行。
|
||
|
||
**解决方案**：
|
||
- 检查队列处理器是否在运行：`ps aux | grep "queue:work"`
|
||
- 启动队列处理器：`php artisan queue:work`
|
||
- 或使用 Supervisor 自动管理
|
||
|
||
### 2. 队列任务执行失败
|
||
|
||
**排查步骤**：
|
||
1. 查看日志：`tail -f storage/logs/laravel.log`
|
||
2. 查看失败任务：`php artisan queue:failed`
|
||
3. 检查任务详情：`php artisan queue:failed-table`
|
||
|
||
### 3. 队列处理速度慢
|
||
|
||
**优化方案**：
|
||
- 增加队列处理器数量（修改 Supervisor 配置中的 `numprocs`）
|
||
- 使用 Redis 队列驱动（性能更好）
|
||
- 调整 `--sleep` 和 `--tries` 参数
|
||
|
||
## 生产环境部署
|
||
|
||
### 使用 Supervisor
|
||
|
||
1. 复制配置文件到服务器
|
||
2. 修改路径和用户名
|
||
3. 启动 Supervisor：
|
||
```bash
|
||
sudo supervisorctl reread
|
||
sudo supervisorctl update
|
||
sudo supervisorctl start laravel-worker:*
|
||
```
|
||
|
||
### 使用 Docker
|
||
|
||
项目已包含 Docker 配置，Supervisor 会自动启动队列处理器。
|
||
|
||
查看 `docker/supervisor/supervisord.conf` 了解详情。
|
||
|
||
## 监控队列
|
||
|
||
### 使用 Horizon（可选）
|
||
|
||
如果需要更强大的队列监控，可以安装 Laravel Horizon：
|
||
|
||
```bash
|
||
composer require laravel/horizon
|
||
php artisan horizon:install
|
||
php artisan horizon
|
||
```
|
||
|
||
访问 `/horizon` 查看队列监控面板。
|
||
|
||
## 相关文档
|
||
|
||
- [Laravel 队列文档](https://laravel.com/docs/queues)
|
||
- [Laravel Octane 文档](https://laravel.com/docs/octane)
|
||
- [Supervisor 文档](http://supervisord.org/)
|