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 官方帳號
- 進入 LINE Official Account Manager。
- 使用自己的 LINE Business ID 登入。
- 建立新官方帳號;本專案現行名稱為「小世界族譜」。若是另行複製空白框架,可依實際用途命名。
- 類別選最接近的非商業/個人用途即可,日後仍可調整名稱與圖示。
二、啟用 Messaging API
- 在官方帳號後台進入「設定」。
- 找到 Messaging API,選擇啟用。
- 建立或選擇一個 Provider。Provider 是長期容器,建議取名「小世界」;不要隨意建立多個 Provider,因為同一使用者在不同 Provider 下會有不同 userId。
- 完成後進入 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
正式自動回覆採「一批兩次」而不是逐則回覆:
- 新投稿的第一則訊息立即確認已開始收件;
- 中間的文字與附件安靜收件,不逐則洗版;
- 收到「本次資料傳完」時,依 D1 訊息索引回覆文字、圖片、語音、影片與文件數量;
- 人工接受案件後,仍由管理者在 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 一鍵備份的一次性設定
- 使用 Google Drive 中專供 LINE 原件的私人資料夾,一般存取必須是「受限制」。若資料夾存在
anyone分享權限,Worker 會拒絕備份。目前指定資料夾 ID 是1Sl-pkLUi-WybqSFAqK2rP7REJAsuAtx2;舊測試資料夾保留,但不再接收親族原件。 - 在 Google Cloud Console 建立專案,啟用 Google Drive API。
- 設定 OAuth consent screen,只供資料管理者本人使用;建立「Desktop app」OAuth client,下載憑證 JSON,放到
apps/line-webhook/google-oauth-client.json。該檔已排除 Git,絕對不可提交。 - 在專案目錄執行:
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 實際功能;不在錯誤頁反覆撤銷授權。
- 套用
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- 進入私人案件頁,按「一鍵備份並核對 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
- 在 Messaging API 頁籤填入 Webhook URL。
- 按 Verify;成功時 Worker 會對空事件請求回傳 HTTP 200。
- 回到 LINE Official Account Manager 的「設定 → 回應設定」,開啟「Webhook」;LINE Developers Console 內的狀態應隨之顯示為
Use webhook已開啟。 - 開啟 Webhook redelivery。
- 先由資料持有人傳一則無敏感內容的測試文字,例如「連線測試」。
若為全新環境,可先用 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、
0004Drive 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 保留來源與清理稽核索引。