Apache Knox 2.1.0 常用 CLI 命令与工具详解

目标：整理 Apache Knox Gateway 2.1.0 日常运维所需的全部命令行工具——gateway.sh/ldap.sh 服务管理、knoxcli.sh 全量子命令（master secret、证书、凭据别名、拓扑管理、认证测试、token 迁移）、JVM 参数验证与日志/审计排查，命令与回显均逐条实测。已在 Ubuntu 22.04.5 + OpenJDK 1.8.0_504 + Knox 2.1.0（/opt/knox，运行用户 knox）实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Java：OpenJDK 1.8.0_504；Apache Knox：2.1.0（hash 57793d31b8234863b242f766b8861c2023cbd72d）
工具位置：/opt/knox/bin（gateway.sh、ldap.sh、knoxcli.sh、gateway.jar、ldap.jar、knoxcli.jar、shell.jar）
运行用户：knox（网关禁止 root 运行，全部 CLI 建议 knox 身份执行）
实测端口：网关 8443，演示 LDAP 33389
网关实测 JVM：-Xms256m -Xmx512m（knox-env.sh 配置，jps -v 验证）

二、工具概览

工具	类型	用途
gateway.sh	服务脚本	网关启停/状态/清理（start\|stop\|status\|clean）
ldap.sh	服务脚本	演示 LDAP 启停（start\|stop\|status\|clean）
knoxcli.sh	管理命令行	master secret、证书、凭据别名、拓扑、认证测试、token 等全量管理
shell.jar / samples	客户端 SDK	KnoxShell 交互式 Groovy 环境与示例脚本（独立发布包 knoxshell，网关包内含 jar）
jps / ps	JDK 工具	验证 JVM 参数与进程状态
日志/审计	文本	gateway.log、gateway-audit.log、ldap.log 排障

knoxcli.sh 帮助总览（/opt/knox/bin/knoxcli.sh --help 实测节选，完整子命令清单如下）：

KnoxCLI {cmd} [options]
   [--help]
   [version]
   [create-master [--force] [--master mastersecret] [--generate]]
   [create-cert [--force] [--hostname h]]
   [export-cert [--type PEM|JKS|JCEKS|PKCS12]]
   [create-alias aliasname [--cluster clustername] [ (--value v) | (--generate) ]]
   [create-aliases --alias alias1 [--value value1] --alias alias2 [--value value2] --alias aliasN [--value valueN] ... [--cluster clustername] [--generate]]
   [delete-alias aliasname [--cluster clustername]]
   [list-alias [--cluster cluster1,clusterN]]
   [redeploy [--cluster clustername]]
   [list-topologies]
   [validate-topology [--cluster clustername] | [--path "path/to/file"]]
   [user-auth-test [--cluster clustername] [--u username] [--p password] [--g]]
   [system-user-auth-test [--cluster clustername] [--d]]
   [service-test [--u username] [--p password] [--cluster clustername] [--hostname name] [--port port]]
   [list-registry-clients]
   [list-provider-configs --registry-client name]
   [upload-provider-config providerConfigFile --registry-client name [--entry-name entryName]]
   [list-descriptors --registry-client name]
   [upload-descriptor descriptorFile --registry-client name [--entry-name entryName]]
   [delete-provider-config providerConfig --registry-client name]
   [delete-descriptor descriptor --registry-client name]
   [get-registry-acl entry --registry-client name]
   [convert-topology --path "path/to/topology.xml" --provider-name my-provider.json [--descriptor-name my-descriptor.json] ... ]
   [generate-jwk [--jwkAlg HS256|HS384|HS512] [--saveAlias alias] [--topology topology]]
   [generate-descriptor --service-urls-file "path/to/urls.txt" --service-name SERVICE_NAME --provider-name my-provider.json --descriptor-name my-descriptor.json [...]]
   [migrate-tokens [--progressCount num] [--verbose true|false] [--archivedMigrated true|false] [--migrateExpiredTokens true|false]]
   [create-list-aliases --alias alias1 [--value value1] ... --cluster cluster1 [--generate]]

三、前置条件

已完成 Knox 安装（《Ubuntu 22.04 安装 Apache Knox 2.1.0 指南》），master secret 已初始化。
以 knox 用户执行：su - knox 后使用 /opt/knox/bin/<工具>（或 cd /opt/knox 后 ./bin/xx.sh）。
user-auth-test/system-user-auth-test 仅对使用 ShiroProvider 的拓扑有效（实测对 SSOCookieProvider 的 manager 拓扑报错，见 6.4 节）。

四、gateway.sh 服务管理命令详解

4.1 脚本用法

/opt/knox/bin/gateway.sh

Usage: /opt/knox/bin/gateway.sh {start|stop|status|clean}

4.2 启动网关（start）

/opt/knox/bin/gateway.sh start

Starting Gateway succeeded with PID 4662.

4.3 查询状态（status）

/opt/knox/bin/gateway.sh status

运行中：

Gateway is running with PID 4662.

已停止（PID 文件存在但进程不在）：

Gateway is not running.

4.4 停止网关（stop）

/opt/knox/bin/gateway.sh stop

实测输出：

Stopping Gateway with PID 8840 failed.

⚠️ 注意：以上 failed 输出是脚本停止逻辑的边界竞态——脚本发 SIGTERM 后仅等待内置 10 秒（APP_KILL_WAIT_TIME），而 JVM 优雅关闭（undeploy 拓扑、关闭 Derby）实测约 10 秒，随后补发的 kill -s KILL 落在进程已退出之后（ESRCH）导致误报。实际进程已干净退出，确认方法：cat /opt/knox/data/gatewayServer.status 显示 STOPPED、tail /opt/knox/logs/gateway.out 出现 INFO - Derby database is closed、再查 status 显示 is not running。若优雅关闭快于 10 秒，脚本输出为 Stopping Gateway succeeded.。

4.5 清理运行文件（clean）

仅当网关已停止时清理 PID/ERR/OUT 文件；运行中执行会拒绝（实测）：

/opt/knox/bin/gateway.sh clean

Can't clean files.  Gateway is running with PID 9841.

五、ldap.sh 演示 LDAP 命令详解

5.1 脚本用法

/opt/knox/bin/ldap.sh

Usage: /opt/knox/bin/ldap.sh {start|stop|status|clean}

5.2 启动/停止演示 LDAP

/opt/knox/bin/ldap.sh start

Starting LDAP succeeded with PID 10381.

/opt/knox/bin/ldap.sh stop

LDAP 供 admin/sandbox 等拓扑认证联调；生产环境使用企业 LDAP/AD 时不启动本服务。

六、knoxcli.sh 管理命令详解

6.1 版本查看

/opt/knox/bin/knoxcli.sh version

Apache Knox: 2.1.0 (57793d31b8234863b242f766b8861c2023cbd72d)

6.2 master secret 管理

/opt/knox/bin/knoxcli.sh create-master --master q1w2e3r4

Master secret has been persisted to disk.

--generate 可随机生成；--force 覆盖已有 master（覆盖后旧凭据库不可解密，慎用）。
产物：/opt/knox/data/security/master。迁移/备份 data 目录时必须保留该文件。

6.3 证书管理

签发自签名网关证书：

/opt/knox/bin/knoxcli.sh create-cert --hostname localhost

Certificate gateway-identity has been successfully created.

导出证书分发给客户端信任（实测导出 PEM）：

/opt/knox/bin/knoxcli.sh export-cert --type PEM

Certificate gateway-identity has been successfully exported to: /opt/knox/data/security/keystores/gateway-client-trust.pem

--type 可选 PEM|JKS|JCEKS|PKCS12；导出前需已 create-cert。自签名证书场景客户端访问需 curl -k 或导入该 PEM（实测不导入时 service-test 报 PKIX 校验失败，见 Q4）。

6.4 凭据别名管理

创建别名（将后端密码等敏感值加密存入拓扑凭据库）：

/opt/knox/bin/knoxcli.sh create-alias webhdfs.pass --cluster sandbox --value hdfsP4ss

webhdfs.pass has been successfully created.

列出别名：

/opt/knox/bin/knoxcli.sh list-alias --cluster sandbox

Listing aliases for: sandbox
webhdfs.pass
encryptquerystring

2 items.

删除别名：

/opt/knox/bin/knoxcli.sh delete-alias webhdfs.pass --cluster sandbox

webhdfs.pass has been successfully deleted.

💡 说明：encryptquerystring 是网关自动生成的内置别名；--generate 参数可让 Knox 随机生成值；--cluster 不传时操作网关级凭据库。

6.5 拓扑管理

列出已部署拓扑：

/opt/knox/bin/knoxcli.sh list-topologies

List of files available in the topologies directory
/opt/knox/conf/topologies
admin
sandbox
manager
metadata
knoxsso
homepage

校验拓扑文件（按集群名或按路径）：

/opt/knox/bin/knoxcli.sh validate-topology --cluster sandbox

/opt/knox/conf/topologies/sandbox.xml
==========================================
Topology file validated successfully

手工触发重新部署（conf/topologies 下文件被监测自动部署，此命令用于强制立即生效；实测成功无输出、返回码 0）：

/opt/knox/bin/knoxcli.sh redeploy --cluster sandbox

6.6 认证连通性测试

按拓扑测试 LDAP 认证（成功用例）：

/opt/knox/bin/knoxcli.sh user-auth-test --cluster admin --u admin --p q1w2e3r4

LDAP authentication successful!

密码错误用例（实测）：

/opt/knox/bin/knoxcli.sh user-auth-test --cluster admin --u admin --p badpass

[LDAP: error code 49 - INVALID_CREDENTIALS: Bind failed: ERR_229 Cannot authenticate user uid=admin,ou=people,dc=hadoop,dc=apache,dc=org]
For more information use --d for debug output.
ERR: Unable to authenticate user: admin

⚠️ 注意：该命令仅支持 ShiroProvider 拓扑，对 SSOCookieProvider 的 manager 拓扑实测报错：

ERR: This tool currently only works with Shiro as the authentication provider.
Please update the topology to use "ShiroProvider" as the authentication provider.

6.7 服务连通性测试

/opt/knox/bin/knoxcli.sh service-test --cluster sandbox --u admin --p q1w2e3r4 --hostname localhost --port 8443

实测输出（自签名证书未信任时的典型结果，先 HTTPS 失败再降级 HTTP）：

GET https://localhost:8443/gateway/sandbox/service-test HTTP/1.1
javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
Attempting request without SSL.
GET http://localhost:8443/gateway/sandbox/service-test HTTP/1.1
org.apache.http.client.ClientProtocolException

💡 说明：HTTPS 网关端口上降级 HTTP 必然失败属预期；先按 6.3 导出并信任证书，或临时用 curl -k 直接测目标服务 URL。

6.8 token 迁移（升级场景）

/opt/knox/bin/knoxcli.sh migrate-tokens --progressCount 100 --verbose true

用于 Knox 升级后迁移旧格式 token 状态（Derby token 状态库，data/security/tokens）；新装环境无历史 token，输出为空且返回码 0。

七、JVM 参数与进程验证

确认堆配置真实生效（网关按 256–512MB 堆实测部署）：

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

等价方式：

ps -ef | grep [g]ateway.jar

knox        4662       1  1 12:33 ?        00:00:27 /usr/bin/java -Xms256m -Xmx512m -Djava.library.path=/opt/knox/ext/native -jar /opt/knox/bin/gateway.jar

八、日志与审计排查

8.1 日志文件分工

文件	内容
/opt/knox/logs/gateway.log	网关运行日志（启动、拓扑部署、认证细节）
/opt/knox/logs/gateway-audit.log	访问与转发审计（access/dispatch 两类记录）
/opt/knox/logs/gateway.err / gateway.out	stderr/stdout（含 Jersey 初始化信息、Derby 关闭提示）
/opt/knox/logs/ldap.*	演示 LDAP 日志
/opt/knox/data/gatewayServer.status	网关状态标记（STARTED/STOPPED，脚本 stop 竞态排障依据）

8.2 典型排查路径

网关启动成功依据：grep "Started gateway on port" /opt/knox/logs/gateway.log，实测行：

2026-10-11 12:49:43,215  INFO  knox.gateway (GatewayServer.java:startGateway(390)) - Started gateway on port 8443.

证书配置依据（首次启动生成自签名证书）：

2026-10-11 12:33:47,098  INFO  knox.gateway (JettySSLService.java:logAndValidateCertificate(114)) - The Gateway SSL certificate is issued to hostname: localhost.
2026-10-11 12:33:47,100  INFO  knox.gateway (JettySSLService.java:logAndValidateCertificate(117)) - The Gateway SSL certificate is valid between: 10/11/26 12:33 PM and 10/11/27 12:33 PM.

认证失败：gateway-audit.log 中 access 记录 authentication_failed，gateway.log 中 KnoxLdapRealm 报 Shiro unable to login；先用 user-auth-test（6.6）定位 LDAP 侧问题。
转发排障：gateway-audit.log 的 dispatch 行含改写后的后端 URL 与后端响应码（实测样例）：

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

九、注意事项

网关 CLI 一律以 knox 用户执行，root 运行 gateway.sh 会直接拒绝（实测报 This command /opt/knox/bin/gateway.sh must not be run as root.）。
create-master/create-alias 写加密凭据库，操作前确认 data 目录磁盘可写；--force/--generate 影响旧数据，生产变更前备份 /opt/knox/data。
validate-topology 通过仅代表语法与引用合法，不代表后端服务可达；连通性用 service-test 或 curl 实测。
knoxcli.log 记录 CLI 操作历史，审计合规场景定期归档。

十、常见问题

Q1：--help 看到的子命令执行报 command not found？ A：注意 knoxcli.sh 的子命令不带双横线（如 list-topologies 而非 --list-topologies）；参数（--cluster/--value 等）才带横线。

Q2：user-auth-test 通过但浏览器/curl 仍 401？ A：测试的是 LDAP 认证环节；401 还可能由授权 ACL（AclsAuthz 的 knox.acl）拦截。确认账号属于 ACL 允许的用户/组（admin 组成员实测可过 manager/admin 拓扑），以及密码是否与 users.ldif/企业目录一致。

Q3：redeploy 后拓扑未生效？ A：先 validate-topology 确认无语法错误；检查 data/deployments 是否生成对应 sandbox.topo.16fcdcdcfd8 目录（实测部署目录名，末尾 hash 随拓扑内容变化）；再看 gateway.log 的 topology loading 日志确认监测目录路径与预期一致（实测为 /opt/knox/conf/topologies）。

Q4：service-test 证书报错如何彻底解决？ A：create-cert --hostname gateway.example.com（替换为实际对外域名） 重建证书后重启网关，export-cert --type PEM 导出并分发给客户端导入信任库；测试期可用 curl -k 替代 service-test。

Q5：stop 提示 failed 但需要立即释放端口？ A：见 4.4 节——先确认 status/gatewayServer.status；确需强杀用 kill 8840（PID 取自 gateway.sh status 输出，实测示例；JVM 收 SIGTERM 优雅退出，实测约 10 秒），再清掉残留 /opt/knox/pids/gateway.pid 后 start。

十一、参考链接

2.1.x 用户手册（Knox CLI 章节）：https://knox.apache.org/books/knox-2-1-0/user-guide.html
Knox 官网：https://knox.apache.org/
命令总览来源：/opt/knox/bin/knoxcli.sh --help（Knox 2.1.0 实测输出）