即时通讯后端【免费下载链接】WuKongIMMore than just IM 不只是即时通讯(IM)项目地址https://gitcode.com/gh_mirrors/wu/WuKongIM点击查看免费下载导读WuKongIM 在云端仿真Simulation Run体系中引入了一个关键架构决策每一次仿真运行Simulation Run只在它的仿真节点simulator node上托管一个 Analysis MCP Gateway为 Codex 这类分析 Agent 提供唯一的、随运行run-scoped而生的工具端点同时把 MCP 端口与协议逻辑完全隔离在三节点集群之外。本文基于 docs/adr/0004-host-one-analysis-mcp-gateway-per-run.md 展开结合仓库中 cmd/wkanalysis 的完整实现与 scripts/cloud-sim/analyze.sh 的调用链讲解该网关的定位、聚合原理、生命周期绑定与故障语义以及它如何与 OIDC、访问窗口、窄工具契约等相邻决策协同。读完本文你将掌握 WuKongIM 云仿真分析控制面的设计取舍与可运行的配置细节。为什么需要“每次运行一个网关”单点端点 vs 集群直连三节点 WuKongIM 集群自身暴露了丰富的私有限制诊断面private diagnostic surfaces包括各节点 API、simulator 本地的 Prometheus、以及 manager 管理面。如果让分析工具直接散落访问这些端口会出现三类问题端口暴露面失控每个节点、每个服务都要对分析方开放端口集群的网络安全边界被持续扩大协议逻辑侵入集群MCPModel Context Protocol握手、令牌校验、工具调度等控制面逻辑如果直接落在集群节点上会与消息收发、存储、复制等数据面逻辑耦合影响集群的稳定性与演进速度身份与范围难以收敛多端点访问意味着无法用一个统一的运行身份Run Identity来限定分析方的可见范围与权限。ADR 0004 的核心主张是把这些分散的诊断面聚合到仿真节点上的单个 Analysis MCP Gateway 之后分析方只看到一个端点、一种协议、一个身份作用域。聚合对象三类诊断源从源码结构看该网关聚合了三类对象见 internal/app/cloud_analysis.go 的 HTTP 源组装诊断源默认地址环境变量可覆盖用途Prometheussimulator 本地http://prometheus:9090指标查询、队列深度、时延分位、节点与宿主资源状态WuKongIM 三节点私有 APIhttp://wk-node1:5001、http://wk-node2:5001、http://wk-node3:5001集群快照、日志搜索、运行时状态Manager 管理面http://wk-node1:5301会话、任务审计、受管控的诊断操作默认节点映射在 cmd/wkanalysis/config.go 中由parseNodeURLs定义WK_ANALYSIS_NODE_API_URLS为空时默认解析为节点 1/2/3 的三个 5001 端口并且强制要求恰好包含节点 1、2、3缺一不可。网关的组成结构与单进程部署形态wkanalysis一个进程承载全部控制面cmd/wkanalysis/main.go 展示了网关的完整装配它通过环境变量加载配置loadServeConfig创建 GitHub OIDC 校验器与运行期会话存储analysisSessionStore然后调用app.NewCloudAnalysisGatewayHandler组装出真正的 MCP 处理器并在同一个http.Server上同时挂载POST /mcp—— MCP 工具端点GET /healthz—— 存活与运行身份校验端点GET /self-check—— 预检依次探测 Prometheus/-/ready、每个节点的/readyz以及配置了账号时manager 的/manager/loginPOST /analysis/token—— 仅在启用 OIDC 时挂载的令牌交换端点。也就是说“一个网关”在部署形态上就是一个名为wkanalysis的独立进程监听默认地址0.0.0.0:19092cmd/wkanalysis/config.go与集群三节点完全分离。网关内部的层次从 internal/app/cloud_analysis.go 可以看到三个组装层次RunInspector运行检查器把 RunID、RunState、InventoryCount、Provider、Region、SourceSHA、ExpiresAt、Scenario 等运行身份与租约信息固定下来。Provider为local-compose时只做显式运行时状态检查并附带警告云环境则要求 RunLocator 校验通过以证明云厂商资源清单中的运行身份HTTPSources私有 HTTP 适配层把 manager、Prometheus、三节点 API、运行报告目录统一封装为受限数据源cloudanalysismcp.HandlerMCP 访问层最终暴露工具校验运行期 MCP Token静态令牌或动态签发的 Analysis Token。为什么“唯一”的答案是仿真节点租约/生命周期绑定的必然结果ADR 0004 的关键推理是丢失仿真节点既会使负载失效也会使网关不可用。因此它选择“运行失败”而不是“再引入一个独立的 MCP 控制面主机”。仿真运行Simulation Run是一段临时的、租约Run Lease约束的云资源生命周期参见 docs/adr/0001-decouple-cloud-simulation-and-analysis.md分析只能在资源仍然存活时进行不允许为已释放的运行增加历史诊断后端参见 docs/adr/0003-analyze-live-simulation-runs-only.md网关与负载同生共死仿真节点存活 ⇒ 网关可用仿真节点丢失 ⇒ 负载无效且网关不可达此时把整个运行判为失败而不是去维持一个失去数据源的孤儿控制面。这个决策直接把“控制面可用性”与“数据面可用性”对齐避免了双控制面带来的状态分裂与额外计费成本。与访问窗口决策的衔接网关并非永久公开可达。ADR 0006docs/adr/0006-open-mcp-ingress-only-for-an-analysis-access-window.md规定分析工作流只在分析访问窗口Analysis Access Window内临时放行当前 GitHub runner 的出口 IP 到网关 HTTPS 端口并在无条件清理中关闭该规则云侧运行租约提供第二条清理路径。这一“窄窗口 双清理”设计与 ADR 0004 的“单网关”定位互为补充端点数量收敛到一个可见时间窗口也收敛到一段。运行身份与令牌体系两种认证路径cmd/wkanalysis/config.go 明确规定网关必须同时具备“运行身份 以下两者之一”GitHub OIDC 配置或长度 ≥ 32 字节的 MCP Token。两条路径对应两种使用场景路径启用开关说明GitHub OIDC 交换WK_ANALYSIS_GITHUB_OIDC_ENABLEDtrue通过POST /analysis/token用 GitHub OIDC ID 令牌换取动态 Analysis Token要求 TLS 证书与密钥静态 MCP Token直接设置WK_ANALYSIS_MCP_TOKEN长度必须 ≥ 32 字节用于本地 Compose 等非 OIDC 场景OIDC 校验在 cmd/wkanalysis/oidc.go 中有严格约束仅接受 GitHub Actions 的签发者https://token.actions.githubusercontent.com且只认wukongim-cloud-sim:run_id或wukongim-cloud-lease:run_id两类 Audience同时校验 repository、ref必须以refs/heads/开头、workflow ref 与环境名subject 也必须精确匹配。会话令牌的生命周期约束cmd/wkanalysis/session.go 实现的analysisSessionStore.Issue把动态令牌的寿命死死限制在运行租约之内默认有效期 45 分钟若运行租约截止时间减 5 分钟更早则以该更早时间为准令牌不能越过租约边界运行租约剩余不足 30 分钟时拒绝签发令牌为 32 字节随机值仅以 SHA-256 摘要形式驻留内存验证时按摘要查找并校验过期。这正好印证 ADR 0004 中“run-scoped”随运行作用域的含义令牌的有效期、身份、可访问的数据范围全部与当前运行的租约强绑定。配置全景环境变量清单网关的全部行为由环境变量驱动以下是 cmd/wkanalysis/config.go 中可确认的完整清单必填项环境变量约束WK_ANALYSIS_RUN_ID运行身份非空WK_ANALYSIS_SCENARIO_PATH生效场景文件路径必须能加载且版本为wkbench/v1、随机种子非零认证二选一WK_ANALYSIS_MCP_TOKEN≥32 字节或WK_ANALYSIS_GITHUB_OIDC_ENABLEDtrue附带 OIDC 系列变量与 TLS可选项与默认值环境变量默认值说明WK_ANALYSIS_LISTEN_ADDR0.0.0.0:19092监听地址必须可被SplitHostPort解析WK_ANALYSIS_SCENARIO_DIGEST无若提供则必须与场景文件实际摘要一致WK_ANALYSIS_FAKE_INVENTORY_PATH无与WK_ANALYSIS_RUN_LOCATOR_PATH必须同时配置WK_ANALYSIS_RUN_LOCATOR_PATH无运行定位文件其 RunID 与场景摘要必须匹配ExpiresAt 必须与租约一致WK_ANALYSIS_RUN_EXPIRES_AT当前时间 2 小时有 locator 时取其 ExpiresAt距当前时间不得少于 30 分钟WK_ANALYSIS_TOKEN_EXPIRES_AT当前时间 45 分钟不越过租约 − 5 分钟仅静态令牌路径不得超过 45 分钟且不得越过租约边界WK_ANALYSIS_NODE_API_URLS{1:http://wk-node1:5001,2:http://wk-node2:5001,3:http://wk-node3:5001}JSON 对象必须恰好含节点 1/2/3WK_ANALYSIS_INVENTORY_COUNT12已证明的相关资源计数WK_ANALYSIS_MANAGER_BASE_URLhttp://wk-node1:5301manager 来源WK_ANALYSIS_MANAGER_BEARER_TOKEN无与用户名/密码二选一WK_ANALYSIS_MANAGER_USERNAME/WK_ANALYSIS_MANAGER_PASSWORD无必须成对设置WK_ANALYSIS_PROVIDERlocal-compose云厂商标识WK_ANALYSIS_REGIONlocal区域WK_ANALYSIS_SOURCE_SHA无已部署源码提交与 locator 不一致时报错WK_ANALYSIS_RUN_STATErunning运行生命周期状态WK_ANALYSIS_TLS_CERT_FILE/WK_ANALYSIS_TLS_KEY_FILE无必须成对启用云 OIDC 时强制要求WK_ANALYSIS_PROMETHEUS_BASE_URLhttp://prometheus:9090指标来源网关暴露的窄工具契约ADR 0004 只是“部署形态”决策工具契约本身由 ADR 0028docs/adr/0028-expose-a-narrow-run-scoped-mcp-tool-contract.md定义。analyze.sh中实际启用的工具清单验证了这一点scripts/cloud-sim/analyze.sh[run_inspect,workload_inspect,cluster_snapshot,metrics_query_range,logs_search,logs_context,diagnostics_query,task_audits_query,trace_start,trace_query,profile_capture,profile_top,profile_list,config_read_redacted]要点包括每个结果都携带 run、node、observation time、data window、completeness、warnings 元数据指标查询强制 range、step、series、sample、timeout 上限profile 工具只返回服务端符号化视图不提供任意文件读取工具输入不能命名任意 URL、文件、命令或进程也没有批量采集或通用远程操作工具。预置的 PromQL 查询库位于 cmd/wkanalysis/config.go覆盖发送/投递速率、channelv2 RPC 各阶段 P99、存储提交队列、投递重试、slot 提案、会话目录扫描、presence 端点查找、送达 ack 批处理等上百个稳定查询 ID全部由服务端持有查询字符串客户端只能引用查询 ID。端到端调用链从分析脚本到 Codex一次完整分析会话的阶段scripts/cloud-sim/analyze.sh 串起了“一个网关、一个会话”的完整生命周期inspect预检通过 GitHub Actions 工作流cloud-sim-analyze.yml校验云厂商资源清单证明运行仍存活若资源已释放则直接终止避免把缺失的分析误报为成功对应 docs/adr/0003-analyze-live-simulation-runs-only.mdprepare会话准备客户端生成临时 RSA 密钥与公钥探测出口 IPv4工作流临时放行该地址到网关 HTTPS 端口、签发并加密交付 Analysis Token 与 CA 指纹对应 docs/adr/0006-open-mcp-ingress-only-for-an-analysis-access-window.md健康探测用固定 CA 对{mcp_url}/healthz做最多 12 次、每次间隔 5 秒的重试校验status ok、run_id与run_state running本地桥接构建并启动 cmd/wkcloudanalysisbridge把远端https://ip:19092/mcp桥接到http://127.0.0.1:port/mcpCodex 只接触本机回环地址Codex 诊断在严格隔离的临时环境中以--ephemeral、禁用网络、限定文件系统只读的方式启动 Codex把 MCP 服务器配置为wukongim_cloud_analysis仅启用上面 15 个工具输出受.github/cloud-sim/diagnosis.schema.json约束的 JSON 结果close会话关闭诊断结束后无条件触发关闭工作流并确认令牌清空即便关闭失败访问窗口过期与租约清理仍是兜底结果校验用cmd/wkclouddiagnosis validate做模式校验再核对 run_id、source_sha、scenario_digest 与加密会话一致最后原子写入结果文件。网关健康检查的客户端视角分析脚本对网关的存活判断不只是“端口能连”而是三重要求status ok、run_id匹配、run_state runningscripts/cloud-sim/analyze.sh。这与网关侧 cmd/wkanalysis/main.go 中healthz的载荷设计一一对应健康载荷固定携带 run_id、run_state、run_expires_at、provider、region、source_sha、scenario_digest。健康检查本身同时承担了“身份确认”职责。故障语义什么情况下整个运行判失败ADR 0004 明确拒绝“双控制面主机”方案因此故障语义非常清晰事件结果仿真节点存活网关正常分析会话正常进行仿真节点丢失spot 中断、租约到期、资源释放负载无效、网关不可达运行判为失败不启动孤儿控制面网关自身进程异常退出预检/健康探测失败分析工作流以 preflight failure 终止且“网关不可达”被当作独立预检失败而非资源已释放的证据docs/adr/0003-analyze-live-simulation-runs-only.md值得注意的是ADP 0003 特别强调MCP 不可达本身只是独立的 preflight 失败不能作为“运行已销毁”的证据——销毁证据必须来自云厂商资源清单。网关是否存活只影响“能否分析”不影响“运行是否还存在”的判定。相关决策脉络与测试佐证该决策处于 WuKongIM 云仿真分析控制面的决策序列之中建议按顺序阅读docs/adr/0001-decouple-cloud-simulation-and-analysis.md仿真执行与 GitHub 工作流解耦运行可长达数小时到数天docs/adr/0002-pair-analysis-mcp-with-analysis-skill.mdMCP 提供结构化可观测能力Skill 负责教会 Codex 如何查询、交叉验证、归类根因docs/adr/0003-analyze-live-simulation-runs-only.md只分析存活运行不建历史诊断后端本决策0004每次运行只托管一个网关于仿真节点失败即整个运行失败docs/adr/0006-open-mcp-ingress-only-for-an-analysis-access-window.md入口只在访问窗口内开放docs/adr/0028-expose-a-narrow-run-scoped-mcp-tool-contract.md暴露窄工具契约。在测试方面cmd/wkanalysis/config_test.go、cmd/wkanalysis/session_test.go、cmd/wkanalysis/oidc_test.go 分别覆盖了配置校验运行身份、租约、节点 URL、摘要匹配、会话令牌签发/过期边界与 OIDC 校验约束scripts/cloud_sim_analyze_test.go 与 scripts/cloud_sim_analyze_integration_test.go 覆盖了分析脚本的阶段契约与集成路径可以作为理解该决策落地形态的第一手参考。小结ADR 0004 用一句话定义了 WuKongIM 云仿真分析的控制面形态每个 Simulation Run 恰好一个 Analysis MCP Gateway托管在仿真节点上聚合三节点私有诊断面与 Prometheus为 Codex 提供唯一的 run-scoped 工具端点并把 MCP 端口与协议逻辑完全隔离在集群之外仿真节点一旦丢失负载与网关一并失效整个运行按失败处理不再引入第二个控制面主机。这一决策与运行租约、分析访问窗口、OIDC 身份交换、窄工具契约共同构成了一个“单端点、短窗口、强绑定、窄契约”的云分析控制面既收敛了安全暴露面也避免了在临时云资源上维护多余控制面的成本与复杂度。赞分享即时通讯后端【免费下载链接】WuKongIMMore than just IM 不只是即时通讯(IM)项目地址https://gitcode.com/gh_mirrors/wu/WuKongIM点击查看免费下载相关推荐从硬件报告到开机OpCore-Simplify 黑苹果 EFI 一键生成实操从硬件报告到开机OpCore Simplify 黑苹果 EFI 一键生成实操 OpCore Simplify 是一个命令行工具负责黑苹果搭建中最繁琐的一环即时通讯后端WuKongIM 云仿真诊断架构解析Analysis MCP 与 Analysis Skill 的职责分离设计WuKongIM 云仿真诊断架构解析Analysis MCP 与 Analysis Skill 的职责分离设计 云仿真压测Cloud Simulation即时通讯后端Jina 中 add_voter Proto 的构建指南跨 protobuf 版本生成 Raft gRPC 代码Jina 中 add_voter Proto 的构建指南跨 protobuf 版本生成 Raft gRPC 代码 Jina 的状态化 Executor 依赖内即时通讯后端上一篇华硕笔记本风扇异常3个技巧快速诊断与修复下一篇Sign Language Transformers突破性端到端手语识别与翻译技术创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考