Star Cloud 智能販賣機管理平台

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

Star Cloud 是一個專為智能販賣機設計的後台管理系統，提供機台監控、庫存管理、銷售分析與會員管理等完整功能。本專案採用 Docker Compose 容器化架構，實現快速部署與環境一致性。

---

技術架構

容器化架構

本專案完全運行在 Docker 容器中，包含以下服務：

服務	容器名稱	技術	用途	連接埠
應用程式	star-cloud-laravel	Laravel 10 + PHP 8.5	Web 應用與 API	8090:80, 5175:5175
資料庫	star-cloud-mysql	MySQL 8.0	關聯式資料庫	3306:3306
快取	star-cloud-redis	Redis Alpine	快取與 Session	6380:6379

後端技術棧

• Framework: Laravel 10.x
• Language: PHP 8.5+
• Database: MySQL 8.0
• Cache/Session: Redis
• Authentication: Laravel Sanctum (API Token)
• Package Manager: Composer 2.x

前端技術棧

• Template Engine: Blade Templates
• UI Library: Preline UI 3.x (Tailwind CSS 組件庫)
• CSS Framework: Tailwind CSS 3.x
• JavaScript: Alpine.js 3.x (輕量級互動框架)
• Build Tool: Vite 5.x
• HTTP Client: Axios

---

快速開始

前置需求

確保您的系統已安裝以下軟體：

• Docker 20.10+
• Docker Compose 2.0+
• Git

提示：Windows 使用者建議安裝 Docker Desktop，Linux 使用者可參考 官方安裝文件

安裝步驟

1. Clone 專案

git clone <repository_url>
cd star-cloud

2. 環境設定

複製環境變數範例檔案：

cp .env.example .env

重要設定（.env 檔案）：

# 應用程式設定
APP_NAME=Star Cloud
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8090

# 資料庫設定（對應 Docker Compose 服務）
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=star_cloud
DB_USERNAME=sail
DB_PASSWORD=password

# Redis 設定（對應 Docker Compose 服務）
REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379

# Vite 開發伺服器
VITE_PORT=5175

3. 啟動 Docker 容器

啟動所有服務（應用程式、資料庫、Redis）：

docker compose up -d

說明：-d 參數表示背景執行

檢查容器狀態：

docker compose ps

預期輸出：

NAME                 STATUS         PORTS
star-cloud-laravel   Up X minutes   0.0.0.0:8090->80/tcp, 0.0.0.0:5175->5175/tcp
star-cloud-mysql     Up X minutes   0.0.0.0:3306->3306/tcp
star-cloud-redis     Up X minutes   0.0.0.0:6380->6379/tcp

4. 初始化應用程式

4.1 安裝後端依賴

docker compose exec laravel.test composer install

4.2 產生應用程式金鑰

docker compose exec laravel.test php artisan key:generate

4.3 執行資料庫遷移與種子

docker compose exec laravel.test php artisan migrate --seed

預設管理員帳號：

• Email: admin@star-cloud.com
• Password: password

4.4 安裝前端依賴

docker compose exec laravel.test npm install

4.5 編譯前端資源

# 開發模式（支援 Hot Module Replacement）
docker compose exec laravel.test npm run dev

# 或生產模式
docker compose exec laravel.test npm run build

5. 訪問應用程式

• 應用程式: http://localhost:8090
• Vite Dev Server: http://localhost:5175

---

Docker 常用指令

容器管理

# 啟動所有服務
docker compose up -d

# 停止所有服務
docker compose down

# 重啟服務
docker compose restart

# 查看容器日誌
docker compose logs -f laravel.test

# 進入應用程式容器
docker compose exec laravel.test bash

Laravel 指令

所有 Laravel Artisan 指令需在容器內執行：

# 執行 Artisan 指令
docker compose exec laravel.test php artisan <command>

# 範例：清除快取
docker compose exec laravel.test php artisan cache:clear

# 範例：執行 Migration
docker compose exec laravel.test php artisan migrate

# 範例：建立新 Controller
docker compose exec laravel.test php artisan make:controller ExampleController

前端開發

# 安裝 npm 套件
docker compose exec laravel.test npm install

# 開發模式（即時編譯）
docker compose exec laravel.test npm run dev

# 生產編譯
docker compose exec laravel.test npm run build

資料庫操作

# 進入 MySQL 容器
docker compose exec mysql bash

# 直接執行 SQL
docker compose exec mysql mysql -u sail -ppassword star_cloud

# 備份資料庫
docker compose exec mysql mysqldump -u sail -ppassword star_cloud > backup.sql

# 還原資料庫
docker compose exec -T mysql mysql -u sail -ppassword star_cloud < backup.sql

---

主要功能模組

核心功能

模組	功能描述
儀錶板	銷售數據總覽、機台狀態即時監控、營收統計圖表
機台管理	機台列表、遠端控制、日誌查詢、維修管理、效期控制
倉庫管理	倉庫列表、庫存管理、調撥單、採購單、補貨單
商品管理	商品資料、分類管理、商品報表分析
銷售管理	交易紀錄、金流管理、促銷設定、營收報表
會員系統	會員管理、點數系統、來店禮、Line 整合
權限控制	角色管理、權限分配、功能權限設定
遠端管理	機台重啟、遠端出貨、遠端結帳、庫存調整

---

Preline UI 組件庫

本專案已整合 Preline UI 3.x，這是一個基於 Tailwind CSS 的開源 UI 組件庫，提供 50+ 預構建組件。

可用組件類別

• Navigation: 導航列、側邊欄、分頁、麵包屑、頁籤
• Forms: 輸入框、選擇器、開關、檔案上傳、日期選擇器
• Overlays: 模態框、抽屜、下拉選單、提示框、彈出框
• Data Display: 表格、卡片、時間軸、折疊面板、徽章
• Feedback: 通知、警告、載入狀態、進度條

使用範例

<!-- 下拉選單 -->
<div class="hs-dropdown relative inline-flex">
  <button type="button" class="hs-dropdown-toggle px-4 py-2 bg-blue-600 text-white rounded-lg">
    選單 <svg class="w-4 h-4 inline ml-2">...</svg>
  </button>
  <div class="hs-dropdown-menu hidden bg-white shadow-lg rounded-lg p-2 mt-2">
    <a class="block px-3 py-2 rounded hover:bg-gray-100" href="#">選項 1</a>
    <a class="block px-3 py-2 rounded hover:bg-gray-100" href="#">選項 2</a>
  </div>
</div>

<!-- 模態框 -->
<button type="button" data-hs-overlay="#my-modal" class="px-4 py-2 bg-blue-600 text-white rounded-lg">
  開啟模態框
</button>
<div id="my-modal" class="hs-overlay hidden">
  <!-- 模態框內容 -->
</div>

更多資源：

• 官方文件: https://preline.co/docs/
• 組件範例: https://preline.co/examples.html
• GitHub: https://github.com/htmlstreamofficial/preline

---

故障排除

容器無法啟動

# 檢查容器日誌
docker compose logs

# 重建容器
docker compose down
docker compose up -d --build

連接資料庫失敗

確認 .env 中 DB_HOST 設定為 mysql（容器服務名稱），而非 127.0.0.1。

前端資源編譯失敗

# 清除 node_modules 重新安裝
docker compose exec laravel.test rm -rf node_modules
docker compose exec laravel.test npm install
docker compose exec laravel.test npm run build

權限問題

# 修正儲存目錄權限
docker compose exec laravel.test chmod -R 775 storage bootstrap/cache

---

部署至生產環境

1. 環境變數設定

將 .env 中的設定調整為生產環境：

APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

2. 編譯前端資源

docker compose exec laravel.test npm run build

3. 優化 Laravel

docker compose exec laravel.test php artisan config:cache
docker compose exec laravel.test php artisan route:cache
docker compose exec laravel.test php artisan view:cache

4. 設定 HTTPS

建議使用 Nginx Reverse Proxy + Let's Encrypt SSL 憑證。

---

開發團隊協作

Git Workflow

# 拉取最新程式碼
git pull origin main

# 重建容器（若 Docker 設定有變更）
docker compose down
docker compose up -d

# 更新依賴
docker compose exec laravel.test composer install
docker compose exec laravel.test npm install

# 執行 Migration
docker compose exec laravel.test php artisan migrate

---

授權與版權

© Star Cloud. All Rights Reserved.

---

技術支援

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