AI Agent 的数据库工具环境准备之 Chat2DB Local

环境：Rocky 10+ VNC  版本：chat2db-local-5.3.899-1.x86_64适用人群：需要在 Linux 服务器 桌面上跑 Chat2DB Local 的 DBA 和后端同学

一、启动脚本找错了 JDK 路径

装完 RPM 一敲启动命令：

Failed to find JVM in "/opt/chat2db-local/chat2db-local/lib/app/runtime" directory.

报错路径 lib/app/runtime/ —— 这个目录确实存在，但它只是应用自身的 runtime（chat2db-studio.jar、dist/、lib/），里面没有 bin/java。

真正包自带的 JDK 在隔壁目录：

ls /opt/chat2db-local/chat2db-local/lib/runtime/bin/java# 有输出 → ✓ 自带的 JRE，java/javac/jstack 一整套都在

修复其实就一句：在 wrapper 里把 JAVA_HOME 指定到正确的路径即可。

cd /opt/chat2db-local/chat2db-local/binsudocp"Chat2DB Local""Chat2DB Local.bak"sudomv"Chat2DB Local" chat2db-local

$ cat chat2dbstart.shexportJAVA_HOME=/opt/chat2db-local/chat2db-local/lib/runtime/binexportPATH=$JAVA_HOME/bin:$PATHHOME=/home/tangzhiang/chat2db-home /opt/chat2db-local/chat2db-local/bin/chat2db-local

sudochmod+x chat2dbstart.sh

二、JCEF / Chromium 误判"被另一台机器锁住"

JVM 通了，紧接着撞上第二道墙：

ERROR:process_singleton_posix.cc(353)] 其他计算机的另一个 Chromium 进程 (107678)好像正在使用此个人资料。Chromium 已锁定此个人资料以防止其受损。ERROR:main_runner.cc(261)] ContentMainRun failed with exit code 21JCEF_E: CefApp: N_Initialize failed.

有两层原因：

1. 上次 Chat2DB / JCEF 子进程异常退出，SingletonLock 锁文件残留

2. VNC / 云桌面共享 $HOME，Chromium 把当前主机名记作  qwenpaw 之类的，判定"另一台机器在占用 Profile"，拒绝启动

真正的锁目录不是~/.config/Chat2DB，而是：

~/.chat2db_local_edition/chat2db_cache_local/├── SingletonLock      ← 元凶├── SingletonCookie└── SingletonSocket

⚠️ 不要见 SingletonLock 就删。~/.local/share/browseract/ 和 ~/.copaw/workspaces/*/browser/user_data/ 下面也有 Singleton*，那是别的 agent 程序的 Chrome 实例在用，删了它们会崩。只删 Chat2DB 自己的那一份。

最稳的修法：清锁 + 用独立 HOME 启动，绕开主机名冲突：

# 1) 杀掉残留进程pkill -9-f Chat2DBpkill -9-f jcefpkill -9-f cef_helper# 2) 只删 Chat2DB 自己的锁rm-f ~/.chat2db_local_edition/chat2db_cache_local/Singleton*rm-f ~/.chat2db_local_edition/chat2db_cache_local/*/Singleton*# 3) 用独立 HOME 启动 wrappermkdir-p ~/chat2db-homeHOME=~/chat2db-home /opt/chat2db-local/chat2db-local/bin/

成功的话，日志里会出现：

Successfully acquired the instance lock.JCEF_I: CefApp: set state INITIALIZING

窗口弹出、左侧"数据源"能看见已配置的连接——恭喜，安装成功 🎉。

三、文件名带空格引发的 cfg 找不到

JVM 问题解决后，又会撞上第二个不那么显眼的小坑：

Error opening "/opt/chat2db-local/chat2db-local/lib/app/chat2db.cfg" file:No such file or directory

启动二进制原名是 Chat2DB Local（带空格），脚本内部按空格截取拼出了 chat2db.cfg 这个期望文件名，但实际 cfg 文件叫 Chat2DB Local.cfg。

既然第一个坑已经顺手改名为 chat2db-local，把 cfg 也跟着改就行：

cd /opt/chat2db-local/chat2db-local/lib/appsudo cp "Chat2DB Local.cfg" chat2db-local.cfg

完整安装 4 步走

把上面三道坑串起来，整个修复其实只有 4 步：

1）装 RPM

sudo dnf install -y ./chat2db-local-latest.rpm

2）改名 + 写 wrapper

cd /opt/chat2db-local/chat2db-local/binsudo cp "Chat2DB Local" "Chat2DB Local.bak"sudo mv  "Chat2DB Local" chat2db-localsudo tee chat2dbstart.sh > /dev/null <<'EOF'#!/usr/bin/env bashexport JAVA_HOME=/opt/chat2db-local/chat2db-local/lib/runtime/binexport PATH="$JAVA_HOME/bin:$PATH"exec "$(dirname "$0")/chat2db-local" "$@"EOFsudo chmod +x chat2dbstart.sh

3）生成cfg和清理 JCEF 锁

cd /opt/chat2db-local/chat2db-local/lib/appsudo cp "Chat2DB Local.cfg" chat2db-local.cfgpkill -9 -f Chat2DB; pkill -9 -f jcef; pkill -9 -f cef_helperrm -f ~/.chat2db_local_edition/chat2db_cache_local/Singleton*rm -f ~/.chat2db_local_edition/chat2db_cache_local/*/Singleton*

4）alias + 启动

cat >> ~/.bashrc <<'EOF'# Chat2DB Local：

alias chat2db-local='HOME=$HOME/chat2db-home /opt/chat2db-local/chat2db-local/bin/chat2dbstart.sh'EOFsource ~/.bashrc

# 以后在命令行输入chat2db-local 程序正常打开

关键路径速查

避坑清单

1. 「Failed to find JVM in .../runtime」 → RPM 自带 JRE，就在 lib/runtime/bin/。wrapper 里 export JAVA_HOME 指过去即可，不用装系统 Java，也不用 sed 二进制。

2. 「N_Initialize failed / 其他计算机 (openNebula)」 → 清 ~/.chat2db_local_edition/chat2db_cache_local/Singleton*，并用独立 HOME 启动。

3. 「Error opening .../chat2db.cfg」 → 二进制改名后，cfg 也要跟着改成 chat2db-local.cfg。

4. 「OpenJDK ... -Xverify:none was deprecated」 → JDK 13+ 废弃该参数，可忽略，不影响运行。

5. 误删 SingletonLock 让别的程序崩 → ~/.local/share/browseract/ 和 ~/.copaw/workspaces/*/browser/user_data/ 下的锁别动，只清 Chat2DB 自己那一份。

6. AppImage 能跑、RPM 不行 → AppImage 每次挂载到 /tmp/.mount_XXXXXX，JCEF 数据目录随挂载点变化无锁冲突；RPM 固定写到 ~/.chat2db_local_edition，异常退出留锁即必报错。

7. 「想用 sed 改 Chat2DB Local 的内容」 → 千万别这么干，它是编译好的 ELF，sed 会破坏文件结构。

8. 「找不到 bin/java 就以为没装 JRE」 → 别只看 lib/app/runtime/，要顺手 ls lib/runtime/bin/java —— 真正的 JRE 在那里。

四、内网环境的额外配置：让 Chat2DB 真正发挥 AI Agent 的威力

装好之后只是第一步。Chat2DB Local 在内网环境下的杀手锏是它能当桥——既给桌面端用，又能被 Claude Code / Cursor / Copaw 等 AI Agent 通过 MCP 调用，还能把数据源导给 SQLX CLI 让 Agent 直接跑 SQL。

1）配置自定义模型 API（接内网 LLM）

Chat2DB 自带 5 个国内模型（QWEN3.7_MAX、DeepSeek-V4-Pro、KIMI-K2.7、GLM-5、MiniMax-M2.7），但内网环境通常有自己的 LLM 网关，需要走「自定义模型」。

打开「模型下拉 → + 自定义模型」：

填好字段：

• 名称：自取，例如「公司内网 LLM」

• 提供方：选「OpenAI」（兼容 OpenAI 接口的都选这个）

• 模型：模型名，例如 qwen2.5-72b-instruct / deepseek-v3 / 内网网关定义的名字

• API Key：内网网关给你的 token

• Base URL：改成内网地址

http://10.x.x.x:8000/v1# 或者带路径http://llm-gateway.internal.company.com/openai/v1

2）启用 MCP HTTP 服务（让 Claude Code / Cursor 等调用）

AI Agent 想直接"问"你的数据库，最标准的接法是 MCP。Chat2DB 内置一个 MCP HTTP 服务，启用之后外部客户端就能连进来。

打开「设置 → 连接与服务 → MCP 服务」：

• 打开顶部开关

• 点「立即重启」

• 重启后下面会显示一个 MCP Token（被掩码），点「复制」

这个 Token 相当于 MCP 鉴权凭证，相当于 Chat2DB 给外部客户端开的"钥匙"。建议定期「重置 Token」轮换。

外部 MCP client 的配置：

{si"mcpServers": {"chat2db": {"type": "streamable-http","url": "http://127.0.0.1:11924/mcp","headers": {"X-Chat2DB-MCP-Token": " <你的 Token>"      }    }  }}

3）安装 SQLX CLI（让 AI Agent 直接跑 SQL）

光 MCP 还是"问"；要"动手"操作数据库（DDL、批量更新、跨库查询），需要 SQLX CLI——Chat2DB 官方出的面向 AI Agent 的数据库命令行工具。

打开「设置 → 连接与服务 → CLI 集成」：

页面里有三块信息：

• SQLX 版本：显示当前装的是不是最新

• 安装位置：~/.local/bin/sqlx

• 数据源导入：列表里是你在 Chat2DB 里配的所有数据源，"已导入"状态表示 SQLX 已经认得这个连接

首次用点「本地安装」，让 Chat2DB 自己把 sqlx 二进制下下来装好（无 sudo，落到 ~/.local/bin，确保 ~/.local/bin 在 $PATH 里）。

装好后勾选要导给 SQLX 的数据源，点「导入到 SQLX」。导入后 CLI 端就能直接用：

4）一键接到 Claude Code / Cursor

CLI 集成页面底部已经给出了 Claude Code 的安装命令：

# 装 SQLX 插件 + skillclaude plugin marketplace add OtterMind/sqlx@pluginsclaude plugin install sqlx@ottermind

装完重启 Claude Code，它会自动识别：

• MCP 上的 Chat2DB 工具 → 「问」数据库（schema 查询、SQL 生成、结果解释）

• SQLX CLI 工具 → 「动手」操作数据库（执行 DDL / DQL、批量任务）

AI Agent 这下就能在你的内网数据库上"问 + 做"了。

Cursor / Copaw / 其他 MCP 客户端的接入方式同理：把 MCP 配置写进 mcp.json 即可，URL 和 Token 从上面复制。

参考链接

https://chat2db-ai.com/

https://github.com/OtterMind/Chat2DB

https://github.com/OtterMind/sqlx

SQL界的“cursor”，让运维效率飞起