paper
All projects
獨立開發者 / 維運者 / Ongoing

Paper Discord Bot

從高中時期開始獨立開發與維護的 Discord bot,涵蓋音樂播放、伺服器管理與自訂指令系統,背後有持久化資料庫、快取層與獨立的 Go API 服務支撐長期穩定運作。

TypeScriptdiscord.js v14Node.jsMongoDBRedisFastifyGoGingorilla/websocketJWTSentrymoonlink
01 / Overview

The problem, and the approach.

Problem

bot 長期在數百個 server 上運行,重啟或部署後必須維持每個 server 的播放狀態、設定與權限,同時大量重複的資料庫查詢(如伺服器設定、使用者權限)會在高併發時造成延遲與資料庫壓力。

Solution

設計 PaperClient 作為核心,將狀態持久化到 MongoDB 以支援跨重啟恢復;高頻讀取的資料(伺服器設定、快取型查詢)導入 Redis 作為 cache 層;另外拆出一個獨立的 Go 後端 paper-api,用 Gin 處理 Discord OAuth2 與 dashboard 對 bot 的控制請求,讓 bot 進程本身專注在事件處理,不被 web 層的請求邏輯拖累。

02 / Architecture

How the system fits together.

選擇節點查看元件職責與它在整體系統中的位置。

discord

Discord

使用者互動的入口,透過 Gateway 事件與 bot 通訊。

Hover、focus 或點擊節點來探索架構。

03 / Request flow

Follow a request.

用一個具體請求理解資料與控制流程,而不只停留在技術名稱。

Illustrative request flow

  1. 01
    Request

    使用者於 Discord 觸發指令,例如查詢伺服器設定。

  2. 02
    Redis MISS

    cache 中沒有對應資料。

  3. 03
    MongoDB Query

    向持久化資料庫查詢原始資料。

  4. 04
    Redis SET

    將查詢結果寫回 cache,設定 TTL。

  5. 05
    Response

    將結果回傳給使用者。

04 / Engineering decisions

Trade-offs are part of the design.

記錄選項、選擇理由與代價,讓設計決策可以被理解,而不只是被展示。

為什麼引入 Redis

Problem

伺服器設定、權限等資料被高頻率重複讀取,每次都直接打 MongoDB,在多 server 併發時造成不必要的資料庫負載與回應延遲。

Options considered

  • 維持全部查詢直接打 MongoDB,靠索引優化
  • 在應用層做 in-memory cache(單一 process 內)
  • 導入 Redis 作為獨立的 cache 層

Decision

導入 Redis,採用 cache-aside 策略。

Why

  • cache 與應用邏輯分離,未來多 process / 水平擴展時仍可共用同一份 cache
  • Redis 原生支援 TTL,可以直接控制資料新鮮度而不用額外寫過期邏輯
  • 讀取路徑簡單:先查 cache,miss 才查資料庫並回填

Trade-offs

  • 多一個要維運的服務,多一個故障點
  • cache 與資料庫之間存在短暫的不一致視窗(eventual consistency)
  • 需要額外設計 cache invalidation 策略,避免資料更新後讀到舊值

為什麼把 API 拆成獨立的 Go 服務

Problem

bot 本身用 TypeScript / Fastify 處理 Discord 事件,如果把 dashboard 需要的 OAuth2 與控制請求也塞進同一個進程,web 層的請求會跟 bot 的事件處理互相搶資源。

Options considered

  • 全部邏輯留在既有的 Fastify 服務裡
  • 拆成獨立服務,但用 Node.js 寫,共用同一套語言
  • 拆成獨立的 Go 服務

Decision

用 Go + Gin 建立獨立的 paper-api 服務,搭配 gorilla/websocket 與 JWT。

Why

  • 職責分離:bot 進程只處理 Discord 事件,web 層的流量不會影響 bot 的即時性
  • 藉此機會學習 Go,累積除了 TypeScript 生態以外的後端經驗
  • Go 的併發模型適合處理 dashboard 的 WebSocket 連線與多個 bot 控制請求

Trade-offs

  • 系統裡多了一個語言,增加維護與除錯的認知負擔
  • bot 與 API 之間需要額外定義溝通介面,而不是直接共用同一份程式碼
05 / Code notes

A closer look at the code.

typescript / Cache-aside 讀取邏輯

const cached = await redis.get(key)
if (cached) {
  return JSON.parse(cached)
}

const data = await mongo.collection("guildSettings").findOne({ guildId })
await redis.set(key, JSON.stringify(data), { EX: 300 })

return data

What

先查 Redis,miss 的話才查 MongoDB,並把結果寫回 cache。

Why

把高頻讀取的路徑集中在延遲較低的 Redis,只有第一次或 cache 過期時才真正打資料庫。

Trade-off

TTL 設定 300 秒代表最多有 5 分鐘的資料延遲,對設定類資料可以接受,但不適合用在需要強一致性的場景。

Project notes

Railway.app

Deployment