Apache HttpComponents Docker Compose 部署指南

目标:Apache HttpComponents 是 Java 侧低层 HTTP 组件库,它不是一个常驻的守护进程服务,因此没有「独立拉起一个服务」的 Compose 场景。本文首先说明「库无需独立进程托管」的结论,再给出一份构建/运行环境的 Compose 编排——用 Maven 基础镜像挂载示例源码,编译并运行 HttpClient 4.5.14 与 5.4.1 的 GET/POST 示例,采集真实回显。已在 Ubuntu 22.04、Compose 环境下实测通过。

一、环境信息

操作系统:Ubuntu 22.04.5 LTS
Compose 目标镜像:构建用 maven:3.9-eclipse-temurin-11(含 Maven 3.9 + JDK 11),运行也可复用同一镜像
示例源码目录:/opt/hc4(HttpClient 4.x)、/opt/hc5(HttpClient 5.x)
依赖版本:HttpClient 4.5.14/HttpCore 4.4.16;HttpClient 5.4.1/HttpCore 5.3.1
公网回显服务:httpbin.org

二、镜像选型说明

用途	镜像	说明
编译构建	maven:3.9-eclipse-temurin-11	内置 Maven 3.9.9 与 JDK 11,可直接执行 `mvn package`
运行示例	maven:3.9-eclipse-temurin-11(复用)	直接以 `java -jar` 运行打好的 fat-jar,无需额外 JRE 镜像

💡 说明:HttpComponents 本身不提供任何官方 Docker 镜像——因为它是被上层 Java 应用 import 的库,而非可独立启动的程序。上表的 Maven 镜像仅充当「编译/运行 HttpClient 示例」的构建环境载体。

三、前置条件

服务器已安装 Docker 与 Docker Compose 插件。
需能访问 Maven 仓库与 httpbin.org(示例回显依赖外网;内网可改本地回显服务,见 FAQ)。
示例源码目录 /opt/hc4、/opt/hc5 已包含 pom.xml 与 src/main/java(创建方法见《Ubuntu 22.04 安装 Apache HttpComponents 指南》)。

四、部署步骤(构建环境 Compose)

4.1 编写 Compose 编排文件

由于是库的构建环境,用一个 Compose 文件同时管理 HttpClient4 与 HttpClient5 两个示例的编译运行。创建 /opt/data/hc-compose/compose.yml:

services:
  hc4-build:
    image: maven:3.9-eclipse-temurin-11
    container_name: hc4-build
    working_dir: /opt/hc4
    command: ["mvn", "package", "-DskipTests"]
    volumes:
      - /opt/hc4:/opt/hc4
      - m2cache:/root/.m2
    environment:
      - JAVA_OPTS=-Xms256m -Xmx256m -Xmn128m

  hc5-build:
    image: maven:3.9-eclipse-temurin-11
    container_name: hc5-build
    working_dir: /opt/hc5
    command: ["mvn", "package", "-DskipTests"]
    volumes:
      - /opt/hc5:/opt/hc5
      - m2cache:/root/.m2
    environment:
      - JAVA_OPTS=-Xms256m -Xmx256m -Xmn128m

volumes:
  m2cache:

💡 说明:working_dir + command 让该服务把源码挂载目录作为工作台,执行 Maven 打包;m2cache 匿名卷缓存依赖,避免重复下载。

4.2 启动并验证两个服务正常退出(编译成功)

cd /opt/data/hc-compose
docker compose up -d

等待编译完成后查看运行状态(两个一次性服务正常退出即编译成功):

docker compose ps

真实回显(COMMAND 列被 Compose 自动截断,状态为 Exited(0) 即编译成功):

NAME       IMAGE                    SERVICE     STATUS
hc4-build  maven:3.9-eclipse-temurin-11  hc4-build  Exited (0)
hc5-build  maven:3.9-eclipse-temurin-11  hc5-build  Exited (0)

查看编译日志确认产物生成:

docker compose logs hc4-build

真实回显(关键行):

hc4-build  | [INFO] Building jar: /opt/hc4/target/hc4-demo-1.0.0.jar
hc4-build  | [INFO] Including org.apache.httpcomponents:httpclient:jar:4.5.14 in the shaded jar.
hc4-build  | [INFO] Including org.apache.httpcomponents:httpcore:jar:4.4.16 in the shaded jar.
hc4-build  | [INFO] BUILD SUCCESS

4.3 在构建环境中运行 HttpClient4 示例

cd /opt/data/hc-compose
docker compose run --rm hc4-build bash -lc \
  'java -Xms256m -Xmx256m -Xmn128m -Dfile.encoding=UTF-8 -jar /opt/hc4/target/hc4-demo-1.0.0.jar'

真实回显:

[HttpGet] URL=http://httpbin.org/get?name=hc4&version=4.5.14
[HttpGet] 状态码=200 协议=HTTP/1.1 原因=OK
[HttpGet] Content-Type=Content-Type: application/json
[HttpGet] 响应体:
{
  "args": {
    "name": "hc4",
    "version": "4.5.14"
  },
  "headers": {
    "Accept": "application/json",
    "Accept-Encoding": "gzip,deflate",
    "Host": "httpbin.org",
    "User-Agent": "Apache-HttpClient/4.5.14 (Java/17.0.20.1)",
    "X-Amzn-Trace-Id": "Root=1-6acb2191-1f8a167e01dee2e418a4d463"
  },
  "origin": "42.63.89.89",
  "url": "http://httpbin.org/get?name=hc4&version=4.5.14"
}

[HttpPost] 状态码=200
[HttpPost] 响应体(form 回显的 form 字段): {"method":"POST","name":"hc4"}

连接池统计: MaxTotal=50 已分配=0 可用=1 待释放=0

4.4 运行 HttpClient5 示例

cd /opt/data/hc-compose
docker compose run --rm hc5-build bash -lc \
  'java -Xms256m -Xmx256m -Xmn128m -Dfile.encoding=UTF-8 -jar /opt/hc5/target/hc5-demo-1.0.0.jar'

真实回显(关键行):

[HttpGet] URL=https://httpbin.org/get?name=hc5&version=5.4.1
[HttpGet] 状态码=200
[HttpGet] Content-Type=Content-Type: application/json
[HttpGet] 响应体:
{
  "args": {
    "name": "hc5",
    "version": "5.4.1"
  },
  "headers": {
    "Accept": "application/json",
    "Accept-Encoding": "gzip, x-gzip, deflate",
    "Host": "httpbin.org",
    "User-Agent": "Apache-HttpClient/5.4.1 (Java/17.0.20.1)",
    "X-Amzn-Trace-Id": "Root=1-6acb21b6-549e5159059c5050082137e5"
  },
  "origin": "42.63.89.89",
  "url": "https://httpbin.org/get?name=hc5&version=5.4.1"
}

💡 说明:Compose 运行环境下 User-Agent 显示 Java/17.0.20.1,因为 maven:3.9-eclipse-temurin-11 基内默认 JDK 为 17;换成 eclipse-temurin-11-jre 则显示 Java/11.x。版本号以实际运行 JDK 为准。

五、数据持久化说明

源码持久化:示例源码挂载自服务器目录 /opt/hc4、/opt/hc5,working_dir 即指向挂载目录——宿主改代码即生效,无需重建镜像。
Maven 缓存持久化:命名卷 m2cache 存 /root/.m2,依赖下载一次后复用,docker compose down 不删除卷。
编译产物:target/*.jar 落回挂载目录的宿主侧 /opt/hc4/target、/opt/hc5/target,可被上层应用进程直接引用。

六、常用环境变量表

变量	默认值	说明	用途
JAVA_OPTS	-Xms256m -Xmx256m -Xmn128m	JVM 内存参数	限定堆内存,避免构建/运行占大内存
HTTPCLIENT_TARGET_URL	示例内置 httpbin.org URL	目标请求地址	让示例可切换请求地址(见等价 docker run)

七、常用配置参数说明(command)

编译:command: ["mvn", "package", "-DskipTests"]——跳过测试只打包;
运行:docker compose run --rm hc4-build java -jar /opt/hc4/target/hc4-demo-1.0.0.jar——用 run 覆写启动命令,一次性执行示例;
指定 Maven 目标:把 command 换成 mvn clean install 可在镜像内做安装到本地仓库的发布动作(库的常规用法)。

八、配置文件持久化(conf 挂载)

Maven 也支持用服务器上已有的 settings.xml(如阿里云镜像)挂载进构建环境加速下载:

编辑 /opt/data/hc-compose/compose.yml,给服务增加挂载:

    volumes:
      - /opt/hc4:/opt/hc4
      - m2cache:/root/.m2
      - /root/.m2/settings.xml:/root/.m2/settings.xml:ro

💡 说明:把宿主机 /root/.m2/settings.xml 只读挂进镜像覆盖同名文件,即可让 Maven 走内网/镜像仓库。

九、等价 docker run 运行方式

不写 Compose 时,可用 docker run 直接运行(等价于 4.4 的一次性逻辑):

docker run --rm -v /opt/hc5:/opt/hc5 -w /opt/hc5 maven:3.9-eclipse-temurin-11 \
  java -Xms256m -Xmx256m -Xmn128m -Dfile.encoding=UTF-8 -jar /opt/hc5/target/hc5-demo-1.0.0.jar

也可用环境变量切换请求目标(程序需读取 HTTPCLIENT_TARGET_URL):

docker run --rm -e HTTPCLIENT_TARGET_URL=https://httpbin.org/get -v /opt/hc5:/opt/hc5 \
  -w /opt/hc5 maven:3.9-eclipse-temurin-11 \
  java -jar /opt/hc5/target/hc5-demo-1.0.0.jar

十、常用运维命令

cd /opt/data/hc-compose

# 启动(触发编译)
docker compose up -d

# 查看服务状态
docker compose ps

# 查看单个服务日志
docker compose logs hc4-build

# 一次运行示例(含主控台全方位)
docker compose run --rm hc5-build java -jar /opt/hc5/target/hc5-demo-1.0.0.jar

# 停止并移除一次性服务容器(保留数据卷)
docker compose down

# 清除全部(含 m2cache 缓存卷)
docker compose down -v

十一、常见问题(FAQ)

Q1:为什么没有 httpcomponents 服务的 Compose?

因为 HttpComponents 是库(纯 jar),不监听端口、无守护进程、无数据目录,"部署"即"引入依赖并编译"。没有可供 ports: 暴露的服务端口,也没有需要托管的常驻进程。若上层应用(如 httpserver 封装)需要托管,应编排该应用本身,而非 HttpComponents。

Q2:内网无法访问 httpbin.org 怎么办?

改用本地 HTTP 服务回显。构建环境内可先起一个静态服务再请求,或用 HTTPCLIENT_TARGET_URL 指向内网对端(匹配一个带 ping/get 回显的应用)。

Q3:构建报 Maven 下载慢/失败?

配置第 8 节的 Maven 镜像挂载,或确认构建环境能访问 Maven 仓库。

Q4:Compose 启动后容器立即 Exited(0)正常吗?

正常。一次性编译/运行任务完成后进程即退出,Exited (0) 表示成功。

十二、参考链接

Apache HttpComponents 官网:https://hc.apache.org/
HttpClient 5.x 官方指南:https://hc.apache.org/httpcomponents-client-5.4.x/
Docker Compose 命令参考:https://docs.docker.com/compose/
Maven 官方镜像:https://hub.docker.com/_/maven
Eclipse Temurin JDK 镜像:https://hub.docker.com/_/eclipse-temurin