Stirling-PDF项目Docker端口映射问题分析与解决方案

问题背景

在使用Stirling-PDF项目的Docker容器时，用户遇到了端口映射配置问题。具体表现为：当尝试修改容器端口映射关系时，虽然容器日志显示服务已启动，但实际无法通过浏览器访问Web界面，出现"连接被拒绝"的错误提示。

问题现象

用户最初尝试了两种端口映射配置方式：

1. 将容器内外端口都设置为6262（6262:6262）
2. 将外部端口设为6262，内部端口保持默认8080（6262:8080）

两种配置下，容器日志都显示服务正常运行，但实际访问时均失败。特别值得注意的是，即使在第二种配置下，日志仍然提示访问地址为localhost:8080，而非预期的6262端口。

技术分析

Docker端口映射机制

Docker端口映射的基本语法为主机端口:容器端口。在Stirling-PDF项目中，容器内部默认使用8080端口运行服务。因此，正确的映射方式应该是将主机的某个端口（如6262）映射到容器的8080端口。

服务绑定地址

除了端口映射外，服务绑定的网络接口也是一个关键因素。默认情况下，许多服务只绑定到localhost（127.0.0.1），这意味着即使端口映射正确，外部也无法访问。需要将服务绑定到0.0.0.0才能接受来自所有网络接口的连接。

环境变量配置

Stirling-PDF项目支持通过环境变量来配置服务运行参数：

• SERVER_HOST：控制服务绑定的网络接口
• SERVER_PORT：控制服务监听的端口

解决方案

经过多次尝试和验证，最终确定以下配置方案可解决问题：

environment:
  - SERVER_HOST=0.0.0.0
  - SERVER_PORT=6262
ports:
  - '6262:6262'

这一配置实现了：

1. 服务在容器内部监听6262端口
2. 服务绑定到所有网络接口（0.0.0.0）
3. 将主机的6262端口映射到容器的6262端口

经验总结

1. 端口一致性：在Docker环境中，建议保持容器内外端口一致，减少混淆
2. 网络接口绑定：服务必须绑定到0.0.0.0才能接受外部连接
3. 环境变量优先：通过环境变量配置服务参数比修改配置文件更可靠
4. 日志验证：检查服务启动日志，确认实际监听的端口和地址是否符合预期

最佳实践建议

对于类似的应用部署场景，建议采用以下步骤：

1. 首先确定应用默认的监听端口
2. 在Docker配置中明确指定SERVER_HOST和SERVER_PORT环境变量
3. 保持容器内外端口一致，简化配置
4. 测试从主机和网络其他位置访问服务
5. 检查防火墙设置，确保端口未被阻止

通过这种方法，可以避免常见的端口映射问题，确保服务可访问性。