3分钟上手！Gotenberg跨平台部署全攻略（Windows/Linux/macOS）

你还在为不同系统部署文档转换服务头疼？本文3分钟教你搞定Gotenberg在Windows、Linux和macOS上的环境配置，轻松实现跨平台文档转PDF！读完你将获得：3大主流系统部署指南、Docker与源码编译双方案、常见问题解决方案。

项目简介

Gotenberg是一个开发者友好的API服务，能够将HTML、Markdown、Word、Excel等多种文档格式转换为PDF文件。它基于Chromium和LibreOffice等强大工具，提供了简单易用的接口，适合各类文档处理场景。

项目核心文件：

• 主程序入口：cmd/gotenberg/main.go
• 构建配置：Makefile
• 官方文档：README.md

部署方案对比

部署方式	适用场景	难度	跨平台性
Docker容器	快速测试、生产环境	⭐	★★★★★
源码编译	自定义开发、特殊配置	⭐⭐⭐	★★★

Docker快速部署（推荐）

全平台通用步骤

1. 安装Docker Desktop

   • Windows/macOS：从Docker官网下载安装包
   • Linux：执行sudo apt-get install docker-ce docker-ce-cli containerd.io

2. 启动Gotenberg容器

   docker run --rm -p 3000:3000 gotenberg/gotenberg:8
   

3. 验证服务 访问 http://localhost:3000/health ，返回状态为"ok"即表示部署成功

源码编译部署

环境准备

1. 安装Go环境（1.16+）
2. 安装依赖工具
   • Chromium：用于HTML转PDF
   • LibreOffice：用于Office文档转换

Linux系统

1. 安装依赖

   sudo apt-get update && sudo apt-get install -y chromium libreoffice
   

2. 获取源码

   git clone https://gitcode.com/gh_mirrors/go/gotenberg.git
   cd gotenberg
   

3. 编译运行

   make build
   ./gotenberg
   

macOS系统

1. 安装依赖

   brew install chromium libreoffice
   

2. 获取源码并编译

   git clone https://gitcode.com/gh_mirrors/go/gotenberg.git
   cd gotenberg
   make build
   ./gotenberg
   

Windows系统

1. 安装依赖

   • 下载并安装Go
   • 安装Chocolatey
   • 执行choco install chromium libreoffice

2. 获取源码并编译

   git clone https://gitcode.com/gh_mirrors/go/gotenberg.git
   cd gotenberg
   go build -o gotenberg.exe cmd/gotenberg/main.go
   .\gotenberg.exe
   

配置与优化

核心配置参数

通过命令行参数或环境变量可以自定义Gotenberg的行为，主要配置项包括：

• 端口设置：--api-port=3000
• 超时配置：--api-timeout=30s
• Chromium设置：--chromium-restart-after=10
• LibreOffice配置：--libreoffice-restart-after=10

完整配置可参考Makefile中的环境变量定义。

性能优化建议

1. 根据实际需求调整服务重启策略
2. 生产环境建议使用Docker部署，便于管理和扩展
3. 对于高并发场景，可适当提高队列大小：--chromium-max-queue-size=100

常见问题解决

服务启动失败

• 检查端口是否被占用：netstat -tuln | grep 3000
• 确认依赖是否安装完整：特别是Chromium和LibreOffice

文档转换失败

• 检查输入文件格式是否支持
• 查看日志获取详细错误信息：--log-level=debug

总结

Gotenberg提供了灵活的部署方案，无论是快速测试还是生产环境，都能满足不同需求。通过Docker可以实现一键部署，而源码编译则适合需要自定义的场景。

如果您在部署过程中遇到问题，欢迎提交issue或查阅官方文档。别忘了点赞收藏本教程，关注获取更多Gotenberg使用技巧！

下一教程预告：Gotenberg高级功能使用指南 - 自定义PDF转换参数