• 数据库
• 关系型数据库
• 后端
• CLI

Dolt 是一个"Git for Data"的关系型数据库——它是一套可以像 Git 仓库一样 fork、clone、branch、merge、push、pull 的 SQL 数据库，同时又兼容 MySQL 协议与 SQL 语法。官方为 Dolt 提供两套 Docker 镜像：dolthub/dolt（CLI 工具镜像）与dolthub/dolt-sql-server（SQL Server 服务镜像），本指南基于仓库 docker/README.md、docker/serverREADME.md 及配套的 docker/Dockerfile、docker/serverDockerfile、docker/docker-entrypoint.sh，完整讲解这两套镜像的用法、构建方式、环境变量与配置挂载机制，读完即可在本地用 Docker 快速启动一个可版本控制的 MySQL 兼容数据库。

镜像与仓库布局

docker/目录是 Dolt 官方容器化方案的全部资产，对应两种交付形态：

• dolthub/dolt：面向 Dolt 命令行（CLI），无参数运行时等价于在容器内执行dolt命令；
• dolthub/dolt-sql-server：面向 Dolt SQL Server 服务模式，等价于在容器内执行dolt sql-server --host 0.0.0.0 --port 3306。

两者的构建文件与初始化脚本分别是：

使用 CLI 镜像：一个容器化的 Dolt 命令行

CLI 镜像的定位很纯粹：镜像内只有一个可直接执行的dolt二进制，任何dolt支持的子命令都能以容器参数的形式传入。无参数运行即打印命令帮助：

$ docker run dolthub/dolt:latest Valid commands for dolt are init - Create an empty Dolt data repository. status - Show the working tree status. add - Add table changes to the list of staged table changes. diff - Diff a table. reset - Remove table changes from the list of staged table changes. clean - Remove untracked tables from working set. commit - Record changes to the repository. sql - Run a SQL query against tables in repository. sql-server - Start a MySQL-compatible server. sql-client - Starts a built-in MySQL client. log - Show commit logs. branch - Create, list, edit, delete branches. checkout - Checkout a branch or overwrite a table from HEAD. merge - Merge a branch. conflicts - Commands for viewing and resolving merge conflicts. cherry-pick - Apply the changes introduced by an existing commit. revert - Undo the changes introduced in a commit. clone - Clone from a remote data repository. fetch - Update the database from a remote data repository. pull - Fetch from a dolt remote data repository and merge. push - Push to a dolt remote. config - Dolt configuration. remote - Manage set of tracked repositories. backup - Manage a set of server backups. login - Login to a dolt remote host. creds - Commands for managing credentials. ls - List tables in the working set. schema - Commands for showing and importing table schemas. table - Commands for copying, renaming, deleting, and exporting tables. tag - Create, list, delete tags. blame - Show what revision and author last modified each row of a table. constraints - Commands for handling constraints. migrate - Executes a database migration to use the latest Dolt data format. read-tables - Fetch table(s) at a specific commit into a new dolt repo gc - Cleans up unreferenced data from the repository. filter-branch - Edits the commit history using the provided query. merge-base - Find the common ancestor of two commits. version - Displays the current Dolt cli version. dump - Export all tables in the working set into a file.

这份命令清单与仓库根 README.md 中dolt命令帮助完全一致，也与源码go/cmd/dolt/commands/下各命令模块一一对应（init.go、status.go、add.go、commit.go、sql.go、sqlserver/、clone.go、branch.go、merge.go等，见 go/cmd/dolt/commands）。

该镜像的主要价值是作为基础镜像：你可以基于dolthub/dolt:latest定制自己的数据流水线镜像，把dolt init、dolt sql、dolt commit等操作固化到自定义流程里。

CLI 镜像构建细节

docker/Dockerfile 的实现值得留意：

# syntax=docker/dockerfile:1.3-labs FROM ubuntu:22.04 ARG DOLT_VERSION RUN apt update -y && \ apt install -y \ curl \ git \ tini \ ca-certificates && \ apt clean && \ rm -rf /var/lib/apt/lists/* # we install dolt with the install.sh script, which will determine the platform/arch of the container # and install the proper dolt binary RUN bash -c 'curl -L https://github.com/dolthub/dolt/releases/download/v${DOLT_VERSION}/install.sh | bash' RUN /usr/local/bin/dolt version WORKDIR /var/lib/dolt ENTRYPOINT ["tini", "--", "/usr/local/bin/dolt"]

几个设计要点：

• ARG DOLT_VERSION构建参数：通过--build-arg DOLT_VERSION=x.y.z指定要安装的 Dolt 版本；
• 官方install.sh脚本安装：脚本会自动探测容器平台与 CPU 架构并下载对应二进制，保证多架构（如linux/amd64、linux/arm64）下都能拿到正确版本；
• tini作为 PID 1：ENTRYPOINT ["tini", "--", "/usr/local/bin/dolt"]使用tini做容器主进程，正确转发信号并回收僵尸进程——这保证了在 Kubernetes 等环境执行docker stop时dolt能被优雅终止；
• WORKDIR /var/lib/dolt：容器内数据目录默认为/var/lib/dolt，挂载卷时以它为挂载点即可持久化数据。

使用 SQL Server 镜像：MySQL 兼容的服务端

dolthub/dolt-sql-server镜像的行为与官方mysql镜像类似：启动即拉起dolt sql-server，监听0.0.0.0:3306。想查看dolt sql-server支持的全部选项，直接传--help：

$ docker run dolthub/dolt-sql-server:latest --help

构建镜像的三种方式

docker/serverREADME.md 给出了三种DOLT_VERSION取值，对应三种构建策略：

1. 构建最新发布版（构建时自动向 GitHub API 查询最新版本号）：

$ docker build -f docker/serverDockerfile --build-arg DOLT_VERSION=latest -t dolt-sql-server:latest .

2. 构建指定版本：

$ docker build -f docker/serverDockerfile --build-arg DOLT_VERSION=1.59.7 -t dolt-sql-server:1.59.7 .

3. 从本地源码构建（适合参与 Dolt 开发、或想验证未发布改动）：

$ docker build -f dolt/docker/serverDockerfile --build-arg DOLT_VERSION=source -t dolt-sql-server:source .

⚠️ 从源码构建时，工作目录下不能存在其他以dolt开头的文件夹，因为 Dockerfile 使用通配符（COPY dolt*/go*/go.mod* ...）条件式拷贝源码目录，其他dolt*目录可能导致构建失败。源码构建要求工作区至少包含dolt/，其他依赖仓库需自行在 serverDockerfile 中补充COPY。

多阶段构建与二进制来源

docker/serverDockerfile 采用多阶段构建，把"二进制来源"与"运行时"解耦：

• download-binary阶段：当DOLT_VERSION=latest时通过 GitHub API 抓取最新 tag，然后下载官方install.sh安装二进制；指定具体版本时直接下载对应 release；
• build-from-source阶段：当DOLT_VERSION=source时，在golang:1.26.2-bookworm镜像中执行go mod download并go build -o /usr/local/bin/dolt ./cmd/dolt，即构建仓库中 go/cmd/dolt 的主入口；
• runtime阶段：基于debian:bookworm-slim，安装bzip2 gzip xz-utils zstd等压缩工具（用于解压后续初始化用的.sql.gz等文件），并从上面两个阶段之一拷贝二进制，最后执行/usr/local/bin/dolt version做冒烟校验。

运行时阶段还定义了三个关键路径与声明：

RUN mkdir /docker-entrypoint-initdb.d && mkdir -p /var/lib/dolt VOLUME /var/lib/dolt EXPOSE 3306 33060 7007 ENTRYPOINT ["tini", "--", "docker-entrypoint.sh"]

• /docker-entrypoint-initdb.d/：初始化 SQL 脚本目录（后文详述）；
• /var/lib/dolt：数据卷挂载点；
• 3306/33060/7007：SQL 端口、MySQL X 协议端口以及 Dolt 远程 API 端口；
• 入口同样用tini包裹 docker/docker-entrypoint.sh，保证信号正确处理。

从宿主机连接容器内的 SQL Server

容器默认只允许root@localhost连接——这是 Dolt 1.46.0 起引入的安全特性，防止未授权远程访问。若不想先docker exec进容器再连 SQL Server，可用两个环境变量控制root超级用户的初始化：DOLT_ROOT_HOST覆盖 root 的允许来源主机，DOLT_ROOT_PASSWORD覆盖 root 密码（默认空）。下面把 root 开放给任意主机并设置密码：

> docker run -e DOLT_ROOT_PASSWORD=secret2 -e DOLT_ROOT_HOST=% -p 3307:3306 dolthub/dolt-sql-server:latest

宿主机上即可用任意 MySQL 兼容客户端连接：

> mysql --host 0.0.0.0 -P 3307 -u root -p secret2

安全提示：将 root 开放给%（任意主机）时必须设置强密码。若仅需本机访问，保持默认localhost即可。

两种服务端配置方式

方式一：命令行参数

dolt sql-server的命令行参数可以直接追加在docker run末尾，例如启用 debug 日志并关闭自动提交：

$ docker run -p 3307:3306 dolthub/dolt-sql-server:latest -l debug --no-auto-commit

其中-l（--loglevel）与--no-auto-commit等标志的解析定义于源码 go/cmd/dolt/commands/sqlserver/sqlserver.go（logLevelFlag = "loglevel"、noAutoCommitFlag = "no-auto-commit"、configFileFlag = "config"等）。

方式二：YAML 配置文件挂载

服务端配置目录固定为容器内/etc/dolt/servercfg.d/，该目录内只能存在一个.yaml配置文件；若有多个，入口脚本会告警并回退到默认配置（见 docker/docker-entrypoint.sh 中get_config_file_path_if_exists的逻辑）。

将宿主机目录挂载到该路径：

$ docker run -p 3307:3306 -v /Users/jennifer/docker/server/:/etc/dolt/servercfg.d/ dolthub/dolt-sql-server:latest

入口脚本检测到唯一.yaml后，会以--config=<path>参数启动dolt sql-server。YAML 配置的结构与解析在源码中有测试佐证：go/cmd/dolt/commands/sqlserver/server_test.go的TestYAMLServerArgs使用log_level: info与behavior:等键验证配置生效；配置文件的加载与dataDir优先级处理可见 go/cmd/dolt/commands/sqlserver/command_line_config.go（dataDir会被提前取出并转为绝对路径，因为服务器启动前就需要确定数据目录）。

数据目录与 Dolt 全局配置的挂载

与服务器配置平行的还有两个特殊目录：

• 数据目录/var/lib/dolt/：Dolt 数据库文件默认存放位置。容器无需额外配置即可使用，但要在宿主机持久化，把它挂载为数据卷：

$ docker run -p 3307:3306 -v /Users/jennifer/docker/databases/:/var/lib/dolt/ dolthub/dolt-sql-server:latest

• Dolt 全局配置目录/etc/dolt/doltcfg.d/：存放唯一的.json配置文件。入口脚本发现后会将其拷贝到$HOME/.dolt/config_global.json，覆盖容器内默认的 Dolt 全局配置（对应 docker/docker-entrypoint.sh 中set_dolt_config_if_defined的实现）。

另外注意：如果docker run在入口脚本执行过程中报错退出，需要先用docker rm -f <container_name>删除上次遗留的容器，再重新运行。

环境变量一览

SQL Server 镜像支持以下环境变量（完整继承自 docker/serverREADME.md）：

要点说明（均与入口脚本实现一一对应）：

• DOLT_*优先于MYSQL_*：入口脚本的get_env_var先读DOLT_*再读MYSQL_*，因此两种命名都可用，且前者优先级更高；
• 数据库与用户创建：DOLT_DATABASE会触发CREATE DATABASE IF NOT EXISTS；DOLT_USER与DOLT_PASSWORD必须成对出现，缺密码会直接报错退出，只有密码没有用户则告警忽略；不允许通过环境变量创建名为root的用户（防止与超级用户初始化冲突，见 docker/docker-entrypoint.sh 的create_user_from_env）；
• 权限授予：自定义用户会被授予USAGE ON *.*；若同时指定了数据库，则再授予该库的全部权限（GRANT ALL ON <db>.*）；
• root 兜底逻辑：服务器启动后，脚本会检查mysql.user中是否存在root@<DOLT_ROOT_HOST>；若不存在（例如初始化脚本与 root 环境变量的初始化冲突），会强制覆盖创建 root 并授予ALL PRIVILEGES ... WITH GRANT OPTION。

初始化脚本机制：/docker-entrypoint-initdb.d

与 MySQL 官方镜像一致，SQL Server 镜像支持在首次启动时执行/docker-entrypoint-initdb.d/下的初始化文件（该机制移植自docker-library/mysql8.0 的 entrypoint，见 docker/docker-entrypoint.sh 的docker_process_init_files）。支持的文件类型与处理方式：

执行 SQL 时使用exec_mysql函数：它反复重试dolt sql直到成功或超过DOLT_SERVER_TIMEOUT，并过滤错误输出、按需--show-result打印结果——这保证了服务器冷启动或资源紧张时初始化脚本仍能可靠执行。初始化完成后会写入.init_completed标记文件，避免重复初始化。此外，dolt_server_initializer会在后台拉起dolt sql-server --host=0.0.0.0 --port=3306并轮询 TCP 端口就绪后才继续执行后续初始化，因此库/用户创建与初始化脚本都能稳定落到一个"活着"的服务器上。

典型工作流小结

1. 想快速体验 Dolt 命令行：docker run dolthub/dolt:latest <subcommand>，或基于 docker/Dockerfile 定制自己的镜像；
2. 想跑一个 MySQL 兼容、可 fork/clone/branch/merge 的数据库服务：docker run -e DOLT_ROOT_PASSWORD=secret2 -e DOLT_ROOT_HOST=% -p 3307:3306 dolthub/dolt-sql-server:latest，再用任意 MySQL 客户端连接；
3. 需要持久化与自定义配置：挂载/var/lib/dolt/（数据）、/etc/dolt/doltcfg.d/（Dolt 全局配置 JSON）、/etc/dolt/servercfg.d/（服务器 YAML 配置）；
4. 需要初始化数据库结构：将*.sql、*.sh放入/docker-entrypoint-initdb.d/，首次启动自动执行。

整套容器化方案在 docker/ 目录内自洽完整：两份 README 负责使用说明，两份 Dockerfile 负责两种交付形态的构建，一份 entrypoint 脚本负责服务端镜像的初始化编排。如果你需要在此基础上定制镜像（例如预置自己的库表、凭证或数据卷策略），直接以这两个镜像为基底扩展即可。

• 数据库
• 关系型数据库
• 后端
• CLI