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

> **适用范围**：本手册适用于在 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](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html) |
| **Maven** | 3.8.x 及以上 | 编译 Java 项目 | [Maven 下载](https://maven.apache.org/download.cgi) |
| **MySQL** | 8.0 及以上 | 主数据库 | [MySQL Installer](https://dev.mysql.com/downloads/installer/) |
| **Redis** | 7.x（Windows 版） | 缓存、会话存储 | [Redis for Windows](https://github.com/tporadowski/redis/releases) |
| **Node.js** | 18.x 及以上 | 运行前端项目 | [Node.js 官网](https://nodejs.org/) |
| **HBuilderX** | 最新版 | 运行微信小程序端 | [HBuilderX 下载](https://www.dcloud.io/hbuilderx.html) |

### 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. 打开**新的**命令行窗口，运行验证：
   ```bash
   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. 验证：
   ```bash
   mvn -version
   # 期望看到: Apache Maven 3.x.x
   ```
5. **配置阿里云镜像加速**（强烈建议，否则下载依赖极慢）：
   - 找到或新建文件：`C:\Users\你的用户名\.m2\settings.xml`
   - 填入以下内容：
   ```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. 完成安装后，使用命令行验证：
   ```bash
   mysql -u root -p
   # 输入密码，能进入 MySQL 命令行即表示成功
   ```

### 步骤 4：安装 Redis（Windows 版）

1. 下载 [Redis for Windows 最新版](https://github.com/tporadowski/redis/releases)，选 `.msi` 安装包
2. **一路默认安装**，安装完成后 Redis 会自动注册为 Windows 服务并启动
3. 验证：
   ```bash
   redis-cli ping
   # 返回 PONG 表示 Redis 正在运行
   ```

### 步骤 5：安装 Node.js

1. 下载 **LTS 长期支持版**（18.x 或 20.x）
2. 默认安装，安装完成验证：
   ```bash
   node -v
   npm -v
   ```

---

## 🗄️ 四、数据库初始化

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

### 4.1 执行建表脚本

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

```bash
# 方式一：直接导入（推荐）
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 验证数据库创建成功

```sql
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
```

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

```yaml
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（若未自动启动）

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

### 6.2 启动后端 Java 服务

打开命令提示符，执行：

```bash
# 进入后端项目目录
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 文件后运行**（适合正式部署）：

```bash
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 坐席端前端

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

### 6.5 启动 PC 商家端前端

```bash
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](https://min.io/download)（选 Windows 版 `.exe`）
2. 在命令行启动：
   ```bash
   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` 中修改：

```yaml
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*