Chartbrew 6.0.0 配置参数详解

目标：把 Chartbrew 6.0.0 的全部 .env 配置族讲透——每个参数管什么、默认值多少、改完怎样生效，关键开关（注册限制、Data API、队列面板、运行时缓存调试、API 端口等）均给出实测回显。实测环境为 Ubuntu 26.04.1 LTS 服务器上 /opt/chartbrew 部署的 Chartbrew 6.0.0（Node v22.23.4，元数据库 MySQL 8.4.13，Redis 7.4.12）。安装过程见 《Chartbrew Docker Compose 部署指南》。

一、环境信息

• 应用：Chartbrew 6.0.0，安装目录 /opt/chartbrew（server/ 后端、client/ 前端）
• 配置文件：/opt/chartbrew/.env（仓库自带模板 /opt/chartbrew/.env-template，共 90 余行、约 60 个可配参数）
• 运行时：Node v22.23.4 / npm 10.9.9；后端 server/index.js，前端构建产物 client/dist
• 依赖服务：MySQL 8.4.13（192.168.1.200:3306，库名 chartbrew，63 张表）、Redis 7.4.12（6379，AOF 开）
• 端点：后端 API 默认 0.0.0.0:4019，前端静态服务默认 4018（对外经 8129 提供）
• 演示账号：admin@quzuo.net / q1w2e3r4

二、前置条件

1. 已按部署篇完成 Chartbrew 6.0.0 安装且服务正常（curl -s -o /dev/null -w "%{http_code}" http://192.168.1.200:8129/ 返回 200）；
2. 具备 /opt/chartbrew/.env 的读写权限；
3. 改参数前备份：cp /opt/chartbrew/.env /opt/chartbrew/.env.bak-$(date +%F)。

三、参数查看与修改方式

3.1 配置加载机制（源码实测）

后端入口 server/index.js 第 1、7 行注释与代码点明顺序——先补密钥，后载 .env：

// set up the encryption keys first, then load .env file
require("dotenv").config({ path: path.join(__dirname, "..", ".env") });

两个关键语义：

1. dotenv 不覆盖已存在的进程环境变量——同名参数以进程环境变量（如 systemd 的 Environment=、shell 前缀 KEY=val node index.js）优先，.env 文件兜底；
2. 加载前 server/modules/setUpEncryptionKeys.js 会检查 .env 中 CB_ENCRYPTION_KEY、CB_BULLMQ_USERNAME、CB_BULLMQ_PASSWORD 三项，为空则自动生成/补写并落盘，启动日志打印 Set up CB_ENCRYPTION_KEY 等行。

参数值的消费点集中在 server/settings.js，直接映射 process.env：

module.exports = {
  port: process.env.CB_API_PORT,
  secret: process.env.CB_SECRET,
  encryptionKey: process.env.CB_ENCRYPTION_KEY,
  client: process.env.VITE_APP_CLIENT_HOST,
  api: process.env.CB_API_HOST,
  ...
  teamRestricted: process.env.CB_RESTRICT_TEAMS,
  signupRestricted: process.env.CB_RESTRICT_SIGNUP,
};

3.2 查看当前生效值

# 文件层
grep -vE '^#|^$' /opt/chartbrew/.env | head -20
# 进程层（示例：查 API 端口最终值）
node -e "require('dotenv').config({path:'/opt/chartbrew/.env'});console.log(process.env.PORT||process.env.CB_API_PORT||4019)"
4019

3.3 修改与生效方式

四、参数总览

按功能域分组的全量清单（默认值取自 .env-template 与源码；★ 为本篇实测覆盖项）：

五、核心参数分类详解

5.1 元数据库连接（CB_DB_*）

CB_DB_DIALECT 只接受 mysql 或 postgres；主机/端口/库名/账号四项构成 Sequelize 连接串。TLS 三件套（CB_DB_SSL、CB_DB_SSL_CERT、CB_DB_SSL_KEY）用于云端数据库强制加密场景，默认空即明文连接。注意 CB_DB_* 只管元数据库；报表要查的业务库连接是在 Web 界面里建「Connection」对象存的（其密码用 CB_ENCRYPTION_KEY 加密后写入元数据库，见 5.3）。

5.2 Redis 与运行时缓存（CB_REDIS_* / CB_RUNTIME_*）

CB_REDIS_HOST/PORT/PASSWORD 同时服务三件事：BullMQ 队列、Socket.IO 跨进程广播、运行时查询缓存。CB_RUNTIME_REDIS_* 可把查询缓存指到另一个 Redis 实例（默认回落 CB_REDIS_*）。开 CB_RUNTIME_CACHE_DEBUG=true 重启后，启动日志直接吐出生效的缓存后端与 TTL 配置（实测回显）：

[runtime-cache] using Redis via CB_REDIS settings
[runtime-cache][initialized] {
  backend: 'redis',
  envPrefix: 'CB_REDIS',
  config: {
    cacheSchemaVersion: '1',
    chartCacheTtlMs: 300000,
    chartCacheStaleTtlMs: 900000,
    sourceCacheTtlMs: 120000,
    sourceCacheStaleTtlMs: 600000,

CB_PREPARED_SNAPSHOT_MAX_BYTES（默认 5242880=5 MB）限制单个 PreparedData 快照的持久化体积，超限不截断直接不存。

5.3 安全密钥（CB_ENCRYPTION_KEY / CB_SECRET）

• CB_ENCRYPTION_KEY：32 字节 hex（AES-256），加密元数据库内所有业务库连接凭证。留空时启动自动生 成并写回 .env（日志 Set up CB_ENCRYPTION_KEY）；手工生成命令实测：

$ node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
f7d6561495627feacf9eb08c939a70f1ab27500f95ddec802366a84e3cce85de

• CB_SECRET：v5 及更早的遗留密钥，仅用于解密旧数据；
• CB_ALLOW_LEGACY_SHARE_TOKENS（默认 0）：分享 token 的旧签名兼容开关，新装保持 0。

⚠️ 注意：CB_ENCRYPTION_KEY 丢失 = 元数据库里所有数据源密码不可恢复（只能逐个重建连接）。它必须与数据库备份同批、但分渠道保管。

5.4 服务端点（CB_API_HOST / CB_API_PORT / PORT）

监听地址与端口。端口优先级实测（index.js:142：process.env.PORT || app.settings.port || 4019）：

$ CB_API_PORT=4031 CB_REDIS_HOST=redis CB_DB_HOST=db NODE_ENV=production node index.js &
...
Running server on port 4031

CB_API_HOST 默认 localhost——对外提供服务（或经反向代理穿透）必须改 0.0.0.0，否则 API 只绑回环。

5.5 前端构建期参数（VITE_APP_*）

VITE_APP_CLIENT_HOST（前端自身地址）、VITE_APP_API_HOST（API 地址）、VITE_APP_CLIENT_PORT（静态服务端口）在 client/src/config/settings.js 经 import.meta.env 读取，构建时烘焙进产物。实测把 VITE_APP_CLIENT_HOST=http://cb-demo.local:8129 后重建前端：

$ cd /opt/chartbrew/client && npm run build
...
✓ built in 3.96s
$ grep -rl "cb-demo.local" dist/ | head -3
dist/assets/index-BDc1p-O1.js
dist/assets/jsx-runtime-DM392EkQ.js

结论：换域名/换端口属于「改配置 + 重建前端」双动作，只改 .env 不重建，页面仍跳旧地址。运行实例的 dist 里烘焙的是 192.168.1.200:8129 与 192.168.1.200:4019（grep 命中多个 chunk 文件），与 .env 声明一致。

5.6 注册与团队限制（CB_RESTRICT_SIGNUP / CB_RESTRICT_TEAMS）

CB_RESTRICT_SIGNUP=1 后，已有用户时开放注册被拦（UserRoute.js 判 app.settings.signupRestricted === "1"，实测回显）：

$ CB_RESTRICT_SIGNUP=1 CB_API_PORT=4031 NODE_ENV=production node index.js &
$ curl -s -X POST http://127.0.0.1:4031/user -H 'Content-Type: application/json' \
  -d '{"email":"test9@quzuo.net","password":"q1w2e3r4","name":"T U"}'
Signups are restricted        # HTTP 401

对照实验：同请求打到未开限制的实例（4019）返回 200 并建出用户 {"id":3,...}。CB_RESTRICT_TEAMS=1 则禁止用户自建团队、只能被邀请入队——多租户治理两件套，装完第一个管理员后立刻开。

5.7 队列面板与调试（CB_BULLMQ_* / CB_QUEUE_*）

/apps/queues（Bull Board，8 条队列的任务看板）用 HTTP Basic 保护，bullBoardAuth.js 以 sha256+timingSafeEqual 比对 CB_BULLMQ_USERNAME/PASSWORD（实测）：

$ curl -s -o /dev/null -w "%{http_code}\n" http://192.168.1.200:4019/apps/queues
401
$ curl -s -o /dev/null -w "%{http_code}\n" -u chartbrew:q1w2e3r4 http://192.168.1.200:4019/apps/queues
200
$ curl -s -o /dev/null -w "%{http_code}\n" -u chartbrew:wrongpass http://192.168.1.200:4019/apps/queues
401

两项行为细节（源码+实测）：面板只由主实例挂载（cluster 多进程时 NODE_APP_INSTANCE 为 0 或未设的进程才调 setUpQueues，从实例上访问返回 404）；凭据未配置时返回 503 BullMQ dashboard credentials are not configured（bullBoardAuth.js:21）。CB_QUEUE_DEBUG=1 打开队列逐事件调试日志；CB_QUEUE_LOCK_DURATION_MS（默认 900000）/CB_QUEUE_LOCK_RENEW_TIME_MS（默认 60000，实际取二者一半封顶）控制任务锁，长查询被误判卡死时调大前者。

5.8 Data API 与 MCP（CB_DATA_API_ENABLED / CB_MCP_PUBLIC_URL）

Data API（/api/v1/...，API Key 鉴权）默认开启，DataApiRoute.js:17 判定 process.env.CB_DATA_API_ENABLED !== "false"。实测对照（同一数据集端点）：

# 默认（开）：路由在、缺 Key → 401
$ curl -s -H 'Accept: application/json' http://192.168.1.200:4019/api/v1/teams/1/datasets/1/data
{"error":{"code":"API_KEY_REQUIRED","message":"A valid API key is required.","requestId":"..."}}   # 401

# CB_DATA_API_ENABLED=false 的实例（4031）：整组路由不挂 → 404
$ curl -s -H 'Accept: application/json' http://127.0.0.1:4031/api/v1/teams/1/datasets/1/data
{"error":{"code":"RESOURCE_NOT_FOUND","message":"The requested resource was not found.","requestId":"..."}}   # 404

CB_MCP_PUBLIC_URL 覆盖 MCP 端点对外 URL（modules/mcp/oauth.js:28）。生产模式下端点被强制校验「https 且以 /mcp 结尾」（oauth.js:43 抛 MCP requires a public HTTPS URL ending in /mcp），http 明文部署需显式指定该变量绕过推导，详见部署篇常见问题 11.1。

5.9 数据集智能画像（CB_DATASET_INTELLIGENCE_*）

v6 新特性「数据集画像」的参数组（模板默认值）：ENABLED=true 总开关；AUTO_PROFILE=true 新数据集自动画像；PROFILE_TTL_HOURS=168 画像 7 天过期；MAX_SAMPLE_ROWS=200/MAX_FIELDS=200 采样上限；LLM_ENRICHMENT=false 是否用大模型补充语义描述；BACKFILL_BATCH_SIZE=25 存量回填批大小（回填命令见运维实操篇）。

5.10 观测与异常检测（CB_OBSERVATIONS_*）

观测子系统阈值组：ENABLED=true 总开关；AUTO_MONITOR_CHARTS=false 不自动监控全部图表；MINIMUM_SAMPLES=7 最少样本数；PUBLISH_SCORE=0.75 与 MINIMUM_RELATIVE_CHANGE=0.1、MINIMUM_PERCENTAGE_POINT_CHANGE=1 共同决定一条「观测」是否发布；LLM_AUDIT_MODE=off 大模型审计默认影子关闭。审计结果可用 observations:audit-report 脚本导出（运维实操篇有实测回显）。

5.11 数据保留期（*_RETENTION_DAYS 族）

7 个保留期参数控制后台清理（默认：更新审计 30 天、失败审计 90 天、指标快照 90 天、评估 730 天、汇总 730 天、已解决观测 365 天、观测审计 90 天；批次 CB_DATA_RETENTION_BATCH_SIZE=1000、超时 CB_DATA_RETENTION_MAX_RUNTIME_SECONDS=300；置 0 关闭该类清理）。保留期语义可在清理脚本回显里直接验证——cutoff 恰为「当前时间 − 30 天」：

$ npm run retention:run
...
  "workspaceLearning": {
    "actionAudits": {
      "cutoff": "2025-11-02T23:15:32.316Z",     # 2026-11-02 执行，即默认 30 天
      "matched": 0,

5.12 出网安全策略（CB_ALLOW_PRIVATE_NETWORK_CALLS）

默认 false：REST API 类数据源/告警回调不允许指向内网地址（SSRF 防护，outboundTargetPolicy 判定）。确需让 Chartbrew 查询内网 API 时置 true，属安全换功能的开关，生产环境建议保持默认并走白名单网关。

5.13 邮件与第三方集成（CB_MAIL_* / CB_GOOGLE_* / SLACK）

CB_MAIL_HOST/PORT/SECURE/USER/PASS 构成 nodemailer SMTP 配置（默认 smtp.gmail.com:465 secure），CB_ADMIN_MAIL 为发件人显示地址；邮件用于邀请、找回密码与快照报表。Google OAuth（CB_GOOGLE_CLIENT_ID/SECRET）与 Slack（VITE_APP_SLACK_CLIENT_ID 前端 + CB_SLACK_CLIENT_SECRET/SIGNING_SECRET 后端）留空即关闭对应集成。CB_OPENAI_API_KEY 为空时 AI 功能（Chart Studio/画像 LLM 增强）自动降级为不可用，传统 BI 功能不受影响。

六、生产配置模板

适用画像：16 GB 内存、NVMe SSD、50 人以内分析团队、元数据库与应用同机或独立 MySQL。在部署篇 .env 基础上，生产还应显式落定：

# /opt/chartbrew/.env（生产增量项）
CB_DB_HOST=10.0.1.21            # 独立元数据库主机
CB_DB_SSL=1                     # 跨主机强制 TLS
CB_REDIS_HOST=10.0.1.22
CB_ENCRYPTION_KEY=<离线保管的32字节hex>   # 严禁留空靠自动生成
CB_API_HOST=0.0.0.0
CB_API_PORT=4019
VITE_APP_CLIENT_HOST=https://bi.example.com
VITE_APP_API_HOST=https://bi-api.example.com
CB_RESTRICT_SIGNUP=1            # 首管建好后立即关闭开放注册
CB_RESTRICT_TEAMS=1
CB_BULLMQ_USERNAME=ops
CB_BULLMQ_PASSWORD=<强随机>
CB_DATA_API_ENABLED=true
CB_ALLOW_PRIVATE_NETWORK_CALLS=false
CB_MAIL_HOST=smtp.example.com
CB_ADMIN_MAIL=bi@example.com
CB_UPDATE_AUDIT_RETENTION_DAYS=30
CB_OBSERVATION_AUDIT_RETENTION_DAYS=90

要点：VITE_APP_* 改域名后必须重建前端；CB_ENCRYPTION_KEY 换值等于销毁全部数据源凭证；改任何 CB_* 后重启后端进程生效。

七、常见问题

7.1 改了 .env 不生效

先分清参数层：VITE_APP_* 要重建前端（5.5），CB_* 要重启后端进程；再确认没有更高层的同名进程环境变量压过文件值（dotenv 不覆盖既有环境变量，shell/systemd 里残留的旧 export 是常见元凶，env | grep CB_ 排查）。

7.2 队列面板 404 而不是 401

该实例没有挂载面板：要么访问到了 cluster 的非主实例（NODE_APP_INSTANCE≠0，5.7），要么该进程连不上 Redis 导致队列初始化失败（启动日志有 ECONNREFUSED）。主实例 + Redis 可达时未带凭据访问必是 401。

7.3 忘记 CB_ENCRYPTION_KEY

无法找回（密文不可逆）。处置：在界面逐个重建数据源连接后，把新密钥与 .env 一起纳入备份；若从备份恢复旧 .env + 旧库快照，密钥与数据必须配套。

7.4 想临时关 Data API 但 401 变 404 让监控误报

属预期语义（5.8）：关闭后路由整体不挂载。监控拨测应断言「开启态=401/200，关闭态=404」两态，而非一律 401。

八、参考链接

• 官方环境变量文档：https://docs.chartbrew.com/deployment/environment-variables
• 官方配置模板：/opt/chartbrew/.env-template（仓库根同名文件）
• 平台内相关篇：《Chartbrew 介绍与选型指南》、《Chartbrew Docker Compose 部署指南》、《Chartbrew 6.0.0 常用 CLI 命令与运维实操》