iYque系统Docker Compose完整部署教程

本文整理iYque系统的完整部署流程，覆盖服务组件说明、环境变量配置、Docker Compose启动、数据库初始化、登录说明、访问验证和常见问题处理。整体部署方式以Docker Compose统一编排为主，适合在Linux服务器上快速搭建后端服务、前端页面、数据库、缓存和AI向量相关组件。

一、部署整体说明

1、部署服务组件

本次部署通过Docker Compose统一管理所有服务，核心组件包括：

• 后端服务： Spring Boot Java业务服务
• Nginx： 承载PC端和移动端前端静态资源，并反向代理后端API接口
• 基础中间件： MySQL业务数据库、Redis缓存
• AI向量依赖： Milvus向量检索、etcd、MinIO

所有服务由docker-compose.yml统一编排，部署和重启都在项目根目录中执行。

2、系统访问架构

部署完成后，系统访问入口如下：

• 统一入口： http://服务器IP/
• PC端地址： http://服务器IP/tools/
• 移动端地址： http://服务器IP/openmobile/
• 后端API前缀： /api/

其中，根路径默认跳转至PC端页面，后端API由Nginx统一转发。

二、部署前置准备

1、上传项目代码

将完整项目代码上传至服务器目录，推荐路径为：

/opt/iYqueCode

项目目录中需要保留以下核心文件和目录：

docker-compose.yml
Dockerfile
frontEnd/Dockerfile
deploy/nginx/default.conf
.env.example

这些文件分别用于服务编排、后端镜像构建、前端镜像构建、Nginx路由配置和环境变量初始化。

2、配置环境变量

进入项目根目录，复制环境变量模板：

cp .env.example .env

编辑.env文件，按实际环境配置核心参数：

# 数据库配置
MYSQL_ROOT_PASSWORD=root
MYSQL_DATABASE=scrm_ky

# MinIO存储配置
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin

# 文件访问地址
IYQUE_FILE_VIEW_URL=http://localhost/api/file/fileView/

# AI模型密钥，暂无AI需求可留空
AI_MODELS_CONFIGS_GLM_4_API_KEY=
AI_VECTOR_CONFIGS_EMBEDDING_3_API_KEY=

如果系统部署在正式服务器上，IYQUE_FILE_VIEW_URL建议改为实际访问域名或服务器地址，不要长期保留localhost。

数据库和MinIO密码也应在生产环境中改为高强度随机密码。

三、核心部署步骤

1、构建并启动全部服务

在项目根目录执行：

docker compose up -d --build

该命令会自动构建后端镜像和前端Nginx镜像，并启动MySQL、Redis、Milvus、后端服务、Nginx等全部容器。

如果服务器仍使用旧版Docker Compose，也可能需要执行：

docker-compose up -d --build

2、查看服务运行状态

启动完成后，查看所有容器状态：

docker compose ps

正常情况下，各服务状态应显示为Up。

如果某个容器反复重启，需要优先查看对应服务日志，而不是重复执行构建命令。

3、查看启动日志

部署完成后必须检查日志，确认服务真正启动成功。

查看后端日志：

docker compose logs -f backend

查看Nginx日志：

docker compose logs -f nginx

判断标准：

• 后端日志中出现Tomcat启动成功信息
• Nginx日志没有明显配置错误或转发错误
• 容器状态保持Up

四、数据库初始化

数据库初始化是本系统部署中的关键步骤。项目关闭了JPA自动建表，因此必须手动导入基础数据库文件。

1、导入基础数据库

确认MySQL容器已经启动后，将项目根目录中的数据库文件导入到目标库。

目标数据库名称以.env中的配置为准：

MYSQL_DATABASE=scrm_ky

导入思路如下：

1. 启动MySQL服务或完整启动全部服务。
2. 确认项目根目录存在iyque_db.sql。
3. 进入MySQL容器或通过容器命令导入SQL。
4. 将SQL导入到scrm_ky数据库。

示例命令可按实际MySQL容器名称调整：

docker compose exec -T mysql mysql -uroot -p"$MYSQL_ROOT_PASSWORD" scrm_ky < iyque_db.sql

如果当前Shell无法读取.env变量，也可以直接使用实际密码：

docker compose exec -T mysql mysql -uroot -proot scrm_ky < iyque_db.sql

正式环境不建议使用root作为数据库密码。

2、手动补全缺失数据表

当前iyque_db.sql版本可能滞后于代码，缺少部分核心业务表。部署时需要手动补全以下表：

• iyque_ai_conversation
• iyque_ai_conversation_message
• iyque_tag
• iyque_tag_group

如果运行过程中出现表不存在错误，应优先检查这些表是否已经创建。

3、注意字段命名规范

标签相关表必须使用实体类对应的驼峰字段名，不能改成下划线字段。

正确字段示例：

tagId
groupId
tagType
orderNumber
delFlag

错误字段示例：

tag_id
group_id
tag_type
order_number
del_flag

如果字段使用下划线命名，后端可能直接报错：

Unknown column

因此，补表时应严格按照代码实体字段定义创建表结构。

五、系统登录说明

本系统登录账号密码不从数据库用户表读取，而是由项目配置直接定义。

默认登录信息为：

账号：iyque
密码：iyque.cn

如果需要修改账号密码，应通过环境变量或运行配置覆盖，以实际运行配置为准。

登录失败时，优先检查：

• 环境变量是否正确注入
• 后端配置是否读取到新账号密码
• 容器是否已经重新启动
• Nginx是否正确代理API请求

不要优先排查数据库用户表，因为登录账号密码不依赖数据库读取。

六、部署验证

1、验证后端接口连通性

进入Nginx容器，从容器网络内部请求后端服务：

docker compose exec nginx wget -S -O - http://backend:8085/iYqueSys/getBaseInfo

如果返回：

HTTP/1.1 200

说明后端服务、容器网络和服务名解析基本正常。

2、验证前端访问

在浏览器中访问：

http://服务器IP/

重点检查：

• 根路径是否正常跳转PC端页面
• http://服务器IP/tools/是否正常打开
• http://服务器IP/openmobile/是否正常打开
• 登录页面是否正常显示
• 登录后接口请求是否正常
• 浏览器控制台是否有404、502或跨域错误

如果前端页面能打开但接口失败，应优先检查Nginx代理和后端容器状态。

七、常见部署问题与解决方案

1、前端构建报错

常见原因包括npm依赖冲突和浏览器环境变量问题。

已知情况：

• Vite 6.x与部分JSX插件存在兼容问题
• 项目已适配--legacy-peer-deps宽松安装策略
• window is not defined问题已通过浏览器环境判断进行防护

如果构建失败，可重新执行：

docker compose build nginx

或重新构建全部服务：

docker compose up -d --build

不要频繁重复构建后端容器，以免造成服务短时间不可用。

2、前端页面出现404

排查方向：

• Nginx配置文件是否正确挂载
• 前端静态资源是否构建成功
• 访问路径是否为/tools/或/openmobile/
• deploy/nginx/default.conf中的路由前缀是否匹配
• 容器内静态文件目录是否存在

可以查看Nginx日志：

docker compose logs -f nginx

3、接口出现502 Bad Gateway

这是部署中较高频的问题。

常见根因是后端容器正在重启或刚被重新构建，端口尚未监听，Nginx转发到后端失败。此时通常不是Nginx配置错误。

常见触发场景：

• 频繁执行docker compose up -d --build
• 自动发布脚本重复重建后端
• 后端启动时间较长
• 后端容器因异常反复重启

排查容器运行信息：

docker inspect iyque-backend

查看容器事件日志：

docker events --since "2026-05-26T12:43:00" --until "2026-05-26T12:45:00"

查看后端日志：

docker compose logs -f backend

处理思路：

1. 等待后端完全启动。
2. 确认后端容器没有反复重启。
3. 避免无意义重复构建。
4. 确认Nginx代理的服务名和端口与Compose一致。

4、数据库表不存在

如果后端日志提示某张表不存在，通常说明iyque_db.sql未完整导入，或SQL版本落后于当前代码。

重点检查以下表是否存在：

iyque_ai_conversation
iyque_ai_conversation_message
iyque_tag
iyque_tag_group

缺失时需要执行对应SQL补丁。

5、数据库列不存在

如果日志出现：

Unknown column

应检查数据库字段命名是否与Java实体类一致。

标签相关表需要使用驼峰字段名，例如：

tagId
groupId
tagType
orderNumber
delFlag

不要改成：

tag_id
group_id
tag_type
order_number
del_flag

6、登录失败

登录失败优先检查配置注入，而不是数据库用户表。

排查顺序：

1. 查看当前环境变量是否生效。
2. 检查后端容器启动日志。
3. 确认账号密码是否被自定义配置覆盖。
4. 检查前端请求是否正确转发到后端。
5. 确认后端接口是否返回正常响应。

八、生产环境建议

正式部署时，建议完成以下加固和运维设置：

• 修改MySQL Root密码和MinIO默认密码
• 使用正式域名配置文件访问地址
• 为Nginx配置HTTPS证书
• 限制MySQL、Redis、MinIO、Milvus等端口只在内网访问
• 定期备份MySQL数据库和MinIO文件
• 为Docker日志配置轮转
• 避免在业务高峰期执行--build
• 使用固定镜像版本和明确发布流程
• 保存数据库补丁SQL和执行记录
• 设置容器健康检查和异常告警

更多阅读：《Docker教程》

• 

  广告合作

• 

  QQ群号：4114653