如何在Docker中持久化Keycloak默认数据库并复用容器

当前你启动Keycloak时使用的是内置H2数据库，数据默认存储在容器内部的文件系统中——每次执行docker run都会创建全新容器，旧容器销毁后内部数据也会丢失。要实现可重复运行且保留数据的容器，核心是通过数据持久化将数据存储到容器外部，以下是两种实用方案：

方案一：使用Docker数据卷持久化数据 #

Docker数据卷由Docker统一管理，是推荐的容器数据持久化方式，无需手动处理权限问题：

1. 创建专属数据卷（可选，直接挂载时Docker会自动创建）：

sudo docker volume create keycloak-h2-data

2. 带数据卷启动容器，并指定固定容器名方便后续管理：

sudo docker run -d --name my-keycloak -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -v keycloak-h2-data:/opt/keycloak/data/h2 \
  quay.io/keycloak/keycloak:18.0.2 start-dev --http-relative-path /auth

3. 后续容器管理（无需再用docker run新建）：

• 停止容器：sudo docker stop my-keycloak
• 启动已有容器：sudo docker start my-keycloak
• 查看运行日志：sudo docker logs -f my-keycloak

数据会永久保存在keycloak-h2-data卷中，即使删除容器，重新挂载该卷启动新容器也能恢复数据。

方案二：挂载宿主机目录持久化数据 #

如果需要直接在宿主机访问数据文件，可以挂载本地目录：

1. 在宿主机创建数据目录并设置正确权限（Keycloak容器内以UID=1000的用户运行）：

sudo mkdir -p /opt/keycloak/h2-data
sudo chown 1000:1000 /opt/keycloak/h2-data

2. 挂载目录启动容器：

sudo docker run -d --name my-keycloak -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -v /opt/keycloak/h2-data:/opt/keycloak/data/h2 \
  quay.io/keycloak/keycloak:18.0.2 start-dev --http-relative-path /auth

后续同样使用docker start/stop管理容器，数据会保存在宿主机的/opt/keycloak/h2-data目录中。

关键提示 #

• 绝对不要每次执行docker run创建新容器，必须通过容器名复用已创建的容器，才能保证数据不丢失。
• 如果需要调整启动参数，先停止并删除旧容器（数据已在外部存储中，删除容器不影响数据），再用新参数重新执行docker run并挂载同一个数据卷/目录即可。

内容的提问来源于stack exchange，提问作者Illyrian