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

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

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

---

目录

1. 环境要求
2. 安装 JDK 17
3. 安装 MariaDB 10.6+
4. 安装 Redis for Windows
5. 初始化数据库
6. 编译打包
7. 配置应用
8. 启动应用
9. 注册为 Windows 服务（开机自启）
10. 验证部署
11. 防火墙配置
12. 日常运维
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 下载页
2. 选择 Windows x64 .msi 安装包
3. 运行安装程序，勾选 Set JAVA_HOME variable
4. 默认安装路径：C:\Program Files\Eclipse Adoptium\jdk-17.x.x.x-hotspot

2.2 验证

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 下载页
2. 选择 Windows x86_64 MSI 安装包
3. 运行安装程序：
   • 设置 root 密码（本例使用 root）
   • 勾选 Enable networking（端口 3306）
   • 字符集选择 UTF-8 (utf8mb4)
   • 勾选 Install as Windows Service，服务名 MySQL（MariaDB 默认服务名）

3.2 验证

# 使用完整路径（根据实际安装版本调整）
& "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] 段添加：

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

[client]
default-character-set = utf8mb4

[mysql]
default-character-set = utf8mb4

修改后重启服务：

Restart-Service MySQL

---

4. 安装 Redis for Windows

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

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

1. 访问 Memurai 官网 下载安装
2. 安装后自动注册为 Windows 服务，默认端口 6379

方案 B：使用 tporadowski/redis-portable

1. 访问 GitHub Releases 下载 .msi 安装包
2. 安装时勾选 Add to PATH 和 Install as Windows Service
3. 默认端口 6379，无密码

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

# 在 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

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

---

5. 初始化数据库

5.1 执行建表脚本

# 进入项目目录
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 验证

& "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 下载页
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

验证：

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

6.2 编译打包

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

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

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

6.3 部署目录结构

建议创建独立部署目录：

# 创建部署目录
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：

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 命令行前台启动（测试用）

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 后台启动

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 将 Java 应用注册为 Windows 服务。

9.1 下载 WinSW

1. 从 WinSW Releases 下载 WinSW-x64.exe
2. 重命名为 hospital-mgmt-service.exe
3. 复制到 C:\hospital-mgmt\

9.2 创建服务配置文件

在 C:\hospital-mgmt\ 下创建 hospital-mgmt-service.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 安装并启动服务

# 以管理员身份运行
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 常用服务管理命令

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

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

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

---

10. 验证部署

10.1 检查应用状态

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

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

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

10.2 检查数据库连接

& "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 连接

redis-cli ping
# PONG

10.4 访问 Swagger UI

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

10.5 测试登录

# 使用默认管理员账号登录
$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. 防火墙配置

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

# 以管理员身份运行

# 开放后端 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 配置）。如需手动清理：

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

12.3 数据库备份

# 创建备份目录
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 任务计划程序实现自动备份：

# 创建每天凌晨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 应用更新

# 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 被占用

# 查找占用进程
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 配置不一致

# 查看实际 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，可快速完成部署：

# ============================================
#  医院物业 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 密钥！