HTML 转 PDF/图片服务使用指南

本项目是一个基于 Docker 的轻量级微服务，提供 JSON API 接口，用于将 HTML 内容转换为 PDF 文档或 PNG/JPG 图片。 服务底层采用 Chrome Headless (无头浏览器) 技术（基于 Puppeteer），确保页面渲染效果与完整版 Google Chrome 浏览器完全一致。

⚠️ 安全警告 本服务设计为内部微服务组件。严禁将其直接暴露在公共互联网上，否则可能面临安全风险（如 SSRF 攻击、资源耗尽等）。请在内网或通过网关鉴权后使用。

📖 API 接口文档

所有接口均通过 POST 请求发送 JSON 数据。

1. 生成 PDF 文档

接口地址: POST /1/pdf

基础示例

将 HTML 字符串转换为 PDF 文件：

curl \
  -d '{"html": "<h1>Hello World</h1>"}' \
  -H "Content-Type: application/json" \
  --output hello.pdf \
  -X POST "http://localhost:2305/1/pdf"

执行成功后，当前目录将生成 hello.pdf。

指定纸张格式

默认纸张为 Letter (美式标准)。可通过 export.format 设置为 A4 等其他格式：

xxxxxxxxxx
curl \
  -d '{
    "html": "<h1>Hello World</h1>", 
    "export": {
      "format": "A4"
    }
  }' \
  -H "Content-Type: application/json" \
  --output hello-a4.pdf \
  -X POST "http://localhost:2305/1/pdf"

2. 生成图片 (PNG / JPG)

接口地址: POST /1/screenshot

生成 PNG 图片

xxxxxxxxxx
curl \
  -d '{
    "html": "<h1>Hello World</h1>", 
    "export": {
      "type": "png"
    }
  }' \
  -H "Content-Type: application/json" \
  --output hello.png \
  -X POST "http://localhost:2305/1/screenshot"

生成 JPG 图片

只需将 type 改为 jpeg：

xxxxxxxxxx
curl \
  -d '{
    "html": "<h1>Hello World</h1>", 
    "export": {
      "type": "jpeg"
    }
  }' \
  -H "Content-Type: application/json" \
  --output hello.jpg \
  -X POST "http://localhost:2305/1/screenshot"

高级配置 (Advanced Options)

两个接口 (/1/pdf 和 /1/screenshot) 均支持在请求体的 export 字段中传递 Puppeteer 选项。这使得您可以精细控制渲染行为。

局域网中如何使用呢？

这样启动后只能在本机访问通，但是局域网中如何连接通呢，使用端口转发工具即可哦！

接下来，让我们开始配置一下吧！

1. 添加备注信息，便于区分即可

   

2. 出口配置中，端口可以填写任意，但需要注意不要和现有服务端口冲突。图示：填写2305

   

3. 目标配置选择对应服务和端口即可

   

4. 恭喜你，可以访问http://<微服ip>:<端口> 进行接口生成了。我们来测试一下吧

   1. 当前目录状态.

   2. 使用curl将html转换为pdf。

      xxxxxxxxxx
      $ curl \
        -d '{"html": "<h1>Hello World</h1>"}' \
        -H "Content-Type: application/json" \
        --output hello.pdf \
        -X POST "http://192.168.3.110:2305/1/pdf"
      

      输出：

      xxxxxxxxxx
        % Total    % Received % Xferd  Average Speed  Time    Time    Time   Current
                                       Dload  Upload  Total   Spent   Left   Speed
      100   7744 100   7712 100     32 114.5k    486  
      

       

   3. 再次查看当前目录，发现生成了pdf文件。恭喜你，成功了！

      xxxxxxxxxx
      $ ls
      hello.pdf