使用文檔 - 月牙AI客服

環境要求

Node.js

18.0 及以上

MySQL

5.7 及以上

阿里雲帳號

百煉 + 機器翻譯

安裝步驟

1

第一步：安裝依賴

雙擊執行安裝全部依賴.bat，等待所有依賴安裝完成。

安装全部依赖.bat

2

第二步：啟動專案

雙擊執行啟動項目.bat，啟動開發伺服器。

启动项目.bat
# http://127.0.0.1:3000

3

第三步：完成安裝嚮導

瀏覽器訪問 http://127.0.0.1:3000，系統會自動引導你完成資料庫配置和管理員帳號建立。

安裝嚮導會自動執行 SQL 建表、建立管理員、寫入設定檔，全程可視化，無需手動操作資料庫。

資料庫結構

系統共7張資料表，安裝嚮導會自動建立，以下是各表的用途說明：

Table	Description
`users`	管理員和客服帳號，支援 admin / agent 兩種角色
`clients`	站點配置，每個接入網站對應一條記錄，儲存阿里雲 Agent ID 等資訊
`chat_sessions`	訪客會話，記錄訪客IP、設備、來源頁面、當前服務模式等
`chat_messages`	聊天訊息，記錄所有訊息內容及發送者類型（訪客/客服/AI）
`knowledge_base`	知識庫問答對，支援分類、關鍵詞和優先級
`knowledge_files`	上傳到阿里雲知識庫的檔案記錄及同步狀態
`system_config`	系統全域設定，包括阿里雲 API 密鑰、翻譯密鑰等

阿里雲配置

系統需要兩個阿里雲服務：百煉大模型平台（AI回覆）和機器翻譯（訊息翻譯）。登入管理後台進入「系統設定」，填寫以下配置項：

ali_api_key 百煉 API Key

在阿里雲百煉控制台建立，用於呼叫知識問答 Agent。

ali_workspace_id 業務空間 ID

百煉控制台右上角可查看，格式類似 ws-xxxxxxxx。

ali_translate_key_id 翻譯 AccessKey ID

在阿里雲 RAM 控制台建立，開通機器翻譯服務後取得。

ali_translate_key 翻譯 AccessKey Secret

與 AccessKey ID 配套，建立時儲存，之後無法再次查看。

關於 Agent ID：每個接入站點需要在阿里雲百煉中單獨建立知識庫和 Agent，建立完成後在管理後台的「站點管理」裡填寫對應的 Agent ID 和知識庫 ID。

網站接入

安裝完成後，把聊天視窗嵌入到你的網站，訪客無需跳轉即可發起對話。

第一步：建立站點

登入管理後台，進入「站點管理」，建立一個新站點並填寫網站域名。系統會產生唯一的客戶識別碼（client code）。

第二步：嵌入程式碼

將以下程式碼片段貼到網站 HTML 的標籤之前，替換 YOUR_LOCALE 為語言代碼（如 zh-TW），YOUR_CLIENT_CODE 為站點識別碼：

<script>
  (function() {
    var btn = document.createElement('a');
    btn.href = 'https://your-domain.com/YOUR_LOCALE/chat?client=YOUR_CLIENT_CODE';
    btn.target = '_blank';
    btn.rel = 'noopener noreferrer';
    btn.title = '联系客服';
    btn.style.cssText = 'position:fixed;bottom:24px;right:24px;width:56px;height:56px;border-radius:50%;background:#2563eb;display:flex;align-items:center;justify-content:center;box-shadow:0 4px 16px rgba(37,99,235,.45);z-index:9999;transition:transform .15s';
    btn.innerHTML = '<svg width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>';
    btn.onmouseover = function(){ btn.style.transform = 'scale(1.1)'; };
    btn.onmouseout  = function(){ btn.style.transform = 'scale(1)'; };
    document.body.appendChild(btn);
  })();
</script>

第三步：配置知識庫

在阿里雲百煉建立知識庫，上傳業務文件，建立問答 Agent。然後回到管理後台「站點管理」填寫 Agent ID，AI 即可自動回覆訪客問題。