跳至主要内容

附錄：Windows Server 安裝指南

本文件說明如何在 Windows Server 上部署 AppFuse 應用系統。

系統需求​

項目需求
作業系統Windows Server 2019+
JDK21+
Web 伺服器IIS 10+

安裝 JDK​

下載並安裝​

  1. 從 Adoptium 下載 OpenJDK 21 MSI 安裝檔
  2. 執行安裝程式，選擇「Set JAVA_HOME variable」

驗證安裝​

開啟 Command Prompt 或 PowerShell：

java -version

預期輸出：

openjdk version "21.0.x" 2024-xx-xx
OpenJDK Runtime Environment Temurin-21.0.x+xx (build 21.0.x+xx)
OpenJDK 64-Bit Server VM Temurin-21.0.x+xx (build 21.0.x+xx, mixed mode)

目錄結構​

建立以下目錄結構：

C:\AppFuse\
├── conf\
│   └── application.properties
├── opt\
│   └── app\
│       ├── app-server.jar
│       ├── app-server.exe
│       └── app-server.xml
├── app-web\
│   ├── index.html
│   └── assets\
└── var\
    ├── doc\
    └── log\

部署後端服務​

方式一：Windows Service（推薦）​

使用 Windows Service Wrapper (WinSW) 將 Spring Boot 應用程式安裝為 Windows 服務。

步驟 1：下載 WinSW​

從 WinSW Releases 下載對應版本：

  • 64 位元系統：WinSW-x64.exe
  • 32 位元系統：WinSW-x86.exe

將檔案更名為 app-server.exe 並放入 C:\AppFuse\opt\app\。

步驟 2：建立配置檔​

建立 C:\AppFuse\opt\app\app-server.xml：

<?xml version="1.0" encoding="UTF-8"?>
<service>
  <id>appfuse</id>
  <name>AppFuse Application Server</name>
  <description>AppFuse Spring Boot Application</description>
  <executable>java</executable>
  <arguments>-Xms512m -Xmx2048m -Dfile.encoding=UTF-8 -Dapp.home=C:\AppFuse -jar "%BASE%\app-server.jar" --spring.config.location=file:C:\AppFuse\conf\application.properties</arguments>
  <log mode="roll-by-size">
    <sizeThreshold>10240</sizeThreshold>
    <keepFiles>8</keepFiles>
  </log>
  <onfailure action="restart" delay="10 sec"/>
</service>

步驟 3：安裝服務​

以系統管理員身份開啟 Command Prompt：

cd C:\AppFuse\opt\app
app-server.exe install

步驟 4：管理服務​

:: 啟動服務
app-server.exe start

:: 停止服務
app-server.exe stop

:: 重啟服務
app-server.exe restart

:: 查看狀態
app-server.exe status

:: 解除安裝服務
app-server.exe uninstall

也可以透過「服務」管理主控台（services.msc）管理。

方式二：手動執行​

開啟 Command Prompt：

cd C:\AppFuse\opt\app
java -Xms512m -Xmx2048m -Dfile.encoding=UTF-8 -Dapp.home=C:\AppFuse -jar app-server.jar --spring.config.location=file:C:\AppFuse\conf\application.properties

配置 IIS 反向代理​

安裝必要模組​

  1. 安裝 URL Rewrite 模組
  2. 安裝 Application Request Routing (ARR) 模組

啟用 ARR Proxy​

  1. 開啟 IIS 管理員
  2. 選取伺服器節點
  3. 雙擊「Application Request Routing Cache」
  4. 點選右側「Server Proxy Settings」
  5. 勾選「Enable proxy」
  6. 點選「Apply」

建立網站​

  1. 在 IIS 管理員中，右鍵點選「Sites」→「Add Website」
  2. 設定：
    • Site name: AppFuse
    • Physical path: C:\AppFuse\app-web
    • Binding: 依需求設定（如 Port 80 或 443）

配置 URL Rewrite​

在 C:\AppFuse\app-web 建立 web.config：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <!-- API 反向代理 -->
        <rule name="API Proxy" stopProcessing="true">
          <match url="^api/(.*)" />
          <action type="Rewrite" url="http://localhost:8080/app-server/api/{R:1}" />
        </rule>

        <!-- Actuator 端點 -->
        <rule name="Actuator Proxy" stopProcessing="true">
          <match url="^actuator/(.*)" />
          <action type="Rewrite" url="http://localhost:8080/app-server/actuator/{R:1}" />
        </rule>

        <!-- SPA 路由 -->
        <rule name="SPA Routes" stopProcessing="true">
          <match url=".*" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          </conditions>
          <action type="Rewrite" url="/" />
        </rule>
      </rules>
    </rewrite>

    <!-- 靜態檔案快取 -->
    <staticContent>
      <clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="365.00:00:00" />
    </staticContent>

    <!-- 預設文件 -->
    <defaultDocument>
      <files>
        <clear />
        <add value="index.html" />
      </files>
    </defaultDocument>
  </system.webServer>
</configuration>

啟用 HTTPS（選用）​

  1. 取得 SSL 憑證（.pfx 格式）
  2. 在 IIS 管理員中，選取伺服器節點 →「Server Certificates」
  3. 匯入 PFX 憑證
  4. 編輯網站 Bindings，新增 HTTPS（Port 443）並選取憑證

防火牆設定​

開放必要的埠號：

# 開放 HTTP
New-NetFirewallRule -DisplayName "HTTP" -Direction Inbound -Protocol TCP -LocalPort 80 -Action Allow

# 開放 HTTPS
New-NetFirewallRule -DisplayName "HTTPS" -Direction Inbound -Protocol TCP -LocalPort 443 -Action Allow

驗證安裝​

# 檢查後端服務
Invoke-WebRequest -Uri http://localhost:8080/app-server/actuator/health

# 檢查 IIS 代理
Invoke-WebRequest -Uri http://localhost/api/actuator/health

# 檢查前端
Invoke-WebRequest -Uri http://localhost/

WinSW 配置參考​

完整配置範例​

<?xml version="1.0" encoding="UTF-8"?>
<service>
  <!-- 服務識別 -->
  <id>appfuse</id>
  <name>AppFuse Application Server</name>
  <description>AppFuse Spring Boot Application Server</description>

  <!-- 執行設定 -->
  <executable>java</executable>
  <arguments>-server -Xms1024m -Xmx2048m -Dfile.encoding=UTF-8 -Dapp.home=C:\AppFuse -jar "%BASE%\app-server.jar" --spring.config.location=file:C:\AppFuse\conf\application.properties</arguments>

  <!-- 工作目錄 -->
  <workingdirectory>C:\AppFuse\opt\app</workingdirectory>

  <!-- 日誌設定 -->
  <log mode="roll-by-size">
    <sizeThreshold>10240</sizeThreshold>
    <keepFiles>8</keepFiles>
  </log>
  <logpath>C:\AppFuse\var\log</logpath>

  <!-- 失敗處理 -->
  <onfailure action="restart" delay="10 sec"/>
  <resetfailure>1 hour</resetfailure>

  <!-- 啟動設定 -->
  <startmode>Automatic</startmode>
  <delayedAutoStart>true</delayedAutoStart>

  <!-- 相依服務 -->
  <depend>MSSQLSERVER</depend>

  <!-- 環境變數 -->
  <env name="JAVA_HOME" value="C:\Program Files\Eclipse Adoptium\jdk-21.0.2.13-hotspot"/>
</service>

WinSW 指令參考​

指令說明
install安裝服務
uninstall解除安裝服務
start啟動服務
stop停止服務
restart重啟服務
status查看狀態
refresh重新載入配置（不需重新安裝）

常見問題​

問題：服務無法啟動​

  1. 檢查 Java 路徑是否正確
  2. 檢查 JAR 檔案路徑
  3. 查看 WinSW 日誌（與 exe 同目錄）
  4. 以手動方式執行確認錯誤訊息

問題：IIS 反向代理失敗​

  1. 確認 ARR 已啟用 Proxy 功能
  2. 確認 URL Rewrite 規則正確
  3. 確認後端服務正在運行
  4. 檢查 IIS 錯誤日誌

問題：靜態檔案 404​

  1. 確認 web.config 中的 SPA 路由規則
  2. 確認實體路徑正確
  3. 確認 IIS 應用程式集區身份有讀取權限

相關文件​