企业官网建设流程全解析

简介：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 默认暴露的关键端口如下：

最常见的冲突是宿主机已经装了 MySQL 或 ES，3306 和 9200 被占。遇到这种情况，我的做法是只改 compose 里的端口映射，比如把 mysql 的映射改成 3307:3306，ES 改成 9201:9200，内部服务名和容器间通信地址不要动，否则 openmetadata-server 连不上依赖。

2.2 docker compose 全家桶 vs 单容器：为什么多数场景我选 compose

openMetadata 官方镜像里最省事的是单容器跑 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.yml

docker 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_packet=64M"] 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_VERSION=docker.elastic.co/elasticsearch/elasticsearch:7.17.13 OM_SERVER_IMAGE=openmetadata/server:1.4.4 OM_INGESTION_IMAGE=openmetadata/ingestion:1.4.4

再次强调：这里的版本号只是示例，镜像 tag 必须换成你正在部署的 release 配套版本，不要照抄。

3.3 启动、等初始化、验证健康：up 完不是终点

compose 文件就位后，启动命令只有三条：

docker compose up -d docker compose ps docker compose logs -f openmetadata-server

docker 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 数据源：登录、建连接、跑 ingestion

UI 里接数据源很直观，但要把过程沉淀成可复用脚本，我习惯用 API 演示一遍。先登录拿 token：

curl -X POST http://localhost:8585/api/v1/users/login \ -H 'Content-Type: application/json' \ -d '{"email":"admin@example.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.json

mysql-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 ingestion，scope 覆盖 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 里一直显示 Restarting；docker logs 里能看到 bootstrap checks failed 或者内存相关报错；openmetadata-server 日志里持续出现连接 9200 失败。

原因：最常见是两个。一是 Linux 默认的 vm.max_map_count 只有 65530，ES 7.x 要求至少 262144，没调的话启动阶段直接拒绝运行；二是机器内存不够，ES 的 JVM heap 默认约 2G，加上页缓存和另外三个容器，整机被 OOM killer 杀掉，表现就是容器反复退出。

解决：先调系统参数再动容器。临时生效执行 sysctl -w vm.max_map_count=262144，永久生效写入 /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_packet=64M"]，然后重新创建 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_healthy，mysql 和 ES 还没就绪时 server 就开始跑，ingestion 又在 server 就绪前启动，Airflow scheduler 连不上平台 API，就会陷入启动-失败-重启的循环。

解决：给 openmetadata-server 的 depends_on 加 condition: service_healthy，给 ingestion 也做同样的健康依赖，保证链路是 mysql/ES -> server -> ingestion 递进启动。同时用 docker compose logs --tail=200 openmetadata-server 确认 server 的 migration 是否真正跑完。如果 server 还在刷迁移日志，先把服务按依赖顺序手动一个个拉起来，比反复重启整套编排要快得多。

6. 备份、升级与生产化：装完之后的三个收尾动作

6.1 数据库备份与升级：先备份再动 tag

openMetadata 的元数据全部落在 MySQL 里，ES 只是索引，所以备份的核心就是把 openmetadata_db 这个库导出。我自己的习惯是任何 compose 改动、任何升级动作前，先执行一次 dump：

docker 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、最后才重启”。每次觉得麻烦省掉备份，后面都补了课。希望帮到你。

本文还有配套的精品资源，点击获取