englishread-admin/README-restart-script.md

# Java应用启动/重启脚本使用说明

## 概述

`restart-java-app.sh` 是一个用于在Linux系统下管理Java JAR包应用的Shell脚本。它可以自动检测应用是否运行，并提供启动、停止、重启等功能。

## 功能特性

- ✅ 自动检测应用运行状态
- ✅ 优雅停止应用（先发送TERM信号，超时后强制停止）
- ✅ 智能端口检测，避免端口冲突
- ✅ PID文件管理，确保进程跟踪准确
- ✅ 彩色日志输出，便于查看状态
- ✅ 详细的错误处理和状态反馈
- ✅ 支持多种命令选项

## 配置参数

在使用脚本前，需要修改脚本开头的配置参数：

```bash
# ========================================
# 配置参数 - 请根据实际情况修改
# ========================================
JAR_NAME=""                      # JAR包名称（留空则自动检测）
PORT=8080                        # 应用端口号
```

### 主要配置项

| 参数 | 说明 | 示例 |
|------|------|------|
| `JAR_NAME` | JAR包文件名（留空可自动检测） | `"my-spring-boot-app.jar"` 或 `""` |
| `PORT` | 应用监听端口 | `8080` |

**自动检测功能**: 如果将 `JAR_NAME` 留空（`JAR_NAME=""`），脚本会自动检测当前目录下的JAR文件：
- 如果只有一个JAR文件，自动使用该文件
- 如果有多个JAR文件，会提示用户指定具体的JAR文件名
- 如果没有JAR文件，会提示错误

### 可选配置项

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `JAVA_OPTS` | JVM启动参数 | `"-Xms512m -Xmx1024m"` |
| `LOG_FILE` | 日志文件名 | `"app.log"` |
| `PID_FILE` | PID文件名 | `"app.pid"` |

## 使用方法

### 1. 设置执行权限

```bash
chmod +x restart-java-app.sh
```

### 2. 基本用法

```bash
# 重启应用（默认操作）
./restart-java-app.sh

# 或者明确指定重启
./restart-java-app.sh restart
```

### 3. 其他命令

```bash
# 启动应用
./restart-java-app.sh start

# 停止应用
./restart-java-app.sh stop

# 查看应用状态
./restart-java-app.sh status

# 显示帮助信息
./restart-java-app.sh help
```

## 命令详解

### start - 启动应用
- 检查JAR文件是否存在
- 检查端口是否被占用
- 启动Java应用
- 等待应用完全启动
- 验证端口监听状态

### stop - 停止应用
- 查找应用进程PID
- 发送TERM信号优雅停止
- 等待最多30秒
- 超时后强制停止（KILL信号）
- 清理PID文件

### restart - 重启应用
- 先执行stop操作
- 等待2秒
- 再执行start操作

### status - 查看状态
- 显示应用运行状态
- 显示进程PID
- 显示端口监听状态

## 输出说明

脚本使用彩色输出来区分不同类型的消息：

- 🔴 **红色**: 错误信息
- 🟢 **绿色**: 成功信息
- 🟡 **黄色**: 警告信息
- 🔵 **蓝色**: 操作信息

## 文件说明

脚本运行时会创建以下文件：

- `app.log`: 应用运行日志
- `app.pid`: 应用进程PID文件

## 常见问题

### Q: 提示"JAR文件不存在"
**A**: 
- 如果使用自动检测模式（`JAR_NAME=""`），确保当前目录下有且仅有一个JAR文件
- 如果指定了JAR文件名，检查`JAR_NAME`配置是否正确，确保JAR文件在脚本同一目录下

### Q: 提示"当前目录下有多个JAR文件"
**A**: 当目录下有多个JAR文件时，需要在脚本中明确指定`JAR_NAME`，例如：`JAR_NAME="my-app.jar"`

### Q: 提示"端口已被占用"
**A**: 检查是否有其他应用占用了配置的端口，或修改`PORT`配置。

### Q: 应用启动失败
**A**: 查看`app.log`日志文件，检查具体错误原因。

### Q: 无法停止应用
**A**: 脚本会先尝试优雅停止，30秒后自动强制停止。

## 系统要求

- Linux操作系统
- Bash Shell
- Java运行环境
- 网络工具（netstat、ss或lsof中的任意一个）

## 注意事项

1. 确保脚本有执行权限
2. 确保Java环境已正确安装
3. 确保JAR文件路径正确
4. 建议在生产环境使用前先在测试环境验证
5. 定期检查日志文件大小，避免占用过多磁盘空间

## 示例

### 示例1: 自动检测模式（推荐）

如果你的目录下只有一个JAR文件，可以使用自动检测模式：

1. 保持脚本配置为默认：
```bash
JAR_NAME=""                      # 留空，自动检测
PORT=8080
```

2. 启动应用：
```bash
./restart-java-app.sh start
```

脚本会自动检测并使用目录下唯一的JAR文件。

### 示例2: 指定JAR文件名

假设你有一个名为`my-app.jar`的Spring Boot应用，需要在8080端口运行：

1. 修改脚本配置：
```bash
JAR_NAME="my-app.jar"
PORT=8080
```

2. 启动应用：
```bash
./restart-java-app.sh start
```

3. 查看状态：
```bash
./restart-java-app.sh status
```

输出示例：
```
[2024-01-15 10:30:15] 应用正在运行
[2024-01-15 10:30:15] PID: 12345
[2024-01-15 10:30:15] 端口: 8080
[2024-01-15 10:30:15] 端口状态: 正在监听
```