Files

Knowledge Base System acf549c43c feat: 初始化知识库系统项目

- 实现基于 Laravel 11 和 Filament 3.X 的文档管理系统
- 添加用户认证和分组管理功能
- 实现文档上传、分类和权限控制
- 集成 Word 文档自动转换为 Markdown
- 集成 Meilisearch 全文搜索引擎
- 实现文档在线预览功能
- 添加安全日志和审计功能
- 完整的简体中文界面
- 包含完整的项目文档和部署指南

技术栈:
- Laravel 11.x
- Filament 3.X
- Meilisearch 1.5+
- Pandoc 文档转换
- Redis 队列系统
- Pest PHP 测试框架

2025-12-05 14:44:44 +08:00

3.9 KiB

Raw Blame History

文档转换服务使用指南

概述

DocumentConversionService 负责将上传的 Word 文档（.doc/.docx）转换为 Markdown 格式。转换过程是异步的，通过队列系统处理。

功能特性

自动转换: 文档上传后自动触发转换
异步处理: 使用队列系统，不阻塞用户操作
错误处理: 转换失败时记录错误，但不影响文档的基本功能
重试机制: 转换失败后自动重试（默认 3 次）
预览生成: 自动生成 Markdown 内容的预览（前 500 字符）

使用方法

1. 队列转换（推荐）

use App\Services\DocumentConversionService;
use App\Models\Document;

$document = Document::find($id);
$conversionService = app(DocumentConversionService::class);

// 将转换任务加入队列
$conversionService->queueConversion($document);

2. 同步转换（不推荐用于生产环境）

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 文件中：

'conversion' => [
    'driver' => 'pandoc',                    // 转换驱动
    'pandoc_path' => '/usr/local/bin/pandoc', // Pandoc 路径
    'timeout' => 300,                        // 超时时间（秒）
    'queue' => 'documents',                  // 队列名称
    'retry_times' => 3,                      // 重试次数
    'retry_delay' => 60,                     // 重试延迟（秒）
],

队列工作进程

确保队列工作进程正在运行：

# 启动队列工作进程
php artisan queue:work --queue=documents

# 或者使用 Supervisor 管理队列进程

依赖要求

Pandoc

系统需要安装 Pandoc 才能进行文档转换：

macOS:

brew install pandoc

Ubuntu/Debian:

sudo apt-get install pandoc

验证安装:

pandoc --version

错误处理

转换失败时，系统会：

记录详细的错误日志
更新文档的 conversion_status 为 failed
在 conversion_error 字段中保存错误信息
保留原始 Word 文档，用户仍可下载

监控和调试

查看转换日志

tail -f storage/logs/laravel.log | grep "文档转换"

查看队列任务

php artisan queue:failed

重试失败的任务

# 重试所有失败的任务
php artisan queue:retry all

# 重试特定任务
php artisan queue:retry {job-id}

性能优化

使用 Redis 队列: 比数据库队列更快
增加队列工作进程: 并行处理多个转换任务
调整超时时间: 根据文档大小调整 timeout 配置
监控队列长度: 避免队列积压

故障排查

转换一直处于 processing 状态

检查队列工作进程是否运行
检查 Pandoc 是否正确安装
查看错误日志

转换失败

检查 Pandoc 路径配置是否正确
检查文档文件是否存在
检查文档文件是否损坏
查看 conversion_error 字段的错误信息

队列任务不执行

确认队列连接配置正确（Redis/Database）
确认队列工作进程正在运行
检查队列名称是否匹配

3.9 KiB Raw Blame History Unescape Escape