Apache Knox 2.1.0 配置参数详解

目标：系统梳理 Apache Knox Gateway 2.1.0 的配置体系——gateway-site.xml 网关服务参数、topology 拓扑 XML 与提供者（ShiroProvider 认证、AclsAuthz 授权、SSOCookieProvider 联合登录、WebAppSec）、演示 LDAP 与用户数据（users.ldif）、knox-env.sh JVM 内存参数、日志配置，并给出可直接落地的生产拓扑模板。已在 Ubuntu 22.04.5 + OpenJDK 1.8.0_504 + Knox 2.1.0（/opt/knox）实测环境整理，默认值均取自实测安装的配置文件。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Java：OpenJDK 1.8.0_504
• Apache Knox：2.1.0（hash 57793d31b8234863b242f766b8861c2023cbd72d）
• 安装目录：/opt/knox；配置目录 /opt/knox/conf；数据目录 /opt/knox/data
• 实测网关端口 8443、演示 LDAP 端口 33389
• 默认拓扑：admin、manager、knoxsso、homepage、metadata、sandbox（共 6 个，knoxcli.sh list-topologies 实测列出）

二、前置条件

• 已按《Ubuntu 22.04 安装 Apache Knox 2.1.0 指南》完成安装并启动网关（参数修改验证需要运行中的 Knox）。
• 熟悉 XML 基本语法；理解 Knox 的「拓扑 = 提供者链 + 服务集群定义」模型。

三、参数查看与修改方式

修改后验证：

/opt/knox/bin/knoxcli.sh validate-topology --cluster sandbox   # 拓扑语法校验
/opt/knox/bin/knoxcli.sh redeploy --cluster sandbox            # 手工触发重新部署（成功无输出，返回码 0）

实测校验回显：

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

四、参数总览

Knox 配置分四个层次，优先级从高到低：拓扑 XML 内联提供者 > 共享提供者 JSON（被描述符引用）> gateway-site.xml 网关全局 > 代码内置默认（gateway-default.xml，随 jar 分发）。实测 gateway-site.xml 中的参数分组：

五、核心参数分类详解

5.1 网关服务参数（gateway-site.xml）

JVM 内存参数（/opt/knox/bin/knox-env.sh，实测默认全部注释，本文改为网关 256–512MB）：

生效验证（实测回显，jps -v）：

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

5.2 拓扑 XML 与提供者参数

拓扑文件位于 /opt/knox/conf/topologies/<名称>.xml，结构为 <topology><gateway><provider>…</provider></gateway><service>…</service></topology>。提供者按 role 顺序执行：webappsec → federation/authentication → identity-assertion → authorization → hostmap。

认证：ShiroProvider（Basic 认证 + LDAP，admin/sandbox 拓扑实测配置）

授权：AclsAuthz

manager 拓扑（Knox 管理台）实测使用 knox.acl = KNOX_ADMIN_USERS;KNOX_ADMIN_GROUPS;*，即授信 Knox 管理员用户/组（对应 gateway.knox.admin.groups=admin）。

联合登录：SSOCookieProvider（manager 拓扑实测）

配套的 knoxsso 拓扑提供表单登录（knoxauth 应用），实测访问 /gateway/manager/admin/api/v1/version 未登录时 302 跳转：

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

WebAppSec（manager 拓扑实测）：csrf.enabled=true（csrf.customHeader=X-XSRF-Header，GET/OPTIONS/HEAD 免校验）、xframe.options.enabled=true、xss.protection.enabled=true、strict.transport.enabled=false。

身份断言：HadoopGroupProvider（manager 拓扑实测）：CENTRAL_GROUP_CONFIG_PREFIX=gateway.group.config.，将组映射配置集中到 gateway-site（见 5.3）。

服务定义（<service> 段）：role 指定服务类型，url 指定后端地址。sandbox 拓扑实测片段：

<service>
    <role>WEBHDFS</role>
    <url>http://localhost:50070/webhdfs</url>
</service>

经网关访问 https://host:8443/gateway/sandbox/webhdfs/v1/?op=LISTSTATUS 时，Knox 改写 URL、附加 user.name 身份参数后转发（审计日志实测：dispatch|uri|http://localhost:50070/webhdfs/v1/?op=LISTSTATUS&user.name=admin|success|Response status: 200）。

5.3 演示 LDAP 与组映射参数

gateway-site.xml 实测内含 HadoopGroupProvider 的中央组映射配置（前缀 gateway.group.config.）：

演示用户数据（/opt/knox/conf/users.ldif 实测结构）：people 分支下 guest/sam/tom/admin 四个用户，groups 分支下 analyst（sam、tom）、scientist（sam）、admin（admin）三组。认证与组的组合决定 AclsAuthz 与 manager 拓扑的访问权。

⚠️ 注意：ldap.bind.password 在默认文件中为明文，生产环境应改用凭据别名（knoxcli.sh create-alias 存入 jceks，配置里引用 ${alias=…} 形式）。

5.4 日志配置

• /opt/knox/conf/gateway-log4j2.xml：网关 Log4j2 配置，滚动日志输出到 /opt/knox/logs/gateway.log；审计独立于 gateway-audit.log。
• /opt/knox/logs 实测文件：gateway.log（运行日志）、gateway-audit.log（访问审计）、gateway.err/gateway.out（stdout/stderr）、ldap.log/ldap.err/ldap.out（演示 LDAP）、knoxcli.log（CLI 操作）。
• 审计日志字段（实测样例行）：时间 ||请求ID|audit|来源IP|服务角色|用户|||动作|uri|结果|详情，排障时先看 access/dispatch 两类记录定位认证与转发环节。

六、生产配置模板

适用场景：8–16GB 内存服务器、SSD 磁盘、为企业 LDAP 后端 + WebHDFS/YARN UI 提供网关入口，网关 JVM 限 256–512MB 堆。

/opt/knox/conf/gateway-site.xml 生产关键项（在默认文件基础上修改）：

<configuration>
    <property><name>gateway.port</name><value>8443</value></property>
    <property><name>gateway.path</name><value>gateway</value></property>
    <property><name>gateway.websocket.feature.enabled</name><value>true</value></property>
    <property><name>gateway.scope.cookies.feature.enabled</name><value>true</value></property>
    <property><name>gateway.knox.admin.groups</name><value>knox-admin</value></property>
    <property><name>gateway.dispatch.whitelist</name><value>^https?:\/\/(nn\.hadoop\.example\.com|rm\.hadoop\.example\.com):[0-9]{1,5}$</value></property>
</configuration>

/opt/knox/conf/topologies/production.xml（企业 LDAP + Basic 认证 + ACL + WebHDFS/YARN UI 模板）：

<topology>
    <name>production</name>
    <gateway>
        <provider>
            <role>authentication</role>
            <name>ShiroProvider</name>
            <enabled>true</enabled>
            <param><name>sessionTimeout</name><value>30</value></param>
            <param><name>main.ldapRealm</name><value>org.apache.knox.gateway.shirorealm.KnoxLdapRealm</value></param>
            <param><name>main.ldapRealm.userDnTemplate</name><value>uid={0},ou=people,dc=example,dc=com</value></param>
            <param><name>main.ldapRealm.contextFactory.url</name><value>ldap://ldap.example.com:389</value></param>
            <param><name>main.ldapRealm.contextFactory.authenticationMechanism</name><value>simple</value></param>
            <param><name>urls./**</name><value>authcBasic</value></param>
        </provider>
        <provider>
            <role>authorization</role>
            <name>AclsAuthz</name>
            <enabled>true</enabled>
            <param><name>knox.acl</name><value>hdfs-users;hadoop-users;10.0.0.0/24</value></param>
        </provider>
        <provider>
            <role>identity-assertion</role>
            <name>Default</name>
            <enabled>true</enabled>
        </provider>
        <provider>
            <role>hostmap</role>
            <name>static</name>
            <enabled>true</enabled>
            <param><name>localhost</name><value>nn.hadoop.example.com</value></param>
        </provider>
    </gateway>
    <service>
        <role>WEBHDFS</role>
        <url>http://nn.hadoop.example.com:50070/webhdfs</url>
    </service>
    <service>
        <role>RESOURCEMANAGER</role>
        <url>http://rm.hadoop.example.com:8088/ws</url>
    </service>
</topology>

落地与验证：

/opt/knox/bin/knoxcli.sh validate-topology --path /opt/knox/conf/topologies/production.xml
/opt/knox/bin/knoxcli.sh list-topologies
curl -s -k -u admin:q1w2e3r4 "https://localhost:8443/gateway/production/webhdfs/v1/?op=LISTSTATUS"
# 账号取能通过该拓扑认证的用户；演示目录实测 admin/q1w2e3r4，企业 LDAP 换实际账号

内存与磁盘标注：网关 JVM -Xms256m -Xmx512m（小流量网关足够，>500 QPS 建议 1–2GB 并同步调大 KNOX_GATEWAY_MEM_OPTS）；data/deployments 随拓扑数增长，SSD 保留 5GB 空余；日志按 gateway-log4j2.xml 滚动策略预留 10GB。

七、常见问题

Q1：修改 gateway-site.xml 后端口没变？ A：gateway.port 属启动期参数，需 gateway.sh stop/start 重启网关生效；topologies/*.xml 才是保存即自动重部署。

Q2：拓扑部署失败或服务 503？ A：先校验语法 knoxcli.sh validate-topology --cluster sandbox，再看 data/deployments/sandbox.topo.16fcdcdcfd8（实测部署目录名，末尾 hash 随拓扑内容变化） 是否生成；后端地址不可达时网关本身仍正常，转发才报错——用审计日志的 dispatch 行区分网关问题与后端问题。

Q3：LDAP 认证一直失败（401）？ A：逐项核对 ShiroProvider 的 contextFactory.url 可达性（curl telnet://ldap-host:389 或 nc -zv）、userDnTemplate 与目录结构是否匹配；用 knoxcli.sh user-auth-test --cluster admin --u admin --p q1w2e3r4 复现，密码错误实测输出 [LDAP: error code 49 - INVALID_CREDENTIALS: Bind failed: ERR_229 ...]。

Q4：UI 类服务跳转被拒或白页？ A：gateway.dispatch.whitelist 默认只放行 localhost，生产必须加入后端主机域名；同时浏览器经网关访问 UI 需要时钟同步与 Cookie 作用域配置正确。

Q5：如何把明文密码改成别名引用？ A：knoxcli.sh create-alias ldap.bind.password --cluster sandbox --value hdfsP4ss（实测示例值） 后，将配置值改为 ${alias=ldap.bind.password} 形式；凭据存于 data/security/keystores 下对应拓扑 jceks。

八、参考链接

• 2.1.x 用户手册（Gateway Details/Configuration 章节）：https://knox.apache.org/books/knox-2-1-0/user-guide.html
• 官方默认 gateway-site.xml 参考：Knox 2.1.0 安装包 conf/gateway-site.xml（本文默认值来源）
• Knox 官网：https://knox.apache.org/