Skip to main content

​
LangChat Pro 文档使用指南

本文档介绍 LangChat Pro 项目中 docs/ 目录下各个文件夹的用途，以及如何进行版本更新和数据库迁移。

​
目录结构说明

docs/
├── .env                              # Docker 部署环境配置
├── .gitignore                        # Git 忽略配置
├── docker-compose.yml                # 主服务 Docker Compose 配置
├── 使用指南.md                       # 本文件
├── changelog/                        # 版本更新日志
├── database/                         # 数据库脚本
│   ├── README.md                     # 数据库详细使用说明
│   ├── mysql/                        # MySQL 数据库脚本
│   │   ├── langchat_pro.sql         # MySQL 全量 SQL 脚本
│   │   └── migrations/              # MySQL 增量更新脚本
│   └── postgresql/                   # PostgreSQL 数据库脚本
│       └── langchat_pro.sql         # PostgreSQL 全量 SQL 脚本
├── docker/                           # Docker 服务部署脚本
├── nginx/                            # Nginx 配置文件
└── widget/                           # Widget 组件文件

​
各目录用途

​
📁 changelog/ - 版本更新日志

存放每个版本的功能更新说明、Bug 修复、重要变更等信息。 如何查看更新日志：
  • 查看最新版本：打开 changelog/ 目录下版本号最大的文件（如 v2.3.3.md）
  • 查看历史版本：按版本号降序排列，选择对应版本文件

​
📁 database/ - 数据库脚本

存放数据库相关的 SQL 脚本，支持 MySQL 和 PostgreSQL 两种数据库。 目录说明：
  • mysql/ - MySQL 数据库脚本（含全量和增量）
  • postgresql/ - PostgreSQL 数据库脚本（仅全量）
  • README.md - 数据库详细使用说明
如何使用数据库脚本：
  1. 全新安装：直接执行对应数据库的全量 SQL 脚本 
    # MySQL
mysql -u root -p langchat < database/mysql/langchat_pro.sql

# PostgreSQL
psql -U postgres -d langchat -f database/postgresql/langchat_pro.sql
  2. 版本升级：按版本号顺序执行增量脚本（仅 MySQL） 
    # 从 v2.3.2 升级到 v2.3.3
mysql -u root -p langchat < database/mysql/migrations/v2.3.3.mysql.sql
重要提示：
  • 执行任何 SQL 脚本前，请务必备份数据库
  • 增量升级必须按版本号顺序执行，不能跳过版本
  • 详细使用说明请参考 database/README.md

​
📁 docker/ - Docker 部署脚本

存放各个服务的 Docker Compose 配置文件。 包含的服务：
  • mysql/ - MySQL 数据库
  • redis/ - Redis 缓存
  • pgvector/ - PostgreSQL with pgvector（向量数据库）
  • nginx/ - Nginx 反向代理
  • minio/ - MinIO 对象存储
  • milvus/ - Milvus 向量数据库
  • neo4j/ - Neo4j 图数据库
  • searxng-docker/ - SearXNG 搜索引擎
  • xinference/ - Xinference 模型服务
  • gpustack/ - GPUStack 模型服务
  • 以及其他辅助服务…
如何使用：
  • 各服务目录下都有对应的 README.md 说明文档
  • 根据需要选择部署对应的服务
  • 修改配置文件中的 IP、端口等参数后执行启动命令

​
📁 nginx/ - Nginx 配置

存放 Nginx 反向代理配置文件。 配置文件说明：
  • nginx.conf - 基础 Nginx 配置（单节点部署）
  • nginx-lb.conf - 负载均衡配置（多节点部署）
使用场景：
  • 开发环境：使用 nginx.conf
  • 生产环境（多节点）：使用 nginx-lb.conf

​
📁 widget/ - Widget 组件

存放前端 Widget 组件的相关文件。 文件说明：
  • langchat-widget.umd.js - Widget 组件 JS 文件
  • langchat-widget.css - Widget 组件样式文件
  • pdfium.wasm - PDF 处理 WASM 文件

​
版本更新流程

​
方式一：全量更新（适合全新安装或重置）

适用场景：
  • 首次安装
  • 需要完全重置数据库
  • 版本跨度较大
步骤：
  1. 备份现有数据库（如果有）
  2. 执行全量 SQL 脚本： 
    # MySQL
mysql -u root -p langchat < database/mysql/langchat_pro.sql

# PostgreSQL
psql -U postgres -d langchat -f database/postgresql/langchat_pro.sql
  3. 更新应用代码到最新版本
  4. 重启服务

​
方式二：增量更新（推荐）

适用场景：
  • 小版本升级（如 v2.3.2 → v2.3.3）
  • 需要保留现有数据
步骤：
  1. 查看更新日志，了解版本变更内容 
    # 查看最新版本日志
cat changelog/v2.3.3.md
  2. 备份数据库 
    # MySQL 备份
mysqldump -u root -p langchat > backup_$(date +%Y%m%d).sql

# PostgreSQL 备份
pg_dump -U postgres langchat > backup_$(date +%Y%m%d).sql
  3. 按版本顺序执行增量 SQL 脚本（仅 MySQL） 
    # 从当前版本升级到目标版本
# 例如：从 v2.3.2 升级到 v2.3.3
mysql -u root -p langchat < database/mysql/migrations/v2.3.3.mysql.sql
  4. 更新应用代码到最新版本
  5. 重启服务
注意事项：
  • 必须按版本号顺序执行，不能跳过版本
  • 如果版本跨度较大，建议检查中间所有版本的增量脚本
  • PostgreSQL 目前仅支持全量更新

​
查看更新日志

​
查看最新版本更新

# 查看最新版本日志
cat changelog/v$(ls changelog/ | sort -V | tail -n 1 | sed 's/.md//').md

​
查看特定版本更新

# 查看指定版本日志
cat changelog/v2.3.3.md

​
查看所有版本列表

ls -1 changelog/ | sort -V

​
快速参考

​
常用命令

# 1. 查看当前版本
git describe --tags --always

# 2. 备份数据库 (MySQL)
mysqldump -u root -p langchat > backup_$(date +%Y%m%d_%H%M%S).sql

# 3. 备份数据库 (PostgreSQL)
pg_dump -U postgres langchat > backup_$(date +%Y%m%d_%H%M%S).sql

# 4. 恢复数据库 (MySQL)
mysql -u root -p langchat < backup_file.sql

# 5. 恢复数据库 (PostgreSQL)
psql -U postgres -d langchat -f backup_file.sql

# 6. 查看增量 SQL 文件列表
ls -1 database/mysql/migrations/ | sort -V

​
版本号说明

LangChat Pro 遵循语义化版本控制（Semantic Versioning）：
  • 主版本号：不兼容的 API 修改
  • 次版本号：向下兼容的功能性新增
  • 修订版本号：向下兼容的问题修正
示例：v2.3.3 表示：
  • 主版本：2
  • 次版本：3
  • 修订版本：3

​
数据版本对应关系

  • 全量 SQL：langchat_pro.sql 对应最新发布版本
  • 增量 SQL：每个版本一个文件，命名格式为 v{版本号}.mysql.sql

​
问题排查

​
执行 SQL 脚本失败

  1. 检查数据库版本是否符合要求
    • MySQL：8.0+
    • PostgreSQL：12+
  2. 确认数据库字符集
    • MySQL：utf8mb4
    • PostgreSQL：UTF8
  3. 检查数据库用户权限
  4. 确认是否按正确顺序执行增量脚本

​
版本升级后功能异常

  1. 检查应用日志
  2. 确认数据库迁移是否成功
  3. 验证配置文件是否需要更新
  4. 查看对应版本的更新日志，了解可能的破坏性变更

​
更多帮助

  • 数据库详细使用说明：database/README.md
  • 版本更新历史：changelog/ 目录
  • Docker 服务部署：docker/ 目录下各服务的 README

​
更新日期

最后更新：2025-01-08 当前文档版本：v2.3.3