企业官网建设流程全解析

使用 Google Cloud Run Jobs 部署 dlt 数据管道：完整实战指南

【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy 🛠️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt

dlt（data load tool）是开源的 Python 数据加载库。本文将讲解如何把基于 dlt 的数据管道以Google Cloud Run Jobs的形式部署到云端：从dlt init初始化管道代码、创建 Procfile 定义启动命令，到用gcloud run jobs deploy发布、配置环境变量（含 Secret Manager 集成）以及手动触发与定时调度。读完本文，你将掌握一套完整的"本地开发 → 云端托管 → 密钥管理 → 定时运行"的 dlt 管道部署方案。

本文面向已具备一定 GCP 基础知识的开发者，涉及 Cloud Run Jobs、IAM 权限与 GCP Service Account 等概念。仓库内的实现代码位于 dlt/_workspace 目录，部署相关模板可在 deploy/dlt 目录下查看。

1. 准备工作：初始化 dlt 管道

1.1 选择数据源与目标库

本指南以 dlt 的Notion verified source为例进行部署，其详细说明见 Notion 官方 verified source 文档。你也可以替换为任意其他 verified source（如 github.md、stripe.md），或者使用自定义 source。

执行以下命令初始化 Notion verified source，并以BigQuery作为目标目的地：

dlt init notion bigquery

命令执行完毕后，会在当前主目录生成管道运行所需的文件与配置目录，包括：

• notion_pipeline.py—— 管道示例脚本（Notion 数据源 + BigQuery 目标）
• requirements.txt—— Python 依赖清单
• .dlt/config.toml—— 非敏感配置
• .dlt/secrets.toml—— 敏感凭据（切勿提交到代码仓库）

从源码看，dlt init的实际工作由 dlt/_workspace/cli/_init_command.py 中的初始化逻辑完成：它会校验 source 名称（必须是合法的 Python 标识符，仅允许小写字母、数字与下划线），探测 source 类型（template/core/verified），创建.dlt配置目录，并根据目标目的地（此处为 BigQuery）生成对应的 pipeline 脚本与依赖声明。依赖既可能写入requirements.txt，也可能写入pyproject.toml，取决于初始化时指定的依赖系统。

初始化生成的 pipeline 脚本结构可参考仓库中的模板，例如 rest_api_pipeline.py：

def load_github() -> None: pipeline = dlt.pipeline( pipeline_name="rest_api_github", destination="duckdb", dataset_name="rest_api_data", ) load_info = pipeline.run(github_source()) print(load_info)

即：创建一个dlt.pipeline实例（指定管道名、目的地、数据集名），调用pipeline.run(source)执行加载。

1.2 创建 Procfile 指定启动命令

在管道主目录下新建名为Procfile的文件，内容如下：

web: python3 notion_pipeline.py

该文件指示 Cloud Run Job 使用python3解释器运行notion_pipeline.py。Procfile 是部署的关键入口：Cloud Run Jobs 启动容器后会按照其中定义的进程命令执行管道逻辑。

1.3 补充依赖

dlt init生成的requirements.txt已包含 dlt 核心依赖与源/目的地相关依赖。若管道需要额外依赖（例如自定义处理逻辑引用的第三方库），请直接追加到requirements.txt中，Cloud Run 构建容器时会基于该文件安装依赖。

提示：部署前请先本地验证管道可运行。可参考 Notion 文档 中的步骤：pip install -r requirements.txt安装依赖，然后运行python notion_pipeline.py，最后用dlt pipeline notion show检查加载结果。

2. 使用 gcloud 部署 Cloud Run Jobs

在终端中进入包含notion_pipeline.py的目录，执行以下命令：

gcloud run jobs deploy notion-pipeline-job \ --source . \ --tasks 1 \ --max-retries 5 \ --cpu 4 \ --memory 4Gi \ --region us-central1 \ --project dlthub-sandbox

参数说明：

关于任务超时：Cloud Run Jobs 默认任务超时为 10 分钟，可通过配置提升至最多 1440 分钟（24 小时）。数据量较大或源 API 响应缓慢的管道建议调大超时上限，避免任务被强制终止。

关于服务账号权限：每个 GCP 项目都有关联的默认服务账号（通常形如<project-id>@<project-id>.iam.gserviceaccount.com）。部署后需为该项目默认服务账号授予roles/run.invoker角色，Cloud Run Job 才能被触发执行（包括手动触发与后续的定时触发）。

若管道目标为 BigQuery，还需确认该服务账号具备 BigQuery 数据写入权限（如roles/bigquery.dataEditor与roles/bigquery.jobUser），否则任务运行时会因凭据不足而失败。

3. 在 Cloud Run 中配置环境变量

重要安全原则：切勿将密钥直接写入secrets.toml后随代码一起部署。secrets.toml会被打进容器镜像，任何能拉取该镜像的人都能读取到你的密钥。正确做法是使用环境变量或Google Secret Manager，二者均可避免敏感信息进入镜像层。

Cloud Run 提供了两种注入方式，下面分别说明。

3a. 直接在 Job 配置中添加变量

1. 进入 Google Cloud Console，打开已部署的 Cloud Run Job，点击"VIEW AND EDIT JOB CONFIGURATION"（查看并编辑任务配置）。
2. 在"CONTAINERS" > "VARIABLE AND SECRETS"（容器 > 变量与密钥）下点击"ADD VARIABLE"（添加变量）。
3. 按管道所需参数填写变量名。若该变量在secrets.toml中以下划线分隔的小写形式声明，则必须将变量名大写并将点替换为双下划线。例如secrets.toml中的sources.notion.api_key，环境变量名应为SOURCES__NOTION__API_KEY。
4. 填入对应的值（如 Notion API Key）。
5. 点击"Done"并更新任务配置。

这一映射规则源于 dlt 的环境变量解析机制：dlt 的环境变量提供方（EnvironProvider，实现见 dlt/common/configuration/providers/environ.py）会把"配置段 + 键名"拼接后统一转为大写，并以__作为层级分隔符。例如密钥路径sources.notion.api_key会被规范化为环境变量SOURCES__NOTION__API_KEY。通用规则如下：

dlt 解析配置时按优先级依次查找环境变量、config.toml、secrets.toml与默认值，环境变量优先级最高，因此云上部署可通过环境变量直接覆盖本地配置文件中的值。

3b. 使用 GCP Secret Manager

1. 在 GCP 中提前创建 Secret（例如名为notion_secret，值为 Notion API Key）。
2. 进入 Cloud Run Job，点击"VIEW AND EDIT JOB CONFIGURATION"。
3. 在"Containers" > "VARIABLE AND SECRETS" > "ADD VARIABLE"下点击"Add a secret reference"（添加密钥引用），选择已创建的 Secret（如notion_secret）。
4. 将"REFERENCE A SECRET"设置为以环境变量方式挂载（mounted as an environment variable）。
5. 在"Environment Variable"字段填写与管道参数对应的环境变量名。同样遵循大写 + 双下划线的命名规范：例如管道所需的sources.notion.api_key，声明为SOURCES__NOTION__API_KEY。
6. 选择要引用的 Secret 及版本。
7. 点击"Done"并更新任务配置。
8. 为 Cloud Run 服务账号授予roles/secretmanager.secretAccessor角色（Secret Manager Secret Accessor）。该服务账号通常是创建 Job 时所在 GCP 项目的默认服务账号。缺少此角色时，任务启动阶段读取 Secret 会报权限错误。

使用 Secret Manager 的优势：密钥不进入容器镜像、支持版本管理与轮换，且可在多个 Job 间复用。从 dlt 源码看，环境变量提供方还会尝试从 Kubernetes/Docker 风格的密钥文件路径（/run/secrets/<name>）读取密钥，这说明 dlt 的密钥注入机制与云原生容器生态是兼容的。

4. 监控与触发 Cloud Run Job

4.1 手动触发

在 Cloud Console 打开该 Cloud Run Job，点击"EXECUTE"（执行）即可手动触发一次运行。执行后可在任务运行记录中查看日志与状态，dlt 管道运行时的加载信息也会输出到标准输出，可在 Cloud Logging 中检索。

4.2 定时触发（Scheduled Trigger）

如需定期自动化运行管道，可在 GCP 中创建Cloud Scheduler定时任务，通过 Pub/Sub 或 HTTP 目标调用 Cloud Run Job 的触发端点。调度频率可按管道需求设置（如每天一次、每小时一次）。注意：定时触发同样依赖服务账号的roles/run.invoker权限。

4.3 运行状态确认

管道执行完毕后，可回到本地（或使用 BigQuery 查询）验证数据落库情况：

dlt pipeline notion show

若在 Cloud Run 中执行，更推荐直接查询目标 BigQuery 数据集，确认表结构与行数与预期一致。

5. 完整部署流程回顾

1. 本地初始化：dlt init notion bigquery生成管道脚本、.dlt配置目录与requirements.txt。
2. 编写启动文件：创建Procfile，写入web: python3 notion_pipeline.py；按需补充requirements.txt依赖。
3. 移除本地敏感信息：清理secrets.toml中的真实密钥，改为环境变量或 Secret Manager 注入。
4. 部署：执行gcloud run jobs deploy notion-pipeline-job --source . ...，并授予服务账号roles/run.invoker（以及 Secret 读取、BigQuery 写入等所需角色）。
5. 配置密钥：在 Job 配置中添加环境变量，或引用 Secret Manager 中的 Secret。
6. 触发与监控：手动点击 EXECUTE 或配置 Cloud Scheduler 定时任务，通过 Cloud Logging 与目标库查询确认运行结果。

6. 常见问题与注意事项

• 任务超时被杀：默认 10 分钟超时，大管道请上调至合适值（上限 1440 分钟）。
• 密钥泄露风险：secrets.toml会进入镜像，务必改用环境变量或 Secret Manager。
• 权限不足报错：触发失败检查roles/run.invoker；读取 Secret 失败检查roles/secretmanager.secretAccessor；写 BigQuery 失败检查 BigQuery 相关角色。
• 区域与成本：--cpu、--memory直接影响计费，按管道实际负载配置，避免过度分配。
• 重试语义：--max-retries 5针对任务级失败重试，幂等性好的管道（dlt 支持主键去重与增量加载）可安全开启。

至此，你的 dlt 管道已经运行在 Google Cloud Run 之上，既可以手动触发，也可以按计划自动运行，享受 Google Cloud 全托管的弹性与可靠性。

【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy 🛠️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt