Arova Nexus 技術堆疊規格

系統架構

Arova Nexus 技術堆疊規格

Arova Nexus — Phase 0 Product Definition ｜ 2026-03-31

狀態：鎖定（Locked） — 本文件為技術堆疊的唯一權威來源。所有 Product Guide、Wireframe、架構設計必須符合本規格。變更本文件需經技術負責人核准。

錨定技術

以下兩項為技術選型的起點，所有其他決策由此推導：

前端：React / TypeScript / shadcn/ui / Tailwind CSS
AI 框架：Mastra AI (https://mastra.ai/)

總覽

層級	技術	說明
語言	TypeScript 5.x+	前後端統一語言
執行環境	Node.js 22+	Mastra 最低要求
前端	React 19 + Next.js 15	shadcn/ui 與 Mastra 的最佳整合框架
UI 元件	shadcn/ui	基於 Radix UI，Tailwind 原生
樣式	Tailwind CSS 4	Utility-first
AI 框架	Mastra AI	Agent、Workflow、RAG、Memory、MCP
HTTP 伺服器	Hono	Mastra 內建，輕量高效能
資料庫	PostgreSQL 16+	關聯式資料 + pgvector 向量搜尋
快取	Redis 7+	Session、排程佇列、指標快取
容器化	Docker Compose	地端部署標準方式

前端

技術選擇理由

選擇	理由
Next.js 15	shadcn/ui 官方支援框架；Mastra 提供 `@mastra/ai-sdk` 整合；App Router 支援 Server Components + Streaming
shadcn/ui	非套件、直接複製元件原始碼，完全可控；Radix UI 基礎確保無障礙；Tailwind 原生樣式
Tailwind CSS 4	與 shadcn/ui 緊密整合；設計 token 透過 CSS 變數管理主題
@ai-sdk/react	Vercel AI SDK 的 React hooks（useChat、useCompletion）；Mastra 透過 `@mastra/ai-sdk` 橋接

前端套件

套件	用途
next	Meta-framework（SSR、API Routes、App Router）
react / react-dom	UI Library
tailwindcss	Utility-first CSS
@radix-ui/*	shadcn/ui 底層元件（由 shadcn CLI 安裝）
@ai-sdk/react	AI 對話介面 hooks
@mastra/ai-sdk	Mastra Agent/Workflow streaming 橋接
react-hook-form	表單狀態管理
zod	Schema 驗證（與後端共用）
@tanstack/react-table	資料表格（shadcn/ui Data Table）
recharts	圖表（shadcn/ui Charts）
nuqs	URL 狀態管理（篩選、分頁）
next-themes	深色/淺色主題切換
next-intl	i18n（zh-TW、en）

設計原則

AI Copilot 為主要操作介面，傳統 UI 為 fallback
深色 / 淺色主題，透過 shadcn/ui 的 CSS 變數切換
繁體中文（zh-TW）為主，英文（en）為輔
桌面優先，響應式支援平板
A4 列印友善（報表頁面）

後端

Mastra AI 套件

套件	用途
@mastra/core	Agent 定義、Tool calling、Workflow、Model Router
@mastra/memory	對話歷史、語意回溯、工作記憶
@mastra/rag	文件切塊（recursive / sliding window）、Embedding、向量檢索
@mastra/mcp	MCP Client（連接外部工具）/ MCP Server（暴露 Nexus 能力）
@mastra/evals	Agent 品質評分、回溯分析

Mastra 核心能力對應產品功能

Mastra 能力	產品功能
Agent + Tool calling	AI Copilot 對話、系統狀態查詢、工單操作
Workflow (createWorkflow)	自動化流程編排、審核流程（suspend/resume）
Multi-Agent (Supervisor)	多 Agent 協作：Triage、Correlation、Anomaly Detection
RAG	知識庫語意搜尋、文件 QA
Memory	對話上下文保留、使用者偏好記憶
Model Router	LLM 供應商切換、自動 failover
MCP Client	連接 LibreNMS、Graylog 等外部系統工具
MCP Server	將 Nexus Agent 能力暴露給其他 MCP Client

LLM 策略

透過 Mastra Model Router 統一管理，不綁定特定供應商：

用途	配置方式	說明
推論	`model: "provider/model-name"`	由部署環境決定（地端 Ollama / 雲端 API）
Embedding	`model: "provider/embedding-model"`	RAG 向量化，建議 CJK 優化模型
Failover	Model Router fallback chain	主模型不可用時自動切換備援

具體模型選擇為部署時配置，不寫死在程式碼中。

後端輔助套件

套件	用途
hono	HTTP 伺服器（Mastra 內建）
zod	API Schema 驗證、Tool input/output schema
bullmq	排程佇列（報表產生、通知重試、AI 背景作業）
nodemailer	Email 通知
puppeteer	報表 HTML → PDF
handlebars	報表模板引擎
jose	JWT 處理（認證）

資料層

PostgreSQL + pgvector

統一使用 PostgreSQL 處理關聯式資料與向量搜尋，不額外部署向量資料庫：

用途	機制
核心業務資料	標準 relational schema
AI 中繼資料	JSONB 欄位（分類、摘要、推理鏈）
向量搜尋	pgvector 擴充套件，Mastra RAG 原生支援
Mastra 儲存	Thread、Message、Trace、Workflow snapshot
稽核日誌	Append-only table
密鑰	加密欄位

選擇 pgvector 而非獨立向量資料庫的理由：

少一個服務 → 部署與維運更簡單
交易一致性：向量與業務資料在同一交易中更新
Mastra RAG 原生支援 pgvector
地端單節點規模下效能足夠

Redis

用途	說明
Session 儲存	httpOnly cookie 對應的 session 資料
BullMQ 後端	排程任務佇列
快取	Dashboard 指標、AI Briefing

整合方式

所有外部系統整合透過 Mastra Tool + MCP 實現：

整合對象	方式	說明
監控系統（LibreNMS、Datadog 等）	Mastra Tool / MCP Client	Agent 可呼叫查詢設備狀態、指標
日誌系統（Graylog 等）	Mastra Tool / MCP Client	Agent 可呼叫搜尋日誌、產生統計
目錄服務（AD / LDAP）	Mastra Tool	使用者驗證、帳號管理
通知管道（Email、Slack、Line）	Mastra Tool	Agent / Workflow 觸發通知
Webhook 接收	Hono API Route	接收外部告警，轉換為 Incident
MCP 工具生態	@mastra/mcp	連接任意 MCP-compatible 工具

部署架構

地端部署（Docker Compose）

Docker Compose
├── app        (Next.js + Mastra Server)
├── postgres   (PostgreSQL 16 + pgvector)
├── redis      (Redis 7)
└── ollama     (Ollama，選配地端 LLM)

四個容器。Ollama 為選配 — 若使用雲端 LLM API 則不需要。

部署原則

資料留在客戶端基礎設施
無硬性外部網路依賴
LLM 可地端（Ollama）或雲端（API），由配置決定
未來可擴展至 Kubernetes

禁止事項

以下技術不得出現在 Arova Nexus 的實作中：

禁止	理由
Python	全棧統一 TypeScript
LangChain / LangGraph	已由 Mastra AI 取代
Angular / Vue.js	前端統一 React
MySQL / MariaDB / MongoDB	統一 PostgreSQL
獨立向量資料庫（Qdrant / Milvus / Pinecone）	使用 pgvector，減少服務數
Webpack / Vite 獨立配置	使用 Next.js 內建 Turbopack
Express.js / Fastify	使用 Hono（Mastra 內建）

Mastra 原始碼驗證結果

以下結論基於 Mastra AI 原始碼分析（2026-04-01），commit: mastra-ai/mastra@HEAD

Mastra 原生覆蓋的產品需求

產品需求	Mastra 能力	驗證套件
AI Copilot 對話	Agent + Tool calling + SSE Streaming	@mastra/core
多 Agent 協作	Supervisor pattern（取代已棄用的 Agent Network）	@mastra/core
自動化工作流程	createWorkflow + suspend/resume + 並行/分支	@mastra/core
知識庫語意搜尋	RAG + pgvector（含混合搜尋 sparsevec）	@mastra/rag + @mastra/pg
對話記憶	歷史、語意回溯、工作記憶、觀察式記憶	@mastra/memory
LLM 供應商切換	Model Router（94 供應商、3567+ 模型、fallback chain）	@mastra/core
外部工具整合	MCP Client/Server + OAuth	@mastra/mcp
RBAC 權限控制	StaticRBACProvider（resource 層級權限）	@mastra/core (EE)
JWT 認證	MastraJwtAuth + JWKS（RS256）	@mastra/auth
Agent 品質評估	12+ 預建評分器 + 自訂 Scorer Pipeline	@mastra/evals
可觀測性	Span/Trace + OpenTelemetry 匯出	@mastra/core
Webhook 接收	Hono registerApiRoute	@mastra/server
自訂業務資料	PostgreSQL 共存（Mastra 用 `mastra_` prefix）	@mastra/pg

需要自行實作的缺口

缺口	影響程度	解法	工作量
背景排程	高	BullMQ（已納入技術堆疊，Redis 支撐）	中
LDAP/AD 整合	高	自訂 SSO Provider + Mastra Tool	中
稽核日誌	高	自訂 Mastra Processor + append-only table	低
Rate Limiting	中	Hono middleware	低
CJK 文件切塊	中	自訂 Sentence Transformer（現有為英文導向）	中
WebSocket	低	SSE 已足夠；需要時加 Hono WebSocket adapter	低
通知系統	低	自訂 Mastra Tool（Nodemailer / Webhook）	低
分散式事件匯流排	低	Phase 1 單節點不需要；Phase 2+ 再評估	延後

已知限制與風險

CJK 文件切塊（中等風險）

Mastra 的 Sentence Transformer（packages/rag/src/document/transformers/sentence.ts）使用英文導向正則表達式（偵測大寫字母、英文縮寫 "Dr.", "Mr."），對繁體中文斷句不理想。

短期解法：使用 character 或 token 切塊策略（語言無關）
長期解法：實作自訂 CJK Sentence Transformer
影響範圍：僅影響 RAG 搜尋精準度，不影響系統架構

即時通訊（低風險）

Mastra 僅支援 SSE（單向 Server→Client），不支援 WebSocket 雙向通訊。Dashboard 即時更新使用 SSE polling 即可滿足需求。

資料庫遷移（低風險）

Mastra 使用 init() + ifNotExists 模式自動建立/擴充 schema，無傳統 migration 機制。自訂業務 table 的 migration 需自行管理（建議使用 Drizzle ORM 或 Prisma）。

變更控制

本文件為鎖定狀態。若需修改：

提出 OpenSpec proposal，說明變更理由與影響評估
技術負責人核准
更新本文件並同步更新所有受影響的 Product Guide 與 Wireframe

← 上一篇Arova Nexus 系統架構下一篇 →Tool 擴展方案設計