signadot-validate

Signadot：验证微服务更改

使用 Signadot 验证代码更改是否适用于真实集群依赖项，除非服务无法在本地运行，否则无需构建镜像。优先使用本地映射的沙箱：在本地运行已更改的服务，通过路由键将集群流量路由至该服务，并持续迭代，直到完整验证流程通过。

参考索引

仅当工作流涉及相应主题时，才加载以下单跳参考资料：

• references/sandbox-setup.md：集群和工作负载解析、沙箱复用／创建／更新、devbox 检测、环境变量重建、进程启动和端口规则。
• references/validation-types.md：如何运行集成测试、现有端到端测试套件、临时浏览器自动化，以及注入路由键的现有 Signadot 计划。
• references/troubleshooting.md：针对 503、看似基线的响应、浏览器空白、传播失败、异步跳转、进程退出和 gRPC DNS 延迟的快速诊断。
• references/worked-example.md：通过本地沙箱验证 UI 更改的端到端示例。

核心工作流

此工作流分为四个阶段：A（编码前）、B（设置沙箱）、C（运行验证）、D（迭代）。步骤按顺序编号；每一步都链接到包含其详细说明的参考文档。

1. 编码前定义“验证通过”的标准（阶段 A）。如果用户没有指定验证类型，提出一个问题，并提供以下选项：集成测试、现有 e2e 测试套件、临时浏览器自动化，或现有的带标签 Signadot 计划。验证类型会影响实现方式、沙箱端口和路由键的接入方式。如果用户提到其他工具，例如 Locust、Postman 或自定义 Cypress 脚本，则遵循同一原则：找到其 HTTP/gRPC 客户端所在位置，以及它将如何发送路由键。 参见 references/validation-types.md。
2. 确定集群和工作负载（阶段 B）。如果 Signadot MCP 服务可用，则使用它；否则使用 CLI。通过工具或仓库自有的 Signadot 规范解析名称，不要猜测。如果工具响应因存在多个集群、工作负载或 devbox 而要求确认，请让用户选择。 参见 references/sandbox-setup.md。
3. 优先复用，再创建（阶段 B）。创建新沙箱前，先查找同一用户和工作负载是否已有运行中的沙箱。复用沙箱可确保路由键在本地测试环境变量、curl 和浏览器自动化之间保持稳定。 参见 references/sandbox-setup.md。
4. 创建或更新沙箱（阶段 B）。如果 .signadot/ 下有匹配的现有仓库规范，则使用它。否则，创建最小化的本地映射沙箱，其中仅包含已更改或跟进变更后的用户可见路径所需的服务。 关于必填字段、端口规则和预览端点策略，参见 references/sandbox-setup.md。
5. 拉取环境变量并启动服务（阶段 B）。先查看仓库的常规运行命令。导出所有必需的环境变量，尤其是服务间地址、密钥和功能标志。将进程置于后台运行前先完成构建，然后确认进程仍在运行且端口正在监听。 参见 references/sandbox-setup.md 和“Starting The Service”部分。
6. 通过集群 URL 验证（阶段 C）。向 http://<svc>.<namespace>.svc:<service-port>/... 发送带路由键标头的流量。不要直接调用 localhost:<port> 进行验证。 关于与阶段 A 所选类型对应的小节，参见 references/validation-types.md。
7. 针对失败进行迭代（阶段 D）。读取确切的失败信息，修复最小范围的原因，重启受影响的服务，并针对同一沙箱重新运行相同的验证。在约定的验证路径通过前，不要报告成功。 参见 references/troubleshooting.md。
8. **妥善收尾。**报告沙箱名称、集群、路由键、目标 URL、验证命令或浏览器路径，以及已停止的本地进程。默认保留沙箱运行；仅将删除命令作为可选项提供。

MCP 和 CLI 的使用

如果 Signadot MCP 服务可用，则使用它执行控制平面操作：列出并检查集群、沙箱、routegroup、工作负载、端点和 devbox；在下方副作用策略允许时，创建或更新沙箱。按意图搜索，调用工具前加载工具架构，并优先采用工具输出，而非记忆。

如果 MCP 不可用，则使用 CLI 作为后备方案：

signadot cluster list -o json
signadot sandbox list -o json
signadot sandbox get <name> -o json
signadot sandbox apply -f <spec.yaml>
signadot sandbox get-env <name>
signadot sandbox get-files <name>

仅当 MCP 无法获取相同工作负载、ConfigMap、Secret 或 Service 数据，且本地环境可访问集群时，才使用 kubectl get <kind> <name> -n <ns> -o yaml。

信号清单

信号	用途
本地进程接收真实集群流量	在不构建镜像的情况下，优先用于验证已更改的服务
本地可解析集群 DNS/IP	signadot local connect 或开发机箱可让 .svc 名称变得可访问
路由请求时，本地 stdout/stderr 持续输出	观察请求是否进入已更改的代码、查看 panic、连接调试器
沙箱就绪状态、分叉、路由状态和隧道连接	确认沙箱可以路由后再测试代码
按需显式请求的预览端点	无需手动设置路由标头即可确定性地访问分叉，但可能会公开一个 *.preview.signadot.com URL
路由键隔离	证明带键的流量会进入沙箱，而不带键的流量仍留在基线版本
signadot local proxy	诊断依赖项是否可访问；不属于验证结果

副作用策略

操作	默认行为
读取集群、工作负载、端点、沙箱、路由组	自主执行
为此任务创建隔离沙箱	集群/工作负载明确时自主执行
更新明确属于此任务的沙箱	自主执行
更新共享沙箱或路由组	先询问
添加公共预览端点，例如 defaultRouteGroup.endpoints	先询问
删除沙箱	先询问；默认保持运行
运行 sudo signadot local connect --cluster <cluster> 或 signadot local disconnect	请用户运行；此操作会修改本地网络堆栈，且可能需要 sudo
运行 signadot local status 或 signadot local proxy	有用时自主执行；proxy 用于诊断，不能证明验证成功

路由规则

注意两个端口

请区分以下两种端口：

上下文	要使用的端口	如何确定
沙箱本地映射	工作负载/容器端口	使用 MCP 工作负载端口解析器，例如 resolve_workload_port，或检查工作负载规范
发往 .svc URL 的验证流量	Kubernetes Service 端口	使用端点解析器，例如 resolve_endpoints、Service 对象或仓库中的 Signadot 规范

即使映射使用了错误的容器端口，只要隧道已连接，沙箱仍可能显示 ready: true；此时请求会回退到基线版本。如果路由看起来不正常，请检查 /etc/hosts 中是否存在类似 <sandbox>-<mapping>-*.<namespace>.svc 的虚拟主机条目。

始终访问集群 URL

验证流量必须发往集群服务 URL，而非本地进程：

curl -sS "http://<svc>.<namespace>.svc:<service-port>/<path>" \
  -H "baggage: sd-routing-key=<routing-key>" \
  -H "tracestate: sd-routing-key=<routing-key>"

对于 gRPC：

grpcurl -plaintext \
  -H "baggage: sd-routing-key=<routing-key>" \
  -H "tracestate: sd-routing-key=<routing-key>" \
  -d '{"field":"value"}' \
  <svc>.<namespace>.svc:<service-port> package.Service/Method

始终接受名称为 sd-routing-key 的 baggage 和 tracestate。如果 clusterConfig.routing.customHeaders 列出了其他标头，请为每个标头注入路由键作为其值。只有当请求接口无法设置标头时，才使用查询参数路由。

signadot local proxy 可帮助调试机器是否能够访问集群依赖项，但 localhost 代理 URL 会绕过相同的端到端路由路径，因此不属于验证结果。

在各跳之间转发路由键

只有每一跳都传播路由键时，它才能到达被沙箱化的下游服务。原始 HTTP/gRPC 客户端、自定义代理处理程序和异步生产者通常会丢弃该键，除非代码显式复制它。添加新的转发器时，请将传入的 baggage 标头复制到出站请求，或使用该服务现有的、已插桩的客户端。

Secrets And Env Vars

从工作负载规范、ConfigMaps 或 Secrets 重建环境变量时：

• 在归咎于代码之前，先解析出所有必需的值。缺少数据库地址、凭据和功能标志，往往会导致首次请求返回 500。
• 不要在聊天、日志或摘要中输出机密值。请将其替换为 <redacted>，并避免粘贴解码后的 Secret 内容。
• 优先将机密直接导出到进程环境中。如果必须使用环境变量文件，请设置严格的文件权限，并在清理时将其删除。
• 对于服务地址，请在代码中搜索配置读取项，例如 *_ADDR、*_HOST、*_URL，以及特定语言的辅助函数。在 Pod 内可用的默认值，从本地进程访问时可能无法使用。

Validation Type Picker

• 集成测试：使用该语言原生的测试命令，对集群 .svc URL 运行测试，并在测试客户端或共享传输中注入路由标头。
• 现有端到端测试套件：使用仓库现有的命令和配置。将基础 URL 指向 .svc URL，并在框架 HTTP 层附加路由标头。
• 临时浏览器自动化：通过浏览器操作 UI，端到端测试此变更。使用可用的浏览器自动化工具（常用的是 Playwright）；在每个请求上注入路由标头，如果浏览器状态会保留，则先清除之前的路由，并完整走一遍 UI 流程。
• 现有的带标签 Signadot 计划：根据 selectionHint 选择一个标签，并在沙箱中运行计划。关于计划的其他所有内容——参数、机密、日志/输出、编写和打标签——请参阅 signadot-plan 技能。

运行所选类型之前，请阅读 references/validation-types.md。

Failure Loop

验证失败时，不要止步于“验证失败”。继续以下循环：

1. 引用确切的失败信息：状态码、错误消息、堆栈跟踪、缺失的 UI 元素、错误字段或空白的浏览器状态。
2. 判断可能的原因是应用代码、沙箱配置、缺失的环境变量、过时的进程、错误的端口、路由键传递，还是必须在本地运行的下游消费者发生了变化。
3. 应用最小修复，重新构建并重启受影响的进程，然后使用相同的路由键和目标 URL 重新运行同一项验证。
4. 只有当修复需要用户作出无法代为判断的决策时，才暂停并询问——例如，在向前修复、保持向后兼容或接受有意的破坏性变更之间作出选择。对于拼写错误、缺失的环境变量或重启已停止的进程等机械性修复，不要请求许可；直接修复并继续循环。

在宣布完成之前，请考虑是否应将已验证的行为纳入 Signadot 计划。当该问题可确定性复现、影响重要且未被其他测试覆盖时，应这样做。拼写错误、基础设施偶发故障、探索性检查和非确定性故障模式则无需纳入。沙箱仍在运行——在其中运行一次新计划，即可在打标签之前确认它能捕获该问题（或能通过已修复的代码）。

快速诊断

症状	可能原因	首先检查
devbox 返回 Envoy 503，但 Pod 状态正常	访问了容器端口，而非 Service 端口	Service 对象／端点解析器
响应看起来像旧版基线行为	路由键被丢弃或使用了 localhost 目标	目标 URL 和所有路由标头
Sandbox 已就绪且隧道已连接，但本地进程没有收到流量	Sandbox 映射端口错误	/etc/hosts 中的虚拟 Sandbox 条目
本地进程启动后，首个实际请求返回 500	缺少环境变量或依赖地址未解析	配置查询和导出的环境变量
交互后，浏览器正文或无障碍树变为空	SPA 运行时错误	浏览器控制台错误和 page.content().length
后台进程启动后很快退出	Shell 作业收到 SIGHUP 或端口冲突	进程状态、监听器、日志文件
gRPC 拨号在 DNS 超时附近停滞	Go gRPC SRV 查询延迟	passthrough:/// 目标和连接复用

详细信号和修复方法请参阅 references/troubleshooting.md。

最终报告

请包含：

• 验证类型以及使用的命令／工具路径
• 集群、Sandbox 名称、路由键和服务 URL
• 通过的项目，包括相关的浏览器／用户路径
• 已停止的任何本地进程 PID 或端口
• 作为选项而非操作提供的 Sandbox 拆除命令：

signadot sandbox delete <sandbox-name>

如果用户运行了 local network connect，请提醒他们之后可以运行：

signadot local disconnect