企业官网建设流程全解析

Chainlink Local CRE 参考手册：源码锚点、环境命令与拓扑文档生成指南

【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink

本篇文章是面向Local CRE（本地 Chainlink Runtime Environment）贡献者与调试者的深度参考指南。它以仓库中docs/local-cre/reference/index.md为骨架，逐条剖析官方文档列出的核心源码锚点（入口main.go、环境管理environment.go、工作流管理workflow.go、拓扑发现topology.go、测试辅助等），完整梳理env、workflow、topology三大命令族的全部子命令与参数，并讲透拓扑文档的生成机制。读完本文，你将能快速定位 Local CRE 的关键实现文件、熟练使用其命令行工具，并能够自行生成与校验拓扑文档。

Local CRE Reference 页面在文档体系中的定位

docs/local-cre/reference/index.md是 Local CRE 文档体系中的索引式参考页，其定位非常明确：为 Local CRE 贡献者收集“有实现支撑（implementation-backed）”的最实用参考，而不是重复展开操作教程。它提供了三类信息：

1. 关键源码锚点（Key Source Anchors）：从 CLI 入口到系统测试辅助的一串精确文件路径；
2. 生成产物（Generated Artifacts）：由命令自动产出的拓扑文档及其存放位置、生成命令；
3. 主环境命令（Main Environment Commands）：覆盖环境生命周期、工作流部署、拓扑管理的核心 CLI 调用。

该页与同目录下的 Getting Started、Environment、System Tests 互为补充——前者回答“怎么做”，本参考页回答“去哪里看代码、跑什么命令”。

关键源码锚点：8 个文件定位 Local CRE 的实现核心

1. CLI 入口：core/scripts/cre/environment/main.go

Local CRE 的整个 CLI 由core/scripts/cre/environment/main.go驱动。它通过init()将四个命令组挂载到root.RootCmd上：

• environment.EnvironmentCmd——env命令族（环境生命周期、工作流、状态等）；
• environment.TopologyCmd()——topology命令族（拓扑发现、可视化、文档生成）；
• examples.ExamplesCmd——示例工作流相关命令；
• environment.BsCmd与environment.ObsCmd——billing（计费服务）与 observability（可观测性）辅助命令。

main()中还内置了两个快捷参数：传入version/--version/-v时打印Local CRE version: <version>, commit: <commit>, date: <date>；传入shell/sh时进入交互式 Shell，并默认把CTF_CONFIGS设置为configs/workflow-gateway-don.toml。其余参数一律交给 cobra 根命令执行，出错时打印错误并退出码 1。

值得注意的是，root.RootCmd定义于 root/root.go，其Use字段为local_cre（这也是make install安装出的二进制名），描述为“CLI tool for the local CRE to create and manage environments”。因此下面所有go run . <command>等价于安装后执行local_cre <command>。

2. 环境生命周期实现：environment/environment.go

environment.go 是env命令族的核心实现，文件体量约 1300 行，涵盖：start（含restart别名）、stop、status、workflow、chip-ingress-stack、swap、state、billing等子命令（见其init()中EnvironmentCmd.AddCommand(...)的注册列表）。其中几个关键实现细节值得注意：

• env start的启动流程（startCmd的RunE）：先执行setDefaultCtfConfigs()——若未显式设置CTF_CONFIGS环境变量，则默认使用configs/workflow-gateway-capabilities-don.toml，并始终在其前面追加configs/capability_defaults.toml作为能力默认配置；随后设置TESTCONTAINERS_RYUK_DISABLED=true防止容器被 Ryuk 回收；加载并校验CTF_CONFIGS指定的 TOML 配置；生成拓扑可视化产物；最终调用StartCLIEnvironment完成整套环境的装配（20 分钟超时）。
• 端口占用诊断：当启动失败且错误包含address already in use时，CLI 会用lsof -nP -iTCP:<port>自动探测端口占用情况并打印占用进程，方便快速定位冲突。
• 失败恢复：StartCmdRecoverHandlerFunc会在启动 panic 时打印堆栈、上报 DX 追踪，并可（在--cleanup-on-error下）等待一段时间后保存容器日志、移除测试容器。
• env stop的智能提示：stopCmd在仅停止主环境后，会通过detectServiceStatus检测 Chip Ingress 栈、Billing、Observability 是否仍在运行，并给出对应的停止命令提示；加--all则一并移除全部附加服务并清理环境状态文件。

3. 工作流管理实现：environment/workflow.go

workflow.go 实现env workflow命令族，共注册 5 个子命令：deploy-and-verify-example、delete、delete-all、compile、deploy。文件里定义了默认工作流所有者地址常量：

DefaultWorkflowOwnerAddress = "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266"

deploy的完整执行链（deployWorkflow）分五步走，每一步都有清晰的日志输出：

1. 拷贝产物到容器：通过creworkflow.CopyArtifactsToDockerContainers把 base64 编码的工作流 WASM 文件拷贝到匹配容器名模式的工作流节点容器内；
2. 创建 Seth 客户端：newSethClient会确保PRIVATE_KEY环境变量存在（缺省时回退到blockchain.DefaultAnvilPrivateKey），并构造 RPC 客户端；
3. 拷贝配置文件（可选）：若指定--config-file-path，则把配置拷贝进容器，并以file://绝对路径形式传给注册调用；
4. Vault 密钥流程（可选，--secrets-file-path）：要求 Workflow Registry 与 Capabilities Registry 均为v2 版本合约，从网关拉取 Vault 公钥、检查/更新 Capabilities Registry 中的 Vault 能力配置、等待 registry syncer 传播，最后用公钥加密密钥并以 JSON 形式经网关下发到 Vault；
5. 注册工作流：先从注册表删除同名旧工作流（不存在则跳过），再以donID、donFamily、名称、标签、file://WASM 路径等参数调用creworkflow.RegisterWithContract完成注册。

此外，compile子命令的底层实现在system-tests/lib/cre/workflow/compile.go中（见下文第 8 点），delete/delete-all则直接调用注册表合约的删除方法。

4. 拓扑发现与文档生成实现：environment/topology.go

topology.go 实现topology命令族：list、show、generate。其核心机制是自动发现拓扑配置：递归扫描configs/目录下所有.toml文件（排除capability_defaults.toml），仅当文件中同时存在nodesets、blockchains、jd、infra四个顶层字段时才判定为拓扑配置（isTopologyConfig函数，对应topologyProbe结构体）。list输出 ASCII 表格（列：Topology / Class / DONs），show为单个配置渲染 ASCII 拓扑图并写出产物，generate则为全部配置批量生成 Markdown 文档与索引（详见下节）。

5. 系统测试入口：system-tests/tests/smoke/cre/cre_suite_test.go

cre_suite_test.go 是 CRE 冒烟测试套件的入口。文件头部注释给出了标准的本地执行方式：

1. 在 core/scripts/cre/environment 目录下执行: go run . env restart --with-chip-ingress-stack 2. 在 system-tests/tests/smoke/cre 目录下执行: go test -timeout 15m -run "^Test_CRE_"

测试按桶（Bucket）划分：Test_CRE_V2_Suite_Bucket_A/B/C分别执行suite_config.SuiteBucketA/B/C中的用例，测试命名还会读取TOPOLOGY_NAME环境变量以区分拓扑。

6~7. 测试辅助：system-tests/tests/test-helpers/before_suite.go与t_helpers.go

这两个文件位于 system-tests/tests/test-helpers/，是系统测试与 Local CRE 环境之间的桥梁：before_suite.go负责测试套件运行前的前置逻辑（含在状态文件缺失时自动拉起 Local CRE），t_helpers.go则提供贯穿用例的通用辅助函数（如环境变量读取、并行开关ParallelEnabled()等）。它们消费env start写入的 repo 本地状态文件，这就是“测试辅助能探测到已存在环境并避免重复创建”的原因。

8. 工作流编译：system-tests/lib/cre/workflow/compile.go

compile.go 实现了工作流从源码到可部署产物的编译管线：

• 语言检测：支持go与typescript两种工作流语言；
• 编译：Go 工作流编译为 WASM；TypeScript 工作流同理编译为 WASM；
• 压缩与编码：用 Brotli 压缩 WASM，再 base64 编码（这正是env workflow deploy要求输入“base64 编码、已编译的 WASM 文件”的原因）；
• 约束：工作流名称长度必须不少于 10 个字符，否则直接报错。

生成产物：拓扑文档的存放位置与生成命令

Local CRE 会把拓扑配置自动渲染成文档并固化在仓库中，产出物有两类：

• core/scripts/cre/environment/docs/TOPOLOGIES.md——拓扑索引总表；
• core/scripts/cre/environment/docs/topologies/——每个拓扑配置一份独立的 Markdown 文档。

生成命令（在core/scripts/cre/environment目录下执行）：

go run . topology generate

从 TOPOLOGIES.md 可以看到生成索引的形态（该文件头部明确标注“generated bygo run . topology generate. Do not edit manually”，即人工不要直接编辑生成产物）：

表中每一行都链接到topologies/下的详细文档。topology generate命令还提供--check模式（对应源码writeOrCheck的逻辑）：只比对产物是否过期而不写盘，发现过期即报错列出需要重新生成的文件，适合接入 CI 做文档一致性校验。

除了generate，topology命令族还包括：

go run . topology list # 列出 configs/ 下发现的全部拓扑配置（ASCII 表格） go run . topology show # 为单个配置渲染 ASCII 拓扑图并输出产物

show的常用参数：--config（-c，默认configs/workflow-gateway-don.toml）、--output-dir（-o，默认state）。generate的参数：--output-dir（-o，默认docs/topologies）、--index-path（-i，默认docs/TOPOLOGIES.md）、--check（仅校验）。

主环境命令全解析

以下是官方参考页列出的核心命令，结合源码展开其子命令与参数细节。所有命令均需在core/scripts/cre/environment目录下执行（或使用make install安装后的local_cre二进制）。

环境生命周期

go run . env setup # 校验并准备前置条件：Docker、AWS、Job Distributor、CRE CLI 等 go run . env start # 启动 Local CRE 环境（restart 是 start 的别名） go run . env stop # 停止环境（只停主环境；加 --all 同时移除附加服务与状态文件） go run . env restart # 等价于 go run . env start

• env setup参数（见 setup.go）：-c/--config（默认configs/setup.toml）、-y/--no-prompt（不交互直接采用默认值）、-p/--purge（清除已有镜像重新拉取/构建）、-b/--build（本地构建而非从 ECR 拉取，Apple Silicon 常用）、--with-billing。setup 由configs/setup.toml驱动，管理 Job Distributor、Chip Router、Chip Ingress、Chip Config 等托管镜像。
• env start参数（定义于 environment.go）非常丰富，重点如下：

• env stop参数：-a/--all，移除所有附加服务（Chip Ingress 栈、Billing、Observability）并清理环境状态目录。不带--all时，若检测到附加服务仍在运行，会打印相应的停止提示命令。

工作流部署与删除

go run . env workflow deploy # 部署工作流到环境 go run . env workflow delete # 从 Workflow Registry 合约删除指定工作流 go run . env workflow delete-all # 清空注册表中的全部工作流 go run . env workflow compile # 只编译（Brotli 压缩 + base64 编码），不部署

env workflow deploy的完整参数清单（见 workflow.go）：

拓扑管理

go run . topology list go run . topology show go run . topology generate

参数细节见前文“生成产物”一节，此处不再重复。需要强调的是：topology generate具备--check校验模式，可直接作为 CI 中“拓扑文档是否过期”的门禁；而topology list是对configs/目录的一次实时扫描，能反映新增拓扑配置而不需要重新生成文档。

从源码看命令背后的关键机制

CTF_CONFIGS与配置叠加

env start与topology系列命令都依赖CTF_CONFIGS环境变量。源码setDefaultCtfConfigs()展示了它的叠加语义：默认值configs/workflow-gateway-capabilities-don.toml之前始终会被前缀拼接configs/capability_defaults.toml，形成“能力默认配置 + 拓扑配置”的多文件列表（逗号分隔）。topology相关命令在加载单个配置时也复用这一机制：cfgArg := defaultCapabilitiesConfigFile + "," + configPath。这意味着任何拓扑 TOML 都能继承能力默认值，且自身字段可以覆盖之。

拓扑配置的判定条件

从topologyProbe与isTopologyConfig可以看出，一份 TOML 要被识别为拓扑配置，必须同时包含blockchains、nodesets、jd、infra四个顶层字段。这也是为什么 configs/ 目录下像billing-platform-service.toml、capability_defaults.toml、chip-ingress.toml这类单组件配置不会被误判为拓扑。

状态文件与测试辅助的衔接

env start成功后会把配置与已部署合约地址写入 repo 本地的状态文件（in.Store(...)），t_helpers.go 与before_suite.go正是读取该状态来判断环境是否已就绪；resolveRPCURL、resolveRegistryContractAddressAndVersion等函数也体现了“命令行参数优先、状态文件兜底”的取值策略，这是 Local CRE 命令与测试能够无缝衔接的根基。

从参考页出发：继续深入的三条路径

官方参考页末尾以 “Related Pages” 收尾，为贡献者指路，下面已按仓库根目录相对路径转换：

• Getting Started——从干净 checkout 到运行环境与首个冒烟测试的最短路径，含env setup/env start --auto-setup的完整引导；
• Environment——环境生命周期、Chip Ingress 栈、端口规划（如50050Chip Router admin、50051Chip Router ingress gRPC、50053Chip Ingress gRPC）、状态存储与排障的完整展开；
• System Tests——CRE 系统测试套件的组织方式、运行模式（本地 / Kubernetes / CI）与维护说明。

此外，core/scripts/cre/environment/README.md中的 Quickstart 给出了与本参考页互补的最短实操命令：

cd core/scripts/cre/environment go run . env start --auto-setup go run . env workflow deploy -w ./examples/workflows/v2/cron/main.go --compile -n cron_example

小结

docs/local-cre/reference/index.md虽然篇幅精炼，却是理解 Local CRE 工程结构的“地图”：8 个源码锚点分别覆盖 CLI 入口、环境装配、工作流管线、拓扑生成与系统测试五大模块；env/workflow/topology三大命令族支撑起从环境拉起、工作流发布到文档产出的完整闭环。结合本文对源码的逐条展开，贡献者可以快速建立“文档→源码→命令→测试”的映射，无论是二次开发、调试环境问题，还是维护拓扑文档，都能做到有的放矢。

【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink