sky121113 e3ad7dd44f [DOCS] 修正並對齊 Demo 環境基礎設施資訊

1. 更新 README.md 與 framework.md 中的 Demo 環境網域、伺服器指令、部署路徑。
2. 更新 Gitea Workflow (.gitea/workflows/) 中的 Gitea 官方網址 (gitea.setdomains.work)。
3. 更新遠端部署模板中的舊 IP、路徑與機器人信箱，確保全站文件一致性。

2026-04-17 10:30:05 +08:00

5.3 KiB

Raw Blame History

Star Cloud 智能販賣機管理平台

基於 Docker 的全方位智能販賣機後台管理系統 (Cloud 平台)

Star Cloud 是一個專為智能販賣機設計的後台管理系統，負責管理機台、商品、銷售數據，並為硬體端點提供專用的 API。

🚀 技術架構

核心架構

本專案採用 Monorepo 單體式架構，以 Laravel 為核心進行伺服器端渲染 (SSR) 與 API 服務，並搭配 Go MQTT Gateway 作為高併發 IoT 通訊的前置接收層。兩者透過 Redis 進行異步橋接。

服務	容器名稱	技術	用途	本地 Port
應用程式	`star-cloud-laravel`	Laravel 12 + PHP 8.5	核心業務與渲染	8090
背景隊列	`star-cloud-queue`	Laravel Queue Worker	異步任務處理	-
資料庫	`star-cloud-mysql`	MySQL 8.0	數據持久化	3306
快取/隊列	`star-cloud-redis`	Redis Alpine	IoT 高併發隊列與 MQTT 橋接	6380
MQTT Broker	`star-cloud-emqx`	EMQX 5.10	機台長連線與訊息路由	1883 / 18083
MQTT Gateway	`star-cloud-mqtt-gateway`	Go	訂閱 MQTT Topic、轉發至 Redis	-

後端技術棧

Framework: Laravel 12.x
Language: PHP 8.5
Redis: 用於 IoT 高併發隊列與 MQTT 橋接
Database: MySQL 8.0

IoT 通訊層

MQTT Broker: EMQX 5.10 (維持機台長連線與訊息路由)
MQTT Gateway: Go (訂閱 MQTT Topic、預處理訊息、轉發至 Redis)
橋接機制: Redis List (mqtt_incoming_jobs)，由 Laravel 常駐指令 (mqtt:listen) 消費

前端技術棧

View: Laravel Blade
CSS: Tailwind CSS + Preline UI
JS: Alpine.js (行為控制)
Build: Vite

🛠️ 開發環境 (Laravel Sail)

本專案建議使用 Laravel Sail 進行開發，避免直接在宿主機執行指令。

前置需求

Docker Desktop (Windows/Mac) 或 Docker Engine (Linux)
Git

快速啟動

clone 專案並進入目錄
cp .env.example .env
./vendor/bin/sail up -d
./vendor/bin/sail composer install
./vendor/bin/sail artisan key:generate
./vendor/bin/sail artisan migrate --seed
./vendor/bin/sail npm install
./vendor/bin/sail npm run dev
./vendor/bin/sail artisan mqtt:sync-auth (同步機台 MQTT 認證至 Redis)
./vendor/bin/sail artisan mqtt:listen (啟動 MQTT 訊息消費者)

常用開發指令

功能	指令
啟動環境	`./vendor/bin/sail up -d`
停止環境	`./vendor/bin/sail down`
Artisan 指令	`./vendor/bin/sail artisan <cmd>`
Composer 指令	`./vendor/bin/sail composer <cmd>`
NPM 指令	`./vendor/bin/sail npm <cmd>`
執行測試	`./vendor/bin/sail test`
MQTT 認證同步	`./vendor/bin/sail artisan mqtt:sync-auth`
MQTT 隊列監聽	`./vendor/bin/sail artisan mqtt:listen`
重建 Gateway	`docker compose build mqtt-gateway && docker compose up -d mqtt-gateway`

🔐 API 規範

系統 API 分為兩大類，遵循不同的設計慣例：

1. Admin/Web API (`/api/v1/...`)

對象: 後台管理介面、APP UI。
認證: Laravel Sanctum (Session/Token)。
格式: 標準 RESTful JSON。

2. Machine IoT API (`/api/app/...`)

對象: 智能販賣機、計時器等硬體。
認證: Header Authorization: Bearer <api_token>。
高併發處理: 核心日誌 (B010 心跳、B600 交易) 嚴禁直寫 DB，必須進入 Redis Queue 背景異步處理。

3. MQTT IoT 通訊

對象: 高頻/即時性機台通訊 (心跳、異常、交易)。
認證: EMQX 透過 Redis Hash 驗證 (machine_auth:{serial_no} → password 欄位)。
資料流向: 機台 ➜ EMQX ➜ Go Gateway ➜ Redis List ➜ Laravel mqtt:listen ➜ Job ➜ MySQL

🌐 多語系支援 (I18n)

所有 UI 顯示文字必須支援多語系，禁止 Hard-coded。

語系檔案: lang/zh_TW.json, lang/en.json, lang/ja.json。
呼叫方式: 使用 __('Phrases in English') 或 @lang('...')。
命名規範: 優先使用「英文原始詞彙」作為 Key 名稱。

📂 目錄結構

Laravel (PHP)

app/Http/Controllers/: 控制器
app/Models/{Domain}/: 分領域的模型 (如 Machine, Member)
app/Services/{Domain}/: 封裝商業邏輯與資料異動
app/Jobs/{Domain}/: IoT 異步隊列處理任務 (重要)
app/Console/Commands/: Artisan 指令 (含 mqtt:listen, mqtt:sync-auth)
resources/views/: Blade 模板 (按功能分資料夾)
resources/views/components/: 可重用的 UI 組件
routes/: 路由定義 (web.php 與 api.php)

MQTT Gateway (Go)

mqtt-gateway/main.go: 進入點 (MQTT 連線、Redis 初始化)
mqtt-gateway/config/: 環境變數與連線設定
mqtt-gateway/internal/handler/: MQTT Topic 訊息處理邏輯
mqtt-gateway/internal/bridge/: Redis 橋接層 (RPush / Consumer)

🚢 CI/CD 與部署

自動化工具: Gitea Actions (.gitea/workflows/)。
Demo 環境: 推送到 demo 分支會自動部署至 demo-cloud.setdomains.work。
伺服器路徑: /workspace/mama/star-cloud (透過 ssh demo-sc-103 登入)。

授權與版權

技術支援

如有問題或建議，請聯繫開發團隊或提交 Issue。

5.3 KiB Raw Blame History