student-management/docs/DEPLOYMENT.md

# 部署与常见问题手册

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

---

## 目录

- [环境要求](#环境要求)
- [通用部署流程](#通用部署流程)
- [Windows 部署指南](#windows-部署指南)
- [Mac M1 部署指南](#mac-m1-部署指南)
- [常见错误与解决方案](#常见错误与解决方案)
- [Maven 推荐配置](#maven-推荐配置)
- [更新部署流程](#更新部署流程)

---

## 环境要求

| 组件 | 版本要求 | 说明 |
|------|----------|------|
| 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. 初始化数据库

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

### 2. 修改数据库配置

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

```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. 编译打包

```bash
mvn clean package
```

成功后 WAR 包路径：

```
target/student-management.war
```

### 4. 访问地址

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

### 5. 测试账号

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

---

## Windows 部署指南

### 安装 JDK 并配置 JAVA_HOME

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

```cmd
echo %JAVA_HOME%
java -version
```

### 安装 Tomcat

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

### 部署 WAR

**方法一：资源管理器**

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

**方法二：PowerShell**

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

### 启动 / 停止 Tomcat

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

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

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

```cmd
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）

```bash
# 安装 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）

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

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

### 编译打包（Mac）

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

### 部署 WAR 到 Tomcat（Mac）

**Homebrew 安装的 Tomcat 9：**

```bash
# 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：**

```bash
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**。若端口冲突，编辑：

```bash
# 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：

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

```bash
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 — 强制重新下载**

```bash
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 — 永久配置：**

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

**Windows — 临时配置：**

```cmd
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 — 永久配置：**

```bash
# 查看 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 — 临时配置：**

```bash
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 缺少项目上下文路径

**解决方案：**

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

---

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

**原因：**

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

**解决方案：**

```bash
# 检查 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：**

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

**Mac：**

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

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

```powershell
# 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

```bash
# 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/`