Apache SeaTunnel Zeta Engine 的 Basic Auth 如何工作？

作者：技术拾光

时间：2026-06-27

在排查 Apache SeaTunnel Zeta Engine 的 REST API 认证逻辑时，我们发现了一个常见但容易忽视的问题。现象十分直接：Zeta Engine 已经正常启动，REST 服务也在监听指定端口，但当我们访问 /overview、/running-jobs、/job-inf

文章目录

在排查 Apache SeaTunnel Zeta Engine 的 REST API 认证逻辑时，我们发现了一个常见但容易忽视的问题。

现象十分直接：Zeta Engine 已经正常启动，REST 服务也在监听指定端口，但当我们访问 /overview、/running-jobs、/job-info 等接口时，却收到以下响应：

HTTP/1.1 401 Unauthorized

初次遇到这种情况，大多数人首先会检查服务是否启动、端口是否正确、接口路径是否拼写错误。

然而，这类问题通常与 SeaTunnel Zeta Engine 的 Basic Auth 配置密切相关。

一旦 Basic Auth 被开启，客户端在调用 REST API 时就不能再像以前那样随意请求，必须在请求头中携带正确的认证信息。

本文将从 401 错误入手，详细解析 SeaTunnel Zeta Engine 的 Basic Auth 机制如何工作，以及客户端如何正确完成连接。

1. 现象描述：访问 Zeta REST API 返回 401

假设我们直接通过 curl 访问 Zeta Engine 的 REST API：

curl

如果 Basic Auth 未开启，该请求可以正常返回 Zeta Engine 的概要信息。

但一旦配置文件启用了 Basic Auth，而请求未包含认证信息，就会变成如下结果：

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="SeaTunnel Web UI"

这表明请求已成功到达 Zeta Engine，但在进入实际的 REST Servlet 之前，被认证过滤器拦截。

总结起来就是：

Zeta Engine 正常运行
REST API 地址正确
但客户端未携带 Authorization 请求头
因此被 BasicAuthFilter 拦截并返回 401

Basic Auth 本身并不复杂，本质就是在 HTTP Header 中添加一段认证信息：

Authorization: Basic base64(username:password)

例如，用户名和密码均为 admin 时，客户端需要将：

admin:admin

进行 Base64 编码，然后放入 Authorization 请求头中。

2. 源码分析：BasicAuthFilter 如何拦截请求

SeaTunnel Zeta Engine 的 Basic Auth 核心逻辑位于 BasicAuthFilter 类中。

它实现了标准的 Servlet Filter：

public class BasicAuthFilter implements Filter {
    private final HttpConfig httpConfig;    public BasicAuthFilter(HttpConfig httpConfig) {
        this.httpConfig = httpConfig;
    }
}

Filter 的特点是：请求在进入真正的 Servlet 之前会先经过过滤器，因此认证逻辑统一在过滤器中完成，而不是分散在各个接口中。

核心代码位于 doFilter 方法中。

首先，它会判断 Basic Auth 是否开启：

if (!httpConfig.isEnableBasicAuth()) {
    chain.doFilter(request, response);
    return;
}

逻辑很直接——未开启认证，请求直接放行。

如果开启了，代码继续执行，开始读取 HTTP 请求头：

HttpServletRequest httpRequest = (HttpServletRequest) request;
HttpServletResponse httpResponse = (HttpServletResponse) response;String authHeader = httpRequest.getHeader("Authorization");

接着判断请求头是否存在，以及是否以 "Basic " 开头：

if (authHeader != null && authHeader.startsWith("Basic ")) {
    String base64Credentials = authHeader.substring("Basic ".length());
    String credentials =
            new String(Base64.decodeBase64(base64Credentials), StandardCharsets.UTF_8);    final String[] values = credentials.split(":", 2);
}

这里执行了以下操作：从请求头获取 Authorization 内容，去掉 "Basic " 前缀，对剩余部分进行 Base64 解码，然后将解码后的字符串按冒号分割成用户名和密码。

例如，如果请求头为：

Authorization: Basic YWRtaW46YWRtaW4=

解码后得到：

admin:admin

然后将此结果与配置文件中的用户名密码进行比较：

if (username.equals(httpConfig.getBasicAuthUsername())
        && password.equals(httpConfig.getBasicAuthPassword())) {
    chain.doFilter(request, response);
    return;
}

如果两者匹配，请求放行。

如果请求头不存在、格式不正确或账号密码不匹配，则返回 401：

httpResponse.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 Unauthorized