Python Runner 部署指南为 Metabase 自托管 Python 转换配置独立执行环境【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabaseoutput_articleMetabase Python Runner 部署实战为自托管 Python 转换配置独立执行环境导读本文聚焦于 Metabase Data Studio 中 Python 转换Python transforms的关键基础设施——Python Runner一个独立于 Metabase 主实例运行的 Python 代码执行服务。你将掌握如何在自托管场景下通过 Docker、环境变量或 Docker Compose 完成 Python Runner 与 Metabase 的对接配置 S3 兼容存储AWS S3 / MinIO 等用于传递执行工件并理解这些配置项在 Metabase 后端源码中的真实语义与默认值。读完本文你可以独立搭建一套生产可用的 Python 转换执行环境并能定位常见的Metabase 连不上 RunnerRunner 连不上存储类故障。说明自托管场景下的 Python 转换需要自托管 Pro 或 Enterprise 计划并购买 Advanced transforms 附加组件。若使用 Metabase Cloud则需购买 Transforms 附加组件。Python Runner 的核心机制与配置流程详见 python-runner.md。一、为什么需要 Python Runner在了解配置之前先明确架构背景。Metabase 的转换Transforms承担了ETL 中的 T运行查询或脚本在目标数据库建表写入结果并把新表同步回 Metabase 供提问Questions或其他转换复用。转换分两类见 transforms-overview.md基于查询的转换query-based transforms用 SQL 或查询构建器编写直接在数据库内执行无需额外组件Python 转换Python transforms用 Python 编写运行在专门的执行环境中必须由 Python Runner 提供。Python 转换的完整工作链路见 python-transforms.md在 Metabase 中编写一个返回pandasDataFrame 的transform()函数引用一个或多个数据表Metabase 启动一个独立的 Python 执行环境而非在 Metabase 实例内部运行该脚本Metabase 安全地把源数据复制到 Python 环境以 pandas DataFrame 形式暴露Python 环境在内存中执行脚本把结果 DataFrame 保存为文件工件Metabase 读取该文件把结果写入目标数据库的新表并同步该表后续运行默认覆盖目标表除非配置了增量转换。这一Metabase ↔ Runner ↔ S3 存储的三方协作正是本文配置工作的核心。从企业版源码 base.clj 可以印证执行时会调用python-runner/copy-tables-to-s3!把源表复制到 S3再调用execute-python-code-http-call!让 Runner 执行脚本随后从 S3 读取输出清单output manifest与事件日志最终把结果写回数据库。因此 Runner 与 Metabase 之间通过HTTP API通信而数据工件通过S3 兼容存储中转。二、前置条件在开始部署前请确认满足以下条件python-runner.md已安装并运行Docker或具备可运行容器的其他基础设施持有自托管 Metabase Pro 或 Enterprise 许可证Python Runner 属于付费能力Open Source 自托管计划不可用参见 addons.md生产环境准备一个 S3 兼容的存储桶AWS S3、MinIO 等并记录访问凭据。另外请通读 transforms-overview.md 中自托管转换的完整设置路径检查计划 → 连接可写数据库转换会创建/替换表数据库用户需具备 create/drop/write 权限建议配置 writable connection→ 为 Python 转换准备 Runner → 在 Data Studio 中启用转换 → 创建并运行转换。三、快速开始内置 S3 服务器仅体验最简单的上手方式是使用 Python Runner 镜像自带的内置 S3 服务器端口 4566。此模式仅用于试用不可用于生产python-runner.md# 1. 创建 Docker 网络使容器之间可以通信 docker network create metabase-network # 2. 启动 Python Runner并启用内置 S3 docker run -d \ --network metabase-network \ -e AUTH_TOKENyour-secure-token-here \ -e ENABLE_INTERNAL_S3true \ --name python-runner metabase/python-runner:latest # 3. 启动 Metabase Enterprise指向 Runner 与内置 S3 docker run -d \ --network metabase-network \ -p 3000:3000 \ -e MB_PYTHON_RUNNER_URLhttp://python-runner:5000 \ -e MB_PYTHON_RUNNER_API_TOKENyour-secure-token-here \ -e MB_PYTHON_STORAGE_S_3_ENDPOINThttp://python-runner:4566 \ -e MB_PYTHON_STORAGE_S_3_BUCKETmetabase-python-runner \ -e MB_PYTHON_STORAGE_S_3_REGIONus-east-1 \ -e MB_PYTHON_STORAGE_S_3_PATH_STYLE_ACCESStrue \ -e MB_PYTHON_STORAGE_S_3_ACCESS_KEYtest \ -e MB_PYTHON_STORAGE_S_3_SECRET_KEYtest \ --name metabase metabase/metabase-enterprise:latest两个容器必须处于同一 Docker 网络metabase-network因为 Metabase 通过容器名python-runner访问 Runner端口 5000与内置 S3端口 4566。内置 S3 的默认凭据为test/test仅用于本地体验。四、生产环境部署步骤生产环境必须使用外部的 S3 兼容存储服务python-runner.md分三步完成步骤 1生成安全的认证令牌Runner 与 Metabase 之间通过令牌token完成 API 鉴权令牌必须双方一致openssl rand -hex 32妥善保存生成的 64 位十六进制字符串两个容器都会用到它。步骤 2准备 S3 存储在 S3 兼容服务AWS S3、MinIO 等中创建一个存储桶并记下访问密钥Access Key与秘密密钥Secret Key。注意Metabase 和 MinIO 都不会自动创建桶桶必须由你提前创建下文 Compose 示例中的minio-init容器正是为此存在。步骤 3启动两个容器docker network create metabase-network # Python Runner不启用内置 S3 docker run -d \ --network metabase-network \ -e AUTH_TOKENyour-secure-token-here \ --name python-runner --hostname python-runner metabase/python-runner:latest # Metabase Enterprise指向外部 S3 docker run -d \ --network metabase-network \ -p 3000:3000 \ -e MB_PYTHON_RUNNER_URLhttp://python-runner:5000 \ -e MB_PYTHON_RUNNER_API_TOKENyour-secure-token-here \ -e MB_PYTHON_STORAGE_S_3_ENDPOINThttps://s3.amazonaws.com \ -e MB_PYTHON_STORAGE_S_3_BUCKETyour-bucket-name \ -e MB_PYTHON_STORAGE_S_3_REGIONus-east-1 \ -e MB_PYTHON_STORAGE_S_3_ACCESS_KEYyour-access-key \ -e MB_PYTHON_STORAGE_S_3_SECRET_KEYyour-secret-key \ --name metabase metabase/metabase-enterprise:latest使用 AWS S3 时无需设置MB_PYTHON_STORAGE_S_3_PATH_STYLE_ACCESS默认关闭使用虚拟主机式寻址仅当使用 MinIO、LocalStack 等 S3 兼容服务时才需置为true。五、配置参考环境变量全解析5.1 Python Runner 侧环境变量变量说明AUTH_TOKEN用于 API 请求的认证令牌必须与 Metabase 的MB_PYTHON_RUNNER_API_TOKEN一致ENABLE_INTERNAL_S3设为true时启用内置 S3 服务器端口 4566仅用于试用不适用于生产5.2 Metabase 侧环境变量这些设置也可以在 Metabase UI 中配置AdminSettingsPython Runner。注意环境变量的优先级高于 UI 设置。变量说明MB_PYTHON_RUNNER_URLMetabase 访问 Python Runner 的地址如http://python-runner:5000MB_PYTHON_RUNNER_API_TOKEN认证令牌必须与 Runner 的AUTH_TOKEN一致MB_PYTHON_STORAGE_S_3_ENDPOINTS3 端点 URLMB_PYTHON_STORAGE_S_3_CONTAINER_ENDPOINTRunner 容器视角看到的 S3 端点若与主端点不同才需要设置MB_PYTHON_STORAGE_S_3_BUCKET存储 Python 工件的 S3 桶名MB_PYTHON_STORAGE_S_3_REGIONAWS 区域如us-east-1MB_PYTHON_STORAGE_S_3_ACCESS_KEYS3 访问密钥MB_PYTHON_STORAGE_S_3_SECRET_KEYS3 秘密密钥MB_PYTHON_STORAGE_S_3_PATH_STYLE_ACCESS可选使用 MinIO 或 LocalStack 等 S3 兼容服务时设为true5.3CONTAINER_ENDPOINT的语义MB_PYTHON_STORAGE_S_3_CONTAINER_ENDPOINT是Metabase 签署进预签名 URLpresigned URLs的主机名Runner 通过该 URL 上传与下载工件。当Runner 解析存储服务所用的主机名与 Metabase 不同时需要设置此项为 Runner 视角的地址python-runner.md。典型场景Metabase 与 Runner 不在同一网络Metabase 通过https://s3.amazonaws.com访问 S3而 Runner 容器内必须通过http://minio:9000才能访问到同一存储——此时ENDPOINT填 Metabase 视角的地址CONTAINER_ENDPOINT填 Runner 视角的地址Metabase 会按后者生成 Runner 可访问的预签名 URL。5.4 源码层面的完整参数清单从企业版源码 settings.clj 可以看到Metabase 后端实际定义了比文档表格更完整的设置项且带有非生产环境默认值config/is-prod?为假时生效便于本地开发源码设置名对应环境变量类型非生产默认值说明源码注释python-runner-urlMB_PYTHON_RUNNER_URLstringhttp://localhost:5001运行 transform 函数的 Python 执行服务器 URLpython-runner-api-tokenMB_PYTHON_RUNNER_API_TOKENstring敏感dev-token-12345与 python-runner 服务通信的 API 令牌python-storage-s-3-endpointMB_PYTHON_STORAGE_S_3_ENDPOINTstringhttp://localhost:4566存储 Python 执行工件的 S3 端点python-storage-s-3-regionMB_PYTHON_STORAGE_S_3_REGIONstringus-east-1S3 存储区域python-storage-s-3-bucketMB_PYTHON_STORAGE_S_3_BUCKETstringmetabase-python-runner存储 Python 执行工件的 S3 桶python-storage-s-3-prefixMB_PYTHON_STORAGE_S_3_PREFIXstringtest-prefixS3 对象前缀生产环境需要设置以限定访问特定前缀python-storage-s-3-access-keyMB_PYTHON_STORAGE_S_3_ACCESS_KEYstring敏感testS3 访问密钥 IDpython-storage-s-3-secret-keyMB_PYTHON_STORAGE_S_3_SECRET_KEYstring敏感testS3 秘密访问密钥python-storage-s-3-container-endpointMB_PYTHON_STORAGE_S_3_CONTAINER_ENDPOINTstringhttp://localstack:4566容器内可访问的替代 S3 端点与主端点相同则留空python-storage-s-3-path-style-accessMB_PYTHON_STORAGE_S_3_PATH_STYLE_ACCESSbooleantrue对 S3 请求使用路径式访问LocalStack 及部分 S3 兼容服务必需python-runner-timeout-secondsinteger180030 分钟Python 脚本执行超时python-runner-test-run-timeout-secondsinteger601 分钟Python 脚本测试运行预览超时值得注意的源码细节敏感项加密python-runner-api-token、python-storage-s-3-access-key、python-storage-s-3-secret-key等在设置了加密密钥时会加密存储encryption :when-encryption-key-set其中令牌与秘密密钥不参与审计audit :never特性门控以上所有设置均标记feature :transforms-python即仅在启用 Advanced transformsPython 转换能力后生效生产默认值缺失所有默认值都只在非生产环境生效生产环境下必须显式提供全部配置这正是上文生产部署必须逐项填写环境变量的源码依据。5.5 Runner 的 HTTP API 端点从 python_runner.clj 可以确认 Runner 对外暴露的 HTTP 接口理解这些端点有助于排查故障POST /execute提交 Python 脚本执行携带request_id、脚本内容、超时参数等GET /logs按request_id获取执行日志POST /cancel按request_id取消执行。其中python-runner-request会携带api-token来自MB_PYTHON_RUNNER_API_TOKEN完成鉴权——这就是文档强调Runner 的AUTH_TOKEN必须与 Metabase 的MB_PYTHON_RUNNER_API_TOKEN一致的原因。六、Docker Compose 一键部署含 MinIO生产或长期测试环境推荐使用 Docker Compose 编排全部组件。官方文档提供了一套自托管存储 MinIO的完整示例python-runner.md。MinIO 是自托管场景下常见的 S3 兼容服务器与自托管 Metabase 搭配自然。该 Compose 文件同时运行 Metabase、Python Runner、MinIO以及一个一次性容器minio-init负责创建桶——因为 MinIO 与 Metabase 都不会替你创建桶name: metabase-python-runner services: metabase: image: metabase/metabase-enterprise:latest ports: - 3000:3000 environment: - MB_PYTHON_RUNNER_URLhttp://python-runner:5000 - MB_PYTHON_RUNNER_API_TOKEN${AUTH_TOKEN} - MB_PYTHON_STORAGE_S_3_ENDPOINThttp://minio:9000 - MB_PYTHON_STORAGE_S_3_CONTAINER_ENDPOINThttp://minio:9000 - MB_PYTHON_STORAGE_S_3_BUCKETmetabase-python-runner - MB_PYTHON_STORAGE_S_3_REGIONus-east-1 - MB_PYTHON_STORAGE_S_3_PATH_STYLE_ACCESStrue - MB_PYTHON_STORAGE_S_3_ACCESS_KEY${MINIO_ROOT_USER} - MB_PYTHON_STORAGE_S_3_SECRET_KEY${MINIO_ROOT_PASSWORD} depends_on: minio-init: condition: service_completed_successfully python-runner: condition: service_started python-runner: image: metabase/python-runner:latest environment: - AUTH_TOKEN${AUTH_TOKEN} minio: image: quay.io/minio/minio:latest command: server /data --console-address :9001 environment: - MINIO_ROOT_USER${MINIO_ROOT_USER} - MINIO_ROOT_PASSWORD${MINIO_ROOT_PASSWORD} volumes: - minio-data:/data minio-init: image: quay.io/minio/mc:latest depends_on: minio: condition: service_started entrypoint: - /bin/sh - -c - | until mc alias set local http://minio:9000 ${MINIO_ROOT_USER} ${MINIO_ROOT_PASSWORD} /dev/null 21; do echo waiting for minio...; sleep 2; done mc mb --ignore-existing local/metabase-python-runner volumes: minio-data: {}为什么两个 S3 端点变量都指向http://minio:9000因为 Metabase 与 Runner 共享同一个 Compose 网络二者以相同主机名访问 MinIO。MB_PYTHON_STORAGE_S_3_CONTAINER_ENDPOINT决定 Metabase 签署进预签名 URL 的主机名——若你的 Runner 与 Metabase 解析存储的主机名不同应将其设为 Runner 视角的地址。创建.env文件提供共享凭据AUTH_TOKENyour-secure-token-here MINIO_ROOT_USERminioadmin MINIO_ROOT_PASSWORDminioadmin然后按顺序完成验证生成强共享密钥Runner 与 Metabase 必须对同一令牌达成一致openssl rand -hex 32启动整个栈docker compose up -d启用并运行转换需要带有 Advanced transforms 附加组件 的 Pro 或 Enterprise 许可证。先在 Metabase 中启用转换再创建 Python 转换并点击Run。查看运行结果打开Data Studio Jobs Runs找到本次运行。若运行失败日志通常会指明故障方向是 Metabase 无法连接 Runner还是 Runner 无法连接 MinIO。七、验证与排障指南7.1 验证连通性部署完成后可通过以下方式快速验证Runner 可达性在 Metabase 容器内测试curl http://python-runner:5000或从宿主机curl http://localhost:5000若已映射端口确认 HTTP 服务响应S3 可达性在 Runner 容器内测试对http://minio:9000的访问MinIO 场景确认凭据与桶存在端到端创建最小 Python 转换并点击Run Python script编辑器右下角按钮Metabase 会从每个输入表拉取100 行数据运行预览可在Results preview标签页查看结果、在Output标签页查看print()输出。7.2 常见故障方向Metabase 无法连接 Runner检查MB_PYTHON_RUNNER_URL是否可从 Metabase 容器解析、AUTH_TOKEN与MB_PYTHON_RUNNER_API_TOKEN是否一致、两容器是否在同一网络Runner 无法连接存储检查MB_PYTHON_STORAGE_S_3_*系列配置特别是 MinIO 场景下PATH_STYLE_ACCESStrue与CONTAINER_ENDPOINT是否正确桶不存在MinIO 与 Metabase 都不会自动建桶确认minio-init成功执行mc mb完成。7.3 运行时行为约束源码佐证Python 转换串行执行从 settings.clj 的源码注释可以看到python-runner 服务是单线程的因此 Python 转换在作业内总是逐个执行并行派发只会让它们排队并各自触发超时与之对比SQL 转换可通过transform-run-job-sql-concurrency默认 3并行执行转换超时transform-timeout默认 240 分钟控制整个转换作业的超时优先于常规查询的MB_DB_QUERY_TIMEOUT_MINUTES测试预览超时python-runner-test-run-timeout-seconds默认 60 秒约束点击Run Python script时的预览执行。八、生产环境 Checklist完成部署后请对照以下清单逐项确认✅ 使用openssl rand -hex 32生成强令牌并确保 Runner 的AUTH_TOKEN与 Metabase 的MB_PYTHON_RUNNER_API_TOKEN完全一致✅ S3 桶已提前创建MinIO 场景由minio-init完成Metabase 与 Runner 均能访问✅ 生产环境显式设置了全部MB_PYTHON_STORAGE_S_3_*配置源码默认值仅存在于非生产环境✅ 若 Runner 解析存储的主机名与 Metabase 不同正确设置了MB_PYTHON_STORAGE_S_3_CONTAINER_ENDPOINT✅ MinIO / LocalStack 场景设置MB_PYTHON_STORAGE_S_3_PATH_STYLE_ACCESStrue✅ 已购买 Advanced transforms 附加组件并在 Data Studio 中启用转换、配置了带写入权限的可写连接✅ 通过Data Studio Jobs Runs验证了一次真实的 Python 转换运行并检查其日志。完成以上步骤后你的 Metabase 即可稳定地承载 Python 转换工作负载。更进一步可阅读 python-transforms.md 掌握transform()函数编写技巧与增量转换配置或通过 jobs-and-runs.md 将转换纳入定时调度。 /output_article【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考