使用 dltHub Platform 将 dlt 管道部署到云端：从本地 DuckDB 到托管 Playground 存储

使用 dltHub Platform 将 dlt 管道部署到云端：从本地 DuckDB 到托管 Playground 存储

【免费下载链接】llm-zoomcampLLM Zoomcamp - a free online course about real-life applications of LLMs. In 10 weeks you will learn how to build an AI system that answers questions about your knowledge base. Register here 👇🏼项目地址: https://gitcode.com/GitHub_Trending/ll/llm-zoomcamp

本地跑通的 dlt 管道只能服务你自己——dlthub local show打开的 marimo 仪表盘读取的是磁盘上的 DuckDB 文件，无法分享给团队。本课解决的核心问题是：如何把 dlt 管道与仪表盘部署到 dltHub Platform 云端，实现定时运行、团队共享，并理解云端"临时存储"与"持久化存储"的区别。读完本文你将掌握dlthubCLI 的登录、部署、运行全流程，能把 destination 从duckdb无缝切换到托管的playgroundS3 lake，并弄清deltalake依赖为何必不可少。

为什么要把管道部署到云端

在 dlt 工作坊的前几课中，你已经完成了两条本地管道与两个仪表盘：

• 文件系统管道：读取~/.claude、~/.codex等本地 JSONL 会话日志，写入 DuckDB（filesystem_pipeline.py）；
• REST API 管道：从托管 API 拉取 100 万条模拟 Claude Code 轨迹（rest_api_pipeline.py）；
• 两个 marimo 报表：claude_logs_dashboard.py与agent_traces_dashboard.py。

这些工作在本地完全没问题，但有一个硬性限制：你无法与团队共享本地仪表盘。dltHub Platform 的价值正在于此——它允许你把管道和仪表盘部署到云端、按计划调度运行，并与同事共享结果。

整体架构可以用一条链路概括：数据源 → dlt 管道 → DuckDB/Playground → marimo 仪表盘 → dltHub Platform。本地阶段数据落在 DuckDB（dlt 直接写到磁盘上的.duckdb文件，无需额外服务），部署阶段数据则落在平台管理的存储中。

登录：将本地工作区连接到 dltHub Platform

部署的第一步是把本地工作区与 dltHub Platform 账号绑定。全部通过uv run dlthub子命令完成：

uv run dlthub login # device-code OAuth in the browser uv run dlthub workspace connect # pick or create a workspace

两条命令的职责分别是：

• dlthub login：在浏览器中走 device-code OAuth 流程完成身份认证；
• dlthub workspace connect：选择或创建一个云端工作区，把本地项目绑定到该工作区上。

连接成功后，可以用下面的命令在平台 UI 中查看当前状态：

uv run dlthub show

值得注意的机制是：每个新账号都自带一个 playground 工作区，本地工作区会自动连接到它。这意味着你本地运行的一切都会自动同步到平台——管道定义、运行记录、数据都能在平台 UI 中看到，这也是后续部署动作的基础。

从脚手架阶段（见 01-overview.md）开始，uvx dlthub-init@latest创建的项目就包含了为云端部署准备的__deployment__.py部署清单文件，它正是本课部署动作的操作对象。

部署管道：让 Agent 代办，或手动执行

方式一：用自然语言让 Agent 部署

连接工作区后，直接在编码 Agent 中下达指令：

deploy this on the dlthub platform, use duckdb as destination

Agent 会自动完成以下动作：

1. 安装 dlthub-platform toolkit——这是 dltHub AI workbench 按需安装的工具包之一（工作坊中出现过的 toolkit 还包括 filesystem、rest-api、data-exploration，每个都是一套引导式工作流）；
2. 走一遍五步部署检查清单，确保管道可部署；
3. 把管道注册到__deployment__.py；
4. 执行部署。

这正是 dltHub AI workbench 的核心工作方式：dlt 领域的知识被封装进 toolkit、skill 与 MCP 工具中，你只需用自然语言描述目标，编码 Agent 负责落地。

方式二：手动命令

你也可以完全手动完成部署，两个命令分别对应"发布新版本"与"在云端运行"：

uv run dlthub deploy # ship the current project as a new version uv run dlthub run # run the pipeline on the cloud

• dlthub deploy：把当前整个项目作为新版本推送到平台；
• dlthub run：在云端执行管道。

这里有一个关键的实践要点：每次代码变更后都要重复 deploy-and-run 循环，确保云端始终运行的是你最新的版本。部署平台不感知你的本地改动，只有显式deploy才会把新代码推上去。

临时存储：为什么 DuckDB 的数据不持久

如果你按照上面的方式以duckdb作为 destination 部署，会立即遇到一个现象：管道在云端运行成功，但数据不会跨运行保留。

原因在于平台以容器方式运行管道：

• 管道在容器中执行；
• 容器内的本地文件（包括 DuckDB 的.duckdb文件）是临时存储（ephemeral storage）；
• 作业结束后，容器内的文件被清理。

因此以duckdb为 destination 的部署，每次运行都是"从零开始、用完即焚"。这对开发调试没问题，但对任何需要持续积累数据的真实场景都不可接受——数据必须在运行之间存活。

切换到 Playground destination：获得持久化存储

要解决数据持久化问题，需要把 destination 从duckdb切换为playground。playground 是平台托管的 S3 lake，数据能够跨运行保留，这正是"命名 destination"（named destination）机制的体现——playground在开发场景下等价于 duckdb，在生产场景下则指向 S3 lake，管道代码路径完全一致，只改一个字符串。

在rest_api_pipeline.py中修改 destination：

# was: # destination="duckdb" # now: destination="playground"

如果你对照 rest_api_pipeline.py 的源码，会看到这个值出现在load()函数里创建管道的地方：

pipeline = dlt.pipeline( pipeline_name="agent_traces", destination="duckdb", # 部署时改为 "playground" dataset_name="traces", # persistent dataset (distinct from catalog name) )

从源码结构可以推断，destination是dlt.pipeline()的显式参数，改字符串即可切换目标存储；其余部分——source 定义、REST API 配置、运行逻辑——全部保持不变。这就是 dlt"同一份管道代码写遍所有 destination"设计的最直接体现。

deltalake：Playground 的隐藏依赖

切换 destination 之后还有一个坑：playground destination 依赖deltalake包。S3 lake 上的数据以 Delta Lake 格式落盘，因此需要该 Python 包支持读写。

修改后重新部署并运行：

uv run dlthub deploy uv run dlthub run

如果这次运行因为deltalake缺失而失败，deploy 步骤会自动把依赖补进pyproject.toml——这是平台部署流程的便利之处：依赖解析失败时，它会尝试修复清单文件。你只需要再次 deploy 并 run 即可。

部署后的验证与后续动作

管道部署成功且写入 playground 后，你可以继续在 06-dashboard-deploy.md 中完成仪表盘的部署与调度：把 marimo 仪表盘模块注册进__deployment__.py、将dlt.attach()指向 playground destination、通过uv run dlthub job publish agent_traces_dashboard发布共享链接，并用trigger.schedule("0 12 * * *")这类 cron 触发器让管道定时运行——uv run dlthub job list可以确认调度是否生效。

不过在此之前，请确认你已经理解本课的两个核心判断标准：

1. 数据是否持久：部署后看 playground 中的数据是否跨运行保留，而不是每次 run 都被清空；
2. 依赖是否齐备：deltalake是否已出现在pyproject.toml中，deploy是否完成了自动修复。

只有这两点都满足，你的管道才真正从"本地玩具"升级为"云端服务"。

小结

本课把管道从本地搬上了 dltHub Platform，关键点可以浓缩为四步：

同时记住两个容易踩坑的事实：以duckdb部署的数据是临时存储，作业结束即被清理；切换playground后必须保证deltalake依赖可用，否则运行会失败——好在deploy会自动修复pyproject.toml。每次代码变更后都重复 deploy-and-run 循环，云端就会始终与你最新的本地版本保持一致。

相关课程：REST API 管道 · 仪表盘部署与调度

【免费下载链接】llm-zoomcampLLM Zoomcamp - a free online course about real-life applications of LLMs. In 10 weeks you will learn how to build an AI system that answers questions about your knowledge base. Register here 👇🏼项目地址: https://gitcode.com/GitHub_Trending/ll/llm-zoomcamp