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