本文探讨了在Docker化PHP应用中，如何避免将LibreOffice及其依赖安装到PHP容器中造成的臃肿和单点故障问题。通过引入独立的LibreOffice转换微服务，PHP应用可以通过HTTP API安全高效地进行文件转换（如DOC/DOCX转TXT或PDF），实现服务解耦、提升应用健壮性，并详细介绍了Docker Compose配置和PHP客户端调用示例。
在现代Web应用开发中，尤其是在使用Docker进行容器化部署时，保持容器的精简和单一职责原则至关重要。当需要处理文件转换任务，例如将Word文档（.doc/.docx）转换为纯文本（.txt）以进行字数统计，或者转换为PDF格式时，LibreOffice是一个功能强大的工具。然而，直接将LibreOffice及其所有依赖安装到PHP-FPM容器中，会显著增加镜像大小，引入不必要的复杂性，并可能在LibreOffice服务出现问题时影响整个Web应用的可用性。本文将介绍一种更优的解决方案：将LibreOffice作为一个独立的微服务运行，并通过HTTP API与PHP应用进行交互。
1. 为什么选择微服务架构进行文件转换
将LibreOffice独立部署为微服务具有以下显著优势：
- 解耦与隔离： LibreOffice及其依赖与PHP应用完全隔离，互不影响。即使转换服务出现故障，主应用仍能正常运行。
- 镜像精简： PHP容器保持轻量，只包含Web应用所需的核心组件。
- 可伸缩性： 转换服务可以独立于PHP应用进行扩展，根据文件转换负载动态调整资源。
- 安全性： 避免了共享卷或Docker Socket等潜在的安全风险，通过HTTP API进行通信更加安全可控。
- 多语言支持： 转换服务可以被任何支持HTTP请求的语言调用，提高了复用性。
2. 部署LibreOffice转换微服务
为了实现文件转换微服务，我们可以利用现成的Docker镜像，例如sgbj/versed，它封装了LibreOffice并提供了一个Web API用于文件转换。
立即学习“PHP免费学习笔记（深入）”；
2.1 Docker Compose 配置
首先，在您的docker-compose.yml文件中添加转换服务。确保它与您的PHP应用位于同一网络中，以便内部通信。
version: '3.8'
services:
nginx:
image: nginx:alpine
ports:
- "80:80"
volumes:
- ./:/var/www/html
- ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf
depends_on:
- php-fpm
- converter # 确保 Nginx 也知道 converter 服务
networks:
- app-network
php-fpm:
image: php:8.1-fpm-alpine
volumes:
- ./:/var/www/html
networks:
- app-network
converter:
image: sgbj/versed:latest # 使用 sgbj/versed 镜像
environment:
- PORT=3000 # 默认端口，可以根据需要修改
ports:
- "3000:3000" # 如果需要从宿主机访问，可以暴露端口，否则内部通信不需要
networks:
- app-network
networks:
app-network:
driver: bridge在上述配置中：
- converter 服务使用了sgbj/versed镜像。
- PORT=3000 指定了转换服务监听的端口。
- 所有服务都加入了app-network，这使得它们可以通过服务名（例如converter）相互访问。
3. PHP应用与转换服务交互
在Laravel应用中，我们可以使用内置的Illuminate\Support\Facades\Http客户端来向转换微服务发送文件并接收转换结果。
3.1 配置转换服务终端
为了方便管理，将转换服务的API终端配置到Laravel的config/custom.php（或任何自定义配置文件）中。
config/custom.php:
env('CONVERTER_ENDPOINT', 'http://converter:3000/convert')
];然后，在您的.env文件中设置CONVERTER_ENDPOINT变量：
CONVERTER_ENDPOINT=http://converter:3000/convert
这里的http://converter:3000/convert是转换服务的内部地址，converter是docker-compose.yml中定义的service名称。
3.2 PHP客户端调用示例
以下是一个PHP控制器中调用转换服务的示例，演示了如何将一个文件上传到转换服务，并将返回的转换文件直接保存到本地。
timeout(60) // 设置请求超时时间，根据文件大小和转换复杂性调整
->withOptions([
'sink' => $destinationFilePath // 直接将响应流保存到文件
])
->post(config('custom.converter_endpoint'), [
'format' => $outputFormat, // 目标格式，例如 'pdf', 'txt'
]);
if ($response->successful()) {
// 转换成功
// 可选：删除原始文件，如果它是临时文件
// unlink($sourceFilePath);
return $destinationFilePath;
} else {
// 转换服务返回错误
logger()->error("文件转换失败：", [
'status' => $response->status(),
'body' => $response->body(),
'source_file' => $sourceFilePath,
'output_format' => $outputFormat
]);
return $sourceFilePath; // 返回原始文件路径
}
} catch (ConnectionException $e) {
// 转换服务不可用或网络连接错误
logger()->error("连接文件转换服务失败: " . $e->getMessage(), [
'endpoint' => config('custom.converter_endpoint'),
'source_file' => $sourceFilePath
]);
return $sourceFilePath; // 返回原始文件路径
} finally {
// 确保关闭文件句柄
fclose($fileHandler);
}
}
/**
* 示例：处理上传的DOCX文件并转换为PDF
*
* @param Request $request
* @return \Illuminate\Http\JsonResponse
*/
public function processUpload(Request $request)
{
$request->validate([
'document' => 'required|file|mimes:doc,docx|max:10240', // 10MB限制
]);
$uploadedFile = $request->file('document');
$tempPath = $uploadedFile->storeAs('temp_uploads', $uploadedFile->getClientOriginalName()); // 保存到临时目录
$sourceFilePath = storage_path('app/' . $tempPath);
$outputDirPath = public_path('converted_files'); // 转换后文件保存的公共目录
// 确保输出目录存在
if (!file_exists($outputDirPath)) {
mkdir($outputDirPath, 0777, true);
}
try {
$convertedFilePath = $this->convertFile($sourceFilePath, 'pdf', $outputDirPath);
// 如果转换成功，可以删除临时上传的文件
if ($convertedFilePath !== $sourceFilePath) {
unlink($sourceFilePath);
return response()->json(['message' => '文件转换成功', 'path' => asset(str_replace(public_path(), '', $convertedFilePath))]);
} else {
return response()->json(['message' => '文件转换失败，返回原始文件', 'path' => asset(str_replace(public_path(), '', $sourceFilePath))], 500);
}
} catch (Exception $e) {
logger()->error("文件处理异常: " . $e->getMessage());
// 清理临时文件
if (file_exists($sourceFilePath)) {
unlink($sourceFilePath);
}
return response()->json(['message' => '文件处理过程中发生错误', 'error' => $e->getMessage()], 500);
}
}
}代码解析：
- use Illuminate\Support\Facades\Http;: 引入Laravel的HTTP客户端。
- fopen($sourceFilePath, 'r'): 打开待转换文件的句柄。HTTP客户端可以直接从文件句柄读取数据，避免将整个文件加载到内存中。
-
Http::attach('file', $fileHandler, basename($sourceFilePath)): 这是发送文件的关键。attach方法用于发送multipart/form-data请求，其中：
- 'file' 是表单字段的名称，转换服务会通过这个名称接收文件。
- $fileHandler 是文件句柄。
- basename($sourceFilePath) 是文件的原始名称，用于告知转换服务。
- ->timeout(60): 设置请求的超时时间。文件转换可能需要一些时间，特别是对于大文件，因此需要适当延长超时。
- ->withOptions(['sink' => $destinationFilePath]): 这是接收转换后文件的关键。sink选项指示HTTP客户端将响应体直接流式传输到指定的文件路径，而不是加载到内存中。这对于处理大文件非常高效。
- ->post(config('custom.converter_endpoint'), ['format' => $outputFormat]): 向转换服务的/convert端点发送POST请求，并通过format参数指定目标转换格式（例如pdf、txt）。
-
错误处理:
- try...catch (ConnectionException $e): 捕获网络连接错误，例如转换服务未启动或无法访问。
- if ($response->successful()): 检查HTTP响应状态码是否表示成功（2xx）。
- finally { fclose($fileHandler); }: 确保无论转换成功与否，文件句柄都能被关闭，防止资源泄露。
4. 字数统计的特殊处理
原始问题中提到需要从doc/docx文件获取总字数。在这种情况下，转换服务的format参数应设置为txt。
// 假设 $sourceFilePath 是你的 .doc 或 .docx 文件路径
// 假设 $outputDirPath 是你希望保存 .txt 文件的目录
$txtFilePath = $this->convertFile($sourceFilePath, 'txt', $outputDirPath);
if ($txtFilePath !== $sourceFilePath) {
// 文件成功转换为 TXT
$wordCount = str_word_count(file_get_contents($txtFilePath));
// 可以在这里删除临时生成的 .txt 文件
// unlink($txtFilePath);
echo "文件字数: " . $wordCount;
} else {
echo "文件转换失败，无法统计字数。";
}通过将文件转换为纯文本格式，PHP就可以轻松地读取文本内容，并使用str_word_count()等函数进行字数统计。
5. 注意事项与总结
- 网络配置： 确保PHP容器和转换服务容器在同一个Docker网络中，以便它们可以通过服务名称相互通信。
- 超时设置： 文件转换，特别是对于大型或复杂文档，可能需要较长时间。务必在PHP HTTP客户端中设置合理的超时时间。
- 错误处理： 实施健壮的错误处理机制，包括网络连接失败、转换服务内部错误和文件操作错误，以提高应用的韧性。
- 资源清理： 转换完成后，如果原始文件或转换后的文件是临时性的，请确保及时清理，释放磁盘空间。
- 安全性： 尽管此方法比共享卷更安全，但仍需确保转换服务本身没有不必要的端口暴露，并考虑在生产环境中对内部API调用进行身份验证或授权。
- 替代方案： 针对仅处理.docx文件的场景，PHPWord是一个纯PHP解决方案，无需外部服务，但它不支持旧版.doc格式。对于需要广泛格式支持的场景，LibreOffice微服务是更通用的选择。
通过将LibreOffice作为独立的Docker微服务运行，并利用HTTP API进行通信，我们不仅解决了PHP应用臃肿和单点故障的问题，还构建了一个更具弹性、可伸缩和易于维护的文件转换解决方案。这种架构模式在处理其他需要外部复杂工具的任务时也同样适用。
