parent
9dd23c74f5
commit
f4a275de92
8 changed files with 434 additions and 17 deletions
@ -0,0 +1,9 @@ |
||||
{ |
||||
"editor.defaultFormatter": "biomejs.biome", |
||||
"editor.formatOnSave": true, |
||||
"editor.codeActionsOnSave": { |
||||
"source.organizeImports.biome": "explicit", |
||||
"source.fixAll.biome": "explicit" |
||||
}, |
||||
"css.lint.unknownAtRules": "ignore" |
||||
} |
||||
@ -0,0 +1,403 @@ |
||||
# 展件互動系統 — 開發架構文件（Windows 10 原生版） |
||||
|
||||
> 三組電腦＋螢幕、三台 iPad，使用者透過 iPad 操控螢幕內容，流程結束後上傳圖片至客戶 FTPS，並以 QR Code 顯示對應圖片網址供民眾掃描。 |
||||
> |
||||
> 部署環境：Host 為 **Windows 10**（較舊機器，不使用 Docker），所有服務以原生方式安裝。 |
||||
|
||||
--- |
||||
|
||||
## 1. 系統總覽 |
||||
|
||||
### 1.1 硬體拓撲 |
||||
|
||||
| 角色 | 數量 | 跑什麼 | 網路 | |
||||
|---|---|---|---| |
||||
| Host 主機 | 1 | Caddy + Next.js（pm2）＋ Mosquitto（Windows Service）＋ 一個 Unity client | 有線連 AP/switch（建議） | |
||||
| Unity 主機 | 2 | 各一個 Unity client | 有線（建議） | |
||||
| iPad | 3 | PWA（加到主畫面、Single App Mode 鎖機） | WiFi | |
||||
| 螢幕 | 3 | 由各自的 Unity client 輸出 | — | |
||||
|
||||
> Host 主機（Win10）同時跑 broker、Caddy、Next.js、以及第一組的 Unity client；另外兩台只跑 Unity client。 |
||||
|
||||
### 1.2 服務管理方式（Win10） |
||||
|
||||
| 服務 | 啟動方式 | 開機自啟 | |
||||
|---|---|---| |
||||
| Mosquitto | Windows Service | 服務自動啟動（最先就緒） | |
||||
| Next.js（standalone） | pm2 | startup 資料夾的 bat | |
||||
| Caddy | pm2 | startup 資料夾的 bat | |
||||
|
||||
- Mosquitto 走獨立 Windows Service，作為最底層依賴最先起來。 |
||||
- Next.js 與 Caddy 由 pm2 管理，開機透過「startup 資料夾的 bat ＋ Windows 自動登入」拉起。 |
||||
- **務必設定 Windows 自動登入**（`netplwiz` 取消「使用者必須輸入密碼」），否則機器重開停在登入畫面時 bat 不會執行、服務不會啟動。 |
||||
|
||||
### 1.3 資料流（單一 station） |
||||
|
||||
``` |
||||
iPad (PWA) --- MQTT over wss ---> Caddy (TLS 443) --- ws ---> Mosquitto (localhost:9001) |
||||
| |
||||
| MQTT TCP 1883 |
||||
v |
||||
Unity client (subscribe) |
||||
| |
||||
使用者操作互動內容 ─────────────────────────────────────────────────┘ |
||||
| |
||||
流程結束 ── iPad 觸發 ──> Next.js Server Action ── basic-ftp ──> 客戶 FTPS |
||||
| |
||||
上傳成功 + 驗證 URL 可達 |
||||
| |
||||
publish 最終 URL 至 station topic |
||||
| |
||||
┌────────────────────────┴───────────────────┐ |
||||
v v |
||||
iPad 顯示 QR Code Unity 螢幕顯示 QR Code |
||||
``` |
||||
|
||||
### 1.4 技術選型摘要 |
||||
|
||||
- **螢幕內容**：Unity（原生 MQTT TCP client） |
||||
- **iPad 介面**：Next.js + PWA（**純 PWA，不走 Apple Developer / IPA**），zustand 保存裝置設定 |
||||
- **訊息中介**：Mosquitto（Windows Service），同時開 1883（TCP，給 Unity）與 9001（WebSocket，經 Caddy 給 iPad） |
||||
- **反向代理 / TLS**：Caddy（原生安裝，pm2 管理，手動掛 mkcert 憑證，**關閉自動 HTTPS**） |
||||
- **圖片上傳**：Next.js Server Action + `basic-ftp`（Node runtime） |
||||
- **程序管理**：pm2（Next.js + Caddy） |
||||
|
||||
--- |
||||
|
||||
## 2. 為什麼是純 PWA（決策紀錄） |
||||
|
||||
在「iOS ＋ 永不碰 Apple Developer 簽證 ＋ 展場 Kiosk」三個約束下，PWA 是唯一解： |
||||
|
||||
| 方案 | 是否產生 .ipa | 簽證到期問題 | 結論 | |
||||
|---|---|---|---| |
||||
| 原生 IPA | 是 | 每年到期、需重簽 | ✗ 排除 | |
||||
| Capacitor（WebView 殼） | 是 | 每年到期 | ✗ 排除 | |
||||
| Expo / React Native | 是（EAS Build） | 每年到期 | ✗ 排除 | |
||||
| **純 PWA** | **否** | **無此問題** | ✓ 採用 | |
||||
|
||||
關鍵釐清： |
||||
|
||||
- **Guided Access（引導使用模式）是 iOS 系統層級功能，鎖的是前景 app，不限原生或 Safari**。因此 PWA 一樣能被鎖。 |
||||
- 展場長展期、無人看管，建議用 **Apple Configurator 2 的 Single App Mode / Autonomous Single App Mode** 做到「開機自動鎖在這個 PWA、免人工」。**此功能不需要 Apple Developer 帳號**（Configurator 是免費 Mac 工具，針對自有裝置），與簽證無關。 |
||||
- Expo Go 不可用於正式佈署（開發沙盒、功能受限）；EAS Build 產出的仍是標準需簽證的 app。 |
||||
|
||||
--- |
||||
|
||||
## 3. 網路與 TLS |
||||
|
||||
### 3.1 為什麼需要 TLS |
||||
|
||||
PWA 要在 secure context 下運作，且 `wss://`（MQTT over WebSocket）也要求加密連線。區網內無公網域名，無法用 Let's Encrypt，故採 **mkcert 自簽 + iPad 安裝 RootCA**。 |
||||
|
||||
### 3.2 mkcert 在 Windows |
||||
|
||||
- 安裝後 `mkcert -install` 會將 RootCA 裝進 Windows 憑證庫。 |
||||
- 產 leaf 給 Caddy 用：`mkcert 192.168.1.50 host.local`（**SAN 必須包含連線用的 IP**）。 |
||||
- **CAROOT 路徑在 `%LOCALAPPDATA%\mkcert`**，內含 `rootCA.pem` 與 `rootCA-key.pem`。 |
||||
- **`rootCA-key.pem` 是整個系統的命脈**：重簽 leaf 靠它，遺失會導致重簽產生新 Root、iPad 全部要重裝。務必異地備份。 |
||||
|
||||
### 3.3 憑證效期 |
||||
|
||||
- **leaf 憑證（`cert.pem` / `key.pem`）**：mkcert v1.4.4 起效期約 2 年多。到期只需在 host 重簽，**iPad 完全不用動**（iPad 信任的是 RootCA，非 leaf）。 |
||||
- **RootCA**：效期約 10 年。到期才需重新在每台 iPad 安裝（屆時設備早已汰換）。 |
||||
- 重簽時 SAN 必須與原本一致（同組 IP / 主機名），否則 PWA 連線會因 SAN 不符報錯。 |
||||
|
||||
### 3.4 iPad 安裝 RootCA 流程（易漏） |
||||
|
||||
1. 將 `rootCA.pem` 傳到 iPad（AirDrop / 郵件 / 網頁下載）並安裝描述檔。 |
||||
2. **設定 → 一般 → VPN 與裝置管理** 安裝描述檔。 |
||||
3. **設定 → 一般 → 關於本機 → 憑證信任設定** 手動「啟用完整信任」。**只裝描述檔不夠，這步必做。** |
||||
|
||||
### 3.5 固定 IP |
||||
|
||||
Host 必須使用固定 IP（DHCP 保留或靜態）。iPad 端以 zustand 保存 host IP，且憑證 SAN 綁定 IP，host 換 IP 會導致設定與憑證同時失效。 |
||||
|
||||
### 3.6 Windows 防火牆 |
||||
|
||||
Windows Defender 防火牆需手動放行對外 port： |
||||
|
||||
- `443`（Caddy，對 iPad WiFi 開放） |
||||
- `1883`（Mosquitto TCP，對另外兩台 Unity 主機的區網 IP 開放） |
||||
- `9001` 僅 localhost 內部使用（Caddy 反代），**不需對外開放** |
||||
|
||||
Caddy 與 Mosquitto 首次啟動時 Windows 可能跳防火牆詢問，選允許。 |
||||
|
||||
### 3.7 WiFi 即時性建議 |
||||
|
||||
- 專用 AP、專用 SSID，不與公眾 WiFi 混用。 |
||||
- 控制訊號用 QoS 0、payload 最小化，高頻操作（連續拖曳）在 iPad 端 throttle/debounce 後再 publish。 |
||||
- Host 與 Unity 主機盡量走有線，只讓 iPad 走 WiFi。 |
||||
|
||||
--- |
||||
|
||||
## 4. MQTT 設計 |
||||
|
||||
### 4.1 連線方式 |
||||
|
||||
| 來源 | 協定 | 目標 | TLS | |
||||
|---|---|---|---| |
||||
| iPad（PWA / MQTT.js） | MQTT over WebSocket | `wss://<host>/mqtt` → Caddy → Mosquitto localhost:9001 | 是（Caddy 收 TLS） | |
||||
| Unity client | MQTT over TCP | `<host>:1883` | 否（區網內 TCP） | |
||||
|
||||
> Caddy 與 Mosquitto 同在一台 host，Caddy 直接反代 `localhost:9001`，無 Docker 跨網路問題。TLS 集中在 Caddy；Mosquitto 走明文 ws / tcp（封閉區網內）。 |
||||
|
||||
### 4.2 Topic 命名規範 |
||||
|
||||
採 `station/{stationId}/...` 命名空間，`stationId` 為 `1` / `2` / `3`。 |
||||
|
||||
| Topic | 方向 | QoS | Retained | 說明 | |
||||
|---|---|---|---|---| |
||||
| `station/{id}/control` | iPad → Unity | 0 | 否 | 即時控制訊號（操作、移動、選取） | |
||||
| `station/{id}/state` | Host → all | 1 | 是 | 流程狀態（single source of truth），重連後可立即取得當前狀態 | |
||||
| `station/{id}/command` | iPad → Host | 1 | 否 | 流程指令（如「開始上傳」） | |
||||
| `station/{id}/result` | Host → all | 1 | 是 | 最終圖片 URL，iPad 與 Unity 皆訂閱以顯示 QR | |
||||
| `station/{id}/error` | Host → all | 1 | 否 | 明確的錯誤狀態（帶錯誤碼／原因） | |
||||
| `station/{id}/status/ipad` | iPad LWT | 1 | 是 | iPad 上下線（Last Will） | |
||||
| `station/{id}/status/unity` | Unity LWT | 1 | 是 | Unity 上下線（Last Will） | |
||||
|
||||
### 4.3 即時性與穩定性原則 |
||||
|
||||
- **QoS 分級**：即時控制 QoS 0（降延遲）；狀態轉換 / 結果 / 錯誤 QoS 1（確保送達）。 |
||||
- **Retained + LWT**：用 LWT 偵測斷線；retained message 讓裝置重連後立即取得最新狀態與結果。 |
||||
- **狀態 single source of truth**：流程狀態以 Host 為準（`station/{id}/state`），不可只存在各 client 記憶體。任一 client 重開後須能由 retained state 接回原進度。 |
||||
|
||||
### 4.4 iPad 與螢幕的配對 |
||||
|
||||
- iPad 以 zustand persist 保存 `{ hostIp, stationId }`。 |
||||
- iPad 須提供「重新設定」入口（因 iOS 可能在系統清理時清除 PWA storage，設定遺失需可重設）。 |
||||
- 配對機制建議：首次開啟顯示設定頁手動輸入 / 選擇 stationId 與 host IP；之後自動沿用。 |
||||
|
||||
--- |
||||
|
||||
## 5. 圖片上傳與 QR 顯示 |
||||
|
||||
### 5.1 流程 |
||||
|
||||
1. 流程結束，iPad 透過 `station/{id}/command` 或直接呼叫 Next.js Server Action 觸發上傳。 |
||||
2. Server Action 用 `basic-ftp` 上傳圖片至客戶 FTPS（已驗證可用）。 |
||||
3. **上傳成功後，對「對外 HTTP(S) URL」做一次 HEAD 驗證可達**，再產生 QR。 |
||||
4. Host 將最終 URL publish 到 `station/{id}/result`（retained, QoS 1）。 |
||||
5. iPad 與 Unity 各自訂閱 `result`，**任一端皆可渲染 QR**。URL 的產生與驗證集中在 Host 一處，新增螢幕顯示為零成本。 |
||||
|
||||
### 5.2 注意事項 |
||||
|
||||
- **「上傳成功」≠「URL 可被掃描存取」**：FTPS 是上傳協定，掃描走 HTTP(S)。需與客戶確認上傳路徑對應的對外 URL 規則與 web server。 |
||||
- **上傳到可讀之間可能有延遲**：故步驟 3 先 HEAD 驗證，避免掃到 404；必要時加重試。 |
||||
- **FTPS passive mode 與防火牆**：確認 passive port range 未被擋。 |
||||
- **Server Action runtime**：`basic-ftp` 是 Node API，須跑在 Node runtime（standalone 預設即是，勿標為 edge）。 |
||||
- **並發控制**：三台可能同時送，上傳建議以 queue 串接而非無限制並發，避免打爆 FTPS 連線數。 |
||||
- **Windows 路徑**：暫存圖片路徑等請用 `path.join` 或 Windows 路徑，勿寫死 POSIX 斜線。 |
||||
|
||||
### 5.3 失敗處理 |
||||
|
||||
- 失敗時 Host 透過 `station/{id}/error` 廣播明確錯誤狀態（錯誤碼／原因），iPad 與 Unity 兩端皆顯示失敗，維持 single source of truth。 |
||||
- 提供**自動重試（數次）＋ 手動重試按鈕**，讓現場工作人員可一鍵重送。 |
||||
- 考慮失敗時**本地暫存圖片、事後補傳**，避免使用者該張圖片遺失。 |
||||
|
||||
--- |
||||
|
||||
## 6. 部署（Win10 原生） |
||||
|
||||
### 6.1 安裝清單 |
||||
|
||||
| 元件 | 安裝方式 | |
||||
|---|---| |
||||
| Node.js 20 LTS | 官方 Windows installer（Win10 可正常運作） | |
||||
| pm2 | `npm i -g pm2` | |
||||
| Caddy | 下載 Windows 版 `caddy.exe`，放固定路徑（如 `C:\caddy\`） | |
||||
| Mosquitto | 官方 Windows installer，安裝時註冊為 Windows Service | |
||||
| mkcert | 下載 Windows 版執行檔，`mkcert -install` | |
||||
|
||||
### 6.2 目錄建議 |
||||
|
||||
``` |
||||
C:\exhibit\ |
||||
web\ # Next.js 專案 |
||||
.next\standalone\ # build 產物，pm2 在此跑 server.js |
||||
caddy\ |
||||
caddy.exe |
||||
Caddyfile |
||||
certs\ |
||||
cert.pem |
||||
key.pem |
||||
scripts\ |
||||
start-services.bat # 放進 startup 資料夾 |
||||
``` |
||||
|
||||
### 6.3 啟動順序與依賴 |
||||
|
||||
- Mosquitto（Windows Service）開機自動啟動，最先就緒。 |
||||
- Next.js 與 Caddy 由 bat 啟動；兩者彼此無依賴，皆連 Mosquitto。 |
||||
- bat 開頭可加短暫等待，確保 Mosquitto service 已就緒。 |
||||
|
||||
--- |
||||
|
||||
## 7. 範本檔案 |
||||
|
||||
### 7.1 `Caddyfile` |
||||
|
||||
```caddyfile |
||||
{ |
||||
# 關閉自動 HTTPS：區網自簽憑證，不走 ACME |
||||
auto_https off |
||||
} |
||||
|
||||
# 以 host IP 作為 site address |
||||
https://192.168.1.50 { |
||||
# 手動指定 mkcert 產出的憑證（Windows 路徑） |
||||
tls C:\caddy\certs\cert.pem C:\caddy\certs\key.pem |
||||
|
||||
# MQTT over WebSocket → 同機 Mosquitto 9001 |
||||
@mqtt path /mqtt* |
||||
handle @mqtt { |
||||
reverse_proxy localhost:9001 |
||||
} |
||||
|
||||
# 其餘流量 → Next.js |
||||
handle { |
||||
reverse_proxy localhost:3000 |
||||
} |
||||
} |
||||
``` |
||||
|
||||
> Caddy 會偵測憑證檔變動並嘗試熱載；重簽後通常只需覆寫 `cert.pem` / `key.pem`。實際行為請以你使用的 Caddy 版本實測確認，必要時 `caddy reload`。 |
||||
|
||||
### 7.2 `mosquitto.conf`（Windows Service） |
||||
|
||||
```conf |
||||
# TCP listener — 給區網內的 Unity client |
||||
listener 1883 0.0.0.0 |
||||
protocol mqtt |
||||
|
||||
# WebSocket listener — 由同機 Caddy 反代給 iPad（僅需 localhost） |
||||
listener 9001 localhost |
||||
protocol websockets |
||||
|
||||
# 封閉區網環境，允許匿名連線 |
||||
allow_anonymous true |
||||
|
||||
# 持久化（保留 retained message 與 session） |
||||
persistence true |
||||
persistence_location C:\Program Files\mosquitto\data\ |
||||
|
||||
# 日誌 |
||||
log_dest file C:\Program Files\mosquitto\mosquitto.log |
||||
log_type error |
||||
log_type warning |
||||
log_type notice |
||||
``` |
||||
|
||||
> 9001 綁 `localhost` 即可（只給同機 Caddy 反代用，不需對外）。1883 綁 `0.0.0.0` 讓區網內 Unity 主機連得到。修改 conf 後需重啟 Mosquitto service 生效。 |
||||
|
||||
### 7.3 Next.js standalone 設定 |
||||
|
||||
`next.config.js`： |
||||
|
||||
```js |
||||
/** @type {import('next').NextConfig} */ |
||||
const nextConfig = { |
||||
output: 'standalone', |
||||
}; |
||||
|
||||
module.exports = nextConfig; |
||||
``` |
||||
|
||||
Build 後處理（standalone 不含靜態資源，須手動複製）： |
||||
|
||||
```bat |
||||
:: 在專案根目錄 build 後執行 |
||||
xcopy /E /I /Y public .next\standalone\public |
||||
xcopy /E /I /Y .next\static .next\standalone\.next\static |
||||
``` |
||||
|
||||
> standalone 產物跑的是 `node server.js`，**不是** `next start`。`public\` 與 `.next\static` 漏複製會導致靜態資源 404。 |
||||
|
||||
### 7.4 啟動 bat：`C:\exhibit\scripts\start-services.bat` |
||||
|
||||
放進 startup 資料夾（`Win + R` → `shell:startup`），搭配 Windows 自動登入。 |
||||
|
||||
```bat |
||||
@echo off |
||||
:: 等待 Mosquitto service 就緒 |
||||
timeout /t 5 /nobreak |
||||
|
||||
:: 清掉前次殘留的 pm2 程序，確保乾淨啟動 |
||||
pm2 delete all |
||||
|
||||
:: 啟動 Next.js standalone |
||||
cd /d C:\exhibit\web\.next\standalone |
||||
pm2 start server.js --name nextjs |
||||
|
||||
:: 啟動 Caddy（用 caddy run 讓 pm2 接管，勿用 caddy start） |
||||
pm2 start "C:\caddy\caddy.exe" --name caddy -- run --config C:\caddy\Caddyfile |
||||
|
||||
:: 儲存目前程序清單 |
||||
pm2 save |
||||
``` |
||||
|
||||
環境變數（FTPS 帳密、對外 URL）建議用 pm2 ecosystem 檔注入，避免寫死於程式碼： |
||||
|
||||
`C:\exhibit\web\.next\standalone\ecosystem.config.js` |
||||
|
||||
```js |
||||
module.exports = { |
||||
apps: [ |
||||
{ |
||||
name: 'nextjs', |
||||
script: 'server.js', |
||||
env: { |
||||
NODE_ENV: 'production', |
||||
PORT: '3000', |
||||
FTPS_HOST: '<ftps-host>', |
||||
FTPS_USER: '<ftps-user>', |
||||
FTPS_PASSWORD: '<ftps-password>', |
||||
FTPS_SECURE: 'true', |
||||
PUBLIC_IMAGE_BASE_URL: '<向客戶確認後填入>', |
||||
}, |
||||
}, |
||||
], |
||||
}; |
||||
``` |
||||
|
||||
若改用 ecosystem 檔，bat 中 Next.js 那行改為： |
||||
|
||||
```bat |
||||
cd /d C:\exhibit\web\.next\standalone |
||||
pm2 start ecosystem.config.js |
||||
``` |
||||
|
||||
--- |
||||
|
||||
## 8. 開工檢查清單 |
||||
|
||||
部署現場最容易出問題的順序：**WiFi 延遲 > iPad 憑證信任那步 > 開機服務未自動拉起**。 |
||||
|
||||
- [ ] Host 設為固定 IP，憑證 SAN 包含此 IP |
||||
- [ ] mkcert CAROOT（`%LOCALAPPDATA%\mkcert`，含 `rootCA-key.pem`）已備份至異地 |
||||
- [ ] 三台 iPad 已安裝 RootCA **且啟用完整信任** |
||||
- [ ] 三台 iPad 設定 Single App Mode（Apple Configurator）並測試開機自動鎖機 |
||||
- [ ] iPad 自動鎖定設為「永不」＋ PWA 端 Wake Lock 實測 |
||||
- [ ] PWA manifest `display: standalone`、防呆 CSS（`overscroll-behavior`、`user-select`、`touch-action`） |
||||
- [ ] PWA service worker 更新策略：能偵測新版並刷新，避免跑到舊 code |
||||
- [ ] zustand persist 設定（hostIp / stationId）＋「重新設定」入口 |
||||
- [ ] Mosquitto 已註冊為 Windows Service 且設為自動啟動 |
||||
- [ ] **Windows 自動登入已設定**（`netplwiz`），bat 才會在開機後執行 |
||||
- [ ] start-services.bat 已放入 startup 資料夾 |
||||
- [ ] pm2 跑 Caddy 用 `caddy run`（非 `caddy start`） |
||||
- [ ] Next.js standalone 已複製 `public\` 與 `.next\static` |
||||
- [ ] Windows 防火牆放行 443、1883（對 Unity 主機） |
||||
- [ ] 與客戶確認 FTPS 上傳路徑對應的對外 HTTP(S) URL 規則 |
||||
- [ ] 與客戶確認 FTPS passive port range 未被防火牆擋 |
||||
- [ ] 上傳後 HEAD 驗證 URL 可達再產生 QR |
||||
- [ ] 上傳失敗的自動重試 + 手動重試 + 本地暫存補傳 |
||||
- [ ] **實際重新開機測試**：確認 Mosquitto / Next.js / Caddy 三者皆自動起來、iPad 連得上 |
||||
|
||||
--- |
||||
|
||||
## 9. 待釐清事項 |
||||
|
||||
1. **FTPS 上傳路徑 → 對外 URL 對應規則**（最高優先，影響 QR 內容是否可掃） |
||||
2. **iPad 與 station 的配對機制細節**（手動輸入 / QR 綁定 / URL 參數） |
||||
3. **QR 最終顯示位置**（iPad 先做，預期螢幕也需顯示 — 架構已支援零成本擴充） |
||||
4. Caddy 版本對憑證檔變動的熱載行為（決定重簽後是否需手動 reload） |
||||
5. Host 機器的 Win10 build 版本（確認 Node 20 相容性；過舊則退 Node 18） |
||||
Loading…
Reference in new issue