01 版主使用教學

適用對象：想用「反詐小幫手」保護自己 LINE 群組的版主。全程約 15～20 分鐘，不需要寫程式。 LINE 介面名稱依 LINE Developers 官方文件（2026 年 11 月查證）： Get started with the Messaging API、 Build a bot、 Group chats。 LINE Developers Console 以英文介面為準；LINE Official Account Manager 顯示語言可能是中文，請對照說明操作。

先了解：能做什麼、不能做什麼

群組內「回覆」訊息不算 LINE 的訊息則數；「私訊通知版主」用的是 push 訊息，會計入你官方帳號方案的每月訊息額度，請留意方案上限。

步驟 1：在反詐小幫手申請帳號

1. 打開平台首頁，按 免費申請。
2. 填寫名稱（例如社區名稱）、Email、密碼（至少 8 碼），按 建立帳號。
3. 自動進入 連接 LINE 頁，你會看到專屬的 Webhook URL（格式 https://<平台網址>/webhook/t_xxxxxxxx）和 通知綁定代碼。先把這頁開著。

步驟 2：建立 LINE 官方帳號

每位版主要用自己的 LINE 官方帳號；已經有官方帳號的人可跳到步驟 3。

1. 依 LINE 官方文件 Step 1-1，先註冊 Business ID（可用 LINE 帳號或 Email 註冊）。
2. 註冊完會出現 LINE 官方帳號的申請表單（entry form），填完必填欄位送出，官方帳號就建立了。
3. 到 LINE Official Account Manager 確認帳號已建立。

步驟 3：啟用 Messaging API（建立 channel）

自 2024 年 9 月 4 日起，已不能直接在 LINE Developers Console 建立 Messaging API channel，必須從 LINE Official Account Manager 啟用。

1. 在 LINE Official Account Manager 打開你的官方帳號，進入設定中的 Messaging API 項目，按啟用 Messaging API。
2. 第一次使用時會要求登錄開發者資料（姓名、Email）。
3. 選擇 Provider（提供者）。可以新建一個，例如「我的社區」。 ⚠️ 官方文件提醒：選定後無法更改，也不同 provider 下同一使用者的 userId 會不同，請謹慎選擇。
4. 用同一個帳號登入 LINE Developers Console，點進剛剛的 provider，確認已出現一個 Messaging API channel。

步驟 4：取得 Channel secret 與 Channel access token

1. 在 LINE Developers Console 點進你的 channel。
2. Channel secret：在 Basic settings 分頁，找到 Channel secret，複製。
3. Channel access token：切到 Messaging API 分頁，捲到最下面 Channel access token，按 Issue 發行一組 long-lived（長效）token，複製。
   • 長效 token 不會過期，但重新發行時舊的會失效，需要回到反詐小幫手重新貼上。
4. 回到反詐小幫手的 連接 LINE 頁，把兩個值分別貼上，按 儲存並測試連線。
   • 看到綠色「已儲存並成功連線到官方帳號『○○』」就代表 token 正確。

🔒 這兩組資料等同官方帳號的鑰匙，平台會加密保存。若懷疑外流，請在 LINE Developers Console 重新發行並更新到這裡。

步驟 5：設定 Webhook URL

依官方文件「Set a webhook URL」：

1. LINE Developers Console → 你的 provider → 你的 Messaging API channel。
2. 點 Messaging API 分頁。
3. 在 Webhook URL 下按 Edit，貼上反詐小幫手給你的 Webhook URL，按 Update。
4. 按 Verify，看到 Success 就成功了。
   • 失敗時：確認 Channel secret 有貼對（簽章錯誤會回 401），以及網址完整沒多空白。
5. 開啟 Use webhook。

步驟 6：讓機器人可以進群組、關閉自動回應

1. 同一個 Messaging API 分頁，找到 Allow bot to join group chats，按 Edit 會帶你到 LINE Official Account Manager，改成允許（預設是關閉的）。
2. Auto-reply messages（自動回應訊息）：官方文件建議用 Messaging API 時改成 Disabled，到 LINE Official Account Manager 的回應設定中關閉，避免官方帳號在群組裡亂回話。
3. Greeting messages（加入好友的歡迎訊息）：可保留或關閉，不影響防詐。

步驟 7：綁定自己為通知對象

1. 用你自己的 LINE 加官方帳號好友（在 Messaging API 分頁可以掃 QR code 加好友）。
2. 私訊官方帳號：綁定 ABC123（換成 連接 LINE 頁上顯示的代碼）。
3. 收到「✅ 綁定成功」就完成了。想查自己的 userId，私訊 我的ID。
4. 也可以讓其他管理員一起綁定，或在 設定 → 通知 手動貼 userId。

步驟 8：邀請官方帳號進群組

1. 打開要保護的 LINE 群組 → 右上角選單 → 邀請，選你的官方帳號。
2. 官方帳號加入後會發一則招呼訊息，後台 群組 頁會自動出現這個群組。
3. 不想守護某個群組時，在 群組 頁按「守護中 ✓」切換成「已關閉」。

步驟 9：設定群主保護（強烈建議）

到 設定 → 群主保護與白名單 → 受保護的名字，每行一位：

好鄰居社群 Kevin,U1234567890abcdef...
副版主小美,U9876...

有人把暱稱改成和群主幾乎一樣、但 userId 不同時，系統會判定冒名。userId 可私訊官方帳號 我的ID 取得。

步驟 10：測試

找一位同事在群組貼以下文字（都是假訊息）：

到後台 事件紀錄 可以看到每一筆。

收到通知後怎麼處理

1. 到 LINE 群組 → 成員列表 → 找到該成員 → 刪除（移出群組）。
2. 回後台 事件紀錄，把狀態改成「已移除成員」。
3. 若是誤判：改成「誤判」，並把該成員 userId 加到 白名單，或把常用字詞加到 允許字詞。

常見問題

• Verify 失敗？ 先確認已在步驟 4 儲存正確的 Channel secret；若平台被暫停，Webhook 也會回 200 但不處理。
• 官方帳號沒反應？ 檢查 Use webhook 是否開啟、群組是否「守護中」、本月額度是否用完（儀表板可看）。
• 可以用在 LINE 社群嗎？ 不行，這是 LINE 官方 API 的限制。
• 可以自動踢人嗎？ 不行，官方 API 沒有踢人功能，請手動移除。

02 安裝部署（給技術長）

系統需求

安裝

git clone <repo> /opt/line-guard-saas   # 或直接複製 /workspace/line-guard-saas
cd /opt/line-guard-saas
npm ci --omit=dev
npm run docs          # 產生 public/docs.html（說明頁 /docs）
cp .env.example .env  # 編輯環境變數

環境變數

產生密鑰：node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

HTTPS 反向代理（Nginx 範例）

server {
  listen 443 ssl http2;
  server_name guard.task.com.tw;
  ssl_certificate     /etc/letsencrypt/live/guard.task.com.tw/fullchain.pem;  # 需完整憑證鏈
  ssl_certificate_key /etc/letsencrypt/live/guard.task.com.tw/privkey.pem;
  client_max_body_size 2m;
  location / {
    proxy_pass http://127.0.0.1:3100;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

LINE 官方提醒：若 Verify 出現 SSL 錯誤，多半是中繼憑證沒裝完整，請用 fullchain.pem。 也可用 Caddy：guard.task.com.tw { reverse_proxy 127.0.0.1:3100 }（自動申請憑證）。

程序管理

systemd

# /etc/systemd/system/line-guard.service
[Unit]
Description=LINE Guard SaaS
After=network.target
[Service]
WorkingDirectory=/opt/line-guard-saas
EnvironmentFile=/opt/line-guard-saas/.env
ExecStart=/usr/bin/node src/server.js
Restart=always
User=lineguard
[Install]
WantedBy=multi-user.target

systemctl enable --now line-guard && journalctl -u line-guard -f

或 PM2

pm2 start src/server.js --name line-guard --node-args="--env-file=.env" && pm2 save

健康檢查：GET /healthz → {"ok":true}

備份

SQLite 是單一檔案，用線上備份指令（不需停機）：

# 每日 03:00 備份，保留 30 天（crontab）
0 3 * * * sqlite3 /opt/line-guard-saas/data/guard.db ".backup '/backup/guard-$(date +\%F).db'" && find /backup -name 'guard-*.db' -mtime +30 -delete

• APP_SECRET 要和資料庫分開保存（例如密碼管理器），兩者都要有才能還原。
• 還原：停服務 → 把備份檔複製成 data/guard.db → 啟動。

部署到管理王

• 這是需要常駐的 Node 服務，不能只放在 task.com.tw/preview/ 靜態目錄；建議子網域 guard.task.com.tw 指向這台主機。
• /docs 說明頁（public/docs.html）是單一靜態檔，可另外放到 task.com.tw/preview/line-guard-docs.html。

擴充與注意事項

• 目前為單機 SQLite，適合數百位版主、每秒數十則訊息。量大時可換 PostgreSQL（src/db.js 集中所有 SQL）。
• Webhook 先回 200 再處理；服務重啟瞬間的事件可能遺失。可在 LINE Developers Console 開啟 webhook redelivery：系統會依 webhookEventId 去重（同一租戶同一事件只處理一次，紀錄保留 7 天），不會重複通知。
• 登入保護：同一帳號 15 分鐘內連續失敗 5 次、或同一 IP 失敗 20 次，鎖定 15 分鐘（平台管理員登入同樣適用）；同一 IP 每小時最多申請 5 個帳號。紀錄存在 SQLite，重啟後仍有效。
• 版主在設定頁自訂的 AI 端點必須是 https://，且不能指向內網或本機位址（避免被拿來存取主機內部服務）；平台環境變數 LLM_BASE_URL 不受此限制。
• 執行測試：npm i && npm test（含模擬 LINE 平台的兩租戶 e2e）。

03 設定說明

所有設定都在版主後台，依頁面說明。

連接 LINE（/app/setup）

留空表示不變更。兩者皆以 AES-256-GCM 加密存放。

群組（/app/groups）

官方帳號被邀請進群組（join 事件）時自動新增，被移出（leave 事件）時標成「已離開」。 守護 開關：關閉後該群組的訊息不檢查、不計額度。

設定（/app/settings）

偵測

內建規則與分數（同一類只算一次）：

群主保護與白名單

AI 判斷（選用）

通知

訊息範本

可用變數：{name} 發送者顯示名稱、{userId}、{group} 群組名稱、{reasons} 判定原因、{excerpt} 內容摘要（120 字）、{score} 分數。

事件紀錄（/app/incidents）

每筆記錄時間、群組、發送者與 userId、類型（文字／圖片／冒名／LINE 邀請 QR）、內容、原因、已執行動作、狀態（待處理／已移除成員／誤判）。可匯出 CSV（UTF-8 BOM，Excel 可直接開）。

額度

額度由平台管理員在 /admin 調整。

平台管理（/admin）

平台管理員（SUPERADMIN_EMAIL）可看所有版主、官方帳號連接狀態、群組數、本月用量、事件數，並可 暫停／恢復（暫停後 webhook 回 200 但不處理）與調整每位版主的 訊息／AI 額度。

04 API 串接

一、LINE Webhook（LINE → 本系統）

POST /webhook/{tenantId}
Header: x-line-signature: base64(HMAC-SHA256(channelSecret, 原始 request body))

• 每位版主一個網址；以該版主的 Channel secret 驗證簽章，不符回 401；未知租戶回 404；暫停的租戶回 200 但不處理。
• 立即回 200 {"ok":true}，再非同步處理事件。
• 處理的事件類型（LINE 官方格式，參考 Messaging API reference – Webhook events）：

範例 payload：

{
  "destination": "Uxxxxxxxx",
  "events": [{
    "type": "message", "mode": "active", "timestamp": 1730700000000,
    "webhookEventId": "01H...", "deliveryContext": { "isRedelivery": false },
    "replyToken": "b60d4...",
    "source": { "type": "group", "groupId": "Ca56f9...", "userId": "U4af49..." },
    "message": { "id": "468789577898262530", "type": "text", "text": "老師帶單保證獲利" }
  }]
}

本系統呼叫的 LINE API：reply、push、GET /v2/bot/info、群組摘要、群組成員資料、訊息內容。不使用任何非官方 API，也不呼叫踢人（官方沒有此 API）。

二、版主 REST API（管理王 ↔ 本系統，單一版主）

• Base：{PUBLIC_BASE_URL}/api/v1
• 認證：Authorization: Bearer lgk_...（版主後台「API 串接」頁取得，可重新產生）
• 格式：JSON；錯誤 {"error": "..."}，401 = 金鑰錯誤

curl -H "Authorization: Bearer lgk_xxx" https://guard.task.com.tw/api/v1/incidents?status=open
curl -X PATCH -H "Authorization: Bearer lgk_xxx" -H "content-type: application/json" \
     -d '{"sensitivity":"high","blocklist":["代購"]}' https://guard.task.com.tw/api/v1/settings

事件物件：

{ "id": 12, "tenant_id": "t_ab12...", "group_id": "Ca56...", "group_name": "好鄰居社區",
  "user_id": "U4af...", "display_name": "投資小美", "kind": "text",
  "text": "老師帶單保證獲利…", "score": 7, "reasons": ["LINE 邀請／加好友","投資帶單"],
  "verdict": "scam", "actions": ["group_warning","admin_push"], "status": "open",
  "created_at": "2026-11-04 06:30:00" }

created_at 為 UTC。kind：text、image、impersonation、qr_invite。actions：group_warning、admin_push、admin_email，失敗時帶 _failed。

三、平台 API（管理王後台 ↔ 本系統，所有版主）

• 認證：Authorization: Bearer {PLATFORM_API_TOKEN}（環境變數；未設定則全部 401）

四、與管理王整合建議

1. 管理王會員申請「反詐小幫手」→ 後台呼叫 POST /api/platform/tenants 建帳號，把 apiKey 存在該會員資料。
2. 管理王頁面用 GET /api/v1/stats、/incidents 顯示該會員的儀表板；或直接連結到本系統後台。
3. 付費方案變更 → PATCH /api/platform/tenants/{id} 調整額度；欠費 → status: suspended。
4. 想統一用管理王登入時可設 ALLOW_SIGNUP=0 關閉自助申請（目前沒有 SSO，見已知限制）。