安裝指南

本文件說明如何將 AppFuse 應用系統部署至 Apache Tomcat 環境。

前置條件：開始安裝前，請先完成 建構指南 取得安裝媒體。

部署架構

安裝媒體

安裝前請確認具備以下檔案：

檔案	說明
app-server.war	後端 API 模組
app-web-host.war	前台 SPA 模組（含靜態託管層）
application.properties	配置檔範本

---

Ubuntu 安裝步驟

步驟 1：安裝 JDK 25

# 更新套件清單
sudo apt update

# 安裝 OpenJDK 25
sudo apt install openjdk-25-jdk -y

# 驗證安裝
java -version

預期輸出：

openjdk version "25" 2025-09-16
OpenJDK Runtime Environment (build 25+...)
OpenJDK 64-Bit Server VM (build 25+..., mixed mode, sharing)

步驟 2：配置工作目錄

# 建立應用程式使用者
sudo useradd -r -m -d /home/appmgr -s /bin/bash appmgr

# 切換至應用程式使用者
sudo su - appmgr

# 建立目錄結構
mkdir -p ~/tmp
mkdir -p ~/opt
mkdir -p ~/bin
mkdir -p ~/conf
mkdir -p ~/var/log
mkdir -p ~/var/doc

步驟 3：安裝 Apache Tomcat

# 下載 Tomcat 11.0（以 appmgr 身份執行）
cd ~/tmp
curl -O https://archive.apache.org/dist/tomcat/tomcat-11/v11.0.18/bin/apache-tomcat-11.0.18.tar.gz

# 解壓縮至 opt 目錄
tar xzf apache-tomcat-11.0.18.tar.gz -C ~/opt/

步驟 4：配置 Tomcat

編輯 ~/opt/apache-tomcat-11.0.18/conf/server.xml，調整 Connector 設定：

<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           maxPostSize="67108864"
           redirectPort="8443"
           maxParameterCount="1000" />

說明：maxPostSize 設為 64MB 以支援大型檔案上傳。

步驟 5：配置執行環境

建立環境設定腳本 ~/bin/setenv.sh：

#!/bin/bash

# Java 設定
export JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64
export JAVA_OPTS="-server -Djava.awt.headless=true -Xms1024m -Xmx2048m -Dfile.encoding=UTF8"
export PATH=${JAVA_HOME}/bin:$PATH

# Tomcat 設定
export CATALINA_HOME=$HOME/opt/apache-tomcat-11.0.18

# 應用程式設定
export APP_HOME=$HOME

設定登入時自動載入：

echo '. $HOME/bin/setenv.sh' >> ~/.profile

登出並重新登入後驗證：

java -version
echo $CATALINA_HOME

步驟 6：部署應用程式

# 複製配置檔
cp application.properties ~/conf/

# 複製所有 WAR 檔案至 Tomcat
cp app-server.war $CATALINA_HOME/webapps/
cp app-web-host.war $CATALINA_HOME/webapps/

步驟 7：啟動測試

# 啟動 Tomcat
$CATALINA_HOME/bin/startup.sh

# 查看啟動日誌
tail -f $CATALINA_HOME/logs/catalina.out

等待出現 Server startup in [xxxx] milliseconds 表示啟動完成。

驗證後端服務：

curl http://localhost:8080/app-server/actuator/health
# {"status":"UP"}

停止 Tomcat：

$CATALINA_HOME/bin/shutdown.sh

步驟 8：安裝 Nginx

# 切換回管理員帳號
exit

# 安裝 Nginx
sudo apt install nginx -y

# 啟動並設定開機啟動
sudo systemctl start nginx
sudo systemctl enable nginx

步驟 9：配置 Nginx 反向代理

建立站點配置檔 /etc/nginx/sites-available/appfuse.conf：

server {
    listen 80;
    server_name _;

    # 共用的 Proxy 設定
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;

    # 檔案上傳限制
    client_max_body_size 64M;

    # 後端 API 模組
    location /app-server/ {
        proxy_pass http://127.0.0.1:8080/app-server/;
        proxy_buffering off;
    }

    # 前台 SPA 模組
    location /app-web/ {
        proxy_pass http://127.0.0.1:8080/app-web/;
        proxy_buffering off;
    }

    # 根路徑重導向至前台
    location = / {
        return 302 /app-web/;
    }
}

啟用配置：

# 啟用站點
sudo ln -s /etc/nginx/sites-available/appfuse.conf /etc/nginx/sites-enabled/

# 停用預設站點
sudo unlink /etc/nginx/sites-enabled/default

# 測試配置
sudo nginx -t

# 重新載入
sudo systemctl reload nginx

步驟 10：配置 Systemd 服務

建立服務檔 /etc/systemd/system/appfuse.service：

[Unit]
Description=AppFuse Application (Tomcat)
After=syslog.target network.target

[Service]
Type=forking
User=appmgr
Group=appmgr
UMask=0007

Environment="APP_HOME=/home/appmgr"
Environment="JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64"
Environment="JAVA_OPTS=-server -Djava.awt.headless=true -Xms1024m -Xmx2048m -Dfile.encoding=UTF8"
Environment="CATALINA_HOME=/home/appmgr/opt/apache-tomcat-11.0.18"
Environment="CATALINA_PID=/home/appmgr/opt/apache-tomcat-11.0.18/temp/tomcat.pid"

ExecStart=/bin/bash -c "${CATALINA_HOME}/bin/startup.sh"
ExecStop=/bin/bash -c "${CATALINA_HOME}/bin/shutdown.sh"

RestartSec=10
Restart=on-failure

[Install]
WantedBy=multi-user.target

啟用服務：

# 載入配置
sudo systemctl daemon-reload

# 啟動服務
sudo systemctl start appfuse.service

# 設定開機啟動
sudo systemctl enable appfuse.service

# 檢查狀態
sudo systemctl status appfuse.service

---

安裝驗證

驗證清單

項目	驗證方式	預期結果
Tomcat 服務	sudo systemctl status appfuse	Active: active (running)
後端 API	curl http://localhost:8080/app-server/actuator/health	{"status":"UP"}
Nginx 代理	curl http://localhost/app-server/actuator/health	{"status":"UP"}
前台頁面	瀏覽器開啟 http://localhost/app-web/	顯示前台頁面

驗證腳本

#!/bin/bash
echo "=== 安裝驗證 ==="

echo -n "Tomcat 服務: "
systemctl is-active appfuse.service

echo -n "Nginx 服務: "
systemctl is-active nginx.service

echo -n "後端 API: "
curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/app-server/actuator/health
echo ""

echo -n "Nginx 代理 (app-server): "
curl -s -o /dev/null -w "%{http_code}" http://localhost/app-server/actuator/health
echo ""

echo -n "前台頁面 (app-web): "
curl -s -o /dev/null -w "%{http_code}" http://localhost/app-web/
echo ""

echo "=== 驗證完成 ==="

---

啟用 HTTPS

準備 SSL 憑證

需要以下檔案：

• 私鑰檔案：your-domain.key
• 憑證檔案：your-domain.crt（或包含中繼憑證的 your-domain.chained.crt）

# 建立 SSL 目錄
sudo mkdir -p /etc/nginx/ssl

# 複製憑證檔案
sudo cp your-domain.key /etc/nginx/ssl/
sudo cp your-domain.crt /etc/nginx/ssl/

# 設定權限
sudo chmod 600 /etc/nginx/ssl/*.key

配置 HTTPS

修改 /etc/nginx/sites-available/appfuse.conf：

# HTTP 重導向至 HTTPS
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

# HTTPS 設定
server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL 憑證
    ssl_certificate /etc/nginx/ssl/your-domain.crt;
    ssl_certificate_key /etc/nginx/ssl/your-domain.key;

    # SSL 安全設定
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;

    # HSTS
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # 共用的 Proxy 設定
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;

    # 檔案上傳限制
    client_max_body_size 64M;

    # 後端 API 模組
    location /app-server/ {
        proxy_pass http://127.0.0.1:8080/app-server/;
        proxy_buffering off;
    }

    # 前台 SPA 模組
    location /app-web/ {
        proxy_pass http://127.0.0.1:8080/app-web/;
        proxy_buffering off;
    }

    # 根路徑重導向至前台
    location = / {
        return 302 /app-web/;
    }
}

重新載入 Nginx：

sudo nginx -t
sudo systemctl reload nginx

---

目錄結構總覽

安裝完成後的目錄結構：

/home/appmgr/
├── bin/
│   └── setenv.sh                    # 環境變數設定
├── conf/
│   └── application.properties       # 應用程式配置
├── opt/
│   └── apache-tomcat-11.0.18/       # Tomcat
│       ├── webapps/
│       │   ├── app-server.war       # 後端 API 模組
│       │   └── app-web-host.war     # 前台 SPA 模組
│       └── logs/
│           └── catalina.out         # Tomcat 日誌
└── var/
    ├── doc/                         # 文件儲存
    └── log/                         # 應用程式日誌

---

下一步

• 配置說明 - 詳細的配置選項
• 維運管理 - 日常維運操作
• 故障排除 - 常見問題解決