LINE Messaging API 整合技術 SOP

結論

在 LINE Bot 開發中，LINE_CHANNEL_SECRET 用於「驗證別人（LINE）是不是真的」，而 LINE_CHANNEL_ACCESS_TOKEN 用於「證明我是誰（取得發送權限）」。兩者皆為極機密資訊，應透過環境變數管理，嚴禁寫死在程式碼或上傳至公共倉庫。

1. 憑證取得路徑

請登入 LINE Developers Console 並進入你的 Messaging API Channel：

Channel Secret: 位於 Basic settings 分頁。
Channel Access Token (Long-lived): 位於 Messaging API 分頁的最下方，點擊 Issue 產生。
註：若看到的是 "Assertion Signing Key"，那是 v2.1 的進階動態驗證方式，初學者建議先用 Long-lived 版本。

2. 環境變數配置 (Linux / HomeLab 環境)

在你慣用的開發目錄下，使用 vi 建立環境變數檔，這能有效分離憑證與程式碼。

vi .env

在檔案中貼入以下內容：

# 取得自 Basic settings 分頁  
LINE_CHANNEL_SECRET=你的_CHANNEL_SECRET_字串

# 取得自 Messaging API 分頁最下方  
LINE_CHANNEL_ACCESS_TOKEN=你的_LONG_LIVED_TOKEN_字串

# 你的機器人 Channel ID (10位數字)  
LINE_CHANNEL_ID=你的_CHANNEL_ID

3. 元件角色與原理圖解 (社區大樓與外送比喻)

元件名稱	角色比喻	運作方向	功能描述
Channel ID	社區門牌	識別用	識別你的 Bot 專案身分。
Channel Secret	管委會印章	LINE -> 你	驗證身分。當 LINE 傳送 Webhook 訊息給你時，你用此 Secret 驗證 Request Body 的簽章，確保訊息真的是 LINE 寄來的。
Webhook URL	外送地址	LINE -> 你	接收訊息。使用者傳訊息給 Bot，LINE 就會送到這個 HTTPS 地址。
Access Token	通行感應卡	你 -> LINE	獲取授權。當你要回覆訊息（Reply）或推播訊息（Push）時，必須在 Header 帶上此 Token。

4. 關鍵 Gotchas (避坑指南)

Token 複製陷阱：LINE_CHANNEL_ACCESS_TOKEN 長度極長（數百字元），在 vi 貼上或從網頁複製時，請務必檢查是否因自動換行產生了不可見的換行符號。
Webhook 驗證失敗：
必須是 https，且憑證必須受信任（建議用 Let's Encrypt 或 Tailscale Funnel）。
在控制台點擊 "Verify" 時，你的伺服器必須正在運行且回傳 HTTP 200。
IP 白名單 (Whitelist)：若控制台開啟了 IP 白名單，請加入你 HomeLab 出口的公網 IP，否則 API 呼叫會被拒絕。
Webhook Signature (安全性)：強烈建議在程式碼中實作 x-line-signature 的驗證邏輯，避免駭客直接對你的 Webhook 網址發送偽造訊息。

5. 進一步研究方向

無狀態驗證 (Stateless Token v2.1)：研究如何利用 Assertion Signing Key 實作 JWT 簽署。優點是 Token 每 15 分鐘自動失效，安全性遠高於長期有效的 Long-lived Token。
Webhook 異步處理 (Task Queue)：LINE 要求 Webhook 必須在1 秒內回傳成功。研究如何使用 Celery (Python) 或其他隊列機制，先收下訊息再處理耗時的 AI 運算。
Tailscale Funnel 自動化：研究如何利用 tailscale funnel 將本地 Katharine 或 Mint2Bee 的 8080 port 暴露給 LINE，並確保網址變動時自動更新 LINE Channel 設定。

6. 驗證一個反向 / 懷疑角度的想法

「如果我只打算回覆訊息 (Reply)，是否可以完全不保護 Secret？」

這是一個常見的誤區。雖然 Secret 是用來保護你的伺服器不被假訊息攻擊，但由於 replyToken 是隨 Webhook 訊息附帶而來的，若你不驗證 Secret，任何人都可以傳送一個「假 Webhook」給你的伺服器，裡面包著他自己的 replyToken，誘導你的 Bot 把內部的機密資訊（例如 Database 查詢結果）回傳給攻擊者。因此，驗證 Secret 是保護 Access Token 發言權的第一道防線。