StackSaga TraceWindow 连接器概述 (Connector Overview)

概述 (Overview)

StackSaga TraceWindow 连接器 (Connector) 是一个内嵌式客户端库，用于让您的编排器 (Orchestrator) 微服务能够安全地与 StackSaga TraceWindow 控制台通信。

它负责暴露内部 /stacksaga/* REST 管理端点，强制执行双令牌安全策略，支持可选的次级端口与 TLS 隔离，并从您本地的事务事件存储 (Event-Store) 中提取执行轨迹日志。

核心能力 (Key Capabilities)

  • 通用事件存储访问 (Universal Event-Store Access)： 暴露标准化的内部端点，供 TraceWindow 从任何 支持的数据库实现 中拉取 Saga 事务追踪数据。

  • 双技术栈支持 (Dual Stack Support)： 为 Spring MVC (Servlet 阻塞栈) 与 Spring WebFlux (Netty 反应式非阻塞栈) 分别提供专门的原生连接器。

  • 双运行安全模式 (Dual Security Operating Modes)： 支持无需 Token 的本地开发模式 (secure-api=false)，以及集成了 StackSaga Central RBAC 权限控制的生产双令牌校验模式 (secure-api=true)。

  • 独立端口与 SSL 隔离 (Port & SSL Isolation)： 允许通过 Spring Boot SSL Bundles 在专属的独立次级端口上启用自定义 TLS 证书运行追踪端点。

  • 敏捷连接拓扑 (Topological Agility)： 完美支持 直连模式 (Direct Mode) ({host:port}/{api-path}) 与自带自动化 CORS 处理的 网关模式 (Gateway Mode) ({host:port}/{service-name}/{api-path})。

添加连接器依赖 (Adding the Connector Dependency)

要将 TraceWindow 集成到您的编排器服务中，请在 pom.xml 中引入与您技术栈相匹配的依赖：

这两个依赖都会自动传递引入 stacksaga-trace-window-connector-api。您只需根据所选的 Web 运行时声明其中一个连接器依赖即可。

stacksaga-trace-window-connector-servlet (Spring MVC)

适用于标准的 Spring Boot Web (Tomcat / Jetty / Undertow) 应用程序：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.stacksaga</groupId>
            <artifactId>stacksaga-bom</artifactId>
            <version>1.0.0-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- 适用于 Spring MVC 的 StackSaga TraceWindow 连接器 -->
    <dependency>
        <groupId>org.stacksaga</groupId>
        <artifactId>stacksaga-trace-window-connector-servlet</artifactId>
    </dependency>
</dependencies>

stacksaga-trace-window-connector-webflux (Spring WebFlux)

适用于运行在 Netty 上的反应式非阻塞编排器服务：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.stacksaga</groupId>
            <artifactId>stacksaga-bom</artifactId>
            <version>1.0.0-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- 适用于 Spring WebFlux 的 StackSaga TraceWindow 连接器 -->
    <dependency>
        <groupId>org.stacksaga</groupId>
        <artifactId>stacksaga-trace-window-connector-webflux</artifactId>
    </dependency>
</dependencies>

配置属性参考手册 (Configuration Properties Reference)

所有连接器配置属性均以 stacksaga.trace-window 为前缀绑定。

属性名称 (Property) 数据类型 (Data Type) 默认值 (Default Value) 描述说明 (Description)

stacksaga.trace-window.enable-api

boolean

false

暴露本地 /stacksaga/* 端点的总开关。必须设置为 true 连接器才会注册过滤器和端点。当为 false 时，不会激活任何端点。

stacksaga.trace-window.secure-api

boolean

true

当为 true（默认值）时，传入的请求必须携带与 access-token 匹配的有效令牌。在生产环境中，该检查将委托给 StackSaga Central 进行校验。本地离线测试可设置为 false。

stacksaga.trace-window.access-token

String

(无)

用于认证请求的服务访问令牌 (Service Access Token)。当 enable-api 与 secure-api 同时为 true 时必填。可在 TraceWindow 项目设置 中生成。

stacksaga.trace-window.connector-port

int

0 (禁用)

为 /stacksaga/* 端点配置的可选专属端口。配置后，系统将在该端口上启动次级连接器服务，而在主业务端口上收到的追踪请求将被拒绝并返回 403 Forbidden。留空或设置为 0 则直接复用主应用程序端口。

stacksaga.trace-window.connector-ssl-bundle

String

(无)

在 connector-port 上启用 HTTPS 的 Spring Boot SSL Bundle 名称（位于 spring.ssl.bundle.* 下）。仅在配置了 connector-port 时生效。

stacksaga.trace-window.connector-event-loop-threads

int

1

(仅限 WebFlux) 为在 connector-port 上启动的次级服务器分配的 Netty Event-Loop 线程数。默认使用最小线程以节省管理端口的系统资源。

stacksaga.trace-window.allow-private-network

boolean

true

是否在 CORS 预检和追踪响应中输出 Access-Control-Allow-Private-Network: true 响应头。允许运行在公网 TraceWindow 控制台（https://trace.stacksaga.org）的现代浏览器（如 Chrome、Edge）与本地或内网微服务通信，避免触发私有网络访问 (PNA) 拦截。

启动校验规则强制要求：当 enable-api=true 且 secure-api=true 时，必须提供 stacksaga.trace-window.access-token。若缺少令牌，应用程序将在启动时快速失败 (Fail-Fast) 退出。

配置示例 (Configuration Examples)

1. 本地开发模式 (禁用安全校验)

适合在 http://localhost:8080 上快速进行本地开发，无需生成令牌或登录 GitHub：

stacksaga:
  trace-window:
    enable-api: true
    secure-api: false

2. 标准生产模式 (复用主业务端口)

在默认微服务端口上使用双令牌安全认证：

stacksaga:
  trace-window:
    enable-api: true
    secure-api: true
    access-token: ${STACKSAGA_ACCESS_TOKEN}

3. 专属管理连接器端口 (HTTP)

将 /stacksaga/ 追踪端点独占暴露在 8787 端口上。对主应用端口发起的 /stacksaga/ 请求将被拒绝并返回 403 Forbidden：

server:
  port: 8080

stacksaga:
  trace-window:
    enable-api: true
    secure-api: true
    access-token: ${STACKSAGA_ACCESS_TOKEN}
    connector-port: 8787

4. 具备 HTTPS 的专属连接器端口 (SSL Bundle)

将次级连接器端口 8787 绑定到通过 Spring Boot 3 SSL Bundles 声明的独立 SSL 证书：

server:
  port: 8443

spring:
  ssl:
    bundle:
      jks:
        trace-connector-cert:
          keystore:
            location: classpath:admin-keystore.p12
            password: changeit
            type: PKCS12

stacksaga:
  trace-window:
    enable-api: true
    secure-api: true
    access-token: ${STACKSAGA_ACCESS_TOKEN}
    connector-port: 8787
    connector-ssl-bundle: trace-connector-cert

主应用程序端口（如 8443）与连接器端口（8787）可以使用完全独立的 SSL 证书与密钥库 (Keystore)。

5. 自定义 Netty 线程数 (仅限 WebFlux)

适用于预期有高频自动化控制台轮询的反应式服务：

stacksaga:
  trace-window:
    enable-api: true
    secure-api: true
    access-token: ${STACKSAGA_ACCESS_TOKEN}
    connector-port: 8787
    connector-event-loop-threads: 2

网关路由配置示例 (Gateway Routing Examples)

在 网关模式 (Gateway Mode) 下，您的 API 网关或反向代理拦截发送至 {host:port}/{service-name}/{api-path} 的请求，剥离服务前缀，并将调用转发给后端的内部微服务实例。

以下是具体的生产路由配置方案：

Spring Cloud Gateway

配置路由匹配与路径前缀剥离：

gateway-application.yml
spring:
  cloud:
    gateway:
      routes:
        # 订单服务 TraceWindow 连接器路由
        - id: order-service-trace-window
          uri: lb://ORDER-SERVICE
          predicates:
            - Path=/order-service/stacksaga/**
          filters:
            # 转发至微服务前剥离 /order-service 前缀
            - StripPrefix=1

        # 支付服务 TraceWindow 连接器路由
        - id: payment-service-trace-window
          uri: lb://PAYMENT-SERVICE
          predicates:
            - Path=/payment-service/stacksaga/**
          filters:
            - StripPrefix=1

      # 为 TraceWindow Web 控制台开启全局跨域 (CORS) 支持
      globalcors:
        cors-configurations:
          '[/**]':
            allowedOrigins: "https://trace.stacksaga.org"
            allowedMethods:
              - GET
              - POST
              - OPTIONS
            allowedHeaders:
              - Authorization
              - Content-Type

Nginx 反向代理

使用正则表达式重写规则剥离服务标识符前缀，并透传认证请求头：

nginx.conf
http {
    # 内部微服务上游集群定义
    upstream order_service_upstream {
        server order-service-internal.local:8081;
    }

    upstream payment_service_upstream {
        server payment-service-internal.local:8082;
    }

    server {
        listen 443 ssl;
        server_name api.mycompany.com;

        # SSL 证书配置...

        # 订单服务 TraceWindow 路由
        # 将 /order-service/stacksaga/* 重写为 /stacksaga/*
        location ~ ^/order-service/(stacksaga/.*)$ {
            proxy_pass http://order_service_upstream/$1$is_args$args;

            # 透传客户端真实 IP 与 Host
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;

            # 确保 Authorization 请求头 (Bearer User_Token) 正确传递
            proxy_pass_header Authorization;

            # TraceWindow CORS 响应头
            add_header 'Access-Control-Allow-Origin' 'https://trace.stacksaga.org' always;
            add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
            add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type' always;

            # 处理预检 OPTIONS 请求
            if ($request_method = 'OPTIONS') {
                add_header 'Access-Control-Allow-Origin' 'https://trace.stacksaga.org' always;
                add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
                add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type' always;
                add_header 'Access-Control-Max-Age' 1728000;
                add_header 'Content-Type' 'text/plain charset=UTF-8';
                add_header 'Content-Length' 0;
                return 204;
            }
        }

        # 支付服务 TraceWindow 路由
        location ~ ^/payment-service/(stacksaga/.*)$ {
            proxy_pass http://payment_service_upstream/$1$is_args$args;
            proxy_set_header Host $host;
            proxy_pass_header Authorization;
        }
    }
}

Kubernetes Ingress (ingress-nginx)

在 Kubernetes 上使用 ingress-nginx 控制器时，可通过路径重写注解实现：

order-service-trace-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: order-service-trace-ingress
  namespace: stacksaga-apps
  annotations:
    # 将 /order-service/stacksaga/(.*) 重写为 /stacksaga/$1
    nginx.ingress.kubernetes.io/rewrite-target: /stacksaga/$1
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://trace.stacksaga.org"
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, OPTIONS"
    nginx.ingress.kubernetes.io/cors-allow-headers: "Authorization, Content-Type"
spec:
  ingressClassName: nginx
  rules:
    - host: api.mycompany.com
      http:
        paths:
          - path: /order-service/stacksaga/(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: order-service
                port:
                  number: 8081

连接器端点参考手册 (Connector Endpoints Reference)

当 stacksaga.trace-window.enable-api=true 时，连接器会自动注册并提供以下 REST 端点服务：

HTTP 请求方法 路径模式 (Path Pattern) 用途与详细描述说明

GET

/stacksaga/api/v1/welcome

握手与探活检查 (Handshake & Health Probe)： TraceWindow 通过调用此接口探测微服务可达性、检查实例 ID、验证令牌并确认项目读取权限。

GET

/stacksaga/api/v1/transaction

事务链路查询 (Transaction Trace Query)： 根据传入的 transactionId 获取详尽的 Saga 链路追踪数据，涵盖各执行步骤节点、执行状态、毫秒时间戳与异常诊断详情。

请求头规范 (Request Headers)

  • Authorization: Bearer <User_JWT_Token>：由 TraceWindow Web 控制台自动携带，用于标识当前登录的操作员身份。

  • X-Timezone: <Timezone_Offset>：（例如 +08:00）由 TraceWindow 自动传入，服务端据此将所有返回的时间戳格式化为操作员的本地时区。

后续步骤 (Next Steps)