dlt 凭据配置实战指南secrets.toml、环境变量与 Google Cloud Secret Manager【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dltdltdata load tool作为开源 Python 数据加载库其核心设计之一就是将凭据credentials与业务代码彻底分离你不需要在脚本里硬编码 API Key 或私钥而是通过.dlt/secrets.toml、环境变量或云密钥托管服务Vault集中管理。本文以 docs/website/docs/walkthroughs/add_credentials.md 为主线完整覆盖本地开发与生产部署两种场景下的凭据注入方式并结合仓库源码配置 Provider 实现说明底层工作机理。读完本文你将掌握如何编写secrets.toml、如何把配置映射为环境变量命名、如何从 Google Cloud Secret Manager 拉取凭据并优化调用成本以及如何扩展自定义 Vault Provider。凭据管理的核心机制配置 Provider 与查询顺序在深入具体写法之前先理解 dlt 的配置体系。dlt 通过**配置提供者Config Provider**从不同位置读取配置与密钥运行管线时按以下顺序依次查询一旦在某处命中即停止不再查询优先级更低的提供者环境变量优先最高常用于部署环境secrets.toml与config.toml文件本地开发主力前者存放敏感信息后者存放非敏感配置Vault密钥托管服务如 Google Cloud Secret Manager、AWS Secrets Manager、Airflow Variables自定义 Provider通过register_provider注册的自定义实现函数签名默认值兜底。以上顺序与查询细节见 docs/website/docs/general-usage/credentials/setup.md。这套机制的实现位于 dlt/common/configuration/providers 目录environ.py负责环境变量toml.py负责 TOML 文件vault.py与google_secrets.py负责密钥托管服务它们统一继承自ConfigProvider基类。正是因为有了这套 Provider 抽象同一个api_key参数既可以从secrets.toml注入也可以从环境变量注入代码无需任何改动。本地开发使用 .dlt/secrets.toml在本地运行管线时官方推荐使用.dlt/secrets.toml方式。打开你的 dlt secrets 文件将 section 名和键名与脚本中 source/destination 的参数名一一对应即可。完整示例Pipedrive 源 BigQuery 目标假设你的脚本使用 Pipedrive source 和 BigQuery destinationsecrets.toml应写成[sources.pipedrive] pipedrive_api_key pipedrive_api_key # please set me up! [destination.bigquery] location US [destination.bigquery.credentials] project_id project_id # please set me up! private_key private_key # please set me up! client_email client_email # please set me up!:::note TOML 文件中的键是大小写敏感的section 之间用点号.分隔。 :::secrets.toml 与 config.toml 的分工.dlt目录下实际上有两个文件详见 docs/website/docs/general-usage/credentials/setup.mdconfig.toml存放非敏感配置如bucket_url、数据库主机、超时、日志级别等可安全提交到版本控制secrets.toml存放敏感信息如密码、API Key、私钥绝不能提交到版本控制项目.gitignore默认已排除。两个文件均从当前工作目录下的.dlt文件夹加载。也就是说若你在my_dlt_project目录执行python pipelines/google_sheets.pydlt 会读取my_dlt_project/.dlt/secrets.toml而不是脚本所在目录的.dlt。此外dlt 还会检查~/.dlt/家目录下的全局配置项目配置优先并支持 Google Colab 与 Streamlit 的 secrets 特殊位置相关实现见 dlt/common/configuration/providers/toml.pySettingsTomlProvider。推荐的 section 布局当项目中有多个 source 或 destination 时建议使用以下推荐布局也是dlt init自动生成的布局用sources和destination作为顶级 section 分别隔离源与目标配置用 source 函数所在Python 模块名来区分配置如[sources.notion]对应notion.py中定义的 source用 destination类型名来区分目标如[destination.postgres.credentials]。# source 定义在 notion.py 中 [sources.notion] api_key some_value # 使用 postgres destination [destination.postgres.credentials] user dlthub password some_valuedlt 在查找某个值时会从最完整的路径开始逐级去掉最右侧的 section 重试。例如notion.py中定义了dlt.source def notion_databases(api_key: str dlt.secrets.value)它会依次尝试sources.notion.notion_databases.api_keysources.notion.api_keysources.api_keyapi_key对 destination 凭据credentials视为必需分组不会被消除顺序为destination.postgres.credentials.password→destination.credentials.password→credentials.password。这意味着你可以只写一个顶层[credentials]段让 source 和 destination 共享同一套 Google 凭据如同时用于 Google Sheets 源和 BigQuery 目标。获取具体 source/destination 的凭据不同目标类型与 Verified Source 的凭据格式差异较大目标destination凭据的创建与配置方式参见各目标类型的文档页docs/website/docs/dlt-ecosystem/destinationsVerified Source 凭据的获取方式参见各源的 Setup 指南docs/website/docs/dlt-ecosystem/verified-sources。拿到凭据后填入上文件并保存即可。更系统的配置组织方式可参考 docs/website/docs/general-usage/credentials/ 下的进阶文档。部署环境通过环境变量注入凭据在部署到服务器、容器或调度平台时环境变量是最常见的方式。dlt 完整支持从环境读取凭据且命名约定与 TOML 不同所有名称大写section 之间用**双下划线__**分隔。仍以上述 Pipedrive BigQuery 的secrets.toml为例等价的环境变量为SOURCES__PIPEDRIVE__PIPEDRIVE_API_KEY DESTINATION__BIGQUERY__CREDENTIALS__PROJECT_ID DESTINATION__BIGQUERY__CREDENTIALS__PRIVATE_KEY DESTINATION__BIGQUERY__CREDENTIALS__CLIENT_EMAIL DESTINATION__BIGQUERY__LOCATION环境变量还支持传递字典和列表但必须写成Python 字面量而非 JSON例如export DESTINATION__DUCKDB__CREDENTIALS__PRAGMAS[\enable_logging\]从源码看环境变量的键名拼接逻辑在 dlt/common/configuration/providers/environ.py 的EnvironProvider.get_key_name中实现get_key_name(key, __, *sections).upper()即用__连接各 section 后统一转大写。该 Provider 还有一个实用特性对标记为 secret 的值若存在/run/secrets/secret-name路径会直接从该文件读取Kubernetes/Docker secrets 的标准挂载位置文件名采用小写加连字符的替代格式如sources--facebook-ads--access-token详见 docs/website/docs/general-usage/credentials/setup.md 中的说明。对于本地开发也可以借助python-dotenv从.env文件自动加载这些变量让凭据管理更便捷安全。生产环境从 Google Cloud Secret Manager 读取凭据当凭据需要集中托管、轮换与审计时dlt 支持直接从 Google Cloud Secret Manager 读取。启用此功能前需要为服务账号授予以下权限roles/secretmanager.secretAccessor读取指定 secret必需roles/secretmanager.secretViewer列出可用 secret可选但强烈推荐配合list_secrets使用。启用 Google Secrets Provider在secrets.toml或环境变量中配置[providers] enable_google_secretstrue [providers.google_secrets] only_secretsfalse only_toml_fragmentsfalse list_secretstrue [providers.google_secrets.credentials] project_id project_id private_key -----BEGIN PRIVATE KEY-----\n....\n-----END PRIVATE KEY-----\n client_email ....gserviceaccount.com[providers.google_secrets.credentials]一段可以省略——如果运行环境本身已具备具备相应权限的默认 Google 凭据如 Colab、GCE 实例dlt 会自动使用。对应环境变量写法见 docs/website/docs/general-usage/credentials/vaults.md。优先使用 TOML 片段fragment而非单值dlt 强烈建议开启list_secrets预先列出可用密钥名避免对不存在的 key 发起后端调用同时建议按 TOML 片段存储配置而非单值以减少对后端的调用次数——Vault Provider 能够抓取这些片段并在内存中即时合并为完整配置。例如定义destinationsecret 存放各目标凭据[destination] postgres.credentialspostgresql://loader:***host:5432/postgres [destination.bigquery.credentials] project_id project_id private_key -----BEGIN PRIVATE KEY-----\n....\n-----END PRIVATE KEY-----\n client_email ....gserviceaccount.com或destination-filesystem只存放文件系统凭据[destination.filesystem] bucket_urls3://bucket/path [destination.filesystem.credentials] # s3 (same as athena) region_nameeu-central-1 aws_access_key_id... aws_secret_access_key...source 同理例如sources-mongodb存放 MongoDB 凭据[sources.mongodb] connection_urlmongodbsrv://temp_writer:***/dlt_data?authSourceadminreplicaSetdb-mongodbtlstrue单值存储方式当然也可以像环境变量一样逐个存储单值此时 Google Vault 的行为与环境变量 Provider 类似secret 命名采用连字符分隔 sectionsources-pipedrive-pipedrive_api_key destination-bigquery-credentials-project_id destination-bigquery-credentials-private_key destination-bigquery-credentials-client_email destination-bigquery-location但这种方式显然会对 Secrets 后端发起多次调用一个配置项可能探测多个位置成本更高因此不推荐作为默认方案。:::warning Vault Provider 会在内部缓存所有检索到的 key进程存活期间不会重新抓取直到进程重启。这既减少了后端调用后端调用是付费的也意味着运行时无法感知密钥变更。 :::无 list 权限时的最小化配置如果服务账号没有secretViewer权限可用以下设置跳过列操作同时仍把后端调用次数降到最低[providers.google_secrets] only_secretstrue only_toml_fragmentstrue list_secretsfalse此时 Vault 只抓取 secret 值凭据、dlt.secrets.value标记的参数以及上文所述的 TOML 片段不再抓取单值。:::warning dlt 会为单个值探测多个位置因此如果你关闭only_toml_fragments可能对 Secrets 后端产生大量调用。 :::源码级原理VaultDocProvider 与 GoogleSecretsProvider从源码结构可以清晰地印证上述行为dlt/common/configuration/providers/vault.py 中的VaultDocProvider是所有 Vault 型 Provider 的抽象基类负责把 vault 中的密钥重构为一份类似secrets.toml的内存文档作为缓存。它的_load_fragments方法按短路径优先、长路径覆盖的顺序探测dlt_secrets_toml、sources、sources.name、destination、destination.name全局与 pipeline 作用域两种_update_from_vault实现了list_secrets预列与_vault_lookups调用缓存对应上文进程重启前不再抓取的警告。dlt/common/configuration/providers/google_secrets.py 中的GoogleSecretsProvider实现了_look_vault读取projects/{project_id}/secrets/{key}/versions/latest并对 404/403/400 分别降级处理与_list_vault分页列出所有 secret 名供list_secretstrue时预加载密钥名通过normalize_key去掉标点保留-和_并以连字符连接各 section。同时secret 值支持 TOML、YAML 或 JSON 三种格式dlt 会自动识别这对 AWS Secrets Manager 控制台创建的键值型 secret 尤其友好。扩展其他 Vault 类型子类化 VaultDocProviderdlt 目前内置了 Google Cloud Secret Manager、AWS Secrets Manager 与 Airflow Variables 三类 Vault ProviderAWS 与 Airflow 的详细配置见 docs/website/docs/general-usage/credentials/vaults.md。如果需要接入其他密钥服务如 Azure Key Vault可以子类化VaultDocProvider实现_look_vault(full_key, hint)方法按full_key从外部 Vault 返回 secret 值可选实现_list_vault()方法返回可用 key 集合以配合list_secrets优化将子类注册为自定义 Provider具体步骤参考 docs/website/docs/examples/custom_config_provider 示例。VaultDocProvider已把重构 TOML 文档、fragment 合并、缓存、预列密钥等重活全部封装好你只需要实现两个方法即可这是仓库源码中对贡献者的明确指引见 dlt/common/configuration/providers/vault.py 的类注释。将凭据加入部署环境dlt deploy 与代码注入要把凭据带到生产部署中官方提供两条路径详见 docs/website/docs/walkthroughs/deploy-a-pipeline/使用dlt deploy系列命令dlt deploy命令实现位于 dlt/_workspace/cli/_deploy_command.py由 CLI 自动生成部署配置并引导填入凭据或者在代码中直接传递凭据见 docs/website/docs/general-usage/credentials/advanced.md 中的代码注入方式或通过环境变量注入见 docs/website/docs/general-usage/credentials/setup.md#environment-variables。在代码中设置凭据时可以借助dlt.config与dlt.secrets两个全局字典import os import dlt # 非敏感配置 dlt.config[destination.filesystem.bucket_url] s3://[your_bucket_name] # 敏感凭据优先复用已有环境变量避免硬编码 os.environ[SOURCES__NOTION__API_KEY] os.environ.get(NOTION_KEY, ) dlt.secrets[sources.credentials.client_email] os.environ.get(SHEETS_CLIENT_EMAIL, )故障排查ConfigFieldMissingException当 dlt 找不到必需的配置值或密钥时会抛出ConfigFieldMissingException其异常信息会完整列出它依次尝试过的所有 key 与位置。例如缺少 Postgres 密码时dlt.common.configuration.exceptions.ConfigFieldMissingException: Following fields are missing: [password] in configuration with spec PostgresCredentials for field password config providers and keys were tried in the following order: In Environment Variables key CHESS_GAMES__DESTINATION__POSTGRES__CREDENTIALS__PASSWORD was not found. In Environment Variables key CHESS_GAMES__DESTINATION__CREDENTIALS__PASSWORD was not found. In Environment Variables key CHESS_GAMES__CREDENTIALS__PASSWORD was not found. In secrets.toml key chess_games.destination.postgres.credentials.password was not found. In Environment Variables key DESTINATION__POSTGRES__CREDENTIALS__PASSWORD was not found. In secrets.toml key destination.postgres.credentials.password was not found. In secrets.toml key credentials.password was not found.这条报错至少透露四个信息缺的是哪个字段、按优先级尝试了哪些 key 和位置、先带 pipeline 名前缀再不带的搜索顺序、环境变量优先于secrets.toml的 Provider 顺序。注意config.toml不会被查询——因为它不适用于存放密钥。对照这个顺序排查你的secrets.toml与环境变量拼写通常能快速定位问题。小结凭据管理是数据管线从本地跑通到生产落地的关键一环。dlt 通过配置 Provider抽象让同一份配置逻辑同时支持secrets.toml、环境变量与云密钥托管服务三种形态本地开发用.dlt/secrets.toml按推荐 section 布局组织部署环境把同名 key 转成大写 双下划线格式写入环境变量生产环境则通过 Google Cloud Secret Manager 等 Vault 托管并借助 TOML 片段、list_secrets预列与进程内缓存将后端调用成本降到最低。掌握这套映射关系与底层 Provider 机制即可在任意运行环境中安全、一致地注入凭据。【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 dlt 凭据配置实战指南：secrets.toml、环境变量与 Google Cloud Secret Manager
dlt 凭据配置实战指南secrets.toml、环境变量与 Google Cloud Secret Manager【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dltdltdata load tool作为开源 Python 数据加载库其核心设计之一就是将凭据credentials与业务代码彻底分离你不需要在脚本里硬编码 API Key 或私钥而是通过.dlt/secrets.toml、环境变量或云密钥托管服务Vault集中管理。本文以 docs/website/docs/walkthroughs/add_credentials.md 为主线完整覆盖本地开发与生产部署两种场景下的凭据注入方式并结合仓库源码配置 Provider 实现说明底层工作机理。读完本文你将掌握如何编写secrets.toml、如何把配置映射为环境变量命名、如何从 Google Cloud Secret Manager 拉取凭据并优化调用成本以及如何扩展自定义 Vault Provider。凭据管理的核心机制配置 Provider 与查询顺序在深入具体写法之前先理解 dlt 的配置体系。dlt 通过**配置提供者Config Provider**从不同位置读取配置与密钥运行管线时按以下顺序依次查询一旦在某处命中即停止不再查询优先级更低的提供者环境变量优先最高常用于部署环境secrets.toml与config.toml文件本地开发主力前者存放敏感信息后者存放非敏感配置Vault密钥托管服务如 Google Cloud Secret Manager、AWS Secrets Manager、Airflow Variables自定义 Provider通过register_provider注册的自定义实现函数签名默认值兜底。以上顺序与查询细节见 docs/website/docs/general-usage/credentials/setup.md。这套机制的实现位于 dlt/common/configuration/providers 目录environ.py负责环境变量toml.py负责 TOML 文件vault.py与google_secrets.py负责密钥托管服务它们统一继承自ConfigProvider基类。正是因为有了这套 Provider 抽象同一个api_key参数既可以从secrets.toml注入也可以从环境变量注入代码无需任何改动。本地开发使用 .dlt/secrets.toml在本地运行管线时官方推荐使用.dlt/secrets.toml方式。打开你的 dlt secrets 文件将 section 名和键名与脚本中 source/destination 的参数名一一对应即可。完整示例Pipedrive 源 BigQuery 目标假设你的脚本使用 Pipedrive source 和 BigQuery destinationsecrets.toml应写成[sources.pipedrive] pipedrive_api_key pipedrive_api_key # please set me up! [destination.bigquery] location US [destination.bigquery.credentials] project_id project_id # please set me up! private_key private_key # please set me up! client_email client_email # please set me up!:::note TOML 文件中的键是大小写敏感的section 之间用点号.分隔。 :::secrets.toml 与 config.toml 的分工.dlt目录下实际上有两个文件详见 docs/website/docs/general-usage/credentials/setup.mdconfig.toml存放非敏感配置如bucket_url、数据库主机、超时、日志级别等可安全提交到版本控制secrets.toml存放敏感信息如密码、API Key、私钥绝不能提交到版本控制项目.gitignore默认已排除。两个文件均从当前工作目录下的.dlt文件夹加载。也就是说若你在my_dlt_project目录执行python pipelines/google_sheets.pydlt 会读取my_dlt_project/.dlt/secrets.toml而不是脚本所在目录的.dlt。此外dlt 还会检查~/.dlt/家目录下的全局配置项目配置优先并支持 Google Colab 与 Streamlit 的 secrets 特殊位置相关实现见 dlt/common/configuration/providers/toml.pySettingsTomlProvider。推荐的 section 布局当项目中有多个 source 或 destination 时建议使用以下推荐布局也是dlt init自动生成的布局用sources和destination作为顶级 section 分别隔离源与目标配置用 source 函数所在Python 模块名来区分配置如[sources.notion]对应notion.py中定义的 source用 destination类型名来区分目标如[destination.postgres.credentials]。# source 定义在 notion.py 中 [sources.notion] api_key some_value # 使用 postgres destination [destination.postgres.credentials] user dlthub password some_valuedlt 在查找某个值时会从最完整的路径开始逐级去掉最右侧的 section 重试。例如notion.py中定义了dlt.source def notion_databases(api_key: str dlt.secrets.value)它会依次尝试sources.notion.notion_databases.api_keysources.notion.api_keysources.api_keyapi_key对 destination 凭据credentials视为必需分组不会被消除顺序为destination.postgres.credentials.password→destination.credentials.password→credentials.password。这意味着你可以只写一个顶层[credentials]段让 source 和 destination 共享同一套 Google 凭据如同时用于 Google Sheets 源和 BigQuery 目标。获取具体 source/destination 的凭据不同目标类型与 Verified Source 的凭据格式差异较大目标destination凭据的创建与配置方式参见各目标类型的文档页docs/website/docs/dlt-ecosystem/destinationsVerified Source 凭据的获取方式参见各源的 Setup 指南docs/website/docs/dlt-ecosystem/verified-sources。拿到凭据后填入上文件并保存即可。更系统的配置组织方式可参考 docs/website/docs/general-usage/credentials/ 下的进阶文档。部署环境通过环境变量注入凭据在部署到服务器、容器或调度平台时环境变量是最常见的方式。dlt 完整支持从环境读取凭据且命名约定与 TOML 不同所有名称大写section 之间用**双下划线__**分隔。仍以上述 Pipedrive BigQuery 的secrets.toml为例等价的环境变量为SOURCES__PIPEDRIVE__PIPEDRIVE_API_KEY DESTINATION__BIGQUERY__CREDENTIALS__PROJECT_ID DESTINATION__BIGQUERY__CREDENTIALS__PRIVATE_KEY DESTINATION__BIGQUERY__CREDENTIALS__CLIENT_EMAIL DESTINATION__BIGQUERY__LOCATION环境变量还支持传递字典和列表但必须写成Python 字面量而非 JSON例如export DESTINATION__DUCKDB__CREDENTIALS__PRAGMAS[\enable_logging\]从源码看环境变量的键名拼接逻辑在 dlt/common/configuration/providers/environ.py 的EnvironProvider.get_key_name中实现get_key_name(key, __, *sections).upper()即用__连接各 section 后统一转大写。该 Provider 还有一个实用特性对标记为 secret 的值若存在/run/secrets/secret-name路径会直接从该文件读取Kubernetes/Docker secrets 的标准挂载位置文件名采用小写加连字符的替代格式如sources--facebook-ads--access-token详见 docs/website/docs/general-usage/credentials/setup.md 中的说明。对于本地开发也可以借助python-dotenv从.env文件自动加载这些变量让凭据管理更便捷安全。生产环境从 Google Cloud Secret Manager 读取凭据当凭据需要集中托管、轮换与审计时dlt 支持直接从 Google Cloud Secret Manager 读取。启用此功能前需要为服务账号授予以下权限roles/secretmanager.secretAccessor读取指定 secret必需roles/secretmanager.secretViewer列出可用 secret可选但强烈推荐配合list_secrets使用。启用 Google Secrets Provider在secrets.toml或环境变量中配置[providers] enable_google_secretstrue [providers.google_secrets] only_secretsfalse only_toml_fragmentsfalse list_secretstrue [providers.google_secrets.credentials] project_id project_id private_key -----BEGIN PRIVATE KEY-----\n....\n-----END PRIVATE KEY-----\n client_email ....gserviceaccount.com[providers.google_secrets.credentials]一段可以省略——如果运行环境本身已具备具备相应权限的默认 Google 凭据如 Colab、GCE 实例dlt 会自动使用。对应环境变量写法见 docs/website/docs/general-usage/credentials/vaults.md。优先使用 TOML 片段fragment而非单值dlt 强烈建议开启list_secrets预先列出可用密钥名避免对不存在的 key 发起后端调用同时建议按 TOML 片段存储配置而非单值以减少对后端的调用次数——Vault Provider 能够抓取这些片段并在内存中即时合并为完整配置。例如定义destinationsecret 存放各目标凭据[destination] postgres.credentialspostgresql://loader:***host:5432/postgres [destination.bigquery.credentials] project_id project_id private_key -----BEGIN PRIVATE KEY-----\n....\n-----END PRIVATE KEY-----\n client_email ....gserviceaccount.com或destination-filesystem只存放文件系统凭据[destination.filesystem] bucket_urls3://bucket/path [destination.filesystem.credentials] # s3 (same as athena) region_nameeu-central-1 aws_access_key_id... aws_secret_access_key...source 同理例如sources-mongodb存放 MongoDB 凭据[sources.mongodb] connection_urlmongodbsrv://temp_writer:***/dlt_data?authSourceadminreplicaSetdb-mongodbtlstrue单值存储方式当然也可以像环境变量一样逐个存储单值此时 Google Vault 的行为与环境变量 Provider 类似secret 命名采用连字符分隔 sectionsources-pipedrive-pipedrive_api_key destination-bigquery-credentials-project_id destination-bigquery-credentials-private_key destination-bigquery-credentials-client_email destination-bigquery-location但这种方式显然会对 Secrets 后端发起多次调用一个配置项可能探测多个位置成本更高因此不推荐作为默认方案。:::warning Vault Provider 会在内部缓存所有检索到的 key进程存活期间不会重新抓取直到进程重启。这既减少了后端调用后端调用是付费的也意味着运行时无法感知密钥变更。 :::无 list 权限时的最小化配置如果服务账号没有secretViewer权限可用以下设置跳过列操作同时仍把后端调用次数降到最低[providers.google_secrets] only_secretstrue only_toml_fragmentstrue list_secretsfalse此时 Vault 只抓取 secret 值凭据、dlt.secrets.value标记的参数以及上文所述的 TOML 片段不再抓取单值。:::warning dlt 会为单个值探测多个位置因此如果你关闭only_toml_fragments可能对 Secrets 后端产生大量调用。 :::源码级原理VaultDocProvider 与 GoogleSecretsProvider从源码结构可以清晰地印证上述行为dlt/common/configuration/providers/vault.py 中的VaultDocProvider是所有 Vault 型 Provider 的抽象基类负责把 vault 中的密钥重构为一份类似secrets.toml的内存文档作为缓存。它的_load_fragments方法按短路径优先、长路径覆盖的顺序探测dlt_secrets_toml、sources、sources.name、destination、destination.name全局与 pipeline 作用域两种_update_from_vault实现了list_secrets预列与_vault_lookups调用缓存对应上文进程重启前不再抓取的警告。dlt/common/configuration/providers/google_secrets.py 中的GoogleSecretsProvider实现了_look_vault读取projects/{project_id}/secrets/{key}/versions/latest并对 404/403/400 分别降级处理与_list_vault分页列出所有 secret 名供list_secretstrue时预加载密钥名通过normalize_key去掉标点保留-和_并以连字符连接各 section。同时secret 值支持 TOML、YAML 或 JSON 三种格式dlt 会自动识别这对 AWS Secrets Manager 控制台创建的键值型 secret 尤其友好。扩展其他 Vault 类型子类化 VaultDocProviderdlt 目前内置了 Google Cloud Secret Manager、AWS Secrets Manager 与 Airflow Variables 三类 Vault ProviderAWS 与 Airflow 的详细配置见 docs/website/docs/general-usage/credentials/vaults.md。如果需要接入其他密钥服务如 Azure Key Vault可以子类化VaultDocProvider实现_look_vault(full_key, hint)方法按full_key从外部 Vault 返回 secret 值可选实现_list_vault()方法返回可用 key 集合以配合list_secrets优化将子类注册为自定义 Provider具体步骤参考 docs/website/docs/examples/custom_config_provider 示例。VaultDocProvider已把重构 TOML 文档、fragment 合并、缓存、预列密钥等重活全部封装好你只需要实现两个方法即可这是仓库源码中对贡献者的明确指引见 dlt/common/configuration/providers/vault.py 的类注释。将凭据加入部署环境dlt deploy 与代码注入要把凭据带到生产部署中官方提供两条路径详见 docs/website/docs/walkthroughs/deploy-a-pipeline/使用dlt deploy系列命令dlt deploy命令实现位于 dlt/_workspace/cli/_deploy_command.py由 CLI 自动生成部署配置并引导填入凭据或者在代码中直接传递凭据见 docs/website/docs/general-usage/credentials/advanced.md 中的代码注入方式或通过环境变量注入见 docs/website/docs/general-usage/credentials/setup.md#environment-variables。在代码中设置凭据时可以借助dlt.config与dlt.secrets两个全局字典import os import dlt # 非敏感配置 dlt.config[destination.filesystem.bucket_url] s3://[your_bucket_name] # 敏感凭据优先复用已有环境变量避免硬编码 os.environ[SOURCES__NOTION__API_KEY] os.environ.get(NOTION_KEY, ) dlt.secrets[sources.credentials.client_email] os.environ.get(SHEETS_CLIENT_EMAIL, )故障排查ConfigFieldMissingException当 dlt 找不到必需的配置值或密钥时会抛出ConfigFieldMissingException其异常信息会完整列出它依次尝试过的所有 key 与位置。例如缺少 Postgres 密码时dlt.common.configuration.exceptions.ConfigFieldMissingException: Following fields are missing: [password] in configuration with spec PostgresCredentials for field password config providers and keys were tried in the following order: In Environment Variables key CHESS_GAMES__DESTINATION__POSTGRES__CREDENTIALS__PASSWORD was not found. In Environment Variables key CHESS_GAMES__DESTINATION__CREDENTIALS__PASSWORD was not found. In Environment Variables key CHESS_GAMES__CREDENTIALS__PASSWORD was not found. In secrets.toml key chess_games.destination.postgres.credentials.password was not found. In Environment Variables key DESTINATION__POSTGRES__CREDENTIALS__PASSWORD was not found. In secrets.toml key destination.postgres.credentials.password was not found. In secrets.toml key credentials.password was not found.这条报错至少透露四个信息缺的是哪个字段、按优先级尝试了哪些 key 和位置、先带 pipeline 名前缀再不带的搜索顺序、环境变量优先于secrets.toml的 Provider 顺序。注意config.toml不会被查询——因为它不适用于存放密钥。对照这个顺序排查你的secrets.toml与环境变量拼写通常能快速定位问题。小结凭据管理是数据管线从本地跑通到生产落地的关键一环。dlt 通过配置 Provider抽象让同一份配置逻辑同时支持secrets.toml、环境变量与云密钥托管服务三种形态本地开发用.dlt/secrets.toml按推荐 section 布局组织部署环境把同名 key 转成大写 双下划线格式写入环境变量生产环境则通过 Google Cloud Secret Manager 等 Vault 托管并借助 TOML 片段、list_secrets预列与进程内缓存将后端调用成本降到最低。掌握这套映射关系与底层 Provider 机制即可在任意运行环境中安全、一致地注入凭据。【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考