Chat2DB 5.3.8 配置参数详解

逐组实测 Chat2DB Community 5.3.8 服务端核心配置：内置 application.yml 关键项与 dev/release profile 端口差异（10825/11924 实测）、server.port 与 server.address 绑定行为、社区版加密密钥三种提供方式与缺失报错、MCP 端点开关（-D 不生效与 -- 参数生效对比）、外部配置文件覆盖、multipart/flyway/日志滚动/JVM 堆默认值与生产配置模板。

Chat2DBChat2DB数据库客户端AI2026/10/19

Chat2DB 5.3.8 配置参数详解

目标：逐组讲清并实测 Chat2DB Community 5.3.8 服务端（WEB 形态）的核心配置——内置 application.yml 关键项、profile 端口差异、绑定地址、社区版加密密钥、MCP 端点开关、外部配置文件覆盖与 JVM 内存。每组参数给出「含义 → 默认值 → 修改方式 → 实测效果回显」，全文回显均在 Ubuntu 22.04 + OpenJDK 17 环境实测取得。

一、环境信息

本章记录实测环境与配置基准。

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64），内核 6.8.0-138-generic；Java：OpenJDK 17.0.20.1。
  • 配置对象：Chat2DB Community 5.3.8 服务端 jar chat2db-community.jar（Spring Boot 3.5.13，内嵌 Tomcat 10.1.53），程序目录 /opt/chat2db/，构建与安装过程见 《Chat2DB 5.3.8 Ubuntu 22.04 安装指南》。
  • 配置基准文件：jar 内 BOOT-INF/classes/application.yml（主配置）、application-release.yml（release profile）、application-dev.yml（dev profile）。
  • 实测端口：10825（标准端口）、11924（release profile 默认值）、18080（外部配置覆盖验证）。
  • 日常运行/备份/排障操作见 《Chat2DB 日常运维手册》。

二、前置条件

参数实验前确认以下事项，避免改不生效或互相干扰。

2.1 查看内置配置原文

配置文件打包在 jar 内，用 unzip -p 直接读取（不落盘）：

unzip -p /opt/chat2db/chat2db-community.jar BOOT-INF/classes/application.yml

实测回显（全文，关键组）：

spring:
  application:
    name: chat2db
  # Default development profile.
  profiles:
    active: dev
  main:
    allow-bean-definition-overriding: true
    lazy-initialization: true
  messages:
    basename: i18n/messages
    encoding: UTF-8
    fallbackToSystemLocale: true
  jmx:
    enabled: false
  # thymeleaf
  thymeleaf:
    prefix: classpath:/thymeleaf/
    check-template-location: true
    suffix: .html
    servlet:
      content-type: text/html
    mode: HTML5
  # Static files.
  mvc:
    static-path-pattern: /static/**
  web:
    resources:
      static-locations[0]: classpath:/static/
  flyway:
    enabled: false
  # Database schema version management.
  servlet:
    multipart:
      max-file-size: -1
      max-request-size: -1
  jackson:
    serialization:
      write-dates-as-timestamps: true
  ai:
    mcp:
      server:
        request-timeout: 300s
        version: 1.0.0
        enabled: false
        stdio: false
        protocol: STREAMABLE
        sse-endpoint: /mcp
        name: chat2db
        instructions: >
          Chat2DB MCP tools can work with or without a selected datasource.
          ...

chat2db:
  version: 5.3.0

# Print the HTTP log
logbook:
  include:
    - /api/**

两个 profile 文件内容很短，实测：

unzip -p /opt/chat2db/chat2db-community.jar BOOT-INF/classes/application-release.yml
unzip -p /opt/chat2db/chat2db-community.jar BOOT-INF/classes/application-dev.yml

实测回显（release）：

# Server port.
server:
  port: 11924

实测回显（dev）：

# Server port.
server:
  port: 10825

💡 说明：application.yml 里 spring.profiles.active: dev 是源码开发用的默认；官方发行镜像与部署命令都显式传 -Dspring.profiles.active=release，以 release profile 运行。

2.2 参数注入方式与优先级

Chat2DB 服务端参数有三类注入方式，实测优先级从高到低：

方式位置示例适用
Spring 程序参数-jar 之后--server.port=10826临时覆盖、脚本启动
JVM 系统属性-jar 之前-Dserver.port=10826systemd/官方镜像标准用法
外部配置文件--spring.config.additional-location=file:...见 5.3 节批量配置、不改启动命令

⚠️ 注意：两类参数的位置不能放反。把 --xxx 写到 -jar 之前会被 JVM 当成自身选项而拒绝启动，实测回显：Unrecognized option: --spring.config.additional-location=... + Error: Could not create the Java Virtual Machine.（见 5.3 节）。官方镜像与本文标准启动命令统一用 -D 方式。

三、参数总览

按功能分组的核心参数速查（默认值均为 5.3.8 实测值）：

分组参数默认值作用
网络server.port10825（dev）/11924（release 配置文件值）HTTP 监听端口
网络server.address未设置（监听全部地址）绑定地址，官方启动命令显式 127.0.0.1 或 0.0.0.0
运行形态chat2db.mode—WEB（服务端） / DESKTOP（桌面端）
运行形态chat2db.runtime.modecommunity运行时版本线（社区版固定 community）
运行形态chat2db.gui—false 关闭 GUI（服务端必传）
网络chat2db.network.status—OFFLINE 离线模式（内网部署实测值）
安全chat2db.community.encryption-key-file~/.config/chat2db-community/encryption.key社区版 AES-256 密钥文件
安全chat2db.community.encryption-key / CHAT2DB_COMMUNITY_ENCRYPTION_KEY未设置内联密钥 / 环境变量（官方镜像用后者）
AI/MCPspring.ai.mcp.server.enabledfalseMCP 端点开关
AI/MCPspring.ai.mcp.server.sse-endpoint/mcpMCP 端点路径
数据spring.servlet.multipart.max-file-size-1（不限制）文件上传上限
数据spring.flyway.enabledfalse迁移工具开关
日志logback maxHistory/maxFileSize/totalSizeCap7 天/1GB/10GB日志滚动策略
JVM-Xms/-Xmx官方命令实测 256m/512m堆内存

关键差异解读：Chat2DB 的「默认端口」取决于 profile（dev 10825 / release 配置文件 11924），因此生产部署一律显式传 -Dserver.port=10825 与官方镜像对齐，不依赖隐含值。

四、网络与服务参数实测（server.*）

本组验证监听端口与绑定地址的真实行为。启动命令固定为标准形态（仅按实验需要增删参数）：

java -Xms256m -Xmx512m -Dloader.path=/opt/chat2db/lib -Dchat2db.gui=false \
  -Dchat2db.runtime.mode=community -Dchat2db.mode=WEB -Dchat2db.network.status=OFFLINE \
  -Dchat2db.community.encryption-key-file=/root/.config/chat2db-community/encryption.key \
  -Dspring.profiles.active=release -jar /opt/chat2db/chat2db-community.jar

4.1 release profile 不传 server.port：默认监听 11924

不传 -Dserver.port 时，release profile 配置文件的 server.port: 11924 生效：

实测回显：

Tomcat initialized with port 11924 (http)
Tomcat started on port 11924 (http) with context path '/'

ss -ltn | grep 11924

实测回显：

LISTEN 0      100                     *:11924            *:*

绑定 *:11924 说明此时未限制地址（全接口监听）。换一台机器实测外部可达：

curl -s -o /dev/null -w "%{http_code}\n" http://<服务器IP>:11924/

实测回显：

200

4.2 dev profile 不传 server.port：默认监听 10825 且仅本机

只把 profile 换成 dev，其余不传：

实测回显：

Tomcat initialized with port 10825 (http)

ss -ltn | grep 10825

实测回显：

LISTEN 0      100    [::ffff:127.0.0.1]:10825            *:*

dev 形态实测仅绑定 127.0.0.1（开发者本机自用语义），与 4.1 的全接口监听形成对照。

4.3 显式指定端口与地址（生产标准形态）

显式传参后日志回显：

Tomcat initialized with port 10825 (http)
Tomcat started on port 10825 (http) with context path '/'

-Dserver.address=0.0.0.0 时 ss 实测：

LISTEN 0      100                     *:10825            *:*

-Dserver.address=127.0.0.1 时 ss 实测：

LISTEN 0      100    [::ffff:127.0.0.1]:10825            *:*

结论：对内网多入口服务用 0.0.0.0（配合防火墙/反代），个人或跳板机场景用 127.0.0.1。社区版无登录体系，不建议把端口直接暴露给不受信网络。

4.4 端口被占用的失败形态

10825 已有实例时再启动第二个（同端口），进程退出并输出：

实测回显：

***************************
APPLICATION FAILED TO START
***************************

Description:

Web server failed to start. Port 10825 was already in use.

Action:

Identify and stop the process that's listening on port 10825 or configure this application to listen on another port.

处理：ss -ltnp | grep 10825 定位占用进程；多实例需求换端口启动即可。

五、安全与 AI 能力参数实测

本组验证社区版加密密钥与 MCP 端点开关——两者都是 5.3.8 社区版最常踩坑的参数。

5.1 社区版加密密钥（必需项）

社区版 5.3.x 强制要求 AES-256 密钥，三种提供方式（实测均有效，任选其一）：

方式参数/环境变量适用
密钥文件-Dchat2db.community.encryption-key-file=~/.config/chat2db-community/encryption.key主机部署标准方式
内联参数-Dchat2db.community.encryption-key=<base64密钥>临时验证
环境变量CHAT2DB_COMMUNITY_ENCRYPTION_KEY官方 Docker 镜像内置方式

密钥缺失时启动直接失败，实测回显（移走密钥文件后启动，退出码 1）：

Caused by: java.lang.IllegalStateException: Community encryption key is required. Configure chat2db.community.encryption-key or CHAT2DB_COMMUNITY_ENCRYPTION_KEY, or initialize /root/.config/chat2db-community/encryption.key
        at ai.chat2db.community.tools.security.CommunityEncryptionKeyStore.missingKey(CommunityEncryptionKeyStore.java:197)
        at ai.chat2db.community.tools.security.CommunityEncryptionKeyStore.resolve(CommunityEncryptionKeyStore.java:58)

密钥文件本体为 44 字符 base64（解码 32 字节）、权限 600，官方初始化脚本实测输出：

Community encryption key created: /root/.config/chat2db-community/encryption.key
decoded-bytes=32

⚠️ 注意：密钥重建后旧密钥加密的历史数据无法解密；密钥必须与数据目录一起纳入备份（见 《Chat2DB 日常运维手册》）。

5.2 MCP 端点开关（spring.ai.mcp.server.enabled）

默认 enabled: false。此时 POST /mcp 不落到 MCP 端点，而是被全局异常处理接住，实测回显：

No mapping for POST /mcp
{"success":false,"errorCode":"common.systemError","errorMessage":"common.systemError : no message.","errorDetail":null,"solutionLink":"https://github.com/chat2db/Chat2DB/wiki/Chat2DB","traceId":null}

开启后（注意：实测 -Dspring.ai.mcp.server.enabled=true 不生效，仍报 No mapping for POST /mcp；必须用 Spring 程序参数、写在 -jar 之后）：

java ... -jar /opt/chat2db/chat2db-community.jar --spring.ai.mcp.server.enabled=true

MCP 端点激活，用标准 JSON-RPC 初始化请求实测（Streamable HTTP 传输要求 Accept 头带 application/json, text/event-stream）：

curl -s -X POST -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"1.0.0","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  http://127.0.0.1:10825/mcp

实测回显（节选）：

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}},"serverInfo":{"name":"chat2db","version":"1.0.0"},"instructions":"Chat2DB MCP tools can work with or without a selected datasource. ..."}}

带会话 ID 列出工具（先从 initialize 响应头取 Mcp-Session-Id，再请求 tools/list）：

data:{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"list_all_datasources","description":"List available Chat2DB datasources. ..."},{"name":"text2sql","description":"Convert a natural language question into SQL using Chat2DB's internal AI. ..."}]}}

💡 技术拓展：MCP（Model Context Protocol）服务端传输方式不止本文开启的 Streamable HTTP——| 传输 | 特点 | 适用 | |---|---|---| | stdio | 标准输入输出管道，随客户端进程启动 | 本地桌面客户端内嵌调用 | | SSE | 服务端事件流（旧版 HTTP 传输） | 兼容旧客户端 | | Streamable HTTP | 单端点 JSON-RPC + 会话头，MCP 2025-06 规范 | 远程/服务端共享 |

Chat2DB 5.3.8 服务端配置实测为 protocol: STREAMABLE、stdio: false，即远程 MCP 共享形态。

5.3 外部配置文件覆盖（spring.config.additional-location）

不改启动命令、用外部文件覆盖端口（先建 /opt/chat2db/config/application.yml）：

server:
  port: 18080

启动命令（--spring.config.additional-location 放在 -jar 之后）：

java -Xms256m -Xmx512m -Dloader.path=/opt/chat2db/lib -Dchat2db.gui=false \
  -Dchat2db.runtime.mode=community -Dchat2db.mode=WEB -Dchat2db.network.status=OFFLINE \
  -Dchat2db.community.encryption-key-file=/root/.config/chat2db-community/encryption.key \
  -Dspring.profiles.active=release \
  -jar /opt/chat2db/chat2db-community.jar \
  --spring.config.additional-location=file:/opt/chat2db/config/application.yml

实测回显（外部配置覆盖了 release profile 的 11924）：

Tomcat initialized with port 18080 (http)
Tomcat started on port 18080 (http) with context path '/'

ss -ltn | grep 18080 && curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:18080/

实测回显：

LISTEN 0      100                *:18080            *:*
200

误把该参数放 -jar 之前的失败实测回显：

Unrecognized option: --spring.config.additional-location=file:/opt/chat2db/config/application.yml
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.

六、其余关键项说明（multipart / flyway / 日志 / JVM）

本组为确认默认行为与实测值的辅助项，一般无需修改。

  • spring.servlet.multipart.max-file-size: -1：上传大小不限制（导入大 SQL/备份文件用），默认值实测自内置配置原文。
  • spring.flyway.enabled: false：应用内置数据结构不走 Flyway 自动迁移，保持默认即可，避免升级时非预期改库。
  • 日志滚动：jar 内 logback-spring.xml 实测配置为按天+大小滚动（${LOG_FILE}.%d{yyyy-MM-dd}.%i.log），maxHistory=7 天、maxFileSize=1GB、totalSizeCap=10GB；运行日志落 ~/.chat2db-community/release/logs/（application.log 与 error.log）。
  • JVM 堆：标准启动命令 -Xms256m -Xmx512m。修改后用 jps -lv 验证生效：
jps -lv | grep chat2db

实测回显：

17 /opt/chat2db/chat2db-community.jar -Xms256m -Xmx512m -Dloader.path=/opt/chat2db/lib -Dchat2db.gui=false -Dchat2db.runtime.mode=community -Dchat2db.mode=WEB -Dchat2db.network.status=OFFLINE -Dchat2db.community.encryption-key-file=/root/.config/chat2db-community/encryption.key -Dserver.address=127.0.0.1 -Dserver.port=10825 -Dspring.profiles.active=release

七、生产配置模板

以下为 2C/4GB 内存、SSD 磁盘、内网部署的推荐启动配置（systemd ExecStart 形态，逐行含义见注释；服务托管完整 unit 文件见 《Chat2DB 5.3.8 Ubuntu 22.04 安装指南》第四章）：

/usr/bin/java -Xms256m -Xmx512m \
  -Dloader.path=/opt/chat2db/lib \
  -Dchat2db.gui=false \
  -Dchat2db.runtime.mode=community \
  -Dchat2db.mode=WEB \
  -Dchat2db.network.status=OFFLINE \
  -Dchat2db.community.encryption-key-file=/home/chat2db/.config/chat2db-community/encryption.key \
  -Dserver.address=127.0.0.1 \
  -Dserver.port=10825 \
  -Dspring.profiles.active=release \
  -jar /opt/chat2db/chat2db-community.jar

逐项说明：堆 256~512MB 覆盖单人/小团队使用（实测进程 RSS 约 490MB）；chat2db.gui=false 服务端关 GUI；runtime.mode=community 锁定社区版；mode=WEB 浏览器形态；network.status=OFFLINE 为内网实测值（外网 AI 能力按需调整）；密钥文件指向运行账号家目录；127.0.0.1 绑定 + 前置反代是最安全的暴露方式。16GB 以上内存多人共用场景可放宽 -Xmx1024m。

八、常见问题（FAQ）

Q1：改了 -Dserver.port 为什么还是 11924/10825？

先确认参数放在 -jar 之前（JVM 系统属性），且没有别的外部配置文件以更高优先级覆盖；再确认不是 profile 隐含值（release 配置文件默认 11924，见 4.1）。jps -lv 能看到进程实际参数，ss -ltn 能看到实际监听，两边对照即可定位。

Q2：MCP 端点 404 / 报 common.systemError？

spring.ai.mcp.server.enabled 默认 false；开启必须用 -- 程序参数放 -jar 之后（实测 -D 方式不生效）。POST 时必须带 Accept: application/json, text/event-stream 头，否则同样不进入 MCP 处理。

Q3：密钥文件权限/格式有什么要求？

官方脚本实测产出为 600 权限、44 字符 base64 单行（解码 32 字节）；文件存在但格式非法时脚本会拒绝覆盖并提示 Existing Community encryption key is invalid and was not overwritten。

Q4：哪些参数可以在 Docker 镜像上改？

官方镜像入口命令固定 0.0.0.0:10825，改端口/绑定地址需覆盖入口命令（--entrypoint java chat2db/chat2db:latest -Dloader.path=/app/lib ... -Dserver.port=10826 -jar /app/chat2db-community.jar），密钥用环境变量 CHAT2DB_COMMUNITY_ENCRYPTION_KEY 注入（镜像内置了默认值）。

九、参考链接