這是一個用於抓取與提供 MozTW 摩茲工寮空間 環境資訊的 API 與 Telegram 機器人。基於 Hono 框架開發,可部署於 Cloudflare Workers 或 Node.js 環境。
提供簡單的 HTTP 端點供外部整合:
GET /: 回傳所有資訊 (JSON)。
機器人支援以下指令:
/space: 顯示完整的空間資訊(溫度、濕度、CO2)。
如果你只想在終端機快速查看資訊,可以使用:
npm run getnpm install將 .env.sample 複製為 .env 並填入相關資訊:
cp .env.sample .env
# 若使用 Cloudflare Workers 模式 (wrangler dev),請同時複製一份為 .dev.vars
cp .env .dev.varsTELEGRAM_BOT_TOKEN: 你的 Telegram Bot Token。SENSORS_CONFIG: 所有IoT設備的相關資訊,結構範例請看.env.sample檔案 (目前支援SwitchBot Meter/Hub 的設備)
專案支援三種本地測試模式,啟動時皆會自動建置前端與靜態資源(npm run build:assets):
使用本機 Node.js 與 @hono/node-server 執行,讀取 .env。資料庫會使用本機檔案系統(.data/ 目錄)模擬,完全獨立於 Cloudflare 遠端環境,適合離線開發、修改 API 或調整前端儀表板:
npm run dev:node- 預設網址:
http://localhost:3000(可透過環境變數PORT調整) - 儀表板頁面:開啟瀏覽器造訪
http://localhost:3000/查看即時空間狀態 - API 文件 (Swagger UI):造訪
http://localhost:3000/doc即可線上測試 API
使用 wrangler dev 模擬 Cloudflare Workers Runtime,讀取 .dev.vars:
npm run dev
# 或若需開放同區域網路的其他設備測試(監聽 0.0.0.0):
npm run dev:worker-host- 預設網址:
http://localhost:8787 - 儀表板頁面:
http://localhost:8787/ - API 文件 (Swagger UI):
http://localhost:8787/doc
本機測試 Telegram Bot 指令時,無需對外暴露 Webhook 或架設 ngrok,直接由本機主動向 Telegram 伺服器長輪詢:
npm run dev:tg
⚠️ 注意:在此模式下,必須確保該 Bot Token 目前沒有綁定 Webhook(否則 Telegram 會拒絕連線)。若需清除 Webhook,可至瀏覽器造訪:
https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/deleteWebhook
- 終端機快速查看感測器數值:
npm run get
- 手動重新編譯前端與靜態資源:
npm run build:assets
- 常用驗證端點:
GET /:前端儀表板 (Dashboard)GET /doc:內建 Swagger UI 互動式文件GET /openapi.json:OpenAPI 3.1 規範GET /sensors/data:感測器詳細數值
本專案支援 Cloudflare D1 (分散式 SQLite,推薦) 與 Cloudflare KV 兩種儲存後端,可透過環境變數 SENSOR_STORAGE 隨時切換(d1 或 kv)。
- 建立 D1 資料庫:
npx wrangler d1 create moztw-co2-db
- 將終端機回傳的
database_id填入wrangler.jsonc中的d1_databases區塊: - 匯入資料表結構與既有資料(可透過本地遷移腳本自動生成):
# 1. 執行本地遷移(將 .data/ JSON 轉移為 SQLite 並生成 seed_for_d1.sql) npm run db:migrate # 2. 匯入至線上 D1 資料庫 npx wrangler d1 execute moztw-co2-db --remote --file=./migrations/seed_for_d1.sql
若需切回 KV 模式,建立 KV Namespace 並在 wrangler.jsonc 設定 "vars": { "SENSOR_STORAGE": "kv" }:
npx wrangler kv:namespace create "SENSOR_KV"請將機器人 Token 與感測器設定存入 Cloudflare Workers 內部:
npx wrangler secret put TELEGRAM_BOT_TOKEN
npx wrangler secret put SENSORS_CONFIG
([{...}] 即可)
npm run deploy注意:部署到 Cloudflare 時請使用 Webhook 模式(
/bot端點),本地測試可使用 Long Polling (npm run dev:tg)。
https://api.telegram.org/bot<TG_TOKEN>/getWebhookInfo
https://api.telegram.org/bot<TG_TOKEN>/setWebhook?url=<YOUR_URL>/bot/<TG_TOKEN>
https://api.telegram.org/bot<TG_TOKEN>/deleteWebhook
本站已內建 Swagger UI,並提供標準 /openapi.json 規範:
- 內建 Swagger UI:伺服器啟動後直接在瀏覽器開啟
/doc(例如:http://localhost:3000/doc或http://localhost:8787/doc)即可線上瀏覽與測試。 - OpenAPI 規範:可將
/openapi.json匯入相容 OpenAPI 的客戶端(如:Insomnia、Postman)。 - 獨立 Docker Swagger UI:若想使用官方 Swagger 容器預覽,可執行:
docker run -p 9000:8080 -e SWAGGER_JSON_URL=http://localhost:8787/openapi.json docker.swagger.io/swaggerapi/swagger-ui- 只要
fetch成功或收到webhook,且該裝置不是only_webhook的主動查詢,lastchange就會更新為當前時間。 - 這代表了「系統最後一次與該設備取得聯繫」的時間,與數值是否有變無關。
- 快取保護:系統會以
lastchange結合staleThresholdSeconds(預設 600s) 判定資料是否過期。若未過期,主動查詢時會直接回傳快取內容,不發起 API 請求與 KV 寫入。
- 只有當新取得的數值(如溫度)與資料庫中現有的數值不同時,才會更新這個項目的
lastchange。 - 如果數值相同,則保留舊的變動時間。
- 寫入優化:若所有感測數值均未變動,系統將跳過歷史紀錄 (Raw Ingestion) 的寫入,僅更新目前的狀態以節省 Cloudflare KV PUT 額度。
- 如果裝置設定為
only_webhook: true,則主動的fetch行為不會更新整體的lastchange。 - 該裝置的
lastchange只有在真正收到 Webhook 通知時才會變動,符合您「記錄上次被通知時間」的需求。
當未來引入新感測器或需要擴充新的監測指標(如:battery 電量、light_level 光照度、pm25 等)時,請依照以下檢查清單依序修改:
- 宣告型別 (
interface SensorDataRecord): 新增屬性及其變動追蹤元資料:battery?: number; battery_lastchange?: number; battery_iswebhook?: boolean;
- 屬性合併 (
consolidate):- 將新欄位加入泛型 key 聯集:
K extends 'temperature' | ... | 'battery'。 - 加入取值:
const batteryProps = getConsolidatedProperty('battery');。 - 在回傳物件中組裝屬性(
battery,battery_lastchange,battery_iswebhook)。
- 將新欄位加入泛型 key 聯集:
- 資料來源解析:
updateFromWebhook():從 SwitchBot Webhook context 讀取並賦值。fetch():從 SwitchBot 官方雲端 API 的body讀取並賦值。
在檔案最前段的 SENSOR_FIELDS 陣列新增一筆欄位定義:
export const SENSOR_FIELDS: readonly SensorFieldDefinition[] = [
// ...既有欄位
{ column: 'battery', property: 'battery', type: 'number' }, // 新增這行
] as const;💡
save()的 INSERT 與getHistory()的 SELECT/物件映射會自動由此陣列動態驅動,無需手動修改底層 SQL 語句。
在 Cloudflare D1 資料庫的 sensor_records 表新增欄位:
ALTER TABLE sensor_records ADD COLUMN battery REAL; -- 或 INTEGER / TEXT- OpenAPI 文件與 Webhook 驗證:
src/core/route/locations.ts:更新SensorDataRecordSchema,讓 Swagger UI 與客戶端 API 包含新欄位。src/core/app.ts:若 Webhook 接收端有驗證 payload,更新SwitchBotWebhookPayload。
- Telegram 機器人 (
src/core/route/bot.ts):- 若要在
/co2或其他指令中呈現該指標文字,於訊息組裝迴圈中加入顯示條件。
- 若要在
- 即時圖表與 Open Graph 圖片 (
src/core/og.tsx&src/core/route/og.ts):- 若要繪製該指標的歷史圖表,新增對應的 Chart 元件與 OG 端點。
- SpaceAPI 格式相容 (
src/core/format.ts):- 若該指標屬於 SpaceAPI 規範支援項目,在轉換器中加入映射。
- 前端儀表板 (
src/core/frontend/main.tsx):- 若網頁前端 Dashboard 需要展示,加入對應的 Card 卡片與數值渲染。