Ubuntu 22.04 安装 Apache Knox 2.1.0 指南

目标：在 Ubuntu 22.04 服务器上从 0 到 1 安装并启动 Apache Knox Gateway 2.1.0（Hadoop 生态 REST API 安全网关），完成 JDK 8 环境、master secret 初始化、演示 LDAP 启动、JVM 堆限制、systemd 开机自启配置，并通过 8443 端口实测 REST API 版本接口与 WebHDFS 代理转发。已在 Ubuntu 22.04.5 x86_64、OpenJDK 1.8.0_504、/opt/knox 环境实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64），主机名 knox-u22
• Java：OpenJDK 1.8.0_504（openjdk-8-jdk-headless，Knox 2.1.0 官方要求 Java 1.8）
• Apache Knox：2.1.0（构建 hash 57793d31b8234863b242f766b8861c2023cbd72d）
• 安装目录：/opt/knox（运行用户 knox）
• 网关端口：8443（HTTPS）；演示 LDAP 端口：33389
• 数据目录：/opt/knox/data（keystore、deployments、master secret）
• 日志目录：/opt/knox/logs（gateway.log / gateway-audit.log / ldap.log）
• 实测 JVM 参数：-Xms256m -Xmx512m

二、前置条件

• 一台 Ubuntu 22.04 服务器，具备 root 或 sudo 权限。
• 服务器可访问外网（在线方案），或已将安装包拷贝到内网（离线方案）。
• 内存 ≥ 2GB（Knox 网关 JVM 建议限制在 256–512MB 堆即可满足演示/小规模场景）。
• 放行端口：8443（网关 HTTPS）、33389（演示 LDAP，生产环境替换为企业 LDAP/AD 后无需放行）。

三、版本选型说明

• Apache Knox 官方（knox.apache.org）当前公告的最新稳定版为 2.1.0，官方仅发布 tar.gz/zip 二进制包与源码包，不提供 apt/yum 仓库，因此统一采用官方二进制包安装。
• Knox 2.1.0 运行时要求 Java 1.8（官方用户手册 Requirements 章节原文：Java 1.8 is required for the Knox Gateway runtime）；JDK 17 从 3.0.0 起才受支持，选 2.1.0 必须装 JDK 8。
• 版本获取命令（不硬编码未来版本号）：

  # 查看官方在发版本目录
  curl -s https://downloads.apache.org/knox/ | grep -oE 'href="[0-9.]+/"' | sort -V
  

• 实测下载包信息：

四、安装部署步骤（方案 A：官方 tar.gz 在线安装）

4.1 创建运行用户

Knox 网关拒绝以 root 运行（实测启动时报 must not be run as root，见常见问题 Q1），先创建专用用户：

sudo useradd -m -s /bin/bash knox    # 创建 knox 运行用户

4.2 安装 JDK 8

sudo apt-get update                  # 刷新软件源
sudo apt-get install -y openjdk-8-jdk-headless   # 安装 OpenJDK 8

实测版本回显：

java -version

openjdk version "1.8.0_504"
OpenJDK Runtime Environment (build 1.8.0_504-8u504-ga-1ubuntu1~22.04.3-b01)
OpenJDK 64-Bit Server VM (build 25.504-b01, mixed mode)

4.3 下载安装包并校验

cd /tmp
wget https://dlcdn.apache.org/knox/2.1.0/knox-2.1.0.tar.gz          # 官方发行站下载
wget https://downloads.apache.org/knox/2.1.0/knox-2.1.0.tar.gz.sha256 -O -   # 获取官方校验值
sha256sum knox-2.1.0.tar.gz                                          # 本地计算校验值

实测回显：

ac97bd1f6944c9ac8c3f8e159c480b2c6793b81cd58fc3e1963a345dd4450635  knox-2.1.0.tar.gz
ac97bd1f6944c9ac8c3f8e159c480b2c6793b81cd58fc3e1963a345dd4450635

两值一致即包完整。若 dlcdn 不可达，可换 https://archive.apache.org/dist/knox/2.1.0/knox-2.1.0.tar.gz。

4.4 解压安装到 /opt/knox

sudo tar -zxf /tmp/knox-2.1.0.tar.gz -C /opt/       # 解压到 /opt
sudo mv /opt/knox-2.1.0 /opt/knox                   # 统一目录名
sudo chown -R knox:knox /opt/knox                   # 属主交给 knox 用户
ls /opt/knox                                        # 确认目录结构

实测目录结构回显：

CHANGES  ISSUES  LICENSE  NOTICE  README  bin  conf  data  dep  ext  lib  logs  pids  samples  templates

4.5 生成 master secret

master secret 用于加密网关自身凭据库，首次启动前必须初始化（初始化后持久化在 /opt/knox/data/security/master）：

sudo su - knox -c "/opt/knox/bin/knoxcli.sh create-master --master q1w2e3r4"

实测回显：

Master secret has been persisted to disk.

💡 说明：演示环境统一使用示例口令 q1w2e3r4；生产环境请替换为强口令。若交互式执行 knoxcli.sh create-master 不带 --master，会提示手动输入并确认两次。

4.6 限制 JVM 堆内存

编辑 /opt/knox/bin/knox-env.sh，取消注释并设置 KNOX_GATEWAY_MEM_OPTS：

sudo -u knox vi /opt/knox/bin/knox-env.sh

将原注释行：

# export KNOX_GATEWAY_MEM_OPTS=""

改为：

export KNOX_GATEWAY_MEM_OPTS="-Xms256m -Xmx512m"

4.7 启动演示 LDAP

Knox 自带演示用 LDAP（ApacheDS，读取 /opt/knox/conf/users.ldif），用于网关认证联调：

sudo su - knox -c "/opt/knox/bin/ldap.sh start"

实测回显：

Starting LDAP succeeded with PID 4796.

4.8 启动网关

sudo su - knox -c "/opt/knox/bin/gateway.sh start"

实测回显：

Starting Gateway succeeded with PID 4662.

检查进程与实际生效的 JVM 参数（验证 4.6 节堆限制已生效）：

jps -v | grep -E "gateway.jar|ldap.jar"

4662 gateway.jar -Xms256m -Xmx512m -Djava.library.path=/opt/knox/ext/native
4796 ldap.jar -Djava.library.path=/opt/knox/ext/native

确认端口监听：

sudo netstat -tlnp | grep -E "8443|33389"

tcp6       0      0 :::33389                :::*                    LISTEN      -
tcp6       0      0 :::8443                 :::*                    LISTEN      -

4.9 验证网关

默认拓扑中 admin 拓扑走 ShiroProvider（HTTP Basic 认证）对接演示 LDAP。修改 /opt/knox/conf/users.ldif 中 admin 用户密码为 q1w2e3r4 后（默认 admin-password，见 6.2 节），重启 LDAP 并实测：

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>

反向用例（实测均为 401）：

curl -s -k -o /dev/null -w "%{http_code}\n" https://localhost:8443/gateway/admin/api/v1/version          # 不带凭据
curl -s -k -o /dev/null -w "%{http_code}\n" -u admin:wrongpass https://localhost:8443/gateway/admin/api/v1/version   # 错误密码

401
401

KnoxSSO 联动（manager 拓扑使用 SSOCookieProvider，未登录时重定向到 KnoxSSO）：

curl -s -k -o /dev/null -w "%{http_code} redirect:%{redirect_url}\n" https://localhost:8443/gateway/manager/admin/api/v1/version

302 redirect:https://localhost:8443/gateway/knoxsso/api/v1/websso?originalUrl=https://localhost:8443/gateway/manager/admin/api/v1/version

代理转发链路验证：在后端 50070 端口准备 WebHDFS 服务后，经网关访问（实测后端返回 200，审计日志记录 dispatch 过程）：

curl -s -k -u admin:q1w2e3r4 "https://localhost:8443/gateway/sandbox/webhdfs/v1/?op=LISTSTATUS"

实测回显（HTTP 200，JSON 为后端 WebHDFS 原样返回）：

{"FileStatuses":{"FileStatus":[{"pathSuffix":"tmp","type":"DIRECTORY","length":0,"owner":"hdfs","group":"hdfs","permission":"755","accessTime":0,"modificationTime":1728000000000,"blockSize":0,"replication":0},{"pathSuffix":"user","type":"DIRECTORY","length":0,"owner":"hdfs","group":"supergroup","permission":"755","accessTime":0,"modificationTime":1728000000000,"blockSize":0,"replication":0}]}}

审计日志（/opt/knox/logs/gateway-audit.log）可看到完整转发链路（认证 admin、dispatch 到后端、user.name=admin 身份断言）：

26/10/11 12:36:37 ||c3a8b8b0-8148-4853-a893-beccf5e23ead|audit|127.0.0.1|WEBHDFS|admin|||dispatch|uri|http://localhost:50070/webhdfs/v1/?op=LISTSTATUS&user.name=admin|success|Response status: 200

五、方案对比与选择建议

Knox 官方仅提供二进制压缩包，两种方案差异仅在安装包获取方式，解压后的安装/配置/启动步骤完全一致：

选择建议：可联网优先方案 A（下载与校验一步完成）；内网隔离环境用方案 B，在具备外网的跳板机上下载并校验 sha256 后再拷贝入内网。

5.1 方案 B：离线安装差异步骤

在能出网的机器上下载并校验（同 4.3 节），然后拷贝到目标服务器：

scp knox-2.1.0.tar.gz knox-u22:/tmp/     # 从跳板机拷贝到目标服务器 /tmp

目标服务器上从 4.4 节起执行，后续步骤与方案 A 完全一致。

六、配置说明

6.1 目录结构

6.2 修改演示 LDAP 的 admin 密码

默认 admin 密码为 admin-password，演示环境统一改为 q1w2e3r4：编辑 /opt/knox/conf/users.ldif，找到 admin 用户条目：

# entry for sample user admin
dn: uid=admin,ou=people,dc=hadoop,dc=apache,dc=org
objectclass:top
objectclass:person
objectclass:organizationalPerson
objectclass:inetOrgPerson
cn: Admin
sn: Admin
uid: admin
userPassword:q1w2e3r4

admin 用户默认已属于 cn=admin,ou=groups 组（users.ldif 末尾 admin 组的 member 已包含 uid=admin），满足 manager/admin 拓扑的 KNOX_ADMIN_GROUPS 授权要求。修改后重启 LDAP 生效：

sudo su - knox -c "/opt/knox/bin/ldap.sh stop"
sudo su - knox -c "/opt/knox/bin/ldap.sh start"

⚠️ 注意：users.ldif 是首次启动 LDAP 时加载的演示数据源，仅用于联调；生产环境应替换为企业 LDAP/AD，并把拓扑中 ShiroProvider 的 main.ldapRealm.contextFactory.url 指向真实目录服务。

6.3 gateway-site.xml 常用键

配置文件：/opt/knox/conf/gateway-site.xml。实测默认值中的关键项：

完整参数分类解释见《Apache Knox 2.1.0 配置参数详解》。

6.4 JVM 内存调整位置汇总

• 脚本启动：/opt/knox/bin/knox-env.sh 中 KNOX_GATEWAY_MEM_OPTS（网关）、KNOX_LDAP_MEM_OPTS（演示 LDAP）、KNOX_CLI_MEM_OPTS（knoxcli）。
• systemd 托管：单元文件 Environment="KNOX_GATEWAY_MEM_OPTS=-Xms256m -Xmx512m"（见第七节）。
• 修改后用 jps -v 或 ps -ef | grep [g]ateway.jar 确认实际生效值（见 4.8 节回显）。

七、systemd 开机自启

⚠️ 本节需要带 systemd 的 Linux 真机执行 systemctl 命令；单元文件内容已通过 systemd-analyze verify 离线校验（systemd 249）。

7.1 knox-ldap.service（演示 LDAP）

创建 /etc/systemd/system/knox-ldap.service：

[Unit]
Description=Apache Knox Demo LDAP Server
After=network.target

[Service]
Type=forking
User=knox
Group=knox
ExecStart=/opt/knox/bin/ldap.sh start
ExecStop=/opt/knox/bin/ldap.sh stop
PIDFile=/opt/knox/pids/ldap.pid
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

7.2 knox-gateway.service（网关）

创建 /etc/systemd/system/knox-gateway.service：

[Unit]
Description=Apache Knox Gateway
After=network.target knox-ldap.service
Wants=knox-ldap.service

[Service]
Type=forking
User=knox
Group=knox
Environment="KNOX_GATEWAY_MEM_OPTS=-Xms256m -Xmx512m"
ExecStart=/opt/knox/bin/gateway.sh start
ExecStop=/opt/knox/bin/gateway.sh stop
PIDFile=/opt/knox/pids/gateway.pid
Restart=on-failure
RestartSec=10
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

7.3 单元文件校验与两处修正实录

写入后先离线校验语法：

sudo systemd-analyze verify /etc/systemd/system/knox-gateway.service /etc/systemd/system/knox-ldap.service

初版实测发现两处问题（均会被 systemd 忽略导致配置不生效）：

/etc/systemd/system/knox-gateway.service:10: Invalid environment assignment, ignoring: -Xmx512m
/etc/systemd/system/knox-gateway.service:13: Unknown key name 'ExecStatus' in section 'Service', ignoring.

• 问题一：Environment=KNOX_GATEWAY_MEM_OPTS=-Xms256m -Xmx512m 含空格未加引号，systemd 只取到 -Xms256m，-Xmx512m 被判为非法赋值。修正为 Environment="KNOX_GATEWAY_MEM_OPTS=-Xms256m -Xmx512m"。
• 问题二：ExecStatus 不是 systemd 合法键（状态查询应直接运行脚本），已删除。

修正后再次校验无任何输出、返回码 0。

7.4 启用与开机自启

sudo systemctl daemon-reload                    # 重新加载单元文件
sudo systemctl enable knox-ldap.service         # LDAP 开机自启
sudo systemctl enable knox-gateway.service      # 网关开机自启
sudo systemctl start knox-ldap.service          # 启动 LDAP
sudo systemctl start knox-gateway.service       # 启动网关
systemctl is-active knox-gateway.service        # 确认运行状态

⚠️ 注意：Type=forking + PIDFile 依赖启动脚本写出 PID 文件；确保 /opt/knox/pids 属于 knox 用户可写（默认解压属主已正确）。

八、注意事项

• Knox 网关不能以 root 运行，必须使用专用用户（本文 knox）。
• curl 访问自签名证书需加 -k；客户端接入建议导出网关证书（knoxcli.sh export-cert --type PEM）后信任。
• 修改 conf/topologies/ 下任意 XML 后，Knox 会自动监测并重新部署（也可手工 knoxcli.sh redeploy）。
• 防火墙需放行 8443；若使用 Knox 首页/UI 类服务，还需按 gateway.dispatch.whitelist 调整重定向白名单。
• 数据备份只需备份 /opt/knox/conf 与 /opt/knox/data（master secret 丢失将导致凭据库无法解密）。

九、常见问题（FAQ）

Q1：启动报 "This command /opt/knox/bin/gateway.sh must not be run as root." 怎么办？ A：Knox 网关禁止 root 运行。创建专用用户 useradd -m -s /bin/bash knox，chown -R knox:knox /opt/knox 后以 knox 身份启动（su - knox -c "/opt/knox/bin/gateway.sh start"）。演示 LDAP（ldap.sh）无此限制，但建议统一用 knox 用户。

Q2：gateway.sh stop 提示 "Stopping Gateway with PID 8840 failed."，但进程其实退出了？ A：这是脚本停止逻辑的边界竞态。gateway.sh 先发 SIGTERM 并等待 APP_KILL_WAIT_TIME（内置 10 秒），JVM 优雅关闭（undeploy 拓扑、关闭 Derby）实测约 10 秒，等待窗口结束后脚本补发的 kill -s KILL 落在进程已退出之后（ESRCH）导致误报 failed。确认方法：查看 /opt/knox/data/gatewayServer.status 已变为 STOPPED，/opt/knox/logs/gateway.out 出现 INFO - Derby database is closed；再次执行 gateway.sh status 显示 is not running 即已停止，直接 start 即可。

Q3：curl 认证返回 401，账号密码确认无误？ A：多为演示 LDAP 未就绪或刚重启。LDAP 启动后 ApacheDS 初始化需数秒，期间网关侧 KnoxLdapRealm 绑定失败，gateway.log 会出现 Shiro unable to login ERROR。等 LDAP 端口 33389 就绪后重试；用 knoxcli.sh user-auth-test --cluster admin --u admin --p q1w2e3r4 快速定位，实测成功输出 LDAP authentication successful!，密码错误输出 [LDAP: error code 49 - INVALID_CREDENTIALS: Bind failed: ERR_229 ...]。

Q4：knoxcli.sh service-test 报 PKIX path building failed？ A：网关默认使用自签名证书，工具走严格证书校验所致。导出并信任网关证书：knoxcli.sh export-cert --type PEM（实测导出到 /opt/knox/data/security/keystores/gateway-client-trust.pem），客户端导入该 PEM 后重试；测试场景也可用 curl -k 忽略校验。

Q5：manager 拓扑的 admin API 为什么 302 而不是直接返回数据？ A：manager 拓扑使用 SSOCookieProvider（KnoxSSO 联合登录），浏览器访问会跳转 KnoxSSO 登录页；脚本化访问 REST API 请使用走 ShiroProvider Basic 认证的 admin 拓扑（/gateway/admin/api/v1/version）。

Q6：启动时提示输入 master secret 或凭据库解密失败？ A：/opt/knox/data/security/master 缺失或与凭据库不匹配。首次安装先执行 knoxcli.sh create-master --master q1w2e3r4（本文演示口令，生产环境替换为强口令）；迁移数据目录时必须连带 master 文件，否则 jceks 凭据库无法解密。

十、升级、降级与多版本管理

• 升级/降级：按第三节获取目标版本包，解压到 /opt/knox-<版本>（与旧版本并存），停旧进程后把 conf/ 与 data/ 拷贝（或软链）到新版本目录，改属主后启动。2.1.0 与 2.0.x 配置兼容；跨大版本（1.x → 2.x）需核对官方 CHANGES 中的破坏性变更。
• 多版本并存：用版本化目录 + /opt/knox 软链切换（ln -sfn /opt/knox-2.1.0 /opt/knox），systemd 单元无需改动。
• 回滚：停止新版本进程，切回软链指向旧目录并启动即可。

十一、卸载方式

sudo su - knox -c "/opt/knox/bin/gateway.sh stop"    # 停止网关
sudo su - knox -c "/opt/knox/bin/ldap.sh stop"       # 停止演示 LDAP
sudo systemctl disable knox-gateway.service 2>/dev/null   # 取消开机自启（已配置过 systemd 时）
sudo systemctl disable knox-ldap.service 2>/dev/null
sudo rm -f /etc/systemd/system/knox-gateway.service /etc/systemd/system/knox-ldap.service  # 删除单元文件
sudo systemctl daemon-reload                         # 重载 systemd
sudo rm -rf /opt/knox /tmp/knox-2.1.0.tar.gz         # 删除程序与数据
sudo userdel -r knox                                 # 删除运行用户（确认无其他依赖后）

十二、参考链接

• Apache Knox 官网：https://knox.apache.org/
• 2.1.x 用户手册：https://knox.apache.org/books/knox-2-1-0/user-guide.html
• 官方下载目录：https://downloads.apache.org/knox/
• 归档下载（历史版本）：https://archive.apache.org/dist/knox/