Chat2DB 介绍与 Docker 部署指南

一、项目介绍

Chat2DB 是一款开源的 AI 数据库客户端与报表工具，集数据库连接管理、SQL 开发、AI 辅助查询、仪表盘报表于一体，支持 MySQL、PostgreSQL、Oracle、SQL Server、ClickHouse、Redis、MongoDB 等数十种主流数据库。

• GitHub: OtterMind/Chat2DB
• 官网: chat2db.ai
• 官方文档: docs.chat2db.ai
• Docker 镜像: chat2db/chat2db

核心能力：

• 多数据源连接管理，连接配置集中保存
• SQL 编辑器与执行、结果集导出
• AI 辅助（自然语言转 SQL、SQL 解释与优化建议，需自行配置 AI 服务）
• 仪表盘报表生成

注意：v5.x 社区版启动时强制要求配置社区加密密钥，不配置会直接启动失败。这是新版本的强制要求，官方旧文档未提及，下文有完整说明。

二、Docker 部署

2.1 重要前置：社区加密密钥

社区版启动时必须提供加密密钥，否则报错退出：

Community encryption key is required. Configure chat2db.community.encryption-key or CHAT2DB_COMMUNITY_ENCRYPTION_KEY, or initialize /root/.config/chat2db-community/encryption.key

密钥有三种提供方式（按优先级）：

密钥格式为 32 字节随机数据的 Base64 字符串，在宿主机生成（权限设为 600）：

mkdir -p ~/.chat2db-docker
openssl rand -base64 32 > ~/.chat2db-docker/encryption.key
chmod 600 ~/.chat2db-docker/encryption.key

服务端 / Docker 模式下应用不会自动生成密钥（仅桌面模式自动创建），必须提前准备。

2.2 端口说明

当前镜像（v5.3.0 实测）内部 Tomcat 实际监听 10825，官方文档写的 10824 是旧版行为。部署时用 10824:10825 映射，保持文档一致的访问入口，同时直连 10825 也可用。

2.3 启动容器（docker run）

docker run -d --name chat2db \
  -p 10824:10825 \
  -p 10825:10825 \
  -v ~/.chat2db-docker:/root/.chat2db \
  -v ~/.chat2db-docker/encryption.key:/root/.config/chat2db-community/encryption.key:ro \
  --restart unless-stopped \
  chat2db/chat2db:latest

启动约 5~10 秒完成后，浏览器访问：

http://localhost:10824

首次访问会要求注册本地管理员账号（用户名 + 密码），注册后即可登录使用。

2.4 docker compose 方式（推荐）

services:
  chat2db:
    image: chat2db/chat2db:latest
    container_name: chat2db
    restart: unless-stopped
    ports:
      # 新版镜像内部监听 10825，映射到文档约定的 10824
      - "10824:10825"
      - "10825:10825"
    volumes:
      # 数据持久化
      - ~/.chat2db-docker:/root/.chat2db
      # 社区版加密密钥（只读挂载，务必保留）
      - ~/.chat2db-docker/encryption.key:/root/.config/chat2db-community/encryption.key:ro

docker compose up -d

三、持久化说明

容器本身可以随时删除重建，但以下两项必须持久化到宿主机，否则数据丢失或无法解密。

3.1 数据目录 /root/.chat2db

3.2 加密密钥文件（最重要）

四、常用操作

docker logs -f chat2db     # 查看日志
docker restart chat2db     # 重启
docker stop chat2db        # 停止
docker rm -f chat2db       # 删除容器（数据仍在 ~/.chat2db-docker，不丢失）

升级镜像：

docker pull chat2db/chat2db:latest
docker rm -f chat2db
# 重新执行 2.3 的 docker run 命令，或 docker compose up -d

数据目录与密钥文件都在宿主机，升级不影响任何数据。

五、常见问题排查

六、实测环境信息（2026-08-28）

• 镜像：chat2db/chat2db:latest（v5.3.0，linux/arm64 约 300MB，Apple Silicon 原生运行）
• 运行时：Java 17 + Spring Boot 3.5，Tomcat 监听 10825
• 启动耗时：约 4~10 秒
• 访问地址：http://localhost:10824（映射入口）或 http://localhost:10825（直连）