SeaTunnel Zeta Engine 的 Basic Auth 是怎么工作的？

最近在看 SeaTunnel Zeta Engine 的 REST API 认证逻辑时遇到一个很典型的问题Zeta Engine 明明已经启动了REST 服务也正常监听端口但是访问/overview、/running-jobs、/job-info这些接口时却返回了HTTP/1.1 401 Unauthorized如果只是第一次看到这个错误很容易以为是服务没有启动、端口写错了或者接口路径不对。但实际上这类问题很多时候和 SeaTunnel Zeta Engine 的 Basic Auth 配置有关。当 Zeta Engine 开启 Basic Auth 后客户端再访问 REST API就不能像之前一样直接请求接口而是必须在请求头里带上正确的认证信息。这篇文章就从这个 401 问题开始简单看一下 SeaTunnel Zeta Engine 的 Basic Auth 是怎么工作的以及客户端应该如何正确连接。1. 先说现象访问 Zeta REST API 返回 401假设我们直接访问 Zeta Engine 的 REST APIcurlhttp://localhost:8080/overview如果没有开启 Basic Auth这个请求可以正常返回 Zeta Engine 的概要信息。但是当配置里开启 Basic Auth 后如果请求没有携带认证信息就会返回HTTP/1.1 401 Unauthorized WWW-Authenticate: Basic realmSeaTunnel Web UI这说明请求已经到达了 Zeta Engine但在进入真正的 REST Servlet 之前被认证过滤器拦截了。也就是说Zeta Engine 正常运行 REST API 地址也没有问题 但是客户端没有带 Authorization 请求头 所以被 BasicAuthFilter 拦截并返回 401Basic Auth 本身并不复杂它本质上就是在 HTTP Header 中增加一段认证信息Authorization: Basic base64(username:password)例如用户名是admin密码是admin客户端最终需要把admin:admin做 Base64 编码然后放到Authorization请求头里。2. 看源码BasicAuthFilter 如何拦截请求SeaTunnel Zeta Engine 的 Basic Auth 核心逻辑在BasicAuthFilter中。这个类实现了标准的 ServletFilterpublicclassBasicAuthFilterimplementsFilter{privatefinalHttpConfighttpConfig;publicBasicAuthFilter(HttpConfighttpConfig){this.httpConfighttpConfig;}}Filter 的特点是请求进入真正的 Servlet 之前会先经过过滤器。所以 Basic Auth 的认证逻辑并不是写在某一个具体接口里而是在统一的过滤器中完成的。核心代码在doFilter方法里。首先它会判断是否开启 Basic Authif(!httpConfig.isEnableBasicAuth()){chain.doFilter(request,response);return;}这段代码很关键。如果没有开启 Basic Auth请求会直接放行chain.doFilter(request,response);也就是说enable-basic-auth没有开启时REST API 不需要认证。如果开启了 Basic Auth代码会继续往下走开始读取 HTTP 请求头HttpServletRequesthttpRequest(HttpServletRequest)request;HttpServletResponsehttpResponse(HttpServletResponse)response;StringauthHeaderhttpRequest.getHeader(Authorization);然后判断请求头是否存在并且是否以Basic开头if(authHeader!nullauthHeader.startsWith(Basic )){Stringbase64CredentialsauthHeader.substring(Basic .length());StringcredentialsnewString(Base64.decodeBase64(base64Credentials),StandardCharsets.UTF_8);finalString[]valuescredentials.split(:,2);}这里做了几件事从请求头中取出Authorization去掉前面的Basic对后面的内容进行 Base64 解码将解码后的字符串按:拆分成用户名和密码比如请求头是Authorization: Basic YWRtaW46YWRtaW4解码后就是admin:admin然后代码会和配置中的用户名、密码进行比较if(username.equals(httpConfig.getBasicAuthUsername())password.equals(httpConfig.getBasicAuthPassword())){chain.doFilter(request,response);return;}如果用户名和密码都正确请求继续放行。如果请求头不存在、格式不正确、用户名密码不匹配就会返回 401httpResponse.setHeader(WWW-Authenticate,Basic realm\SeaTunnel Web UI\);httpResponse.sendError(HttpServletResponse.SC_UNAUTHORIZED,Unauthorized);所以 BasicAuthFilter 的整体流程可以理解成请求进入 Zeta REST 服务 ↓ 判断是否开启 Basic Auth ↓ 未开启直接放行 ↓ 已开启读取 Authorization 请求头 ↓ 解析 Basic Auth 用户名和密码 ↓ 和配置中的 username/password 比较 ↓ 匹配成功放行 匹配失败返回 401 Unauthorized3. 看配置enable-basic-auth、username、password 如何生效Basic Auth 相关的核心配置主要有三个参数是否必填说明enable-basic-authNo是否开启 Basic Auth默认是falsebasic-auth-usernameNoBasic Auth 用户名默认是adminbasic-auth-passwordNoBasic Auth 密码默认是admin也就是说默认情况下enable-basic-auth false basic-auth-username admin basic-auth-password admin这里要注意一点虽然basic-auth-username和basic-auth-password默认都是admin但是如果enable-basic-auth没有开启它们并不会生效。真正决定是否启用认证的是enable-basic-auth如果它是falseZeta Engine 的 REST API 不会要求客户端携带 Basic Auth。如果它是true所有被 BasicAuthFilter 保护的请求都需要认证。一个示例配置大概是这样seatunnel { engine { http { enable-http true port 8080 enable-basic-auth true basic-auth-username admin basic-auth-password admin } } }开启后普通请求就会失败curlhttp://localhost:8080/overview返回401 Unauthorized正确的访问方式应该是curl-uadmin:admin http://localhost:8080/overview或者显式传递 Headercurl\-HAuthorization: Basic YWRtaW46YWRtaW4\http://localhost:8080/overview这里的YWRtaW46YWRtaW4就是admin:admin的 Base64 编码。4. 看客户端如何通过 Authorization Header 连接理解了服务端的认证逻辑后客户端要做的事情就很明确了只要 Zeta Engine 开启了 Basic Auth客户端请求 REST API 时就必须带上Authorization: Basic base64(username:password)如果用 Java 代码访问可以直接使用 Spring 的HttpHeaders#setBasicAuth。例如HttpHeadersheadersnewHttpHeaders();headers.setBasicAuth(admin,admin,StandardCharsets.UTF_8);HttpEntityVoidentitynewHttpEntity(headers);ResponseEntityMapresponserestTemplate.exchange(http://localhost:8080/overview,HttpMethod.GET,entity,Map.class);这段代码会自动生成 Basic Auth 请求头不需要我们手动做 Base64 编码。如果想封装得更通用一点可以把认证逻辑独立成一个方法privatevoidapplyBasicAuth(HttpHeadersheaders,Stringusername,Stringpassword){if(usernamenull||username.trim().isEmpty()){return;}if(passwordnull||password.trim().isEmpty()){return;}headers.setBasicAuth(username.trim(),password,StandardCharsets.UTF_8);}然后每次请求 Zeta REST API 前都统一调用HttpHeadersheadersnewHttpHeaders();headers.setAccept(Collections.singletonList(MediaType.APPLICATION_JSON));applyBasicAuth(headers,username,password);这样无论是 GET 请求restTemplate.exchange(http://localhost:8080/running-jobs,HttpMethod.GET,newHttpEntityVoid(null,headers),List.class);还是 POST 请求restTemplate.exchange(http://localhost:8080/submit-job,HttpMethod.POST,newHttpEntity(configText,headers),Map.class);都可以统一带上认证信息。这也是客户端连接开启 Basic Auth 的 Zeta Engine 时最核心的一点不是 REST API 变了 也不是接口路径变了 只是请求头中必须多一个 Authorization5. 最后补充SeaTunnel Web 如何把这一步可视化前面讲的是 SeaTunnel Zeta Engine 层面的 Basic Auth 逻辑。如果直接用代码连接我们需要自己维护Zeta Engine 地址 端口 是否开启 Basic Auth 用户名 密码然后在每次请求 REST API 时把认证信息加到请求头里。但对于很多使用者来说他们并不希望每次都手动写代码、拼 Header、测试接口。所以在 SeaTunnel Web 中可以把这一步做成可视化配置。比如新增一个 Zeta Engine 客户端时页面上可以提供这些配置项Client Name Engine Type Client Address Client Port Enable Basic Auth Username Password当用户开启 Basic Auth并填写用户名密码后SeaTunnel Web 在请求 Zeta REST API 时自动补充Authorization: Basic xxx这样用户点击“测试连接”时背后实际访问的还是 Zeta Engine 的/overview接口只是 SeaTunnel Web 帮用户把认证请求头处理好了。保存客户端后后续访问这些接口/overview /running-jobs /job-info /finished-jobs /submit-job /submit-job/upload /stop-job /metrics也都可以基于保存的客户端配置自动带上 Basic Auth。这样做的好处是SeaTunnel Zeta Engine 仍然保持原有的 REST 认证机制 SeaTunnel Web 只是把认证配置可视化 用户不需要关心 Authorization Header 的细节小结SeaTunnel Zeta Engine 的 Basic Auth 逻辑并不复杂但它很容易在第一次使用时造成 401 问题。核心可以总结成几句话enable-basic-auth默认是false不开启时 REST API 不需要认证。开启 Basic Auth 后Zeta Engine 会通过BasicAuthFilter拦截请求。客户端必须在请求头中携带Authorization: Basic xxx。xxx是username:password的 Base64 编码。basic-auth-username和basic-auth-password默认都是admin。SeaTunnel Web 可以把这个过程可视化让用户通过页面配置完成认证连接。所以当我们遇到401 Unauthorized不要第一时间怀疑 Zeta Engine 没启动也不要只看端口和接口路径。更应该先确认是否开启了 enable-basic-auth 客户端是否带了 Authorization 请求头 用户名和密码是否和配置一致理解了这一点再看 SeaTunnel Zeta Engine 的 REST API 认证流程就会清楚很多。写在最后SeaTunnel Web 是我正在持续完善的一个 SeaTunnel 可视化项目希望把数据源管理、Zeta Engine 连接、任务配置、运行日志和指标查看这些常用能力做得更直观、更容易上手。项目地址https://github.com/weifuwan/seatunnel-web里面有体验地址、部署文档、社区交流群如果你也在学习 SeaTunnel或者正在做数据同步、数据集成相关的事情也欢迎一起交流。这里有一群上进的小伙伴也有一群爱分享的大佬。大家可以一起讨论问题、分享实践、完善文档也一起把 SeaTunnel 这件事讲得更清楚、做得更好用。