3993 字
20 分鐘

Ghost 文章觀看數怎麼做?用 Cloudflare Workers 和 D1 自架計數器

驗證於

本文目錄

用 WordPress 的人換到 Ghost,常會發現一件事:文章頁沒有「幾次觀看」。Ghost 6 的原生分析要接 Tinybird,數字只顯示在後台,主題讀不到;自架時想把 Tinybird 也搬到自己機器上,Tinybird Local 的官方定位又是開發用的隔離環境,不適合拿來跑正式站。

如果網站本來就放在 Cloudflare 後面,比較省事的做法是自己用 Cloudflare Workers 加 D1 做一個計數器:Worker 掛在同網域的 /api/views 路徑,D1 存每篇文章的累計數字,主題用一小段 JavaScript 讀寫。做完的效果像這樣,文章日期和閱讀時間後面多一個「N 次觀看」:

文章標題下方的資訊列,最後顯示眼睛圖示和「4 次觀看」

首頁和列表的文章卡片也會顯示,0 次的就不顯示:

文章卡片底部的發布時間和觀看數

以下用 example.com 當網站網域、views-db 當 D1 資料庫、view-counter 當 Worker 名稱,實際部署時換成自己的。

整體架構:Worker 只接 /api/views#

元件做什麼
D1 views 表每篇文章一列,存累計觀看數
D1 seen 表記錄 30 分鐘內看過的訪客,用來去重
Worker 路由 example.com/api/views*只處理計數 API,不碰 Ghost 的 /ghost/api
主題 JavaScript文章頁送 POST 加 1,列表頁批次 GET 讀數字

三個 API 端點:

  • POST /api/views/:slug:加 1,回傳最新數字。
  • GET /api/views/:slug:讀單篇的數字。
  • GET /api/views?slugs=a,b,c:一次讀多篇,給列表卡片用,回應快取 60 秒。

為什麼掛同網域,而不是用 workers.dev#

Worker 預設會有一個 *.workers.dev 網址。計數器改用網站自己的路徑,好處有兩個:瀏覽器送的是同源請求,不用處理 CORS;而且 example.com/api/views 看起來就是網站本身的 API,比第三方網域不容易被廣告攔截外掛擋掉。部署時也順便把 workers.dev 網址關掉,避免有人繞過網域檢查直接打。

依 Cloudflare Routes 文件,路由只能加在 DNS 有開 Cloudflare 代理(橘色雲朵)的主機名稱上,網站本來就在 Cloudflare 後面的話,這個條件已經滿足。

為什麼用 D1,不用 KV#

計數器最怕的是同時有好幾個人打開同一篇文章。KV 沒有原子操作,只能「讀出數字、加 1、寫回去」,兩個請求同時讀到 10,就會都寫回 11,少算一次。依 Cloudflare KV 文件,KV 是最終一致的儲存,官方也寫明不適合需要原子操作的用途;同一個 key 每秒也只能寫入 1 次。

D1 是 SQLite,可以用一行 SQL 在資料庫裡直接加 1,並發時也不會少算:

INSERT INTO views (slug, count, updated_at) VALUES (?1, 1, ?2)
ON CONFLICT(slug) DO UPDATE SET count = count + 1, updated_at = excluded.updated_at
RETURNING count;

建立 D1 資料庫和資料表#

先用 Wrangler 建資料庫:

Terminal window
npx wrangler d1 create views-db

建好後會拿到一組 database ID,等一下要填進設定檔。接著建立 schema.sql:

CREATE TABLE IF NOT EXISTS views (
slug TEXT PRIMARY KEY,
count INTEGER NOT NULL DEFAULT 0,
updated_at INTEGER NOT NULL
);
CREATE TABLE IF NOT EXISTS seen (
h TEXT PRIMARY KEY,
ts INTEGER NOT NULL
);

views 存每篇文章的累計數字;seen 存「訪客 + 文章」的雜湊值和最後計數的時間,用來判斷 30 分鐘內是不是同一個人重看。把資料表建到線上的資料庫:

Terminal window
npx wrangler d1 execute views-db --remote --file=schema.sql

Worker 程式碼#

完整的 worker.js。SITE_HOSTS 和 SITE_ORIGIN 換成自己的網域:

// view-counter: per-article view counter for a Ghost site (Workers + D1)
const SITE_ORIGIN = "https://example.com";
const SITE_HOSTS = new Set(["example.com", "www.example.com"]);
const SLUG_RE = /^[a-z0-9-]{1,190}$/;
const BOT_RE = /bot|crawl|spider|slurp|scrap|preview|facebookexternalhit|embedly|headless|phantom|puppeteer|playwright|selenium|lighthouse|pagespeed|python|curl|wget|httpie|axios|node-fetch|undici|go-http|okhttp|java\/|libwww|postman|insomnia|monitor|uptime|pingdom/i;
const DEDUPE_SEC = 30 * 60;
const GET_TTL = 60;
const json = (obj, status = 200, extra = {}) =>
new Response(JSON.stringify(obj), {
status,
headers: { "content-type": "application/json; charset=utf-8", "x-robots-tag": "noindex", ...extra },
});
// Only accept requests whose Origin (or Referer) is this site.
function sameOrigin(req) {
for (const h of ["origin", "referer"]) {
const v = req.headers.get(h);
if (!v) continue;
try { return SITE_HOSTS.has(new URL(v).hostname); } catch { return false; }
}
return false;
}
// IPv6 users rotate addresses inside their /64, so dedupe on the /64 prefix.
function ipKey(ip) {
if (!ip.includes(":")) return ip;
const [head, tail = ""] = ip.split("::");
const h = head ? head.split(":") : [], t = tail ? tail.split(":") : [];
const full = ip.includes("::") ? [...h, ...Array(8 - h.length - t.length).fill("0"), ...t] : h;
return full.slice(0, 4).map((g) => g.toLowerCase().replace(/^0+(?=.)/, "")).join(":") + "::/64";
}
async function sha256(s) {
const buf = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(s));
return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
}
async function getCount(env, slug) {
const row = await env.DB.prepare("SELECT count FROM views WHERE slug = ?").bind(slug).first();
return row ? row.count : 0;
}
// Only checked the first time a slug is seen, so junk slugs can't fill the table.
async function postExists(slug) {
const r = await fetch(`${SITE_ORIGIN}/${slug}/`, {
method: "HEAD", redirect: "manual", headers: { "user-agent": "view-counter-check" },
cf: { cacheTtl: 300, cacheEverything: true },
});
return r.status === 200;
}
async function increment(req, env, ctx, slug) {
if (!sameOrigin(req)) return json({ error: "forbidden" }, 403);
const ua = req.headers.get("user-agent") || "";
if (!ua || BOT_RE.test(ua)) return json({ slug, count: await getCount(env, slug), counted: false });
const now = Math.floor(Date.now() / 1000);
const existing = await env.DB.prepare("SELECT count FROM views WHERE slug = ?").bind(slug).first();
if (!existing && !(await postExists(slug))) return json({ error: "not_found" }, 404);
const ip = req.headers.get("cf-connecting-ip") || "0";
const h = await sha256(`${env.IP_SALT}|${ipKey(ip)}|${ua}|${slug}`);
const seen = await env.DB.prepare(
"INSERT INTO seen (h, ts) VALUES (?1, ?2) ON CONFLICT(h) DO UPDATE SET ts = excluded.ts WHERE seen.ts < ?3"
).bind(h, now, now - DEDUPE_SEC).run();
let count, counted = false;
if (seen.meta.changes > 0) {
const row = await env.DB.prepare(
"INSERT INTO views (slug, count, updated_at) VALUES (?1, 1, ?2) ON CONFLICT(slug) DO UPDATE SET count = count + 1, updated_at = excluded.updated_at RETURNING count"
).bind(slug, now).first();
count = row.count; counted = true;
} else {
count = existing ? existing.count : 0;
}
// Occasionally clean up expired dedupe rows.
if (Math.random() < 0.02) {
ctx.waitUntil(env.DB.prepare("DELETE FROM seen WHERE ts < ?").bind(now - DEDUPE_SEC).run());
}
return json({ slug, count, counted }, 200, { "cache-control": "no-store" });
}
async function cachedGet(req, ctx, producer) {
const cache = caches.default;
const key = new Request(new URL(req.url).toString(), { method: "GET" });
const hit = await cache.match(key);
if (hit) return hit;
const res = json(await producer(), 200, { "cache-control": `public, max-age=${GET_TTL}` });
ctx.waitUntil(cache.put(key, res.clone()));
return res;
}
export default {
async fetch(req, env, ctx) {
const url = new URL(req.url);
const path = url.pathname.replace(/\/+$/, "");
if (!path.startsWith("/api/views")) return fetch(req); // safety: pass through anything else
if (path === "/api/views") {
if (req.method !== "GET") return json({ error: "method_not_allowed" }, 405, { allow: "GET" });
const slugs = [...new Set((url.searchParams.get("slugs") || "").split(",").map((s) => s.trim()).filter(Boolean))];
if (!slugs.length || slugs.length > 60 || !slugs.every((s) => SLUG_RE.test(s))) return json({ error: "bad_slugs" }, 400);
return cachedGet(req, ctx, async () => {
const { results } = await env.DB.prepare(
`SELECT slug, count FROM views WHERE slug IN (${slugs.map(() => "?").join(",")})`
).bind(...slugs).all();
const counts = Object.fromEntries(slugs.map((s) => [s, 0]));
for (const r of results) counts[r.slug] = r.count;
return { counts };
});
}
const m = path.match(/^\/api\/views\/([^/]+)$/);
if (!m || !SLUG_RE.test(m[1])) return json({ error: "bad_slug" }, 400);
const slug = m[1];
if (req.method === "POST") return increment(req, env, ctx, slug);
if (req.method === "GET" || req.method === "HEAD") return cachedGet(req, ctx, async () => ({ slug, count: await getCount(env, slug) }));
return json({ error: "method_not_allowed" }, 405, { allow: "GET, POST" });
},
};

幾個關鍵段落:

  • 原子累加:真正加 1 的只有 INSERT … ON CONFLICT … RETURNING count 那一句,數字在資料庫裡算好再回傳。
  • 去重:seen 表的 INSERT … ON CONFLICT(h) DO UPDATE … WHERE seen.ts < ?3 只有在「第一次看」或「上次計數超過 30 分鐘」時才會改到資料,meta.changes > 0 才去加 1。
  • 清理:過期的去重紀錄不用排程清,每次計數有 2% 的機率順手刪掉,用 ctx.waitUntil 在回應之後執行,不拖慢回應。
  • 批次讀取:一次最多 60 篇,超過或格式不對直接回 400;回應用 Cache API 快取 60 秒,列表頁被很多人看時不會每次都查 D1。

防灌水:擋掉大部分「不是真人在看」的請求#

計數 API 是公開的,任何人都能對它送 POST。上面的程式碼用了幾層檢查:

  1. slug 格式:只接受 ^[a-z0-9-]{1,190}$,也就是 Ghost 預設的網址代稱格式。
  2. 文章要真的存在:資料庫裡還沒有這個 slug 時,先對 https://example.com/<slug>/ 送 HEAD,回 200 才寫入。這樣亂打的 slug 不會塞滿資料表;這個檢查假設文章網址是 Ghost 預設的 /<slug>/,有改過網址結構的要跟著調整。
  3. 只收本站來的請求:Origin 或 Referer 不是自己網域的,回 403。瀏覽器送同源的 POST 時會自動帶 Origin,正常讀者不受影響。
  4. 過濾爬蟲和工具:User-Agent 是空的,或含 bot、curl、python、headless、puppeteer、lighthouse 這類字串的,照樣回傳數字,但不計數。
  5. 同一位訪客 30 分鐘只算一次:用「鹽值 + IP + User-Agent + slug」做 SHA-256 雜湊,資料庫只存雜湊值,不存原始 IP。IPv6 取前 64 位元的網段,因為手機的 IPv6 位址常在同一個網段裡換來換去,用完整位址會一直被當成新訪客。

要知道的是,Origin 和 User-Agent 都能被程式偽造,這些檢查擋的是爬蟲和隨手灌水,不是刻意攻擊。觀看數本來就是給讀者參考的數字,不要拿來當計費或排名的依據。

設定檔與部署#

wrangler.toml:

name = "view-counter"
main = "worker.js"
compatibility_date = "2026-11-01"
account_id = "YOUR_ACCOUNT_ID"
# Only serve on the site's own domain
workers_dev = false
preview_urls = false
routes = [
{ pattern = "example.com/api/views*", zone_name = "example.com" }
]
[[d1_databases]]
binding = "DB"
database_name = "views-db"
database_id = "YOUR_DATABASE_ID"

workers_dev = false 會關掉 workers.dev 網址,preview_urls = false 關掉預覽網址。有 www.example.com 也會被讀者用到的話,再加一條 www.example.com/api/views* 的路由。

鹽值不要寫進程式碼或設定檔,用 secret 存。先產生一組隨機字串,再設成 IP_SALT:

Terminal window
openssl rand -hex 32
npx wrangler secret put IP_SALT
npx wrangler deploy

鹽值設好之後就不要再換,換了之後所有人的雜湊都會變,30 分鐘內重看會被多算一次(影響不大,但沒必要)。

主題:在文章頁顯示「N 次觀看」#

文章頁#

在 post.hbs 裡,日期和閱讀時間的後面加上這段。圖示用的是 Lucide 的 eye:

<span class="post-views" data-views-post data-views-slug="{{slug}}" hidden>
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
<path d="M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0"/>
<circle cx="12" cy="12" r="3"/>
</svg>
<span class="post-views-count"></span> 次觀看
</span>

預設加上 hidden,拿到數字才顯示。API 掛掉、超過免費額度或被外掛擋掉時,讀者只會看到原本的日期和閱讀時間,不會出現「0 次觀看」或錯誤訊息。

列表卡片#

首頁、標籤頁的卡片(通常在 partials/post-card.hbs)加上類似的標記,只是改成 data-views-card:

<span class="post-views" data-views-card data-views-slug="{{slug}}" hidden>
<svg ...同上...></svg>
<span class="post-views-count"></span>
</span>

JavaScript#

放在主題的 JS 檔,或 default.hbs 的 {{ghost_foot}} 前面:

(() => {
const API = "/api/views";
const TTL = 30 * 60 * 1000;
// Don't count Ghost previews (/p/<uuid>/) or pages shown inside the admin iframe.
const isPreview = location.pathname.startsWith("/p/") || window.self !== window.top;
const show = (el, n) => {
if (!n) return; // 0 or missing: keep hidden
el.querySelector(".post-views-count").textContent = n.toLocaleString();
el.hidden = false;
};
// Article page: POST once per 30 minutes, otherwise just read.
const post = document.querySelector("[data-views-post]");
if (post) {
const slug = post.dataset.viewsSlug;
const key = `viewed:${slug}`;
let recent = false;
try { recent = Date.now() - Number(localStorage.getItem(key) || 0) < TTL; } catch {}
const shouldCount = !isPreview && !recent;
fetch(`${API}/${slug}`, { method: shouldCount ? "POST" : "GET" })
.then((r) => (r.ok ? r.json() : null))
.then((d) => {
if (!d) return;
if (shouldCount) { try { localStorage.setItem(key, String(Date.now())); } catch {} }
show(post, d.count);
})
.catch(() => {});
}
// List cards: batch GET, up to 60 slugs per request.
const cards = [...document.querySelectorAll("[data-views-card]")];
const slugs = [...new Set(cards.map((el) => el.dataset.viewsSlug))];
for (let i = 0; i < slugs.length; i += 60) {
const batch = slugs.slice(i, i + 60);
fetch(`${API}?slugs=${batch.join(",")}`)
.then((r) => (r.ok ? r.json() : null))
.then((d) => {
if (!d) return;
cards.forEach((el) => {
const n = d.counts[el.dataset.viewsSlug];
if (n !== undefined) show(el, n);
});
})
.catch(() => {});
}
})();

瀏覽器端用 localStorage 記住 30 分鐘內看過的文章,這段時間內重新整理只會送 GET,不會送 POST,和伺服器端的去重是兩道關卡。

改完主題後打包上傳,或用自己平常更新主題的方式部署。

上線後怎麼測#

用瀏覽器實際開一篇文章,再用 curl 測被擋的情況:

測試預期結果
第一次打開文章數字 +1,畫面出現「N 次觀看」
30 分鐘內重新整理數字不變
curl -X POST https://example.com/api/views/some-post403,沒有 Origin
加上 -H "Origin: https://other.example"403,不是本站
加上本站 Origin,但用 curl 預設的 User-Agent200,counted: false
本站 Origin、一般瀏覽器 UA、不存在的 slug404,不會寫入資料庫
GET /api/views?slugs=a,b,c回傳 {"counts": {...}}

也要確認原本的功能沒被影響:首頁、Ghost 後台、/sitemap.xml、RSS 都要能正常打開。Worker 只掛在 /api/views*,理論上不會碰到,但上線後實際點一輪比較安心。

有一個容易誤判的地方:如果測試環境每次連線的 IP 都不一樣(例如經過會輪替出口 IP 的代理或雲端瀏覽器),伺服器端的 30 分鐘去重看起來會「失效」,每次重新整理都 +1。這不是程式壞掉,而是每次都被當成新訪客。這段判斷要另外單獨測:從固定 IP 的電腦,清掉 localStorage 後連續送兩次 POST,第二次應該回 counted: false。

免費額度夠用嗎#

依 Workers 限制文件和 D1 價格文件,Workers Free 的額度是:

項目免費額度
Workers 請求每天 10 萬次
D1 讀取列數每天 500 萬列
D1 寫入列數每天 10 萬列
D1 儲存空間共 5 GB

估算時注意三件事:

  • Workers 的 10 萬次是整個帳號共用的,帳號裡還有其他 Worker 的話要一起算。每次打開文章是 1 次請求,每次打開列表頁也是 1 次請求;快取命中時仍會執行 Worker,一樣算請求。
  • D1 算的是「列」不是「查詢」。 每次計入觀看會寫入 seen 和 views 兩張表,再加上主鍵索引的更新,寫入列數會是計入次數的好幾倍,10 萬列寫入撐不到 10 萬次觀看。實際用量可以到 D1 資料庫的 Metrics → Row Metrics 查看。
  • 每日額度在 00<00> UTC 重設,也就是台灣時間早上 8 點。

超過額度時,依官方文件,D1 會拒絕查詢;Workers 超過每日請求數時,路由可以設成 Fail open(略過 Worker)或 Fail closed(回 1027 錯誤頁)。不管哪一種,計數 API 都拿不到正常的 JSON,主題就維持隱藏,文章和其他頁面照常運作,只是暫時看不到觀看數。D1 超額的處理方式可以參考 Cloudflare D1 超過每日限制怎麼辦。

限制:數字從上線那天開始算#

這個計數器沒有歷史資料,上線前的觀看次數都是 0。想讓舊文章有比較合理的起始數字,可以從 GA4 匯出各篇文章的瀏覽數,再寫進 D1:

INSERT INTO views (slug, count, updated_at)
VALUES ('my-first-post', 1234, strftime('%s', 'now'))
ON CONFLICT(slug) DO UPDATE SET count = count + excluded.count;

把每篇文章整理成一行,存成 seed.sql 後執行 npx wrangler d1 execute views-db --remote --file=seed.sql。GA4 的「瀏覽」和這個計數器的算法不同(沒有 30 分鐘去重、也不過濾同一套 UA),匯入後的數字只能當參考的起點。

常見問題#

Q: Ghost 6 有內建文章觀看數嗎?#

A: 前台沒有。Ghost 6 的原生 Web Analytics 由 Tinybird 提供,數據顯示在 Ghost 後台,主題無法讀取並顯示在文章頁。自架時要啟用原生分析,官方說明需要用 Docker 安裝方式並設定 Tinybird 帳號。想在文章頁顯示觀看數,就要自己做計數器。

Q: 為什麼計數不用 Cloudflare KV?#

A: KV 沒有原子操作,只能讀出數字、加 1、再寫回去,同時有多個請求時會互相覆蓋而少算;Cloudflare 官方文件也寫明 KV 是最終一致的儲存,不適合需要原子操作的用途,同一個 key 每秒只能寫 1 次。D1 可以用 SQL 在資料庫內直接加 1,並發時不會少算。

Q: 會存到讀者的 IP 嗎?#

A: 不會存原始 IP。伺服器端把鹽值、IP(IPv6 取 /64 網段)、User-Agent 和文章代稱組在一起做 SHA-256 雜湊,資料庫只存雜湊值和時間,用來判斷 30 分鐘內是否重看;過期的紀錄會定期刪除。鹽值用 wrangler secret 存,不寫在程式碼裡。

Q: 超過免費額度網站會掛掉嗎?#

A: 不會。Worker 只掛在 /api/views*,文章、首頁和後台都不經過它。超過 Workers 或 D1 的每日額度時,計數 API 會回錯誤,主題拿不到數字就維持隱藏,讀者只是暫時看不到觀看數,每日額度在台灣時間早上 8 點重設。

參考資料:

Ghost Docs:How To Install Ghost With Docker

Ghost:Tinybird Integration

Tinybird Docs:Tinybird Local

Cloudflare Docs:Workers Limits

Cloudflare Docs:D1 Pricing

Cloudflare Docs:How KV works

Cloudflare Docs:Routes

Ghost 文章觀看數怎麼做?用 Cloudflare Workers 和 D1 自架計數器
https://laplusda.com/posts/ghost-view-counter-cloudflare-workers-d1/
作者
Zero
發佈於
2026-11-17
許可協議
CC BY-NC-SA 4.0