Opencode Supabase

即時資料庫（Supabase）

官方文件查證日期：2026-07-27 依據：https://supabase.com/docs/guides/getting-started/mcp、https://supabase.com/docs/guides/database/postgres/row-level-security、https://supabase.com/changelog/45329-breaking-change-tables-not-exposed-to-data-and-graphql-api-automatically、https://supabase.com/docs/guides/getting-started/migrating-to-new-api-keys、https://supabase.com/docs/guides/platform/free-project-pausing

🔴 給 AI agent：這份文件該怎麼用

這份的價值不在「步驟」，在「你查不到的那些事」。

三條執行原則

1. 先查現況再動手。 動任何設定之前，先跑指令看這台目前是什麼狀態，並回報給使用者。
2. 失敗時先報錯誤原文，然後停下來。 不要自己換方法重試——尤其不要換憑證。 今天現場的混亂就是這樣來的：一個 project_ref 打錯，agent 一路換金鑰亂試了一個下午。
3. 文件跟現況對不上時，以現況為準，並告訴使用者哪裡對不上。 不要硬套這份文件的字面步驟。

⚠️ 先看這裡：這一包和 05-sheets-gas 差在哪

兩包都在「讓作品記得住事情」，但適用場景完全不同，選錯會很痛：

判斷句一句話：「同一秒鐘會不會有兩個人以上在寫？」 會 → 本包。不會 → 回 05-sheets-gas，不要為了用資料庫而用資料庫。

🚨 這一包的四個陷阱（先看完再動手）

這四條是本包最重要的內容。網路上 2026 年 5 月以前的 Supabase 教學，全部會在第 ① 條斷掉。

下面每一步都會再點名它處理的是哪一條。

這個懶人包會幫你做什麼？

1. 建一個 Supabase 免費專案（不用綁信用卡）
2. 拿到可以放在網頁裡的那把金鑰
3. 用一段貼一次就過三關的 SQL，建好一張真的能用的表
4. 讓 GitHub Pages 上的網頁前端寫得進去、讀得回來、即時更新
5. 用 GitHub Actions 每日排程擋掉「閒置 7 天自動暫停」
6. （老師端進階，研習建議最後再看）把 Supabase MCP 接給 OpenCode

原理說明（30 秒）

學生的手機 ──┐
學生的手機 ──┼─→ GitHub Pages 上的網頁 ──→ Supabase（雲端資料庫）
學生的手機 ──┘         （前端）              ↑
                                        RLS 守門員
老師的 OpenCode ─────────────────────────────┘（進階，選用）

要記住的只有一件事：網頁前端拿的那把金鑰，全世界都看得到（按 F12 就看得到）。 所以資料安不安全，100% 取決於資料庫自己的守門員 RLS，跟金鑰藏得好不好完全無關。 這句話是本包所有安全設計的根。

免費方案（不用綁卡）

⚠️ 以下額度為 2026-07-27 查到的數字，服務商隨時會調整，以官方頁面為準。

關於暫停後還救不救得回來：官方頁面存在兩個互相矛盾的說法（一處寫 90 天內可還原，另一處提到最長 1 年）。 本包一律用保守版本教：

🔴 就當作只有 90 天。90 天內一定還原得回來，超過就不要賭。 期末做的東西如果暑假要留著，暑假前就把重要資料匯出一份放 GitHub。

先備條件

• 已完成 00-env-setup 與 01-connect-model（沒接模型，OpenCode 不會動手）
• 已完成 07-github 的第二階段（有 GitHub 帳號、會 push）——網頁要掛在 GitHub Pages，防暫停排程也要用 GitHub
• 有網路
• 一個瀏覽器

驗證：

gh auth status

看得到 Logged in to github.com 就過。看不到 → 回去做 07-github，不要在這裡臨時處理。

步驟一：建帳號與專案（🚨 這裡處理陷阱 ①）

🖐️ 全程在瀏覽器手動做。AI agent 不要代為註冊、不要代填密碼。

1-1 註冊

開 https://supabase.com 自己註冊，建議用 Continue with GitHub（跟 07-github 同一個帳號，之後好管理）。

按鈕文字與版面以你眼前的畫面為準，不要照這份文件找字。

1-2 建立專案

建新專案時，這四個欄位要注意（欄位名稱可能微調，看語意對應）：

1-3 🚨 陷阱 ①：那個勾勾是什麼

2026-05-30 起，Supabase 新專案預設「不再自動把新建的表曝露給 Data API」。

今天建的專案已經在新預設之內。 不勾這個，後面前端一連就會拿到：

permission denied for table wordcloud.
Grant the required privileges to the current role with:
GRANT SELECT ON public.wordcloud TO anon.

而你的網頁程式碼完全沒有寫錯——這是最折磨人的地方。

兩條路，選一條（本包兩條都幫你做，雙保險）：

• A｜建專案時勾起來（步驟 1-2 那個勾勾）
• B｜每次建表的 SQL 後面固定接 grant（步驟三的範本已經內建了）

💡 找不到那個勾勾也沒關係——走 B 就好，步驟三的 SQL 已經包含它。 反過來說：只勾了 A 就以為安全，是不夠的，因為你之後在別的地方建的表可能仍然沒被曝露。所以本包堅持 SQL 裡一定要有 grant。

1-4 驗證

專案建立要等 1～2 分鐘。左側選單看得到 Table Editor、SQL Editor、Authentication 就算好了。

步驟二：拿金鑰（🚨 這裡處理陷阱 ④）

2-1 🚨 陷阱 ④：金鑰換代了

anon 和 service_role 這兩個名字正在被淘汰。現在的名字是：

研習講義請只用這兩句話講，不要講 JWT、不要講 role：

Publishable key ＝可以放在網頁裡的。 Secret key ＝絕對不能放。

⚠️ 舊教材（含網路上大部分 Supabase 教學）會叫你去複製 service_role key。 本包完全不需要 secret key。 只要有人叫你把 secret key 貼進網頁、貼進 GitHub、貼給 AI，那一定是舊做法，停下來。

2-2 去哪裡拿

Dashboard 左下角 Project Settings（齒輪）→ API Keys。

複製兩個東西：

1. Project URL（長得像 https://abcdefghijk.supabase.co）
2. Publishable key（sb_publishable_ 開頭那一串）

如果畫面上還看得到 anon / service_role，通常是收在 Legacy API keys 分頁裡。 不要用那一區的東西，用新的 sb_publishable_...。

2-3 驗證

在 PowerShell 貼這一行（把兩個 <> 換掉）：

curl.exe "<你的Project URL>/rest/v1/" -H "apikey: <你的publishable key>"

• 回傳一段 JSON（就算內容看起來是空的 {} 或一堆 openapi 欄位）→ ✅ 金鑰是對的
• 回 {"message":"Invalid API key"} → key 複製錯了或少了一截，重複製一次

步驟三：建表（🚨 這裡一次處理陷阱 ①②③）

3-1 🚨 陷阱 ②：這是本包最危險的一條

Supabase 官方文件白紙黑字寫的：

• 用 Dashboard 的 Table Editor 建的表 → RLS 預設是開的
• 用 SQL / SQL Editor 建的表 → RLS 預設是關的，要你自己開

🚨 而 AI Agent 幫你建表，一律走 SQL。

也就是說——

你對 OpenCode 說「幫我建一個成績表」，它建出來的那張表，門是開的。

不是它偷懶，是 SQL 建表本來就這樣。而沒有人會提醒你： 前端照樣讀得到寫得進去，畫面一切正常，你不會收到任何警告。 你以為做完了，實際上那張表現在全世界都能讀、能改、能刪。

所以本包的規矩是：

🔴 凡是叫 AI 建表，建完一定要自己確認 RLS 有開、policy 有建。 這件事不能外包給 AI 自己保證——要你自己看步驟 3-4 的驗證畫面。

3-2 現場範本：貼一次，過三關

Dashboard 左側 SQL Editor → New query → 整段貼上 → 右下角 Run。

create table public.wordcloud (
  id bigint generated always as identity primary key,
  seat_no text,                 -- 只存座號，不存姓名
  word text not null,
  created_at timestamptz default now()
);

grant select, insert on public.wordcloud to anon;
grant usage, select on all sequences in schema public to anon;

alter table public.wordcloud enable row level security;

create policy "anyone can insert" on public.wordcloud
  for insert to anon with check (true);

create policy "anyone can read" on public.wordcloud
  for select to anon using (true);

這段 SQL 每一區在做什麼：

⚠️ 這組 policy 是「研習當場、只放假資料」等級的開放設定，不是正式班務可用的設定。 with check (true) / using (true) 的意思是「任何人都可以寫、任何人都可以讀全部」。 拿它來收真實成績、真實名單，等同於公開。正式使用請先看本檔最後的「安全紅線」。

3-3 🚨 陷阱 ③：為什麼一定要有 SELECT policy

很多人以為「我只是要讓學生送資料進來，給個 INSERT policy 就好」。錯。

只給 INSERT 不給 SELECT，老師會踩到兩種狀況，兩種看起來都像壞掉：

狀況 A｜前端程式碼寫成 .insert(...).select()（AI 幫你寫的前端十之八九是這樣，Dashboard 的範例也是這樣） Supabase 寫入後會回頭讀一次剛剛那筆，這一讀就撞到沒有 SELECT policy：

new row violates row-level security policy for table "wordcloud"   (code 42501)

狀況 B｜前端只寫 .insert(...) 不接 .select() 寫入沒報錯，但接下來「把大家的詞撈回來畫文字雲」的那次讀取拿到空陣列，畫面什麼都沒出現。

兩種狀況，老師看到的都是「它壞了」。而老師的直覺動作是——再送一次。 於是同一句話送三遍、五遍，資料表裡全是重複資料。

🔴 請直接背這條規則： 不要用「畫面有沒有出現東西」判斷資料進去了沒有。 要確認就去 Dashboard 的 Table Editor 打開那張表看——那裡看到的才算數。

而只要你照 3-2 的範本貼（INSERT ＋ SELECT 兩個 policy 都有），這整件事根本不會發生。

3-4 驗證（🔴 這一步不要跳過）

驗證 1：RLS 真的開了嗎 Dashboard → Table Editor → 點 wordcloud 表。 表格上方要看到 RLS enabled（綠色）。 看到 RLS disabled / Unrestricted（紅色警告）→ 表示 alter table ... enable row level security 沒跑到，回 SQL Editor 重跑那一行。

驗證 2：policy 真的有兩條嗎 Dashboard → Authentication → Policies → 找到 wordcloud。 要看到兩條：一條 INSERT、一條 SELECT。只有一條 → 回去重跑缺的那一條。

驗證 3：純文字驗證（給 agent 判讀，也可以自己貼） 在 SQL Editor 跑：

select relrowsecurity from pg_class where relname = 'wordcloud';
select policyname, cmd from pg_policies where tablename = 'wordcloud';
select has_table_privilege('anon', 'public.wordcloud', 'select') as can_read,
       has_table_privilege('anon', 'public.wordcloud', 'insert') as can_write;

全部通過的樣子：

• 第一句 → true（RLS 開著）
• 第二句 → 兩列，cmd 分別是 INSERT 和 SELECT
• 第三句 → can_read = true、can_write = true（陷阱 ① 過關）

3-5 要「即時更新」的話，還要多一行

前面做完，前端已經能寫、能讀。但「別人送出的詞，我這邊畫面自己跳出來」是另一件事，要另外開：

alter publication supabase_realtime add table public.wordcloud;

沒跑這行的症狀：自己送自己看得到（因為是自己重新讀的），但別人送你不會動，要手動重新整理。 文字雲、線上對戰、即時排行榜都需要這一行。

驗證：

select tablename from pg_publication_tables where pubname = 'supabase_realtime';

清單裡看得到 wordcloud = 過。

步驟四：網頁前端串接

前端用官方的 @supabase/supabase-js（v2）。可以直接用 CDN 的 ESM 版本 import，不用 npm、不用打包，所以放在 GitHub Pages 上就能跑。

4-1 最小可動範例

<script type="module">
  import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

  // ⬇️ 這兩行本來就會被所有人看到，這是設計，不是漏洞（見最後一節）
  const supabase = createClient(
    'https://<你的專案id>.supabase.co',
    'sb_publishable_<你的publishable key>'
  )

  // ① 送出一個詞
  async function sendWord(seatNo, word) {
    const { error } = await supabase
      .from('wordcloud')
      .insert({ seat_no: seatNo, word })
    if (error) { alert('送出失敗：' + error.message); return false }
    return true
  }

  // ② 讀回全部（畫文字雲用）
  async function loadWords() {
    const { data, error } = await supabase
      .from('wordcloud')
      .select('seat_no, word, created_at')
      .order('created_at', { ascending: false })
    if (error) { console.error(error); return [] }
    return data
  }

  // ③ 即時：別人一送出，我這邊自己更新（需要步驟 3-5 那一行）
  supabase
    .channel('wordcloud-live')
    .on('postgres_changes',
        { event: 'INSERT', schema: 'public', table: 'wordcloud' },
        payload => {
          console.log('有人送了新的詞：', payload.new.word)
          // 這裡放你重畫文字雲的函式
        })
    .subscribe()
</script>

4-2 交給 OpenCode 做整頁的講法

不用自己寫，把下面這段貼給 OpenCode（把 <> 換成你自己的）：

幫我做一個文字雲網頁，掛在 GitHub Pages 上。

資料庫用 Supabase：
- Project URL：<你的 Project URL>
- Publishable key：<你的 sb_publishable_...>
- 資料表：public.wordcloud，欄位 seat_no（座號，文字）、word（詞彙，文字）、created_at

功能：
1. 一個輸入框讓學生輸入「座號」和「一個詞」，按送出寫進資料庫
2. 一個按鈕切換顯示 / 隱藏文字雲
3. 用 Realtime 訂閱，別人送出的詞我這邊要自動出現，不用重新整理
4. 頁面上放這個網址的 QR Code，讓學生掃了就能進來

技術要求：
- 用 @supabase/supabase-js v2，走 CDN 的 ESM import，不要用 npm 打包
- 不要在程式碼裡放任何 secret key
- 不要收集姓名，只收座號

做完幫我 commit 並 push，然後告訴我 GitHub Pages 的網址。

⚠️ 要提醒 agent 的一句話：如果它「順手」幫你在 Supabase 建了新的表， 請它一併把步驟 3-2 那組 grant ＋ enable row level security ＋ 兩條 policy 補上—— 這正是陷阱 ②：AI 建表走 SQL，RLS 預設是關的。

4-3 驗證（每一項都要看到）

第 4 項是這一包真正的分水嶺——做到這裡，才算做出「即時」資料庫。

步驟五：老師端怎麼看資料（不用另外做登入網頁）

Dashboard → Table Editor → 點你的表。

它長得就像 Excel：可以直接排序、篩選、改一格、刪一列、匯出 CSV。 研習現場請直接把這個畫面投影出來，老師會馬上懂「資料庫」是什麼——就是一張永遠在線上、全班可以同時寫的試算表。

匯出：表格右上角 → Export → Download as CSV。

💡 這一步之所以重要：很多人以為做資料庫一定要再做一個「老師管理後台」。 不用。 Dashboard 就是後台，而且是官方維護的。省下來的時間拿去做學生端的體驗。

步驟六：防暫停（GitHub Actions 每日 ping）

免費專案閒置 7 天會自動暫停。暫停之後學生掃 QR Code 會失敗，而且只有你手動去 Dashboard 按還原才會回來。 寒暑假一放就中招，開學前一天發現最崩潰。

6-1 為什麼用 GitHub Actions，不用 agent 排程

6-2 建立 workflow

在你放網頁的那個 repo 裡，建立檔案 .github/workflows/supabase-keep-alive.yml：

name: Supabase Keep Alive

on:
  schedule:
    # UTC 21:00 = 台灣時間隔天早上 05:00，每天一次
    - cron: "0 21 * * *"
  workflow_dispatch:        # 讓你可以手動按一次來測試

jobs:
  ping:
    runs-on: ubuntu-latest
    steps:
      - name: Ping Supabase REST API
        run: |
          curl --fail --silent --show-error \
            "${SUPABASE_URL}/rest/v1/wordcloud?select=id&limit=1" \
            -H "apikey: ${SUPABASE_KEY}" \
            -H "Authorization: Bearer ${SUPABASE_KEY}"
          echo "PING_OK"
        env:
          SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
          SUPABASE_KEY: ${{ secrets.SUPABASE_PUBLISHABLE_KEY }}

6-3 設定兩個 Secret

GitHub 網頁 → 你的 repo → Settings → Secrets and variables → Actions → New repository secret，建兩個：

💡 publishable key 本來就可以公開，直接寫死在 YAML 裡其實也不會出事。 用 Secret 的理由是好維護：以後換 key 只改一個地方，不用去翻檔案。 但 sb_secret_... 無論如何都不要放進來——連 Secret 都不要，這支排程根本用不到它。

6-4 驗證

1. repo → Actions 分頁 → 左側點 Supabase Keep Alive → 右邊 Run workflow → 綠色勾勾
2. 展開執行紀錄，要看到 PING_OK
3. 紅色叉叉的話展開看錯誤：
   • 401 / Invalid API key → Secret 貼錯或少一截
   • permission denied → 🚨 陷阱 ①，回步驟 3-2 補跑那兩行 grant
   • 404 → 表名打錯，或 URL 結尾多了斜線

6-5 ⚠️ GitHub Actions 自己也會睡著

這是很多人設完就忘、半年後才發現的坑：

GitHub 的排程 workflow，在 repo 連續 60 天沒有任何動作之後會被自動停用。 也就是說：你設了防暫停排程，結果排程自己先被停掉，Supabase 接著被暫停。

怎麼辦（擇一）：

• 最簡單：把這個 repo 就用在你平常會改的那個網頁專案上（有 push 就算活動）
• GitHub 停用排程時會寄信給你，收到信就去 Actions 頁面按一下 Enable workflow
• 每學期開學前，順手到 Actions 手動 Run workflow 一次

這條和 Supabase 沒關係，是 GitHub 的規則。但兩個加起來才是完整的解法，所以寫在這裡。

步驟七（進階／選用）：把 Supabase MCP 接給 OpenCode

⚠️ 研習現場建議：先不要裝

🔴 研習主線到步驟六就結束了。純用網頁 ＋ publishable key，閉環已經完整。

MCP 請當作「老師端進階」，放在最後 5 分鐘由講師示範就好。理由： 這條路要走瀏覽器 OAuth 登入，而在學校網路（擋外連、擋跳轉）和多 Google 帳號（瀏覽器登入了三個帳號、彈出來的視窗選錯人）的環境下很容易失敗。 三十個人同時卡在授權視窗，這一節課就沒了。

沒有 MCP 也完全做得出文字雲。 MCP 只是讓老師端多一個「用講的查資料」的入口。

裝了之後可以做的事：對 OpenCode 說「幫我看一下文字雲那張表現在有幾筆、最多人寫的詞是什麼」，它直接讀資料庫回答你，不用開 Dashboard。

🔴 7-0 先跑這一行——這一步會省下你一整個下午

在寫任何設定之前，先確認兩件事：token 有沒有效、project_ref 該填哪一個。

先到 https://supabase.com/dashboard/account/tokens → Generate new token（取名 opencode）→ 複製 sbp_ 開頭那串，設成環境變數：

[Environment]::SetEnvironmentVariable('SUPABASE_ACCESS_TOKEN','你的sbp_token','User')

然後開一個新的 PowerShell 視窗（舊視窗看不到剛設的變數），跑：

curl.exe -s -H "Authorization: Bearer $env:SUPABASE_ACCESS_TOKEN" https://api.supabase.com/v1/projects

會列出你所有專案的 id（＝project_ref）、name、status：

id: jjiuptgdwdpnhnzujzcl   name: myclass             status: ACTIVE_HEALTHY
id: xxbjykdheracbfmwpxwm   name: my-teaching-tools   status: INACTIVE

這一行同時回答四件事：

🔴 給 AI agent：這一步不准跳過。 project_ref 填錯的症狀極度誤導——MCP 會顯示 ✓ connected、20 個工具全部列得出來， 但每一個呼叫都回 You do not have permission to perform this action，連 select 都被拒絕。 這看起來完全像憑證權限不足，於是 agent 會開始換各種金鑰亂試——那是白費力氣，錯的是 ID 不是憑證。 先跑上面那行，用它印出來的 id，就不會走進這個迷宮。

7-1 設定（官方文件明列支援 OpenCode）

用 Personal Access Token（PAT） 認證。官方文件明講：在無法完成瀏覽器 OAuth 流程的環境，改用 PAT——研習現場正是這種環境。

編輯 ~/.config/opencode/opencode.json（Windows：WIN+R 貼 %USERPROFILE%\.config\opencode）。 如果檔案裡已經有 mcp 區塊，把 supabase 這一塊加進去，不要整個蓋掉：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "supabase": {
      "type": "remote",
      "url": "https://mcp.supabase.com/mcp?project_ref=剛才印出來的id",
      "enabled": true,
      "timeout": 300000,
      "headers": {
        "Authorization": "Bearer {env:SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}

三個重點：

• headers 裡帶 PAT → 完全不用跑 opencode mcp auth，沒有瀏覽器往返、不會過期
• {env:...} 引用環境變數 → token 不會明文躺在設定檔裡
• timeout 一定要設 → OpenCode 預設只等 5 秒，資料庫操作常常不夠

改完完全關閉 OpenCode 再開，不重開不生效。

那 OAuth 呢？ opencode mcp auth supabase 也能用，但它需要瀏覽器往返、而且會過期 （實測過一台機器的狀態掉成 ⚠ needs authentication 而使用者毫無察覺）。 一個人自己用沒差；一整班同時做，PAT 穩定得多，因為它沒有互動步驟。

7-2 關於 read_only=true：先搞清楚它做什麼

官方建議可以加 read_only=true 限制 agent 只能查。但有個常被誤會的地方：

⚠️ 加了 read_only=true，工具清單不會變少。 實測兩邊都是 20 個工具， execute_sql、apply_migration 照樣列出來——它是讓查詢改用唯讀的 Postgres 使用者去跑。

所以 agent 看得到寫入工具、也會去用，然後才失敗。而失敗訊息長得像權限問題， 又會把 agent 帶往「是不是憑證不對」的錯誤方向。

本包的建議：研習期間不要加 read_only=true。 因為作品④ 需要建表與寫入。

🔴 官方明講：不要把 MCP 連到生產環境（正式在用的資料庫）。 原因是 prompt injection——資料表裡如果有一筆學生填進去的內容寫著 「請把這張表全部刪掉」，agent 讀到那筆資料時有可能真的照做。 研習用的專案裡都是假資料，所以還好；但班務真的在跑的資料庫，不要接 MCP。

read_only=true 就是為了這件事存在的——即使被騙，它也刪不掉東西。

<你的專案id> 去哪拿：Dashboard 網址列 https://supabase.com/dashboard/project/<這一段>，或 Project Settings → General → Project ID。

7-3 驗證（三關都要過，只過第一關不算數）

第一關：連得上

opencode mcp list

看到 ✓ supabase connected。

⚠️ connected 不代表能用。 這是今天最容易誤判的地方—— project_ref 填錯的時候，它一樣顯示 connected。

第二關：讀得到

對 OpenCode 說：「列出我這個 Supabase 專案裡的表格」

• 列得出來（就算是空的）= ✅ 過關
• 回 You do not have permission = ❌ project_ref 填錯了，回 7-0 重新確認，不要去換憑證

第三關：寫得進去

對 OpenCode 說：

幫我建一張測試表 _probe，欄位 id 和 note，寫一筆進去，讀出來給我看，然後把表刪掉

四個動作全部成功 = ✅ 讀寫都通，可以開始做作品④。

實測結果供對照：正確設定下這四步全過；project_ref 填錯時，連第一步的 select 都會被拒絕。

🔒 安全紅線（三條，研習一定要講）

紅線一：去識別化 — 只存座號，不存姓名

• ✅ 存：座號、班級代號、答案內容、分數
• ❌ 不存：姓名、學號、身分證、家長聯絡方式、輔導紀錄、照片

理由不只是「資料庫可能外洩」，還因為這些資料之後很可能會被丟給 AI 整理（你自己就會這樣做）。 座號＋一張你自己保管的紙本對照表，功能完全一樣，風險少一個數量級。

紅線二：每一張表都要開 RLS，而且只開到剛好夠用

• 每張表都要 enable row level security（🚨 陷阱 ②：SQL 建的表預設是關的）
• policy 只給這個作品真的需要的動作。文字雲需要 INSERT ＋ SELECT，就不要給 UPDATE 和 DELETE——沒給，就沒有人能改別人的詞、沒有人能清空整張表
• 本包步驟 3-2 的範本刻意只 grant select, insert，就是這個道理

紅線三：Secret key 永不進前端、永不進 GitHub

• sb_secret_... 只有伺服器端會用到。本包全程用不到它
• 不要貼進網頁、不要貼進 GitHub（連私有 repo 都不要）、不要貼進聊天視窗給 AI
• 萬一貼出去了：立刻回 Dashboard → API Keys 把那把 key 撤銷（revoke）並重新產生。 刪掉檔案、刪掉訊息沒有用，key 已經在別人手上了 —— 換掉它才是唯一有效的處置。

💡 為什麼「金鑰出現在網頁裡」不是漏洞（這段請講給老師聽）

老師第一次按 F12 看到自己的 key 出現在原始碼裡，一定會嚇一跳：「這樣不是被看光了？」

是被看光了。而且這是設計，不是漏洞。

sb_publishable_... 的中文意思就是「可以公開的」。它的角色不是「密碼」，是「這棟樓的地址」—— 知道地址不代表可以進去，因為門口有警衛。那個警衛就是 RLS。

所以真正的重點是：

🔴 不設 RLS，等於把資料庫的門拆掉，放在馬路上。

而且門牌（金鑰）就貼在你的網頁原始碼上，任何人按 F12 就看得到。

具體會發生什麼事（不是嚇你，是這幾件事都不需要任何技術能力）：

最後一列才是關鍵：沒有 RLS 的資料庫，不是「比較危險」，是「出事了你也不知道」。

所以本包的 SQL 範本才會堅持把 enable row level security 和 policy 寫在同一段裡—— 分開寫，就一定會有人只跑前半段。

常見坑

✅ 成功訊號（機器可判讀）

依序執行，agent 依規則判定：

-- 在 Supabase SQL Editor 執行
select relrowsecurity from pg_class where relname = '<你的表名>';
select policyname, cmd from pg_policies where tablename = '<你的表名>';
select has_table_privilege('anon', 'public.<你的表名>', 'select') as can_read,
       has_table_privilege('anon', 'public.<你的表名>', 'insert') as can_write;
select tablename from pg_publication_tables where pubname = 'supabase_realtime';

最後輸出這一段（沒做的填 SKIP，失敗填 FAIL:<原因>）：

SUPABASE_PACK_STATUS=OK
SB_KEY=OK
SB_EXPOSED=OK
SB_RLS_ON=OK
SB_POLICY_INSERT=OK
SB_POLICY_SELECT=OK
SB_REALTIME=OK
SB_WRITE_E2E=OK
SB_LIVE_E2E=OK
SB_KEEPALIVE=OK
SB_MCP=SKIP

🔴 SB_RLS_ON、SB_POLICY_SELECT、SB_EXPOSED 任一為 FAIL，SUPABASE_PACK_STATUS 就必須是 FAIL。 這三項就是四個陷阱的機器版本，不准跳過、不准「先繼續之後再補」。

完成回報格式

## Supabase 即時資料庫連接結果

- Supabase 專案：`<專案名>`（region：<區域>）
- 建專案時「Automatically expose new tables」：有勾 / 沒勾 / 找不到該選項
- 金鑰類型：sb_publishable_（新式）/ anon（舊式，建議換新）
- 金鑰驗證（SB_KEY）：PASS / FAIL
- 資料表：`public.<表名>`（欄位：<列出>）

### 四個陷阱檢查
- ① Data API 曝露（SB_EXPOSED）：PASS / FAIL
- ② RLS 已啟用（SB_RLS_ON）：PASS / FAIL　← 建表方式：SQL / Table Editor
- ③ INSERT ＋ SELECT policy 皆存在（SB_POLICY_*）：PASS / FAIL
- ④ 使用新式金鑰、前端無 secret key：PASS / FAIL

### 端對端
- Realtime 已加入 publication（SB_REALTIME）：PASS / FAIL / SKIP
- 網頁寫入 → Table Editor 看得到（SB_WRITE_E2E）：PASS / FAIL
- 第二台裝置即時同步（SB_LIVE_E2E）：PASS / FAIL / SKIP
- GitHub Pages 網址：<url>

### 防暫停
- workflow 檔案：`.github/workflows/supabase-keep-alive.yml` 已建立 / 未建立
- 兩個 Secret 已設定：是 / 否
- 手動 Run 測試（SB_KEEPALIVE）：PASS / FAIL
- 已告知使用者「GitHub Actions 60 天無活動會自動停用」：是 / 否

### MCP（選用）
- 是否安裝：是 / 否（研習建議「否」）
- read_only 與 project_ref 參數：已加 / 未加

### 安全確認
- 資料表內只有座號、無姓名等個資：是 / 否
- 前端與 repo 中不含 sb_secret_：是 / 否
- 已向使用者說明「這組 policy 只適用研習假資料」：是 / 否

### 待處理
- <把 FAIL 的項目與原因列在這裡；全部 PASS 就寫「無」>

如果做壞了，怎麼重來

對 OpenCode 說：「Supabase 這一包做壞了，幫我把表砍掉重建。」

手動版（在 SQL Editor 跑）：

drop table if exists public.wordcloud;

⚠️ drop table 會把資料一起刪掉，而且沒有資源回收桶。 研習用的假資料無所謂；如果裡面已經有你要留的東西，先去 Table Editor 匯出 CSV 再刪。

刪完回步驟三重貼一次那段 SQL 即可。

其他層級的重來：

下一步

• 作品要上線、要備份 → 07-github
• 不需要「同時多人寫」的資料（報名、繳交、點名）→ 用 05-sheets-gas，比較單純
• 想在網頁上做語音／字幕素材 → 02-file-toolkit

📌 想用 Firebase 而不是 Supabase？看 extras/firebase。 那是替代方案，不在研習主線，內容也未經 v2 重新查證。