AdStackX 專案架構與設計思維：模組化、可擴展與高效能的廣告平台

在當今數位廣告瞬息萬變的環境中，一個高效、可擴展且安全的廣告後台系統至關重要。AdStackX 專案正是一個旨在解決這些挑戰的模組化廣告後台與 AI 推薦平台。本文將深入探討 AdStackX 的核心架構、各模組的設計考量，以及我們如何透過現代技術棧實現其高效能與可維護性。

您可以透過以下 GitHub 連結檢閱本專案的原始碼：https://github.com/BpsEason/ad-platform.git

專案概述與設計理念

AdStackX 採用了**微服務（Microservices）和多租戶（Multi-tenancy）**的設計理念，將複雜的廣告平台功能拆分為獨立、可部署的服務。這種設計帶來了以下核心優勢：

1. 模組化與解耦： 各服務獨立開發、部署與擴展，降低了系統的複雜性，提高了開發效率。

2. 可擴展性： 針對不同服務的負載特性，可以獨立擴展相應的服務，實現資源的最佳利用。

3. 技術多樣性： 允許不同服務選擇最適合其任務的技術棧，例如 Laravel 處理業務邏輯，FastAPI 處理 AI 推薦。

4. 高可用性與彈性： 單一服務的故障不會影響整個系統，提升了平台的穩定性。

5. 多租戶支援： 核心業務邏輯透過租戶隔離，確保不同客戶數據的獨立性與安全性。

整個專案由 Laravel 後台、FastAPI 推薦服務、Vue 3 前端應用以及一套強大的 DevOps 工具鏈組成，共同協作提供完整的廣告解決方案。

核心架構組件

1. Laravel 後台服務 (PHP)

Laravel 作為一個成熟且功能豐富的 PHP 框架，被選為 AdStackX 的核心後台服務。它承擔了以下關鍵職責：

• 廣告管理 (CRUD)： 提供廣告的創建、讀取、更新和刪除功能。

• 用戶認證與授權 (Auth & RBAC)： 透過 Laravel Sanctum 實現 API Token 認證，並結合 Spatie Laravel Permission 套件實現基於角色的存取控制 (RBAC) 和多租戶權限管理。

• 多租戶隔離： 利用 Eloquent Global Scopes 和自定義 Middleware (SetTenant)，確保所有數據操作都嚴格限定在當前租戶的範圍內，防止數據洩漏。

• 報表與分析： 提供廣告曝光、點擊和轉換率等核心指標的匯總報表 API。

• Traefik 動態配置生成： 透過 TraefikConfigController 提供一個 API 端點，動態生成 Traefik 的路由配置，實現新租戶上線時的自動化路由配置。此端點具備 API 密鑰驗證，增強安全性。

• API 速率限制： 透過 Laravel 內建的 throttle Middleware，對 API 請求進行速率限制，保護後端服務免受惡意攻擊或濫用。

• 健康檢查： 提供 /api/health 端點，供負載均衡器和監控系統檢查服務健康狀況。

設計思維： Laravel 的生態系統成熟，開發效率高，非常適合處理複雜的業務邏輯和數據管理。其內建的認證、ORM 和 Artisan 命令列工具極大地加速了開發進程。多租戶的實現是其核心，確保了平台的可擴展性和數據安全。

2. FastAPI 推薦服務 (Python)

FastAPI 是一個現代、快速 (基於 Starlette 和 Pydantic) 的 Python Web 框架，非常適合構建高效能的 API。它被用於處理 AdStackX 中的 AI 推薦邏輯和事件日誌：

• 動態推薦邏輯： /recommend 端點實現了基於用戶歷史事件（點擊、曝光）的增強型協同過濾推薦算法。它不僅考慮用戶互動過的廣告標籤，還引入了**近因效應（Recency）和廣告的歷史點擊率（CTR）**作為權重，使得推薦結果更加個性化和有效。

  • 數據來源： 直接從 MySQL 資料庫讀取 ads 和 events 表的數據，確保推薦模型使用最新且真實的用戶行為數據。

  • 彈性處理： 如果用戶沒有歷史數據，會自動回退到基於廣告整體 CTR 的熱門推薦。

• 事件日誌： /log-event 端點用於接收前端或其他服務發送的用戶行為事件（如廣告曝光、點擊）。

  • Kafka 集成： 事件首先嘗試推送到 Kafka 消息隊列。Kafka 提供了高吞吐量、持久化和容錯能力，適合處理大量的即時事件流。

  • Redis 緩存作為備援： 如果 Kafka 不可用，事件將回退到 Redis 緩存。Redis 作為一個快速的記憶體數據庫，可以臨時儲存事件，等待 Kafka 恢復後再處理。

  • 檔案日誌作為最終備援： 在 Kafka 和 Redis 都失效的極端情況下，事件會寫入本地檔案，確保數據不會丟失。

• 健康檢查： 提供 /health 端點。

設計思維： 選擇 FastAPI 是因為 Python 在數據科學和機器學習領域的強大生態系統，以及 FastAPI 本身的高效能。將推薦邏輯獨立出來，使其可以獨立擴展，並利用消息隊列處理事件，實現了異步處理和系統解耦，避免了推薦服務成為整個平台的瓶頸。

3. Vue 3 前端應用 (JavaScript)

前端應用基於 Vue 3 和 Vite 構建，為用戶提供直觀的廣告報表儀表板。

• 報表數據可視化： 利用 Chart.js 和 Apache ECharts 庫，將後台提供的報表數據（如每日曝光、點擊、轉換率）以圖表形式清晰呈現。

• 多租戶選擇： 用戶可以透過下拉選單切換不同的租戶，查看對應的廣告數據。前端會自動在請求頭中帶上 X-Tenant-Id。

• 載入動畫： 在數據載入過程中顯示友好的載入動畫，提升用戶體驗，避免頁面卡頓感。

• 離線支援與數據快取： 透過 localStorage 機制快取報表數據。當用戶再次訪問或網路不佳時，可以優先從本地快取載入數據，提供更快的響應速度和基本的離線能力。

• 前端測試： 採用 Vitest 進行單元測試，確保組件邏輯的正確性。

• Nginx 靜態服務： 前端應用透過 Vite 打包後，由 Nginx 服務靜態檔案，實現高效的內容分發。

設計思維： Vue 3 提供了更優的性能和 Composition API，使得組件邏輯更清晰、更易於維護。數據可視化是報表應用核心，選擇成熟的圖表庫保證了數據呈現的專業性。離線快取和載入動畫則專注於提升最終用戶的體驗。

DevOps 與基礎設施

一個健壯的應用需要強大的 DevOps 支援。AdStackX 的 DevOps 策略涵蓋了容器化、服務發現、監控和自動化部署。

• Docker 與 Docker Compose： 所有服務都被容器化，並透過 docker-compose.yml 進行統一管理和部署。這確保了開發、測試和生產環境的一致性。

  • Laravel Dockerfile： 基於 php:8.1-fpm-alpine，包含 Nginx 配置，並透過 entrypoint.sh 自動生成 APP_KEY 和動態獲取 Traefik 配置。

  • FastAPI Dockerfile： 輕量級 Python 映像檔，安裝必要的依賴。

  • Frontend Dockerfile： 兩階段建置，首先使用 Node.js 進行 Vue 應用建置，然後使用 Nginx 映像檔服務靜態檔案。

• Traefik 反向代理與服務發現： Traefik 作為邊緣路由器，負責將外部請求路由到正確的內部服務。

  • Docker Provider： Traefik 自動發現 Docker 容器，並根據容器上的 Label 配置路由規則。

  • File Provider： 結合 Laravel 的 TraefikConfigController，實現基於租戶域名的動態路由配置，無需手動修改 Traefik 配置即可添加新租戶域名。

  • HTTPS/TLS： 支援 HTTPS 配置，可透過環境變數啟用，並可整合 Let's Encrypt 等憑證服務。

• MySQL 資料庫： 採用 MySQL 8.0，並透過 init.sql 腳本進行自動初始化，包含租戶、廣告和事件的初始數據，方便快速啟動開發環境。

• Redis 緩存與消息佇列： 用於 Laravel 的緩存、Session 管理以及 FastAPI 的事件日誌備援。

• Zookeeper 與 Kafka 集群： 構建高可用的消息隊列系統。Zookeeper 提供集群協調服務，Kafka 則用於處理高吞吐量的事件流，確保事件日誌的可靠性。

• Prometheus 與 Grafana 監控：

  • Prometheus： 負責從各服務（Traefik、cAdvisor）抓取指標數據。未來可為 Laravel 和 FastAPI 集成自定義指標，提供更細緻的應用層監控。

  • Grafana： 提供可視化的儀表板，透過 provisioning 配置自動連接 Prometheus 資料源並載入預設儀表板，方便快速查看服務的健康狀況、CPU、記憶體和網路 I/O 等關鍵指標。

  • cAdvisor： 收集 Docker 容器的運行時指標，為 Prometheus 提供數據源。

• GitHub Actions CI/CD： 自動化建置、測試和部署流程。

  • 服務健康檢查： CI 流程中包含對所有 Docker 服務的健康檢查，確保在執行測試前所有依賴服務都已啟動並正常運行。特別針對 Zookeeper 和 Kafka 增加了更穩定的檢查方式。

  • 自動化測試： 執行 Laravel 的 PHPUnit 測試、FastAPI 的 Pytest 測試和 Vue 前端的 Vitest 測試，確保代碼品質。

  • 清理： 測試完成後自動清理 Docker 資源。

設計思維： 容器化和自動化是現代 DevOps 的基石。透過 Docker Compose 簡化了多服務的本地開發和部署。Traefik 提供了靈活的路由能力。完整的監控棧則確保了系統的可觀測性，能夠及時發現並解決問題。CI/CD 管道則將這些流程自動化，提升了開發效率和部署可靠性。

結論

AdStackX 專案展示了一個如何透過模組化設計和現代技術棧構建可擴展、高效能且安全的廣告平台的範例。從 Laravel 處理核心業務邏輯，到 FastAPI 提供智能推薦，再到 Vue 3 打造流暢的前端體驗，以及強大的 DevOps 工具鏈支撐整個生命週期，每個組件都經過精心選擇和設計，以實現最佳的協同作用。

這個架構不僅為未來的功能擴展提供了堅實的基礎，也為處理高併發和複雜數據提供了可靠的解決方案。希望這篇部落格能幫助您更好地理解 AdStackX 的設計理念與技術實現。