SayDou Turnstile 流程
SayDou 後台 · 機器人驗證

Turnstile 驗證流程cf-turnstile

網頁後台改用 Cloudflare Turnstile 取代 Google reCAPTCHA。瀏覽器向 Cloudflare 拿到一次性的驗證 token，連同表單送給 SayDou 後端，後端再拿 token 回頭問 Cloudflare「這是真人嗎」。這頁用實際的程式位置，一步步拆開這個流程。

免費不限驗證次數 背景驗證多數人看不到任何畫面 一次性 token300 秒內有效、只能驗一次 無套件前端只動態載入一支 script
01 · 用在哪裡

三個會用到 Turnstile 的地方

點卡片會切換到下方對應的流程圖。

App 登入（/phone/auth、/pad/auth） OA Plus 店家（登入與查詢超量）
02 · 逐步流程

誰在什麼時候傳了什麼

四條泳道分別是使用者的瀏覽器、瀏覽器裡的 Cloudflare 驗證元件、SayDou 後端，以及 Cloudflare 的驗證 API。點圖上的任一步，或用下方按鈕逐步前進。

驗證結果 


          

            
            
            
          

        

      

    

  


  

    

      03 · 前端
      
Cloudflare 的東西怎麼進到頁面

      
專案沒有安裝任何 Cloudflare 套件。loadTurnstileScript() 在需要時往 <head> 插入一支 script，整個網站只插一次；之後由 turnstile.render() 在指定的空容器裡建立驗證元件。切換下方三種情況，看畫面和 DOM 的變化。

    

    

      
      
      
    

    

      

        
使用者看到的登入頁

        
        

      

      

        
實際的 DOM 與資料

        

        

          
sitekey
公開的網站金鑰，依環境放在 environment.*.ts 的 turnstileSiteKey

          
appearance
interaction-only：只有需要人工確認時才顯示勾選框

          
language
zh-tw

          
callback
拿到 token 時呼叫，token 交給送出表單的程式

          
expired-callback
token 過期（300 秒）時清掉，Cloudflare 會自動再取一個

          
error-callback
失敗時讓送出按鈕顯示「再按一次」，下次送出自動重試

          
?render=explicit
不讓 Cloudflare 自動掃描頁面，由我們決定何時、在哪個容器建立元件

        

      

    

  


  

    

      04 · 後端
      
後端怎麼向 Cloudflare 驗證

      
瀏覽器送來的 token 本身不代表通過，後端一定要拿 Secret Key 去問 Cloudflare。所有驗證都集中在 TurnstileService::verify()，逾時設 10 秒。切換下方情況，看 Cloudflare 的回覆和後端的判斷。

    

    

      
      
      
      
      
    

    

      

        
後端送出的請求

        

      

      

        
Cloudflare 的回覆

        

      

    

    

      
後端的判斷

      
    
      
    
    
    
  
    

  
    
    
    
      05 · 規則
      
    查詢超量規則模擬器
    
      
    計數單位是「同一店家＋同一 IP」，同店家同地點換帳號仍合併計算，連鎖店不同分店各自計算。鎖定也是以「店家＋IP」為單位，一間分店被鎖不會影響其他分店。拉動次數、切換條件，看後端會怎麼回應。數值為目前的預設設定。
    
    
    
    
    
      
    
        
    
          
          
    40 次 / 10 分鐘
    
          
          
          
          正常店家實測：大多數每 10 分鐘 3 次左右，最忙的店家約 60 次。
        
    
        
    
          
    
            
            
          
    
          
          
        
    
      
    
      
    
        
    
        
      
      
      
    
      
  
      

  
      
    
      
      06 · 設定
      
      開關與設定一覽
      
      
      後端設定在 .env，修改後執行 php artisan config:clear（正式機再加 config:cache），不用改程式。Secret Key 只放後端，不寫進任何文件。
      
    
      
    
      
      
      
        
      設定預設作用
      
        
          
      開關
      
          
      TURNSTILE_LOGIN_ENABLEDfalse網頁登入是否驗證。前端新版上線後才開，否則舊頁面無法登入
      
          
      TURNSTILE_ENABLEDfalse查詢超量驗證的總開關
      
          
      TURNSTILE_OBSERVE_ONLYfalse觀察模式：超量只寫 log、不要求驗證
      
          
      連線
      
          
      TURNSTILE_SECRET—Cloudflare 的 Secret Key，只放後端
      
          
      TURNSTILE_ALLOWED_HOSTNAMES（空）Cloudflare 回覆的網域必須在清單內，逗號分隔
      
          
      查詢超量規則
      
          
      TURNSTILE_SOFT_LIMIT100一般店家：同店家＋同 IP，計數區間內超過幾次要驗證
      
          
      TURNSTILE_SOFT_WINDOW_MINUTES10計數區間（分鐘），從第一次查詢起算
      
          
      TURNSTILE_LOCK_MINUTES10一般店家超過門檻後，沒通過驗證要等多久；持續打也不延長
      
          
      TURNSTILE_STRICT_CUSTIDS（空）異常店家名單，逗號分隔
      
          
      TURNSTILE_STRICT_SOFT_LIMIT20異常店家的門檻
      
          
      TURNSTILE_STRICT_LOCK_MINUTES30異常店家超過門檻後，沒通過驗證要等多久
      
          
      TURNSTILE_CLEARANCE_TTL_MINUTES10通過驗證後通行的有效時間
      
          
      TURNSTILE_CLEARANCE_MAX_REQUESTS60通行期間最多再放行幾次，用完要再驗證
      
          
      前端
      
          
      environment.*.ts → turnstileSiteKey測試 key正式、staging 各一個 Site Key（公開值）；本機開發用 Cloudflare 官方測試 key