---
title: "03-项目完整启动指南"
created: 2025-12-01
tags:
  - 项目
aliases:
  - 项目完整启动指南
---
# 项目完整启动指南

## 快速启动

### 1️⃣ 启动 Nacos 注册中心

```
cd D:\develop\nacos\bin
startup.cmd -m standalone
```

**预期结果**：浏览器访问 http://localhost:8848/nacos

- 用户名：nacos
- 密码：nacos

![[image-b000d6b9.png]]

![[image-bbc65c2a.png]]

---

### 2️⃣ 编译并启动公共模块

```
cd D:\project\CanvasChain
cd canvaschain-common
mvn clean install
```

**预期结果**：输出 `BUILD SUCCESS`

![[image-b14ebf10.png]]

---

### 3️⃣ 编译并启动三个业务服务

#### user-service（用户服务）- 端口 8010

```
cd D:\project\CanvasChain\services\user-service

# 清理 + 编译 + 打包
mvn -s D:\project\CanvasChain\.mvn\settings.xml -U -q -DskipTests clean package

# 启动（会自动创建数据库）
java "-Dspring.datasource.url=jdbc:mysql://127.0.0.1:3306/canvaschain?createDatabaseIfNotExist=true&useSSL=false&serverTimezone=UTC" ^
     "-Dspring.datasource.username=root" ^
     "-Dspring.datasource.password=zw200495" ^
     "-Dspring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver" ^
     -jar target/user-service-0.0.1-SNAPSHOT.jar ^
     --server.port=8010
```

**预期结果**：日志显示 `Registering Nacos...` 和 `Started UserServiceApplication`

![[image-7fb4aaf7.png]]![[image-94aa0018.png]]

#### artwork-service（作品服务）- 端口 8020

```
cd D:\project\CanvasChain\services\artwork-service

mvn -s D:\project\CanvasChain\.mvn\settings.xml -U -q -DskipTests clean package

java -jar target/artwork-service-0.0.1-SNAPSHOT.jar --server.port=8020
```

**预期结果**：日志显示 `Registering Nacos...` 和 `Started ArtworkServiceApplication`

![[image-1207ee72.png]]![[image-a2d58e21.png]]

#### auction-service（拍卖服务）- 端口 8030

```
cd D:\project\CanvasChain\services\auction-service

mvn -s D:\project\CanvasChain\.mvn\settings.xml -U -q -DskipTests clean package

java -jar target/auction-service-0.0.1-SNAPSHOT.jar --server.port=8030
```

**预期结果**：日志显示 `Registering Nacos...` 和 `Started AuctionServiceApplication`

![[image-587bc5be.png]]

---

### 4️⃣ 启动网关 - 端口 8080

```
cd D:\project\CanvasChain\gateway

mvn clean package -DskipTests

java -jar target/gateway-0.0.1-SNAPSHOT.jar --server.port=8080
```

**预期结果**：日志显示 `Started GatewayApplication`

![[image-bc070ed8.png]]

![[image-f2fa4f00.png]]

![[image-38e30fb9.png]]

---

### 5️⃣ 启动前端

```bash
cd D:\project\CanvasChain\frontend
npm install
npm run dev
```

**预期结果**：浏览器自动打开 <http://localhost:5173>

![[image-6f12c8bc.png]]

---

## 完整启动时间轴

| 序号 | 组件 | 端口 | 启动命令窗口 | 预期时间 |
| --- | --- | --- | --- | --- |
| 1 | Nacos | 8848 | 新窗口 | 5 秒 |
| 2 | canvaschain-common | - | 原窗口 | 3 秒 |
| 3 | user-service | 8010 | 新窗口 1 | 10 秒 |
| 4 | artwork-service | 8020 | 新窗口 2 | 10 秒 |
| 5 | auction-service | 8030 | 新窗口 3 | 10 秒 |
| 6 | gateway | 8080 | 新窗口 4 | 10 秒 |
| 7 | frontend | 5173 | 新窗口 5 | 5 秒 |

**总耗时**：约 2-3 分钟（第一次因为下载依赖会慢一点）

---

## 常见问题与解决方案

### 问题 1：Nacos 启动失败

**现象**：运行 `startup.cmd -m standalone`，报错：

```
Failed to bind to address 0.0.0.0/0.0.0.0:9848
java.net.BindException: Address already in use: bind
```

---

**原因：**

**1. Nacos 2.x 需要多个端口**

| **端口** | **用途** |
| --- | --- |
| 8848 | HTTP 主端口 |
| 9848 | gRPC 客户端端口 (主端口 + 1000) |
| 9849 | gRPC 服务端端口 (主端口 + 1001) |

**2. Windows 动态端口范围冲突**

查看系统动态端口配置：

```
netsh int ipv4 show dynamicport tcp
```

发现问题：

```
启动端口 : 1024
端口数   : 13977
```

这意味着 Windows 会在 **1024 ~ 15000** 范围内随机分配临时端口，而 **9848** 正好在这个范围内，可能被其他程序占用。

**3. 根本原因**

Windows 的临时端口范围包含了 Nacos gRPC 端口 9848，导致端口被随机占用。

---

**解决方案**

**方案一：修改 Windows 动态端口范围（推荐）**

**步骤 1：以管理员身份运行 CMD，执行：**

```
netsh int ipv4 set dynamicport tcp start=49152 num=16384
netsh int ipv4 set dynamicport udp start=49152 num=16384
```

**步骤 2：重启电脑**（设置需要重启才能生效）

**步骤 3：验证设置**

```
netsh int ipv4 show dynamicport tcp
```

应显示：

```
启动端口 : 49152
端口数   : 16384
```

**步骤 4：启动 Nacos**

```
cd /d D:\develop\nacos
startup.cmd -m standalone
```

---

**方案二：更换 Nacos 端口（临时方案）**

如果不想重启电脑，可以修改 Nacos 使用的端口：

**修改** `D:\develop\nacos\conf\application.properties`：

```properties
server.port=8858
```

这样 Nacos 会使用：

- HTTP：8858
- gRPC：9858、9859

| **项目** | **说明** |
| --- | --- |
| **问题** | Windows 动态端口范围 (1024-15000) 包含 Nacos gRPC 端口 9848 |
| **原因** | 9848 端口可能被其他程序随机占用 |
| **解决** | 将动态端口范围改为 49152-65535，避开 Nacos 端口 |
| **关键** | 修改后必须重启电脑才能生效 |

---

### 问题 2：Maven 编译超时

**现象**：`mvn package` 卡住不动 5 分钟以上

**原因**：

- 第一次编译下载依赖慢
- Maven 镜像源响应慢

**解决**：

```
# 方案 A：使用 settings.xml 配置国内镜像
mvn -s D:\project\CanvasChain\.mvn\settings.xml clean package

# 方案 B：强制更新依赖（跳过本地缓存）
mvn -U clean package

# 方案 C：清理依赖缓存重新下载
cd %USERPROFILE%\.m2
rmdir /s repository
mvn clean package
```

---

### 问题 3：user-service 启动报错

**现象**：

```
Error: Could not find or load main class
```

**原因**：

- JAR 包没有生成
- 版本号不匹配

**解决**：

```
# 1. 检查 JAR 是否存在
dir D:\project\CanvasChain\services\user-service\target\

# 2. 如果不存在，检查编译错误
mvn clean package -DskipTests

# 3. 如果版本不同，调整命令
# 比如 user-service-0.0.1-SNAPSHOT.jar 改成实际的版本号
```

---

### 问题 4：端口被占用

**现象**：

```
Address already in use: bind
```

**原因**：端口已被其他进程占用

**解决 Windows**：

```
# 查看占用 8080 端口的进程
netstat -ano | findstr :8080

# 假设 PID 为 1234，强制关闭
taskkill /PID 1234 /F

# 或者改用其他端口启动
java -jar target/gateway-0.0.1-SNAPSHOT.jar --server.port=8081
```

---

### 问题 5：连接 MySQL 失败

**现象**：

```
java.sql.SQLException: Access denied for user 'root'@'localhost'
```

**原因**：

- MySQL 未启动
- 用户名/密码错误
- MySQL 端口不是 3306

**解决**：

```
# 1. 启动 MySQL（如果是 Windows 服务）
net start MySQL80

# 2. 检查连接字符串中的用户名/密码是否正确
# 在启动命令中：
# -Dspring.datasource.username=root
# -Dspring.datasource.password=zw200495

# 3. 测试连接
mysql -h 127.0.0.1 -u root -pzw200495
```

---

### 问题 6：Redis/RabbitMQ 连接失败

**现象**：

```
Cannot get a resource, pool is exhausted
redis.clients.jedis.exceptions.JedisConnectionException
```

**原因**：

- Redis/RabbitMQ 未启动
- 配置中的主机/端口错误

**解决**：

```
# 启动 Redis（如果用了）
redis-server.exe

# 启动 RabbitMQ（如果用了）
# 通常在 RabbitMQ/sbin 目录
rabbitmq-server.bat
```

---

### 问题 7：前端 npm 依赖缺失

**现象**：

```
npm ERR! Missing required argument: list
```

**原因**：`node_modules` 未初始化

**解决**：

```bash
cd D:\project\CanvasChain\frontend

# 清理旧的 node_modules
rmdir /s /q node_modules

# 重新安装依赖
npm install

# 启动开发服务
npm run dev
```

---

## 简化启动脚本（推荐）

如果每次都要输这么多命令很烦，可以用批处理脚本：

### startup.bat（Windows）

```
@echo off
chcp 65001 >nul

:: 获取脚本所在目录作为项目根目录
set PROJECT_ROOT=%~dp0
:: 去掉末尾的反斜杠
set PROJECT_ROOT=%PROJECT_ROOT:~0,-1%

echo ========================================
echo   CanvasChain 一键启动
echo ========================================
echo   项目目录: %PROJECT_ROOT%
echo ========================================
echo.

:: 1. 启动 Nacos
echo [1/7] 启动 Nacos...
start "Nacos" cmd /k "cd /d D:\develop\nacos\bin && startup.cmd -m standalone"
timeout /t 10 /nobreak >nul
echo       Nacos 已启动
echo.

:: 2. 编译公共模块
echo [2/7] 编译公共模块...
cd /d "%PROJECT_ROOT%\canvaschain-common"
call mvn clean install -DskipTests
if errorlevel 1 (
    echo [错误] 公共模块编译失败！
    pause
    exit /b 1
)
echo       公共模块编译完成
echo.

:: 3. 启动 user-service
echo [3/7] 编译并启动 user-service...
cd /d "%PROJECT_ROOT%\services\user-service"
call mvn -s "%PROJECT_ROOT%\.mvn\settings.xml" -U -DskipTests clean package
if errorlevel 1 (
    echo [错误] user-service 编译失败！
    pause
    exit /b 1
)
start "user-service" cmd /k "cd /d "%PROJECT_ROOT%\services\user-service" && java -Dspring.datasource.url=jdbc:mysql://127.0.0.1:3306/canvaschain?createDatabaseIfNotExist=true^&useSSL=false^&serverTimezone=UTC -Dspring.datasource.username=root -Dspring.datasource.password=zw200495 -Dspring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver -jar target/user-service-0.0.1-SNAPSHOT.jar --server.port=8010"
echo       user-service 已启动
echo.

:: 4. 启动 artwork-service
echo [4/7] 编译并启动 artwork-service...
cd /d "%PROJECT_ROOT%\services\artwork-service"
call mvn -s "%PROJECT_ROOT%\.mvn\settings.xml" -U -DskipTests clean package
if errorlevel 1 (
    echo [错误] artwork-service 编译失败！
    pause
    exit /b 1
)
start "artwork-service" cmd /k "cd /d "%PROJECT_ROOT%\services\artwork-service" && java -jar target/artwork-service-0.0.1-SNAPSHOT.jar --server.port=8020"
echo       artwork-service 已启动
echo.

:: 5. 启动 auction-service
echo [5/7] 编译并启动 auction-service...
cd /d "%PROJECT_ROOT%\services\auction-service"
call mvn -s "%PROJECT_ROOT%\.mvn\settings.xml" -U -DskipTests clean package
if errorlevel 1 (
    echo [错误] auction-service 编译失败！
    pause
    exit /b 1
)
start "auction-service" cmd /k "cd /d "%PROJECT_ROOT%\services\auction-service" && java -jar target/auction-service-0.0.1-SNAPSHOT.jar --server.port=8030"
echo       auction-service 已启动
echo.

:: 6. 启动 gateway
echo [6/7] 编译并启动 gateway...
cd /d "%PROJECT_ROOT%\gateway"
call mvn clean package -DskipTests
if errorlevel 1 (
    echo [错误] gateway 编译失败！
    pause
    exit /b 1
)
start "gateway" cmd /k "cd /d "%PROJECT_ROOT%\gateway" && java -jar target/gateway-0.0.1-SNAPSHOT.jar --server.port=8080"
echo       gateway 已启动
echo.

:: 7. 启动前端
echo [7/7] 启动前端...
cd /d "%PROJECT_ROOT%\frontend"
if not exist "node_modules" (
    echo       首次运行，安装依赖...
    call npm install
    if errorlevel 1 (
        echo [错误] npm install 失败！
        pause
        exit /b 1
    )
)
start "frontend" cmd /k "cd /d "%PROJECT_ROOT%\frontend" && npm run dev"
echo       前端已启动
echo.

echo ========================================
echo   全部启动完成！
echo ========================================
echo   Nacos:    http://localhost:8848/nacos
echo   Gateway:  http://localhost:8080
echo   Frontend: http://localhost:5173
echo ========================================
pause
```

**使用方式**：

```
# 将上面的脚本保存为 startup.bat
# 放在项目根目录
# 双击运行即可

D:\project\CanvasChain\startup.bat
```

stop-all.bat：

```
@echo off
chcp 65001 >nul
echo ========================================
echo   停止所有 CanvasChain 服务
echo ========================================
echo.

echo 停止 Java 服务...
taskkill /F /FI "WINDOWTITLE eq user-service*" 2>nul
taskkill /F /FI "WINDOWTITLE eq artwork-service*" 2>nul
taskkill /F /FI "WINDOWTITLE eq auction-service*" 2>nul
taskkill /F /FI "WINDOWTITLE eq Gateway*" 2>nul
taskkill /F /FI "WINDOWTITLE eq Nacos*" 2>nul

echo 停止 Node 服务...
taskkill /F /FI "WINDOWTITLE eq Frontend*" 2>nul

echo.
echo 所有服务已停止
pause
```

---

## 日常开发快速参考

### 只改后端代码

```
# 1. 进入对应服务目录
cd D:\project\CanvasChain\services\user-service

# 2. 重新编译打包（Maven 会检测变化）
mvn clean package -DskipTests

# 3. 重启该服务（关闭旧窗口，运行新的 java -jar 命令）
```

### 只改前端代码

```
# 前端启用了热更新，修改代码后自动刷新，无需重启
cd D:\project\CanvasChain\frontend
npm run dev
# 浏览器会自动重新加载
```

### 改了公共模块

```
# 1. 重新安装公共模块
cd D:\project\CanvasChain\canvaschain-common
mvn clean install

# 2. 重启所有依赖公共模块的服务（即所有业务服务）
```

---

## 端口速查表

| 组件 | 端口 | 用途 |
| --- | --- | --- |
| Nacos | 8848 | 服务注册中心 + 管理控制台 |
| user-service | 8010 | 用户服务 API |
| artwork-service | 8020 | 作品服务 API |
| auction-service | 8030 | 拍卖服务 API |
| gateway | 8080 | API 网关（唯一对外端口） |
| frontend | 5173 | 前端开发服务器 |
| MySQL | 3306 | 数据库 |
| Redis | 6379 | 缓存（如果用到） |
| RabbitMQ | 5672 | 消息队列（如果用到） |

---

## 完全重启项目（清理所有）

```
# 如果遇到诡异问题，用这个方案
cd D:\project\CanvasChain

# 1. 清理所有编译文件
mvn clean

# 2. 清理所有 JAR 包
for /r %%i in (target) do @rmdir /s /q "%%i"

# 3. 清理 Maven 本地缓存（可选，会重新下载所有依赖）
rmdir /s /q %USERPROFILE%\.m2\repository

# 4. 重新编译所有模块
mvn package -DskipTests

# 5. 按上面的步骤重新启动所有组件
```

---

## 记住这个顺序

```
启动顺序（重要）
    ↓
1. Nacos（注册中心先启）
    ↓
2. canvaschain-common（公共模块先装）
    ↓
3. 三个业务服务（都依赖 Nacos）
    ↓
4. Gateway（依赖业务服务已注册）
    ↓
5. Frontend（最后启，调用已准备好的 Gateway）
```

**记住：一定不要倒序启动，否则服务会相互找不到！**

---

**项目分区导航**：⬅️ [[02-微服务架构划分与协作：最小最佳实践|02-微服务架构划分与协作：最小最佳实践]] | 03-项目完整启动指南 | ➡️ [[04-技术栈完善指南|04-技术栈完善指南]]