Lightdash 实战：用 Docker Compose 一键构建并填充本地 Jaffle Shop 数据库（Postgres + dbt）

Lightdash 实战：用 Docker Compose 一键构建并填充本地 Jaffle Shop 数据库（Postgres + dbt）

【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash

Lightdash 仓库内置了一套完整的 Jaffle Shop 演示工程，其中 dbt/docker 目录 提供了一组开箱即用的 Docker Compose 配置与脚本：一条命令即可在本地拉起 Postgres 数据库，并自动运行 dbt 将 Jaffle Shop 的原始 CSV 数据构建为可分析的表。本文完整讲解这套「容器化建库 + 数据填充」流程的每一步操作，并结合仓库中的docker-compose.yml、entrypoint.sh、profiles.yml等真实文件深入剖析其工作原理，读完你可以独立完成本地演示库的搭建、数据验证，并把 Postgres 连接到 Lightdash 或其他任意 BI 工具。

整体工作方式：两个服务构成的数据管道

该目录的定位是：在本地快速启动一个包含全部 Jaffle Shop 数据的数据库，方便测试 Lightdash 功能，或直接玩弄这份演示数据。从 docker-compose.yml 可以看到，整个管道由两个协作服务组成：

1. postgres：数据库本身，你可以用任何 SQL 工具连上来查询数据；
2. dbt：运行 dbt-core 的容器服务，负责把 Jaffle Shop 这个 dbt 项目「转化」为 Postgres 中的可用数据（建表、灌数、跑模型）。

两个服务的依赖与数据流如下：

• dbt服务通过depends_on: [postgres]声明启动顺序依赖，确保 Postgres 先就绪；
• dbt服务把仓库目录挂载进容器（'..:/usr/app'），并在容器内执行自定义 entrypoint.sh 完成建数；
• postgres服务把5432端口映射到宿主机，设置restart: always保证数据库持久运行。

# examples/full-jaffle-shop-demo/dbt/docker/docker-compose.yml（原文） services: dbt: image: fishtownanalytics/dbt:0.21.0 depends_on: - postgres volumes: - '..:/usr/app' entrypoint: /usr/app/docker/entrypoint.sh postgres: image: postgres restart: always environment: POSTGRES_PASSWORD: password ports: - '5432:5432'

几个值得注意的配置细节：

• dbt 镜像版本：固定为fishtownanalytics/dbt:0.21.0。dbt 0.21 时代dbt seed/dbt run尚不支持--project-dir参数，所以 entrypoint 采用「以挂载的仓库根目录为工作目录 +--profiles-dir ./docker」的方式运行（见下文源码解析）；
• 卷挂载..:/usr/app：..指向dbt/工程根目录（包含dbt_project.yml、models/、data/、docker/等），挂载后 dbt 容器内可直接读到完整工程；
• Postgres 密码：通过POSTGRES_PASSWORD: password环境变量注入，即后文连接信息中password: password的由来；
• 官方postgres镜像：未固定 tag，实际拉取时以 Docker Hub 上该镜像的默认（latest）版本为准。

Step 1. 获取代码

根据你是否要修改 Jaffle Shop 的数据模型，选择对应方式：

选项 1：只体验、不改模型

直接克隆官方 Jaffle Shop 仓库（文档原文指向[e-mail]:lightdash/jaffle_shop，即 Lightdash 维护的 jaffle_shop 仓库）：

git clone [e-mail]:lightdash/jaffle_shop cd jaffle_shop/docker

选项 2：要改数据模型

在 GitHub 页面上点击fork按钮创建自己的 Fork，然后克隆你自己的仓库（把your_profile_name替换为你的用户名）：

git clone [e-mail]:your_profile_name/jaffle_shop cd jaffle_shop/docker

本仓库内的等价路径：如果你已经拿到了 Lightdash 仓库本身，无需另行克隆。演示工程完整内置于 examples/full-jaffle-shop-demo/dbt，直接cd到examples/full-jaffle-shop-demo/dbt/docker即可执行后续所有步骤。该目录与官方 jaffle_shop 仓库的docker/目录结构一致（start.sh、stop.sh、connect.sh、entrypoint.sh、profiles.yml、docker-compose.yml、README.md齐全），且模型覆盖面更广——除了经典 customers/orders/payments，本仓库版本还内置了订阅、营销活动、漏斗、地图、医疗等多个主题模型（见 dbt_project.yml 中按group_label分组的 model 配置）。

Step 2. 安装 Docker

本流程依赖 Docker 与 Docker Compose 命令（脚本中直接调用docker compose），需要先在机器上安装 Docker，并确保docker compose子命令可用。

Step 3. 一条命令建库并灌入 Jaffle 数据

在docker/目录下执行：

./start.sh

启动脚本 的全部内容就一行：

docker compose up -d -V

参数含义：

• -d：后台（detached）模式启动，不占用终端；
• -V：同时创建并启动命名卷（本 compose 文件未显式定义 volume，此参数主要保证任何声明的卷都被初始化）。

执行后发生的事：

1. Compose 先拉起postgres容器（restart: always，数据库常驻）；
2. dbt容器随后启动，执行挂载进来的 entrypoint 脚本，自动完成「灌种子数据 + 跑模型」两步（原理见下一节）；
3. 首次运行需要下载postgres与fishtownanalytics/dbt:0.21.0两个镜像，耗时较长属正常现象；之后再运行则秒级启动。

深入解析：entrypoint.sh 里的两行 dbt 命令

entrypoint.sh 是「数据库如何被填满」的关键，全文仅两行核心命令：

#!/bin/bash set -e dbt seed --profiles-dir ./docker dbt run --profiles-dir ./docker

• dbt seed：把 data/ 目录下的原始 CSV 物化为目标 schema 中的表。本演示工程刻意用 seed 而非 source 来保持自包含（原始数据直接以 CSV 形式随仓库分发）。本仓库版本的种子数据包括raw_customers.csv、raw_orders.csv、raw_payments.csv、raw_subscriptions.csv、raw_plan.csv等数十个文件（覆盖订阅、营销活动、漏斗、地图、医疗等主题）；
• dbt run：编译并运行 models/ 下的全部 SQL 模型（本仓库版本含 60 余个.sql模型），把原始表加工成面向分析的事实表与维度表，例如customers、orders、payments、subscriptions等；
• --profiles-dir ./docker：指向容器内/usr/app/docker/目录下的 profiles.yml（因为工程被挂载到/usr/app）；
• set -e：任一步骤失败立即终止，避免在空库上「假装成功」。

深入解析：profiles.yml 如何连接 Postgres

profiles.yml 定义了 dbt 与数据库的连接方式：

config: send_anonymous_usage_stats: false jaffle_shop: outputs: default: type: postgres threads: 4 host: postgres port: 5432 user: postgres pass: password dbname: postgres schema: jaffle

逐参数说明：

参数	值	说明
type	postgres	使用 Postgres 适配器
threads	4	dbt 并行执行线程数
host	postgres	注意：这里写的是服务名postgres而非localhost——dbt 容器运行在同一个 Compose 网络内，通过服务名解析到数据库容器
port	5432	Postgres 默认端口
user/pass	postgres/password	与 compose 中POSTGRES_PASSWORD一致
dbname	postgres	默认库
schema	jaffle	dbt 自动创建并使用的目标 schema，即验证数据时查询jaffle.payments的由来
config.send_anonymous_usage_stats	false	关闭 dbt 匿名使用统计上报

此外，dbt_project.yml 声明了工程的目录布局（model-paths: [models]、seed-paths: [data]、macro-paths: [macros]），并配置了物化策略：顶层模型默认materialized: table，staging/子目录下的模型为view；同时为raw_customers.created、raw_orders.order_date等种子列显式指定了column_types（如timestamp、date、numeric），保证 seed 后列类型符合模型 SQL 的假设。

Step 4. 验证数据已就绪

可以直接用 psql 连入 Postgres 检查数据是否灌入。connect.sh 的内容是：

docker compose exec postgres psql -U postgres postgres

它会进入一个交互式 psql 会话，在其中执行：

select * from jaffle.payments;

• 如果查询返回行数据，说明 seed 与 run 均已成功；
• 如果查询没有数据，说明流程某处出了问题（可回到docker compose logs dbt查看 dbt 容器日志定位失败原因）；
• 退出 psql：按Ctrl-d（control 键加d）。

Step 5. 从其他工具连接（例如 Lightdash）

以下连接信息适用于任意工具连接这个本地 Postgres：

port: 5432 host: localhost ( or 'host.docker.internal' if accessing from another docker container ) user: postgres password: password database: postgres schema: jaffle ssl: false ( or 'disabled' )

关键差异点——host 怎么填：

• 工具运行在宿主机上：用localhost，因为 compose 已把5432映射到宿主机；
• 工具运行在另一个 Docker 容器里（典型场景：用仓库根的 install.sh 容器化方式安装 Lightdash 后，在 Lightdash 里配置 warehouse connection）：必须用host.docker.internal才能穿透到宿主机上被映射出来的 5432 端口。

本仓库内 examples/full-jaffle-shop-demo/dbt/README.md 给出的 Lightdash 仓库连接参数与此完全一致（type: postgres、host:host.docker.internal、user:postgres、password:password、database:postgres、schema:jaffle、port:5432、ssl: disable）。

Step 6. 停止全部服务

./stop.sh

stop.sh 的内容为：

docker compose down

docker compose down会停止并移除postgres与dbt两个容器。注意它不会删除命名卷，因此 Postgres 的数据目录（若挂载了卷）在下次./start.sh后依然可用；若数据容器本身未持久化，重新start.sh时 dbt 也会重新 seed 与 run 一遍，数据库会再次被完整填充。

附录：全流程速查

步骤	命令 / 操作	对应文件
启动并灌数	./start.sh（即docker compose up -d -V）	start.sh
容器内建数逻辑	dbt seed+dbt run	entrypoint.sh
连接配置	profiles.yml（host 为服务名postgres）	profiles.yml
验证数据	./connect.sh后执行select * from jaffle.payments;	connect.sh
停止服务	./stop.sh（即docker compose down）	stop.sh
服务编排	dbt 0.21.0 镜像 + 官方 postgres 镜像，5432 端口映射	docker-compose.yml

适用前提与限制

• 机器需安装 Docker 且docker compose子命令可用；
• 5432端口需空闲，否则需调整 compose 的端口映射；
• dbt 镜像固定为fishtownanalytics/dbt:0.21.0，--profiles-dir写法是适配该版本的行为，升级 dbt 版本时需同步调整 entrypoint 的调用方式；
• 官方postgres镜像未锁版本，首次拉取与后续升级行为以镜像默认 tag 为准；
• 演示数据中的敏感值（password: password）仅用于本地开发，切勿照搬到任何共享或生产环境；
• 本流程的目标产物是 schema 为jaffle的本地演示库，供 Lightdash 连接与功能测试使用，不构成生产级部署方案。

【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash