学生管理系统作业

14 KiB

Raw Permalink Blame History

部署与常见问题手册

本文档整理了项目部署过程中遇到的典型错误及解决方案，分别提供 Windows 和 Mac M1（Apple Silicon） 两套操作说明。

环境要求

组件	版本要求	说明
JDK	1.8+（推荐 8 或 11）	Tomcat 9 支持 Java 8–21
Maven	3.6+	构建 WAR 包
MySQL	8.x	数据存储
Tomcat	9.x	Web 容器

Mac M1 注意：请安装 ARM64（aarch64） 版本的 JDK 和 Tomcat，或通过 Homebrew 安装（会自动选择正确架构）。

通用部署流程

无论 Windows 还是 Mac，基本步骤一致：

1. 初始化 MySQL 数据库
2. 修改 db.properties 数据库连接配置
3. mvn clean package 打包
4. 复制 WAR 到 Tomcat/webapps
5. 启动 Tomcat
6. 浏览器访问 http://localhost:8080/student-management/

1. 初始化数据库

mysql -u root -p < src/main/resources/db_init.sql

2. 修改数据库配置

编辑 src/main/resources/db.properties：

jdbc.driver=com.mysql.cj.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/student_db?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&useSSL=false
jdbc.username=root
jdbc.password=你的密码

修改后需重新执行 mvn clean package。

3. 编译打包

mvn clean package

成功后 WAR 包路径：

target/student-management.war

4. 访问地址

http://localhost:8080/student-management/

5. 测试账号

角色	用户名	密码
管理员	admin	admin123
一般用户	zhangsan	user123

Windows 部署指南

安装 JDK 并配置 JAVA_HOME

安装 JDK（如 C:\Program Files\Java\jdk-21）
Win + R → 输入 sysdm.cpl → 高级 → 环境变量
新建系统变量：
- 变量名：JAVA_HOME
- 变量值：C:\Program Files\Java\jdk-21（按实际路径填写）
编辑 Path，新增：%JAVA_HOME%\bin
新开 cmd 验证：

echo %JAVA_HOME%
java -version

安装 Tomcat

下载 Tomcat 9：https://tomcat.apache.org/download-90.cgi
选择 64-bit Windows zip，解压到如 D:\apache-tomcat-9.0.98

部署 WAR

方法一：资源管理器

复制 target\student-management.war
粘贴到 D:\apache-tomcat-9.0.98\webapps\

方法二：PowerShell

Copy-Item "D:\codefiles\javaweb-homework\student-management\target\student-management.war" `
          "D:\apache-tomcat-9.0.98\webapps\"

启动 / 停止 Tomcat

:: 启动（需先设置 JAVA_HOME，见下方临时方案）
D:\apache-tomcat-9.0.98\bin\startup.bat

:: 停止
D:\apache-tomcat-9.0.98\bin\shutdown.bat

临时设置 JAVA_HOME 后启动（未配环境变量时）：

set JAVA_HOME=C:\Program Files\Java\jdk-21
set JRE_HOME=C:\Program Files\Java\jdk-21
cd /d D:\apache-tomcat-9.0.98\bin
startup.bat

Mac M1 部署指南

安装依赖（Homebrew）

# 安装 Homebrew（如未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 JDK（ARM64 原生版本）
brew install openjdk@17

# 配置 JAVA_HOME（Apple Silicon 路径）
echo 'export JAVA_HOME="/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home"' >> ~/.zshrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证
java -version
echo $JAVA_HOME

# 安装 Maven
brew install maven

# 安装 MySQL
brew install mysql
brew services start mysql

# 安装 Tomcat 9
brew install tomcat@9

Intel Mac 用户：Homebrew 前缀为 /usr/local 而非 /opt/homebrew，JDK 路径类似 /usr/local/opt/openjdk@17/...。

初始化数据库（Mac）

# 首次安装 MySQL 后设置 root 密码（按提示操作）
mysql_secure_installation

# 导入数据
cd /path/to/student-management
mysql -u root -p < src/main/resources/db_init.sql

编译打包（Mac）

cd /path/to/student-management
mvn clean package

部署 WAR 到 Tomcat（Mac）

Homebrew 安装的 Tomcat 9：

# Tomcat 目录（M1 默认）
TOMCAT_HOME="/opt/homebrew/opt/tomcat@9/libexec"

# 复制 WAR
cp target/student-management.war "$TOMCAT_HOME/webapps/"

# 启动 Tomcat
brew services start tomcat@9

# 停止 Tomcat
brew services stop tomcat@9

# 查看日志
tail -f "$TOMCAT_HOME/logs/catalina.out"

手动解压的 Tomcat：

TOMCAT_HOME="$HOME/apache-tomcat-9.0.98"

cp target/student-management.war "$TOMCAT_HOME/webapps/"
"$TOMCAT_HOME/bin/startup.sh"

Mac 访问地址

http://localhost:8080/student-management/

Homebrew 版 Tomcat 9 默认端口为 8080。若端口冲突，编辑：

# M1
/opt/homebrew/opt/tomcat@9/libexec/conf/server.xml

# 修改 <Connector port="8080" ...> 为其他端口

Mac 常用命令对照

操作	Windows	Mac M1
环境变量文件	系统设置 / cmd `set`	`~/.zshrc`
启动 Tomcat	`startup.bat`	`startup.sh` 或 `brew services start tomcat@9`
停止 Tomcat	`shutdown.bat`	`shutdown.sh` 或 `brew services stop tomcat@9`
复制 WAR	`Copy-Item` / 资源管理器	`cp`
Maven 配置	`C:\Users\用户名\.m2\settings.xml`	`~/.m2/settings.xml`

常见错误与解决方案

错误 1：Maven 代理连接失败

报错信息：

Connect to 127.0.0.1:7890 failed: Connection refused: no further information
Could not transfer artifact ... from/to central (https://repo.maven.apache.org/maven2)

原因：

~/.m2/settings.xml（Windows：C:\Users\用户名\.m2\settings.xml）中配置了 HTTP 代理 127.0.0.1:7890（Clash、V2Ray 等），但代理软件未启动。

解决方案（二选一）：

方案	操作
A. 不使用代理	将 settings.xml 中 proxy 的 `<active>true</active>` 改为 `<active>false</active>`
B. 使用代理	先启动 Clash 等代理软件，保持 `<active>true</active>`

错误 2：依赖下载失败被缓存，无法重试

报错信息：

failed to transfer from https://repo.maven.apache.org/maven2 during a previous attempt.
This failure was cached in the local repository and resolution is not reattempted
until the update interval of central has elapsed or updates are forced.

未解析的依赖项: 'javax.servlet:javax.servlet-api:jar:4.0.1'
未解析的依赖项: 'mysql:mysql-connector-java:jar:8.0.33'
...

原因：

错误 1 导致的下载失败被 Maven 写入本地仓库缓存（.lastUpdated 文件），后续不会自动重试。

解决方案：

步骤 1 — 清理失败缓存

Windows PowerShell：

$paths = @(
  "$env:USERPROFILE\.m2\repository\javax\servlet\javax.servlet-api\4.0.1",
  "$env:USERPROFILE\.m2\repository\javax\servlet\jsp\javax.servlet.jsp-api\2.3.3",
  "$env:USERPROFILE\.m2\repository\javax\servlet\jstl\1.2",
  "$env:USERPROFILE\.m2\repository\mysql\mysql-connector-java\8.0.33",
  "$env:USERPROFILE\.m2\repository\commons-fileupload\commons-fileupload\1.5",
  "$env:USERPROFILE\.m2\repository\commons-io\commons-io\2.11.0"
)
foreach ($p in $paths) { if (Test-Path $p) { Remove-Item $p -Recurse -Force } }
Get-ChildItem "$env:USERPROFILE\.m2\repository" -Recurse -Filter "*.lastUpdated" | Remove-Item -Force

Mac / Linux：

rm -rf ~/.m2/repository/javax/servlet/javax.servlet-api/4.0.1
rm -rf ~/.m2/repository/javax/servlet/jsp/javax.servlet.jsp-api/2.3.3
rm -rf ~/.m2/repository/javax/servlet/jstl/1.2
rm -rf ~/.m2/repository/mysql/mysql-connector-java/8.0.33
rm -rf ~/.m2/repository/commons-fileupload/commons-fileupload/1.5
rm -rf ~/.m2/repository/commons-io/commons-io/2.11.0
find ~/.m2/repository -name "*.lastUpdated" -delete

步骤 2 — 强制重新下载

mvn -U clean compile

-U 表示强制更新，忽略失败缓存。

步骤 3 — IDEA 刷新

右侧 Maven 面板 → 点击 Reload All Maven Projects（刷新按钮）。

错误 3：Tomcat 启动报 JAVA_HOME 未定义

报错信息：

Neither the JAVA_HOME nor the JRE_HOME environment variable is defined
At least one of these environment variable is needed to run this program

原因：

系统未配置 JAVA_HOME，Tomcat 找不到 Java。

解决方案：

Windows — 永久配置：

Win + R → sysdm.cpl → 高级 → 环境变量
新建系统变量 JAVA_HOME = JDK 安装目录（如 C:\Program Files\Java\jdk-21）
Path 中添加 %JAVA_HOME%\bin
重新打开 cmd，执行 startup.bat

Windows — 临时配置：

set JAVA_HOME=C:\Program Files\Java\jdk-21
set JRE_HOME=C:\Program Files\Java\jdk-21
cd /d D:\apache-tomcat-9.0.98\bin
startup.bat

Mac M1 — 永久配置：

# 查看 JDK 路径
/usr/libexec/java_home -V

# 写入 ~/.zshrc（以 OpenJDK 17 为例）
echo 'export JAVA_HOME="/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home"' >> ~/.zshrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证
echo $JAVA_HOME
java -version

Mac — 临时配置：

export JAVA_HOME=$(/usr/libexec/java_home)
export JRE_HOME=$JAVA_HOME
~/apache-tomcat-9.0.98/bin/startup.sh

错误 4：页面 404 Not Found

原因：

WAR 未放入 webapps，或 Tomcat 未完成解压
访问 URL 缺少项目上下文路径

解决方案：

确认 webapps 下存在 student-management.war 或 student-management/ 文件夹
访问：http://localhost:8080/student-management/（注意含项目名）
查看 Tomcat 日志确认部署是否成功

错误 5：页面 500 / 数据库连接失败

原因：

MySQL 未启动
db.properties 账号密码错误
未执行 db_init.sql 初始化数据库

解决方案：

# 检查 MySQL 是否运行
# Windows
sc query mysql

# Mac
brew services list | grep mysql

# 测试连接
mysql -u root -p -e "USE student_db; SHOW TABLES;"

确认 db.properties 配置正确后，重新打包并部署 WAR。

错误 6：8080 端口被占用

报错信息（Tomcat 日志）：

Address already in use: bind

解决方案：

Windows：

netstat -ano | findstr :8080
taskkill /PID <进程号> /F

Mac：

lsof -i :8080
kill -9 <PID>

或修改 Tomcat conf/server.xml 中 <Connector port="8080"> 为其他端口（如 8081）。

Maven 推荐配置

将以下内容写入 Maven 用户配置文件：

Windows： C:\Users\你的用户名\.m2\settings.xml
Mac： ~/.m2/settings.xml

<settings>
  <mirrors>
    <mirror>
      <id>aliyunmaven</id>
      <mirrorOf>central</mirrorOf>
      <name>Aliyun Maven</name>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
  </mirrors>

  <!-- 代理软件（Clash 等）未启动时请将 active 设为 false -->
  <proxies>
    <proxy>
      <id>http-proxy</id>
      <active>false</active>
      <protocol>http</protocol>
      <host>127.0.0.1</host>
      <port>7890</port>
    </proxy>
    <proxy>
      <id>https-proxy</id>
      <active>false</active>
      <protocol>https</protocol>
      <host>127.0.0.1</host>
      <port>7890</port>
    </proxy>
  </proxies>
</settings>

IDEA 中确认 Maven 使用该配置：

File → Settings → Build Tools → Maven → User settings file 指向上述 settings.xml。

更新部署流程

代码或配置修改后，按以下步骤重新部署：

Windows

# 1. 重新打包
cd D:\codefiles\javaweb-homework\student-management
mvn clean package

# 2. 停止 Tomcat（shutdown.bat）

# 3. 删除旧部署
Remove-Item "D:\apache-tomcat-9.0.98\webapps\student-management" -Recurse -Force
Remove-Item "D:\apache-tomcat-9.0.98\webapps\student-management.war" -Force

# 4. 复制新 WAR
Copy-Item "target\student-management.war" "D:\apache-tomcat-9.0.98\webapps\"

# 5. 启动 Tomcat（startup.bat）

Mac M1

# 1. 重新打包
cd /path/to/student-management
mvn clean package

# 2. 停止 Tomcat
brew services stop tomcat@9

# 3. 删除旧部署
TOMCAT_HOME="/opt/homebrew/opt/tomcat@9/libexec"
rm -rf "$TOMCAT_HOME/webapps/student-management"
rm -f "$TOMCAT_HOME/webapps/student-management.war"

# 4. 复制新 WAR
cp target/student-management.war "$TOMCAT_HOME/webapps/"

# 5. 启动 Tomcat
brew services start tomcat@9

快速排查清单

遇到问题时按顺序检查：

MySQL 已启动，student_db 数据库存在
db.properties 用户名密码正确
JAVA_HOME 已配置，java -version 正常
Maven settings.xml 代理已关闭或代理软件已启动
依赖无红色报错（必要时 mvn -U clean compile）
WAR 包已复制到 Tomcat webapps/
Tomcat 已成功启动（日志无 ERROR）
浏览器访问 URL 含 /student-management/

14 KiB Raw Permalink Blame History

部署与常见问题手册

目录

环境要求

通用部署流程

1. 初始化数据库

2. 修改数据库配置

3. 编译打包

4. 访问地址

5. 测试账号

Windows 部署指南

安装 JDK 并配置 JAVA_HOME

安装 Tomcat

部署 WAR

启动 / 停止 Tomcat

Mac M1 部署指南

安装依赖（Homebrew）

初始化数据库（Mac）

编译打包（Mac）

部署 WAR 到 Tomcat（Mac）

Mac 访问地址

Mac 常用命令对照

常见错误与解决方案

错误 1：Maven 代理连接失败

错误 2：依赖下载失败被缓存，无法重试

错误 3：Tomcat 启动报 JAVA_HOME 未定义

错误 4：页面 404 Not Found

错误 5：页面 500 / 数据库连接失败

错误 6：8080 端口被占用

Maven 推荐配置

更新部署流程

Windows

Mac M1

快速排查清单

14 KiB

Raw Permalink Blame History