ChartDB 1.20.1 Docker Compose 部署指南

使用 Docker Compose 一键部署 ChartDB 1.20.1 官方镜像，覆盖镜像选型、环境变量注入、端口映射与日志运维，实测固定 tag 1.20.1 拉取启动与 /config.js 注入生效。

ChartDBChartDBDockerDocker ComposeLinux2026/10/17

ChartDB 1.20.1 Docker Compose 部署指南

目标：用 Docker Compose 在单台服务器上部署 ChartDB 1.20.1 官方镜像，实现一键启停、环境变量注入与版本固定。本文全部命令与输出已在 Docker Engine 29.8.1 + Compose v5.5.1 环境实测通过，固定 tag 镜像（238MB）拉取即用，/config.js 环境变量注入验证生效。

一、环境信息

  • 操作系统：Ubuntu 22.04（x86_64）
  • Docker Engine：29.8.1
  • Docker Compose：v5.5.1（docker compose 插件形式）
  • ChartDB 镜像：ghcr.io/chartdb/chartdb:1.20.1（238MB，内含 nginx/1.28.3 静态托管）
  • 应用端口：容器内 80（nginx），宿主机映射 18090
  • Compose 工作目录：/opt/chartdb
  • 容器名：chartdb（由 compose 文件显式指定）

版本确认输出：

docker --version && docker compose version

Docker version 29.8.1, build 4a63305
Docker Compose version v5.5.1

💡 技术拓展：数据库图表/schema 可视化工具横向对比——

工具形态数据存储适用差异
ChartDB开源自托管 Web浏览器 IndexedDBSmart Query 反向工程、AI 导出、免账号
dbdiagram.io在线 SaaS云端DBML 文本驱动，免费版限制图表数
DrawSQL在线 SaaS云端协作团队协作向，闭源收费
DBeaver ER桌面客户端直连数据库实时逆向但不可离线分享

本文采用 ChartDB 官方 Docker 镜像部署，理由：镜像即开即用（内含 nginx 托管链）、无服务端状态、升级只需换 tag。

二、镜像选型说明

ChartDB 官方镜像发布在 GitHub Container Registry（ghcr.io），不在 Docker Hub。选型要点：

项目取值说明
镜像地址ghcr.io/chartdb/chartdb官方唯一发布渠道
推荐 tag1.20.1（当前最新）固定 tag 便于回滚与审计
不推荐 taglatest内容随上游漂移，生产环境不可控
镜像体积238MB两阶段构建产物（见下）
底座nginx:stable-alpine（nginx/1.28.3）构建期 node:24-alpine，运行期仅 nginx
对外端口80单一 HTTP 端口，无其他端口

镜像构建链：源码在 node:24-alpine 中执行 npm ci && npm run build，产物拷贝进 nginx:stable-alpine，由 entrypoint.sh 用 envsubst 把环境变量渲染进 nginx 配置。因此容器内没有数据库、没有持久化目录，是纯粹的无状态静态站点。

查询镜像当前可用 tag 的方法：ChartDB 发新版本后 tag 会同步到 ghcr.io，本文以实测时最新版 1.20.1 为准。当前 1.20.1 与 latest 指向同一镜像（digest sha256:9385f1a72174a2cdba27036127a98474a0c941c3c795dcc15149884c09834460，拉取 latest 时的实测返回），生产环境仍应固定写 1.20.1 以免疫受 latest 漂移影响。

确认镜像信息：

docker images ghcr.io/chartdb/chartdb

IMAGE                            ID             DISK USAGE   CONTENT SIZE   EXTRA
ghcr.io/chartdb/chartdb:1.20.1   9385f1a72174        238MB         84.1MB

三、前置条件

  1. 服务器已安装 Docker Engine 与 compose 插件（docker compose version 有输出即可，见第一节实测版本）。
  2. 服务器可访问 ghcr.io（拉取镜像）；国内网络拉取缓慢时配置镜像加速或 HTTP 代理。
  3. 宿主机 18090 端口未被占用（可自行更换，与 compose 文件保持一致即可）：
ss -tlnp | grep 18090 || echo "端口 18090 空闲"

端口 18090 空闲
  1. 创建 Compose 工作目录：
mkdir -p /opt/chartdb && cd /opt/chartdb

四、部署步骤

4.1 编写 Compose 文件

创建 /opt/chartdb/docker-compose.yml：

services:
  chartdb:
    image: ghcr.io/chartdb/chartdb:1.20.1
    container_name: chartdb
    restart: unless-stopped
    ports:
      - "18090:80"
    environment:
      OPENAI_API_KEY: ""
      OPENAI_API_ENDPOINT: ""
      LLM_MODEL_NAME: ""
      HIDE_CHARTDB_CLOUD: "true"
      DISABLE_ANALYTICS: "true"

逐项说明：

配置项取值说明
imageghcr.io/chartdb/chartdb:1.20.1固定版本 tag，生产环境禁用 latest
container_namechartdb显式容器名，便于 docker 命令定位
restartunless-stopped开机自启、异常退出自动拉起（手动 stop 除外）
ports18090:80宿主机 18090 → 容器 80（nginx），宿主端口可自行更换
environment5 个变量运行时注入，经 envsubst 渲染到 /config.js（见第七节）

4.2 启动服务

首次执行时 compose 会自动拉取 tag 对应的镜像，随后创建并启动容器：

docker compose up -d

实测输出：

 Container chartdb Created
 Container chartdb Starting
 Container chartdb Started

确认运行状态：

docker compose ps

NAME      IMAGE                            COMMAND            SERVICE   CREATED         STATUS         PORTS
chartdb   ghcr.io/chartdb/chartdb:1.20.1   "/entrypoint.sh"   chartdb   6 seconds ago   Up 4 seconds   0.0.0.0:18090->80/tcp, [::]:18090->80/tcp

4.3 验证服务

请求首页：

curl -sI http://localhost:18090/ | head -5

HTTP/1.1 200 OK
Server: nginx/1.28.3
Date: Sat, 17 Oct 2026 02:23:27 GMT
Content-Type: text/html
Content-Length: 2124

验证环境变量注入效果（/config.js 由 nginx 按环境变量动态生成，HIDE_CHARTDB_CLOUD 与 DISABLE_ANALYTICS 已变为 "true"）：

curl -s http://localhost:18090/config.js

window.env = {
            OPENAI_API_KEY: "",
            OPENAI_API_ENDPOINT: "",
            LLM_MODEL_NAME: "",
            HIDE_CHARTDB_CLOUD: "true",
            DISABLE_ANALYTICS: "true"
        };

确认页面标题：

curl -s http://localhost:18090/ | grep -oE '<title>[^<]*</title>'

<title>ChartDB - Create & Visualize Database Schema Diagrams</title>

浏览器访问 http://<服务器IP>:18090 即可使用。

五、数据持久化说明

ChartDB 容器是无状态应用，无需配置任何 volume。 用户数据（图表、导入的 schema、编辑历史）全部存储在使用者浏览器的 IndexedDB 中（前端通过 Dexie 库读写），服务端不落盘任何业务数据。这意味着：

  • 重建/升级容器不影响用户浏览器里的图表数据；
  • 用户清理浏览器数据 = 图表丢失，备份策略见《ChartDB 1.20.1 进阶实战与运维》篇；
  • 容器内唯一有意义的文件是 /etc/nginx/conf.d/default.conf（由 entrypoint.sh 每次启动从模板 + 环境变量渲染生成），无需挂载持久化。

如需自定义 nginx 行为（如加 HTTPS、改 gzip 策略），可挂载覆盖配置：

    volumes:
      - ./nginx-override.conf:/etc/nginx/conf.d/default.conf:ro

挂载后 entrypoint.sh 的 envsubst 渲染结果会被覆盖，/config.js 的动态注入随之失效，需在 override 配置中静态写死（见第九节 FAQ）。

六、环境变量表

镜像运行时支持以下 5 个环境变量（entrypoint.sh 用 envsubst 渲染进 nginx 配置的 /config.js 响应，前端加载后写入 window.env）：

环境变量默认值作用
OPENAI_API_KEY空OpenAI API 密钥，启用 AI 辅助导出 DDL 功能；留空则 AI 功能不可用
OPENAI_API_ENDPOINT空自定义推理端点（OpenAI 兼容协议，如 vLLM http://vllm:8000/v1）；与 LLM_MODEL_NAME 成对使用
LLM_MODEL_NAME空自定义推理模型名；端点+模型名同时配置时不需要 OpenAI key，两者均空则前端回退默认模型 gpt-4o-mini-2024-07-18（仍需 key）
HIDE_CHARTDB_CLOUD空设为 "true" 跳过编辑器里的 GitHub Star 推广弹窗（Star Us dialog），自托管环境推荐开启
DISABLE_ANALYTICS空设为 "true" 关闭 Fathom 匿名统计上报，内网环境推荐开启

⚠️ 注意：AI 配置二选一——要么只配 OPENAI_API_KEY（走 OpenAI 官方 API），要么配 OPENAI_API_ENDPOINT + LLM_MODEL_NAME（走自建/第三方推理服务），不要混用两种方式。

七、配置参数说明

7.1 环境变量如何生效

镜像内的 /entrypoint.sh 每次启动时执行 envsubst，把环境变量渲染进 nginx 配置模板：

docker exec chartdb sh -c 'cat /entrypoint.sh'

#!/bin/sh

# Replace placeholders in nginx.conf
envsubst '${OPENAI_API_KEY} ${OPENAI_API_ENDPOINT} ${LLM_MODEL_NAME} ${HIDE_CHARTDB_CLOUD} ${DISABLE_ANALYTICS}' < /etc/nginx/conf.d/default.conf.template > /etc/nginx/conf.d/default.conf

# Start Nginx
nginx -g "daemon off;"

nginx 配置模板中对 /config.js 的处理（环境变量最终落到这里）：

docker exec chartdb sh -c 'grep -A 8 "location /config.js" /etc/nginx/conf.d/default.conf'

    location /config.js {
        default_type application/javascript;
        return 200 "window.env = {
            OPENAI_API_KEY: \"$OPENAI_API_KEY\",
            OPENAI_API_ENDPOINT: \"$OPENAI_API_ENDPOINT\",
            LLM_MODEL_NAME: \"$LLM_MODEL_NAME\",
            HIDE_CHARTDB_CLOUD: \"$HIDE_CHARTDB_CLOUD\",
            DISABLE_ANALYTICS: \"$DISABLE_ANALYTICS\"
        };";
    }

前端读取顺序（源码 src/lib/env.ts）：window.env.X（即 /config.js 注入值）优先，回退构建期 VITE_* 编译值。因此修改环境变量只需改 compose 文件并重建容器，无需重新构建镜像。

7.2 修改环境变量后重建

修改 compose 文件中的 environment: 后，执行重建（compose 检测到配置差异会重建容器）：

docker compose up -d

实测输出（实测把 HIDE_CHARTDB_CLOUD 从 "true" 改为 "false" 后重建）：

 Container chartdb Starting
 Container chartdb Started

再次请求 /config.js 确认新值已生效（实测回显 HIDE_CHARTDB_CLOUD: "false"），改回 "true" 后同样方式重建即可。

八、常用运维命令

以下命令均在 /opt/chartdb（compose 文件所在目录）执行。

查看服务状态：

docker compose ps

查看实时日志（nginx 访问日志与启动日志）：

docker compose logs -f --tail 20

实测日志样例（nginx worker 启动与访问记录）：

chartdb  | 2026/10/17 02:23:23 [notice] 8#8: start worker process 19
chartdb  | 2026/10/17 02:23:23 [notice] 8#8: start worker process 20
chartdb  | 172.28.0.1 - - [17/Oct/2026:02:23:27 +0000] "GET /config.js HTTP/1.1" 200 204 "-" "curl/7.81.0" "-"

重启服务：

docker compose restart

实测输出：

 Container chartdb Restarting
 Container chartdb Started

停止并移除容器与网络：

docker compose down

实测输出：

 Container chartdb Stopping
 Container chartdb Stopped
 Container chartdb Removing
 Container chartdb Removed
 Network chartdb_default Removing
 Network chartdb_default Removed

再次启动（幂等操作，重建容器与网络）：

docker compose up -d

实测输出：

 Network chartdb_default Creating
 Network chartdb_default Created
 Container chartdb Creating
 Container chartdb Created
 Container chartdb Starting
 Container chartdb Started

查看镜像详情：

docker compose images

CONTAINER           REPOSITORY                TAG                 PLATFORM            IMAGE ID            SIZE                CREATED
chartdb             ghcr.io/chartdb/chartdb   1.20.1              linux/amd64         9385f1a72174        238MB               6 months ago

九、常见问题（FAQ）

Q1：镜像拉取超时或 ghcr.io 无法访问？ ghcr.io 在部分网络环境不稳定。为 Docker 守护进程配置 HTTP 代理（/etc/systemd/system/docker.service.d/http-proxy.conf 中设置 HTTPS_PROXY 后 systemctl daemon-reload && systemctl restart docker），或先在可联网机器 docker pull 后 docker save / docker load 离线迁移。

Q2：启动后访问 502/连接拒绝？ 确认映射端口正确（docker compose ps 的 PORTS 列）与防火墙放行；容器内 nginx 启动失败时 docker compose logs 会有 [emerg] 级错误日志，常见原因是挂载的 override 配置语法错误。

Q3：为什么浏览器里的图表换台电脑就没了？ 这是设计行为：ChartDB 数据存浏览器 IndexedDB，不随服务端同步。跨设备迁移用图表导出功能（Actions → Export as → JSON/DBML），在新设备导入即可。

Q4：如何启用 AI 辅助导出？ 在 compose 文件 environment 中配置 OPENAI_API_KEY（OpenAI 官方 API）或 OPENAI_API_ENDPOINT + LLM_MODEL_NAME（OpenAI 兼容自建推理，如 vLLM 部署 Qwen 模型），docker compose up -d 重建后生效。模型名缺省回退 gpt-4o-mini-2024-07-18。

Q5：升级到新版本怎么做？ 修改 compose 文件 image: 的 tag 为新版本号（如 1.21.0），执行 docker compose up -d 自动拉取新镜像并重建容器；回滚同理改回旧 tag。用户浏览器数据不受服务端升级影响。

十、参考链接