企业官网建设流程全解析

• 即时通讯
• 后端

本文以 WuKongIM 仓库中的架构决策记录 ADR-0020：Simulate only trusted main revisions 为主体，结合.github/workflows下的真实工作流与scripts/cloud-sim脚本，说明该决策的信任模型、Git 校验实现、无凭据构建与受保护环境审批如何共同把云仿真（Cloud Simulation）的计费资源创建限制在可信main历史内，以及该策略在分析（Analysis）与修复（Remediation）环节的落地方式。

一、决策背景：为什么云仿真必须限制来源

WuKongIM 的 Cloud Simulation 是一套在云端创建三节点集群 + 压测机（sim host）并运行真实工作负载的自动化体系。它会在阿里云上创建 ECS 实例、数据盘、弹性公网 IP 等计费资源，还会把包含 Analysis MCP、诊断工具的服务端部署到这些主机上。如果任意分支、任意 fork 的 Pull Request 提交都能触发这套流程，攻击者就能通过一次恶意提交让 CI 使用仓库级云凭据创建大量资源，或者注入被篡改的工作流定义来窃取凭据。

因此 ADR-0020 制定了第一版信任策略，核心约束可以概括为：

1. Provisioning（供应）工作流只能从**默认分支（main）**发起；
2. 接受的源码提交必须是可信main历史中的成员（通过 Git 祖先关系验证）；
3. 构建 Job 不持有任何云凭据；
4. 创建计费资源的供应 Job 由受保护环境（protected environment）审批门禁把关；
5. 工作流定义、Analysis Skill、Analysis MCP 工具链一律来自可信main；
6. 修复类 Draft PR 始终以当前main为目标；
7. 任意分支与 fork PR 提交被排除在外，直到另行设计并批准"非可信来源模式"（untrusted-source mode）。

该 ADR 与 ADR-0036：Deliver cloud simulation as verified tracer phases 描述的"分阶段验证"路径互为补充：后者决定何时开放某个能力，前者决定允许什么代码来源进入这条路径。

二、信任的核心：source_sha 必须属于可信 main 历史

2.1 输入面：默认分支 + 可选精确提交

在 cloud-sim-provision.yml 中，workflow_dispatch的输入定义直接体现了信任策略：

on: workflow_dispatch: inputs: source_sha: description: Optional exact commit reachable from trusted main; empty uses current main required: false default: "" type: string

• 该工作流没有pull_request或push触发事件，只能通过workflow_dispatch手动发起；
• source_sha为空时使用当前main最新提交，有值时必须是"可从可信 main 到达的精确提交"；
• scripts/cloud-sim/setup.sh中同样固化这一前提：它要求默认分支必须是main，否则直接失败（the current trust policy requires main to be the default branch），并在引导完成后通过repos/$repository/commits/main解析可信main的 40 位 SHA 作为推荐输入。

2.2 校验面：一条完整的 Git 信任证明链

供应工作流构建 Job 的第一步Prove source is a trusted main revision是信任策略的程序化落地，逐条实现了"属于可信 main 历史"的定义：

git fetch --no-tags origin main source_sha="$REQUESTED_SOURCE_SHA" if [[ -z "$source_sha" ]]; then source_sha="$(git rev-parse origin/main)" fi [[ "$source_sha" =~ ^[0-9a-f]{40}$ ]] # 1. 必须是完整 40 位 SHA git cat-file -e "${source_sha}^{commit}" # 2. 该对象必须是真实存在的 commit git merge-base --is-ancestor "$source_sha" origin/main # 3. 必须是 origin/main 的祖先 git checkout --detach "$source_sha" # 4. 检出到分离 HEAD test "$(git rev-parse HEAD)" = "$source_sha" # 5. 确认检出的就是声明的提交

这五个断言缺一不可：

校验通过后，SOURCE_SHA会写入GITHUB_ENV并作为 Job 输出传递给后续步骤，同时被写入部署 bundle 的bundle-spec.json与运行时的analysis.env（WK_ANALYSIS_SOURCE_SHA），使整条链路（构建 → 供应 → 分析）都能追溯到同一个被信任的提交。

同样的merge-base --is-ancestor祖先校验模式也复用在仓库的其他发布/部署工作流中（如 cloud_deployment_bundle_workflow_test.go 中git -C source merge-base --is-ancestor "$REQUESTED_SOURCE_SHA" origin/main的断言），说明"祖先链信任"是仓库级一致的安全惯例，而非云仿真独有。

三、凭据与责任分离：无凭据构建 + 受保护环境供应

信任策略的另一个关键设计是把"构建"和"创建计费资源"拆成两个 Job，并施加完全不同的权限。

3.1 build Job：只读、无云凭据

在 cloud-sim-provision.yml 顶部，整个工作流的最小权限声明为：

permissions: contents: read

build Job 内部只做三件事：

1. 证明源码属于可信 main（上文 2.2 的 Git 校验链）；
2. 构建静态 Go 二进制（wukongim、wkcli、wkanalysis、wkcloudsim、wkcloudbundle、wkcloudhost、wkcloudgate等，CGO_ENABLED=0交叉编译）；
3. 使用wkcloudbundle render渲染并密封不可变部署包（bundle），连同bundle_digest、scenario_digest一起作为输出。

它没有id-token: write，也不访问任何secrets.ALIBABA_CLOUD_*，因此即使某个被误接受的提交中包含恶意代码，构建阶段也无凭据可窃取——它生产的是一个可校验摘要的静态产物，而不是一个有权限的动作。

3.2 provision Job：受保护环境门禁 + 短期身份

真正的计费动作集中在 provision Job：

provision: needs: build runs-on: ubuntu-24.04 environment: cloud-sim-provision # 受保护环境，需人工审批 permissions: contents: read actions: write id-token: write

• 受保护环境cloud-sim-provision：GitHub 允许为环境配置审批者，workflow_dispatch触发后，创建计费资源前需要经过环境审批。这是决策中"protected-environment approval gates the provisioning job that creates billable resources"的直接体现；
• id-token: write：Job 通过 GitHub OIDC 换取短时、工作流条件限定的 STS 身份（aliyun/configure-aliyun-credentials-action配合ALIBABA_CLOUD_SIM_PROVISIONER_ROLE_ARN等变量），替代长期 AccessKey 存储在仓库中；
• 该 Job 还执行运行身份派生（run_id=gh-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}）、创建精确运行资源（wkcloudsim create）、部署 bundle、执行 Bootstrap Gate 校验、开启公共观测、启动工作负载并落盘finalize.json调度清单等一系列动作。

关于凭据模式，ADR-0038：Allow AccessKey onboarding with OIDC fallback 进一步说明：仓库同时支持两种阿里云认证模式，AccessKey 对（作为 Repository Secrets）仅在受保护的云 Job 内可用，从不写入源码、制品、摘要、云主机或日志；OIDC 仍是长期优选的加固路径，因为它用短时工作流限定 STS 凭据替代了存储的长期凭据。无论哪种模式，凭据都不会流经 build Job。

四、端到端可信：工作流定义、Analysis Skill 与 MCP 工具链

ADR-0020 的信任承诺不止于供应环节，还延伸到消费这些资源的一方——分析工作流。

4.1 分析工作流固定在 main 上执行

在 cloud-sim-analyze.yml 中：

jobs: prepare: runs-on: ubuntu-24.04 environment: cloud-sim-analysis permissions: contents: read actions: read id-token: write steps: - uses: actions/checkout@... with: ref: main # 工作流定义与工具链永远来自 main persist-credentials: false

checkout固定ref: main，意味着执行分析的代码（工作流定义、Analysis Skill、MCP 工具实现）永远来自可信 main，而不是来自某个可能被篡改的运行时分支。

4.2 运行时契约也携带 main 引用

供应阶段写入 sim 主机analysis.env的环境变量同样固化了信任边界：

WK_ANALYSIS_GITHUB_REF=refs/heads/main WK_ANALYSIS_GITHUB_WORKFLOW_REF=$GITHUB_REPOSITORY/.github/workflows/cloud-sim-analyze.yml@refs/heads/main WK_ANALYSIS_GITHUB_ENVIRONMENT=cloud-sim-analysis

这些变量与服务端契约测试（见 runtime_contract_test.go 所覆盖的运行时契约）配合，确保部署到云上的分析端只知道"来自 main 的仓库身份"，不会把任意分支当作合法来源。

4.3 分析只针对存活的运行

信任策略与 ADR-0003：Analyze live Simulation Runs only 形成闭环：分析工作流通过 Run Locator 精确解析运行（cloud-sim-locator-${RUN_ID}制品，要求run_id、source_sha、scenario_digest、region、account_id_hash全部通过格式校验），并依据云端资源清单验证运行仍存活；若运行已释放，则记录释放证据并以失败状态终止，避免"缺失的分析被误认为成功"。这里的source_sha正是供应阶段从可信 main 证明后写入 Run Locator 的同一个提交。

五、修复 Draft PR 永远指向当前 main

ADR-0020 还规定：修复类 Draft PR 必须针对当前main。这意味着分析发现的问题即使被自动生成修复建议，也不会把补丁开到一个中间分支上，而是始终以最新可信 main 为基线，避免"基于过期 main 的修复"引入漂移或冲突。结合 ADR-0036 的分阶段计划，"隔离的 Draft-PR 修复"本身就是一个独立验证阶段，只有本地契约、阿里云生命周期、实时分析依次证明稳定后才会启用仓库变更能力。

六、排除面：任意分支与 fork PR 提交

第一版策略明确排除：

• 任意分支的提交；
• fork Pull Request 的提交。

只要这些来源的提交不满足"可信 main 祖先"这一几何条件，就会在Prove source is a trusted main revision步骤被merge-base --is-ancestor拒绝，工作流直接失败。仓库目前的 34 个云相关工作流均以workflow_dispatch为入口（见 .github/workflows 目录），没有为 PR 来源开放云供应入口，与"untrusted-source mode 需另行设计并批准"的决策一致。

七、实现与测试证据

该策略不是停留在文档层面的声明，而是被测试固化的行为契约：

• cloud_sim_workflows_test.go 断言工作流输入source_sha的说明文案为 "Optional exact commit reachable from trusted main; empty uses current main"，防止信任语义被无意改写；
• setup.sh 强制默认分支为main、要求.github/workflows/cloud-sim-provision.yml等文件在远端 main 上存在、并在引导完成后输出一组推荐输入（region、source_sha、scenario=cloud-small、duration=30m、max_total_cost=70），把"可信 main 起点"直接交到首次验证运行的启动者手中；
• cloud-sim-provision.yml 的Prove source is a trusted main revision步骤是决策中每条规则的可执行实现。

八、相关决策链路

这篇 ADR 属于 WuKongIM 云仿真治理体系的一环，与以下记录联动阅读更完整：

• ADR-0003：分析只针对存活的运行，释放证据与失败语义；
• ADR-0021：工作负载时长与分析宽限分离，运行租约整体参与成本估算；
• ADR-0036：按验证阶段逐步开放能力；
• ADR-0038：AccessKey 快速上云与 OIDC 长期加固的凭据模式；
• 其他如 ADR-0015（成本与并发护栏）、ADR-0030（分析访问窗口）共同构成"只有可信代码、只有受控成本、只有有界时间"的完整护栏。

总结：ADR-0020 回答的是"谁有资格让 WuKongIM 在云端花钱运行仿真"这一安全问题。它的答案是：只有可证明属于可信main祖先链的提交，只有只读、无凭据的构建，只有受保护环境审批后的供应动作，以及永远来自main的工作流与工具链。这套"Git 祖先证明 + 权限最小化 + 环境门禁"的组合，使云仿真的每个计费动作都可以追溯到仓库中一个被明确信任的源码修订。

• 即时通讯
• 后端