Inicio Explorar Axuda
Iniciar sesión
yp_web
/
sj-miniprogram
17
0
Fork 0
Ficheiros Incidencias 0 Pull Requests 0 Wiki
Rama: master
Ramas Etiquetas
sj-miniprogram
/
online-service
/
backend-service
/
docs
/
完整部署手册.md

完整部署手册.md 13 KB
Permalink Histórico Raw

审计之家 · 在线客服系统 · 完整部署手册

适用范围：本手册适用于在 Windows 环境下从零开始搭建审计之家在线客服系统的全栈开发环境。

技术栈：Java 17 + Spring Boot 2.7 + MySQL 8.0 + Redis 7 + Vue 3 + WebSocket

📁 一、项目文件位置说明

所有后端服务文件均位于以下目录：

e:\Item\shenjizhijia2\online-service\backend-service\
├── README.md                        ← 项目总说明
├── docs\
│   ├── 完整部署手册.md              ← 本文档
│   ├── API接口文档.md               ← REST API 接口清单
│   ├── WebSocket消息协议.md         ← WebSocket 消息格式说明
│   ├── 数据库设计.sql               ← 8 张数据表建表 SQL
│   └── 在线沟通对接接入说明.md       ← 前端接入使用说明
└── ruoyi-chat\                      ← Java 后端项目根目录
    ├── pom.xml                      ← Maven 依赖配置（JDK 17）
    └── src\main\
        ├── resources\
        │   ├── application.yml      ← 主配置文件
        │   ├── application-dev.yml  ← 开发环境配置（⚠️ 修改数据库密码）
        │   └── mapper\              ← MyBatis SQL 映射文件
        └── java\com\ruoyi\chat\
            ├── RuoyiChatApplication.java   ← 启动入口
            ├── config\                     ← WebSocket、跨域配置
            ├── controller\                 ← REST API 控制器
            ├── domain\                     ← 数据库实体类
            ├── dto\                        ← 数据传输对象
            ├── mapper\                     ← MyBatis Mapper 接口
            ├── service\                    ← 业务逻辑层
            └── websocket\                  ← WebSocket 消息处理器

前端项目位置：

端 路径 访问端口
PC 坐席端 e:\Item\shenjizhijia2\online-service\pc-web-preview http://localhost:5173
PC 商家端 e:\Item\shenjizhijia2\merchant-chat-pc http://localhost:5174
微信小程序端 e:\Item\shenjizhijia2（根目录） HBuilderX 运行

🖥️ 二、环境要求

2.1 必装软件

软件 版本要求 用途 下载地址
JDK 17（必须，不可用其他版本） 运行 Java 后端 Oracle JDK 17
Maven 3.8.x 及以上 编译 Java 项目 Maven 下载
MySQL 8.0 及以上 主数据库 MySQL Installer
Redis 7.x（Windows 版） 缓存、会话存储 Redis for Windows
Node.js 18.x 及以上 运行前端项目 Node.js 官网
HBuilderX 最新版 运行微信小程序端 HBuilderX 下载

2.2 可选软件

软件 用途 说明
MinIO 文件/图片对象存储 不安装则使用本地文件夹存储，功能一致
IntelliJ IDEA Java 开发 IDE 推荐用于查看和修改后端代码

🔧 三、安装步骤（Windows 环境）

步骤 1：安装 JDK 17

  1. 打开下载地址，选择 Windows x64 Installer（.exe 格式）并下载安装
  2. 安装路径建议保持默认，如 C:\Program Files\Java\jdk-17
  3. 配置环境变量（关键步骤）：
    • 右键"此电脑" → 属性 → 高级系统设置 → 环境变量
    • 在"系统变量"中新建：
      • 变量名：JAVA_HOME
      • 变量值：C:\Program Files\Java\jdk-17（你的实际安装路径）
    • 找到系统变量中的 Path，点击编辑，新增一行：%JAVA_HOME%\bin

  4. 打开新的命令行窗口，运行验证：

    java -version
# 期望看到: java version "17.x.x"

步骤 2：安装 Maven 3.8+

  1. 打开下载地址，下载 Binary zip archive（如 apache-maven-3.9.6-bin.zip）
  2. 将 zip 解压至 C:\maven（路径不要含中文和空格）
  3. 配置环境变量：
    • 在系统变量 Path 中新增：C:\maven\bin

  4. 验证：

    mvn -version
# 期望看到: Apache Maven 3.x.x

  5. 配置阿里云镜像加速（强烈建议，否则下载依赖极慢）：

    • 找到或新建文件：C:\Users\你的用户名\.m2\settings.xml

    • 填入以下内容：

      <?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
https://maven.apache.org/xsd/settings-1.0.0.xsd">
<mirrors>
<mirror>
 <id>aliyunmaven</id>
 <mirrorOf>*</mirrorOf>
 <name>阿里云公共仓库</name>
 <url>https://maven.aliyun.com/repository/public</url>
</mirror>
</mirrors>
</settings>

步骤 3：安装 MySQL 8.0

  1. 下载 MySQL Installer for Windows（选 mysql-installer-community-8.x.x.msi）
  2. 安装类型选择 Developer Default
  3. 安装过程中设置 root 用户密码（请务必记住）

  4. 完成安装后，使用命令行验证：

    mysql -u root -p
# 输入密码，能进入 MySQL 命令行即表示成功

步骤 4：安装 Redis（Windows 版）

  1. 下载 Redis for Windows 最新版，选 .msi 安装包
  2. 一路默认安装，安装完成后 Redis 会自动注册为 Windows 服务并启动

  3. 验证：

    redis-cli ping
# 返回 PONG 表示 Redis 正在运行

步骤 5：安装 Node.js

  1. 下载 LTS 长期支持版（18.x 或 20.x）

  2. 默认安装，安装完成验证：

    node -v
npm -v

🗄️ 四、数据库初始化

完成 MySQL 安装后执行以下步骤。

4.1 执行建表脚本

打开命令提示符（管理员权限），执行：

# 方式一：直接导入（推荐）
mysql -u root -p < "e:\Item\shenjizhijia2\online-service\backend-service\docs\数据库设计.sql"

# 方式二：登录后手动执行
mysql -u root -p
# 进入 MySQL 后执行：
source e:/Item/shenjizhijia2/online-service/backend-service/docs/数据库设计.sql;

4.2 验证数据库创建成功

USE sjzj_chat;
SHOW TABLES;

期望输出（8 张表）：

+------------------------+
| Tables_in_sjzj_chat    |
+------------------------+
| cs_file_resource       |   ← 文件资源表
| cs_message             |   ← 聊天消息表（核心）
| cs_order_card          |   ← 结算单表（60s倒计时）
| cs_read_record         |   ← 消息已读记录
| cs_seat_config         |   ← 坐席配置表
| cs_seat_waiter         |   ← 坐席-客服关联表
| cs_session             |   ← 会话表（核心）
| cs_ticket              |   ← 工单表
+------------------------+

⚙️ 五、后端配置修改

这是必须进行的操作，否则后端无法连接数据库。

打开文件：

e:\Item\shenjizhijia2\online-service\backend-service\ruoyi-chat\src\main\resources\application-dev.yml

只需修改以下几处（用你实际的值替换）：

spring:
  datasource:
    # ⚠️ 修改这里：url 中的 localhost:3306 如果 MySQL 不在本机需要改成对应 IP
    url: jdbc:mysql://localhost:3306/sjzj_chat?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&serverTimezone=GMT%2B8&allowPublicKeyRetrieval=true
    username: root           # ← 修改为你的 MySQL 用户名
    password: 123456         # ← ⚠️ 修改为你安装 MySQL 时设置的密码

  redis:
    host: localhost          # Redis 地址（本机不需要改）
    port: 6379
    password:                # Redis 若无密码留空即可

🚀 六、启动服务

6.1 启动 Redis（若未自动启动）

# 检查 Redis 是否运行
redis-cli ping
# 若未运行，手动启动（找到 Redis 安装目录执行）
redis-server.exe redis.windows.conf

6.2 启动后端 Java 服务

打开命令提示符，执行：

# 进入后端项目目录
cd e:\Item\shenjizhijia2\online-service\backend-service\ruoyi-chat

# 首次运行：下载依赖（需要几分钟，视网络速度）
mvn dependency:resolve

# 启动项目
mvn spring-boot:run

启动成功标志（控制台输出）：

====================================================
 审计之家在线客服系统启动成功！
 API文档：http://localhost:8080/api/chat/doc.html
 WebSocket：ws://localhost:8080/api/chat/ws/chat
====================================================

或打包成 JAR 文件后运行（适合正式部署）：

mvn clean package -DskipTests
java -jar target/ruoyi-chat-1.0.0.jar

6.3 访问在线 API 文档

后端启动成功后，打开浏览器访问：

http://localhost:8080/api/chat/doc.html

可以在此页面查看并测试所有接口。

6.4 启动 PC 坐席端前端

cd e:\Item\shenjizhijia2\online-service\pc-web-preview
npm install          # 首次运行需要安装依赖
npm run dev
# 启动成功后访问: http://localhost:5173

6.5 启动 PC 商家端前端

cd e:\Item\shenjizhijia2\merchant-chat-pc
npm install
npm run dev
# 启动成功后访问: http://localhost:5174

6.6 启动微信小程序端

  1. 打开 HBuilderX
  2. 菜单：文件 → 打开目录 → 选择 e:\Item\shenjizhijia2
  3. 菜单：运行 → 运行到小程序模拟器 → 微信开发者工具（需已安装微信开发者工具）
  4. 或选择 运行到浏览器 → Chrome 进行 H5 调试

🪣 七、MinIO 文件存储（可选）

不安装 MinIO 也可正常使用，系统会自动将图片/附件存储到本地 uploads/ 目录。 生产环境建议使用 MinIO 进行文件管理。

安装 MinIO

  1. 下载 MinIO for Windows（选 Windows 版 .exe）

  2. 在命令行启动：

    minio.exe server C:\minio-data --console-address ":9001"

  3. 访问 MinIO 控制台：http://localhost:9001

    • 默认账号：minioadmin
    • 默认密码：minioadmin

  4. 在控制台中创建 Bucket：

    • 点击 Create Bucket
    • Bucket 名称填：sjzj-chat
    • 设置为 Public（允许公开访问图片）

启用 MinIO 配置

在 application-dev.yml 中修改：

spring:
  minio:
    enabled: true               # 改为 true
    endpoint: http://localhost:9000
    access-key: minioadmin
    secret-key: minioadmin
    bucket: sjzj-chat

❓ 八、常见问题排查

问题现象 可能原因 解决方案
java 命令不识别 JDK 未安装或环境变量未配置 重新检查 JAVA_HOME 和 Path 配置，重启命令行
mvn 命令不识别 Maven 未安装或 Path 未配置 检查 Maven 的 bin 目录是否加入 Path
数据库连接失败 密码错误或 MySQL 未启动 检查 application-dev.yml 中的密码；检查 MySQL 服务是否运行
WebSocket 连接失败 Redis 未启动 先启动 Redis，再重启后端服务
Maven 下载依赖超时 网络问题 确认已配置阿里云镜像（步骤 3.2）
端口 8080 被占用 有其他服务占用该端口 修改 application.yml 中的 server.port 为其他端口（如 8090）
图片上传失败 uploads/ 目录无写入权限 以管理员权限运行命令行，或修改 file.upload-path 为有权限的目录
前端 npm install 失败 网络或版本问题 执行 npm config set registry https://registry.npmmirror.com 后重试

📊 九、各服务端口汇总

服务 默认端口 访问地址
Java 后端 API 8080 http://localhost:8080/api/chat
API 文档（Knife4j） 8080 http://localhost:8080/api/chat/doc.html
WebSocket 端点 8080 ws://localhost:8080/api/chat/ws/chat
PC 坐席端前端 5173 http://localhost:5173
PC 商家端前端 5174 http://localhost:5174
MySQL 3306 —
Redis 6379 —
MinIO 服务（可选） 9000 http://localhost:9000
MinIO 控制台（可选） 9001 http://localhost:9001

✅ 十、启动检查清单

在正式联调前，请按顺序确认以下项目：

  • JDK 17 已安装，java -version 显示 17.x
  • Maven 已安装，mvn -version 正常显示
  • 阿里云 Maven 镜像已配置
  • MySQL 已安装并启动，密码已记录
  • 已执行 数据库设计.sql，8 张表已创建
  • Redis 已安装并运行，redis-cli ping 返回 PONG
  • application-dev.yml 中的数据库密码已修改为正确值
  • 后端服务已启动，控制台显示"启动成功"
  • 可访问 http://localhost:8080/api/chat/doc.html
  • PC 坐席端已启动，可访问 http://localhost:5173
  • PC 商家端已启动，可访问 http://localhost:5174
  • 微信小程序端在 HBuilderX 中运行正常

文档版本：v1.0 · 2026-03-31