StackSaga TraceWindow 链路追踪控制台 (Dashboard)
概述 (Overview)
StackSaga TraceWindow 是 StackSaga 框架专用的监控与分布式事务追踪可视化控制台。 它为开发人员、架构师和运维工程师提供对分布式 Saga 事务执行流程、步骤状态、时间线、异常堆栈轨迹和补偿路径的实时可视化可观测性能力。
核心能力 (Core Capabilities)
-
交互式事务可视化 (Interactive Transaction Visualization)： 在图形化时间线中完整追踪每个编排器动作、执行顺序、状态变迁与补偿回滚。
-
双运行模式 (Dual Operational Modes)： 无缝支持无需认证 Token 的*本地开发模式 (Local Development Mode)，以及基于 GitHub OAuth 与细粒度访问控制的企业级*生产模式 (Production Mode)。
-
灵活拓扑 (Flexible Topologies)： 原生支持微服务直连 (Direct Mode，直连模式) 与企业级反向代理集群 (Gateway Mode，网关模式)。
-
原生数据隐私保护 (Data Privacy by Design)： 所有的事务追踪数据、业务载荷和数据库记录完全保留在您的私有基础设施内部。 StackSaga Central 云服务仅作为身份验证与权限控制平面运作——绝不存储、镜像或处理您的任何业务事务数据。
运行与安全模式 (Operational & Security Modes)
TraceWindow 支持以下两种运行模式之一，具体由目标微服务中的安全配置决定：
| 特性 (Feature) | 本地开发模式 (Local Development Mode) | 生产模式 (Production Mode) |
|---|---|---|
连接器配置属性 |
|
|
服务访问令牌 (Access Token) |
不需要 |
必须配置 ( |
GitHub 登录与项目注册 |
不需要 |
必须配置 (GitHub OAuth 登录 + 注册项目与服务) |
鉴权引擎 (Authorization Engine) |
自动跳过 (直接访问本地数据) |
由 StackSaga Central 进行校验 (双令牌 Dual-Token 检查) |
适用场景 |
本地开发机、离线测试、CI 测试环境 |
预发 (Staging)、QA 与生产微服务集群 |
1. 本地开发模式 (secure-api=false)
在本地工作站（例如 http://localhost:8080）进行开发时，您可以直接连接微服务，无需创建项目或生成 Token：
-
在服务中启用本地链路追踪端点 (
stacksaga.trace-window.enable-api=true)。 -
禁用安全检查 (
stacksaga.trace-window.secure-api=false)。 -
打开 TraceWindow，填入本地服务 URL，即可立即开始检查和调试事务数据。
2. 生产模式 (secure-api=true)
在生产环境中，敏感事务追踪数据的访问受 StackSaga 双令牌授权模型 (Dual-Token Authorization Model) 严格保护：
-
用户会话令牌 (User Session Token, JWT)： 标识通过 GitHub OAuth 登录 TraceWindow 的操作人员身份。
-
服务访问令牌 (Service Access Token)： 在 TraceWindow 内部生成的唯一密钥，配置在微服务中 (
stacksaga.trace-window.access-token)。 -
通过 StackSaga Central 的双向校验： 当发起追踪请求时，目标微服务将两个令牌转发给 StackSaga Central。 StackSaga Central 验证服务令牌有效且处于激活状态，并确认该登录用户拥有访问该项目的读取权限。
生产环境搭建与项目管理 (Production Setup & Project Management)
按照以下步骤在 TraceWindow 中注册应用程序并获取生产模式凭据：
步骤 1：通过 GitHub 登录
访问 StackSaga TraceWindow，使用您的 GitHub 账号完成登录。
步骤 2：创建项目 (Create a Project)
创建一个项目，用于逻辑分组您的微服务并管理团队权限：
创建完成后，项目将显示在您的 TraceWindow 控制台看板中：
|
团队协作与 RBAC 权限控制： 您可以邀请其他团队成员作为项目下的服务运维操作员 (Service Operators)。 进入 Manage Operators，输入其 GitHub 用户名并分配角色。 您可以随时授予或吊销操作员权限，无需重启或修改应用程序密钥。 |
步骤 3：注册微服务 (Register a Service)
在新建的项目下注册微服务。
使用与您的微服务名称一致的清晰标识符（例如 order-service）：
注册后的微服务将列在项目看板下方：
步骤 4：生成服务访问令牌 (Generate a Service Access Token)
为目标微服务生成服务访问令牌 (Service Access Token)：
您可以按需配置令牌过期时间。 生成后请立即复制该令牌并妥善保管：
步骤 5：配置应用属性 (Configure Application Properties)
将生成的访问令牌添加到您的微服务配置文件中：
spring.application.name=order-service
# 暴露本地 /stacksaga/* 端点
stacksaga.trace-window.enable-api=true
# 强制开启访问令牌安全鉴权
stacksaga.trace-window.secure-api=true
# 在 TraceWindow 控制台生成的服务访问令牌
stacksaga.trace-window.access-token=04949811-7be5-427f-8a80-57a26592493f
在生产环境中，推荐通过环境变量（例如 STACKSAGA_ACCESS_TOKEN）或密钥管理系统注入令牌，切勿将明文密钥提交到版本控制仓库中。
|
|
若需了解如何在 Maven/Gradle 中引入连接器依赖、配置独立端口隔离或调优 Netty 反应式线程，请参阅配套的 StackSaga TraceWindow 连接器参考指南。 |
连接拓扑：直连模式 (Direct Mode) 与网关模式 (Gateway Mode)
TraceWindow 直接从操作员的浏览器会话与目标后端 URL 通信。 根据您的基础设施暴露微服务的方式，您可以选择采用直连模式 (Direct Mode) 或网关模式 (Gateway Mode) 进行连接。
| 架构维度 | 直连模式 (Direct Mode) | 网关模式 (Gateway Mode) |
|---|---|---|
中介代理 |
无（直接连接至目标微服务） |
反向代理 / API 网关 (Spring Cloud Gateway, Nginx, Kubernetes Ingress) |
目标 URL 规范 |
|
|
典型运行环境 |
本地开发机、独立容器、直连虚拟机 |
生产级 Kubernetes / 私有网络 (VPC) 微服务集群 |
目标 URL 示例 |
|
1. 直连模式 (Direct Mode)
在直连模式下，中间没有网关层。 TraceWindow 直接将追踪请求派发至微服务所在的主机和端口。
目标 URL 规范：
{host:port}/{api-path}示例：
* http://localhost:8081/stacksaga/api/v1/welcome
* http://localhost:8081/stacksaga/api/v1/transaction?transactionId=OS-1724153095843
* https://order-service.internal.corp:8443/stacksaga/api/v1/welcome
直连模式执行流程：
1. 开发者访问： 操作员在浏览器中打开 TraceWindow 并输入目标服务地址（例如 http://localhost:8081）。
2. 直接请求： TraceWindow 携带 Bearer User_Token 请求头直接向 order-service 发起 HTTP 调用。
3. 安全拦截： order-service 内部的连接器拦截器提取用户令牌及本地配置的 stacksaga.trace-window.access-token，将二者一同转发给 StackSaga Central。
4. 鉴权校验： StackSaga Central 对照中心数据库校验令牌有效性、项目归属关系及操作员权限。
5. 数据回传： 鉴权通过后，order-service 查询本地 Event-Store 数据库，并将事务执行记录流式回传给 TraceWindow。
2. 网关模式 (Gateway Mode)
在网关模式下，内部微服务受反向代理或 API 网关（如 Spring Cloud Gateway、Nginx 或 Kubernetes Ingress）屏蔽保护。
目标 URL 规范：
{host:port}/{service-name | URL-alias}/{api-path}示例：
* https://api.mycompany.com/order-service/stacksaga/api/v1/welcome
* https://api.mycompany.com/payment-service/stacksaga/api/v1/transaction?transactionId=PS-1724153095843
* http://localhost:8080/order-service/stacksaga/api/v1/welcome
前缀 {service-name | URL-alias} 指引网关将请求准确路由到具体的内部微服务。
|
完整的网关技术路由配置示例文件（涵盖 Spring Cloud Gateway、Nginx 反向代理和 Kubernetes Ingress），请参阅 连接器参考指南中的网关路由示例。 |
在 TraceWindow 中建立连接与探活校验
在查询具体事务追踪数据之前，TraceWindow 会与目标服务执行一次探活握手 (Handshake Probe)：
-
打开 TraceWindow 中的 Connect Service 弹窗。
-
输入微服务（或网关）的 Root URL；若运行在网关模式，提供对应的 Service Name / Alias。
-
TraceWindow 调用目标服务上的
GET /stacksaga/api/v1/welcome探活端点。 -
若身份认证和权限校验成功，界面将显示成功连接确认：
-
若服务令牌无效、缺失，或者您的用户账号尚未加入该项目，服务端将返回 HTTP
403 Forbidden响应。
/stacksaga/api/v1/welcome 端点充当轻量级探活探针。一旦校验成功，TraceWindow 会在当前活动会话中保存该连接配置。
|
解决混合内容 (Mixed Content) 浏览器拦截问题
当从安全的 TraceWindow 控制台（https://trace.stacksaga.org）访问运行在普通 HTTP 上的目标服务（例如 http://localhost:8080 或内网 IP）时，现代浏览器会由于混合内容安全限制 (Mixed Content Security Restrictions) 拦截跨域请求：
解决方案：配置浏览器不安全来源标志 (Insecure Origins Flag)
在本地开发及测试非 SSL 端点时，可通过以下步骤放行限制：
-
在浏览器（Chrome、Edge、Brave）地址栏中访问
chrome://flags或edge://flags。 -
搜索 Insecure origins treated as secure。
-
添加您的目标微服务域名或 IP 与端口（例如
http://192.168.1.50:8080），并将状态切换为 Enabled：
-
重启浏览器。 此时 TraceWindow 即可顺利连通您的非 SSL 后端服务：
|
私有网络访问 (Private Network Access, PNA) 支持： 除了混合内容标志之外，现代 Chromium 浏览器在公网网站（ |