# 队列系统设置指南

## 概述

本系统使用 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/)