Rails中Wicked_pdf在Docker环境无法读取本地临时文件生成PDF

核心问题分析 #

报错显示wkhtmltopdf无法找到临时目录中的header HTML文件，本质是Docker/ECS环境下的文件权限、路径格式、依赖缺失或临时存储配置问题，以下是针对性解决方案：

1. 修复/tmp目录权限 #

Docker容器内的/tmp目录可能因运行用户权限不足，导致wicked_pdf无法创建临时文件。在Dockerfile中添加权限配置：

# 针对Debian/Ubuntu镜像，开放/tmp全权限
RUN chmod 777 /tmp

# 若使用非root用户运行容器，确保用户拥有/tmp读写权限
RUN useradd -m appuser && chown -R appuser:appuser /tmp
USER appuser

2. 修正wicked_pdf路径配置 #

错误日志中的路径存在多余斜杠（file:////tmp/...），是路径拼接异常导致的文件找不到。在初始化配置中指定明确的临时目录：

# config/initializers/wicked_pdf.rb
WickedPdf.config = {
  tmp_path: Rails.root.join('tmp').to_s,
  exe_path: '/usr/local/bundle/bin/wkhtmltopdf' # 后续替换为系统级路径时需修改
}

同时确保生成header路径时使用正确格式：

header_path = Rails.root.join('tmp', "wicked_header_#{SecureRandom.hex}.html").to_s
# 传递给wkhtmltopdf的协议路径格式
"file://#{header_path}"

3. 替换gem版wkhtmltopdf为系统级安装 #

wkhtmltopdf-binary gem提供的二进制文件在Docker轻量镜像（如Alpine）中常缺失依赖库（如libxrender、libfontconfig），直接在Dockerfile中安装系统版本：

Debian/Ubuntu镜像：

RUN apt-get update && apt-get install -y --no-install-recommends wkhtmltopdf libxrender1 libfontconfig1

Alpine镜像：

RUN apk add --no-cache wkhtmltopdf

然后更新wicked_pdf配置指向系统二进制：

WickedPdf.config = {
  exe_path: '/usr/bin/wkhtmltopdf' # Debian/Ubuntu与Alpine通用路径
}

4. 检查ECS Fargate临时存储配置 #

Fargate任务默认临时存储可读写，但自定义卷挂载可能覆盖/tmp权限：

• 确保任务定义中未将/tmp设置为只读卷
• 若使用自定义卷，确认卷权限允许容器用户读写

5. 应急绕过加载错误 #

如果仅header加载失败但不影响核心PDF内容，可添加参数强制生成：

pdf = WickedPdf.new.pdf_from_string(
  render_to_string(template: 'pdfs/report'),
  header: { html: { template: 'layouts/pdf_header' } },
  wkhtmltopdf: ['--load-error-handling', 'ignore']
)

内容的提问来源于stack exchange，提问作者Fabrizio Mele