acf549c43c
- 实现基于 Laravel 11 和 Filament 3.X 的文档管理系统 - 添加用户认证和分组管理功能 - 实现文档上传、分类和权限控制 - 集成 Word 文档自动转换为 Markdown - 集成 Meilisearch 全文搜索引擎 - 实现文档在线预览功能 - 添加安全日志和审计功能 - 完整的简体中文界面 - 包含完整的项目文档和部署指南 技术栈: - Laravel 11.x - Filament 3.X - Meilisearch 1.5+ - Pandoc 文档转换 - Redis 队列系统 - Pest PHP 测试框架
172 lines
3.9 KiB
Markdown
172 lines
3.9 KiB
Markdown
# 文档转换服务使用指南
|
||
|
||
## 概述
|
||
|
||
DocumentConversionService 负责将上传的 Word 文档（.doc/.docx）转换为 Markdown 格式。转换过程是异步的，通过队列系统处理。
|
||
|
||
## 功能特性
|
||
|
||
1. **自动转换**: 文档上传后自动触发转换
|
||
2. **异步处理**: 使用队列系统，不阻塞用户操作
|
||
3. **错误处理**: 转换失败时记录错误，但不影响文档的基本功能
|
||
4. **重试机制**: 转换失败后自动重试（默认 3 次）
|
||
5. **预览生成**: 自动生成 Markdown 内容的预览（前 500 字符）
|
||
|
||
## 使用方法
|
||
|
||
### 1. 队列转换（推荐）
|
||
|
||
```php
|
||
use App\Services\DocumentConversionService;
|
||
use App\Models\Document;
|
||
|
||
$document = Document::find($id);
|
||
$conversionService = app(DocumentConversionService::class);
|
||
|
||
// 将转换任务加入队列
|
||
$conversionService->queueConversion($document);
|
||
```
|
||
|
||
### 2. 同步转换（不推荐用于生产环境）
|
||
|
||
```php
|
||
use App\Services\DocumentConversionService;
|
||
use App\Models\Document;
|
||
|
||
$document = Document::find($id);
|
||
$conversionService = app(DocumentConversionService::class);
|
||
|
||
try {
|
||
// 转换文档
|
||
$markdown = $conversionService->convertToMarkdown($document);
|
||
|
||
// 保存 Markdown 文件
|
||
$markdownPath = $conversionService->saveMarkdownToFile($document, $markdown);
|
||
|
||
// 更新文档信息
|
||
$conversionService->updateDocumentMarkdown($document, $markdownPath);
|
||
|
||
} catch (\Exception $e) {
|
||
// 处理转换失败
|
||
$conversionService->handleConversionFailure($document, $e);
|
||
}
|
||
```
|
||
|
||
## 转换状态
|
||
|
||
文档的 `conversion_status` 字段有以下几种状态：
|
||
|
||
- `pending`: 等待转换
|
||
- `processing`: 正在转换
|
||
- `completed`: 转换完成
|
||
- `failed`: 转换失败
|
||
|
||
## 配置
|
||
|
||
转换相关的配置在 `config/documents.php` 文件中：
|
||
|
||
```php
|
||
'conversion' => [
|
||
'driver' => 'pandoc', // 转换驱动
|
||
'pandoc_path' => '/usr/local/bin/pandoc', // Pandoc 路径
|
||
'timeout' => 300, // 超时时间（秒）
|
||
'queue' => 'documents', // 队列名称
|
||
'retry_times' => 3, // 重试次数
|
||
'retry_delay' => 60, // 重试延迟（秒）
|
||
],
|
||
```
|
||
|
||
## 队列工作进程
|
||
|
||
确保队列工作进程正在运行：
|
||
|
||
```bash
|
||
# 启动队列工作进程
|
||
php artisan queue:work --queue=documents
|
||
|
||
# 或者使用 Supervisor 管理队列进程
|
||
```
|
||
|
||
## 依赖要求
|
||
|
||
### Pandoc
|
||
|
||
系统需要安装 Pandoc 才能进行文档转换：
|
||
|
||
**macOS:**
|
||
```bash
|
||
brew install pandoc
|
||
```
|
||
|
||
**Ubuntu/Debian:**
|
||
```bash
|
||
sudo apt-get install pandoc
|
||
```
|
||
|
||
**验证安装:**
|
||
```bash
|
||
pandoc --version
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
转换失败时，系统会：
|
||
|
||
1. 记录详细的错误日志
|
||
2. 更新文档的 `conversion_status` 为 `failed`
|
||
3. 在 `conversion_error` 字段中保存错误信息
|
||
4. 保留原始 Word 文档，用户仍可下载
|
||
|
||
## 监控和调试
|
||
|
||
### 查看转换日志
|
||
|
||
```bash
|
||
tail -f storage/logs/laravel.log | grep "文档转换"
|
||
```
|
||
|
||
### 查看队列任务
|
||
|
||
```bash
|
||
php artisan queue:failed
|
||
```
|
||
|
||
### 重试失败的任务
|
||
|
||
```bash
|
||
# 重试所有失败的任务
|
||
php artisan queue:retry all
|
||
|
||
# 重试特定任务
|
||
php artisan queue:retry {job-id}
|
||
```
|
||
|
||
## 性能优化
|
||
|
||
1. **使用 Redis 队列**: 比数据库队列更快
|
||
2. **增加队列工作进程**: 并行处理多个转换任务
|
||
3. **调整超时时间**: 根据文档大小调整 `timeout` 配置
|
||
4. **监控队列长度**: 避免队列积压
|
||
|
||
## 故障排查
|
||
|
||
### 转换一直处于 processing 状态
|
||
|
||
- 检查队列工作进程是否运行
|
||
- 检查 Pandoc 是否正确安装
|
||
- 查看错误日志
|
||
|
||
### 转换失败
|
||
|
||
- 检查 Pandoc 路径配置是否正确
|
||
- 检查文档文件是否存在
|
||
- 检查文档文件是否损坏
|
||
- 查看 `conversion_error` 字段的错误信息
|
||
|
||
### 队列任务不执行
|
||
|
||
- 确认队列连接配置正确（Redis/Database）
|
||
- 确认队列工作进程正在运行
|
||
- 检查队列名称是否匹配
|
||
|