Docker 上 Metabase 故障排除

Docker 简化了运行 Metabase 的许多方面，但也有一些陷阱需要注意。如果您在使用 Docker 运行 Metabase 时遇到问题，请尝试完成以下故障排除流程，然后查看下面关于您发现的特定问题的详细信息。

1. 容器是否正在运行？
2. 服务器是否在容器内运行？
3. Metabase 是否使用了正确的应用程序数据库？
4. 您是否可以连接到 Metabase 端口上的 Docker 主机？
5. 您是否可以从 Docker 主机连接到容器？
6. 您是否可以从容器内部连接到服务器？

您可能会发现以下命令在整个过程中很有用。进入 Metabase 容器中的 shell

docker exec -ti CONTAINER_NAME bash

以及获取 Metabase 容器的日志

docker logs -f CONTAINER_NAME

Metabase 容器退出，但未启动服务器

如何检测： 运行 docker ps 以查看 Metabase 容器当前是否正在运行。如果是，请继续下一步。

如果 docker ps 未显示正在运行的容器，则通过运行以下命令列出已停止的容器

docker ps -a | grep metabase/metabase

查找最近退出的容器，并记下容器 ID。使用以下命令查看该容器的日志

Docker logs CONTAINER_ID

Metabase 容器正在运行，但服务器未运行

如何检测： 运行 docker ps 以确保容器正在运行。服务器应将日志记录到 Docker 容器日志中。通过运行以下命令检查

docker logs CONTAINER_NAME

您应该在开头看到类似这样的行

05-10 18:11:32 INFO metabase.util :: Loading Metabase...

稍后，您最终应该看到类似这样的行

05-10 18:12:30 INFO metabase.core :: Metabase Initialization COMPLETE

如果您看到以下几行

05-15 19:07:11 INFO metabase.core :: Metabase Shutting Down ...
05-15 19:07:11 INFO metabase.core :: Metabase Shutdown COMPLETE

则 Metabase 已自行关闭。

如何修复： 检查 Docker 容器日志中是否有关于连接到应用程序数据库的错误。观看日志以查看 Metabase 是否仍在启动；命令

Docker logs -f CONTAINER_ID

将允许您查看打印的日志。

如果容器在完成启动之前被终止，则问题可能是用于启动容器的编排服务（例如 Docker Cloud）中的运行状况检查超时。

如果容器未从外部终止，但无论如何都无法启动，则此问题可能不是 Docker 特有的。如果您使用的是 Metabase 提供的镜像，请打开 GitHub issue。

未连接到远程应用程序数据库

如何检测： 如果这是一个新的 Metabase 实例，则您通过环境变量指定的数据库将为空。如果这是一个具有不正确环境变量参数的现有 Metabase 实例，服务器将创建一个新的 H2 嵌入式数据库用于应用程序数据，您将在日志中看到类似于以下的行

05-10 18:11:40 INFO metabase.core :: Setting up and migrating Metabase DB. Please sit tight, this may take a minute...
05-10 18:11:40 INFO metabase.db :: Verifying h2 Database Connection ...

05-10 18:11:40 INFO metabase.db :: Verify Database Connection ...  ✅

如何修复： 检查您是否正确地将环境传递给 Docker。您可以使用此命令列出容器的环境变量

docker inspect some-postgres -f '{{ .Config.Env }}'

Metabase 服务器无法连接到 MySQL 或 PostgreSQL 数据库

如何检测： Docker 容器的日志在“Verifying Database Connection”行之后返回错误消息。

如何修复： 尝试使用 mysql 或 psql 命令以及您在通过环境变量传递的连接字符串参数进行连接。如果您无法连接到数据库，则问题是由于凭据或连接性造成的。要验证凭据是否正确，请从另一台计算机使用这些凭据登录，然后尝试从运行 Docker 容器的主机建立相同的连接。

运行此操作的一种简单方法是使用 Docker 启动一个容器，该容器具有适用于您的数据库的客户端。对于 Postgres，它看起来像这样

docker run --name postgres-client --rm -ti --entrypoint /bin/bash postgres

在该容器中，尝试使用容器中的客户端命令（例如 psql）连接到数据库主机。如果您能够从同一主机上的另一个容器连接，则尝试从 Metabase Docker 容器本身内部建立该连接

docker exec -ti container-name bash

您也可以尝试使用 nc 命令连接到数据库主机，并检查是否可以打开连接

nc -v your-db-host 5432

这些步骤将帮助您确定问题是出在网络还是身份验证上。

Metabase 应用程序数据库未持久化

如何检测： 如果您每次启动应用程序时都看到“设置”屏幕，则会发生这种情况。最常见的原因是没有为 Docker 容器提供持久性文件系统挂载以将应用程序数据库放入其中。

如何修复： 确保您为容器提供了持久卷。

内部端口未正确重新映射

如何检测： 运行 docker ps 并查看端口映射，然后运行 curl http://localhost:port-number-here/api/health。这应该返回类似于以下的 JSON 响应

{"status":"ok"}

如何修复： 确保在用于启动 Metabase 容器镜像的 docker run 命令中包含 -p 3000:3000 或类似的端口重新映射。

Metabase 无法写入或读取文件或目录

如何检测： 日志中的消息将清楚地指示来自 Java 的 IOError 或“Permission denied”，或者来自 SQLite 的包含 org.sqlite.core.NativeDB._open_utf8 的错误。

如何修复： 确保运行 Metabase 的用户具有读取和写入文件或目录的权限

• 如果您在本地计算机或服务器中以 JAR 文件形式运行 Metabase，请检查运行 Java 进程的用户。
• 如果您从 Docker 容器运行 Metabase，请确保您正在使用 /metabase.db 目录。

如果您从任何类似 Unix 的操作系统中的 JAR 运行 Metabase，您可以通过打开终端并键入 ps -uA | grep metabase 来查看哪个用户正在运行 Metabase。