EDA 配置参数详解

目标：把 EDA（Edalitics）自托管实例涉及的全部配置面一次讲清——后端 API 配置文件、查询缓存调度、数据源连接参数、邮件告警、认证方式与 Web 反代——并给出可直接落地的生产配置模板。基于官方仓库 master 分支源码（eda/eda_api/config/）与 2026-10-30 实测镜像 jortilles/eda:latest 整理，涉及部署步骤的部分见《EDA Docker Compose 部署指南》。

一、环境信息

• 软件版本：EDA / Edalitics 最新稳定发布 edalitics-3.1.2（GitHub Releases，2026-08-10），本文实测镜像 jortilles/eda:latest（拉取日期 2026-10-30，前端 3.1.2 / 后端 API 3.2.0 开发版）
• 配置面构成：一体化单元内三组组件——后端 API（Node.js/Express，PM2 守护，内部端口 8666）、Web 层（Apache 2.4，对外 80）、元数据库（MongoDB 8.0）
• 源码依据：eda/eda_api/config/ 目录 15 个配置文件、eda/eda_api/lib/ 路由与连接器源码、eda/docker_run.sh 启动脚本、eda/000-default.conf Apache 站点配置
• 实测环境：Debian 12 / Docker 29.9.2，部署与验证过程见部署篇

二、前置条件

• 已按《EDA Docker Compose 部署指南》完成部署并能登录（本篇仅覆盖配置，不重复部署步骤）；
• 理解 EDA 的配置分层：镜像内配置文件（改后需重启服务）、MongoDB 元数据（界面操作即生效）、数据源级参数（每个数据源独立设置）三层，多数调优只涉及其中一层；
• 改镜像内文件的方式：docker exec -it eda-app bash 进入后用编辑器修改（服务单元内无 vi 时可 cp 出来改完再 docker cp 回去），改完 pm2 restart eda3 或重建服务实例生效。

三、参数查看与修改方式

EDA 的配置按生效层级分三类：

查看当前生效配置的常用命令：

# 列出全部后端配置文件
docker exec eda-app ls /eda/eda_api/config/

# 查看元数据库连接配置
docker exec eda-app cat /eda/eda_api/config/database.config.js

实测回显：

activedirectory.sample  ai.config.js  bbdd_orcl.js  cache.config.js  database.config.js
database.config.js.dist  eda_api_config.js  google-analytics.config.js  mailing.config.js
microsoft.config.js  oracle-config.js  SAMLconfig.js  seed.js  SMPT.config.json

module.exports = {
    url: "mongodb://localhost:27017/EDA"
}
;

⚠️ 注意：镜像内 database.config.js 的 url 值为 "xxxxx"（仓库工作目录版本），实际运行时由启动流程使用 .dist 模板值 mongodb://localhost:27017/EDA。如需外接 MongoDB（自建副本集），把 url 改为外接地址后 pm2 restart eda3。

四、参数总览

五、核心参数分类详解

5.1 元数据库连接（database.config.js）

module.exports = {
    url: "mongodb://localhost:27017/EDA"
};

• url：MongoDB 连接串，EDA 为库名。默认指向服务单元内的 MongoDB（docker_run.sh 以 --dbpath /eda/mongo/data 启动，仅监听本机 27017）。
• 什么时候改：官方镜像不提供"元数据库外置"的变量入口，若要接入自管 MongoDB 副本集（高可用元数据），唯一路径是改此文件。改后需 pm2 restart eda3，且新库必须先初始化管理员与角色组（初始化语句见部署篇 FAQ Q1），否则登录接口报 Incorrect user。
• 备份即备份 url 指向库的数据目录；默认形态下就是部署目录里的 eda-data/。

5.2 API 服务行为（eda_api_config.js）

module.exports = {
    null_value: '',
    cluster_workers: 4,
    authentication_type: {
      type: 'native',
      native: true,
      options: {
        authentication: "EDA",
        authorization: "EDA",
        elements: []
      }
    },
    maxStatementTime: 900,
    log_file: "XXXXXXXXXXXXXXXXXX",
    error_log_file: "XXXXXXXXXXXXXXXXXX"
  }

• null_value：查询结果中 NULL 值的屏幕显示占位（默认空字符串）。报表里空单元格显示什么由它决定，可改为 - 或 N/A。
• cluster_workers：Node.js cluster 模式的 worker 数，0 或缺省表示用满全部 CPU 核心。实测镜像默认 4。8 核机器上如需让出算力给源库，可调小；该参数只在以 cluster 模式启动时生效（package.json 的 start:cluster 脚本），默认 PM2 单进程形态下仅作参考。
• authentication_type：登录方式总开关，type: 'native' 表示本地 MongoDB 账号密码；改为 SAML/AD 时配合 5.6 的独立配置文件生效。
• maxStatementTime：单条源库查询的最大执行时长（秒），超时 kill。默认 900（15 分钟）。交互式看板建议下调到 60~300，防止失控查询拖垮源库；跑大屏定时刷新可保留大值。
• log_file / error_log_file：查询日志与错误日志的文件名占位（源码中为 XXXX 形态的占位值，需自行填真实文件名才会落盘），同时对应 API 的 admin/log-file、admin/log-error-file 读取端点。

5.3 查询结果缓存（cache.config.js + 数据源级开关）

缓存由"全局调度 + 数据源级开关"两层组成。全局配置（源码原文）：

const MS_PER_MINUTE = 60000;
const MINUTES = 7 * 24 * 60;

module.exports = {
  UPDATING_SCHEDULE: '1 * * * *',     // 每小时第 1 秒检查缓存刷新
  CLEANNING_SCHEDULE: '1 5 * * *',    // 每天 05:01 清理过期缓存
  MAX_MILIS_STORED: MINUTES * MS_PER_MINUTE,  // 缓存最长留存 7 天
  DEFAULT_CACHE_CONFIG: {             // 新建模型默认缓存策略：每天 06:00 刷新
    units: 'days', quantity: 1, hours: '06', minutes: '00', enabled: true,
  },
  MAX_STORED_ROWS : 5000              // 单个缓存结果最多存 5000 行
}

• UPDATING_SCHEDULE / CLEANNING_SCHEDULE：六段 cron（含秒位）。缓存刷新压力默认错峰在每小时第 1 秒与每天 5:01，源库忙时可整体后移。
• MAX_STORED_ROWS：超过 5000 行的查询结果不缓存——大结果集始终直查源库，这是"看板卡顿"的常见根因之一。
• 数据源级开关（在数据源参数里设置）：allowCache: 1 开启该数据源缓存、optimize: 0 关闭查询优化改写。开启后看板读缓存，可用 API 的 datasource/remove-cache/{id} 或仪表盘 clean-refresh 端点强制刷新（见《EDA API 使用详解》）。

5.4 数据源连接参数（Connection 模型）

每个数据源的连接参数在界面「数据源 → 新建」表单或 API add-data-source 中设置，完整字段（源码 connection.model.ts 与路由注释）：

⚠️ 注意：API 传参时 body 是裸连接对象，不要包一层 {"datasource":{...}}——实测包装后报 500 Cannot read properties of null (reading 'generateDataModel')。文件类数据（CSV/Excel）不填本表字段，走上传导入后由内置 DuckDB 引擎托管。

5.5 邮件与 KPI 告警（mailing.config.js / SMPT.config.json）

// mailing.config.js
module.exports = {
  server_baseURL: 'http://localhost:4200/',
  server_apiURL: 'http://localhost:8666',
  MAILING_SCHEDULE: '*/30 * * * *',   // 每 30 分钟扫描一次待发邮件
};

• server_baseURL：邮件正文里链接指向的访问地址。必须改成用户实际访问的 URL（如 https://bi.example.com/），否则收件人点开告警邮件里的仪表盘链接会指向 localhost。
• MAILING_SCHEDULE：邮件扫描周期，默认每 30 分钟；KPI 阈值告警与定时报表的实际发送延迟上限即此周期。
• SMPT.config.json（文件名即为 SMPT，源码原样）：SMTP 发件通道，支持 Gmail OAuth2（默认模板 configType: GMAIL）与普通账号密码（改 configType 后填 host/port/secure/auth.user/pass）。KPI 告警邮件附带图表截图，截图由镜像内置 Playwright Chromium 渲染——这也是镜像体积 7.4 GB 的主要原因之一。

5.6 认证与安全（seed.js / authentication_type / SSO 配置）

• seed.js：JWT 签名密钥，源码默认值 'que-haces-mirando-esto?'。生产必须替换为随机长字符串——默认密钥意味着任何知道源码的人可伪造登录态。改后所有已发 token 失效（含 API 调用），需重新登录。
• JWT 有效期固定 4 小时（源码 expiresIn: 14400，无配置项），到期重新登录即可。
• authentication_type.type：native（默认）/ SAML（SAMLconfig.js，含 auth/saml/* 五个端点：metadata、login、acs、logout、request-logout）/ Active Directory（activedirectory.sample 模板）/ Microsoft OAuth（microsoft.config.js）/ Google（auth/google/login 端点）。
• 角色组固定三个：EDA_ADMIN（管理员）、EDA_DATASOURCE_CREATOR（可建数据源）、EDA_RO（只读），存于 MongoDB groups 集合，界面「管理 → 组」维护。

5.7 AI 助手（ai.config.js）

module.exports = {
    PROVIDER: 'XXXX...', API_KEY: 'xxxx...', MODEL: 'xxxx...', CONTEXT: 'xxxx...',
    AWS_ACCESS_KEY: '...', AWS_SECRET_KEY: '...', AWS_REGION: '...',
    AVAILABLE: false, LIMIT: 200, MAX_LIMIT: 300,
    MAX_TOKENS: 5000, EDA_APP_URL: 'XXXX...', MCP_URL: 'XXXX...',
}

• AVAILABLE: false 默认关闭 AI 问数；启用需填 PROVIDER/API_KEY/MODEL（或 AWS Bedrock 三件套），CONTEXT 是喂给模型的业务语义说明。
• LIMIT/MAX_LIMIT：AI 返回行数上限（200/300），防大结果集撑爆上下文。
• 实例同时内置 MCP 端点（/ia/mcp，路由名 McpRouter），配置 MCP_URL/EDA_APP_URL 后可被外部 MCP 客户端调用问数。

5.8 前端 API 地址（eda_app/src/app/config/config.ts）

export const URL_SERVICES = 'http://localhost:8666';

前端构建期固定的 API 基址。官方镜像已经处理好这一层：镜像内前端编译产物调用的是相对路径 /edapi/，由 Apache 反代到本机 8666，所以默认部署无需改动；只有当你在反向代理（Nginx/Caddy）后面用非标准路径发布 EDA、且不走官方镜像前端时才需要重新构建前端。等价地，生产推荐把"改路径"问题留给反代层而不是前端。

5.9 Web 反代与监听端口（000-default.conf / docker_run.sh）

镜像内 Apache 站点配置（/eda/000-default.conf，启动时拷贝到 sites-available）：

<VirtualHost *:80>
	ServerAdmin webmaster@localhost
	DocumentRoot /var/www/html
	ProxyPass "/edapi/" "http://localhost:8666/"
	ProxyPassReverse "/edapi/" "http://localhost:8666/"
	ErrorLog ${APACHE_LOG_DIR}/error.log
	CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

• ProxyPass：/edapi/ 前缀反代到 API 8666；DocumentRoot 指向 Angular 编译产物 /var/www/html。对外只暴露 80 一个端口。
• 想改对外端口不需要动它：编排里改宿主端口映射即可（"8134:80" → "80:80"）；生产建议前置 Nginx/Caddy 做 TLS 终结，反代规则照抄这两行 ProxyPass 即可。
• 元数据库 mongod 的启动参数固定在 docker_run.sh：mongod --dbpath eda/mongo/data --fork --logpath eda/mongo/log，无独立配置文件；如需调整 WiredTiger 缓存等高级参数，同样只能改此脚本。

六、生产配置模板

以下模板面向「8 vCPU / 16 GB 内存 / NVMe SSD / 部门级 50 并发看板，源库为 MySQL 8.4」场景，改动集中在四个文件：

// 1) eda_api_config.js —— 查询保护与日志
module.exports = {
    null_value: '—',                 // 空值显示
    cluster_workers: 4,              // 保持默认
    authentication_type: { type: 'native', native: true,
      options: { authentication: "EDA", authorization: "EDA", elements: [] } },
    maxStatementTime: 300,           // 交互式看板 5 分钟封顶
    log_file: "query.log",           // 落盘查询日志
    error_log_file: "error.log"
}

// 2) seed.js —— 替换 JWT 密钥（openssl rand -hex 32 生成）
module.exports.SEED = '<随机 64 位十六进制串>';

// 3) mailing.config.js —— 告警邮件指向真实域名
module.exports = {
  server_baseURL: 'https://bi.example.com/',
  server_apiURL: 'http://localhost:8666',
  MAILING_SCHEDULE: '*/30 * * * *',
};

# 4) 编排增量 —— 时区与资源上限
services:
  eda:
    environment:
      - TZ=Asia/Shanghai
    deploy:
      resources:
        limits:
          memory: 8g     # 元库+API+Chromium 截图的余量上限

数据源侧配套：poolLimit: 20（50 并发看板 × 复用池）、高频看板的源 allowCache: 1 并将 UPDATING_SCHEDULE 保持错峰。内存观察用 pm2 monit（API 进程 RSS 正常 12 GB，Chromium 截图时瞬时 +300500 MB）。

七、常见问题（FAQ）

Q1：改了 seed.js 后所有用户掉线？

正常现象：JWT 密钥变更使全部已发 token 失效，重新登录即可。反过来这也是"怀疑 token 泄露时最彻底的处置手段"。

Q2：看板数据不是最新的？

检查三层：数据源 allowCache 是否开启（开启后读缓存）→ 缓存策略的刷新时点（默认每天 06:00）→ MAX_STORED_ROWS: 5000（大结果不缓存，反而是实时的）。强制刷新调 API datasource/remove-cache/{id}（带缓存的数据源 ID 可用 datasource/names 查，见《EDA API 使用详解》）。

Q3：maxStatementTime 调小后大报表失败？

报错来自源库侧查询被 kill（如 MySQL 的 max_execution_time 语义）。两个值要一起看：EDA 侧 maxStatementTime 与源库自身超时参数，前者应 ≤ 后者，且定时刷新类看板单独保留长时限。

Q4：告警邮件发不出来？

按序检查：SMPT.config.json 凭证与 configType 是否匹配（Gmail OAuth2 需要 refreshToken，普通 SMTP 改 configType 后用账号密码）；MAILING_SCHEDULE 周期内服务未重启过；镜像内 Chromium 可用（截图失败会阻断发送）。

Q5：改配置文件后没生效？

分清两层：API 层配置（config/*.js）要 pm2 restart eda3；Apache 层（站点配置）要 service apache2 restart。重建服务实例后镜像内改动全部丢失——持久化自定义配置的办法是把改好的文件纳入部署目录并在编排里 bind mount 覆盖对应路径（如 ./config/eda_api_config.js:/eda/eda_api/config/eda_api_config.js）。

八、参考链接

• 配置源码目录：https://github.com/jortilles/EDA/tree/master/eda/eda_api/config
• 官方文档站（含建模与报表教程）：http://doc.edalitics.com
• 仓库 README（镜像与默认凭证）：https://github.com/jortilles/EDA
• 站内延伸阅读：《EDA 介绍与选型指南》、《EDA Docker Compose 部署指南》、《EDA API 使用详解》、《MySQL 8 配置参数详解》