From 599a91724657f3fd0f13390bcce5b2657458639b Mon Sep 17 00:00:00 2001
From: lizhuoran <625237490@qq.com>
Date: Mon, 9 Mar 2026 14:02:53 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=98=9F=E5=88=97?=
 =?UTF-8?q?=E7=B3=BB=E7=BB=9F=E8=AE=BE=E7=BD=AE=E6=8C=87=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 创建 QUEUE_SETUP.md 文档
- 说明队列系统的配置和使用方法
- 解释文档转换状态问题的原因
- 提供开发环境和生产环境的配置方案
- 包含常见问题和解决方案
- 说明如何使用 Supervisor 管理队列
- 说明如何使用 composer run dev 启动服务
---
 docs/QUEUE_SETUP.md | 204 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 204 insertions(+)
 create mode 100644 docs/QUEUE_SETUP.md

diff --git a/docs/QUEUE_SETUP.md b/docs/QUEUE_SETUP.md
new file mode 100644
index 0000000..fb8936b
--- /dev/null
+++ b/docs/QUEUE_SETUP.md
@@ -0,0 +1,204 @@
+# 队列系统设置指南
+
+## 概述
+
+本系统使用 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/)