ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

Chainlink 节点 Secrets 配置完全指南:TOML 密钥格式、环境变量覆盖与安全校验

Chainlink 节点 Secrets 配置完全指南:TOML 密钥格式、环境变量覆盖与安全校验 Chainlink 节点 Secrets 配置完全指南TOML 密钥格式、环境变量覆盖与安全校验【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink本指南以 Chainlink 节点仓库中的 docs/SECRETS.md 为核心系统讲解节点敏感信息数据库连接、Keystore 口令、OIDC/LDAP 认证、Mercury 凭证、可观测性 Token 等的 TOML 配置格式、对应的CL_环境变量以及底层校验逻辑。读完本文你将能够独立编写一份合法的 secrets 配置理解每一项参数的用途与默认值并知道节点在启动时如何合并、校验和脱敏这些敏感配置。什么是 Secrets 配置与普通配置有何区别Chainlink 节点使用 TOML 格式管理配置其中非敏感配置端口、链参数、日志级别等记录在config.toml而敏感配置数据库口令、密钥加密口令、第三方服务 Token 等单独记录在secrets.toml。这样设计的目的非常明确secrets 文件可以设置更严格的文件权限可以单独备份、单独注入例如通过 Kubernetes Secret 挂载避免把明文密钥混入普通配置导致意外泄露。在源码层面这个划分由 core/config/toml/types.go 中的Secrets结构体承载它包含Database、Password、WebServer、Pyroscope、Prometheus、Mercury、Threshold、EVM、Solana、Aptos、Stellar、P2PKey、DKGRecipientKey、CRE、CCV等多个子结构见 core/config/toml/types.go#L145-L163。每个子结构都带有toml:,omitempty标签意味着未设置的项不会出现在序列化结果中。每个秘密项都有一个对应的环境变量格式统一为CL_前缀加大写下划线命名例如CL_DATABASE_URL、CL_PASSWORD_KEYSTORE。也就是说你可以完全不写 secrets 文件而是通过环境变量注入全部敏感信息环境变量在加载时优先于文件中的值见下文“环境变量覆盖机制”一节。最小可运行示例一个仅包含两项必需配置的最小 secrets 文件如下# Required标注的项是节点启动所必需的[Database] URL postgresql://user:passlocalhost:5432/dbname?sslmodedisable # Required [Password] Keystore keystore_pass # Required其中Database.URL是节点连接 PostgreSQL 的 URIPassword.Keystore是加密节点账户EVM 私钥等的 Keystore 口令。这两个值缺一不可——源码中DatabaseSecrets.validateConfig会直接报错URL must be provided and non-empty见 core/config/toml/types.go#L526-L542而 Keystore 口令缺失则无法解锁链上账户。Database数据库连接与备份[Database] URL postgresql://user:passlocalhost:5432/dbname?sslmodedisable # Example BackupURL postgresql://user:passread-replica.example.com:5432/dbname?sslmodedisable # Example AllowSimplePasswords false # DefaultURL环境变量CL_DATABASE_URLPostgreSQL 连接 URI。Chainlink 节点要求 Postgres版本 11。连接串必须包含认证信息用户名与密码因为源码会校验密码复杂度。BackupURL环境变量CL_DATABASE_BACKUP_URL自动数据库备份时拉取数据的来源地址而非主CL_DATABASE_URL。官方建议如果部署了只读副本就把此值指向只读副本避免备份任务给主库带来额外负载。AllowSimplePasswords环境变量CL_DATABASE_ALLOW_SIMPLE_PASSWORDS默认false。该开关用于跳过对 URL 与 BackupURL 强制执行的密码复杂度检查。源码中的校验逻辑值得注意见 core/config/toml/types.go#L497-L520数据库名包含_test或以testdb_开头时视为测试库跳过密码复杂度校验URL 必须包含密码query 参数password或 userinfo 中的密码否则报错DB URL must be authenticated密码需要满足utils.PasswordComplexityRequirements定义的复杂度要求否则报错missing or insufficiently complex password。更重要的是安全边界在secure/prod 构建模式下即使设置了AllowSimplePasswords true也会被拒绝报错insecure configs are not allowed on secure builds见 core/config/toml/types.go#L529-L530。因此请只在本地开发环境考虑放宽该检查生产节点务必使用强密码。WebServer.OIDC 与 WebServer.LDAPWeb 登录认证节点 Web 服务支持两种外部认证方式均为可选配置。OIDC 客户端密钥[WebServer.OIDC] clientSecret secret # ExampleclientSecret是发送给 OIDC 提供方、用于把授权码兑换为 ID Token 的机密值。对应的结构体WebServerOIDCSecrets在 core/config/toml/types.go#L1429 中定义校验逻辑要求该字段不能为空见 core/config/toml/types.go#L1467-L1470。LDAP 服务配置[WebServer.LDAP] ServerAddress ldaps://127.0.0.1 # Example ReadOnlyUserLogin viewerexample.com # Example ReadOnlyUserPass password # ExampleServerAddressLDAP 服务器的完整ldaps://地址用于认证与查询ReadOnlyUserLogin只读根用户的用户名用于发起 LDAP 查询时的认证ReadOnlyUserPass上述账户的密码。WebServerLDAPSecrets的校验要求这三个字段要么同时为空不启用 LDAP要么全部非空见 core/config/toml/types.go#L1450-L1465避免出现“配了地址却忘了用户名”这类半配置状态。Password节点密钥口令[Password] Keystore keystore_pass # Example VRF VRF_pass # ExampleKeystore环境变量CL_PASSWORD_KEYSTORE节点账户即节点用来签名交易的 EVM 账户的加密口令属于必需项VRF环境变量CL_PASSWORD_VRFVRF 密钥的加密口令运行 VRF 服务时需要。在 core/services/chainlink/testdata/secrets-full.toml 中可以找到与链密钥配套的完整示例其中[EVM.Keys]、[Solana.Keys]、[P2PKey]等段直接嵌入了 JSON 格式的加密密钥内容及其Password字段。也就是说secrets 文件不仅是口令的存放处也承担着导入加密密钥材料的职责。Pyroscope 与 Prometheus可观测性 Token[Pyroscope] AuthToken pyroscope-token # Example [Prometheus] AuthToken prometheus-token # ExamplePyroscope.AuthToken环境变量CL_PYROSCOPE_AUTH_TOKENPyroscope 持续性能分析服务端的 API KeyPrometheus.AuthToken环境变量CL_PROMETHEUS_AUTH_TOKENPrometheus 指标端点的鉴权密钥用于保护/metrics类端点不被任意抓取。两个子结构在 core/config/toml/types.go#L740-L790 中定义均支持多文件合并SetFrom/validateMerge。Mercury.CredentialsMercury 数据流凭证Mercury 是 Chainlink 的低延迟数据流Data Streams服务节点访问 Mercury 价格源时需要配置认证凭证。Mercury.Credentials下的键名是任意自定义的名称示例中使用Name作为占位符每个凭证包含四个字段[Mercury.Credentials.Name] Username A-Mercury-Username # Example Password A-Mercury-Password # Example URL https://example.com # Example LegacyURL https://example.v1.com # ExampleUsername / Password访问 Mercury 端点的 Basic Auth 用户名与密码URL访问 Mercury 价格源的端点基础地址LegacyURL访问 Mercuryv0.2 旧版价格源的端点基础地址。该段支持多凭证并存。在 core/services/chainlink/testdata/secrets-full.toml 中可以看到cred1、cred2、cred3三个凭证并列的写法其中cred3同时配置了URL与LegacyURL用于同时访问新旧两套端点。凭证的合并语义同名键不允许被第二个文件覆盖由 core/config/toml/types.go#L1962-L2000 的MercurySecrets.validateMerge保证。Threshold门限解密密钥分片[Threshold] ThresholdKeyShare A-Threshold-Decryption-Key-Share # ExampleThresholdKeyShare供门限解密 OCR 插件threshold decryption OCR plugin使用是节点持有的解密密钥分片。对应的ThresholdKeyShareSecrets结构体在 core/config/toml/types.go#L2879 中定义。CRE.Streams 与 CRE.LocalSecretOverridesCRE 工作流相关密钥CREChainlink Runtime Environment是节点内运行链下计算工作流的框架相关密钥集中在[CRE]段下。Data Streams SDK 凭证[CRE.Streams] ApiKey streams-api-key # Example ApiSecret streams-api-secret # ExampleApiKey与 CLL Data Streams SDK 通信时使用的 API KeyApiSecret对应的 API Secret。注意 core/services/chainlink/testdata/secrets-full.toml 中该段写作APIKey/APISecretTOML 键大小写不敏感两者等价。实际生成的文档模板 core/config/docs/secrets.toml 中使用的是ApiKey/ApiSecret形式。本地密钥覆盖Vault 故障兜底[CRE.LocalSecretOverrides]该表是空表头实际内容为“工作流属主地址 → (secret id → 明文值)”的嵌套映射0000000000000000000000000000000000000000 { my-secret-id my-plaintext-value } # Example语义当该映射非空时节点在Vault 调用失败时会使用这里的覆盖值作为兜底保证工作流仍能读取到所需密钥。这是为本地开发/测试环境设计的降级通道——生产环境依赖 Vault 时通常不需要配置。密钥材料的导入EVM / Solana / P2PKey 等虽然 docs/SECRETS.md 主要介绍上述口令类配置但从Secrets结构体core/config/toml/types.go#L145-L163可以看出secrets.toml 还承载了链密钥与节点密钥的导入包括EVM、Solana、Aptos、Stellar、P2PKey、DKGRecipientKey等段。以 EVM 为例[EVM] [[EVM.Keys]] JSON {address:0x...,crypto:{...},version:3} ID 1337 Password 每个密钥条目包含三部分JSONWeb3 Secret Storage 格式的加密密钥 JSON、ID对应链 ID、Password该密钥的加密口令留空则使用Password.Keystore中的全局口令。完整的多链示例见 core/services/chainlink/testdata/secrets-full.toml其中可以看到同一 EVM 密钥 JSON 分别挂在ID 1337与ID 9999两条链上、Solana 密钥按devnet/mainnet网络区分、以及[P2PKey]段内嵌 P2P 加密私钥的完整写法。这种设计让节点可以通过一份 secrets 文件完成“密钥导入 口令设置”的全部敏感操作。环境变量覆盖机制与合并规则每个带环境变量的配置项都可以被CL_前缀环境变量覆盖。以CL_DATABASE_URL为例Secrets.setEnv的实现见 core/services/chainlink/config.go#L505-L509会先读取环境变量非空时直接替换Database.URL。这种“环境变量 文件”的优先级让容器化部署Docker、Kubernetes Secret无需把敏感值写进文件。此外secrets 配置还支持多文件合并Secrets.SetFrom见 core/services/chainlink/config.go#L376-L440会逐段合并两个 secrets 配置且通过validateMerge拒绝同一段内相同字段的重复定义返回ErrOverride防止低优先级的文件悄悄覆盖高优先级文件的值。仓库中的测试数据 core/services/chainlink/testdata/mergingsecretsdata/ 展示了这一能力数据库、口令、Mercury 凭证、LDAP、Prometheus、Pyroscope 等可以拆分成多个独立 secrets 文件由节点在启动时合并生效。相关测试位于 core/services/chainlink/config_general_test.goTestConfig_SecretsMerging。脱敏、校验与安全注意事项节点对 secrets 提供了三重保护脱敏输出Secrets.TOMLString见 core/services/chainlink/config.go#L448-L455在序列化输出配置时会隐藏敏感值避免管理界面或日志暴露明文。测试数据中可以看到对应的脱敏结果文件如 core/services/chainlink/testdata/secrets-full-redacted.toml 与 core/services/chainlink/testdata/secrets-multi-redacted.toml。启动时校验Secrets.Validate见 core/services/chainlink/config.go#L475-L480会累积式地校验所有段错误以InvalidSecretsError形式返回ValidateDBcore/services/chainlink/config.go#L483-L502则只校验数据库段用于在完整配置加载前提前暴露数据库连接问题。生产构建强约束如数据库密码复杂度一节所述AllowSimplePasswords等“放行开关”在 secure/prod 构建下会被拒绝从构建层面杜绝弱口令上线。实操建议汇总将secrets.toml与config.toml分离存放并对 secrets 文件设置严格的文件权限如0600数据库与备份库务必使用强密码除非是本地测试库否则不要设置AllowSimplePasswords true容器化环境优先使用CL_*环境变量注入敏感值避免明文写盘如需拆分管理可利用多文件合并能力按模块数据库、Mercury、可观测性分别维护 secrets 片段上线前通过节点日志确认TOMLString输出已脱敏并核对Validate未返回InvalidSecretsError。更完整的非敏感配置项请参阅仓库内的 docs/CONFIG.md本文所依据的原始文档 docs/SECRETS.md 由 core/config/docs/secrets.toml 自动生成修改源码中的注释后重新生成即可保持文档与实现一致。【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表