DuckDB Docker 镜像技术文档

1. 镜像概述与主要用途

DuckDB Docker镜像是DuckDB嵌入式分析数据库的容器化部署方案，构建自GitHub仓库 data-catering/duckdb-docker。该镜像旨在简化DuckDB的部署流程，提供无需手动配置依赖即可快速启动的运行环境，支持命令行交互与Web UI访问，适用于本地开发、数据分析及快速功能验证场景。

2. 核心功能与特性

2.1 基础功能

• DuckDB内核支持：集成DuckDB核心功能，包括SQL标准支持、ACID事务、列式存储优化、内存计算等嵌入式分析数据库特性。
• 轻量级部署：基于Docker容器化，无需本地安装DuckDB依赖，一键启动数据库实例。

2.2 镜像增强特性

• 交互模式支持：通过终端交互模式（-it）直接执行SQL命令，便捷进行数据查询与分析。
• Web UI集成：支持通过-ui参数启动内置Web UI，提供可视化操作界面（访问端口4213）。
• 跨平台兼容：适配Docker支持的各类操作系统（Linux、macOS、Windows），需配合Docker引擎运行。

3. 使用场景与适用范围

3.1 主要适用场景

• 本地数据分析：快速启动DuckDB实例，进行本地数据文件（CSV、Parquet等）的查询与分析。
• 开发与测试：为SQL脚本开发、数据处理逻辑验证提供隔离的数据库环境。
• 教学与演示：简化DuckDB入门门槛，无需复杂配置即可演示数据库功能。

3.2 适用人群

• 数据分析师、数据工程师
• 数据库开发与测试人员
• 需要轻量级SQL环境的开发者

4. 使用方法与部署示例

4.1 基础命令行交互模式

通过Docker直接启动DuckDB交互终端：

shell
docker run -it datacatering/duckdb:v1.4.0

参数说明：

• -i：保持标准输入打开，支持交互
• -t：分配伪终端，模拟终端环境

4.2 启动Web UI界面

通过-ui参数启动内置Web UI，支持浏览器访问：

shell
docker run --rm --net host -it datacatering/duckdb:v1.4.0 -ui

操作步骤：

1. 执行上述命令启动容器
2. 打开浏览器访问 http://localhost:4213 进入Web UI
3. 在UI中执行SQL查询、管理数据

参数说明：

• --rm：容器停止后自动删除，避免残留资源
• --net host：使用主机网络模式，确保容器内Web服务端口（4213）直接映射到主机
• -ui：启动Web UI服务

4.3 通过insta-infra工具启动

借助insta-infra工具链快速部署：

shell
# 克隆insta-infra仓库并进入目录（假设已完成前置配置）
./run.sh duckdb

注：insta-infra为数据工具快速部署脚本集合，具体使用需参考其***文档。

4.4 Docker Compose部署示例

创建docker-compose.yml文件，配置DuckDB服务：

yaml
version: '3.8'
services:
  duckdb:
    image: datacatering/duckdb:v1.4.0
    network_mode: "host"  # 启用主机网络以暴露UI端口
    tty: true             # 等效于`-t`参数
    stdin_open: true      # 等效于`-i`参数
    command: -ui          # 启动Web UI
    # 可选：挂载本地目录持久化数据（需创建./data目录）
    volumes:
      - ./data:/root/.duckdb

启动服务：

shell
docker-compose up

5. 配置参数说明

5.1 容器运行参数

5.2 镜像命令参数

6. 注意事项

1. Docker Desktop主机网络配置：
   在Docker Desktop（Windows/macOS）中使用--net host时，需确保已启用主机网络支持，具体配置参考Docker***文档。

2. 端口冲突处理：
   Web UI默认使用4213端口，若主机该端口被占用，需修改网络配置或停止占用进程。

3. 数据持久化：
   默认情况下，容器内数据存储于临时文件系统，若需持久化，需通过-v参数挂载本地目录（如-v ./duckdb_data:/root/.duckdb）。

4. 版本兼容性：
   示例中使用标签v1.4.0，实际部署时需根据需求指定DuckDB版本，可通过Docker Hub查看可用标签。

7. 参考链接

• 镜像源码仓库：data-catering/duckdb-docker
• DuckDB***文档：duckdb.org/docs
• insta-infra工具：data-catering/insta-infra