系統安裝與管理手冊

本文件為「AppFuse 應用系統」的交付文件，提供系統管理員與維運人員關於安裝、配置及日常維運的操作指引。

1. 概要說明

本系統採用符合現代標準的 Java 技術架構開發，支援高可用性與高安全性的企業級部署。

系統架構分為前後端分離設計：

• 前端 (Frontend): 基於 React 開發的 SPA (Single Page Application)，由 app-web-host 封裝為 WAR 部署。
• 後端 (Backend): 基於 Spring Boot 開發的 RESTful API 服務 (app-server)。

為確保系統的最佳效能與穩定性，建議採用 Apache Tomcat 作為應用伺服器，並搭配 Nginx 進行反向代理與 SSL 加密。

2. 系統需求

軟體環境需求

元件	需求版本	說明
JDK	25	必須為 OpenJDK 25 或相容版本
Web Container	Tomcat 11.0+	需支援 Jakarta Servlet 6.1
Database	MySQL 8.0+	推薦使用。亦支援 PostgreSQL 12+ / SQL Server 2019+
Web Server	Nginx 1.26+	用於反向代理與負載平衡
OS	Ubuntu 22.04 / RHEL 8+	亦支援 Windows Server 2019+

硬體規格建議 (生產環境)

規格	最低需求	建議規格
CPU	2 Core	4 Core+
RAM	4 GB	8 GB+
Disk	40 GB	100 GB+ SSD

3. 安裝前置準備

在開始安裝前，請確認已完成以下準備工作。

3.1 準備安裝檔案

請向開發團隊取得以下發佈檔案：

1. app-server.war (後端應用程式)
2. app-web-host.war (前台應用程式，含靜態託管層)
3. application.properties (系統配置檔範本)

3.2 網路與防火牆設定

請確認伺服器已開放以下通訊埠：

埠號	服務	說明
80	HTTP	Nginx Web 服務 (對外)
443	HTTPS	Nginx SSL 服務 (對外，建議)
8080	Tomcat	應用程式服務 (僅限本機或內網存取)
3306	MySQL	資料庫服務 (僅限本機或內網存取)

3.3 資料庫初始化 (MySQL)

本系統需要完整的 UTF-8 支援 (包含 Emoji 與罕用字)。請依照以下設定初始化資料庫：

1. 優化配置 (mysqld.cnf)：

   [mysqld]
   character-set-server = utf8mb4
   collation-server = utf8mb4_unicode_ci
   transaction-isolation = READ-COMMITTED
   max_allowed_packet = 256M
   max_connections = 200
   lower_case_table_names = 1

2. 建立資料庫與帳戶：

   CREATE DATABASE appdb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'appfuse'@'localhost' IDENTIFIED BY '您的密碼';
   GRANT ALL PRIVILEGES ON appdb.* TO 'appfuse'@'localhost';
   FLUSH PRIVILEGES;

4. 快速安裝流程 (Linux)

本節以 Ubuntu 為例說明標準安裝步驟。

4.1 安裝 JDK 25

sudo apt update
sudo apt install openjdk-25-jdk -y
# 驗證版本
java -version

4.2 建立系統帳戶與目錄

建議使用專用帳戶 appmgr 運行服務，避免使用 root。

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

# 建立目錄結構 (切換至 appmgr 身份)
sudo su - appmgr
mkdir -p ~/opt ~/bin ~/conf ~/var/log

4.3 安裝 Apache Tomcat

下載並解壓縮 Tomcat 11.0 (請自行替換為最新版本號)：

cd ~/tmp
curl -O https://archive.apache.org/dist/tomcat/tomcat-11/v11.0.18/bin/apache-tomcat-11.0.18.tar.gz
tar xzf apache-tomcat-11.0.18.tar.gz -C ~/opt/

4.4 配置環境變數

建立 ~/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 -Xmx4096m -Dfile.encoding=UTF8"
export PATH=${JAVA_HOME}/bin:$PATH

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

4.5 部署應用程式

將安裝檔案複製到對應位置：

1. 配置檔：將 application.properties 複製到 ~/conf/，並修改其中的資料庫連線資訊。
2. 應用程式：將兩個 .war 檔案複製到 $CATALINA_HOME/webapps/。

4.6 啟動與驗證

# 啟動 Tomcat
~/opt/apache-tomcat-11.0.18/bin/startup.sh

# 檢查啟動日誌
tail -f ~/opt/apache-tomcat-11.0.18/logs/catalina.out

若看到 Server startup in [xxxx] milliseconds 表示啟動成功。

5. 進階配置

5.1 配置為系統服務 (Systemd)

為確保伺服器重開機後自動啟動，請建立 /etc/systemd/system/appfuse.service：

[Unit]
Description=AppFuse Application Server
After=syslog.target network.target

[Service]
Type=forking
User=appmgr
Group=appmgr
Environment="APP_HOME=/home/appmgr"
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"
# 請確保 setenv.sh 中的 JAVA_HOME 路徑正確，或在此處直接定義 JAVA_HOME

ExecStart=/home/appmgr/opt/apache-tomcat-11.0.18/bin/startup.sh
ExecStop=/home/appmgr/opt/apache-tomcat-11.0.18/bin/shutdown.sh
Restart=on-failure

[Install]
WantedBy=multi-user.target

啟用服務：

sudo systemctl daemon-reload
sudo systemctl enable appfuse
sudo systemctl start appfuse

5.2 Nginx 反向代理與 SSL

安裝 Nginx 並配置 /etc/nginx/sites-available/appfuse.conf：

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /etc/nginx/ssl/server.crt;
    ssl_certificate_key /etc/nginx/ssl/server.key;

    # 允許大檔案上傳
    client_max_body_size 64M;

    location /app-server/ {
        proxy_pass http://127.0.0.1:8080/app-server/;
        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;
    }

    location /app-web/ {
        proxy_pass http://127.0.0.1:8080/app-web-host/;
    }

    location = / {
        return 302 /app-web/;
    }
}

5.3 日誌輪轉 (Logrotate)

建立 /etc/logrotate.d/appfuse，避免日誌佔滿磁碟：

/home/appmgr/opt/apache-tomcat-*/logs/catalina.out {
    copytruncate
    daily
    rotate 90
    compress
    missingok
}

6. 日常維運管理

服務管理

動作	指令
啟動系統	sudo systemctl start appfuse
停止系統	sudo systemctl stop appfuse
重新啟動	sudo systemctl restart appfuse
查看狀態	sudo systemctl status appfuse
查看日誌	tail -f /home/appmgr/opt/apache-tomcat-*/logs/catalina.out

備份與還原

資料庫備份 (MySQL)： 建議設定每日排程執行以下指令：

mysqldump -u root -p --single-transaction --routines --triggers appdb | gzip > appdb-$(date +%Y%m%d).sql.gz

資料庫還原：

gunzip < appdb-20240101.sql.gz | mysql -u root -p appdb

7. 疑難排解

常見問題

Q1: 服務無法啟動，日誌顯示 Java 版本錯誤？

• 檢查 java -version，必須為 JDK 25+。
• 檢查 setenv.sh 或 Systemd 服務檔中的 JAVA_HOME 路徑是否正確。

Q2: 無法連線資料庫 (CannotGetJdbcConnectionException)？

• 確認 MySQL 服務已啟動。
• 檢查 conf/application.properties 中的 JDBC URL、帳號與密碼。
• 確認資料庫使用者權限 (GRANT ALL ...)。

Q3: 檔案上傳失敗 (413 Request Entity Too Large)？

• 檢查 Nginx 設定 client_max_body_size 64M;。
• 檢查 Tomcat server.xml Connector 設定 maxPostSize="67108864"。

Q4: 系統時間不正確或 Token 驗證失敗？

• 執行 timedatectl 檢查時間同步狀態。
• 若未同步，請安裝並設定 NTP 服務。

---

本文件適用於 AppFuse 應用系統 v1.0+ 版本。如有未盡事宜，請聯繫系統供應商。