houqin-java/docs/Windows部署指南.md

# 医院物业 SaaS 管理后台 — Windows 部署指南

> 本文档指导在 Windows Server / Windows 10/11 上完整部署本系统，包含 MariaDB、Redis、后端应用的安装与配置。

---

## 目录

1. [环境要求](#1-环境要求)
2. [安装 JDK 17](#2-安装-jdk-17)
3. [安装 MariaDB 10.6+](#3-安装-mariadb-106)
4. [安装 Redis for Windows](#4-安装-redis-for-windows)
5. [初始化数据库](#5-初始化数据库)
6. [编译打包](#6-编译打包)
7. [配置应用](#7-配置应用)
8. [启动应用](#8-启动应用)
9. [注册为 Windows 服务（开机自启）](#9-注册为-windows-服务开机自启)
10. [验证部署](#10-验证部署)
11. [防火墙配置](#11-防火墙配置)
12. [日常运维](#12-日常运维)
13. [常见问题](#13-常见问题)

---

## 1. 环境要求

| 组件 | 最低版本 | 推荐版本 | 说明 |
|------|----------|----------|------|
| 操作系统 | Windows Server 2016 / Win 10 | Windows Server 2019+ | 64 位 |
| JDK | 17 | 17 (Eclipse Temurin) | 不要用 JRE，需完整 JDK 编译 |
| Maven | 3.9+ | 3.9.x | 仅编译时需要 |
| MariaDB | 10.6 | 10.11 LTS | 兼容 MySQL 协议 |
| Redis | 6.0 | 7.x (Windows 移植版) | 缓存与权限广播 |
| 内存 | 4 GB | 8 GB+ | 后端默认 512MB JVM |
| 磁盘 | 10 GB | 50 GB+ | 含数据库与日志 |

---

## 2. 安装 JDK 17

### 2.1 下载安装

1. 访问 [Eclipse Temurin 下载页](https://adoptium.net/temurin/releases/?version=17)
2. 选择 **Windows x64 .msi** 安装包
3. 运行安装程序，勾选 **Set JAVA_HOME variable**
4. 默认安装路径：`C:\Program Files\Eclipse Adoptium\jdk-17.x.x.x-hotspot`

### 2.2 验证

```powershell
java -version
# 输出应包含 openjdk version "17.x.x"

echo $env:JAVA_HOME
# 应输出 JDK 安装路径
```

### 2.3 手动配置环境变量（如安装时未自动配置）

1. 右键 **此电脑** → **属性** → **高级系统设置** → **环境变量**
2. 新建系统变量：
   - 变量名：`JAVA_HOME`
   - 变量值：`C:\Program Files\Eclipse Adoptium\jdk-17.x.x.x-hotspot`
3. 编辑 `Path`，添加：`%JAVA_HOME%\bin`

---

## 3. 安装 MariaDB 10.6+

### 3.1 下载安装

1. 访问 [MariaDB 下载页](https://mariadb.org/download/)
2. 选择 **Windows x86_64 MSI** 安装包
3. 运行安装程序：
   - 设置 root 密码（本例使用 `root`）
   - 勾选 **Enable networking**（端口 3306）
   - 字符集选择 **UTF-8 (utf8mb4)**
   - 勾选 **Install as Windows Service**，服务名 `MySQL`（MariaDB 默认服务名）

### 3.2 验证

```powershell
# 使用完整路径（根据实际安装版本调整）
& "C:\Program Files\MariaDB 10.3\bin\mysql.exe" -uroot -proot -e "SELECT VERSION();"
```

### 3.3 配置字符集（如安装时未设置）

编辑 MariaDB 配置文件 `C:\ProgramData\MariaDB\data\my.ini`（或安装目录下的 `my.ini`），在 `[mysqld]` 段添加：

```ini
[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[client]
default-character-set = utf8mb4

[mysql]
default-character-set = utf8mb4
```

修改后重启服务：

```powershell
Restart-Service MySQL
```

---

## 4. 安装 Redis for Windows

Redis 官方不提供 Windows 版本，需使用社区移植版。

### 方案 A：使用 Memurai（推荐，商用需授权）

1. 访问 [Memurai 官网](https://www.memurai.com/get-memurai) 下载安装
2. 安装后自动注册为 Windows 服务，默认端口 6379

### 方案 B：使用 tporadowski/redis-portable

1. 访问 [GitHub Releases](https://github.com/tporadowski/redis/releases) 下载 `.msi` 安装包
2. 安装时勾选 **Add to PATH** 和 **Install as Windows Service**
3. 默认端口 6379，无密码

### 方案 C：使用 WSL2 运行原生 Redis

```powershell
# 在 WSL2 Ubuntu 中
sudo apt update && sudo apt install redis-server -y
sudo sed -i 's/^bind .*/bind 0.0.0.0/' /etc/redis/redis.conf
sudo service redis-server start

# 验证（Windows 侧连接 WSL 的 Redis）
redis-cli -h $(wsl hostname -I | ForEach-Object { $_.Trim() }) ping
```

### 验证 Redis

```powershell
# 如果安装了 redis-cli
redis-cli ping
# 应输出 PONG
```

---

## 5. 初始化数据库

### 5.1 执行建表脚本

```powershell
# 进入项目目录
cd D:\git\git\医院后勤管理

# 执行初始化脚本（根据 MariaDB 实际安装路径调整）
& "C:\Program Files\MariaDB 10.3\bin\mysql.exe" -uroot -proot --default-character-set=utf8mb4 -e "source D:/git/git/医院后勤管理/backend/src/main/resources/db/init.sql"
```

### 5.2 验证

```powershell
& "C:\Program Files\MariaDB 10.3\bin\mysql.exe" -uroot -proot --default-character-set=utf8mb4 hospital_mgmt -e "SHOW TABLES; SELECT id, username, user_type FROM sys_user;"
```

应看到 48 张表和一条 `superadmin` 初始管理员记录。

---

## 6. 编译打包

### 6.1 安装 Maven

1. 访问 [Maven 下载页](https://maven.apache.org/download.cgi)
2. 下载 **Binary zip archive** (`apache-maven-3.9.x-bin.zip`)
3. 解压到 `C:\apache-maven-3.9.x`
4. 添加环境变量：
   - 新建 `MAVEN_HOME` = `C:\apache-maven-3.9.x`
   - 在 `Path` 中添加 `%MAVEN_HOME%\bin`

验证：

```powershell
mvn -version
# 应输出 Maven 3.9.x + Java 17
```

### 6.2 编译打包

```powershell
cd D:\git\git\医院后勤管理\backend

# 编译打包（跳过测试，生产部署前建议先跑测试）
mvn clean package -DskipTests

# 生成的 jar 包位置
# backend\target\hospital-mgmt-1.0.0.jar
```

### 6.3 部署目录结构

建议创建独立部署目录：

```powershell
# 创建部署目录
New-Item -ItemType Directory -Path "C:\hospital-mgmt" -Force
New-Item -ItemType Directory -Path "C:\hospital-mgmt\logs" -Force
New-Item -ItemType Directory -Path "C:\hospital-mgmt\config" -Force

# 复制 jar 包
Copy-Item "D:\git\git\医院后勤管理\backend\target\hospital-mgmt-1.0.0.jar" "C:\hospital-mgmt\app.jar"
```

---

## 7. 配置应用

### 7.1 创建外部配置文件

在 `C:\hospital-mgmt\config\` 下创建 `application-prod.yml`：

```yaml
server:
  port: 8080
  servlet:
    context-path: /api/v1

spring:
  datasource:
    driver-class-name: org.mariadb.jdbc.Driver
    url: jdbc:mariadb://localhost:3306/hospital_mgmt?useUnicode=true&characterEncoding=utf8mb4&serverTimezone=Asia/Shanghai
    username: root
    password: root                # 修改为实际密码
    hikari:
      maximum-pool-size: 20
      minimum-idle: 10
      idle-timeout: 600000
      max-lifetime: 1800000
  data:
    redis:
      host: localhost
      port: 6379
      password:                   # 如 Redis 设置了密码，在此填写
      lettuce:
        pool:
          max-active: 16
          max-idle: 8
          min-idle: 4

mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true
  global-config:
    db-config:
      id-type: assign_id
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0
  mapper-locations: classpath*:mapper/**/*.xml

jwt:
  secret: your-production-jwt-secret-at-least-32-chars-long  # 生产环境务必修改！
  expiration: 7200
  refresh-expiration: 604800

permission:
  redis-channel: permission:changed

async:
  pool:
    core-size: 4
    max-size: 8
    queue-capacity: 1000

upload:
  max-size: 20

springdoc:
  api-docs:
    path: /swagger-docs
  swagger-ui:
    path: /swagger-ui.html

logging:
  level:
    com.hospital.mgmt: INFO
  file:
    name: C:/hospital-mgmt/logs/hospital-mgmt.log
  logback:
    rollingpolicy:
      max-file-size: 50MB
      max-history: 30
```

### 7.2 关键配置项说明

| 配置项 | 说明 | 默认值 | 生产建议 |
|--------|------|--------|----------|
| `spring.datasource.password` | 数据库密码 | root | 使用强密码 |
| `spring.data.redis.password` | Redis 密码 | (空) | 建议设置 |
| `jwt.secret` | JWT 签名密钥 | (内置默认) | **必须修改**，至少32字符 |
| `jwt.expiration` | Token 有效期(秒) | 7200 (2h) | 按需调整 |
| `logging.file.name` | 日志文件路径 | (控制台) | 指定文件路径 |
| `spring.datasource.hikari.maximum-pool-size` | 最大连接数 | 20 | 根据并发量调整 |

---

## 8. 启动应用

### 8.1 命令行前台启动（测试用）

```powershell
cd C:\hospital-mgmt

java -Xms256m -Xmx512m -XX:+UseG1GC ^
  -Dspring.config.additional-location=file:./config/ ^
  -Dspring.profiles.active=prod ^
  -jar app.jar
```

看到以下日志表示启动成功：

```
Started HospitalMgmtApplication in x.xxx seconds
```

### 8.2 后台启动

```powershell
Start-Process -FilePath "java" `
  -ArgumentList "-Xms256m","-Xmx512m","-XX:+UseG1GC","-Dspring.config.additional-location=file:./config/","-Dspring.profiles.active=prod","-jar","app.jar" `
  -WorkingDirectory "C:\hospital-mgmt" `
  -WindowStyle Hidden `
  -RedirectStandardOutput "C:\hospital-mgmt\logs\startup.log" `
  -RedirectStandardError "C:\hospital-mgmt\logs\startup-error.log"
```

---

## 9. 注册为 Windows 服务（开机自启）

推荐使用 [WinSW](https://github.com/winsw/winsw) 将 Java 应用注册为 Windows 服务。

### 9.1 下载 WinSW

1. 从 [WinSW Releases](https://github.com/winsw/winsw/releases) 下载 `WinSW-x64.exe`
2. 重命名为 `hospital-mgmt-service.exe`
3. 复制到 `C:\hospital-mgmt\`

### 9.2 创建服务配置文件

在 `C:\hospital-mgmt\` 下创建 `hospital-mgmt-service.xml`：

```xml
<service>
  <id>hospital-mgmt</id>
  <name>Hospital Management Backend</name>
  <description>医院物业 SaaS 管理后台后端服务</description>
  <executable>%JAVA_HOME%\bin\java.exe</executable>
  <arguments>-Xms256m -Xmx512m -XX:+UseG1GC -Dspring.config.additional-location=file:./config/ -Dspring.profiles.active=prod -jar app.jar</arguments>
  <workingdirectory>C:\hospital-mgmt</workingdirectory>
  <logpath>C:\hospital-mgmt\logs\service</logpath>
  <log mode="roll-by-size">
    <sizeThreshold>10240</sizeThreshold>
    <keepFiles>5</keepFiles>
  </log>
  <onfailure action="restart" delay="10 sec"/>
  <onfailure action="restart" delay="30 sec"/>
  <onfailure action="restart" delay="60 sec"/>
  <resetfailure>5 minutes</resetfailure>
  <env name="JAVA_HOME" value="%JAVA_HOME%"/>
  <startmode>Automatic</startmode>
  <depend>MariaDB</depend>
</service>
```

> **注意**：`<depend>` 中的 `MariaDB` 需与实际 MariaDB Windows 服务名一致。可通过 `Get-Service *maria*,*mysql*` 查看服务名。

### 9.3 安装并启动服务

```powershell
# 以管理员身份运行
cd C:\hospital-mgmt

# 安装服务
.\hospital-mgmt-service.exe install

# 启动服务
.\hospital-mgmt-service.exe start

# 查看状态
.\hospital-mgmt-service.exe status

# 或使用 Windows 命令
Get-Service hospital-mgmt
```

### 9.4 常用服务管理命令

```powershell
# 停止
.\hospital-mgmt-service.exe stop

# 卸载
.\hospital-mgmt-service.exe uninstall

# 重启
.\hospital-mgmt-service.exe restart
```

---

## 10. 验证部署

### 10.1 检查应用状态

```powershell
# 检查服务是否运行
Get-Service hospital-mgmt

# 检查端口是否监听
netstat -ano | findstr :8080

# 测试 API 健康检查
Invoke-RestMethod -Uri "http://localhost:8080/api/v1/swagger-docs" -Method Head
```

### 10.2 检查数据库连接

```powershell
& "C:\Program Files\MariaDB 10.3\bin\mysql.exe" -uroot -proot hospital_mgmt -e "SELECT COUNT(*) AS table_count FROM information_schema.tables WHERE table_schema='hospital_mgmt';"
```

### 10.3 检查 Redis 连接

```powershell
redis-cli ping
# PONG
```

### 10.4 访问 Swagger UI

浏览器打开：`http://localhost:8080/api/v1/swagger-ui.html`

### 10.5 测试登录

```powershell
# 使用默认管理员账号登录
$body = @{
    username = "superadmin"
    password = "admin123"
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:8080/api/v1/auth/login" -Method Post -Body $body -ContentType "application/json"
```

---

## 11. 防火墙配置

如果需要从其他机器访问，需开放端口：

```powershell
# 以管理员身份运行

# 开放后端 API 端口
New-NetFirewallRule -DisplayName "Hospital Mgmt API" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow

# 开放 MariaDB 端口（如需远程访问数据库）
New-NetFirewallRule -DisplayName "MariaDB" -Direction Inbound -Protocol TCP -LocalPort 3306 -Action Allow

# 开放 Redis 端口（如需远程访问，不建议）
# New-NetFirewallRule -DisplayName "Redis" -Direction Inbound -Protocol TCP -LocalPort 6379 -Action Allow
```

> **安全建议**：Redis 和 MariaDB 端口不应对外网开放，仅后端应用本机访问即可。

---

## 12. 日常运维

### 12.1 日志位置

| 日志 | 路径 |
|------|------|
| 应用日志 | `C:\hospital-mgmt\logs\hospital-mgmt.log` |
| WinSW 服务日志 | `C:\hospital-mgmt\logs\service\` |
| MariaDB 日志 | MariaDB 安装目录 `data\*.err` |
| Redis 日志 | Redis 安装目录或 Windows 事件日志 |

### 12.2 日志清理

应用日志默认保留 30 天（通过 logback 配置）。如需手动清理：

```powershell
# 删除 30 天前的日志
Get-ChildItem "C:\hospital-mgmt\logs\" -Recurse -File |
  Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-30) } |
  Remove-Item -Force
```

### 12.3 数据库备份

```powershell
# 创建备份目录
New-Item -ItemType Directory -Path "C:\hospital-mgmt\backups" -Force

# 执行备份
$timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
& "C:\Program Files\MariaDB 10.3\bin\mysqldump.exe" -uroot -proot --default-character-set=utf8mb4 --single-transaction hospital_mgmt > "C:\hospital-mgmt\backups\hospital_mgmt_$timestamp.sql"
```

可配合 Windows 任务计划程序实现自动备份：

```powershell
# 创建每天凌晨2点的备份任务
$action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-File C:\hospital-mgmt\backup.ps1"
$trigger = New-ScheduledTaskTrigger -Daily -At 2am
Register-ScheduledTask -TaskName "HospitalMgmt-DB-Backup" -Action $action -Trigger $trigger -User "SYSTEM" -RunLevel Highest
```

### 12.4 应用更新

```powershell
# 1. 停止服务
cd C:\hospital-mgmt
.\hospital-mgmt-service.exe stop

# 2. 备份旧版本
Copy-Item "app.jar" "app.jar.bak" -Force

# 3. 替换 jar 包
Copy-Item "D:\git\git\医院后勤管理\backend\target\hospital-mgmt-1.0.0.jar" "app.jar" -Force

# 4. 启动服务
.\hospital-mgmt-service.exe start

# 5. 验证
Get-Service hospital-mgmt
```

---

## 13. 常见问题

### Q1: 启动报错 `Communications link failure`（数据库连接失败）

**排查步骤**：
1. 确认 MariaDB 服务正在运行：`Get-Service MySQL`
2. 确认端口可达：`Test-NetConnection localhost -Port 3306`
3. 确认用户名密码正确：`mysql -uroot -proot -e "SELECT 1;"`
4. 检查配置文件中 `spring.datasource.url` 是否正确

### Q2: 启动报错 `Unable to connect to Redis`（Redis 连接失败）

**排查步骤**：
1. 确认 Redis 服务运行：`Get-Service *redis*`
2. 测试连接：`redis-cli ping`
3. 如 Redis 设置了密码，确认 `spring.data.redis.password` 配置正确
4. 如使用 WSL2 运行 Redis，需将 `spring.data.redis.host` 改为 WSL 的 IP 地址

### Q3: 端口 8080 被占用

```powershell
# 查找占用进程
netstat -ano | findstr :8080

# 结束进程（替换 PID）
taskkill /PID <PID> /F

# 或修改应用端口
# 在 application-prod.yml 中修改 server.port
```

### Q4: JVM 内存不足

编辑 `hospital-mgmt-service.xml` 中的 `<arguments>` 部分，增大内存：

```
-Xms512m -Xmx1024m
```

### Q5: 日志中文乱码

1. 确保 Windows 系统区域设置支持 UTF-8：
   - **设置** → **时间和语言** → **语言和区域** → **管理语言设置** → **更改系统区域设置** → 勾选 **Beta: 使用 Unicode UTF-8 提供全球语言支持**
2. 重启电脑

### Q6: 服务启动后立即停止

1. 查看服务日志：`C:\hospital-mgmt\logs\service\`
2. 查看应用日志：`C:\hospital-mgmt\logs\hospital-mgmt.log`
3. 手动前台启动排查：`java -jar app.jar -Dspring.profiles.active=prod`

### Q7: MariaDB 服务名与 WinSW 配置不一致

```powershell
# 查看实际 MariaDB 服务名
Get-Service | Where-Object { $_.Name -match "maria|mysql" }

# 修改 hospital-mgmt-service.xml 中 <depend> 为实际服务名
# 例如：<depend>MySQL</depend> 或 <depend>MariaDB10</depend>
```

---

## 附录：一键部署脚本

将以下内容保存为 `C:\hospital-mgmt\deploy.ps1`，可快速完成部署：

```powershell
# ============================================
#  医院物业 SaaS 管理后台 - Windows 一键部署脚本
#  使用方式: 以管理员身份运行 PowerShell
#  .\deploy.ps1
# ============================================

$ErrorActionPreference = "Stop"

# ---- 配置区 ----
$ProjectDir = "D:\git\git\医院后勤管理"
$DeployDir = "C:\hospital-mgmt"
$MariaDBPath = "C:\Program Files\MariaDB 10.3\bin"
$DbUser = "root"
$DbPass = "root"
$DbName = "hospital_mgmt"

Write-Host "===== 医院物业 SaaS 管理后台 - 部署开始 =====" -ForegroundColor Cyan

# 1. 创建部署目录
Write-Host "[1/6] 创建部署目录..." -ForegroundColor Yellow
New-Item -ItemType Directory -Path $DeployDir -Force | Out-Null
New-Item -ItemType Directory -Path "$DeployDir\logs" -Force | Out-Null
New-Item -ItemType Directory -Path "$DeployDir\config" -Force | Out-Null
New-Item -ItemType Directory -Path "$DeployDir\backups" -Force | Out-Null

# 2. 编译打包
Write-Host "[2/6] 编译打包..." -ForegroundColor Yellow
Push-Location "$ProjectDir\backend"
mvn clean package -DskipTests -q
if ($LASTEXITCODE -ne 0) { throw "Maven 打包失败" }
Pop-Location

# 3. 复制文件
Write-Host "[3/6] 复制文件..." -ForegroundColor Yellow
Copy-Item "$ProjectDir\backend\target\hospital-mgmt-1.0.0.jar" "$DeployDir\app.jar" -Force

# 4. 初始化数据库
Write-Host "[4/6] 初始化数据库..." -ForegroundColor Yellow
$mysqlExe = "$MariaDBPath\mysql.exe"
if (Test-Path $mysqlExe) {
    & $mysqlExe -u$DbUser -p$DbPass --default-character-set=utf8mb4 -e "source $($ProjectDir -replace '\\','/')/backend/src/main/resources/db/init.sql"
    Write-Host "  数据库初始化完成" -ForegroundColor Green
} else {
    Write-Host "  警告: 未找到 mysql.exe ($mysqlExe)，请手动执行 init.sql" -ForegroundColor Red
}

# 5. 复制配置文件（如不存在）
Write-Host "[5/6] 配置文件..." -ForegroundColor Yellow
if (-not (Test-Path "$DeployDir\config\application-prod.yml")) {
    Copy-Item "$ProjectDir\backend\src\main\resources\application-prod.yml" "$DeployDir\config\application-prod.yml"
    Write-Host "  已复制默认生产配置，请检查并修改！" -ForegroundColor Yellow
} else {
    Write-Host "  配置文件已存在，跳过" -ForegroundColor Green
}

# 6. 完成提示
Write-Host "[6/6] 部署完成！" -ForegroundColor Green
Write-Host ""
Write-Host "===== 下一步操作 =====" -ForegroundColor Cyan
Write-Host "1. 编辑配置文件: $DeployDir\config\application-prod.yml"
Write-Host "2. 前台测试启动:"
Write-Host "   cd $DeployDir"
Write-Host "   java -Xms256m -Xmx512m -Dspring.config.additional-location=file:./config/ -Dspring.profiles.active=prod -jar app.jar"
Write-Host "3. 注册为 Windows 服务（需下载 WinSW）:"
Write-Host "   .\hospital-mgmt-service.exe install"
Write-Host "4. 访问 Swagger: http://localhost:8080/api/v1/swagger-ui.html"
Write-Host "5. 默认管理员: superadmin / admin123"
Write-Host ""
Write-Host "===== 部署结束 =====" -ForegroundColor Cyan
```

---

## 默认账号

| 角色 | 用户名 | 密码 |
|------|--------|------|
| 超级管理员 | superadmin | admin123 |

> **生产环境务必修改默认密码和 JWT 密钥！**