环境准备
LangChat Pro是一个基于Spring Boot + Vue3的AI对话平台,支持多种大语言模型和向量数据库。在开始部署前,请确保您的开发环境满足以下要求。
请注意:下述中间件,优先使用Docker-Compose文件部署,尽量避免使用直接安装的方式。特别是对于PgVector这种VectorDB
总体概览
首先部署LangChat应该至少需要提前部署如下中间件服务:
必要:
- MySQL 8.x
- Redis 6.0+
- PgVector/Milvus/ES (向量数据库任选一个)
- OSS(云服务或者Minio、RustFS)
- XXL-Job-Admin (v3.x版本)
- RapidDoc(或者单独部署MinerU + Gotenberg)
可选:
- OpenSandBox(阿里云独立代码执行沙箱)
- OnlyOffice(文档预览服务,注意商用协议)
- SearXNG(自建搜索引擎)
- Xinference(私有化模型部署平台)
下述位于项目根目录docs/docker/docker-compose.yml 是一个相对完善的compose脚本
version: '3.8'
# LangChat 第三方服务汇总 Docker Compose 配置
#
# 使用说明:
# 1. 启动所有服务: docker compose up -d
# 2. 启动特定服务: docker compose up -d <service-name>
# 3. 查看服务状态: docker compose ps
# 4. 停止所有服务: docker compose down
#
# 各服务端口说明:
# - Redis: 6379 (Redis)
# - PostgreSQL (PgVector): 5432
# - RustFS: 9000 (S3 API), 9001 (Console)
# - Milvus: 19530 (API), 9091 (Metrics), 8000 (Attu UI)
# - XInference: 9997
# - SearXNG: 8081
# - XXL-Job-Admin: 8080
# - RapidDOC(MinerU): 8801
# - Gotenberg: 8802
services:
# ==================== Redis ====================
redis:
container_name: langchat-redis
image: docker.m.daocloud.io/redis/redis-stack:latest
ports:
- "6379:6379" # Redis 默认端口
- "8001:8001" # Redis Stack 管理界面的端口
environment:
- REDIS_ARGS=--requirepass root # 设置密码
volumes:
- ./cache/redis:/data # 数据持久化
restart: always
networks:
- langchat-network
# ==================== PostgreSQL + PgVector ====================
pgvector:
container_name: langchat-pgvector
image: docker.m.daocloud.io/pgvector/pgvector:0.8.0-pg17
ports:
- "5432:5432"
restart: always
environment:
- POSTGRES_DB=langchat
- POSTGRES_USER=root
- POSTGRES_PASSWORD=root
volumes:
- ./cache/pgvector:/var/lib/postgresql/data
networks:
- langchat-network
# ==================== RustFS ====================
rustfs:
image: docker.m.daocloud.io/rustfs/rustfs:latest
container_name: langchat-rustfs
security_opt:
- "no-new-privileges:true"
ports:
- "9000:9000" # S3 API 对外端口
- "9001:9001" # 控制台对外端口
environment:
# 数据卷(多个路径用逗号分隔)
- RUSTFS_VOLUMES=/data
# API 和控制台监听地址
- RUSTFS_ADDRESS=0.0.0.0:9000
- RUSTFS_CONSOLE_ADDRESS=0.0.0.0:9001
- RUSTFS_CONSOLE_ENABLE=true
# CORS 设置,控制台与 S3 API 都放开来源
- RUSTFS_CORS_ALLOWED_ORIGINS=*
- RUSTFS_CONSOLE_CORS_ALLOWED_ORIGINS=*
# 访问密钥(生产环境请修改为强密码)
- RUSTFS_ACCESS_KEY=admin
- RUSTFS_SECRET_KEY=admin
# 日志级别
- RUSTFS_LOG_LEVEL=info
volumes:
# 存储数据卷
- ./cache/rustfs:/data
# 日志目录
- ./cache/rustfs/logs:/app/logs
restart: unless-stopped
healthcheck:
test: ["CMD", "sh", "-c", "curl -f http://localhost:9000/health && curl -f http://localhost:9001/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
networks:
- langchat-network
# # ==================== Milvus ====================
# milvus-etcd:
# container_name: langchat-milvus-etcd
# image: docker.m.daocloud.io/quay.io/coreos/etcd:v3.5.5
# environment:
# - ETCD_AUTO_COMPACTION_MODE=revision
# - ETCD_AUTO_COMPACTION_RETENTION=1000
# - ETCD_QUOTA_BACKEND_BYTES=4294967296
# volumes:
# - ./cache/milvus/etcd:/etcd
# command: etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
# networks:
# - langchat-network
#
# milvus-minio:
# container_name: langchat-milvus-minio
# image: docker.m.daocloud.io/minio/minio:RELEASE.2023-03-20T20-16-18Z
# environment:
# MINIO_ACCESS_KEY: minioadmin
# MINIO_SECRET_KEY: minioadmin
# volumes:
# - ./cache/milvus/minio:/minio_data
# command: minio server /minio_data
# healthcheck:
# test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
# interval: 30s
# timeout: 20s
# retries: 3
# networks:
# - langchat-network
#
# milvus-standalone:
# container_name: langchat-milvus
# image: docker.m.daocloud.io/milvusdb/milvus:v2.3.3
# command: ["milvus", "run", "standalone"]
# environment:
# ETCD_ENDPOINTS: milvus-etcd:2379
# MINIO_ADDRESS: milvus-minio:9000
# volumes:
# - ./cache/milvus/milvus:/var/lib/milvus
# ports:
# - "19530:19530"
# - "9091:9091"
# depends_on:
# - "milvus-etcd"
# - "milvus-minio"
# networks:
# - langchat-network
#
# milvus-attu:
# container_name: langchat-milvus-attu
# image: docker.m.daocloud.io/zilliz/attu:v2.3.3
# environment:
# MILVUS_URL: milvus-standalone:19530
# ports:
# - "8000:3000"
# depends_on:
# - "milvus-standalone"
# networks:
# - langchat-network
# # ==================== SearXNG ====================
# searxng:
# container_name: langchat-searxng
# image: docker.io/searxng/searxng:latest
# restart: always
# networks:
# - langchat-network
# ports:
# - "8081:8080"
# volumes:
# - ./searxng-docker/searxng:/etc/searxng:rw
# - ./cache/searxng:/var/cache/searxng:rw
# environment:
# - SEARXNG_BASE_URL=http://${SEARXNG_HOSTNAME:-localhost}:8081/
# logging:
# driver: "json-file"
# options:
# max-size: "1m"
# max-file: "1"
# ==================== XXL-Job-Admin (分布式任务调度) ====================
# 注意:XXL-Job-Admin 需要 MySQL 数据库支持
# 默认连接到宿主机的 MySQL(需要用户自行部署或配置)
xxl-job-admin:
image: docker.m.daocloud.io/xuxueli/xxl-job-admin:3.3.2
container_name: langchat-xxl-job-admin
ports:
- "8080:8080"
environment:
# 数据库配置
# macOS/Windows: 使用 host.docker.internal 访问宿主机 MySQL
# Linux: 使用宿主机实际 IP 地址替代 host.docker.internal
PARAMS: "--spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver --spring.datasource.url=jdbc:mysql://host.docker.internal:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai --spring.datasource.username=root --spring.datasource.password=root --xxl.job.accesstoken=default_token"
# JVM 参数
JAVA_OPTS: "-Xms512m -Xmx512m"
volumes:
# 配置数据目录
- ./cache/xxl-job-admin:/data
networks:
- langchat-network
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/xxl-job-admin"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
rapid-doc-server:
container_name: langchat-rapid-doc-server
image: hzkitty/rapid-doc:0.7.0
ports:
- "8801:8888"
environment:
- TZ=${TIMEZONE:-UTC}
- GOTENBERG_URL=http://gotenberg:3000
restart: always
networks:
- langchat-network
depends_on:
- gotenberg
gotenberg:
container_name: langchat-gotenberg
image: docker.m.daocloud.io/gotenberg/gotenberg
ports:
- "8802:3000"
environment:
- TZ=${TIMEZONE:-UTC}
restart: always
networks:
- langchat-network
networks:
langchat-network:
driver: bridge
name: langchat-network
Step 1: 基础开发环境
LangChat Pro基于Spring Boot 3.x开发,需要JDK 17或更高版本。macOS (推荐使用Homebrew):brew install openjdk@17
echo 'export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Ubuntu/Debian:sudo apt update
sudo apt install openjdk-17-jdk
Windows:
下载并安装 Oracle JDK 17 或 OpenJDK 17验证安装:运行 java -version 确认版本为17.x
LangChat Pro使用MySQL作为主数据库,支持MySQL 8.0及以上版本。macOS:brew install mysql
brew services start mysql
Ubuntu/Debian:sudo apt install mysql-server
sudo systemctl start mysql
sudo systemctl enable mysql
配置数据库:CREATE DATABASE langchat_pro CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
导入初始数据:
找到项目根目录的 docs/langchat_pro.sql 文件并执行:mysql -u root -p langchat_pro < docs/langchat_pro.sql
确保MySQL服务正常运行,并记录数据库连接信息用于后续配置
LangChat Pro使用Redis进行缓存和会话管理,支持Redis 6.0及以上版本。macOS:brew install redis
brew services start redis
Ubuntu/Debian:sudo apt install redis-server
sudo systemctl start redis
sudo systemctl enable redis
Windows:
下载 Redis for Windows 或使用WSL验证安装:运行 redis-cli ping 应返回 PONG
LangChat Pro前端基于Vue3开发,需要Node.js 22或更高版本。macOS:Ubuntu/Debian:curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
Windows:
下载并安装 Node.js验证安装:运行 node --version 和 npm --version 确认版本
Step 2: XXL-Job-Admin 配置
LangChat Pro新版本深度依赖二开了XXL-Job调度服务,因此需要单独部署XXL-Job-Admin服务。
完整的docker-compose脚本位于 docs/docker/xxl-job/docker-compose.yml 启动此服务即可version: "3.8"
services:
# ==================== XXL-Job-Admin ====================
# 注意:XXL-Job-Admin 需要 MySQL 数据库支持
#
# 方式一:使用外部 MySQL(推荐)
# 修改下方 PARAMS 中的 --spring.datasource.url 和数据库凭证
#
# 方式二:使用本配置中的 MySQL 容器
# 取消下方注释的 xxl-job-mysql 服务,并取消 xxl-job-admin 的 depends_on
xxl-job-admin:
image: docker.m.daocloud.io/xuxueli/xxl-job-admin:3.3.2
container_name: xxl-job-admin
ports:
- "8080:8080"
environment:
# 数据库配置
# macOS/Windows: 使用 host.docker.internal 访问宿主机服务
# Linux: 使用实际的宿主机 IP 地址
PARAMS: "--spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver --spring.datasource.url=jdbc:mysql://host.docker.internal:3307/langchat_pro?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai --spring.datasource.username=root --spring.datasource.password=12345678 --xxl.job.accesstoken=default_token"
# JVM 参数
JAVA_OPTS: "-Xms512m -Xmx512m"
volumes:
# 配置数据目录
- ./cache/xxl-job-admin:/data
networks:
- langchat-network
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://127.0.0.1:8080/xxl-job-admin"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
# ==================== MySQL 数据库(可选,仅在本地部署时需要)====================
# 如果你已有 MySQL 实例,可以注释掉此服务,只需修改上面 xxl-job-admin 的数据库连接信息即可
# xxl-job-mysql:
# image: docker.m.daocloud.io/mysql:8.0
# container_name: xxl-job-mysql
# environment:
# MYSQL_ROOT_PASSWORD: xxljob
# MYSQL_DATABASE: xxl_job
# ports:
# - "3306:3306"
# volumes:
# - ./cache/xxl-job-mysql:/var/lib/mysql
# networks:
# - xxl-job-network
# healthcheck:
# test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
# interval: 10s
# timeout: 5s
# retries: 5
# restart: unless-stopped
networks:
langchat-network:
driver: bridge
name: langchat-network
Step 3: 向量数据库
LangChat Pro支持多种向量数据库用于知识库检索,您可以根据需求选择其中一种:
PostgreSQL的向量扩展,适合中小规模应用。安装PostgreSQL + PgVector:# macOS
brew install postgresql
brew services start postgresql
psql postgres -c "CREATE EXTENSION vector;"
# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib
sudo -u postgres psql -c "CREATE EXTENSION vector;"
创建数据库:CREATE DATABASE langchat_vector;
适合大规模搜索场景,支持复杂的向量检索。使用Docker安装:docker run -d --name elasticsearch \
-p 9200:9200 -p 9300:9300 \
-e "discovery.type=single-node" \
-e "xpack.security.enabled=false" \
elasticsearch:8.11.0
验证安装:curl http://localhost:9200
专为向量搜索设计的数据库,支持高并发和大规模数据。使用Docker Compose安装:# docker-compose.yml
version: '3.5'
services:
etcd:
container_name: milvus-etcd
image: docker.m.daocloud.io/quay.io/coreos/etcd:v3.5.5
environment:
- ETCD_AUTO_COMPACTION_MODE=revision
- ETCD_AUTO_COMPACTION_RETENTION=1000
- ETCD_QUOTA_BACKEND_BYTES=4294967296
volumes:
- ${DOCKER_VOLUME_DIRECTORY:-.}/milvus_data/etcd:/etcd
command: etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
minio:
container_name: milvus-minio
image: docker.m.daocloud.io/minio/minio:RELEASE.2023-03-20T20-16-18Z
environment:
MINIO_ACCESS_KEY: minioadmin
MINIO_SECRET_KEY: minioadmin
volumes:
- ${DOCKER_VOLUME_DIRECTORY:-.}/milvus_data/minio:/minio_data
command: minio server /minio_data
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
interval: 30s
timeout: 20s
retries: 3
standalone:
container_name: milvus-standalone
image: docker.m.daocloud.io/milvusdb/milvus:v2.3.3
command: ["milvus", "run", "standalone"]
environment:
ETCD_ENDPOINTS: etcd:2379
MINIO_ADDRESS: minio:9000
volumes:
- ${DOCKER_VOLUME_DIRECTORY:-.}/milvus_data/milvus:/var/lib/milvus
ports:
- "19530:19530"
- "9091:9091"
depends_on:
- "etcd"
- "minio"
attu:
container_name: milvus-attu
image: docker.m.daocloud.io/zilliz/attu:v2.3.3
environment:
MILVUS_URL: standalone:19530
ports:
- "8000:3000"
depends_on:
- "standalone"
networks:
default:
name: milvus
Milvus需要较多系统资源,建议在配置较高的机器上使用
Step 4: 推理模型
LangChat Pro支持多种大语言模型,包括公有云和私有化部署:
支持OpenAI、Claude、Gemini等主流模型:OpenAI GPT系列:
- GPT-3.5-turbo
- GPT-4
- GPT-4-turbo
Anthropic Claude系列:
- Claude-3-Sonnet
- Claude-3-Haiku
- Claude-3-Opus
Google Gemini系列:
- Gemini Pro
- Gemini Pro Vision
使用公有云模型需要准备相应的API Key,建议在项目启动后通过管理界面配置
支持本地部署的开源模型:使用Ollama (推荐):# 安装Ollama
curl -fsSL https://ollama.ai/install.sh | sh
# 下载模型
ollama pull llama2:7b
ollama pull qwen:7b
ollama pull chatglm3:6b
# 启动服务
ollama serve
使用Xinference:# 安装Xinference
pip install xinference
# 启动服务
xinference
私有化模型需要根据硬件配置选择合适的模型大小,建议至少8GB内存
Step 5: 向量模型
用于文本向量化的模型,支持多种嵌入模型:
OpenAI Embeddings:
- text-embedding-ada-002
- text-embedding-3-small
- text-embedding-3-large
其他云服务:
- 百度文心一言Embedding
- 阿里通义千问Embedding
- 腾讯混元Embedding
使用Ollama:# 下载向量模型
ollama pull nomic-embed-text
ollama pull bge-large-en-v1.5
使用Xinference:# 启动向量模型服务
xinference launch --model-name bge-large-en-v1.5 --model-type embedding
私有化向量模型通常需要4-8GB内存,建议使用GPU加速
Step 6: 对象存储 (OSS)
LangChat Pro支持多种对象存储服务,配置在 langchat.oss 节点下:
开源对象存储,适合本地开发和测试:使用Docker安装:docker run -d --name minio \
-p 9000:9000 -p 9001:9001 \
-e "MINIO_ROOT_USER=admin" \
-e "MINIO_ROOT_PASSWORD=admin123" \
-v minio_data:/data \
minio/minio server /data --console-address ":9001"
访问控制台:创建名为 langchat-oss 的存储桶用于存储文件,并在配置文件中设置 default-platform: minio
国内知名云存储服务:配置信息:
- AccessKey:从七牛云控制台获取
- SecretKey:从七牛云控制台获取
- 存储空间名称:创建的空间名称
- 域名:绑定的域名或七牛云提供的域名
阿里云对象存储服务:配置信息:
- AccessKey ID:从阿里云控制台获取
- AccessKey Secret:从阿里云控制台获取
- Endpoint:OSS地域节点地址
- Bucket名称:创建的存储桶名称
腾讯云对象存储服务:配置信息:
- SecretId:从腾讯云控制台获取
- SecretKey:从腾讯云控制台获取
- Region:存储桶所在地域
- Bucket名称:创建的存储桶名称
配置环境
后端配置
使用IDE打开langchat-pro项目,找到 langchat-bootstrap/src/main/resources 目录下的配置文件:
# 修改 application-dev.yml 开发环境配置文件
server:
port: 8100
spring:
# 数据库配置
datasource:
username: root
password: 12345678
url: jdbc:mysql://127.0.0.1:3306/langchat_pro?characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
type: com.alibaba.druid.pool.DruidDataSource
driver-class-name: com.mysql.cj.jdbc.Driver
druid:
keep-alive: true
# Redis配置
data:
redis:
port: 6379
host: 127.0.0.1
database: 1
jedis:
pool:
max-wait: 2000
time-between-eviction-runs: 1000
langchat:
searxng:
enabled: true
duration: 10
url: http://127.0.0.1:8081
max-results: 10
max-results-limit: 50
excalidraw:
url: http://127.0.0.1:3000
oss:
# 固定填写,本地:local-plus(nginx)、七牛:qiniu-kodo、阿里OSS:aliyun-oss、腾讯OSS:tencent-cos、minio: minio
default-platform: minio
local-plus:
- platform: local-plus
# 是否启用
enable-storage: false
# 访问域名
domain: http://127.0.0.1:80/
# 文件夹名称
base-path: langchat-oss/
# 本地存储路径
storage-path: /Users/tycoding/data/software/nginx/
qiniu-kodo:
- platform: qiniu-kodo
# 是否启用
enable-storage: false
access-key:
secret-key:
# 桶名称
bucket-name:
# 文件夹名称
base-path:
# 访问域名
domain:
aliyun-oss:
- platform: aliyun-oss
# 是否启用
enable-storage: false
access-key:
secret-key:
# 桶名称
bucket-name:
# 访问域名
end-point: oss-cn-hangzhou.aliyuncs.com
tencent-cos:
- platform: tencent-cos
# 是否启用
enable-storage: false
secret-id:
secret-key:
# 区域
region:
# 桶名称
bucket-name:
# 访问域名
domain:
minio:
- platform: minio
# 是否启用
enable-storage: true
secret-key: minioadmin
access-key: minioadmin
# 桶名称
bucket-name: langchat-oss
# 访问域名
end-point: http://127.0.0.1:9000/
前端配置
进入前端项目目录 langchat-ui/apps/langchat,修改环境配置文件(特别是关于后端服务地址和前端服务地址,应该修改为实际的地址,如果是生产环境,应该修改为公网域名):
# .env.development
# 端口号
VITE_PORT=5888
VITE_BASE=/
# 接口地址
VITE_GLOB_API_URL=/api
# 是否开启 Nitro Mock服务,true 为开启,false 为关闭
VITE_NITRO_MOCK=false
# 是否打开 devtools,true 为打开,false 为关闭
VITE_DEVTOOLS=false
# 是否注入全局loading
VITE_INJECT_APP_LOADING=true
# 后端服务地址
VITE_GLOB_BACKEND_URL=http://127.0.0.1:8100
# 前端服务地址
VITE_GLOB_FRONT_URL=http://127.0.0.1:5888
启动项目
后端启动
-
编译项目:
cd langchat-pro
mvn clean compile
-
启动应用:
# 使用IDE直接运行 LangChatApp启动器类
前端启动
-
安装依赖:
cd langchat-ui
pnpm install
-
启动开发服务器:
-
访问应用:
模型配置
项目启动后,通过管理界面配置模型:
- 登录管理后台
- 配置推理模型 - 添加OpenAI、Claude等模型
- 配置向量模型 - 添加文本嵌入模型
- 配置知识库 - 创建知识库并上传文档
- 测试对话 - 验证配置是否正确
常见问题
启动失败排查
-
数据库连接失败
- 检查MySQL服务是否启动
- 验证数据库连接信息是否正确
- 确认数据库用户权限
-
Redis连接失败
- 检查Redis服务是否启动
- 验证Redis连接配置
- 确认Redis密码是否正确
-
端口占用
- 检查8080端口是否被占用
- 使用
lsof -i :8080 查看端口占用情况
性能优化建议
-
向量数据库选择
- 小规模应用:推荐PgVector
- 大规模应用:推荐Milvus或ElasticSearch
-
模型选择
- 开发测试:使用Ollama本地模型
- 生产环境:使用云服务模型
-
硬件要求
- 最低配置:8GB内存,4核CPU
- 推荐配置:16GB内存,8核CPU
- GPU加速:支持CUDA的显卡可显著提升推理速度