AI 應用系列 4 | AstrBot 串接網站 Widget：架構選型、實測與雙版本並行的思考

一、起點：我到底要什麼

一開始的需求很單純：訪客在網頁上開一個聊天窗，輸入問題，後面由 AstrBot 的 AI 與知識庫回答。就這樣。

我先給自己定了幾條 MVP 底線：

• 前端要能用 WSS 即時連線，回覆最好能看到串流效果。
• 後端要有 API，之後能接 ERP、CRM、知識庫、工單。
• 可以商用，授權不要有疑慮。
• 維運成本越低越好，我是一個人在維護。
• 先能用，再談完整，不要一開始就蓋一座城堡。

這幾條底線，後面所有選型都是拿來對照的。

二、第一步：先確認 AstrBot 有沒有現成方案

我先查了 AstrBot 的平台與插件。結論是：它內建的 WebUI 有 ChatUI，但那是管理介面裡的對話窗，不是給外部網站嵌入的客服 widget。插件市集也沒有找到現成的「網站聊天窗」平台。

另一條路是 OneBot。我搜尋了相關開源專案，找到的多半是 QQ 風格的網頁聊天面板，用途是操作機器人帳號，沒有訪客識別、匿名會話、多訪客隔離這些客服場景需要的東西，所以也排除。

真正有用的是 AstrBot 的 HTTP API：用 API Key 驗證，呼叫對話端點就能取得 Agent 的回覆（SSE 串流），插件、工具、知識庫都能一起用，效果與 IM 端一致。這是整個方案的關鍵，因為它代表我只需要做「前端加一層薄薄的中轉」，不必碰 AstrBot 內部。

三、為什麼不直接用功能完整的開源客服系統

我當然想過「直接用現成的」。我實際比較過幾條路線：

我最後得到的判斷是：

1. 完整客服系統的複雜度，是我暫時用不到的成本。 後台、角色、SLA、多渠道收件匣，這些功能都要有人學、有人維護、有人升級。
2. 我真正缺的只是「一個能接 AstrBot 的聊天窗」。 現成系統的整合點（Webhook、Agent Bot）還是要我再寫一層中轉，等於複雜度沒省到，反而多了一堆我不想管的東西。
3. 授權與計費模式要看清楚。 有些專案標榜開源，但關鍵功能在企業版目錄裡，商用前必須逐一看授權條款。

所以我的結論不是「這些系統不好」，而是「它們解決的問題，比我現在的問題大得多」。

四、為什麼選擇複用寶塔技術棧

我的伺服器本來就是寶塔面板，Nginx、PHP 8.2、MySQL 都在，網域和 SSL 也設定好了，AstrBot 還掛在同一個網域的根路徑做反向代理。

如果另外引入一個 Node 或 Rails 服務，我要多處理的是：執行環境、進程守護、反向代理、日誌、升級與備份。對一個人維運來說，每多一個技術棧，風險就多一份。

所以我選擇：

• 前端頁面用 PHP 模板，直接改寫我原本的客服頁面 HTML。
• 中轉層用 PHP，保持和現有環境一致。
• 資料庫預留 MySQL，需要記錄對話時直接用。

唯一的例外是 WebSocket。PHP-FPM 是「一個請求一個程序」的模型，不適合長時間維持連線。我的解法是在旁邊用 Workerman（PHP 的事件驅動 Socket 框架）跑一個只監聽本機的 WSS 服務，再由 Nginx 代理成對外的 wss://。這樣仍然是 PHP，只是多了一個常駐程序，由 systemd 管理。

五、實作細節（簡略版）

整體路徑只有幾段：

瀏覽器 ──WSS──► Nginx ──► Workerman (PHP) ──HTTP/SSE──► AstrBot API

幾個我認為重要的設計選擇：

• API Key 只放伺服器端，瀏覽器拿不到。
• 訪客身分用 cookie 加 HMAC 簽章的 token，WSS 與 HTTP 都驗證 token 和 Origin，另外有限流與訊息長度限制。
• 備援模式：WSS 連續失敗幾次後，前端自動改用 HTTP 呼叫，這樣就算 WebSocket 出問題，聊天還是能用。
• 前端只有一支 JS：浮動按鈕、聊天窗、可拖曳縮放、簡易 Markdown 編輯器、表情、附件。AI 的回覆也用同一套安全的渲染（先轉義 HTML 再套格式）。
• 附件走 HTTP 上傳到 PHP，驗證後再轉傳給 AstrBot 的檔案端點，最後訊息才走 WSS，檔案不經過 WebSocket。
• 訪客資料：已登入會員直接帶入姓名；未登入訪客可填姓名與 Email，也可以略過。

踩到的坑

這部分我覺得比「怎麼做」更有分享價值：

1. Nginx 的 location ^~ /chat/ 會擋住 PHP。 帶 ^~ 的前綴規則會讓 Nginx 跳過正則規則，PHP 就不會被處理，頁面變成下載。拿掉 ^~ 即可。
2. 用 curl 測 WebSocket，結果誤判失敗。 站點開了 HTTP/2，curl 預設走 h2，但 WebSocket 的升級握手要用 HTTP/1.1。測試要加 --http1.1，瀏覽器本身沒有這問題。
3. Workerman 5 的 onWebSocketConnect 不再填 $_SERVER 與 $_GET。 回呼的第二個參數變成 Request 物件。我照 4.x 寫法讀 Origin 和 token，結果全是空值，連線在握手前就被關掉，Nginx 因此回 502。最後靠版本號（5.2.2）加症狀推斷出原因。
4. 權限問題：用 root 執行 composer，之後服務以 www 身分執行，pid 與日誌檔寫不進去就直接退出。
5. 寶塔的 open_basedir：把私有程式放在站點目錄內，再用 Nginx 擋掉外部存取，是比較省事的折衷。

另外，我也寫了診斷腳本和常駐管理腳本，把「環境檢查、握手測試、日誌」包起來。對一個人維運來說，腳本化的 SOP 比記憶可靠。

六、MVP 完成之後，需求開始長大

聊天窗跑起來之後，需求自然冒出來：

• 想知道現在有多少人在線、停留多久。
• 想看歷史對話。
• AI 處理不了時要能轉人工，人工處理完再交還 AI。
• 想把整段對話轉給 Telegram、LINE，或丟進工單系統。

這時我才認真檢視：這些功能做在哪裡最合理？

我的結論是：控制中心放在自己的中轉層，AstrBot 只當 AI 引擎與通知出口。 原因是會話狀態、在線人數、人工接手，本質上是「連線與路由」問題，而這些都發生在訪客連線所在的那一層。把它們塞進 AstrBot 插件，狀態會分散在兩個系統；而 AstrBot 對 LINE 這類平台也不一定支援主動推送，客服要在 LINE 回覆訪客這條路在 AstrBot 層面走不通，所以我把 LINE 定位成「通知轉發的目的地」，不是客服的回覆管道。客服的回覆管道以網頁後台為主，Telegram 為輔。

七、雙版本並行：PHP 還是 Python

功能長大後，我開始認真考慮用 Python 重寫。理由與顧慮都很具體，所以我把比較整理在這裡：

我想特別說明一點：Workerman 本身並不弱，真正的瓶頸是我自己用同步 curl 等待 AstrBot，這是可以在 PHP 裡改成非同步客戶端解決的。所以「為了效能換語言」並不是充分理由。

真正讓我傾向 Python 的，是長期維護：後台、狀態機、轉發連接器、跨程序傳訊，這類「狀態密集」的系統，用 asyncio 寫會比較自然，而且和 AstrBot 同語言，未來整合的空間也比較大。

但我也很清楚，現有 PHP 版已經穩定運作。因此我決定：

1. PHP 版補完新功能後凍結，不再大改，當作穩定後備。
2. Python 版從頭依同一份契約重寫，跑在新 port，Nginx 用 /chat2/ 分流。
3. 兩版共用同一個 MySQL 與 Redis，將來切換時資料不用遷移。
4. 穩定後再決定是否切換流量，或長期並行。

為什麼先定「契約」

雙版本最怕的是兩邊各長各的。所以在寫任何功能之前，我先定稿了一份共用契約：

• 資料表結構（訪客、會話、訊息、附件、連線紀錄、轉發、稽核）。
• Redis 的鍵名、頻道、事件格式（兩種語言各有一份常數檔，並用腳本比對一致）。
• 會話狀態機：ai、waiting_agent、human、closed，以資料庫的條件更新加版本號作為唯一裁決，避免兩位客服同時接手。
• 訪客身分格式：cookie 名稱、token 簽章方式兩版完全相同，這樣同一位訪客走哪個版本都是同一個人。
• 演進規則：並行期間只新增欄位和表，不改名、不刪除。

這份契約的原則是：訊息內容先寫資料庫，事件只負責通知。Redis Pub/Sub 不保證送達，所以客服後台重連時，要用 REST 以「最後訊息 ID」補抓，才不會漏訊息。

八、還沒驗證、也不想誇大的地方

寫到這裡我必須誠實說明：

• 契約與腳本我在沙盒裡做了語法與一致性檢查，但很多 PHP 與 SQL 沒有在真實環境完整跑過。
• AstrBot 的 SSE 事件格式文件沒有詳細描述，我的解析是依實測日誌調整的；附件的欄位格式也要對照 API 文件實測。
• 「Python 效能更好」目前只是推論，我沒有做過壓力測試。
• 圖片是否被 AI 看懂，取決於 AstrBot 選用的模型是否支援視覺。
• 個人資料（Email、IP、對話內容）需要保存期限、揭露與刪除機制，這部分我還在規劃。

九、幾點心得

1. 先用最小方案驗證需求，再決定要不要長大。 如果一開始就選完整客服系統，我現在可能還在研究它的後台。
2. 複用手上的技術棧，比追求「最適合」的技術棧更重要。 對一人維運來說，少一個執行環境，就少一份夜間被叫醒的風險。
3. 遇到問題時，先確認版本、日誌與實際回應，再下結論。 這次最花時間的兩個問題（Nginx 規則、Workerman 5 回呼差異），都是靠「看實際輸出」而不是「憑印象」解決的。
4. 雙版本並行的關鍵不是程式碼，而是共用契約。 先把資料與事件的語言對齊，兩邊才不會越走越遠。

接下來我會先把契約審閱定稿，再補完 PHP 版的後台與人工接手，然後凍結，並在新 port 上用 Python 重新實作。如果有進展，我再來更新這篇文章。