简介OpenMetadata 是一款开源的一站式元数据管理平台集数据发现、血缘追踪、质量监控、数据治理与团队协作于一体。针对采用 Docker 部署的场景这份 doc 文档基于 CentOS 7 环境完整梳理了从基础环境准备Docker、Docker Compose、Python3、JDK到安装配置、启动访问的全流程操作包括镜像源设置、依赖安装、docker-compose.yml 的下载与自定义修改、MySQL 密码及主机端口调整、服务后台运行和通过浏览器访问首页等内容。整份资料共 1 个 doc 文件压缩包大小仅 693KB内容精简集中便于快速查阅。目前已有 1351 人学习适合具备一定容器基础、需要快速搭建元数据管理系统的开发运维人员参考。文档还针对基础镜像拉取超时、不同版本安装差异等常见问题给出了应对思路可帮助读者有效规避部署陷阱快速跑通平台并进行二次配置。1. openMetadata 用 Docker 装到底解决什么把 openMetadata 用 Docker 装起来是很多数据团队搭元数据体系的第一件事也是最容易“装起来却跑不起来”的一件事。openMetadata 本身是开源的数据目录与元数据管理平台解决的是表结构散落、指标口径对不上、数据血缘靠人脑的问题而 docker 安装这个动作解决的则是“快速验证 后续可迁移”的部署问题。这篇内容适合数据平台负责人、数据开发以及想自建元数据体系却不想碰源码编译的团队。我会直接给你可复现的 compose、命令和参数把初始化、避坑、备份这些真正决定能否用起来的点讲透。2. 安装前准备内存预算、端口清单与两条路线选型2.1 内存预算与端口清单先给机器做个减法单机验证 openMetadata 全家桶内存预算建议至少 8G。很多部署翻车不是配置写错而是机器太小。整个 docker 编排里最吃内存的是 Elasticsearch它既要当索引引擎又要承担搜索请求JVM heap 默认给到 2G再加上操作系统的页缓存一台 4G 内存的机器跑全家桶UI 能不能打开都是玄学。安装前先想清楚端口占用。openMetadata 默认暴露的关键端口如下端口对应服务说明8585openMetadata server / UI主入口浏览器访问9200Elasticsearch HTTP服务端连索引用3306MySQLcompose 内部元数据库8080ingestion 里的 Airflow Web UI可关掉不暴露最常见的冲突是宿主机已经装了 MySQL 或 ES3306 和 9200 被占。遇到这种情况我的做法是只改 compose 里的端口映射比如把 mysql 的映射改成 3307:3306ES 改成 9201:9200内部服务名和容器间通信地址不要动否则 openmetadata-server 连不上依赖。2.2 docker compose 全家桶 vs 单容器为什么多数场景我选 composeopenMetadata 官方镜像里最省事的是单容器跑 openmetadata-server看起来一条 docker run 就能起来。但实际用起来会发现server 只是平台的应用层元数据要落库、搜索要索引、定时抽取要调度这些依赖一个都不能少。单容器跑起来之后你还得自己准备 MySQL/PostgreSQL 和 Elasticsearch 实例并手工把连接信息灌进去部署成本反而更高。我一般会选 docker compose 全家桶一次性拉起 server、mysql、elasticsearch、ingestion 四个角色。compose 结构里mysql 存元数据、ES 做索引、ingestion 负责跑 Airflow 调度器去执行各类元数据抽取任务。新手跟这套走能最快看到一个完整可用的 openMetadata老手也能在这个骨架上做裁剪把外部依赖替换成自己托管的实例。除非你就是想看一眼前端长什么样否则别走单容器那条路。3. docker compose 跑通 openMetadata最小可运行配置3.1 拿到 compose 文件后先核对三个版本标识获取 compose 文件的常见做法是从官方发布页下载对应 release 的 docker-compose.yml或者把仓库克隆到本地后切到指定 tag。不管哪种方式拿到文件后第一件事不是 up而是核对版本标识是否对齐。docker compose version grep -E image:|container_name docker-compose.ymldocker compose 命令需要 v2 插件如果你的机器还是老式的 docker-compose命令要改成 docker-compose后续所有指令同步替换。grep 输出里重点看三项openmetadata-server 镜像 tag、openmetadata-ingestion 镜像 tag、elasticsearch 镜像版本。这三项必须和同一个 release 配套不能 server 是 1.x 而 ingestion 是另一个版本。我在实际部署中见过太多次“server 起来了但 ingestion 连不上”的故障最后查下来就是 tag 混搭。顺带说一句镜像拉取慢的问题先看 docker 的 registry mirror 有没有配好而不是反复去重启容器。网络层的问题在容器启动后很难通过日志定位提前配好镜像源能省下不少无意义的等待。3.2 精简一份最小 compose四个服务怎么配合我不建议直接拿官方 docker-compose.yml 一把梭里面的配置项多出问题不好排查。更稳妥的做法是自己写一个骨架版本跑通之后再对照官方参数逐个加。下面这个 compose 是我常用的最小结构镜像 tag 用了变量占位避免写死版本造成混淆。services: mysql: image: mysql:8 container_name: om_mysql environment: MYSQL_ROOT_PASSWORD: openmetadata MYSQL_DATABASE: openmetadata_db command: [mysqld, --max_allowed_packet64M] healthcheck: test: [CMD, mysqladmin, ping, -h, localhost] interval: 10s timeout: 5s retries: 10 elasticsearch: image: ${ES_IMAGE_VERSION} container_name: om_es environment: discovery.type: single-node ES_JAVA_OPTS: -Xms1g -Xmx1g healthcheck: test: [CMD-SHELL, curl -fs http://localhost:9200/_cluster/health] interval: 30s timeout: 10s retries: 5 openmetadata-server: image: ${OM_SERVER_IMAGE} container_name: om_server depends_on: mysql: condition: service_healthy elasticsearch: condition: service_healthy ports: - 8585:8585 environment: SERVER_PORT: 8585 DB_HOST: mysql DB_PORT: 3306 DB_USER: root DB_PASSWORD: openmetadata DB_NAME: openmetadata_db ELASTICSEARCH_HOST: elasticsearch ELASTICSEARCH_PORT: 9200 ingestion: image: ${OM_INGESTION_IMAGE} container_name: om_ingestion depends_on: openmetadata-server: condition: service_healthy environment: AIRFLOW_HOST: ingestion AIRFLOW_PORT: 8080这个骨架没有配 volumes 和自定义 network是为了先把问题收敛在“能否启动”这个层面。mysql 的 healthcheck 用 mysqladmin ping 探活ES 的 healthcheck 请求集群健康接口openmetadata-server 的 depends_on 用 service_healthy 条件确保依赖先就绪。这里最关键的两个参数是 ES_JAVA_OPTS 和 mysql 的 max_allowed_packet前者管内存后者管初始化是否中途断掉。ES 的 image 变量、server 镜像变量、ingestion 镜像变量在同目录的 .env 文件里定义ES_IMAGE_VERSIONdocker.elastic.co/elasticsearch/elasticsearch:7.17.13 OM_SERVER_IMAGEopenmetadata/server:1.4.4 OM_INGESTION_IMAGEopenmetadata/ingestion:1.4.4再次强调这里的版本号只是示例镜像 tag 必须换成你正在部署的 release 配套版本不要照抄。3.3 启动、等初始化、验证健康up 完不是终点compose 文件就位后启动命令只有三条docker compose up -d docker compose ps docker compose logs -f openmetadata-serverdocker compose up -d 是后台拉起全部服务docker compose ps 看每个服务当前状态出现 unhealthy 就说明依赖探活没过docker compose logs 跟踪 server 日志这是判断初始化进度最直接的窗口。首次启动 openmetadata-server 会做大量初始化动作建库建表、跑 schema migration、往 ES 里灌索引模板。日志里会看到很长一串数据库迁移输出这段时间容器一直处于“已经启动但还没 ready”的状态千万忍住别去 restart。判定成功的黄金标准是健康检查接口curl http://localhost:8585/api/v1/system/health返回 JSON 里 status 字段为 healthy 且数据库和 ES 子项都是绿色才说明平台真正起来了。这个时候再打开浏览器访问 http://localhost:8585应该能看到创建管理员账号的页面。如果是其他状态回到 docker compose logs 去查具体组件而不是盲目重启整个编排。4. 初始化与接入第一个数据源从空平台到有数据4.1 创建 admin 账号UI 背后的数据库初始化第一次打开 openMetadata 页面会要求创建管理员账号。这个步骤看起来只是注册用户实际上它完成了平台的最后一段初始化包括写入默认角色、创建 admin 语义、配置默认的认证策略。创建时邮箱和密码会直接写入 MySQL建议把密码复杂度设高一点再做因为这台机器暴露在公网的话8585 端口就是第一攻击面。创建完成后进 Settings - Users能看到 admin 默认角色已经挂上。如果这个页面报错通常不是账号问题而是前面的 server 没有等到 ES ready索引还没建好。回到 3.3 的 health 检查去排查不要在这里反复重试。4.2 用 API 接入 MySQL 数据源登录、建连接、跑 ingestionUI 里接数据源很直观但要把过程沉淀成可复用脚本我习惯用 API 演示一遍。先登录拿 tokencurl -X POST http://localhost:8585/api/v1/users/login \ -H Content-Type: application/json \ -d {email:adminexample.com,password:your_password}登录接口返回的 JSON 里会带 accessToken把它存成变量。接着用这个 token 创建 MySQL 数据源curl -X POST http://localhost:8585/api/v1/services/databaseServices \ -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json \ -d mysql-service.jsonmysql-service.json 的请求体如下{ name: sample_mysql, serviceType: Mysql, connection: { config: { type: Mysql, username: root, password: your_db_password, hostPort: 192.168.1.10:3306 } } }name 是 openMetadata 里的服务名建议用能看出来环境的命名规范serviceType 必须写 Mysql连接器靠它决定解析协议hostPort 这里特别容易踩坑不要写 localhost因为 openmetadata-server 跑在容器里localhost 指向容器自身要写宿主机在局域网里的 IP或者直接写数据库容器的服务名。数据源创建成功后去 UI 的 Settings - Services 找到 sample_mysql点 Add Ingestion选 metadata ingestionscope 覆盖 schema 和 table。跑完之后去 Explore 页面就能看到同步回来的库表结构。如果跑完没有任何数据去看 ingestion 容器的日志十有八九是 hostPort 写错连接器根本没摸到数据库。4.3 metadata / profiler / lineage 三种 pipeline 的取舍openMetadata 的 ingestion 不止一种新建时能看到好几类 pipeline。常见的三种需要分清楚metadata ingestion 抽库表字段结构是最基础的一类profiler ingestion 做数据画像统计行数、空值率、分布开销大但能支撑数据质量看板lineage ingestion 抽血缘依赖上游日志或 dbt 这类工具的元数据输出。我的建议是第一个星期只跑 metadata ingestion。先让元数据目录转起来等团队开始依赖它了再按需开启 profiler 和 lineage。一上来全开ES 的索引压力、ingestion 容器的调度压力都会同时上来出了问题很难判断是哪一步引起的。分开开每步都能在日志里找到对应执行的记录。5. openMetadata Docker 安装避坑ES、MySQL 与版本三座大山5.1 ES 容器反复重启vm.max_map_count 与 heap 参数现象elasticsearch 容器起来几秒就退出docker compose ps 里一直显示 Restartingdocker logs 里能看到 bootstrap checks failed 或者内存相关报错openmetadata-server 日志里持续出现连接 9200 失败。原因最常见是两个。一是 Linux 默认的 vm.max_map_count 只有 65530ES 7.x 要求至少 262144没调的话启动阶段直接拒绝运行二是机器内存不够ES 的 JVM heap 默认约 2G加上页缓存和另外三个容器整机被 OOM killer 杀掉表现就是容器反复退出。解决先调系统参数再动容器。临时生效执行 sysctl -w vm.max_map_count262144永久生效写入 /etc/sysctl.conf。同时把 compose 里 ES 的 ES_JAVA_OPTS 改小例如 -Xms1g -Xmx1g。注意这两个动作要一起做只调堆不调系统参数ES 照样起不来只调系统参数不改堆小内存机器还是会被 OOM。5.2 MySQL max_allowed_packet 太小初始化脚本载入中断现象首次启动时 mysql 容器是 healthy 的但 openmetadata-server 日志卡在 migration 阶段不断报错关键词是 Packet too large或者直接出现连接被中断的异常。这个报错偶尔被误判成网络问题其实和网络没有关系。原因openMetadata 的 schema 迁移脚本里包含批量插入和大字段写入MySQL 5.7/8.0 默认的 max_allowed_packet 通常只有 4M大语句直接超出上限被服务端拒绝。这个问题只在初始化阶段出现跑完的实例日常使用不太会撞到所以很多人第一次安装时完全没防备。解决在 compose 的 mysql 服务里加一句 command: [mysqld, --max_allowed_packet64M]然后重新创建 mysql 容器。改 command 属于启动参数变更docker compose up -d mysql 会重建容器。如果你在骨架基础上加了 volumes 挂载数据目录重建不影响数据如果没挂 volume此时 MySQL 里的数据会消失所以动手前先确认这一点避免把已经初始化的库表冲掉。5.3 镜像 tag 与 compose 不对齐接口 404 与升级翻车现象openMetadata 页面能打开但某些接口持续 404或者创建数据源时请求体被拒、提示字段不存在。更隐蔽的表现是升级之后server 正常启动但所有连接器都变红日志里看不到明确错误。原因openmetadata-server、openmetadata-ingestion、ES 三者 tag 没锁在同一 release。不同 release 的 API 路径、请求体结构和连接器协议都可能有差异server 是新的、ingestion 是旧的两边握手失败页面表现就是 404 或校验不过。解决用 docker compose images 一次性列出全部镜像 tag确认三者版本对齐。升级时不要只升 server所有 openmetadata 系镜像必须同步换。ES 是否一起升看 release 说明大版本升级里 ES 通常也有要求别自作主张保留旧版。5.4 ingestion 容器卡在启动循环depends_on 不等于 ready现象ingestion 容器一直 Restarting日志里在反复报连接 openmetadata-server 失败或 Airflow 初始化超时。这时候单独看 ingestion 容器不会发现配置错误因为它本身没报语法问题。原因compose 的 depends_on 默认只保证启动顺序不保证依赖服务已经 ready。如果条件没写 service_healthymysql 和 ES 还没就绪时 server 就开始跑ingestion 又在 server 就绪前启动Airflow scheduler 连不上平台 API就会陷入启动-失败-重启的循环。解决给 openmetadata-server 的 depends_on 加 condition: service_healthy给 ingestion 也做同样的健康依赖保证链路是 mysql/ES - server - ingestion 递进启动。同时用 docker compose logs --tail200 openmetadata-server 确认 server 的 migration 是否真正跑完。如果 server 还在刷迁移日志先把服务按依赖顺序手动一个个拉起来比反复重启整套编排要快得多。6. 备份、升级与生产化装完之后的三个收尾动作6.1 数据库备份与升级先备份再动 tagopenMetadata 的元数据全部落在 MySQL 里ES 只是索引所以备份的核心就是把 openmetadata_db 这个库导出。我自己的习惯是任何 compose 改动、任何升级动作前先执行一次 dumpdocker compose exec -T mysql sh -c exec mysqldump -uroot -popenmetadata openmetadata_db backup_om_$(date %F).sql恢复时反向灌回去即可cat backup_om_2025-06-01.sql | docker compose exec -T mysql sh -c exec mysql -uroot -popenmetadata openmetadata_db升级路径我的做法是停编排 - 备份数据库 - 修改 compose 里的镜像 tag - docker compose up -d - 等初始化完成。openMetadata 在启动时会自动跑数据库迁移和索引重建但前提是 MySQL 的 max_allowed_packet 等底线参数和升级前保持一致。我在几个团队的升级里见过一次翻车就是有人只换了 server 镜像、没带上 5.2 里的 mysql command 参数升级时重新初始化大字段又触发了 Packet too large。6.2 生产化判断什么时候把 MySQL 和 ES 挪出去判断标准我给得很朴素数据资产超过几百张表或者有五个人以上日常在用。在这个临界点之前单机全家桶还能应付超过之后让 MySQL 和 ES 跟 server 挤一台机器出问题时连排查的余地都没有。挪出去之后的拓扑很清晰托管数据库 托管 ES 实例docker 只跑 openmetadata-server 和 ingestion镜像 tag 依然锁定同一 release。这套迁移主要动环境变量连接串平台自己对这个形态的适配是完整的。我前后在几个团队里用这套 docker 流程装 openMetadata最深的习惯就是“先备份、再动 tag、最后才重启”。每次觉得麻烦省掉备份后面都补了课。希望帮到你。本文还有配套的精品资源点击获取