以远程容器方式运行IronPDF
IronPdfEngine 是一项独立服务,可以处理 PDF 的创建、写入、编辑和读取。 IronPDF Docker 已准备好运行兼容版本的IronPDF (v2023.2.x 及以上)的 Docker 服务。 这将有助于开发人员消除他们在使用IronPDF时可能遇到的部署问题。
为什么将IronPDF作为独立容器运行是个好主意
IronPDF需要 Chrome 和 Pdfium 二进制文件才能运行,而这两个文件体积都非常大(数百 MB)。 它还需要在机器上安装几个依赖项。
使用此方法,您的客户端只会占用很小一部分空间(以 MB 为单位)。
避免部署问题
正确配置环境/容器以包含所有依赖项可能具有挑战性。 使用IronPDF Docker 容器意味着IronPDF已预先安装并保证可以正常工作,避免了所有部署和依赖项方面的麻烦。
版本
IronPDF Docker 标签基于 IronPdfEngine 本身的版本。 它与IronPDF产品的版本不同。
每个IronPDF版本都会有其对应的 IronPdfEngine 版本。 版本号必须与IronPDF Docker 版本匹配。
例如,IronPDF for Java 版本 2023.2.1 需要 IronPdfEngine 版本 2023.2.1。 您不能使用版本不匹配的 IronPdfEngine 和IronPDF 。
如何使用IronPDF Docker
安装IronPDF
将IronPDF NuGet包添加到您的项目中。
注意:IronPdf.Linux 和 IronPdf.MacOs 软件包都包含IronPDF。
为了减小应用程序的大小,我们建议只安装IronPDF。 软件包 IronPdf.Native.Chrome.xxx 已不再使用,因此您可以将其从项目中移除。
确定所需的容器版本
默认情况下,Docker 版IronPDF的版本将与NuGet上IronPDF的当前版本匹配。 您可以使用以下代码手动检查版本:
:path=/static-assets/pdf/content-code-examples/how-to/ironpdfengine-docker-version.cs
string ironPdfEngineVersion = IronPdf.Installation.IronPdfEngineVersion;
Dim ironPdfEngineVersion As String = IronPdf.Installation.IronPdfEngineVersion
为 Docker 容器配置IronPDF
无需 Docker Compose
使用上一步中指定的版本运行 Docker 容器。
- 必须安装 Docker。
设置
- 前往https://hub.docker.com/r/ironsoftwareofficial/ironpdfengine
- 拉取最新的 ironsoftwareofficial/ironpdfengine 镜像
docker pull ironsoftwareofficial/ironpdfengine
docker pull ironsoftwareofficial/ironpdfengine
或者下载特定版本(推荐)
docker pull ironsoftwareofficial/ironpdfengine:2025.3.6
docker pull ironsoftwareofficial/ironpdfengine:2025.3.6
- 运行 ironsoftwareofficial/ironpdfengine 容器。
此命令将创建一个容器,并在后台使用端口 33350 运行它。
docker run -d -p 33350:33350 -e IRONPDF_ENGINE_LICENSE_KEY=MY_LICENSE_KEY ironsoftwareofficial/ironpdfengine:2025.3.6
docker run -d -p 33350:33350 -e IRONPDF_ENGINE_LICENSE_KEY=MY_LICENSE_KEY ironsoftwareofficial/ironpdfengine:2025.3.6
如何配置 IronPdfEngine 运行时参数?
运行时参数可以直接作为镜像名称后的 key=value 对传递给容器。 这些配置用于在不重新构建镜像的情况下配置引擎行为。
docker run -d -p 33350:33350 ironsoftwareofficial/ironpdfengine:2025.3.6 \
license_key="YOUR_LICENSE_KEY" \
enable_debug=true \
chrome_browser_limit=8
docker run -d -p 33350:33350 ironsoftwareofficial/ironpdfengine:2025.3.6 \
license_key="YOUR_LICENSE_KEY" \
enable_debug=true \
chrome_browser_limit=8
可使用的参数如下:
| 范围 | 类型 | Default | 描述 |
|---|---|---|---|
port |
int | 33350 |
gRPC监听端口 |
license_key |
string | — | IronPDF许可证密钥 |
enable_debug |
bool | false |
启用完整调试日志 |
log_path |
path | — | 日志文件路径(也支持完整调试日志记录) |
logging_mode |
string | Console |
日志模式:无、控制台、自定义、调试输出窗口、文件、全部 |
chrome_browser_limit |
int | — | 最大并发 Chrome 浏览器实例数 |
chrome_cache_path |
path | — | Chrome浏览器缓存目录 |
chrome_gpu_mode |
int | 0 |
GPU模式:0 禁用,1 硬件加速,2 硬件全加速,3 软件加速 |
chrome_custom_deployment_dir |
path | — | 用于 Chrome 部署二进制文件的自定义目录 |
temp_folder_path |
path | — | 覆盖临时目录 |
skip_shutdown |
bool | false |
防止发动机怠速时熄火 |
skip_initialization |
bool | false |
启动时跳过 Chrome/Pdfium 初始化 |
keep_alive |
bool | false |
客户端断开连接后,保持引擎运行。 |
single_process |
bool | — | 以单进程模式运行 Chrome |
linux_and_docker_auto_config |
bool | true |
自动配置 Linux/Docker 依赖项(由 Docker 入口点自动设置) |
send_anonymous_analytics_and_crash_data |
bool | — | 启用或禁用匿名遥测 |
linux_and_docker_auto_config 参数设置为 true。 您无需手动传递。 除非您的主机提供 GPU 直通,否则 Docker 中的 chrome_gpu_mode 应保持 0(禁用)。
也可以使用 IRONPDF_ENGINE_LICENSE_KEY 环境变量,通过 Docker Compose 中的 -e 或 environment: 来设置许可证密钥。 当命令行参数和环境变量都设置时,命令行参数优先。
生产示例:
docker run -d --restart=unless-stopped \
-p 33350:33350 \
-e IRONPDF_ENGINE_LICENSE_KEY=MY_KEY \
ironsoftwareofficial/ironpdfengine \
chrome_browser_limit=8 skip_shutdown=true
docker run -d --restart=unless-stopped \
-p 33350:33350 \
-e IRONPDF_ENGINE_LICENSE_KEY=MY_KEY \
ironsoftwareofficial/ironpdfengine \
chrome_browser_limit=8 skip_shutdown=true
调试示例:
docker run -p 33350:33350 \
ironsoftwareofficial/ironpdfengine \
enable_debug=true log_path=/app/logs/engine.log
docker run -p 33350:33350 \
ironsoftwareofficial/ironpdfengine \
enable_debug=true log_path=/app/logs/engine.log
使用 Docker Compose
关键在于建立一个 Docker 网络,使 IronPdfEngine 和你的应用程序能够相互访问。 设置"depends_on"以确保 IronPdfEngine 在应用程序启动之前已启动。
设置
- 首先创建一个
docker-compose.yml文件。使用以下模板设置您的 Docker Compose 文件:
version: '3.6'
services:
myironpdfengine:
container_name: ironpdfengine
image: ironsoftwareofficial/ironpdfengine:latest
ports:
- '33350:33350'
networks:
- ironpdf-network
myconsoleapp:
container_name: myconsoleapp
build:
# enter YOUR project directory path here
context: ./MyConsoleApp/
# enter YOUR dockerfile name here, relative to project directory
dockerfile: Dockerfile
networks:
- ironpdf-network
depends_on:
myironpdfengine:
condition: service_started
networks:
ironpdf-network:
driver: 'bridge'
- 将应用程序(myconsoleapp)中 IronPdfEngine 的地址设置为"myironpdfengine:33350"
- 运行 docker compose
docker compose up --detach --force-recreate --remove-orphans --timestamps
docker compose up --detach --force-recreate --remove-orphans --timestamps
连接到 IronPdfEngine
运行你的IronPDF代码; 您的应用程序现在可以与 Docker 中的 IronPdfEngine 进行通信了!
:path=/static-assets/pdf/content-code-examples/how-to/ironpdfengine-docker-use.cs
using IronPdf;
using IronPdf.GrpcLayer;
// Configure for Docker container
var config = IronPdfConnectionConfiguration.Docker;
config.Host = "localhost";
IronPdf.Installation.ConnectToIronPdfHost(config);
// Use IronPDF
ChromePdfRenderer renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Hello IronPDF Docker!<h1>");
pdf.SaveAs("ironpdf.pdf");
Imports IronPdf
Imports IronPdf.GrpcLayer
' Configure for Docker container
Private config = IronPdfConnectionConfiguration.Docker
config.Host = "localhost"
IronPdf.Installation.ConnectToIronPdfHost(config)
' Use IronPDF
Dim renderer As New ChromePdfRenderer()
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>Hello IronPDF Docker!<h1>")
pdf.SaveAs("ironpdf.pdf")
连接类型
您可以根据要建立的连接类型分配几个 IronPdfConnectionType。
以下是可供出租的房产列表:
LocalExecutable :要连接到在本地计算机上运行可执行文件的 IronPdfEngine"服务器",我们使用此选项。 一个简单的例子是 WinForm 发票应用程序,它可以在本地生成 PDF 文件,而无需依赖云服务。
Docker :当尝试连接到本地或云端的 Docker 容器时,应使用此选项。
RemoteServer :此选项用于云端 IronPdfEngine。 它通过 HTTP 或 HTTPS 协议连接到云托管(例如 Docker)的 IronPdfEngine 实例。 请注意,由于这是连接到远程服务器,因此需要完整的 URL(包括 HTTP 或 HTTPS 协议)。
自定义:要完全控制和自定义连接,您可以使用此选项。 此选项使用您自定义的Grpc.Co/re.ChannelBase ,而不是上面定义的其他选项。 开发人员可以通过创建新的Grpc.Co/re.Channel对象或使用.NET(System.String)来创建新通道,从而自定义和完全控制 gRPC 通道。
.NET Framework与 NetFrameworkChannel
对于.NET Framework,我们需要不同的设置,因为 gRPC 在.NET Framework项目中的工作方式不同。 要使此方法生效,请确保已安装Grpc.Co/re NuGet包。 对于此特定设置,我们将使用从Grpc.Co/re.ChannelBase派生的自定义 gRPC 通道。
让我们来看这个例子,我们将实现连接通道,使用 IronPDFEngine 创建和保存 PDF。
由于 gRPC 在.NET Framework项目中的工作方式不同,如果以下代码不起作用,请尝试移除地址中的 <http> 或 <https> 前缀。
pdf.Dispose 在这种情况下是必需的。:path=/static-assets/pdf/content-code-examples/how-to/ironpdfengine-docker-use-grpc.cs
using IronPdf;
// This code demonstrates how to use IronPdf with gRPC in a .NET Framework application.
// 1. Configure connection to use local IronPdfEngine executable
var config = IronPdf.GrpcLayer.IronPdfConnectionConfiguration.Executable;
// 2. Connect to the IronPDF host with the executable configuration
IronPdf.Installation.ConnectToIronPdfHost(config);
// 3. Create a PDF renderer instance
ChromePdfRenderer renderer = new ChromePdfRenderer();
// 4. Render HTML string as PDF document
PdfDocument pdf = renderer.RenderHtmlAsPdf("Hello world");
// 5. Save the PDF to disk
pdf.SaveAs("output.pdf");
// 6. Clean up , this is needed to work
pdf.Dispose();
Imports IronPdf
' This code demonstrates how to use IronPdf with gRPC in a .NET Framework application.
' 1. Configure connection to use local IronPdfEngine executable
Dim config = IronPdf.GrpcLayer.IronPdfConnectionConfiguration.Executable
' 2. Connect to the IronPDF host with the executable configuration
IronPdf.Installation.ConnectToIronPdfHost(config)
' 3. Create a PDF renderer instance
Dim renderer As New ChromePdfRenderer()
' 4. Render HTML string as PDF document
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("Hello world")
' 5. Save the PDF to disk
pdf.SaveAs("output.pdf")
' 6. Clean up, this is needed to work
pdf.Dispose()
使用 WithCustomChannel 的替代方法
另一种方法是利用 IronPdf.GrpcLayer 提供的 WithCustomChannel 方法。
WithCustomChannel 接受两个参数,customChannel,即您的自定义 gRPC 通道,以及 metadata。 metadata 参数是可选的,默认设置为 null。
:path=/static-assets/pdf/content-code-examples/how-to/ironpdfengine-docker-use-grpc-alt.cs
using IronPdf;
using IronPdf.GrpcLayer;
using Grpc.Core;
// 1. Create custom gRPC channel (.NET Framework style)
var channel = new Channel("123.456.7.8:80", ChannelCredentials.SecureSsl);
// 2. (Optional) Add metadata headers if needed
var metadata = new Metadata
{
{ "Authorization", "Bearer your_token_here" }
};
// 3. Configure IronPDF with custom channel
var config = IronPdfConnectionConfiguration.WithCustomChannel(channel, metadata);
IronPdf.Installation.ConnectToIronPdfHost(config);
// 4. Generate PDF
var renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderHtmlAsPdf("Hello world");
// 5. Save the PDF to disk
pdf.SaveAs("output.pdf");
// 6. Clean up , this is needed to work
pdf.Dispose();
Imports IronPdf
Imports IronPdf.GrpcLayer
Imports Grpc.Core
' 1. Create custom gRPC channel (.NET Framework style)
Dim channel As New Channel("123.456.7.8:80", ChannelCredentials.SecureSsl)
' 2. (Optional) Add metadata headers if needed
Dim metadata As New Metadata From {
{"Authorization", "Bearer your_token_here"}
}
' 3. Configure IronPDF with custom channel
Dim config As IronPdfConnectionConfiguration = IronPdfConnectionConfiguration.WithCustomChannel(channel, metadata)
IronPdf.Installation.ConnectToIronPdfHost(config)
' 4. Generate PDF
Dim renderer As New ChromePdfRenderer()
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("Hello world")
' 5. Save the PDF to disk
pdf.SaveAs("output.pdf")
' 6. Clean up, this is needed to work
pdf.Dispose()
在 AWS ECS 上部署 IronPdfEngine
先决条件
- 拉取 IronPdfEngine Docker 镜像。 这在上面的"为 Docker 容器设置IronPDF"部分中有所提及。
- 拥有访问 ECS 权限的 AWS 账户。
设置
- 创建 ECS 集群。 按照本指南,使用控制台为 Fargate 和 External 启动类型创建集群。
- 创建任务定义。 请按照本指南 使用控制台创建任务定义。
推荐设置:
- AWS Fargate
- 建议至少配备 1 个虚拟 CPU 和 2 GB 内存。 根据您的工作量,如果您处理的 PDF 文件超过 10 页或遇到较大的负载请求,请选择更高的级别。
-网络模式:awsvpc
-端口映射:
{ "containerPort": 33350, "hostPort": 33350, "protocol": "tcp", "appProtocol": "grpc" }-图片 URI :指向我们提供的任何 IronPdfEngine。 例如,"ironsoftwareofficial/ironpdfengine:2024.1.20"(来自 DockerHub) AWS 权限和网络配置需自行负责。 建议启用 Amazon CloudWatch 。 (Enable logging)
- 如果要在同一任务定义中部署应用程序容器,则容器启动顺序是必要的。
- 运行任务定义。 您可以将任务定义作为任务或服务运行。 请按照本指南使用控制台创建服务。
推荐设置:
- 启动类型: AWS Fargate
- 公网 IP:测试时开启,生产时关闭。 安全和AWS网络方面的问题需要您自行解决。
- 尽情享用! IronPdfEngine docker 已在您的 AWS 中启动并运行!
在 Azure 容器实例上部署 IronPdfEngine
先决条件
- 拉取 IronPdfEngine Docker 镜像。 这在上面的"为 Docker 容器设置IronPDF"部分中有所提及。
- Azure 帐户
设置
- 创建一个 Azure 容器。 请按照此快速入门指南,使用 Azure 门户在 Azure 中部署容器实例。
推荐设置:
-图片来源:其他注册表 -镜像: ironsoftwareofficial/ironpdfengine:2024.1.20 (来自 Docker Hub) 操作系统类型:Linux -规模:至少需要 1 个虚拟 CPU 和 2 GiB 内存,或更高 -端口:TCP 端口 33350
- 尽情享用! IronPdfEngine Docker 已在您的 Azure 容器实例中启动并运行!
在 AWS ECR 公共库中获取 IronPdfEngine
先决条件
- 必须安装 Docker。
设置
- 前往https://gallery.ecr.aws/v1m9w8y1/ironpdfengine
- 拉取 v1m9w8y1/ironpdfengine 镜像
docker pull https://gallery.ecr.aws/v1m9w8y1/ironpdfengine
docker pull https://gallery.ecr.aws/v1m9w8y1/ironpdfengine
或者下载特定版本(推荐)
docker pull https://gallery.ecr.aws/v1m9w8y1/ironpdfengine:2023.12.6
docker pull https://gallery.ecr.aws/v1m9w8y1/ironpdfengine:2023.12.6
- 运行 ironpdfengine 容器。
此命令将创建一个容器,并在后台使用端口 33350 运行它。
docker run -d -p 33350:33350 ironsoftwareofficial/ironpdfengine
docker run -d -p 33350:33350 ironsoftwareofficial/ironpdfengine
了解如何配置IronPDF客户端以使用 IronPdfEngine,请导航至"更新代码以使用 IronPdfEngine "部分。
从应用市场获取 IronPdfEngine
为了帮助您快速上手,我们已在 Azure 和 AWS Marketplace 上部署了 IronPdfEngine。
Azure Marketplace
设置
- 前往Azure Marketplace 上的IronPDF Docker 容器。 点击"立即获取"和"继续"。
- 完成"基本信息"、"集群详细信息"和"应用程序详细信息"以创建 Kubernetes 服务。
- 部署完成后,导航到左侧边栏并选择 Kubernetes 资源 > 运行命令。 运行以下命令:
kubectl get services
kubectl get services
有了外部 IP 和端口信息,就可以相应地配置 IronPDFEngine 连接。
:path=/static-assets/pdf/content-code-examples/how-to/pull-run-ironpdfengine-azure-marketplace.cs
using IronPdf;
using IronPdf.GrpcLayer;
IronPdf.License.LicenseKey = "IRONPDF-MYLICENSE-KEY-1EF01";
IronPdfConnectionConfiguration configuration = new IronPdfConnectionConfiguration();
configuration.ConnectionType = IronPdfConnectionType.RemoteServer;
configuration.Host = "http://48.216.143.233";
configuration.Port = 80;
IronPdf.Installation.ConnectToIronPdfHost(configuration);
ChromePdfRenderer renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>testing</h1>");
pdf.SaveAs("output.pdf");
Imports IronPdf
Imports IronPdf.GrpcLayer
IronPdf.License.LicenseKey = "IRONPDF-MYLICENSE-KEY-1EF01"
Dim configuration As New IronPdfConnectionConfiguration()
configuration.ConnectionType = IronPdfConnectionType.RemoteServer
configuration.Host = "http://48.216.143.233"
configuration.Port = 80
IronPdf.Installation.ConnectToIronPdfHost(configuration)
Dim renderer As New ChromePdfRenderer()
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>testing</h1>")
pdf.SaveAs("output.pdf")
AWS Marketplace
先决条件
- 必须安装 Docker。
- 必须安装并登录 AWS CLI。
设置
-
前往AWS Marketplace 上的 IronPdfEngine 。 点击"继续订阅"。
- 接受条款。
- 继续进行配置。
- 拉取 ironpdfengine 镜像。 此步骤将向您展示拉取 ironpdfengine 镜像的命令。
例如:
aws ecr get-login-password \
--region us-east-1 | docker login \
--username AWS \
--password-stdin 000000000000.dkr.ecr.us-east-1.amazonaws.com
CONTAINER_IMAGES="000000000000.dkr.ecr.us-east-1.amazonaws.com/iron-software/ironpdfengine:2024.1.15"
for i in $(echo $CONTAINER_IMAGES | sed "s/,/ /g"); do docker pull $i; done
aws ecr get-login-password \
--region us-east-1 | docker login \
--username AWS \
--password-stdin 000000000000.dkr.ecr.us-east-1.amazonaws.com
CONTAINER_IMAGES="000000000000.dkr.ecr.us-east-1.amazonaws.com/iron-software/ironpdfengine:2024.1.15"
for i in $(echo $CONTAINER_IMAGES | sed "s/,/ /g"); do docker pull $i; done
- 运行 ironpdfengine 容器。 此命令将创建一个容器,并在后台使用端口 33350 运行它。
docker run -d -p 33350:33350 000000000000.dkr.ecr.us-east-1.amazonaws.com/iron-software/ironpdfengine:2024.1.15
docker run -d -p 33350:33350 000000000000.dkr.ecr.us-east-1.amazonaws.com/iron-software/ironpdfengine:2024.1.15
IronPdfEngine 健康检查
检查 Docker 容器的健康状况对于确保生产环境中的可靠性和可用性至关重要。 通过检查 IronPdfEngine Docker 容器,开发人员可以在服务出现故障时重新启动服务,并在需求增加时扩展资源,同时还可以监控持续运行的应用程序。
为了检查 IronPdfEngine 的运行状况,我们可以向 IronPdfEngine 的同一端口(默认情况下为 33350)发送 gRPC 请求,以验证是否收到响应。
使用 gRPC 进行健康检查
IronPdfEngine 遵循标准的 gRPC 健康检查模式,采用以下协议结构。
message HealthCheckRequest {
string service = 1; // Name of the service to check (e.g., "IronPdfEngine")
}
由于我们正在检查 IronPdfEngine,因此我们将服务名称替换为 IronPdfEngine。
以下是使用Postman和JavaScript向本地 IronPdfEngine 服务发送 gRPC 请求的示例,默认编号为 33350。
从响应中可以看到,状态响应为 SERVING,表明服务已启动并正在运行。 如果容器不健康,则状态响应为 NOT_SERVING。
使用 Kubernetes 设置进行健康检查
对于 Kubernetes 设置,我们可以使用以下方法来检查服务是否健康。
livenessProbe:
exec:
command:
- /bin/grpc_health_probe
- -addr=:33350
- -rpc-timeout=5s
livenessProbe:
exec:
command:
- /bin/grpc_health_probe
- -addr=:33350
- -rpc-timeout=5s
常见问题解答
如何在Docker中使用C#将HTML转换为PDF?
您可以使用IronPDF的Docker设置在C#中将HTML转换为PDF。在Docker容器中部署IronPDFEngine,并使用诸如RenderHtmlAsPdf之类的方法来实现这一点。
在Docker中使用IronPDFEngine的好处有哪些?
在Docker中使用IronPDFEngine提供了一个预先安装的可靠环境,减少了依赖问题,并确保所有必要的组件,如Chrome和Pdfium二进制文件,均可用。
如何使用Docker Compose设置IronPDFEngine?
创建一个docker-compose.yml文件并定义服务和网络。使用depends_on指令确保IronPDFEngine在您的应用程序之前启动。
将IronPDFEngine部署到AWS ECS需要哪些步骤?
要在AWS ECS上部署,创建一个ECS集群,定义一个任务定义,并使用AWS Fargate进行资源分配。然后,运行您的任务或服务以启动IronPDFEngine。
如何从AWS ECR Public Gallery中获取IronPDFEngine?
访问AWS ECR Public Gallery,找到IronPDFEngine镜像,并按照提供的命令拉取并运行容器。
是否可以从Azure Marketplace使用IronPDFEngine?
是的,IronPDFEngine可在Azure Marketplace上获得。您可以按Marketplace页面上的设置说明部署Docker容器。
使用IronPDFEngine时应注意哪些限制?
IronPdfEngine Docker 容器本身不支持水平扩展,因为它被设计为单实例后端服务。但是,使用 IronPDF 库(无论是否包含 IronPdfEngine)的应用程序仍可通过部署多个应用程序实例来实现水平扩展。请在规划部署时注意这一区别。
如何高效处理Docker中的PDF生成和操作任务?
在Docker容器中部署IronPDFEngine,以高效管理PDF生成和操作任务,利用Docker的能力来处理依赖项并确保一致的环境。
在Azure Container Instances上部署IronPDFEngine的要求是什么?
要在Azure Container Instances上部署,请确保您有一个Azure帐户并拉取IronPDFEngine Docker镜像进行部署。



