README_CN.md

July 15, 2026 · View on GitHub

Chat2DB 团队新开源项目：youClaw

如果 Chat2DB 对你有帮助，也欢迎顺手给 youClaw 点个 Star。对一个新开源项目来说，早期 Star 不只是鼓励，也能带来更多曝光、反馈和贡献者。

https://github.com/user-attachments/assets/3c857883-8153-4bda-92b8-d25c6adb5b13

Chat2DB 是一个智能的通用SQL客户端和数据报表工具，它集成了AI的能力。Chat2DB可以帮助您更快地编写SQL查询、管理数据库、生成报告、探索数据、并且可以与多种数据库进行交互。Chat2DB是一个开源项目，我们欢迎您的贡献。

1. 智能生成SQL: Chat2DB Pro支持AI驱动的智能SQL开发，可以帮助您更快地编写SQL查询。

2. 数据库管理: 支持多种10+数据库，包括MySQL、PostgreSQL、H2、Oracle、SQLServer、SQLite、MariaDB、ClickHouse、DM、Presto、DB2、OceanBase、Hive、KingBase、MongoDB、Redis、Snowflake等。

3. 智能生成报表: Chat2DB Pro支持AI驱动的智能数据报表，可以帮助您更快地生成看板。

4. 数据结构同步: Chat2DB Pro支持数据库表结构同步，可以帮助您更快地同步数据库表结构。

功能比较

Community、Pro 和 Enterprise 共享同一套数据库客户端基础能力。商业版本是在这一基础上增加官方 AI、云端存储、多设备访问、协作和治理能力，而不是提供另一套数据库内核。

功能点	Community 社区版	Pro 在线个人版	Enterprise 企业版
数据源连接与凭证管理	✅	✅	✅
数据库插件与元数据浏览	✅	✅	✅
SQL 编辑、补全、格式化与执行	✅	✅	✅
DDL/DML、对象管理与数据编辑	✅	✅	✅
数据导入导出	✅	✅	✅
SQL 收藏、历史记录与任务	✅	✅	✅
Dashboard 与 Chart	✅	✅	✅
CLI 与 MCP	✅	✅	✅
自定义 AI 模型	✅	✅	✅
Chat2DB 官方 AI 与预置模型	❌	✅	✅
官方 AI 额度与云端聊天历史	❌	✅	✅
Chat2DB 账号	❌	✅	✅
云端存储与多设备	❌	✅	✅
团队数据源与共享资产	❌	❌	✅
成员与角色	❌	❌	✅
权限、审批与审计	❌	❌	✅
组织数据上下文与 RAG	❌	❌	✅

下载安装

Chat2DB 是一个跨平台的应用程序，支持Windows、MacOS和Linux。您可以从以下链接下载Chat2DB。

社区版安全边界

Warning

Chat2DB Community 是单用户、本机优先的应用，不提供用户账号、租户隔离或多用户之间的权限边界。HTTP 服务必须绑定到 127.0.0.1 或 ::1，不要直接暴露给其他用户或不可信网络。

自定义 JDBC Driver 是可执行 Java 代码，只应安装来自可信来源的驱动。导入的配置文件、压缩包、SQL 文件、数据库内容和 AI 响应仍属于不可信数据。完整信任边界和漏洞报告流程请参阅安全策略。

社区版 Docker 安装

系统要求

在安装 Chat2DB 之前，请确保您的系统满足以下要求：

Docker 19.03.0 或更高版本
Docker Compose 1.25.0 或更高版本
CPU >= 2 Core
RAM >= 4 GiB

# 在仓库目录中首次执行一次；重复执行会复用同一把合法密钥。
./script/security/init-community-encryption-key.sh

docker run --detach \
  --name chat2db-community \
  --restart unless-stopped \
  --publish 127.0.0.1:10825:10825 \
  --volume "$HOME/.chat2db-community-docker:/root/.chat2db-community" \
  --env CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE=/run/secrets/chat2db-community-encryption.key \
  --volume "$HOME/.config/chat2db-community/encryption.key:/run/secrets/chat2db-community-encryption.key:ro" \
  chat2db/chat2db:latest

docker logs --follow chat2db-community

浏览器访问 http://localhost:10825。更新时先拉取新镜像、删除旧容器，再重新执行以上命令。

Chat2DB Community 5.3.0 使用独立的 /root/.chat2db-community 目录，不会自动迁移旧镜像 /root/.chat2db 中的数据。

容器重建时必须保留 ~/.config/chat2db-community/encryption.key，并单独备份。替换或丢失该文件会导致已有数据源密码和 AI 模型 API Key 无法解密；chat2db.mode 不是 DESKTOP 的启动方式（包括常规 Web/headless 启动）缺少合法密钥时会直接启动失败。

仓库也提供了 Compose 配置：

docker compose --file docker/docker-compose.yml up --detach

社区版加密密钥

Chat2DB Community 使用 AES-256-GCM 加密保存的数据源密码和用户配置的 AI 模型 API Key。两类数据使用同一把安装密钥，但使用不同的认证 AAD，因此一种用途的密文不能作为另一种用途解密。密钥必须是合法的 Base64，且解码后恰好为 32 字节。仓库提供的初始化脚本会生成标准带填充格式，即 44 个 Base64 字符并以 = 结尾。它是加密密钥材料，不是用户自行输入的普通口令。

在仓库目录中执行以下命令，创建默认密钥文件：

./script/security/init-community-encryption-key.sh

默认路径是 ~/.config/chat2db-community/encryption.key。如需使用自定义路径，应在初始化脚本和 Chat2DB 启动参数中指定同一路径：

./script/security/init-community-encryption-key.sh /secure/path/chat2db-community.key

java -Dloader.path=chat2db-community-server/chat2db-community-start/target/lib \
    -Dchat2db.runtime.mode=community \
    -Dchat2db.mode=WEB \
    -Dchat2db.gui=false \
    -Dchat2db.network.status=OFFLINE \
    -Dchat2db.community.encryption-key-file=/secure/path/chat2db-community.key \
    -Dserver.address=127.0.0.1 \
    -Dserver.port=10825 \
    -jar chat2db-community-server/chat2db-community-start/target/chat2db-community.jar

初始化脚本依赖 openssl。脚本选择密钥文件路径的优先级依次为位置参数、CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE 和默认路径。脚本会复用已有的合法普通文件，拒绝符号链接和非普通文件；如果已有文件不合法，脚本会报错且不会覆盖。密钥文件应当只允许 Chat2DB 进程所属用户读取，升级或重建容器时必须保留，并与数据源存储分开备份。

密钥配置按以下优先级解析：

JVM 参数 chat2db.community.encryption-key，值为 Base64 密钥。
环境变量 CHAT2DB_COMMUNITY_ENCRYPTION_KEY，值为 Base64 密钥。
JVM 参数 chat2db.community.encryption-key-file，值为密钥文件路径。
环境变量 CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE，值为密钥文件路径。
默认文件 ~/.config/chat2db-community/encryption.key。

第一个已配置的值具有最高优先级。空值、非法 Base64、解码后不是 32 字节的密钥或非法密钥文件都会直接导致启动失败，不会静默回退到下一项。推荐使用密钥文件，避免把密钥值直接暴露在进程参数或环境变量中。

密钥文件是否自动创建只取决于 chat2db.mode，与 chat2db.gui 无关。Community Desktop 模式（chat2db.runtime.mode=community 且 chat2db.mode=DESKTOP）会在未配置内联密钥且所选密钥文件不存在时自动创建该文件。任何非 Desktop 模式（包括常规 Web/headless 启动）都不会创建缺失的密钥，必须提前初始化或显式配置合法密钥，否则启动失败。解析后的密钥会在进程生命周期内缓存，因此修改密钥配置后必须重启应用。替换或丢失密钥后，已经保存的数据源密码和 AI 模型 API Key 将无法解密。

代码调试

运行环境

java 运行 Open JDK 17
Node 运行环境 Node.js 18 或以上版本
Maven 3.8 或以上版本

git clone 到本地

$ git clone git@github.com:OtterMind/Chat2DB.git

前端调试

请使用仓库中的 Yarn lockfile。
$ cd Chat2DB/chat2db-community-client
$ yarn install --frozen-lockfile
$ yarn run start:community:hot

后端调试

$ cd Chat2DB
$ mvn -B clean package -Dmaven.test.skip=true -Dchat2db.finalName=chat2db-community \
    -f chat2db-community-server/pom.xml \
    -pl chat2db-community-start -am
$ ./script/security/init-community-encryption-key.sh
$ java -Dloader.path=chat2db-community-server/chat2db-community-start/target/lib \
    -Dchat2db.gui=false \
    -Dchat2db.runtime.mode=community \
    -Dchat2db.mode=WEB \
    -Dchat2db.network.status=OFFLINE \
    -Dchat2db.community.encryption-key-file="$HOME/.config/chat2db-community/encryption.key" \
    -Dserver.address=127.0.0.1 \
    -Dserver.port=10825 \
    -Dspring.profiles.active=dev \
    -jar chat2db-community-server/chat2db-community-start/target/chat2db-community.jar

构建本地 Docker 镜像

$ ./docker/docker-build.sh 5.3.0 chat2db/chat2db:5.3.0

常见问题

1、无法获取数据源驱动：`getJDBCDriver error: null`

问题原因：无法联网导致下载数据库驱动包失败。

解决办法：本地启动时，将驱动放入 ~/.chat2db-community/jdbc-lib；使用上面的 Docker 命令启动时，将驱动放入 $HOME/.chat2db-community-docker/jdbc-lib。

下载地址可参考 application.yml 中的 jdbc-jar-downLoad-urls 配置。

联系我们

致谢

感谢所有为 Chat2DB 贡献力量的同学们~~

Star History

License

Chat2DB Community 5.3.0 及后续版本适用本仓库的 LICENSE。该许可基于 Apache License 2.0 并附加了使用条件，属于 Source Available 许可。Chat2DB 5.3.0 之前发布的所有版本，包括 0.3.7 以及更早的历史版本，继续适用 Apache License 2.0。