Firestore Hands-on 操作路線 on Tarragon

Firestore Distributed Counter Lab

Tue, 16 Jun 2026 00:00:00 +0000

本文是 Firestore Hands-on 操作路線的 lab，實作 distributed counter 高頻寫入 deep article 的機制。前置環境見 Local emulator quickstart。

Firestore distributed counter lab 的核心責任是把「分片計數」從概念變成可觀察的寫入分佈與彙總結果。這個 lab 在 emulator 上建立 N 個 shard、隨機分片寫入大量 increment、檢查寫入是否均勻打散到各 shard、再讀取彙總驗證總和正確。

本文的驗收標準是：你能跑出一個 sharded counter、看到 N 個 shard 各自累積了大致均勻的 partial count、彙總後等於總寫入次數，並理解 emulator 能驗什麼、不能驗什麼。

先講清楚 emulator 的邊界

這個 lab 驗證的是分片計數的機制正確性：寫入是否均勻分佈、彙總是否等於總和、讀取要讀幾個 document。它不驗證的是 contention 本身——emulator 不強制 production 的單 document 持續寫入軟上限，所以「不分片會寫爆」這件事在 emulator 跑不出來。contention 是 production 的規模特性，要在雲端真實負載下才會出現。

這個分界本身是要學的判讀：emulator 證明「分片計數做對了」，雲端負載測試才證明「不分片會撞牆」。把兩者混為一談會誤以為 emulator 全綠就代表 production 安全。

Lab 環境

沿用 quickstart 的工作區與 emulator。確認 emulator 在跑（另一個 terminal）。

1cd /tmp/firestore-lab
2# 確認 emulator 已啟動：firebase emulators:start --only firestore --project demo-firestore-lab
3export FIRESTORE_EMULATOR_HOST=localhost:8080

實作 sharded counter

counter 的核心責任是把一個邏輯計數拆成 N 個 shard document。寫入時隨機挑 shard increment(1)，讀取時加總所有 shard。這份 script 用 admin SDK 直接對 emulator 操作。

 1cat > counter.js <<'JS'
 2const admin = require('firebase-admin');
 3admin.initializeApp({ projectId: 'demo-firestore-lab' });
 4const db = admin.firestore();
 5const FieldValue = admin.firestore.FieldValue;
 6
 7const NUM_SHARDS = 10;
 8const counterRef = db.collection('counters').doc('likes');
 9
10async function createCounter() {
11  const batch = db.batch();
12  for (let i = 0; i < NUM_SHARDS; i++) {
13    batch.set(counterRef.collection('shards').doc(String(i)), { count: 0 });
14  }
15  await batch.commit();
16}
17
18async function incrementOnce() {
19  const shardId = Math.floor(Math.random() * NUM_SHARDS);
20  await counterRef.collection('shards').doc(String(shardId))
21    .set({ count: FieldValue.increment(1) }, { merge: true });
22}
23
24async function getCount() {
25  const snap = await counterRef.collection('shards').get();
26  let total = 0;
27  const perShard = {};
28  snap.forEach((s) => { perShard[s.id] = s.data().count; total += s.data().count; });
29  return { total, perShard };
30}
31
32module.exports = { createCounter, incrementOnce, getCount, NUM_SHARDS };
33JS

三個設計點對應 deep article：用 FieldValue.increment(1) 而非讀-改-寫（避開 race）；隨機選 shard 讓寫入均勻打散；讀取要讀 N 個 shard 加總（這是分片的代價）。

跑寫入並觀察分佈

driver 的核心責任是製造大量 increment、然後檢查寫入是否均勻落在各 shard。均勻分佈是分片有效的前提——若 shard 選擇有偏，熱點會在某幾個 shard 復現。

 1cat > run.js <<'JS'
 2const { createCounter, incrementOnce, getCount, NUM_SHARDS } = require('./counter');
 3
 4const TOTAL_WRITES = 1000;
 5
 6async function main() {
 7  await createCounter();
 8  console.log(`created ${NUM_SHARDS} shards`);
 9
10  // 製造 1000 次 increment
11  const tasks = [];
12  for (let i = 0; i < TOTAL_WRITES; i++) tasks.push(incrementOnce());
13  await Promise.all(tasks);
14
15  const { total, perShard } = await getCount();
16  console.log('per-shard counts:', perShard);
17  console.log(`total = ${total} (expected ${TOTAL_WRITES})`);
18
19  // 均勻度檢查：每個 shard 期望 ~100，看極差
20  const counts = Object.values(perShard);
21  const min = Math.min(...counts), max = Math.max(...counts);
22  console.log(`min=${min} max=${max} spread=${max - min} (expected mean ~${TOTAL_WRITES / NUM_SHARDS})`);
23}
24main().then(() => process.exit(0));
25JS
26
27export FIRESTORE_EMULATOR_HOST=localhost:8080
28node run.js

預期輸出類似（實際數字每次隨機分佈而異）：

1created 10 shards
2per-shard counts: { '0': 98, '1': 105, '2': 92, ... }
3total = 1000 (expected 1000)
4min=88 max=112 spread=24 (expected mean ~100)

兩個驗收點：total 等於總寫入次數（彙總正確、沒有 increment 遺失），以及各 shard 的 count 大致落在均值附近（隨機分佈均勻、沒有單一 shard 吸走大部分寫入）。

對照實驗：讀取成本隨 shard 數成長

讀取的核心代價是讀 N 個 document。把 NUM_SHARDS 改大（例如 100）重跑，getCount 要讀的 document 從 10 變 100——這就是 deep article 講的「寫入便宜了、讀取乘以 N」的取捨。在 production 這直接反映成 read 計費。

1# 編輯 counter.js 把 NUM_SHARDS 改為 100、重跑 run.js
2# 觀察 per-shard counts 物件變成 100 個 key、getCount 讀取量 10x

這個對照讓「shard 數是寫入分散與讀取成本的取捨」從文字變成可觀察：多 shard 寫入更分散（每 shard 更少），但讀取要加總更多筆。高寫入高讀取的場景該配 summary 彙總（deep article 的進階手段），而非無限加 shard。

Artifact 與驗收

Artifact	來源	驗收
counter 實作	`counter.js`	`increment` 分片寫入 + 彙總讀取
寫入分佈	`run.js` output	total = 寫入次數、各 shard 均勻
讀寫取捨	NUM_SHARDS 對照	shard 數↑ → 讀取 document 數↑

回到 production 判讀

emulator lab 證明了機制正確，但三個 production 判讀要回雲端確認：單 document 寫入軟上限（決定 shard 數要多少）、read 計費（決定 shard 數別太多 / 要不要 summary）、shard 選擇在真實流量下是否仍均勻。把 emulator 的機制驗證當第一道關，production 的容量與成本判讀見 deep article 的容量段。

Cleanup

1# 停 emulator（Ctrl-C）或清整個工作區
2rm -rf /tmp/firestore-lab

引用路徑

上游：Firestore Hands-on 操作路線
Deep article：高頻寫入與 distributed counter
一致性邊界：1.3 transaction 與一致性邊界
官方：Distributed counters、Firestore best practices

Firestore Local Emulator Quickstart

Tue, 16 Jun 2026 00:00:00 +0000

本文是 Firestore Hands-on 操作路線的基礎 lab。指令以 Firebase CLI 文件與 Emulator Suite 文件為準、最後檢查日 2026-06-16。

Firestore local emulator quickstart 的核心責任是建立後續 Security Rules 測試與 distributed counter lab 共用的本地環境。這個 lab 把 Firestore 從抽象服務轉成可觀察的 emulator、規則檔、seed 資料與 query 結果，全程不碰雲端專案。

本文的驗收標準是：你能在本地啟動 Firestore emulator、用 admin SDK 寫入並查詢一組 seed 資料、看到 emulator UI 裡的資料，並知道 cleanup 路徑。

Lab 環境與前置

Lab 在本地資料夾跑，需要 Node.js 與 Firebase CLI。以下命令建立一個可刪除的工作區並裝好工具。

1mkdir -p /tmp/firestore-lab
2cd /tmp/firestore-lab
3
4# Firebase CLI（已裝可跳過）；用 npx 也可避免全域安裝
5npm install -g firebase-tools
6
7# 本 lab 的 Node 依賴
8npm init -y
9npm install firebase-admin

emulator 需要 Java runtime（Firestore emulator 跑在 JVM 上）。java -version 確認存在；缺的話先裝 JDK 再繼續。驗收 artifact 是 /tmp/firestore-lab 工作區。

Emulator 設定

firebase.json 的核心責任是宣告要啟動哪些 emulator 與對應 port。這裡只開 Firestore 與 UI，不需要真實 Firebase 專案——emulator 用一個 demo project id 即可，demo- 前綴讓 CLI 知道這是純本地、不連雲端。

 1cat > firebase.json <<'JSON'
 2{
 3  "emulators": {
 4    "firestore": { "port": 8080 },
 5    "ui": { "enabled": true, "port": 4000 }
 6  },
 7  "firestore": {
 8    "rules": "firestore.rules"
 9  }
10}
11JSON

Baseline 規則

firestore.rules 的核心責任是定義授權。Quickstart 先用一組明確的 owner-scoped 規則（不是 allow read, write: if true，那是 deep article Case 1 的漏洞）。這份規則後續在 Security Rules test lab 會被測試覆蓋。

 1cat > firestore.rules <<'RULES'
 2rules_version = '2';
 3service cloud.firestore {
 4  match /databases/{database}/documents {
 5    match /notes/{noteId} {
 6      allow read: if request.auth != null
 7                  && resource.data.ownerId == request.auth.uid;
 8      allow create: if request.auth != null
 9                    && request.resource.data.ownerId == request.auth.uid;
10      allow update, delete: if request.auth != null
11                            && resource.data.ownerId == request.auth.uid;
12    }
13  }
14}
15RULES

啟動 emulator

啟動 emulator 的核心責任是讓本地有一個可寫可查的 Firestore。用 demo project id 啟動，emulator UI 在 http://localhost:4000 可看到資料。

1firebase emulators:start --only firestore --project demo-firestore-lab

這個指令會 foreground 跑住 emulator。保持它開著，另開一個 terminal 做 seed 與 query。終端輸出會印出 Firestore emulator 的位址（預設 localhost:8080）與 UI 位址。

Seed 資料（admin SDK 繞過規則）

Seed 的核心責任是建立可重跑的測試資料。admin SDK 連到 emulator 時繞過 Security Rules（模擬後端的特權寫入），適合種資料。關鍵是設 FIRESTORE_EMULATOR_HOST 環境變數——有了它，admin SDK 的寫入全部導向 emulator、不需要任何雲端 credential。

 1cat > seed.js <<'JS'
 2const admin = require('firebase-admin');
 3admin.initializeApp({ projectId: 'demo-firestore-lab' });
 4const db = admin.firestore();
 5
 6async function main() {
 7  await db.collection('notes').doc('n1').set({
 8    ownerId: 'alice', text: 'Alice first note', createdAt: Date.now(),
 9  });
10  await db.collection('notes').doc('n2').set({
11    ownerId: 'bob', text: 'Bob first note', createdAt: Date.now(),
12  });
13  console.log('seeded 2 notes');
14}
15main().then(() => process.exit(0));
16JS
17
18# 在新 terminal、同 lab 目錄下
19export FIRESTORE_EMULATOR_HOST=localhost:8080
20node seed.js

預期輸出 seeded 2 notes。打開 http://localhost:4000/firestore 應看到 notes collection 下兩筆 document。

Query baseline

Query 的核心責任是確認資料可讀、access pattern 入口可用。admin SDK 同樣繞過規則，這裡驗證的是資料與查詢本身（規則的放行 / 拒絕在下一個 lab 用 client context 驗）。

 1cat > query.js <<'JS'
 2const admin = require('firebase-admin');
 3admin.initializeApp({ projectId: 'demo-firestore-lab' });
 4const db = admin.firestore();
 5
 6async function main() {
 7  const snap = await db.collection('notes')
 8    .where('ownerId', '==', 'alice').get();
 9  console.log(`alice notes: ${snap.size}`);
10  snap.forEach((d) => console.log(d.id, d.data().text));
11}
12main().then(() => process.exit(0));
13JS
14
15export FIRESTORE_EMULATOR_HOST=localhost:8080
16node query.js

預期輸出 alice notes: 1 與 n1 Alice first note。這證明 where('ownerId', '==', ...) 的 access pattern 成立——它也正是 client 端要自帶、好讓 owner-scoped 規則放行的查詢條件。

Artifact 與驗收

Artifact	路徑 / 來源	驗收
emulator config	`firebase.json`	Firestore + UI port 宣告
規則檔	`firestore.rules`	owner-scoped、非 `if true`
seed 結果	`seed.js` output + UI	`notes/n1`、`notes/n2` 存在
query 結果	`query.js` output	`alice notes: 1`

Cleanup

Cleanup 的核心責任是讓 lab 可重跑。emulator 的資料在 process 結束時預設不持久化（除非設了 --export-on-exit），所以停掉 emulator 等於清空資料。

1# 停掉 emulator：在 emulator terminal 按 Ctrl-C
2# 移除整個工作區
3rm -rf /tmp/firestore-lab

若想保留 emulator 資料跨 session，啟動時加 --import=./data --export-on-exit=./data；lab 預設不持久化，保持每次乾淨起步。

完成本篇後，下一步進 Security Rules test lab（把上面的規則寫成自動化測試）或 Distributed counter lab。

引用路徑

上游：Firestore Hands-on 操作路線
Deep article：Security Rules 授權建模
官方：Install Firebase CLI、Connect to Firestore emulator

Firestore Security Rules Test Lab

Tue, 16 Jun 2026 00:00:00 +0000

本文是 Firestore Hands-on 操作路線的 lab，實作 Security Rules 授權建模 deep article 的測試方法。前置環境見 Local emulator quickstart。測試 API 以 Rules unit testing 文件為準、最後檢查日 2026-06-16。

Firestore Security Rules test lab 的核心責任是把授權規則變成可自動驗證的測試。規則是 client 直連模型的整個控制面，改一條就要證明沒開新洞——這個 lab 用 @firebase/rules-unit-testing 在 emulator 上對規則跑斷言，產出可接進 CI 與 release gate 的測試 evidence。

本文的驗收標準是：你能對一組規則寫出「放行 / 越權拒絕 / 未登入拒絕 / 欄位竄改拒絕」四類斷言、用 firebase emulators:exec 一鍵跑完、並看到 assertFails 確實證明該擋的有擋住。

Lab 環境與依賴

沿用 quickstart 的工作區與 firebase.json / firestore.rules。再裝測試依賴。

1cd /tmp/firestore-lab
2npm install --save-dev @firebase/rules-unit-testing firebase jest

驗收前置是 firestore.rules 存在（quickstart 已建立 owner-scoped 規則）與 firebase.json 宣告了 Firestore emulator。

升級規則：加入欄位竄改防護

quickstart 的規則擋了越權讀寫，但還沒擋「owner 改自己 note 時偷改 ownerId 把資料轉走」。先把規則升級到帶欄位白名單，讓測試有更多面向可驗。

 1cat > firestore.rules <<'RULES'
 2rules_version = '2';
 3service cloud.firestore {
 4  match /databases/{database}/documents {
 5
 6    function isSignedIn() { return request.auth != null; }
 7
 8    function ownsExisting() {
 9      return isSignedIn() && resource.data.ownerId == request.auth.uid;
10    }
11
12    function onlyChanges(fields) {
13      return request.resource.data.diff(resource.data).affectedKeys().hasOnly(fields);
14    }
15
16    match /notes/{noteId} {
17      allow read: if ownsExisting();
18      allow create: if isSignedIn()
19                    && request.resource.data.ownerId == request.auth.uid;
20      allow update: if ownsExisting() && onlyChanges(['text', 'updatedAt']);
21      allow delete: if ownsExisting();
22    }
23  }
24}
25RULES

onlyChanges(['text', 'updatedAt']) 是這版的重點：update 只准動 text 與 updatedAt，碰 ownerId 直接拒絕。下面的測試會驗證它。

寫測試：四類斷言

測試的核心責任是覆蓋「該放行的放行、該拒絕的拒絕」。initializeTestEnvironment 載入規則、authenticatedContext 模擬登入身分、assertSucceeds / assertFails 對操作斷言。預先種資料用 withSecurityRulesDisabled 繞過規則。

 1cat > rules.test.js <<'JS'
 2const {
 3  initializeTestEnvironment, assertFails, assertSucceeds,
 4} = require('@firebase/rules-unit-testing');
 5const { doc, getDoc, setDoc, updateDoc } = require('firebase/firestore');
 6const fs = require('fs');
 7
 8let testEnv;
 9
10beforeAll(async () => {
11  testEnv = await initializeTestEnvironment({
12    projectId: 'demo-firestore-lab',
13    firestore: { rules: fs.readFileSync('firestore.rules', 'utf8') },
14  });
15});
16afterAll(async () => { await testEnv.cleanup(); });
17beforeEach(async () => {
18  await testEnv.clearFirestore();
19  await testEnv.withSecurityRulesDisabled(async (ctx) => {
20    await setDoc(doc(ctx.firestore(), 'notes/n1'),
21      { ownerId: 'alice', text: 'hi', updatedAt: 0 });
22  });
23});
24
25// 1. 放行：owner 讀自己的
26test('owner reads own note', async () => {
27  const db = testEnv.authenticatedContext('alice').firestore();
28  await assertSucceeds(getDoc(doc(db, 'notes/n1')));
29});
30
31// 2. 越權拒絕：非 owner 讀別人的
32test('non-owner cannot read', async () => {
33  const db = testEnv.authenticatedContext('bob').firestore();
34  await assertFails(getDoc(doc(db, 'notes/n1')));
35});
36
37// 3. 未登入拒絕
38test('unauthenticated denied', async () => {
39  const db = testEnv.unauthenticatedContext().firestore();
40  await assertFails(getDoc(doc(db, 'notes/n1')));
41});
42
43// 4. 欄位竄改拒絕：owner 偷改 ownerId
44test('owner cannot change ownerId', async () => {
45  const db = testEnv.authenticatedContext('alice').firestore();
46  await assertFails(updateDoc(doc(db, 'notes/n1'), { ownerId: 'bob' }));
47});
48
49// 4b. 正當 update 放行
50test('owner can edit text', async () => {
51  const db = testEnv.authenticatedContext('alice').firestore();
52  await assertSucceeds(updateDoc(doc(db, 'notes/n1'), { text: 'edited', updatedAt: 1 }));
53});
54JS

四類斷言裡 assertFails 比 assertSucceeds 更重要——它證明的是攻擊路徑被擋住，正是滲透測試會打的點。每條規則至少要有「正向放行 + 至少一條拒絕」配對，光測 happy path 證明不了授權安全。

一鍵跑：emulators:exec

跑測試的核心責任是讓它在乾淨 emulator 上自動化執行。firebase emulators:exec 啟動 emulator、跑指定命令、結束後關閉——適合 CI，不需要手動開關 emulator。

1cat > package.json.test <<'JSON'
2{ "scripts": { "test:rules": "jest rules.test.js" } }
3JSON
4# 把 test:rules script 併進既有 package.json 後執行：
5
6firebase emulators:exec --only firestore --project demo-firestore-lab "npx jest rules.test.js"

預期輸出五個測試全 pass：

1PASS  ./rules.test.js
2  owner reads own note (passed)
3  non-owner cannot read (passed)
4  unauthenticated denied (passed)
5  owner cannot change ownerId (passed)
6  owner can edit text (passed)
7
8Test Suites: 1 passed, 1 total
9Tests:       5 passed, 5 total

（Jest 預設 reporter 每行會印一個通過標記、此處以 (passed) 文字呈現，實際終端輸出為工具自身格式。）

故意改壞驗證測試有效

測試的價值在於它會抓到回歸。把規則改回 allow read, write: if true 再跑，應看到「越權拒絕」「未登入拒絕」「欄位竄改拒絕」三個測試 fail——這證明測試確實守在攻擊路徑上，而不是恆綠的假測試。

1# 暫時把規則改成全放行
2printf "rules_version='2';\nservice cloud.firestore{match /databases/{db}/documents{match /{d=**}{allow read,write:if true;}}}" > firestore.rules
3firebase emulators:exec --only firestore --project demo-firestore-lab "npx jest rules.test.js"
4# 預期：3 個 assertFails 測試 fail（該擋的沒擋）
5# 驗證完改回上面的正確規則

Artifact 與驗收

Artifact	來源	驗收
規則測試檔	`rules.test.js`	四類斷言 + 正向 update
測試結果	`emulators:exec` 輸出	正確規則下全 pass
回歸證明	改壞後重跑	3 個 assertFails 測試轉 fail

接進 release gate

規則測試的下游責任是成為發布證據。把 firebase emulators:exec ... jest 接進 CI pipeline，規則變更的 PR 必須通過才能 merge——這把「規則改動沒開新洞」從人工推敲變成 gate 條件，對齊 6.8 release gate 的 Gate decision / Checks / Stop condition。授權翻譯的正確性是安全邊界，這個 gate 比一般功能測試更該設為硬性 stop condition。

Cleanup

1# emulators:exec 跑完會自動關 emulator；清依賴與工作區
2rm -rf /tmp/firestore-lab