# sip

**Repository Path**: DD2010/sip

## Basic Information

- **Project Name**: sip
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-01
- **Last Updated**: 2026-05-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SIP Helper — PowerShell 脚本使用说明

本项目通过 3 个 PowerShell 脚本覆盖完整的 **构建 → 部署 → 运行时管理** 生命周期。

| 脚本 | 定位 | 典型调用 |
| --- | --- | --- |
| [`build.ps1`](./build.ps1) | 前端 npm + 后端 Maven 打包 | `.\build.ps1` |
| [`deploy.ps1`](./deploy.ps1) | 一键部署（内部调用 build + service） | `.\deploy.ps1 -Start` |
| [`service.ps1`](./service.ps1) | 运行时管理：start / stop / restart / status / logs | `.\service.ps1 start` |

> **环境要求**：Windows PowerShell 5.1+、JDK 8+、Maven、Node.js + npm、MySQL（首启前请先执行 [`sip/src/main/resources/db/schema.sql`](./sip/src/main/resources/db/schema.sql)）。首次运行脚本如遇执行策略拦截，可使用 `powershell -ExecutionPolicy Bypass -File .\xxx.ps1 ...`。

---

## 目录

- [依赖关系与调用链](#依赖关系与调用链)
- [build.ps1 — 自动化构建脚本](#buildps1--自动化构建脚本)
- [deploy.ps1 — 一键部署脚本](#deployps1--一键部署脚本)
- [service.ps1 — 服务管理脚本](#serviceps1--服务管理脚本)
- [常见问题与解决方法](#常见问题与解决方法)
- [日志与 PID 文件](#日志与-pid-文件)

---

## 依赖关系与调用链

```
deploy.ps1  ──►  build.ps1  ──►  npm run build   (sipUI → dist)
     │                      └►   mvn package     (sip → target/*.jar)
     │
     └──(可选 -Start)──►  service.ps1 stop
                          service.ps1 start -Port <n> -Profile <p>
```

- `build.ps1` **可独立运行**，无前置依赖。
- `deploy.ps1` **必须**和 `build.ps1`、`service.ps1` 处于同一目录（项目根目录），内部通过 `Join-Path $ProjectRoot` 解析。
- `service.ps1` **依赖** `sip/target/*.jar` 已存在（即 `build.ps1` 至少跑过一次）。

---

## build.ps1 — 自动化构建脚本

### 功能

1. 检查并安装 `sipUI` 的 npm 依赖（若 `node_modules` 不存在）。
2. 执行 `npm run build`，产物输出到 `sipUI/dist`。
3. 清理 `sip/src/main/resources/static`，将 `dist` 内容整体拷贝进去，并校验文件完整性。
4. 执行 `mvn clean package -DskipTests`，输出可执行 JAR（`sip/target/sip-1.0.0.jar`）。
5. 对 JAR 做结构校验（检查 `META-INF/MANIFEST.MF` 与 `BOOT-INF/classes`）。
6. 所有输出同时写入 `logs/build-yyyyMMdd-HHmmss.log`。

### 参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `-SkipFrontend` | `switch` | 跳过前端构建 + 资源复制步骤，仅打包后端 |
| `-SkipBackend` | `switch` | 跳过后端打包步骤，仅构建前端 |
| `-Help` | `switch` | 打印帮助并退出 |

### 示例

```powershell
# 完整构建（前端 + 资源复制 + 后端打包）
.\build.ps1

# 只改了 Java 代码，跳过前端加速构建
.\build.ps1 -SkipFrontend

# 只想验证前端能否构建成功
.\build.ps1 -SkipBackend

# 查看帮助
.\build.ps1 -Help
```

### 可能的错误

| 现象 | 原因 | 解决 |
| --- | --- | --- |
| `Frontend build failed - dist directory not found` | `npm run build` 失败 | 查看 `logs/build-*.log`，通常是依赖未装好，删掉 `sipUI/node_modules` 后重试 |
| `Generated JAR file not found` | `mvn package` 失败 | 看日志，常见原因：网络拉不到依赖、端口占用（测试阶段）、编译错误 |
| `JAR file structure may be abnormal` (WARN) | JAR 不是 Spring Boot fat-jar | 检查 `sip/pom.xml` 是否包含 `spring-boot-maven-plugin` |
| npm 警告退出 | 历史版本中 `$ErrorActionPreference=Stop` 把 npm 警告当错误 | 当前版本已在前端步骤前后临时切到 `Continue`，若仍异常可手动在 `sipUI/` 下跑 `npm run build` 复现 |

---

## deploy.ps1 — 一键部署脚本

### 功能

按 **Step 1/3 → 3/3** 组织流程：

1. **Step 1**：调用 `build.ps1` 进行完整构建。
2. **Step 2**：验证产物——`sip/target/*.jar` 存在 & `static/` 下有前端文件。
3. **Step 3**：可选启动——先 `service.ps1 stop`，休眠 2 秒，再 `service.ps1 start`。

### 参数

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `-Start` | `switch` | 关闭 | 构建完成后自动停止旧实例并启动新实例 |
| `-Port` | `int` | `8080` | 启动时传给 `service.ps1` 的端口 |
| `-Profile` | `string` | `default` | 启动时传给 `service.ps1` 的 Spring profile |

> ⚠️ 不带 `-Start` 时，`-Port` 和 `-Profile` 不生效（仅做构建 + 验证）。

### 示例

```powershell
# 只构建，不启动
.\deploy.ps1

# 构建完自动重启，使用默认 8080 端口 + default profile
.\deploy.ps1 -Start

# 构建完以 9090 端口、prod profile 启动
.\deploy.ps1 -Start -Port 9090 -Profile prod
```

### 可能的错误

| 现象 | 原因 | 解决 |
| --- | --- | --- |
| `Build failed. Deployment aborted.` | `build.ps1` 返回非 0 | 打开 `logs/build-*.log` 查看具体失败点 |
| `JAR file not found` | 构建成功但 JAR 命名异常 | 检查 `sip/pom.xml` 的 `<finalName>` 与 `target/` 目录 |
| `Warning: No frontend resource files detected` | 前端构建被跳过或失败 | 如使用 `build.ps1 -SkipFrontend` 后直接 deploy，属正常警告；否则检查前端构建日志 |

---

## service.ps1 — 服务管理脚本

### 功能

对 SIP 后端 JAR 的生命周期进行管理：

| 动作 | 作用 |
| --- | --- |
| `start` | 定位 `sip/target/*.jar`，以后台 Java 进程拉起 Spring Boot 应用，stdout/stderr 异步写入 `logs/app-yyyyMMdd.log`，进程号写入 `.sip.pid` |
| `stop` | 从 `.sip.pid` 读取并校验进程，`Stop-Process -Force` 终止，最多等待 10 秒 |
| `restart` | `stop` → 休眠 2 秒 → `start` |
| `status` | 显示 PID / 端口 / 运行时长 / 内存 / CPU 时间 / JAR 名与构建时间 / 端口监听状态 |
| `logs` | 实时 tail `logs/app-yyyyMMdd.log`（`Get-Content -Tail 50 -Wait`，`Ctrl+C` 退出） |
| `help` | 打印帮助 |

> **进程识别策略（重要）**：脚本不再单纯信任 `.sip.pid` 的内容，会额外校验该 PID 对应的进程必须是 `java.exe` / `javaw.exe` 且命令行包含本项目的 `target` 目录与 `.jar` 字样。这样可以避免旧 pid 被其它软件复用时出现的 **误报 Running / 误杀无辜进程** 问题。

### 参数

| 参数 | 位置 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `Action` | 0（位置参数） | `start` / `stop` / `restart` / `status` / `logs` / `help` | `help` | 操作名 |
| `-Port` | 命名 | `int` | `8080` | 通过 `-Dserver.port=` 传入 JVM；同时用于端口占用检查 |
| `-Profile` | 命名 | `string` | `default` | 通过 `-Dspring.profiles.active=` 传入 JVM |
| `-JvmOpts` | 命名 | `string` | `""` | 附加 JVM 参数，会追加在默认参数之后 |

**默认 JVM 参数**：

```
-Xms256m -Xmx512m -XX:+UseG1GC -XX:MaxGCPauseMillis=200
-Dfile.encoding=UTF-8 -Duser.timezone=Asia/Shanghai
-Dserver.port=<Port> -Dspring.profiles.active=<Profile>
```

### 示例

```powershell
# 启动
.\service.ps1 start

# 指定端口启动
.\service.ps1 start -Port 9090

# 使用生产 profile，并追加堆设置
.\service.ps1 start -Profile prod -JvmOpts "-Xmx1024m"

# 状态查询
.\service.ps1 status

# 实时查看日志（Ctrl+C 退出 tail，不影响服务）
.\service.ps1 logs

# 停止 / 重启
.\service.ps1 stop
.\service.ps1 restart
```

### 可能的错误

| 现象 | 原因 | 解决 |
| --- | --- | --- |
| `JAR file not found. Please run build first` | `sip/target/*.jar` 不存在 | 先执行 `.\build.ps1` |
| `Port <n> is already in use` | 端口被占用 | 用 `netstat -ano \| findstr :<n>` 查占用进程；或改用 `-Port` 指定别的端口 |
| `Service is already running (PID: xxx)` | 已有实例在运行 | 先 `.\service.ps1 stop`，或直接 `.\service.ps1 restart` |
| `Service failed to start. Check logs` | JVM 启动失败 | 查看 `logs/app-yyyyMMdd.log`，典型原因：数据库连接失败、端口占用、JVM 参数错误 |
| `Service stop may be incomplete` | 强制 Kill 后 10 秒内仍能检测到进程 | 手动 `Get-Process java` / 任务管理器结束，或检查是否还有子进程 |

---

## 常见问题与解决方法

### 1. 执行策略限制：`无法加载文件 xxx.ps1，因为在此系统上禁止运行脚本`

```powershell
# 单次绕过（推荐）
powershell -ExecutionPolicy Bypass -File .\build.ps1

# 或为当前用户永久放行
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

### 2. PowerShell 中 `<` 重定向不可用

Windows PowerShell **不支持** bash 风格的 `<` 输入重定向。执行 SQL 文件应通过 cmd 包装：

```powershell
Invoke-Expression "cmd /c 'mysql -uroot -p123456 < .\sip\src\main\resources\db\schema.sql'"
```

### 3. npm 警告导致脚本退出

当 `$ErrorActionPreference = "Stop"` 时，npm 的 stderr 警告会被当成终止性错误。`build.ps1` 已在前端步骤前后临时切换为 `Continue` 规避；自行扩展脚本时注意保留此逻辑。

### 4. `.sip.pid` 失效导致 status 误报 / stop 误杀

旧 PID 被其它程序复用是常见现象。新版 `service.ps1` 会校验进程名与命令行，若不匹配自动清理 pid 文件。若你手动观察到这种情况，直接删除 `.sip.pid` 再执行 `status` 即可。

### 5. 数据库未初始化，服务启动报 500

首次部署前务必执行 schema：

```powershell
Invoke-Expression "cmd /c 'mysql -uroot -p123456 < .\sip\src\main\resources\db\schema.sql'"
```

默认账号：`admin` / `admin123`。

---

## 日志与 PID 文件

| 路径 | 写入者 | 作用 |
| --- | --- | --- |
| `logs/build-yyyyMMdd-HHmmss.log` | `build.ps1` | 每次构建的完整 npm / mvn 输出 |
| `logs/app-yyyyMMdd.log` | `service.ps1 start` | 后端应用的 stdout + stderr（按日切分） |
| `.sip.pid` | `service.ps1 start` | 当前运行中的 Java 进程号，`stop` / `status` / `restart` 都会读取并校验 |

清理建议：保留最近 7 天日志即可；`.sip.pid` 不要手动创建，由脚本自管。