# btm-ai

**Repository Path**: BigTailMonkey/btm-ai

## Basic Information

- **Project Name**: btm-ai
- **Description**: 试试使用spring-ai开发个应用
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-04-09
- **Last Updated**: 2026-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# btm-ai

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![JDK](https://img.shields.io/badge/JDK-17%2B-green.svg)](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)
[![Maven](https://img.shields.io/badge/Maven-3.8%2B-orange.svg)](https://maven.apache.org/)
[![MySQL](https://img.shields.io/badge/MySQL-5.6%2B-blue.svg)](https://www.mysql.com/)

## 📖 项目简介

btm-ai是一个集成多种AI能力的综合服务平台，为开发者提供便捷的AI功能接入方案。本项目采用模块化设计，支持大模型对话、智能数据库查询、数据提取等多种AI能力。

### ✨ 核心特性

- 🤖 集成DeepSeek API，提供高质量的AI对话能力
- 📊 智能数据库查询，支持自然语言转SQL
- 🔍 Doris数据结构提取与检索
- 🔌 模块化设计，支持灵活扩展
- 🌐 统一的REST API接口
- 🛠 完整的开发工具链支持

## 🚀 快速开始

### 环境准备

确保您的开发环境满足以下要求：
- JDK 17或更高版本
- Maven 3.8或更高版本
- MySQL 5.6或更高版本
- 可用的DeepSeek API密钥

项目已在根目录提供 `.java-version`，并通过 Maven Enforcer 插件校验 JDK 版本。
如果本机 Maven 仍然使用了错误的 JDK，可以先执行：

```bash
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
export PATH="$JAVA_HOME/bin:$PATH"
```

### 一键部署

1. 克隆项目
```bash
git clone https://github.com/yourusername/btm-ai.git
cd btm-ai
```

2. 配置环境变量
```bash
export MODEL_API_KEY=your_api_key
export HIGRESS_SECRET_KEY=your_higress_secret_key
```

3. 修改配置文件
在各模块的`application.yml`中配置数据库连接信息。

4. 编译部署
```bash
# 编译所有模块
mvn clean package

# 启动服务（按顺序）
java -jar mcp-server-mysql/target/mcp-server-mysql.jar
java -jar mcp-server-organization/target/mcp-server-organization.jar
java -jar mcp-server-business/target/mcp-server-business.jar
java -jar btm-chat/target/btm-chat.jar
```

## docker打包镜像
docker build --platform linux/amd64 -t btm-ai-linux:版本号 .

## 导出docker镜像
docker save -o ./btm-ai-linux-版本号.tar btm-ai-linux:版本号

## docker部署

1. 从本机的docker镜像里导出btm-ai-linux.tar，然后导入到目标服务器的docker镜像库
2. 复制配置文件.env.template为.env，并完善配置项
3. 使用命令`docker run --env-file .env -p 8889:8889 -v /data/btm_ai:/data/btm_ai --name btm-ai-service btm-ai-linux:版本号`启动容器
4. 用户权限体系使用的 H2 数据库文件会写入容器内挂载目录 `/data/btm_ai`，并通过 volume 映射持久化到宿主机硬盘
5. 通过http://ip:8889访问服务

### 表结构数据库注释写入按钮开关

表结构页面中的“批量同步到MySQL”和“保存数据库注释”会写入数据库字段注释，默认不显示。需要在 `.env` 中显式开启：

```text
VITE_ENABLE_TABLE_STRUCTURE_DB_COMMENT_WRITE_ACTIONS=true
```

该配置是前端构建期开关。修改后需要重新构建前端镜像或重新执行前端构建；仅重启已经构建好的容器不会改变按钮显示状态。未配置或配置为 `false` 时，这两个按钮不显示。

### 用户手册挂载

系统顶部提供“用户手册”在线阅读入口和“下载用户手册”按钮，后端会从磁盘路径读取手册文件并返回给前端渲染或下载。手册文件不会打包到 Docker 镜像中，推荐通过 `/data/btm_ai` 的宿主机目录映射加载。

默认容器内路径：

```text
/data/btm_ai/manual/BTM-AI-user-manual.md
```

部署前可将仓库中的示例手册复制到宿主机挂载目录：

```bash
mkdir -p /data/btm_ai/manual
cp docs/user-manual/BTM-AI-user-manual.md /data/btm_ai/manual/BTM-AI-user-manual.md
```

如需使用其他路径，在 `.env` 中配置：

```text
BTM_USER_MANUAL_PATH=/data/btm_ai/manual/BTM-AI-user-manual.md
```

然后继续使用已有挂载方式启动：

```bash
docker run -d --env-file .env -p 8889:8889 -p 8822:8822 -p 8085:8085 -p 8811:8811 -p 8833:8833 -p 8844:8844 -v /data/btm_ai:/data/btm_ai --name btm-ai-service btm-ai-linux:版本号
```

## 📦 项目结构

```
btm-ai/
├── btm-chat/               # AI对话服务模块
│   ├── src/               # 源代码
│   └── pom.xml           # 模块配置
├── mcp-server-mysql/      # 数据库查询服务
│   ├── src/
│   └── pom.xml
├── mcp-server-organization/ # 组织管理服务
│   ├── src/
│   └── pom.xml
├── extract-doris-info/    # Doris数据提取模块
│   ├── src/
│   └── pom.xml
├── flux_web/             # Web前端界面
│   ├── src/             # 前端源代码
│   ├── public/         # 静态资源
│   └── package.json    # 依赖配置
└── pom.xml             # 项目总配置
```

## 🔧 模块说明

### btm-chat

AI对话服务模块，基于Spring-AI框架开发：
- 集成DeepSeek API，支持多种对话模式
- 提供简单对话和系统预设提示功能
- 支持多轮对话，自动管理会话历史
- 集成MCP客户端，可调用数据库查询和组织信息服务
- 提供流式响应能力
- 支持自定义系统提示词

### mcp-server-mysql

数据库查询服务模块：
- 提供SQL查询执行能力
- 支持SELECT语句查询（executeQuerySql）
- 支持所有类型SQL执行（executeAllSql）
- 返回JSON格式的查询结果
- 内置错误处理和日志记录

### mcp-server-organization

组织架构管理服务模块：
- 提供组织机构信息查询
- 支持按机构名称模糊搜索
- 维护组织机构层级关系
- 存储机构基本信息（代码、名称、类型等）
- 支持多维度组织信息（区域、街道等）

### extract-doris-info

Doris数据库表结构管理模块：
- 提取数据库表结构信息
- 支持表结构信息存储到MeiliSearch
- 提供表结构搜索功能
- 支持表注释和字段注释的更新
- 实现数据库与搜索引擎的结构同步
- 提供REST API接口管理表结构

### flux_web

Web前端界面模块：
- 提供统一的Web操作界面
- 集成各后端服务功能
- 支持用户交互操作

## 📚 API文档

### 对话接口

#### 简单对话
```http
POST /api/chat
Content-Type: application/json

Request:
{
    "message": "你好"
}

Response:
{
    "code": 0,
    "message": "success",
    "data": {
        "reply": "AI回复内容"
    }
}
```

#### 系统预设对话
```http
POST /api/chat/system
Content-Type: application/json

Request:
{
    "systemMessage": "你是一个助手",
    "userMessage": "你好"
}
```

## 🤝 参与贡献

1. Fork本仓库
2. 创建特性分支：`git checkout -b feature/xxx`
3. 提交更改：`git commit -am 'Add xxx feature'`
4. 推送分支：`git push origin feature/xxx`
5. 提交Pull Request

## 📄 开源协议

本项目采用[Apache License 2.0](./LICENSE)开源协议。


## IP 限制配置

系统支持配置数据库 IP 限制列表，用于控制数据库操作权限。当数据库连接的 IP 地址在限制列表中时，将禁止进行数据库操作。配置项在mcp-server-mysql模块中。

### 配置方式

1. 应用程序配置文件方式（application.yml）：
```yaml
system:
  safe:
    reject:
      db_ip: ${UNSAFE_DB_IPS}    # 使用环境变量占位符
```

2. 环境变量方式：
```bash
export UNSAFE_DB_IPS=192.168.1.100,10.0.0.0/8
```

3. Docker 环境变量方式：
在 `.env` 文件中配置：
```
unsafe_db_ip=192.168.1.100,10.0.0.0/8
```

### 配置说明

- 支持配置多个 IP 地址，使用逗号分隔
- 支持两种格式：
  - 单个 IP 地址：如 "192.168.1.100"
  - CIDR 格式的 IP 地址段：如 "10.0.0.0/8"
- 配置优先级：环境变量 > 配置文件
- 检查逻辑：系统会检查数据库连接 URL 中的 IP 地址是否在限制列表中
- 注意：此配置仅对 mcp-server-mysql 服务有效

---
© 2024-2025 btm-ai Team. All rights reserved.