Apache Knox 2.1.0 Docker Compose 部署指南

Docker Compose 部署 Apache Knox 2.1.0 网关：镜像构建选型（官方包+JDK8 基础镜像）、entrypoint 初始化 master secret 与演示 LDAP、conf/data 卷持久化、restart 与等价 docker run 实测、常用运维命令与 FAQ

Apache KnoxApache Knox2026/10/12

Apache Knox 2.1.0 Docker Compose 部署指南

目标：用 Docker Compose 从 0 到 1 部署 Apache Knox Gateway 2.1.0——基于官方 tar.gz 构建自定义镜像（Ubuntu 22.04 + OpenJDK 8）、entrypoint 初始化 master secret 与演示 LDAP、conf/data 卷持久化、端口映射验证 REST API、restart 后数据不丢、给出等价 docker run 方式与运维命令。已在 Docker 29.8.1 + Compose v5.5.1 环境构建镜像 knox-gateway:2.1.0 并实测通过。

一、环境信息

  • 宿主系统：Linux x86_64（内核支持 overlayfs/cgroups）
  • Docker：29.8.1；Docker Compose：v5.5.1
  • 基础镜像：ubuntu:22.04；JDK：openjdk-8-jre-headless（Knox 2.1.0 要求 Java 1.8）
  • Knox 包：knox-2.1.0.tar.gz（sha256 ac97bd1f6944c9ac8c3f8e159c480b2c6793b81cd58fc3e1963a345dd4450635，153M）
  • 自建镜像：knox-gateway:2.1.0
  • 实测端口映射：宿主机 8443 → 容器 8443；演示 LDAP 33389 仅容器内使用（不映射）
  • 项目目录：/opt/knox-compose（Dockerfile、entrypoint.sh、docker-compose.yml、conf/、data/）

二、镜像选型说明

  • Docker Hub 无 Apache 官方 Knox 镜像，社区镜像版本滞后且不可控，生产建议基于官方 tar.gz 自建镜像（版本、补丁、用户、JVM 参数全部可控），本文采用该方案。
  • 基础镜像选 ubuntu:22.04 + openjdk-8-jre-headless：与真实服务器安装路径一致（Knox 2.1.0 要求 Java 1.8；JDK 17 从 3.0.0 才支持），jre-headless 体积小且不含编译工具，攻击面小。
  • 若内网有统一的 JRE 基础镜像（如 eclipse-temurin:8-jre），可直接替换 FROM 行，其余不变。
  • 网关在容器内以非 root 用户 knox 运行（Knox 禁止 root 运行网关），LDAP 组件与网关同镜像启动，便于联调；生产可去掉 LDAP 启动行改接企业 LDAP/AD。

三、前置条件

  • 宿主机已安装 Docker 与 Docker Compose v2+，当前用户在 docker 组或具备 sudo。
  • 已获取官方安装包 knox-2.1.0.tar.gz 并校验 sha256（获取与校验方式见《Ubuntu 22.04 安装 Apache Knox 2.1.0 指南》第三节）。
  • 宿主机放行 8443 端口。
  • 准备项目目录：mkdir -p /opt/knox-compose && cd /opt/knox-compose，将 knox-2.1.0.tar.gz 拷入该目录。

四、部署步骤

4.1 编写 Dockerfile

创建 /opt/knox-compose/Dockerfile：

FROM ubuntu:22.04

ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && \
    apt-get install -y --no-install-recommends openjdk-8-jre-headless && \
    rm -rf /var/lib/apt/lists/*

RUN useradd -m -s /bin/bash knox

COPY knox-2.1.0.tar.gz /tmp/knox-2.1.0.tar.gz
RUN tar -zxf /tmp/knox-2.1.0.tar.gz -C /opt/ && \
    mv /opt/knox-2.1.0 /opt/knox && \
    chown -R knox:knox /opt/knox && \
    rm -f /tmp/knox-2.1.0.tar.gz

COPY entrypoint.sh /opt/knox/bin/entrypoint.sh
RUN chmod +x /opt/knox/bin/entrypoint.sh && chown knox:knox /opt/knox/bin/entrypoint.sh

USER knox
WORKDIR /opt/knox
EXPOSE 8443

ENTRYPOINT ["/opt/knox/bin/entrypoint.sh"]

4.2 编写 entrypoint.sh

创建 /opt/knox-compose/entrypoint.sh（首次启动初始化 master secret → 启动演示 LDAP → 网关前台运行）：

#!/bin/bash
set -e

# 首次启动时初始化 master secret（持久化到 /opt/knox/data/security/master）
if [ ! -f /opt/knox/data/security/master ]; then
  /opt/knox/bin/knoxcli.sh create-master --master "${KNOX_MASTER_SECRET:-q1w2e3r4}"
fi

# 启动演示 LDAP（生产环境替换为企业 LDAP/AD，可删除）
/opt/knox/bin/ldap.sh start

# 网关前台运行，交由 PID 1 管理
exec /usr/bin/java -Xms256m -Xmx512m \
  -Djava.library.path=/opt/knox/ext/native \
  -jar /opt/knox/bin/gateway.jar

4.3 准备持久化目录

从官方包解出默认 conf 作为宿主机挂载源，并将演示 LDAP 的 admin 密码统一改为 q1w2e3r4：

cd /opt/knox-compose
mkdir -p conf data
tar -zxf knox-2.1.0.tar.gz -C /tmp/ knox-2.1.0/conf     # 仅解出 conf 目录
cp -a /tmp/knox-2.1.0/conf/. conf/                       # 拷贝到挂载目录
sed -i 's/userPassword:admin-password/userPassword:q1w2e3r4/' conf/users.ldif   # 修改 admin 密码
chown -R 1000:1000 conf data                             # 对齐镜像内 knox 用户(uid 1000)读写权限

4.4 编写 docker-compose.yml

创建 /opt/knox-compose/docker-compose.yml：

services:
  knox:
    build: .
    image: knox-gateway:2.1.0
    container_name: knox-gateway
    restart: unless-stopped
    environment:
      - KNOX_MASTER_SECRET=q1w2e3r4
    ports:
      - "8443:8443"
    volumes:
      - ./conf:/opt/knox/conf
      - ./data:/opt/knox/data

4.5 构建镜像并启动

cd /opt/knox-compose
docker compose up -d --build

实测回显（构建末段与启动日志）：

Successfully built 320a8f3411da
Successfully tagged knox-gateway:2.1.0
 Image knox-gateway:2.1.0 Built
 Container knox-gateway Created
 Container knox-gateway Starting
 Container knox-gateway Started

4.6 验证部署

查看运行状态：

docker compose ps --format "table {{.Name}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"

NAME           IMAGE                STATUS          PORTS
knox-gateway   knox-gateway:2.1.0   Up 25 seconds   0.0.0.0:8443->8443/tcp, [::]:8443->8443/tcp

查看启动日志（master secret 初始化与 LDAP 启动）：

docker compose logs knox

knox-gateway  | Master secret has been persisted to disk.
knox-gateway  | Starting LDAP succeeded with PID 109.

等待网关完成拓扑部署（约 15–25 秒）后，经映射端口实测 REST API：

curl -s -k -u admin:q1w2e3r4 https://localhost:8443/gateway/admin/api/v1/version

实测回显（HTTP 200）：

<?xml version="1.0" encoding="UTF-8"?>
<ServerVersion>
   <version>2.1.0</version>
   <hash>57793d31b8234863b242f766b8861c2023cbd72d</hash>
</ServerVersion>

五、数据持久化说明

  • conf 持久化：宿主机 ./conf 绑定挂载到 /opt/knox/conf，gateway-site.xml、topologies/*.xml、users.ldif 全部落宿主机，重建镜像/容器不丢配置。
  • data 持久化：宿主机 ./data 绑定挂载到 /opt/knox/data，实测首次启动后生成以下内容（master secret、网关自签名证书 keystore、token 状态库）：
data/security/keystores
data/security/master
data/security/registry
data/security/tokens
  • 重启验证：docker compose restart 后再次访问版本接口实测仍为 200，master secret 不再重新初始化（日志无 "Master secret has been persisted" 重复输出）：
after-restart=200

⚠️ 注意：宿主机 conf/data 目录属主必须是 1000:1000（镜像内 knox 用户），否则启动报 keystore 写入失败；更换 KNOX_MASTER_SECRET 必须删除 data/security/master 与相关 jceks 后重建，否则解密失败。

六、常用环境变量表

变量实测取值说明
KNOX_MASTER_SECRETq1w2e3r4首次启动初始化 master secret（entrypoint.sh 消费）
JVM 堆参数-Xms256m -Xmx512m固定写在 entrypoint.sh 的 java 启动行，可按需调整
DEBIAN_FRONTENDnoninteractive构建期 apt 静默安装

💡 说明：knox-env.sh 中的 KNOX_GATEWAY_MEM_OPTS 体系在容器内被 entrypoint.sh 的前台 java 命令取代；如需更多 JVM 调优参数，直接编辑 entrypoint.sh 的 exec /usr/bin/java 行后 docker compose up -d --build 重建。

七、常用配置参数说明（command/entrypoint）

项值说明
ENTRYPOINT/opt/knox/bin/entrypoint.sh初始化 master secret → ldap.sh start → exec java 前台运行
exec javajava -Xms256m -Xmx512m -Djava.library.path=/opt/knox/ext/native -jar /opt/knox/bin/gateway.jar网关前台进程，容器停止时收到 SIGTERM 优雅关闭
ldap.sh start/opt/knox/bin/ldap.sh start演示 LDAP 后台启动，读 /opt/knox/conf/users.ldif
restartunless-stopped宿主机重启后自动拉起（等价 always，但手动 stop 后不拉起）
ports8443:8443网关 HTTPS 端口映射
volumes./conf、./data配置与运行数据持久化（见第五节）

八、配置文件持久化（conf 挂载）

  • 拓扑增删：直接在宿主机 /opt/knox-compose/conf/topologies/ 下新增/修改 XML，Knox 监测目录自动重新部署，无需重启容器（验证：docker compose logs -f knox 可看到 reloading 日志）。
  • 修改网关端口：编辑宿主机 conf/gateway-site.xml 的 gateway.port 后，同步调整 compose 的 ports 映射并 docker compose up -d 重建。
  • 演示用户增删：编辑宿主机 conf/users.ldif 后执行 docker compose restart knox（LDAP 仅启动时加载该文件）。

九、等价 docker run 运行方式

不使用 Compose 时，以下 docker run 与上述 compose 配置等价（实测 HTTP 200）：

mkdir -p /tmp/dr/conf /tmp/dr/data
cp -a /opt/knox-compose/conf/. /tmp/dr/conf/
chown -R 1000:1000 /tmp/dr
docker run -d --name knox-gateway-run \
  --restart unless-stopped \
  -e KNOX_MASTER_SECRET=q1w2e3r4 \
  -p 18443:8443 \
  -v /tmp/dr/conf:/opt/knox/conf \
  -v /tmp/dr/data:/opt/knox/data \
  knox-gateway:2.1.0

实测验证（等待约 30 秒后）：

curl -s -k -o /dev/null -w "%{http_code}\n" -u admin:q1w2e3r4 https://localhost:18443/gateway/admin/api/v1/version

200

十、常用运维命令

docker compose ps                        # 查看服务状态
docker compose logs -f knox              # 跟踪网关日志
docker compose restart knox              # 重启（users.ldif/topology 端口类变更后）
docker compose stop knox                 # 停止服务
docker compose down                      # 停止并删除容器与网络（conf/data 保留）
docker compose up -d --build             # 修改 Dockerfile/entrypoint 后重建
docker compose exec knox bash            # 进入容器排障（knox 用户）
docker compose exec knox /opt/knox/bin/knoxcli.sh list-topologies   # 容器内查看已部署拓扑

实测 docker compose down 回显：

 Container knox-gateway Stopping
 Container knox-gateway Stopped
 Container knox-gateway Removed
 Network knox-compose_default Removing
 Network knox-compose_default Removed

宿主机侧网关证书导出（复制到宿主机后分发客户端）：

docker compose cp knox:/opt/knox/data/security/keystores/gateway-client-trust.pem .   # 先在容器内执行 knoxcli.sh export-cert --type PEM

十一、常见问题（FAQ）

Q1：容器反复重启或立即退出？ A：docker compose logs knox 定位。常见原因：① 宿主机 conf/data 目录属主不是 1000:1000，keystore/master 写入失败；② 修改过 KNOX_MASTER_SECRET 但未清空 data/security，解密失败。处置：chown -R 1000:1000 conf data；或备份后清空 data 重建（master 与凭据库同时重置）。

Q2：构建时 apt 拉取 openjdk-8-jre-headless 失败或很慢？ A：在 Dockerfile FROM ubuntu:22.04 后加换源行（阿里云镜像示例）：RUN sed -i 's|archive.ubuntu.com|mirrors.aliyun.com|g; s|security.ubuntu.com|mirrors.aliyun.com|g' /etc/apt/sources.list，再执行安装层。

Q3：启动 30 秒内 curl 返回 401 或连接被拒？ A：网关 JVM 启动并部署 6 个默认拓扑约需 15–25 秒，LDAP 初始化也需数秒；等待后重试即可（与真实服务器行为一致）。

Q4：映射到宿主机的 33389 需要暴露吗？ A：不需要。演示 LDAP 仅供容器内网关认证使用；生产环境接企业 LDAP/AD 后可从 entrypoint.sh 删除 ldap.sh start 行。

Q5：如何更新到新版本 Knox？ A：替换项目目录中的 tar.gz 与 Dockerfile 中的 COPY 文件名，修改 image 标签（如 knox-gateway:2.1.1），docker compose up -d --build 重建；conf/data 卷保留则 master secret 与拓扑沿用（跨大版本需核对官方 CHANGES）。

Q6：多节点/多拓扑怎么扩展？ A：Knox 网关无状态可水平扩展：同一镜像起多个 service，前置 LB（如 nginx）做 8443 负载均衡；各实例挂同一份 conf（只读）+ 各自 data 卷。

十二、参考链接