ChartDB 1.20.1 配置参数详解

目标：把 ChartDB 1.20.1 所有可配置项讲清楚——运行时环境变量（Docker 部署方式）、编译期变量（源码构建方式）、Vite 构建配置与 nginx 托管要点。全部条目经源码（v1.20.1 tag）与容器实测核对：环境变量经 entrypoint.sh 的 envsubst 渲染进 /config.js，实测注入生效；编译期 .env 由 Dockerfile 生成，实测构建产物 dist/config.js 为空文件（运行时由 nginx 动态返回）。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• ChartDB 版本与镜像：1.20.1（ghcr.io/chartdb/chartdb:1.20.1，官方镜像内置 nginx 静态托管）
• 源码构建环境：Ubuntu 22.04 + Node.js v24.22.0（Vite 7）
• 应用端口：容器内 80（nginx），宿主机映射 18090（http://localhost:18090/config.js）
• 依赖数据库：无（ChartDB 为纯前端应用，服务端不连数据库、不落盘业务数据）
• 数据卷路径：无业务数据卷（仅可选只读挂载 nginx override 配置文件）

二、配置体系总览

ChartDB 是纯前端应用，配置分三层，作用时机不同：

读取优先级：源码 src/lib/env.ts 中每个变量的读取逻辑都是「window.env.X（运行时）优先，回退 import.meta.env.VITE_X（编译期），再回退内置默认值」。因此 Docker 用户只需关心环境变量；源码构建用户只需关心 .env/构建参数；两种方式可以混用但运行时值会覆盖编译期值。

配置数据流（Docker 镜像实测路径）：

docker environment 变量
        ↓ 容器启动
/entrypoint.sh 执行 envsubst
        ↓ 渲染
/etc/nginx/conf.d/default.conf.template → /etc/nginx/conf.d/default.conf
        ↓ nginx 响应
GET /config.js → window.env = { OPENAI_API_KEY: "", ... }
        ↓ 前端加载
src/lib/env.ts 读取 window.env.X ?? VITE_X

三、运行时环境变量（Docker 部署）

镜像运行时读取且仅读取以下 5 个环境变量（entrypoint.sh 的 envsubst 白名单），在 docker run -e 或 Compose environment: 中设置：

3.1 OPENAI_API_KEY —— OpenAI API 密钥

• 类型：字符串，默认空
• 作用：AI 辅助导出 DDL（跨方言 SQL 导出）的鉴权密钥，走 OpenAI 官方 API
• 判定逻辑（源码 export-sql-script.ts 的 validateConfiguration）：baseUrl && modelName 都配置时走自定义端点（不要求 key）；否则要求 key；两者都没有时抛出错误 Configuration Error: Either provide an OpenAI API key or both a custom endpoint and model name
• 示例：OPENAI_API_KEY: "sk-proj-" 开头的 OpenAI 控制台密钥

3.2 OPENAI_API_ENDPOINT —— 自定义推理端点

• 类型：字符串（URL），默认空
• 作用：OpenAI 兼容协议的推理服务地址（vLLM、Ollama 的 OpenAI 兼容层、OneAPI 等均可），与 LLM_MODEL_NAME 成对使用
• 优先级：window.env.OPENAI_API_ENDPOINT ?? import.meta.env.VITE_OPENAI_API_ENDPOINT
• 示例：OPENAI_API_ENDPOINT: "http://192.168.1.50:8000/v1"（vLLM 部署地址）

3.3 LLM_MODEL_NAME —— 推理模型名

• 类型：字符串，默认空
• 作用：自定义端点使用的模型名；端点+模型名同时配置时不需要 OpenAI key
• 缺省回退：端点为空时（走 OpenAI 官方 API），模型名默认 gpt-4o-mini-2024-07-18（源码硬编码）
• 示例：LLM_MODEL_NAME: "qwen2.5-coder-32b-instruct"

3.4 HIDE_CHARTDB_CLOUD —— 关闭 Star Us 推广弹窗

• 类型：布尔字符串（"true"/"false"），默认空（视为 false）
• 作用：设为 "true" 后，编辑器页面跳过 GitHub Star 推广弹窗（Star Us dialog）——源码 editor-page.tsx 中 if (HIDE_CHARTDB_CLOUD) { return; } 直接短路弹窗定时器
• 判定：=== 'true' 严格相等才生效
• 实测：注入 "true" 后 /config.js 输出 HIDE_CHARTDB_CLOUD: "true"，弹窗不再出现

3.5 DISABLE_ANALYTICS —— 关闭匿名统计

• 类型：布尔字符串（"true"/"false"），默认空（视为 false）
• 作用：设为 "true" 后，页面（index.html 内联脚本）不加载 Fathom 统计脚本（https://cdn.usefathom.com/script.js，site id PRHIVBNN）；内网/隐私敏感环境推荐开启
• 判定：window.env.DISABLE_ANALYTICS === 'true'

3.6 运行时配置实测验证

修改环境变量后，无需重建镜像，直接验证注入结果：

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

实测输出（配置 HIDE_CHARTDB_CLOUD=true、DISABLE_ANALYTICS=true 时）：

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

⚠️ 注意：/config.js 是 nginx 对每个请求动态生成的响应（不是静态文件），修改环境变量并重建服务后立即生效；但浏览器可能缓存旧响应，配置变更后建议强刷（Ctrl+Shift+R）。

四、编译期变量（源码构建）

源码构建（npm run build）时，Vite 读取 .env 文件或 shell 环境变量中以下 VITE_ 前缀变量，把值内联进 JS bundle：

4.1 .env 文件机制

源码树中 public/config.js 是 0 字节占位文件（实测 wc -c 为 0），构建时原样拷贝到 dist/config.js——它不携带任何编译期配置，真正的运行时配置由 nginx 在请求 /config.js 时动态返回。因此：

• 官方镜像：所有配置走容器环境变量（第三节）；
• 源码构建直接托管 dist：/config.js 返回空对象（window.env = {}），AI 变量走 VITE_ 编译值或默认值，HIDE_CHARTDB_CLOUD/DISABLE_ANALYTICS 均不生效——需要运行时配置的，按第七节自行配置 nginx 的 /config.js 响应；
• 自建镜像：官方 Dockerfile 用 ARG 接收 5 个 VITE_ 变量并 echo 进 .env（实测 Dockerfile 第 17～21 行），再由 Vite 编译期内联。

4.2 自建镜像示例

把编译期配置打进自定义镜像（适用于想把 AI 端点固化到镜像内的场景）：

docker build \
  --build-arg VITE_HIDE_CHARTDB_CLOUD=true \
  --build-arg VITE_DISABLE_ANALYTICS=true \
  --build-arg VITE_OPENAI_API_ENDPOINT=http://192.168.1.50:8000/v1 \
  --build-arg VITE_LLM_MODEL_NAME=qwen2.5-coder-32b-instruct \
  -t chartdb-custom:1.20.1 .

⚠️ 注意：VITE_OPENAI_API_KEY 编译期内联后，任何能打开页面的人都可以在浏览器 DevTools 里读到该密钥。生产环境不要把真实 OpenAI key 编进镜像，改用运行时环境变量注入（但需注意 /config.js 响应对浏览器同样可见，AI 密钥本质上是「委托给前端」的配置，内网自建端点不携带敏感 key 是更安全的做法）。

五、Vite 构建配置

源码根目录 vite.config.ts 的关键配置（v1.20.1 实测原文）：

官方 package.json 的 scripts（实测）：

"scripts": {
    "dev": "vite --host",
    "build": "tsc -b && eslint src --fix && vite build",
    "lint": "eslint . --fix",
    "preview": "vite preview"
}

构建命令实测输出（Ubuntu 22.04 + Node.js 24.22.0）：

npm run build

✓ built in 49.51s

💡 说明：build 脚本包含 tsc -b（TypeScript 全量类型检查）与 eslint src --fix（自动修复风格问题）两个前置阶段，所以首次构建时间明显高于纯 vite build；若只想快速打包可运行 npx vite build（跳过类型检查，不推荐用于发布）。构建产物 dist/ 实测 84MB，其中 code-editor-DjxaV-BP.js（Monaco 编辑器）15.25MB（gzip 2.79MB）为最大块。

六、nginx 托管要点（镜像内置配置解析）

官方镜像的 nginx 配置模板 /etc/nginx/conf.d/default.conf.template 全文解析（v1.20.1 实测，整个模板仅含以下内容）：

server {
    listen       80;
    listen  [::]:80;

    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
            try_files  $uri $uri/ /index.html;
    }

    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\"
        };";
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

要点逐项说明：

⚠️ 实测注意：官方镜像的配置没有启用 gzip（实测请求 Accept-Encoding: gzip 仍返回未压缩的 Content-Length: 799710，无 Content-Encoding 头），也没有静态资源缓存头。最大 JS 块（Monaco 编辑器）原始 15MB，生产环境建议按《ChartDB 1.20.1 Ubuntu 22.04 安装指南》第七节的自托管配置补上 gzip_types 与 expires 7d（实测开启后主包 gzip 降至 2.8MB）。官方镜像未开 gzip 的原因推测是保持镜像极简，配置策略交给部署方。

6.1 /config.js 注入的等价配置

自托管 dist 并需要运行时 AI 配置时，在自己的 nginx 站点配置中加等价块（值手写死，不经 envsubst）：

location = /config.js {
    default_type application/javascript;
    return 200 "window.env = {
        OPENAI_API_KEY: '',
        OPENAI_API_ENDPOINT: 'http://192.168.1.50:8000/v1',
        LLM_MODEL_NAME: 'qwen2.5-coder-32b-instruct',
        HIDE_CHARTDB_CLOUD: 'true',
        DISABLE_ANALYTICS: 'true'
    };";
}

💡 说明：return 200 中的单引号字符串对 JS 合法（window.env = {...} 是对象字面量）；修改此块后 systemctl reload nginx 生效，无需重启。若不需要运行时配置（纯本地使用、无 AI），保留构建产物里自带的空 config.js 文件即可，无需此块。

6.2 挂载覆盖镜像配置

Compose 部署时想改镜像内 nginx 行为（如加 HTTPS 终结、改缓存策略），挂载只读覆盖：

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

⚠️ 注意：挂载后 entrypoint.sh 的 envsubst 渲染结果被覆盖，/config.js 的动态注入随之失效（nginx 会 404 或返回挂载文件里的静态内容），需按 6.1 节在 override 配置中手写 /config.js 块。index.html 里 <script src="/config.js"> 是硬引用，该路径必须可用，否则页面报 window.env is undefined 白屏。

6.3 index.html 的外部依赖

index.html 引用了两处外部资源，内网隔离环境需知悉：

• Google Fonts（fonts.googleapis.com，Raleway 字体）：加载失败时浏览器回退系统字体，功能不受影响；
• Fathom 统计（cdn.usefathom.com）：DISABLE_ANALYTICS: "true" 时不加载（第三节 3.5）。

七、常见问题（FAQ）

Q1：环境变量改了但页面行为没变？ 三层排查：① docker compose ps 确认服务已重建（改环境变量必须 docker compose up -d 重建，restart 不会重新渲染配置）；② curl -s http://<地址>/config.js 确认 nginx 返回了新值；③ 浏览器强刷（Ctrl+Shift+R）排除 /config.js 缓存。

Q2：AI 导出报 "Configuration Error: Either provide an OpenAI API key or both a custom endpoint and model name"？ 按 validateConfiguration 的规则二选一：只配 OPENAI_API_KEY（OpenAI 官方 API），或同时配置 OPENAI_API_ENDPOINT + LLM_MODEL_NAME（自建端点，此时不要求 key）。只配端点不配模型名视为无效配置。

Q3：同方言导出 SQL 也要配 AI 吗？ 不需要。源码 exportSQL 中同方言（目标方言 = 图表方言）直接走内置确定性转换器返回，不请求任何 AI 服务；AI 只在跨方言导出时介入。

Q4：源码构建部署后 HIDE_CHARTDB_CLOUD/DISABLE_ANALYTICS 不生效？ 这两个变量在源码构建场景必须在 构建前 以 .env 文件或 shell 环境变量形式提供（VITE_HIDE_CHARTDB_CLOUD=true npm run build），构建后无法更改（已内联）。需要运行时可变的，按 6.1 节给 nginx 加 /config.js 注入块。

Q5：/config.js 返回了旧值但 docker inspect 显示新环境变量已注入？ envsubst 只在服务启动时执行一次（entrypoint.sh）。如果服务没有重建（例如只 restart），环境变量渲染结果不会更新——docker compose up -d 重建即可。

八、参考链接

• ChartDB 官方仓库：https://github.com/chartdb/chartdb
• 镜像构建文件（Dockerfile/default.conf.template/entrypoint.sh）：https://github.com/chartdb/chartdb/tree/v1.20.1
• Vite 环境变量文档：https://vite.dev/guide/env-and-mode
• 相关文档：《ChartDB 1.20.1 Docker Compose 部署指南》《ChartDB 1.20.1 Ubuntu 22.04 安装指南》《ChartDB 1.20.1 进阶实战与运维》