Apache SeaTunnel Zeta Engine Basic Auth 认证机制详解

近期在排查 Apache SeaTunnel Zeta Engine REST API 认证机制时，遇到了一个典型且容易忽略的错误。

现象非常直接：Zeta Engine 已正常启动，REST 服务也在对应端口上监听，但一旦请求 /overview、/running-jobs、/job-info 等接口，立刻返回如下错误：

HTTP/1.1 401 Unauthorized

初次见到这个 401 错误，多数人的第一直觉是检查服务是否启动、端口配置是否正确、接口路径是否有误。

但实际上，绝大多数情况下，这个问题都源于 SeaTunnel Zeta Engine 的 Basic Auth 认证配置。

一旦启用了 Basic Auth，客户端调用 REST API 时就不能再像之前那样无限制访问，而必须在请求头中携带正确的认证凭证。

本文将从 401 错误入手，详细梳理 SeaTunnel Zeta Engine 中 Basic Auth 认证机制的工作原理，并给出客户端正确连接的方式。

1. 问题现象：访问 Zeta REST API 返回 401 Unauthorized

假设直接访问 Zeta Engine 的 REST API（例如使用 curl 命令）：

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 请求头中添加认证信息：

Authorization: Basic base64(username:password)

例如，当用户名为 admin、密码为 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

3. 配置详解：enable-basic-auth、username、password 如何生效

Basic Auth 相关的核心配置主要有三个：

默认情况下：

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

如果该值为 false，Zeta Engine 的 REST API 将不要求客户端携带认证信息。

如果为 true，所有被 BasicAuthFilter 保护的请求都必须通过认证。

一个示例配置大致如下：

seatunnel {
  engine {
    http {
      enable-http = true
      port = 8080      enable-basic-auth = true
      basic-auth-username = "admin"
      basic-auth-password = "admin"
    }
  }
}

开启后，普通请求将会失败：

curl 

返回：

401 Unauthorized

正确的请求方式为：

curl -u admin:admin 

或者显式添加 Header：

curl 
  -H "Authorization: Basic YWRtaW46YWRtaW4=" 
  

这里的 YWRtaW46YWRtaW4= 正是 admin:admin 的 Base64 编码。

4. 客户端实践：如何通过 Authorization Header 连接

理解了服务端的认证逻辑后，客户端需要做的事情就很明确了。

只要 Zeta Engine 开启了 Basic Auth，客户端在请求 REST API 时必须携带：

Authorization: Basic base64(username:password)

如果使用 Java 代码访问，可以直接利用 Spring 的 HttpHeaders#setBasicAuth。

例如：

HttpHeaders headers = new HttpHeaders();
headers.setBasicAuth("admin", "admin", StandardCharsets.UTF_8);HttpEntity entity = new HttpEntity<>(headers);ResponseEntity

这段代码会自动生成 Basic Auth 请求头，无需手动进行 Base64 编码。

若希望封装得更通用，可将认证逻辑独立为一个方法：

private void applyBasicAuth(HttpHeaders headers, String username, String password) {
    if (username == null || username.trim().isEmpty()) {
        return;
    }    if (password == null || password.trim().isEmpty()) {
        return;
    }    headers.setBasicAuth(
            username.trim(),
            password,
            StandardCharsets.UTF_8
    );
}

然后在每次请求 Zeta REST API 前统一调用：

HttpHeaders headers = new HttpHeaders();
headers.setAccept(Collections.singletonList(MediaType.APPLICATION_JSON));applyBasicAuth(headers, username, password);

这样无论是 GET 请求：

restTemplate.exchange(
        "http://localhost:8080/running-jobs",
        HttpMethod.GET,
        new HttpEntity(null, headers),
        List.class
);

还是 POST 请求：

restTemplate.exchange(
        "http://localhost:8080/submit-job",
        HttpMethod.POST,
        new HttpEntity<>(configText, headers),
        Map.class
);

都能统一携带认证信息。

这正体现了客户端连接开启了 Basic Auth 的 Zeta Engine 时最核心的一点：REST API 本身未变，接口路径不变，只是请求头中必须包含 Authorization。

5. 可视化体验：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 问题。

核心可总结为以下几点：

1. enable-basic-auth 默认值为 false，未开启时 REST API 无需认证。
2. 一旦开启 Basic Auth，Zeta Engine 会通过 BasicAuthFilter 拦截所有请求。
3. 客户端必须在请求头中携带 Authorization: Basic xxx。
4. xxx 是 username:password 的 Base64 编码。
5. basic-auth-username 和 basic-auth-password 默认均为 admin。
6. SeaTunnel Web 可将该过程可视化，让用户通过页面配置完成认证连接。

因此，再次遇到：

401 Unauthorized

不必急于怀疑 Zeta Engine 未启动，也不要只盯着端口和接口路径。

更值得优先确认的是：

1. 是否开启了 enable-basic-auth
2. 客户端是否携带 Authorization 请求头
3. 用户名和密码是否与配置一致

理清这些问题后，再审视 SeaTunnel Zeta Engine 的 REST API 认证流程，便会清晰很多。

写在最后

SeaTunnel Web 是一个持续完善的可视化项目，目标是将数据源管理、Zeta Engine 连接、任务配置、运行日志和指标查看等常用能力打造得更直观、更易上手。如果你也在学习 SeaTunnel，或者从事数据同步、数据集成相关工作，欢迎一起交流。