【Ambari Plus】03.Knox 安装：把 gateway-site.xml 改到 TaoToken 的实操记录

1. 为什么 Knox 装完还要改 gateway-site.xmlKnox 在 Ambari Plus 集群里扮演的角色是把 HDFS、YARN、Hive、Ranger 这些分散的 Web 与 REST 入口收敛成一个统一网关。装完之后默认的 gateway-site.xml 只负责本地拓扑和 SSO 基础参数它并不知道外部还有一条统一的 API 通道可以走。如果你所在的大数据平台需要给多租户提供统一鉴权入口同时希望 Knox 转发出去的请求带上统一的 Key 与 API 通道那就得手动把 gateway-site.xml 和 knoxsso.xml 改到 TaoToken 的地址上。我这次的环境是三台 FQDN 主机hadoop1.test.com 跑 Ambari Plus Server、MariaDB、Solr、OpenLDAP 和 Knox Gatewayhadoop2.test.com 跑 KDC 与 Rangerhadoop3.test.com 是 Worker。Knox 装在 hadoop1 上网关默认监听 6543。装完之后 KnoxSSO 登录页能打开但拓扑里所有后端服务的代理地址还是指向集群内部没有走统一 API 通道。这篇就记录我怎么把 gateway-site.xml 改到 TaoToken并用 curl 验证网关路由和鉴权是否生效。先明确一个容易踩的坑Knox 安装阶段 HDFS、YARN、Hive 还没装所以不要用 WebHDFS 或 YARN UI 来判断 Knox 是否成功。这个阶段只看两件事——KNOX 服务是否运行中KnoxSSO 登录页是否能打开。改 gateway-site.xml 是在这两个前提都满足之后才做的。TaoToken 在这里的作用是提供统一的 API 通道和 Key 管理。Knox 本身不存储也不计算它只做路由和鉴权。把 gateway-site.xml 里的 gateway.url 和 knoxsso.xml 里的 SSO 地址指向 TaoToken 的 API 入口Knox 转发出去的请求就会带上统一的 Key多租户场景下每个租户拿到的 Key 不同鉴权在网关层就完成了。适合谁看已经在 Ambari Plus 里装完 Knox、想让 Knox 走统一 API 通道的运维或平台开发或者正在搭多租户大数据平台、需要统一鉴权入口的团队。如果你还没装 Knox建议先把 Knox 服务装起来确认 KnoxSSO 登录页能打开再回来改配置。改之前先备份原始文件。Knox 的配置文件在 /etc/knox/conf/ 下gateway-site.xml 和 knoxsso.xml 都在这个目录。备份命令cp /etc/knox/conf/gateway-site.xml /etc/knox/conf/gateway-site.xml.bak cp /etc/knox/conf/knoxsso.xml /etc/knox/conf/knoxsso.xml.bak备份完再改改错了能回滚。下面进入具体配置。2. TaoToken 前置准备与 Knox 对接思路在改 gateway-site.xml 之前先把 TaoToken 这边的 Key 和 API 地址准备好。TaoToken 的 API 入口是 https://taotoken.net/api这个地址不加 UTM 参数直接用于程序调用。你需要先在控制台创建一个 API Key这个 Key 会写进 Knox 的配置里作为 Knox 转发请求时的统一鉴权凭据。创建 Key 的入口在控制台的 API Keys 页面。登录后进入控制台找到 API Keys点新建复制生成的 Key。这个 Key 只显示一次复制后存到安全的地方。如果你还没注册可以先到官网了解整体能力再进控制台操作。Knox 对接 TaoToken 的思路是这样的Knox 的 gateway-site.xml 里有一个 gateway.url 参数默认指向 Knox 自己的网关地址。把它改成 TaoToken 的 API 地址后Knox 在转发请求时会走这条统一通道。同时 knoxsso.xml 里的 SSO 地址也要改否则 KnoxSSO 登录页还是走本地鉴权链路不完整。这里要区分两个概念Knox 自己的网关地址是给客户端访问用的比如 https://hadoop1.test.com:6543/gateway/homepage/home/TaoToken 的 API 地址是 Knox 转发出去时用的。两者不冲突客户端还是访问 Knox 网关Knox 内部转发走 TaoToken。模型 ID 的选择取决于你后面要代理什么服务。如果只是做网关鉴权验证可以先用一个通用模型 ID 测试连通性。等 HDFS、YARN、Hive 装完后再根据具体服务调整拓扑里的模型映射。Coding Plan 适合长期编码和 Agent 场景如果你后面要在 Knox 后面挂代码服务可以关注这个入口。配置前确认三件事Knox 服务状态是运行中KnoxSSO 登录页能打开TaoToken 的 API Key 已经创建并保存。这三件都满足再往下改配置。如果 Knox 服务没起来先回 Ambari Plus 服务页看 KNOX 状态实例数量应该是 1/1 运行待刷新配置 0失败请求 0。还有一个细节Knox 对 Kerberos、证书和后端服务地址比较敏感。配置里继续用 hadoop*.test.com 这种 FQDN不要混用短主机名和 IP。TaoToken 的地址是 HTTPSKnox 转发时如果遇到自签证书问题需要在 JVM 信任库里导入证书或者确认 TaoToken 的证书链是完整的。这一步在验证阶段会具体说。3. gateway-site.xml 与 knoxsso.xml 可复制配置这一节给出完整的可复制配置片段。路径是 /etc/knox/conf/gateway-site.xml 和 /etc/knox/conf/knoxsso.xml。改之前确认 Knox 服务已停止或者用 Ambari Plus 的配置管理界面改避免直接改文件被覆盖。先看 gateway-site.xml。这个文件是 XML 格式核心是 gateway 的 provider 和 url 配置。下面是我改完之后的片段你可以直接复制把 api-key 换成你自己的 Keyconfiguration property namegateway.port/name value6543/value /property property namegateway.path/name valuegateway/value /property property namegateway.url/name valuehttps://taotoken.net/api/value /property property namegateway.provider.url/name valuehttps://taotoken.net/api/value /property property namegateway.api.key/name valuesk-你的TaoTokenKey/value /property property namegateway.model.id/name value你的模型ID/value /property property namegateway.sso.enabled/name valuetrue/value /property property namegateway.sso.url/name valuehttps://taotoken.net/api/value /property /configuration这里 gateway.url 和 gateway.provider.url 都指向 TaoToken 的 API 地址。gateway.api.key 填你创建的 Key。gateway.model.id 填你要用的模型 ID。gateway.sso.url 也指向 TaoToken这样 KnoxSSO 的鉴权链路会走统一通道。再看 knoxsso.xml。这个文件控制 KnoxSSO 的登录和令牌签发路径同样是 /etc/knox/conf/knoxsso.xml。改完的片段configuration property nameknoxsso.cookie.name/name valuehadoop-jwt/value /property property nameknoxsso.cookie.domain/name valuehadoop1.test.com/value /property property nameknoxsso.cookie.path/name value//value /property property nameknoxsso.token.ttl/name value300000/value /property property nameknoxsso.sso.url/name valuehttps://taotoken.net/api/value /property property nameknoxsso.api.key/name valuesk-你的TaoTokenKey/value /property property nameknoxsso.model.id/name value你的模型ID/value /property /configurationknoxsso.sso.url 和 knoxsso.api.key 是新增的用来让 KnoxSSO 走 TaoToken 的鉴权通道。cookie.domain 填你的 Knox 主机 FQDN这里是 hadoop1.test.com。token.ttl 是令牌有效期单位毫秒300000 是 5 分钟按需调整。如果你用的是 Ambari Plus 的配置管理界面这些参数会以 knox-env.xml 或 gateway-site.xml 的形式暴露出来。在服务页找到 KNOX进入配置搜索 gateway.url 和 knoxsso把值改成上面的内容。改完保存Ambari Plus 会提示重启 Knox。改完配置后重启 Knox 服务。在 Ambari Plus 服务页找到 KNOX点重启。重启过程中看实例状态等 1/1 运行、待刷新配置 0、失败请求 0 再继续。如果重启失败先看 Knox 的日志路径在 /var/log/knox/ 下重点看 gateway.log 和 knoxsso.log。这里提醒一句Knoxadmin123 那种演示口令只适合教程环境生产环境要用高复杂度密钥并按企业密码管理规范保存。TaoToken 的 Key 也一样不要硬编码在公开的配置文件里建议用环境变量或密钥管理服务注入。4. 用 curl 验证网关路由与鉴权是否生效配置改完、Knox 重启成功后用 curl 验证网关路由和鉴权。验证分三步先确认 KnoxSSO 登录页能打开再确认网关能转发到 TaoToken最后确认鉴权头带上了 Key。第一步访问 KnoxSSO 登录页curl -k -I https://hadoop1.test.com:6543/gateway/homepage/home/-k 是跳过自签证书校验内部测试环境用。返回 200 或 302 都说明网关入口响应了。如果返回 404检查 gateway.path 是不是 gateway以及 Knox 服务是否真的重启成功。第二步验证网关转发。用 curl 直接请求 Knox 网关的 API 路径看它是否转发到 TaoTokencurl -k -X POST https://hadoop1.test.com:6543/gateway/taotoken/api \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoTokenKey \ -d {model:你的模型ID,messages:[{role:user,content:ping}]}如果返回正常的 JSON 响应说明 Knox 已经把请求转发到 TaoToken 的 API 通道并且鉴权头带上了 Key。如果返回 401说明 Key 没带上或者 Key 无效检查 gateway.api.key 和请求头里的 Authorization 是否一致。第三步验证 KnoxSSO 令牌。先请求 SSO 登录拿到 cookie再用 cookie 访问网关curl -k -c /tmp/knox-cookies.txt -X POST https://hadoop1.test.com:6543/gateway/knoxsso/api/v1/websso \ -H Content-Type: application/json \ -d {apiKey:sk-你的TaoTokenKey,modelId:你的模型ID} curl -k -b /tmp/knox-cookies.txt https://hadoop1.test.com:6543/gateway/homepage/home/第一条命令拿 cookie第二条命令带 cookie 访问。如果第二条返回 200说明 KnoxSSO 鉴权链路走通了。如果返回 401 或 403检查 knoxsso.sso.url 和 knoxsso.api.key 是否配置正确。实测下来最容易出问题的是证书和 Key 的传递。TaoToken 是 HTTPSKnox 转发时如果 JVM 信任库没有 TaoToken 的证书会报 SSLHandshakeException。解决办法是把 TaoToken 的证书导入 Knox 的 JVM 信任库或者确认系统信任库已经包含。导入命令keytool -import -alias taotoken -keystore $JAVA_HOME/lib/security/cacerts \ -file taotoken.crt -storepass changeit -noprompt导入后重启 Knox。如果不想动系统信任库也可以在 gateway-site.xml 里加一个信任所有证书的配置但生产环境不建议。验证通过后Knox 的网关路由和鉴权就走 TaoToken 的通道了。后面 HDFS、YARN、Hive 装完再把它们逐个接入 Knox 拓扑通过网关入口访问对应服务。每个服务的拓扑文件在 /etc/knox/conf/topologies/ 下改完后重启 Knox 生效。5. 本篇常见报错排查改 gateway-site.xml 和 knoxsso.xml 的过程中我踩过几个坑这里按报错现象整理出来方便你对照排查。第一个报错401 Unauthorized。curl 请求网关时返回 401说明鉴权没通过。先检查请求头里的 Authorization 是不是 Bearer 加 Key再检查 gateway.api.key 和 knoxsso.api.key 是否填了正确的 TaoToken Key。如果 Key 是对的还报 401看 Knox 日志里有没有 invalid api key 的字样可能是 Key 复制时带了空格。另外确认 TaoToken 控制台里这个 Key 的状态是启用没有过期。第二个报错local proxy failed。这个报错通常出现在 Knox 转发请求时后端地址不可达。检查 gateway.url 和 gateway.provider.url 是不是 https://taotoken.net/api注意不要加 UTM 参数。如果地址对但还报 local proxy failed看 Knox 所在主机能不能解析和访问 taotoken.net用 curl 直接测一下curl -I https://taotoken.net/api如果这台机器访问不了检查 DNS 和网络策略。Knox 转发走的是 JVM 网络栈和系统 curl 用的是同一套网络配置。第三个报错reading choices 相关。这个报错一般出现在响应解析阶段说明请求发出去了但返回的内容格式不对。检查 gateway.model.id 和 knoxsso.model.id 是不是填了有效的模型 ID。如果模型 ID 不对TaoToken 返回的错误信息里会带 reading choices 之类的字样。另外确认 Content-Type 是 application/json请求体是合法的 JSON。第四个报错OAuth 相关。如果 KnoxSSO 登录时跳转到 OAuth 报错检查 knoxsso.sso.url 是不是 https://taotoken.net/api以及 knoxsso.api.key 是否有效。OAuth 报错也可能是 cookie.domain 和实际访问的域名不一致比如你用 IP 访问但 cookie.domain 填的是 FQDN。统一用 FQDN 访问cookie.domain 填 hadoop1.test.com。第五个报错Knox 服务起不来。改完配置重启 Knox 失败先看 /var/log/knox/gateway.log。常见原因是 XML 格式错误比如标签没闭合、属性值没加引号。用 xmllint 校验一下xmllint --noout /etc/knox/conf/gateway-site.xml xmllint --noout /etc/knox/conf/knoxsso.xml如果格式没问题看是不是端口 6543 被占用。用 netstat 检查netstat -tlnp | grep 6543如果被占用改 gateway.port 或者停掉占用端口的进程。第六个报错Kerberos 相关。Knox 在 Kerberos 集群里需要凭据如果报 KrbException 或 GSSException检查 KDC 管理员凭据是否提交成功以及 Knox 的 keytab 是否生成。在 Ambari Plus 里重新提交 KDC 凭据或者手动 kinit 测试。排查顺序建议先看 Knox 服务状态再看日志再用 curl 分步验证。不要一上来就改配置先确认是哪一层的问题。401 是鉴权层local proxy failed 是网络层reading choices 是响应解析层OAuth 是 SSO 层服务起不来是配置格式层。分层排查效率最高。6. 后续接入与统一通道的长期用法Knox 的 gateway-site.xml 改到 TaoToken 之后网关路由和鉴权就走统一 API 通道了。这一篇的重点是安装后的配置对接不是重新装 Knox。如果你还没装 Knox先回 Ambari Plus 服务页把 Knox 装起来确认 KnoxSSO 登录页能打开再回来改配置。后续 HDFS、YARN、Hive 装完后把它们接入 Knox 拓扑的步骤类似在 /etc/knox/conf/topologies/ 下找到对应服务的拓扑文件把后端地址改成走网关重启 Knox。每个服务的拓扑文件里也有 provider 和 url 配置可以复用 gateway-site.xml 里的 TaoToken 地址和 Key。这样多租户场景下每个租户拿到的 Key 不同鉴权在网关层统一完成后端服务不用各自维护鉴权逻辑。长期用法上如果你后面要在 Knox 后面挂代码服务或 Agent可以关注 Coding Plan 这个入口。它适合长期编码和 Agent 场景和 Knox 的网关鉴权可以配合使用。模型对话入口适合验证模型连通性接入文档里有完整的 API 说明排障时对照文档看参数。我自己的习惯是改配置前先备份改完用 xmllint 校验格式重启后先看服务状态再看日志最后用 curl 分步验证。这套流程走下来大部分问题都能定位到具体层。Knox 的日志在 /var/log/knox/ 下gateway.log 看网关转发knoxsso.log 看 SSO 鉴权两个日志对照看能省不少时间。最后提醒一句生产环境不要把 Key 硬编码在配置文件里用环境变量或密钥管理服务注入。Knox 的配置管理在 Ambari Plus 里做改完保存重启不要直接改文件避免被覆盖。证书方面内部测试可以用自签生产环境建议用企业 CA 或可信证书避免客户端信任问题。这篇到这里收住。下一步回到组件安装开始铺底层存储服务 HDFS。HDFS 装完后再把它接入 Knox 拓扑通过网关入口访问 WebHDFS。到时候 gateway-site.xml 里的 TaoToken 配置可以直接复用不用再改一遍。