LINE 官方帳號與 Webhook 設定

現行上線狀態

LINE 官方帳號、Messaging API、Cloudflare Worker、D1、R2 與私人審核頁均已上線;Worker 現行模式是 pending-review。verify-only 是初次建置或災難重建時使用的驗證模式,不是現在的運作狀態。現行系統會:

  • 驗證請求確實來自 LINE;
  • 接受 Developers Console 的 Verify 測試;
  • 同一位傳送者在人工處理前的資料合併為一筆待確認投稿;
  • 文字保存於私人 D1,照片、語音、影片與檔案保存於私人 R2;
  • LINE 官方帳號 App 使用原生新訊息通知提醒資料管理者;
  • 資料管理者於私人審核頁按「接受」或「忽略」;
  • 接受後才建立案件編號,忽略或七日未處理會刪除訊息內容與附件;
  • 不自動修改任何正式人物、關係或事件母資料。

截至 2026-08-20,四格圖文選單、分批收件、重複開始/完成防重、Reply API 失敗時的 Push API 補送均已完成。第一件含圖片的正式案件為 CASE-LINE-20260816-000007,共 9 則訊息、2 張 JPEG,R2 合計 1,538,567 bytes。Google OAuth secrets、0004 migration 與新版 Worker 均已上線;該案已一鍵備份為 2 張原始 JPEG 與 1 份案件 JSON,完成私人權限、位元組數、重新讀回開啟及重複執行防重驗證。

此家族用途採低流量人工放行,不先建立邀請碼或會員審查。未來若實際出現濫用,再依紀錄增加限制,不預先擴大複雜度。

為什麼不能只用 GitHub Pages

GitHub Pages 只能提供靜態 HTML、JavaScript 與檔案,不能接收 LINE 主動送來的 HTTPS POST,也不能安全保存 Channel secret。因此網站仍留在 GitHub Pages,LINE Webhook 則使用一個小型 Cloudflare Worker:

flowchart LR
    A[親友的 LINE] --> B[LINE Platform]
    B -->|HTTPS POST + 簽章| C[Cloudflare Worker]
    C -->|verify-only| D[只驗證,不保存]
    C -->|pending-review| E[D1 待確認文字與 R2 私人附件]
    E --> H[資料管理者私人審核頁]
    H -->|接受| I[建立原始案件]
    H -->|忽略或逾期| J[刪除內容]
    E -. 審核通過後 .-> F[家族正式 Markdown 母資料]
    F --> G[GitHub Pages 小世界]

初次建立或重建環境的步驟

一、建立 LINE 官方帳號

  1. 進入 LINE Official Account Manager。
  2. 使用自己的 LINE Business ID 登入。
  3. 建立新官方帳號;本專案現行名稱為「小世界族譜」。若是另行複製空白框架,可依實際用途命名。
  4. 類別選最接近的非商業/個人用途即可,日後仍可調整名稱與圖示。

二、啟用 Messaging API

  1. 在官方帳號後台進入「設定」。
  2. 找到 Messaging API,選擇啟用。
  3. 建立或選擇一個 Provider。Provider 是長期容器,建議取名「小世界」;不要隨意建立多個 Provider,因為同一使用者在不同 Provider 下會有不同 userId。
  4. 完成後進入 LINE Developers Console,確認該 Provider 下已出現 Messaging API Channel。

三、現行回應設定

在 LINE Official Account Manager 的「回應設定」中:

  • 開啟加入好友的歡迎訊息,使用本頁下方的正式說明文字;
  • 關閉預設的泛用自動回應,避免出現「無法個別回覆」而讓投稿者以為沒有人處理;
  • 保留手動聊天;
  • 啟用 Webhook。

Webhook 負責收件與保存;歡迎訊息負責讓新加入者立即知道用途。兩者不可互相取代。

官方帳號對外形象與使用文字

目前帳號名稱保留「小世界族譜」,Basic ID 為 @472ckzvx。對外素材已放在網站專案:

  • 方形頭像:content/assets/small-world-line-profile.png
  • 小尺寸預覽:content/assets/small-world-line-profile-256.png
  • 個人檔案封面:content/assets/small-world-line-cover.jpg
  • 官方加入好友 QR Code:content/assets/line-official-qr.png

頭像與封面為 AI 輔助生成的抽象家族網絡圖,不代表特定族人或史料。QR Code 使用 LINE 官方產生版本,保留其中的 LINE 品牌標誌與掃描容錯,不另行覆蓋自製 Logo。

建議狀態訊息:

說說家族故事,讓記憶留下來

建議個人檔案介紹:

用 LINE 就能補充家族資料。請先告訴我們您的姓名與關係,再傳文字、照片、語音、影片、文件或網址;資料會整理後回傳確認,不會直接改寫網站。

現行建議加入好友歡迎訊息:

{Nickname} 您好!歡迎來到「小世界族譜」👋🌿

我是 {AccountName} 的維護者謝昇憲。這是一項由家族共同參與、持續補充的非營利家族記憶整理計畫,目前網站與官方 LINE 由我個人維護。

您不需要整理格式,像平常聊天一樣,就能傳送文字、照片、語音、影片、文件或網址。資料會先由管理者與 AI 整理,再回傳給您確認;確認完成後才會加入網站。

第一次提供資料時,若方便請先告訴我們:

① 您的姓名;若想匿名,也可以不提供 ② 您與資料中人物的關係 ③ 想補充或更正的內容

姓名與關係主要用來註記資料來源,讓日後知道內容有所依據並能交叉核對。資料可以分成多則慢慢傳;全部傳完後,請輸入「本次資料傳完」✅

🚫 本帳號不涉及募款、投資、交易或任何付費服務。

LINE Official Account Manager 的帳號設定必須由帳號擁有者在後台上傳頭像、封面並貼入上述文字;Messaging API 不提供代替擁有者修改這些外觀欄位的介面。

公開身分核對頁

網站保留一個不需家族共用密碼即可開啟的公開頁:

https://enl1217.github.io/hsieh-familytree/line-official

此頁只公開 LINE 官方帳號名稱、Basic ID、管理者、頭像、QR Code、用途、資料處理方式與安全聲明;不得放人物資料、家族共用密碼、LINE userId、私人審核網址或管理金鑰。LINE 商業簡介及親友轉傳說明可連回此頁,頁面也連回 LINE 加好友網址,形成雙向身分核對。

圖文選單與自動收件回覆規劃

第一版圖文選單使用 LINE Official Account Manager 建立四格選單:

選單動作目的
開始提供資料傳送文字「我要提供資料」由 Worker 顯示簡短投稿指引
本次資料傳完傳送文字「本次資料傳完」由 Worker統計本批訊息並回覆已收齊
開啟小世界網站連結小世界首頁進入需共用密碼的家族網站
查看使用說明連結公開身分核對頁說明帳號身分、用途、流程與安全事項

圖文選單本身由 LINE 後台管理;事件判斷、同批收件與動態統計由 Cloudflare Worker 執行。不要同時用後台的固定自動回應處理相同關鍵字,以免同一操作收到重複訊息。

四格選單圖片母檔與上傳檔:

  • 可編輯母檔:content/assets/line-rich-menu-2500x1686.svg
  • 高畫質 PNG:content/assets/line-rich-menu-2500x1686.png
  • LINE 上傳用 JPG:content/assets/line-rich-menu-2500x1686.jpg

正式自動回覆採「一批兩次」而不是逐則回覆:

  1. 新投稿的第一則訊息立即確認已開始收件;
  2. 中間的文字與附件安靜收件,不逐則洗版;
  3. 收到「本次資料傳完」時,依 D1 訊息索引回覆文字、圖片、語音、影片與文件數量;
  4. 人工接受案件後,仍由管理者在 LINE 告知已建立案件及後續整理時間。

按鈕與分批規則:

  • 同一批重複按「我要提供資料/開始提供資料/開始收件」,只建立一次開始狀態;後續按壓會簡短提醒正在收件,指令文字不寫入案件內容。
  • 同一批重複按「本次資料傳完」,只結束及統計一次;後續按壓會簡短提醒已收到完成通知,指令文字不列入統計。
  • 傳完後再按開始,或直接傳送新內容,會在同一筆尚未接受的投稿中開啟新一批;第二批只統計第二批內容。
  • 尚未傳送任何資料就按完成,會提示先提供資料;重複按不會洗版。
  • 若 LINE Reply API 暫時失敗,Worker 會自動改用 Push API 補送;只有 Reply 與 Push 都失敗時才撤銷狀態旗標,讓使用者下一次按鈕操作可以重試。案件內容與 webhook 去重紀錄仍會保留。
  • 已接受或已鎖定的正式案件不會因圖文選單指令自行變更工作階段;後續通知仍由管理者人工傳送。

自動回覆已於 2026-08-14 完成程式、23 項本機測試、D1 migration、Worker 部署與真人 LINE 圖文選單測試。重複開始、重複完成、空資料完成及完成後新開一批均已驗證,按鈕指令不會寫入案件內容。

四、需要的秘密值

在 LINE Developers Console:

  • Basic settings 頁籤可以查看 Channel secret;
  • Messaging API 頁籤可以發行 Channel access token。請複製真正的 Channel access token;Channel ID、Basic ID 與 Channel secret 都不能代替 token。

初次建立的 verify-only 模式只需要 Channel secret;現行 pending-review 另需 Channel access token 與系統產生的 ADMIN_REVIEW_KEY。請不要把秘密值貼入聊天、Markdown、GitHub Issue 或任何 Git 檔案;只在自己的終端機互動輸入,由 Cloudflare 加密保存。

Cloudflare 儲存資源

  • D1:small-world-line-intake,保存待確認投稿、訊息索引、狀態與案件編號。
  • R2:small-world-line-media,私人保存待確認及已接受案件的原始媒體,不開放公開網址。
  • Cron:每日執行一次,清除七日未處理的待確認內容。

Google Drive 不取代即時暫存:LINE 附件先串流寫入私人 R2,人工接受案件後,管理者才在案件頁按一次按鈕,把案件 JSON 與每個原始附件串流到私人 Drive 案件資料夾。每個 Drive file ID、網址、備份時間與大小核對結果寫回 D1;重複按會跳過已核對檔案,接續中斷部分,不會盲目重建整批檔案。

Google Drive 一鍵備份的一次性設定

  1. 使用 Google Drive 中專供 LINE 原件的私人資料夾,一般存取必須是「受限制」。若資料夾存在 anyone 分享權限,Worker 會拒絕備份。目前指定資料夾 ID 是 1Sl-pkLUi-WybqSFAqK2rP7REJAsuAtx2;舊測試資料夾保留,但不再接收親族原件。
  2. 在 Google Cloud Console 建立專案,啟用 Google Drive API。
  3. 設定 OAuth consent screen,只供資料管理者本人使用;建立「Desktop app」OAuth client,下載憑證 JSON,放到 apps/line-webhook/google-oauth-client.json。該檔已排除 Git,絕對不可提交。
  4. 在專案目錄執行:
npm.cmd run line:webhook:google-authorize

系統瀏覽器會開啟 Google 正式授權頁。授權完成後,本機程式直接把 OAuth client ID、client secret、refresh token 寫入 Cloudflare encrypted secrets,不會把 token 印在終端機或寫進 Git。

若 Google Auth Platform 的 Publishing status 仍是 Testing,測試使用者的授權會在同意後七天失效。首次線上驗證完成後,資料管理者應到 Google Auth Platform 的 Audience 將個人用途專案切為 In production,再重跑一次上述授權指令。個人用途、少於 100 位使用者可在未完成完整驗證時繼續使用,但授權頁仍會顯示「未驗證的應用程式」警告;只可在確認是自己建立的 OAuth 專案時繼續。

切換 In production 後先執行 npm.cmd run line:webhook:google-verify -- <案件流水號> 驗證現有 refresh token。若實際 Drive 備份成功,不必為了「再授權一次」撤銷或覆寫正在運作的 secret。只有 Worker 回報 invalid_grant 時才重跑 line:webhook:google-authorize。若 Google 授權頁暫時顯示 500,先保留舊 secret、檢查 Worker 與 Drive 實際功能;不在錯誤頁反覆撤銷授權。

  1. 套用 0004_google_drive_backup.sql、測試並部署:
npm.cmd run line:webhook:migrate
npm.cmd run line:webhook:test
npm.cmd run line:webhook:deploy
npm.cmd run line:webhook:google-verify -- 7
  1. 進入私人案件頁,按「一鍵備份並核對 Google Drive」。成功後會顯示 Drive 案件資料夾,內容至少包括 CASE-LINE-*.json 及每個原始附件。最後從 Drive 下載一張圖片,比對位元組數並實際開啟,完成回復測試。

Google OAuth 授權範圍目前是 Drive,原因是要把檔案寫入資料管理者既有的指定資料夾;Worker 程式只使用指定 folder ID。若日後要把授權縮到 drive.file,需改為由程式建立專用資料夾或加入 Google Picker,此項列為後續安全強化,不阻擋本次家族內部低流量流程。

Drive 與網站連結的界線

  • Google Drive 是長期原件庫及 AI 工作來源;案件 JSON 保存 drive_file_id 與私人檢視網址,讓 Codex 在取得 Drive 授權後能直接搜尋、讀取與整理。
  • 第一版網站媒體依資料持有人決定直接引用 Google Drive,不另建網站專用 R2/CDN,也不強制壓縮轉檔。
  • Drive 案件資料夾、案件 JSON 及未選用原件保持「受限制」;只有經提供者與資料管理者確認要在網站顯示的單一媒體檔,才開放為「知道連結的任何人/檢視者」。不公開整個案件資料夾。
  • 正式 Markdown 使用 media_links 保存媒體 ID、Drive file ID、view_url、preview_url、來源案件、提供者、同意狀態與最後檢查日期。網站預設開啟 Drive 預覽頁;嵌入失效時仍保留原預覽連結。
  • R2 原件只在 Drive 已核對、網站已發布且案件已結案後,經人工輸入「清理 R2」才刪除;Drive 原件不隨網站刪除。完整操作見 Google Drive媒體發布標準程序。

Worker 部署步驟

程式位於 apps/line-webhook/,本機自動測試指令是:

npm.cmd run line:webhook:test

第一次部署或重建環境時,在專案目錄執行:

npx.cmd wrangler login
npm.cmd run line:webhook:secret
npm.cmd run line:webhook:token
npm.cmd run line:webhook:admin-key
npm.cmd run line:webhook:google-authorize
npm.cmd run line:webhook:migrate
npm.cmd run line:webhook:deploy

第一個指令開啟 Cloudflare 登入授權頁。三個 secret 指令分別要求 Channel secret、Channel access token 與隨機審核金鑰;migration 建立資料表;部署完成後會顯示 workers.dev HTTPS 網址。

部署完成後檢查:

https://small-world-line-webhook.line-webhook.workers.dev/healthz

應回傳 ok: true。LINE 的 Webhook URL 則填:

https://small-world-line-webhook.line-webhook.workers.dev/webhook/line

私人審核頁是:

https://<worker-subdomain>/review

在專案資料夾執行 npm run line:review,會開啟私人登入頁,並把本機 .dev.vars 的管理金鑰複製到剪貼簿供貼上。登入 Cookie 有效八小時且只保存金鑰衍生碼,不保存原金鑰。此網址只供資料管理者使用,不得貼到公開網站或群組;金鑰若外洩,重新設定 ADMIN_REVIEW_KEY 即可使舊登入失效。

LINE 連線狀態與重新驗證頁是:

https://<worker-subdomain>/review/setup

此頁可辨識目前連接的官方帳號、顯示 LINE 端登記的 Webhook URL 與 Use webhook 狀態,也可要求 LINE 伺服器重新驗證 Webhook。它與審核頁使用相同的私人管理金鑰,同樣不得公開。

回到 LINE Developers Console

  1. 在 Messaging API 頁籤填入 Webhook URL。
  2. 按 Verify;成功時 Worker 會對空事件請求回傳 HTTP 200。
  3. 回到 LINE Official Account Manager 的「設定 → 回應設定」,開啟「Webhook」;LINE Developers Console 內的狀態應隨之顯示為 Use webhook 已開啟。
  4. 開啟 Webhook redelivery。
  5. 先由資料持有人傳一則無敏感內容的測試文字,例如「連線測試」。

若為全新環境,可先用 verify-only 驗證連線;此模式不保存測試文字。切換至現行 pending-review 後,測試訊息會出現在私人審核頁。重建時先用自己傳送的無敏感文字測試「接受」與「忽略」,再測照片、語音與影片;既有正式環境不需為日常案件重跑整套黑箱驗證。

私人審核頁分成「待確認/已接受/已忽略」。按「接受」會建立 CASE-LINE-*,並提供不含 LINE userId 的 JSON 下載,供後續 AI 整理;按「忽略」或投稿逾期時,文字與附件會清除,LINE userId 也會匿名化,只留下顯示名稱、處理時間與狀態供稽核。

安全與維護規則

  • 每次都用原始 request body 驗證 x-line-signature,驗證前不可先解析或改寫 JSON。
  • LINE 不公布固定來源 IP,因此不能用 IP 白名單代替簽章驗證。
  • 重送可能造成同一事件多次送達;Phase 4C 起必須以 webhookEventId 去重。
  • 文字訊息日後無法再由 API 取得;照片、語音、影片與文件也可能由 LINE 刪除。正式收件開放前必須先完成即時保存。
  • Channel secret、access token 與 LINE userId 不得進入 GitHub Pages 或可編譯資料。
  • 如懷疑 Channel secret 外洩,應在 LINE Developers Console 重新發行,並立即更新 Worker secret。

完成標準

  • LINE 官方帳號已建立。
  • Cloudflare 帳號已建立並完成 Wrangler OAuth 授權。
  • Messaging API 已啟用,Provider 選擇正確。
  • D1 small-world-line-intake 已建立並套用第一版 migration。
  • R2 small-world-line-media 已在 Cloudflare 後台啟用並建立;Standard、APAC、私人存取。
  • Worker 已部署到 small-world-line-webhook.line-webhook.workers.dev,Cloudflare DNS 與部署版本已確認。
  • Channel secret、有效 Channel access token 與管理審核金鑰已用 Cloudflare secret 保存;秘密值未寫入 Git。
  • Webhook URL 已登記,LINE 伺服器 Verify 成功;官方帳號識別為「小世界族譜」@472ckzvx。
  • Use webhook 已開啟,LINE API 回報狀態為 active。
  • (選用、非 v1.0 阻塞項)Webhook redelivery 的後台開關尚未留下核對紀錄;Worker 已依 webhookEventId 去重並通過 redelivery 測試。若日後開啟,先在本清單補記核對日期,不需修改案件 Schema。
  • 資料持有人傳送第一筆文字測試,Worker 無簽章錯誤;成功建立 1 筆待審核投稿與 1 則訊息,且可取得提供者顯示名稱。
  • 第二筆本人文字測試已成功接受,建立格式正確的 CASE-LINE-*,並通過案件 JSON 結構及敏感欄位排除檢查。
  • 本人傳送圖片、語音、短影片及一般檔案的真實測試已成功;四個附件完整存入私人 R2,類型與位元組數均和 D1 索引一致,無管理金鑰無法讀取。
  • Verify 完成後遠端 D1 仍為 0 投稿、0 訊息、0 事件,沒有留下測試內容或 userId。
  • 首件真實文字案件已完成收件、整理、提供者確認、核准、正式資料寫入、網站發布與結案。
  • Google Drive 指定資料夾已完成基本寫入與讀回 metadata 測試;證實不是容量或擁有者權限問題。
  • Worker 一鍵備份、可續傳串流、重複操作防重、公開分享拒絕及 D1 逐檔索引已完成程式與本機測試。
  • Google Drive 已改用專屬私人資料夾,只有資料管理者擁有權限且不存在 anyone 分享。
  • Google OAuth secrets、0004 Drive migration 與 0005 逐檔媒體發布 migration 均已完成線上設定/部署;29 項 Worker 測試通過,Phase 4 v1.0 正式 Worker 版本為 ef71988d-dbf9-4fbb-a578-86329aa99947。
  • CASE-LINE-20260816-000007 的 2 張圖片及案件 JSON 已一鍵備份;至少一張圖片已由 Drive 重新讀回、核對 1,167,014 bytes 並實際開啟。第二次執行仍維持相同 3 個檔案與 file ID,防重驗證通過。
  • Google Auth Platform 的 Audience 已從 Testing 改為 In production;線上案件 7 已在切換後實際通過 Drive 備份與核對,現行 refresh token 仍有效。重新授權頁的 Google 500 未影響 Worker,不撤銷既有 secret。
  • 案件 7 已完成兩張圖片的逐檔同意、Drive 單檔發布、正式人物頁引用、GitHub Pages 核對、案件結案及 R2 暫存清理;D1 保留來源與清理稽核索引。