DEV Community: Let's Write

OpenClaw：安裝教學，在 macOS 用虛擬機 (Ubuntu) 安全部署龍蝦 AI

Let's Write — Tue, 03 Mar 2026 12:39:26 +0000

OpenClaw：安裝教學，在 macOS 用虛擬機 (Ubuntu) 安全部署龍蝦 AI

本篇要解決的問題

自從 OpenClaw 橫空出世後，三不五時就會看到相關的文章和影音介紹，看起來是個跨時代的產物。不過伴隨而來的，也有不少資安方面的疑慮。

相信很多人都想試試龍蝦的威力，但說實話，安裝起來沒那麼簡單。

本篇主要筆記怎麼安裝 OpenClaw。為了安全考量，選擇先在本機架設虛擬機，再於虛擬機上安裝 OpenClaw。這樣萬一出事了，大不了直接把虛擬機砍掉就好。

本篇注意事項：

本篇安裝 OpenClaw 時，官方的版本是 2026.3.2。官方更新速度很快，也許會遇到不同的安裝設定，如果遇到有疑問或不知道是什麼的狀況，建議詢問 AI。
本篇是使用 macOS，虛擬機是使用 Ubuntu-24.04.4。

以下將 OpenClaw 簡稱龍蝦。

安裝虛擬機

下載並安裝 VirtualBuddy：https://github.com/insidegui/VirtualBuddy/releases。

安裝完 VirtualBuddy 後，打開來，選擇 Linux > 左下角的 Custom Link。

輸入：

https://cdimage.ubuntu.com/releases/24.04.4/release/ubuntu-24.04.4-live-server-arm64.iso

或者手動下載 iso：https://cdimage.ubuntu.com/releases/24.04.4/release/

點擊「64-bit ARM (ARMv8/AArch64) server install image」。

在 VirtualBuddy 的介面，選擇 Linux > 左下角的 Custom File，選擇剛剛下載的檔案。

安裝的設定可以如下：

Virtual CPUs：3 或 4
Memory：4
Display Width / Height：都拉到最小值

安裝時，遇到「Install OpenSSH server」，記得這選項要打勾。

安裝完並重開機後，建議後續改用 Mac 的終端機 ssh 的方式來操作。

比方登入後，會看到這段訊息：

我們只需要在終端機上輸入：

ssh [你的帳號]@192.168.64.13
範例：
ssh letswrite@192.168.64.13

接著輸入帳號，就可以遠端登入了。

安裝 Node.js

本篇透過 npm 來安裝 OpenClaw，因此需要先安裝 Node.js。

下載並執行 NVM 安裝腳本

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

更新環境設定

source ~/.bashrc

# 如果是用 Zsh
source ~/.zshrc

安裝 Node.js（npm 會一併安裝）

nvm install --lts

取得 Telegram Bot Token

龍蝦可以在多個平台使用，在看了幾個官方的 Releases，會發現每次更版都有針對 Telegram 的部分，看起來對 Telegram 的支援度較高，因此本篇使用 Telegram。

註冊了 Telegram 會員後，登入，我們要先建立一個機器人用的帳號。

Telegram 上要新增一個機器人很容易，一樣跟機器人對話就可以建立。

點擊這個網址加入 BotFather 為好友：https://telegram.me/BotFather。

接著對話框中傳送這個給 BotFather：

/newbot

再按照 BotFather 需要我們回應的訊息，一步步回應後，就可以得到 Telegram Bot 的 Token，如下圖：

這個 Token 要存下來，之後安裝龍蝦時，就可以在安裝過程中直接輸入。

安裝 OpenClaw：正常版

以下是平常有扶老婆婆過馬路，有積功德，可以一路順順走下去的 Happy Path 版本。

輸入指令：

npm i -g openclaw

安裝完後，接著輸入以下指令，開始進行設定：

openclaw onboard

Onboarding mode

直接使用 QuickStart。

Model/auth provider

根據網路上看到的災情 +
August 本人的 Google Antigravity 被封殺過的人體實驗證明 +
各家 API 的花費如果要到 Pro 等級的很燒 $$ 經驗……

那個，對，August 曾經選擇 Gemini Pro 3 的 API，安裝個 gog 跟一些 skills 就燒掉了 3 美金，所以除非口袋很深，不然不建議用 API 的方式。

建議二種：

ChatGPT 是 Plus 以上方案的，就選 OpenAI 的 OpenAI Codex (ChatGPT OAuth)。
如果有訂閱 GitHub Copilot，就選 Copilot 的 GitHub Copilot (GitHub device login)。

如果是選 OpenAI Codex，選了以後，就會看到一個網址，貼到瀏覽器上後，執行登入，接著會看到「無法連上這個網站」的畫面，莫驚慌莫害怕，我們只要把登入結果的 URL 回貼到終端機上就可以了。

如果是選 GitHub Copilot，選了以後，會看到一個網址，用 GitHub 帳號授權登入後，填寫介面提供的代碼，就完成了。

其他使用模型的方式 August 沒試過，大家可以抱著探索自己口袋深度的心態勇敢按下去。

Select channel

選擇 Telegram (Bot API)，再選 Enter Telegram bot token。

然後把我們在前一段從 Telegram 上取得的 Token 貼上去，就可以了。

接著會問要不要安裝 skill，在這邊可裝可不裝，看個人需求，這個階段跳過也無所謂，後續再跟 Agent 說要裝 XX skill 就行。

下一步會看到問要不要再輸入「GOOGLE_PLACES_API_KEY」、「GEMINI_API_KEY」、「OPENAI_API_KEY」、「ELEVENLABS_API_KEY」，可以都選「No」，因為凡是 Key、Token……都是要發動魔法小卡的。

「NOTION_API_KEY」，如果想讓 Agent 控制 Notion，可以填，在 Notion 的 integrations 頁面上可以取得 Key。

Enable hooks

這一步一開始沒看懂，問了 Gemini 後才懂意思，如下：

boot-md：當系統（Gateway）啟動時，會自動讀取並執行工作區中的 BOOT.md 檔案。這適合用來初始化環境變數或設定當次啟動的特殊邏輯。
bootstrap-extra-files：允許系統在啟動時載入額外的設定檔案（如 USER.md 或 SOUL.md）。這對於維持 AI 對你（使用者）的身份認知非常重要。
command-logger：（推薦勾選）將你下達的所有指令記錄到審計日誌（Audit log）中。重視 ISO 27001 與安全稽核的作業習慣。
session-memory：（核心功能）當執行 /new 或 /reset 指令開新對話時，會自動將之前的上下文（Context）存入記憶。這能確保 AI 即使重啟對話，也能維持開發進度的連續性。

勾不勾選就看個人需求，後續也都可以再更改。

最後，就安裝成功了，之後只要在 Telegram 建的機器人上隨便傳一句訊息，就會收到要配對的指令：

把最後一行的指令在終端機上執行，會看到收到以下的回傳訊息：

Approved telegram sender xxxxxxxxxx.

代表配對完成，可以在 Telegram Bot 上使用 OpenClaw 了。

安裝 OpenClaw：遇到神奇錯誤版

過年前 August 安裝龍蝦，都是上一段的正常版本。

但遇到 Google Antigravity 用到被停權，前幾天帳號終於解封後，再安裝時就出現了錯誤。

如果進行到最後一步，看到以下錯誤，就代表恭喜你，要走這段的版本：

Error: systemctl is-enabled unavailable: Command failed: systemctl --user is-enabled openclaw-gateway.service

解決方式如下，就照著一步步輸入指令就可以，以下都是來自於 Claude 提供的解方。

第一步：前置準備（安裝前先做）

sudo loginctl enable-linger $USER
echo 'export XDG_RUNTIME_DIR=/run/user/$(id -u)' >> ~/.bashrc
echo 'export DBUS_SESSION_BUS_ADDRESS=unix:path=${XDG_RUNTIME_DIR}/bus' >> ~/.bashrc
source ~/.bashrc

第二步：正常安裝 OpenClaw

openclaw onboard

遇到 systemctl 相關錯誤直接忽略，繼續完成設定。

第三步：手動建立 Gateway Service

安裝完成後執（一次性的複製貼上即可）：

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/openclaw-gateway.service << EOF
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
Environment="PATH=$(dirname $(which openclaw)):/usr/local/bin:/usr/bin:/bin"
ExecStart=$(which openclaw) gateway run
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable openclaw-gateway
systemctl --user start openclaw-gateway

第四步：確認正常運作

systemctl --user status openclaw-gateway
systemctl --user is-enabled openclaw-gateway
openclaw status

is-enabled 應顯示 enabled。

openclaw status 裡 gateway 應顯示 reachable。

重新安裝 gateway

openclaw gateway install --force

接著重啟：

openclaw gateway restart

常用管理指令

systemctl --user stop openclaw-gateway      # 停止
systemctl --user restart openclaw-gateway   # 重啟
journalctl --user -u openclaw-gateway -f    # 即時 log

按照上面的步驟執行後，OpenClaw 就安裝成功了。

後續想要修改設定

比方在安裝時，選了使用 GitHub Copilot，之後如果想換用 Openai Codex，或是一些設定值想要修改，要怎麼做呢？

很簡單，執行以下命令：

openclaw config

修改完成後，要再重啟 gateway：

openclaw gateway restart

站內搜尋加上 AI：使用 Google Vertex AI Search（RAG）打造智慧問答型搜尋

Let's Write — Tue, 20 Jan 2026 14:40:02 +0000

本篇要解決的問題

之前就一直想試試看 RAG（Retrieval-Augmented Generation） 要怎麼應用在實際場景，但卡在自建 RAG 架構的門檻不低（像是要處理向量資料庫、轉檔、索引……bla bla bla），又想說成本會不會很高？直到這幾天發現了 Google 有 Vertex AI Search 這功能，讓 Gemini 判斷了一下可能成本，發現，意外的蠻便宜的耶，就決定來應用一下。

簡單說明 RAG（以下為 Gemini 提供）：

RAG 就像是為 AI 掛載了一份「即時參考資料」。它並非單一資料庫，而是包含三個核心動作，而 Vertex AI Search 已經把這些複雜的底層邏輯都封裝好了：

檢索（Retrieval）：當使用者問問題時，系統去你的網站（資料庫）找出最相關的幾段文字。
增強（Augmented）：把這些找出來的文字，連同原本的問題，一起塞進給 AI 的指令（Prompt）裡。
生成（Generation）：AI 閱讀了你給它的「臨時參考資料」，最後產出正確的回答。

因為本站重點都在實作，因此本篇的使用情境設定如下：

當網站內容累積到一定程度後，傳統的關鍵字搜尋往往無法精準回應使用者的需求。透過 Vertex AI Search，可以實作 RAG 架構，讓站內搜尋不只是「找關鍵字」，而是能「閱讀」我們的網站內容並整理出答案。

而在打不過 AI 就加入它的時代，我們可以達成：

自然語言提問：使用者問「怎麼實作 code review」，AI 能從多篇文章中彙整答案。
低開發成本：不需自行維護向量資料庫 (Vector DB) 或處理複雜的資料清洗。
高精準度：結合 Google 的語意搜尋與生成能力。

本篇實作成果，已經放上了首頁，以及每篇筆記文的文末，會看到一個「Vertex AI 搜尋」的輸入框，大家可以試一試喔，覺得好用或不好用，都歡迎留言。

建立 Google Vertex AI Search (RAG) 實作流程：資料匯入

首先，必須要有一個 Google Cloud 的帳號，有了帳號後新增專案，而這個專案必須是「付費帳戶」，就是要付 $$ 的。

有了一個付費帳戶的專案，接著開始以下幾個步驟。

進入 Vertex AI 後台：從 Google Cloud 控制台進入 Vertex AI 介面。

啟用 API：點擊「啟用所有建議的 API」以確保功能完整。

因為啟用不用 $$，之後有使用到才要，為了防止後續步驟陣亡的莫名其妙，這邊就給它全部打開。

選擇應用程式類型：點擊「運用 AI 模式打造站內搜尋服務」。

填寫應用程式資訊：輸入名稱並選取區域（建議選 global）。

建立資料儲存庫 (Data Store)：點擊建立按鈕。

選取資料來源：選擇「網站內容」。

因為本篇是應用在站內搜尋，因此是選「網站內容」，如果大家使用時目的不同，可以詢問 AI 用哪一個省成本。

指定索引路徑：輸入網址模式，如 www.letswrite.tw/*。

「自動檢索網址並持續更新」：建議打勾，之後網站有更新，Vertex 就會自動更新。

啟用強化功能：設定儲存庫名稱並建議勾選「文件處理設定」。

下面截圖中的選項要不要勾看網站的內容，一樣可以跟 AI 討論是否都勾。

選取計費模式：初期選擇「一般計費模式」。

連結 Data Store：勾選剛建好的儲存庫並點擊繼續。

監控進度：在資料頁面查看「正在建立初始索引」。

增加 Sitemap：手動新增 Sitemap 網址以確保文章完整收錄。

索引完成：當狀態顯示「初始索引建立完成」時，可以看到目前文件的總體積與數量（本站約 340 MB，共 696 份文件）。

將 Vertex AI Search 放上網站

調整回覆風格：在「設定」中將搜尋類型改為「搜尋答案」，並在操作說明加入「簡明扼要、不超過 100 字、繁體中文」等指令。

整合權限設定：選取「公開存取權」並填入允許的網域。

實作：iframe 與加到 WordPress

本站是用 WordPress 架站的，照著上圖直接照放程式碼，發現樣式會被影響，因此把 Vertex Search 的頁面做一個 HTML 檔案，然後在 WordPress 上嵌入。

iframe.html

我們將 Widget 放在新增的 HTML 檔案中，並處理 Shadow DOM 的 Enter 事件以動態撐開高度。

<!doctype html>
<html lang="zh-TW">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vertex AI Search - Let's Write</title>
    <style>
      body {
        margin: 0;
        padding: 0;
        width: 100%;
        font-family: sans-serif;
      }
      #searchWidgetTrigger {
        width: 100%;
        padding: 12px;
        box-sizing: border-box;
        border: 1px solid #ccc;
        border-radius: 8px;
        -webkit-appearance: none; /* 移除 iOS 預設樣式 */
      }
      gen-search-widget {
        display: block;
        margin-top: 10px;
      }
    </style>
  </head>
  <body>
    <input id="searchWidgetTrigger" inputmode="search" />

    <gen-search-widget
      configId="9a35bc9d-f398-4b2b-bfeb-28091c39e3f6"
      triggerId="searchWidgetTrigger"
      anchorsTarget="_blank"
      alwaysOpened
      placeholder="Vertex AI 搜尋"
    ></gen-search-widget>

    <script src="https://cloud.google.com/ai/gen-app-builder/client?hl=zh_TW"></script>

    <script>
      const widget = document.querySelector("gen-search-widget");
      const searchInput = document.getElementById("searchWidgetTrigger");
      let triggered = false;

      // 處理 Enter 按下時的邏輯
      const onEnterPressed = () => {
        // 防止重複觸發
        if (triggered) return;
        triggered = true;

        // 通知父頁面調整 iframe 高度
        window.parent.postMessage(
          { type: "setHeight", height: 500 },
          "https://www.letswrite.tw",
        );

        // 2 秒後重置觸發狀態，允許下次搜尋
        setTimeout(() => {
          triggered = false;
        }, 2000);
      };

      // 深度遍歷 shadow DOM，為所有 input 和 button 添加事件監聽
      const setupDeepListener = (root, depth = 0) => {
        // 防止無限遞迴
        if (depth > 5) return;

        const inputs = root.querySelectorAll("input");
        const buttons = root.querySelectorAll("button");

        // 為所有 input 元素添加事件監聽
        inputs.forEach((input) => {
          // 避免重複添加監聽器
          if (input.dataset.listenerAdded) return;
          input.dataset.listenerAdded = "true";

          // 桌機：Enter 鍵 (keyup)
          input.addEventListener("keyup", (e) => {
            if (e.key === "Enter" || e.keyCode === 13) {
              onEnterPressed();
            }
          });

          // 手機：Enter 鍵 (keypress)
          input.addEventListener("keypress", (e) => {
            if (e.key === "Enter" || e.keyCode === 13) {
              onEnterPressed();
            }
          });

          // 手機：輸入變化時觸發 (失焦或完成輸入)
          input.addEventListener("change", () => {
            setTimeout(onEnterPressed, 100);
          });
        });

        // 為所有 button 元素添加點擊監聽 (手機端主要觸發方式)
        buttons.forEach((button) => {
          if (button.dataset.listenerAdded) return;
          button.dataset.listenerAdded = "true";

          button.addEventListener("click", () => {
            onEnterPressed();
          });
        });

        // 遞迴檢查嵌套的 shadow DOM
        root.querySelectorAll("*").forEach((el) => {
          if (el.shadowRoot) {
            setupDeepListener(el.shadowRoot, depth + 1);
          }
        });
      };

      // 設置 shadow DOM 監聽器
      const setupShadowListener = () => {
        try {
          const shadow = widget.shadowRoot;
          if (!shadow) return false;

          // 初始化深度監聽
          setupDeepListener(shadow);

          // 使用 MutationObserver 監聽動態添加的元素
          const observer = new MutationObserver((mutations) => {
            mutations.forEach((mutation) => {
              mutation.addedNodes.forEach((node) => {
                if (node.nodeType === 1) {
                  // 如果新增節點有 shadow root，遞迴設置監聽
                  if (node.shadowRoot) {
                    setupDeepListener(node.shadowRoot);
                  }
                  // 如果新增 input 或 button，重新掃描整個 shadow DOM
                  if (node.tagName === "INPUT" || node.tagName === "BUTTON") {
                    setupDeepListener(shadow);
                  }
                }
              });
            });
          });

          observer.observe(shadow, {
            childList: true,
            subtree: true,
          });

          return true;
        } catch (e) {
          return false;
        }
      };

      // 等待 widget 定義並設置監聽
      customElements.whenDefined("gen-search-widget").then(() => {
        setTimeout(() => {
          // 每 500ms 嘗試設置監聽，直到成功
          const interval = setInterval(() => {
            if (setupShadowListener()) {
              clearInterval(interval);
            }
          }, 500);

          // 15 秒後停止嘗試
          setTimeout(() => clearInterval(interval), 15000);
        }, 1000);
      });

      // 外層 input 的 Enter 鍵監聽 (keyup)
      searchInput.addEventListener("keyup", (e) => {
        if (e.key === "Enter" || e.keyCode === 13) {
          onEnterPressed();
        }
      });

      // 外層 input 的 Enter 鍵監聽 (keypress)
      searchInput.addEventListener("keypress", (e) => {
        if (e.key === "Enter" || e.keyCode === 13) {
          onEnterPressed();
        }
      });

      // 監聽整個文檔的 Enter 鍵 (keyup,捕獲階段)
      document.addEventListener(
        "keyup",
        (e) => {
          if (
            e.target.tagName === "INPUT" &&
            (e.key === "Enter" || e.keyCode === 13)
          ) {
            onEnterPressed();
          }
        },
        true,
      );

      // 監聽整個文檔的 Enter 鍵 (keypress 捕獲階段)
      document.addEventListener(
        "keypress",
        (e) => {
          if (
            e.target.tagName === "INPUT" &&
            (e.key === "Enter" || e.keyCode === 13)
          ) {
            onEnterPressed();
          }
        },
        true,
      );

      // 監聽所有按鈕點擊 (捕獲階段 主要針對手機端)
      document.addEventListener(
        "click",
        (e) => {
          if (e.target.tagName === "BUTTON" || e.target.closest("button")) {
            setTimeout(onEnterPressed, 100);
          }
        },
        true,
      );
    </script>
  </body>
</html>

WordPress 裡嵌入 iframe 頁面

透過 WP Code 等插件，可以選擇在標題上方，或各文章頁底部自動插入 iframe。

以下是範例。

(function() {
    const target = document.querySelector('.bwp-section-header-separator');
    if (target && !document.getElementById('vertexIframe')) {
        const htmlString = `
            <div class="vertex-ai-container" style="width: 100%; margin: 20px 0;">
                <iframe id="vertexIframe" 
                        src="/iframe.html" 
                        style="width: 100%; border: none; overflow: hidden; transition: height 0.3s ease; height: 85px;" 
                        scrolling="no">
                </iframe>
            </div>`;
        target.insertAdjacentHTML('beforebegin', htmlString);
    }

    window.addEventListener('message', function(event) {
        // 建議加入來源網域檢查（因 iframe 同源可省略，但若跨網域則必須）
        // if (event.origin !== "https://YOUR_IFRAME_DOMAIN") return;
        if (event.data && event.data.type === 'setHeight') {
            const iframe = document.getElementById('vertexIframe');
            if (iframe) {
                iframe.style.height = (event.data.height + 10) + 'px';
            }
        }
    }, false);
})();

成本分析預估

基於目前的網站規模（約 700 份文件），August 預計在官網測試一個月多來評估，主要是成本考量。

以下是「Gemini 3 思考型」做的成本預估：

項目	估計單價 (USD)	說明
資料儲存 (Storage)	約 $1.00 / GB / 月	340 MB 體積產生的月費微乎其微。
企業版查詢 (Enterprise)	$4.00 / 1,000 次查詢	包含 RAG 生成式回答與語意搜尋。
Gemini 2.5 Flash Token	依流量計費	由於 Flash 價格極低，主要成本集中在查詢次數費。

如果每月有 1,000 次有效查詢，預估成本約為 $4 ~ $10 美金。

一個月 5 美金以下，就還可以接受，超過 5 美金……就要看本站能不能帶來一些收入了，不然一直造成支出也不是辦法。

CodiumAI PR-Agent，在 Gitea 上用 AI 來 Code Review

Let's Write — Sat, 10 Jan 2026 10:18:06 +0000

CodiumAI PR-Agent，在 Gitea 上用 AI 來 Code Review

本篇要解決的問題

之前有寫過一篇：〈使用 Gitea Actions 與 OpenAI 實現自動化 PR Code Review〉。

底下有人留言說，Gitea 還有其他 Code Review 的方式，研究了以後發現，哎哎哎，這不就是 CodiumAI 的 PR-Agent 嗎？之前寫過在 GitHub、GitLab 上使用的，沒想到 Gitea 也有：

再加上本篇，本站對於 CodiumAI PR-Agent Code Review 這塊就湊滿 Git 三神獸了，看能不能解開什麼封印之門（咦？）

CodiumAI PR-Agent 是一個開源的 AI 工具，能夠自動分析 Pull Request 的變更內容。

本篇將用 Docker 來部署並整合到用 Docker 自架的 Gitea，實現以下自動化流程：

自動審查：當開發者建立或更新 PR 時，自動觸發 AI 進行分析。
自動描述：AI 自動生成 PR 的摘要修改點，減少工程師撰寫文件的時間。
品質建議：提供程式碼改進建議、偵測潛在 Bug。
繁體中文友善：設定 AI 以繁體中文回應，好吸收好閱讀。

Docker 安裝 Gitea

架設 Gitea 伺服器，可以參考前一篇 Gitea 的文章，就邊就不重覆寫：

Docker 安裝 Gitea

本文假設我們已經有一個運行中的 Gitea，並且擁有管理員權限。

取得需要的 Token 與 Webhook Secret

在部署 CodiumAI PR-Agent 前，我們需要先準備好 Gitea 的 Token 與 OpenAI API Key。

取得 Gitea Personal Access Token

Token 是為了讓 PR-Agent 可以讀取專案，並進行留言。

登入 Gitea 伺服器。
點擊右上角頭像，進入「設定」。
選擇左側選單的「應用程式」。
在「管理存取權杖」區塊中，點擊「生成新權杖」。
填寫權杖名稱（例如：pr-agent）。
權限設定（重要）：請務必勾選以下權限：

issue：讀取和寫入
repository：讀取和寫入

點擊「產生 Token」並 立即複製（離開頁面後將無法再次查看）。

生成 Webhook Secret

為了確保安全性，我們需要設定一個 Secret 來驗證 Webhook 請求。

產生 Secret 的方式有二種。

在終端機使用 openssl 產生一組高強度的隨機字串：

openssl rand -base64 24

直接跟 AI 要一組，比方在 ChatGPT 或 Gemini 上，輸入：提供我一組 16 碼金鑰。

產生的 Secret 要記下來，之後會填到設定檔中。

準備 OpenAI API Key

前往 OpenAI Platform 建立一組 API Key。

建立 Key，必須要先存一筆金額才能使用。

這功能是要 $$ 的，記得選用 CP 高的模型，才不會幾次 Code Review 下來，荷包大失血。

Docker Compose 與環境變數設定

.env

建立一個專案用資料夾，取名「pr-agent-gitea」。

資料夾裡新增 .env 的檔案，把敏感的資料，如我們前二步取得的 Token，都寫進去，方便管理與保密。

複製貼上以下到 .env：

# ==================== Gitea 連線設定 ====================
# 若 Gitea 在另一台主機，請填寫該主機的固定 IP 或網域
GITEA_URL=http://192.168.xx.xx:3000
GITEA_TOKEN=在此貼上在 Gitea 取得的Token
GITEA_WEBHOOK_SECRET=在此貼上 Secret

# ==================== LLM 模型設定 ====================
OPENAI_KEY=在此貼上 Openai 的 Key

docker-compose.yml

專案裡新增一個 docker-compose.yml 檔，複製貼上以下內容：

services:
  pr-agent:
    image: codiumai/pr-agent:0.31-gitea_app
    container_name: pr-agent
    restart: unless-stopped

    env_file:
      - .env

    environment:
      # ==================== Gitea 連線設定 ====================
      CONFIG__GIT_PROVIDER: "gitea"
      GITEA__URL: ${GITEA_URL}
      GITEA__PERSONAL_ACCESS_TOKEN: ${GITEA_TOKEN}
      GITEA__WEBHOOK_SECRET: ${GITEA_WEBHOOK_SECRET}
      GITEA__SKIP_SSL_VERIFICATION: "false"

      # ==================== OpenAI 模型設定 ====================
      CONFIG__MODEL: "gpt-4.1-mini"
      OPENAI__KEY: ${OPENAI_KEY}

      # ==================== PR 觸發設定 ====================
      # 設定自動執行的指令：描述 (/describe)、審查 (/review)、優化 (/improve)
      GITEA__PR_COMMANDS: '["/describe", "/review", "/improve"]'
      # 設定觸發動作：開啟 PR 或 同步更新代碼時
      GITEA__HANDLE_PR_ACTIONS: '["opened", "synchronize"]'

      # ==================== 語言與輸出設定 ====================
      CONFIG__RESPONSE_LANGUAGE: "zh-TW"
      CONFIG__PUBLISH_OUTPUT: "true"
      CONFIG__PUBLISH_OUTPUT_PROGRESS: "false"

      # ==================== 留言行為設定 ====================
      # 強制使用新留言模式 (false)，不覆蓋舊留言，保留審查歷史
      PR_DESCRIPTION__PERSISTENT_COMMENT: "false"
      PR_REVIEW__PERSISTENT_COMMENT: "false"
      # 關閉行內程式碼註解 (依喜好開啟)
      PR_REVIEW__INLINE_CODE_COMMENTS: "false"

      # ==================== 功能開關設定 ====================
      # 簡化輸出，關閉額外的分類標籤
      PR_DESCRIPTION__ENABLE_SEMANTIC_FILES_TYPES: "false"
      PR_REVIEW__ENABLE_REVIEW_LABELS_EFFORT: "false"
      PR_REVIEW__ENABLE_REVIEW_LABELS_SECURITY: "false"
      GITEA__PUBLISH_LABELS: "false"

      # ==================== 檔案忽略清單 (Cost Saving) ====================
      # 忽略鎖定檔、靜態資源等不需要分析的檔案，大幅節省 Token 費用
      CONFIG__IGNORE__GLOB: "['dist/**', 'build/**', 'out/**', '.next/**', 'coverage/**', 'node_modules/**', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', '*.md', '*.txt', '*.log', '*.min.js', '*.min.css', '*.map', '*.svg', '*.png', '*.jpg', '*.jpeg', '*.gif', '*.ico', '*.woff', '*.woff2', '*.ttf', '*.eot', '.env*', '.gitignore', '.eslintrc*', '.prettierrc*', 'tsconfig.json', 'jest.config.*', 'vite.config.*', 'webpack.config.*', '*.spec.ts', '*.spec.js', '*.test.ts', '*.test.js']"

    ports:
      - "3001:3000"

內容說明：

模型選擇 (CONFIG__MODEL)：使用 gpt-4.1-mini，這是 CP 值高的選擇。
語言設定 (CONFIG__RESPONSE_LANGUAGE)：指定 zh-TW，讓 AI 輸出時用正體中文。
忽略清單 (CONFIG__IGNORE__GLOB)：如果想省 $$，這點很重要！要排除 node_modules、圖片檔、lock 檔等，避免 AI 浪費 Token 去讀取這些非程式碼檔案。
ports：這邊指定 3001，主要是 Gitea 預設是 3000，如果 PR-Agent 一樣用 3000 會啟動失敗，因此改用 3001。

docker-compose.yml 檔完成後，專案內開啟終端機，執行：

docker-compose up -d

Container 上看到有 pr-agent，代表啟動成功。

實際執行 Code Review

設定 Gitea Repository Webhook

最後一步，我們要告訴 Gitea 當有 PR 發生時，要把資料送給誰。

進入要進行 Code Review 的專案，點擊「設定」 > 「Webhook」 > 「新增 Webhook」 > 「Gitea」。
Webhook 填寫以下資訊：

目標 URL：http://<我們的_PR_AGENT_IP>:3001/api/v1/gitea_webhooks
HTTP 方法：POST
POST Content Type：application/json
密鑰：填入 .env 中的 GITEA_WEBHOOK_SECRET。
觸發條件：選取「自訂事件」，建議勾選：
問題留言（Issue Comment）
合併請求（Pull Request）
合併請求留言（Pull Request Comment）
合併請求同步（Pull Request Synchronize）

點擊「新增 Webhook」。

驗證成果

我們可以建一個小專案，故意寫錯出幾個 bug，然後發一個 Pull Request。

等待約 10~30 秒，我們會看到：

AI 自動留言 (Describe)：AI 會摘要這個 PR 做了什麼改動。
AI 自動審查 (Review)：AI 會列出「主要變更」、「潛在問題」以及「改進建議」。

進階：手動觸發指令

除了 PR 時自動觸發，我也可以在 PR 的留言區輸入指令與 AI 互動：

/describe：重新生成 PR 描述。
/review：重新執行程式碼審查。
/ask "這段改動有 SQL Injection 風險嗎？"：針對特定問題詢問 AI。

總結

透過 PR-Agent 與 Gitea 的整合，我們可以用極低的成本搭建 Code Review 功能。

雖然 AI 無法 100% 取代人工，但它能幫忙過濾低級錯誤、自動撰寫文件，讓攻城獅能將精力集中在怎麼攻城（欸這什麼結論）。

在本機安裝 Mattermost：打造自主控制的團隊通訊平台

Let's Write — Wed, 10 Dec 2025 12:19:20 +0000

本篇要解決的問題

工作上，各家公司用的通訊軟體，常聽到的是以下三種：LINE、Teams、Slack。

如果稍微比較一下，用起來的經驗如下（以下為 August 個人體感，不代表本台立場 XD）：

LINE、Telegram：適合閒聊

這兩個工具雖然方便，尤其台灣人幾乎都有 LINE，但主要設計給日常聊天使用。

面對工程團隊需要更結構化的溝通方式時，比如：頻道分類、討論串、檔案管理、發送程式碼……等功能就不太行。

還容易讓生活 + 工作的訊息都摻在一起作灑尿牛丸，重要資訊很容易被淹沒。

Slack、Teams：貴

Slack 夠強大，也是專門針對開發團隊用，但免費版只能保留最近 90 天的訊息記錄，而且發送訊息的數量每個月有上限，想要完整保存對話歷史就必須付費。

對小團隊或個人專案來說，魔法小卡沒辦法說發動就發動。

Microsoft Teams 需要企業或教育機構的授權才能充分使用，個人或小團隊要獨立使用並不方便，比如想要用 Webhook，家庭方案還無法使用。

Discord：資料及傳檔限制

雖然 Discord 免費且功能豐富，但所有資料都存放在 Discord 的伺服器上，對於重視資料隱私或需要完全掌控資料的人來說，這是一個重要的考量點。

傳檔案時，如果是免費方案有 10 MB 的限制，想傳大一點的檔案就會被擋下來。

因為使用上述幾個通訊軟體的體感，在詢問了 Gemini 3 Pro 有沒有更適合的工具後，才知道了今天要筆記的這個 Mattermost。

Mattermost 優勢

開源，可以完全安裝在自己的電腦或伺服器上。
類似 Slack 的使用方式，支援頻道分類、討論串、檔案分享等功能，還能透過外掛擴充更多能力。
可以整合 Webhook、機器人帳號。
所有資料都在本地，不用擔心第三方服務終止或資料外洩的問題。

本機安裝 Mattermost

事前準備

在開始之前，請確認電腦已經安裝：

Docker Desktop（包含 Docker Compose）
一個行動硬碟（選用，用來存放圖片和檔案）

Docker Compose 設定檔

建立一個工作目錄，在裡面新增 docker-compose.yml 檔案。

可以直接複製貼上以下：

services:
  db:
    image: postgres:16-alpine
    restart: "no"
    volumes:
      - ./volumes/db:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=mattermost
      - POSTGRES_USER=mmuser
      - POSTGRES_PASSWORD=mmuser_password

  mattermost:
    depends_on:
      - db
    image: mattermost/mattermost-team-edition:latest
    restart: "no"
    security_opt:
      - no-new-privileges:true
    pids_limit: 200
    volumes:
      - ./volumes/config:/mattermost/config:rw
      - ./volumes/logs:/mattermost/logs:rw
      - ./volumes/plugins:/mattermost/plugins:rw
      - ./volumes/client/plugins:/mattermost/client/plugins:rw
      - /Volumes/backup/mattermost_data:/mattermost/data:rw
      - /etc/localtime:/etc/localtime:ro
    environment:
      - MM_SQLSETTINGS_DRIVERNAME=postgres
      - MM_SQLSETTINGS_DATASOURCE=postgres://mmuser:mmuser_password@db:5432/mattermost?sslmode=disable&connect_timeout=10
      - MM_SERVICESETTINGS_SITEURL=http://localhost:8065
      - MM_PLUGINSETTINGS_ENABLEUPLOADS=true
      - MM_PLUGINSETTINGS_ENABLEMARKETPLACE=true
      - MM_SERVICESETTINGS_ALLOWCORSFROM=*
      - MM_WEBSERVER_WEBSOCKETSECUREPORT=8065
      - MM_SERVICESETTINGS_ENABLEINSECUREOUTGOINGCONNECTIONS=true
      - MM_EMAILSETTINGS_SENDPUSHNOTIFICATIONS=true
      - MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER=https://push-test.mattermost.com
      - MM_EMAILSETTINGS_PUSHNOTIFICATIONCONTENTS=full
      - MM_LOGSETTINGS_FILEMAXAGEDAYS=30
      - MM_LOGSETTINGS_FILECOMPRESS=true

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "5"

    ports:
      - "8065:8065"

以下逐段說明設定內容：

資料庫服務

db:
  image: postgres:16-alpine
  restart: "no"
  volumes:
    - ./volumes/db:/var/lib/postgresql/data
  environment:
    - POSTGRES_DB=mattermost
    - POSTGRES_USER=mmuser
    - POSTGRES_PASSWORD=mmuser_password

這段設定建立了 PostgreSQL 16 資料庫容器。使用輕量的 Alpine Linux 版本可以減少映像檔大小。

restart: "no" 表示電腦重開機後不會自動啟動，需要手動執行啟動指令，主要是避免重新開機時，行動硬碟沒有插在主機上。

資料庫檔案存放在 ./volumes/db 目錄，這樣即使容器被刪除，資料也不會遺失。

環境變數設定了資料庫名稱、使用者名稱和密碼，這些資訊稍後會被 Mattermost 用來連線。

Mattermost 服務

mattermost:
  depends_on:
    - db
  image: mattermost/mattermost-team-edition:latest
  restart: "no"
  security_opt:
    - no-new-privileges:true
  pids_limit: 200

Mattermost 服務依賴資料庫，Docker 會確保資料庫先啟動。

使用 Team Edition 免費版本，已經足夠小型團隊使用。

security_opt 和 pids_limit 是安全性設定，限制容器的權限提升和程序數量。

儲存策略

volumes:
  - ./volumes/config:/mattermost/config:rw
  - ./volumes/logs:/mattermost/logs:rw
  - ./volumes/plugins:/mattermost/plugins:rw
  - ./volumes/client/plugins:/mattermost/client/plugins:rw
  - /Volumes/backup/mattermost_data:/mattermost/data:rw
  - /etc/localtime:/etc/localtime:ro

這裡採用混合儲存策略，解決 Mattermost 不刪檔特性帶來的空間問題：

存放在本機的檔案

設定檔（config）、日誌（logs）、外掛（plugins）都存在本機的 ./volumes/ 目錄。這些檔案體積小且需要頻繁讀取，放在 Volume 可以確保系統反應速度，避免操作介面卡頓。

存放在行動硬碟的靜態資源

圖片和檔案（data）存在行動硬碟的 /Volumes/backup/mattermost_data 路徑。這是整個設定的關鍵考量點：Mattermost 預設不會刪除任何上傳的檔案，即使訊息被刪除，檔案依然保留在伺服器上。

隨著時間累積，照片、文件、影片……會越來越多，如果全部存在本機，很快就會面臨空間不足的問題。

將這些靜態資源檔案改存到行動硬碟，既能完整保留所有歷史檔案，又不會壓縮主機空間。

請記得修改硬碟路徑：將 /Volumes/backup 改成行動硬碟在 Mac 上的實際掛載位置。

在 Finder 中打開「前往」→「電腦」就能看到硬碟名稱。如果你的行動硬碟名稱是「My Passport」，路徑就是 /Volumes/My Passport/mattermost_data。

最後一行掛載系統時間檔案，確保容器內的時間與主機同步。

資料庫連線設定

environment:
  - MM_SQLSETTINGS_DRIVERNAME=postgres
  - MM_SQLSETTINGS_DATASOURCE=postgres://mmuser:mmuser_password@db:5432/mattermost?sslmode=disable&connect_timeout=10

指定使用 PostgreSQL 資料庫，連線字串包含使用者名稱、密碼、主機名稱（db 就是前面定義的資料庫服務名稱）、Port 和資料庫名稱。在區域網路環境下，為了簡化設定，這裡停用了 SSL 加密。

網站網址設定

- MM_SERVICESETTINGS_SITEURL=http://localhost:8065

這是 Mattermost 對外的網址。如果你只在本機使用，就維持 http://localhost:8065。

如果要讓區域網路內其他裝置存取，可以設定為你電腦的區域網路 IP，例如 http://192.168.1.100:8065。

如果想用 Cloudflare Tunnel 進行內網穿透，可以設定為對外的網址，例如 https://mattermost.yourdomain.com。

外掛市集功能

- MM_PLUGINSETTINGS_ENABLEUPLOADS=true
- MM_PLUGINSETTINGS_ENABLEMARKETPLACE=true

開啟外掛上傳和市集功能，這樣才能安裝 Boards、Todo 等擴充功能。

預設情況下這些功能可能被關閉，需要明確啟用。

WebSocket 連線設定

- MM_SERVICESETTINGS_ALLOWCORSFROM=*
- MM_WEBSERVER_WEBSOCKETSECUREPORT=8065
- MM_SERVICESETTINGS_ENABLEINSECUREOUTGOINGCONNECTIONS=true

WebSocket 是實現即時訊息的關鍵技術，而且後續使用 Boards 看版功能時也需要。

ALLOWCORSFROM=* 允許所有來源的跨域請求，方便在不同裝置上存取。

ENABLEINSECUREOUTGOINGCONNECTIONS 允許 Mattermost 連接到沒有 HTTPS 的外部服務，這在測試環境中很實用。

推播通知設定

- MM_EMAILSETTINGS_SENDPUSHNOTIFICATIONS=true
- MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER=https://push-test.mattermost.com
- MM_EMAILSETTINGS_PUSHNOTIFICATIONCONTENTS=full

開啟推播通知功能，使用 Mattermost 官方提供的測試推播伺服器（TPNS）。這是免費服務，讓你的手機 App 能收到即時通知。

PUSHNOTIFICATIONCONTENTS=full 表示通知會顯示發訊者姓名和訊息內容；如果改成 generic 則只顯示「您有一則新訊息」。

日誌管理

- MM_LOGSETTINGS_FILEMAXAGEDAYS=30
- MM_LOGSETTINGS_FILECOMPRESS=true

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "5"

Mattermost 內部的日誌檔案會保留 30 天，超過後自動壓縮舊檔案。

Docker 容器輸出的日誌則限制每個檔案最大 10MB，最多保留 5 個檔案，避免日誌無限膨脹佔用硬碟空間。

對外 Port

ports:
  - "8065:8065"

將容器內的 8065 Port 對應到主機的 8065 Port。

啟動後可以透過 http://localhost:8065 存取 Mattermost。

啟動服務

在 docker-compose.yml 所在目錄執行：

docker compose up -d

-d 參數表示在背景執行。第一次啟動會需要下載映像檔，可能需要幾分鐘時間。

啟動完成後，打開瀏覽器前往 http://localhost:8065，就會看到 Mattermost 的初始設定頁面。按照指示建立管理員帳號、設定團隊名稱，就能開始使用了。

停止服務

當不需要使用時，可以執行：

docker compose down

這會停止並移除容器，但所有資料都保留在 volumes 目錄中，下次啟動時會自動載入。

切換介面語言為繁體中文

預設安裝後，Mattermost 的介面是英文。如果想改成繁體中文，只需要簡單幾個步驟：

點擊畫面右上角的齒輪圖示（Settings）
在設定選單中找到「Display」（顯示設定）
往下捲動到底部，會看到「Language」（語言）選項
點擊「Edit」，從下拉選單中選擇「繁體中文（台灣）」
點擊「Save」儲存

介面會立即切換成繁體中文，所有選單、按鈕、提示訊息都會變成中文顯示。

安裝擴充功能

Mattermost 跟 LINE 很不同的地方，在於可以安裝另外的擴充功能。

以下介紹兩個實用的擴充功能。

Focalboard

Focalboard 是內建的看板工具，類似 Jira 或 Notion，可以用來管理專案任務、追蹤進度。

安裝步驟：

進到 Focalboard 的 GitHub Releases 頁面。
下載最新版本的檔案，因為 Docker 是 Linux，要選擇 mattermost-plugin-focalboard-vxxxx-linux-xxx.tar.gz 的檔案。
Mattermost 點擊左上角的 Mattermost Logo，選擇「System Console」（系統控制台）。
在左側選單找到「Plugins」（擴充程式）→「Plugin Management」（擴充程式管理）。
在上傳擴充程式中，點擊「選擇檔案」，接著選擇剛剛下載的檔案後，點擊「上傳」。
安裝完成後，左側選單會出現「Mattermost Boards」的選項，點擊進去，再啟用擴充程式功能。

使用 Boards：

回到主畫面，點擊左上角的 Mattermost Logo 會出現「Boards」圖示。點擊後可以建立新的看板。

選擇範本（如待辦清單、專案追蹤、內容行事曆等），或從空白看板開始。

看板支援卡片拖曳、自訂欄位、篩選排序等功能。

Todo

Todo 外掛可以讓你在對話中直接建立待辦事項，並在側邊欄追蹤所有未完成的任務。

安裝步驟：

安裝方式跟上面的 Boards 相同。

Todo 的 GitHub Releases。

使用 Todo：

在任何頻道或私訊中，右側會出現更多 Todo 的圖示（三個點 + 三條線）。

點擊後選擇「Add Todo」。

實用技巧：

你可以在任何頻道輸入 /todo add [任務內容] 快速建立待辦事項，不需要依附在特定訊息上。例如：

/todo add 下週一前完成專案提案

4 使用整合的機器人帳號

機器人帳號可以讓 Mattermost 與其他系統整合，執行像是自動化通知等的訊息發送。

建立機器人帳號

步驟：

進入「System Console」（系統控製台）→「Integrations」（整合）→「Bot Accounts」（機器人帳號）。
點擊「Add Bot Account」（新增機器人帳號）。
填寫機器人資訊：
- Username：例如 notification-bot
- Bot Icon：上傳機器人的頭像圖片（選用）
- Display Name：顯示名稱，例如「通知機器人」
- Description：說明這個機器人的用途
- Role：選擇「Member」即可
點擊「Create Bot Account」

建立完成後，頁面會顯示一個 Token（存取權杖）。請務必複製並妥善保存這個 Token，它只會顯示一次。如果遺失，需要重新產生新的 Token。

用 n8n 發送訊息

n8n 是一個開源的工作流程自動化工具，可以串接各種服務。

以下示範如何讓 n8n 透過機器人帳號發送訊息到 Mattermost。

前置作業：

首先需要在 Mattermost 建立一個接收訊息的頻道，例如「系統通知」。

在 n8n 中設定：

在 n8n 工作流程中新增「Mattermost」節點
建立 Credential（憑證）：
- Base URL：填入你的 Mattermost 網址，例如 http://localhost:8065。
- Access Token：貼上前面複製的機器人 Token。
設定要執行的動作：
- Operation：選擇「Post Message」。
- Channel ID：下拉式選單選取。
- Message：輸入要發送的訊息內容。

簡單的測試範例：

建立一個「Schedule Trigger」節點，設定每天早上 9 點執行，連接到 Mattermost 節點發送「早安！今天也要加油」的訊息。這樣就完成了一個簡單的每日問候機器人。

進階應用：

你可以組合更多節點，例如：

監控網站是否正常運作，異常時發送警告訊息
從 Google Sheets 讀取資料，定期發送報表摘要
串接 Webhook，當特定事件發生時自動通知團隊
整合 RSS 閱讀器，自動分享新文章到頻道

機器人帳號讓 Mattermost 不只是通訊軟體，還能執行自動化流程的訊息中心。

結語

透過 Docker Compose，我們可以在本機快速部署 Mattermost，擁有完整的團隊協作功能，同時保有資料的完全控制權。合理的儲存策略配置（本機設定、行動硬碟存檔）讓系統既快速又節省空間。

搭配 Boards 和 Todo 等外掛，以及機器人帳號的自動化整合，Mattermost 可以滿足從團隊溝通到專案管理的各種需求。

而且，以上這些功能都是免費且開源的，不用擔心訂閱費用或資料隱私問題。

最後，August 其實也還用不到一個月，但覺得好用，又能保有隱私，所以先寫了這篇筆記，紀錄一下安裝、使用的過程。

如果有更好的通訊軟體，歡迎留言提供。

使用 Gitea Actions 與 OpenAI 實現自動化 PR Code Review

Let's Write — Sun, 23 Nov 2025 04:24:05 +0000

本篇要解決的問題

在團隊協作開發中，Code Review 是確保程式碼品質的重要環節。

但很常要審核的人，自己也在趕案子，要落實很難，如果可以每次都自動由 AI 來審，至少可以讓開發工程師藉由 AI 回饋，來知道自己哪些部份需要注意。

之前有寫過 GitHub、GitLab 的版本：

但不是每間公司都會使用外部雲端服務，也有公司是自行架設 Git 服務。

自行架設 Git 服務時，一般會採用 GitLab 或 Gitea。

本筆記文將示範如何使用 Gitea Actions 搭配 OpenAI API，建立自動化的 PR Code Review 流程。當開發者提交 Pull Request 時，系統會自動：

分析 PR 中的程式碼變更
透過 OpenAI 識別潛在的錯誤、安全問題和可維護性問題
在 PR 中自動留言，提供詳細的改善建議
發送 Discord 通知（可選）

這套自動化流程能夠：

提早發現程式碼問題，減少 bug 進入主分支的機會
節省人工審查時間，讓團隊專注於更複雜的邏輯檢查
提供一致性的審查標準
幫助新手開發者學習最佳實踐

一、安裝 Gitea

準備 docker-compose.yml

建立一個專案目錄，並建立 docker-compose.yml 檔案：

services:
  server:
    image: gitea/gitea:latest
    container_name: gitea
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000

      # Database config
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=gitea123

      # Actions config
      - GITEA__actions__ENABLED=true
      - GITEA__actions__DEFAULT_ACTIONS_URL=https://github.com

    ports:
      - "8123:3000" # Web UI

    volumes:
      - ./gitea:/data

    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:15
    container_name: gitea-postgres
    restart: always
    environment:
      - POSTGRES_DB=gitea
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea123
    volumes:
      - ./postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gitea -d gitea"]
      interval: 10s
      timeout: 5s
      retries: 5

關鍵設定說明

在這個 docker-compose 設定中，我們已經透過環境變數啟用了 Gitea Actions 功能：

GITEA__actions__ENABLED=true：啟用 Actions 功能
GITEA__actions__DEFAULT_ACTIONS_URL=https://github.com：設定 Actions 的預設來源為 GitHub

這樣就不需要在 UI 介面另外設定，Gitea 啟動後即可直接使用 Actions 功能。

啟動 Gitea

在專案目錄下執行：

docker-compose up -d

等待容器啟動完成後，開啟瀏覽器訪問 http://192.168.xx.xxx:8123（請將 IP 改為我們的實際 IP 位址）。

完成 Gitea 的初始設定（建立管理員帳號等），即可開始使用。

二、安裝 Gitea Runner

取得 Runner Registration Token

首先需要從 Gitea 後台取得 Runner 的註冊 Token。

登入 Gitea 後，進入管理後台：

在「站點管理」→「Actions」→「Runner」頁面，點選「建立新的 Runner」或查看註冊 Token：

複製這個 Token，稍後會用到。

建立 Runner 的 docker-compose.yml

在另一個目錄，建立 Runner 的 docker-compose.yml：

services:
  runner:
    image: docker.io/gitea/act_runner:latest
    container_name: gitea-runner
    restart: always
    environment:
      GITEA_INSTANCE_URL: "http://192.168.68.61:8123"
      GITEA_RUNNER_REGISTRATION_TOKEN: "請替換為我們的 Token"
      GITEA_RUNNER_NAME: "code_review"

    volumes:
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock

重要提醒：

將 GITEA_INSTANCE_URL 中的 IP 改為我們的實際 IP
將 GITEA_RUNNER_REGISTRATION_TOKEN 替換為剛才複製的 Token

啟動 Runner

docker-compose up -d

確認 Runner 連線狀態

回到 Gitea 管理後台的 Runner 頁面，應該可以看到剛才啟動的 Runner 已經成功註冊並處於「閒置」狀態：

看到綠色的「閒置」狀態，表示 Runner 已經準備好接受任務。

三、建立測試專案

建立新專案並設定 Secrets

在 Gitea 上建立一個新的專案（或使用現有專案）：

進入專案後，前往「設定」→「Actions」→「Secrets」：

新增以下三個 Secrets：

OPENAIAPIKEY：我們的 OpenAI API Key

GITEATOKEN：Gitea 的 Access Token（用於自動留言）

在「設定」→「應用程式」→「管理存取令牌」中產生。

設定令牌權限時：

issue：讀取和寫入
repository：讀取

再把產生的 Token 存到 Secrets 裡。

DISCORDWEBHOOK：Discord Webhook URL（可選）

新增完後，Secrets 管理裡最多就會看到三組設定好的清單：

新增 Workflow 檔案

在要執行 Code Review 的專案根目錄建立 .gitea/workflows/ 目錄結構，並在其中新增 openai-pr-review.yml 檔案：

your-project/
├── .gitea/
│   └── workflows/
│       └── openai-pr-review.yml
└── (其他專案檔案)

openai-pr-review.yml 內容如下：

name: OpenAI PR Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  pr-review:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate PR diff
        run: |
          git fetch origin pull/${{ github.event.pull_request.number }}/head:pr_head
          git diff --diff-filter=AM origin/${{ github.event.pull_request.base.ref }}...pr_head > diff.txt
          echo "Diff generated."

      - name: Review PR with OpenAI and post results
        uses: actions/github-script@v7
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAIAPIKEY }}
          GITEA_TOKEN: ${{ secrets.GITEATOKEN }}
          DISCORD_WEBHOOK: ${{ secrets.DISCORDWEBHOOK }}
          SERVER_URL: ${{ github.server_url }}
          REPO: ${{ github.repository }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          PR_TITLE: ${{ github.event.pull_request.title }}
          PR_AUTHOR: ${{ github.event.pull_request.user.login }}
        with:
          script: |
            const fs = require("fs");

            const apiKey = process.env.OPENAI_API_KEY;
            const giteaToken = process.env.GITEA_TOKEN;
            const discordWebhook = process.env.DISCORD_WEBHOOK;
            const serverUrl = process.env.SERVER_URL;
            const repo = process.env.REPO;
            const prNumber = process.env.PR_NUMBER;
            const prTitle = process.env.PR_TITLE;
            const prAuthor = process.env.PR_AUTHOR;

            if (!apiKey) {
              core.setFailed("缺少 OPENAI_API_KEY");
              return;
            }

            // 讀取 diff
            let diff = "";
            try {
              diff = fs.readFileSync("diff.txt", "utf8");
            } catch (e) {
              core.info("無法讀取 diff.txt");
              diff = "";
            }
            diff = diff.slice(0, 12000);

            if (!diff.trim()) {
              core.info("No diff to review.");
              return;
            }

            // 精簡版 system prompt
            const systemPrompt = [
              "你是專業 code reviewer，請根據 PR diff 找出『最重要的 5 項問題』，依優先順序：1. 錯誤 2. 資安 3. 可維護性。",
              "找不到重要問題時，只回覆：**No major issues found.**(Markdown)。",
              "",
              "# Findings Summary (Top 5)",
              "請產生一份 Markdown 表格：",
              "| # | 分類 | 問題摘要 | Risk | 建議摘要 |",
              "|---|------|----------|------|-----------|",
              "Risk = High / Medium / Low。",
              "",
              "# Detailed Review",
              "依序對每項輸出：",
              "## 問題 X(分類)",
              "### 問題摘要",
              "- 1~2 句說明",
              "### Risk Score",
              "- High / Medium / Low",
              "### 為何重要",
              "- 說明風險與影響",
              "### 改善建議",
              "若有程式碼，請提供『原始程式碼』與『建議後程式碼』兩段 Markdown 程式碼區塊，使用 diff 語法。",
              "若無程式碼,提供可執行條列建議。",
              "",
              "請：",
              "- 只輸出最重要的五項(不足五項則寫實際數量)",
              "- 嚴格使用 Markdown",
              "- 不要產生前言、後記、寒暄或多餘敘述",
              "- 回覆簡潔、可採取行動"
            ].join("\n");

            const payload = {
              model: "gpt-5-nano",
              reasoning_effort: "low",
              messages: [
                {
                  role: "system",
                  content: systemPrompt
                },
                {
                  role: "user",
                  content: `請 review 以下 PR diff：\n\n${diff}`
                }
              ]
            };

            core.info("Calling OpenAI...");

            const openaiRes = await fetch("https://api.openai.com/v1/chat/completions", {
              method: "POST",
              headers: {
                "Authorization": `Bearer ${apiKey}`,
                "Content-Type": "application/json"
              },
              body: JSON.stringify(payload)
            });

            if (!openaiRes.ok) {
              const text = await openaiRes.text();
              core.setFailed(`OpenAI API Error: ${openaiRes.status} ${text}`);
              return;
            }

            const data = await openaiRes.json();
            const reviewContent =
              data.choices?.[0]?.message?.content?.trim() || "無法取得回應";

            core.info("OpenAI review completed.");
            core.info("Preview (first 200 chars):");
            core.info(reviewContent.slice(0, 200));

            // ===== 把結果貼到 Gitea PR comment =====
            if (giteaToken && serverUrl && repo && prNumber) {
              const apiUrl = `${serverUrl}/api/v1/repos/${repo}/issues/${prNumber}/comments`;
              const body = {
                body: `### 🤖 OpenAI Code Review\n\n${reviewContent}`
              };

              core.info(`Posting review comment to: ${apiUrl}`);

              const res = await fetch(apiUrl, {
                method: "POST",
                headers: {
                  "Authorization": `token ${giteaToken}`,
                  "Content-Type": "application/json"
                },
                body: JSON.stringify(body)
              });

              if (!res.ok) {
                const text = await res.text();
                core.setFailed(`Failed to post comment: ${res.status} ${text}`);
                return;
              } else {
                core.info("Comment posted successfully.");
              }
            } else {
              core.info("GITEA_TOKEN / SERVER_URL / REPO / PR_NUMBER 不完整，略過貼 PR comment。");
            }

            // ===== 發 Discord 通知 =====
            if (discordWebhook) {
              const message =
                `🤖 **Code Review 完成**\n\n` +
                `OpenAI 已完成程式碼審查，請前往查看建議。\n\n` +
                `標題：${prTitle}\n` +
                `作者：${prAuthor}\n` +
                `連結：${serverUrl}/${repo}/pulls/${prNumber}`;

              const discordRes = await fetch(discordWebhook, {
                method: "POST",
                headers: {
                  "Content-Type": "application/json"
                },
                body: JSON.stringify({ content: message })
              });

              if (!discordRes.ok) {
                const text = await discordRes.text();
                core.setFailed(`Failed to send Discord notification: ${discordRes.status} ${text}`);
              } else {
                core.info("Discord notification sent.");
              }
            } else {
              core.info("No DISCORD_WEBHOOK provided, skip Discord notification.");
            }

將此 workflow 檔案 commit 到主分支（main 或 master）。

新增分支

建立一個新的開發分支來進行測試，可以用介面操作，也可以下指令：

git checkout -b feature/test-review

建立測試用 JS 檔

在專案根目錄建立 index.js，並故意寫入一些常見的錯誤：

// 測試用程式碼 - 包含一些常見問題
function calculateTotal(price, quantity) {
  // 問題 1：缺少參數驗證
  var total = price * quantity;

  // 問題 2：使用 var 而非 let/const
  var discount = 0.1;

  // 問題 3：可能的精度問題
  return total - total * discount;
}

// 問題 4：未處理的 Promise
fetch("https://api.example.com/data").then((response) => response.json());

// 問題 5：使用 == 而非 ===
if (calculateTotal(100, 2) == 180) {
  console.log("計算正確");
}

這個範例包含了多個常見問題，OpenAI 應該能夠識別並提供改善建議。

Commit 並建立 Pull Request

將變更 commit 並推送到遠端，可以用介面操作，也可以下指令：

git add index.js
git commit -m "Add test file for code review"
git push origin feature/test-review

回到 Gitea 介面，建立一個從 feature/test-review 到 main 的 Pull Request：

填寫 PR 標題和描述後，點選「建立合併請求」：

在 Gitea 上查看結果

PR 建立後，Gitea Actions 會自動觸發。我們可以在以下位置查看執行狀態：

1. Actions 執行狀態

在 PR 頁面下方可以看到 Actions 的執行狀態：

點選可以查看詳細的執行 log：

第一次執行會比較久，後續再執行就會比較快。

2. OpenAI 的 Review 結果

當 Actions 執行完成後，OpenAI 會在 PR 中自動留言，提供詳細的程式碼審查報告：

Review 報告會包含：

Findings Summary 表格：列出前 5 大問題的摘要。
Detailed Review：每個問題的詳細說明，包括風險評估和改善建議。
程式碼範例：使用 diff 格式展示建議的修改。

3. Discord 通知（若有設定）

如果有設定 Discord Webhook，團隊成員也會在 Discord 頻道收到通知：

結語

透過這套自動化流程，我們可以在每次 Pull Request 時獲得即時的程式碼審查建議。

雖然 AI 無法完全取代人工審查，但它能有效地：

捕捉常見的程式碼問題和 anti-patterns。
提供一致性的審查標準。
節省人工審查的時間。
作為程式碼品質的第一道防線。

如果將 AI 審查作為輔助工具，在重要的 PR 中搭配人工審查，確保程式碼品質和業務邏輯的正確性。

圖片壓縮：用 Compressor.js 自動調整品質壓縮至指定大小

Let's Write — Sat, 04 Oct 2025 03:49:43 +0000

本篇要解決的問題

很多網站功能會需要處理使用者上傳的圖片，比方讓使用者上傳會員照片。

但隨著手機相機愈做愈好，拍出來的照片隨便都是幾 MB，直接上傳的話，耗時也佔空間。

雖然網路上搜尋有許多圖片壓縮工具，但大多只能設定固定的壓縮的品質，無法保證壓縮後的檔案大小符合需求。

本筆記文將使用 Compressor.js 套件，實作一個圖片壓縮功能，符合以下需求：

自動嘗試不同的壓縮品質，直到檔案小於指定大小（ex: 600KB）為止。
將圖片轉換為 WebP 格式。
長、寬限制最大尺寸。

這樣就可以確保壓縮後的圖片既符合檔案大小限制，又保有良好的質感。

核心概念：遞迴壓縮

一般網路上的圖片壓縮只能一次性設定品質參數，本篇用了 comporess.js 後，採用 遞迴嘗試 的方式，執行方式如下：

從最高品質(quality = 1.0)開始壓縮。
檢查壓縮後的檔案大小。
如果超過目標大小 600KB，則降低品質（減少 0.05）後重新壓縮。
重複步驟 2-3，直到檔案符合大小要求，或品質降到下限（0.40）。

這種方法能夠在保證檔案大小的前提下，盡可能保留圖片品質。

引入 Compressor.js

首先，我們需要引入 Compressor.js 這個圖片壓縮套件。

它可以在瀏覽器端直接處理圖片：無需後端支援:

<script src="https://cdn.jsdelivr.net/npm/compressorjs@1.2.1/dist/compressor.min.js"></script>

上面是直接引用 CDN 的方式，官方文件也有其他引用方式，可以自己的需求引用。

建立 HTML

我們需要一個檔案上傳的 file input，以及一個用來預覽壓縮結果的 div：

<input type="file" id="upload" accept="image/*" />
<img id="preview" style="max-width:300px" />

實作智慧壓縮函式

這是整個方案的核心函式，接受四個參數:

file：要壓縮的原始檔案。
targetSize：目標檔案大小，預設 600KB。
floor：品質下限，預設 0.40。
step：每次品質遞減幅度，預設 0.05。

function compressWithFloor(
  file,
  targetSize = 600 * 1024,
  floor = 0.4,
  step = 0.05
) {
  return new Promise((resolve, reject) => {
    let q = 1.0;

    const attempt = () => {
      new Compressor(file, {
        quality: q,
        mimeType: "image/webp", // 強制轉換為 WebP 格式
        maxWidth: 2560, // 最大寬度限制
        maxHeight: 1440, // 最大高度限制
        success(blob) {
          console.log(
            `q=${q.toFixed(2)}  size=${Math.round(blob.size / 1024)}KB`
          );
          if (blob.size > targetSize && q - step >= floor) {
            q = +(q - step).toFixed(2);
            attempt(); // 繼續壓縮
          } else {
            resolve(blob); // 符合大小或到達品質下限
          }
        },
        error(err) {
          reject(err);
        },
      });
    };

    attempt();
  });
}

參數說明

1. 強制輸出 WebP 格式

mimeType: 'image/webp' 會將所有圖片（包括 PNG、JPEG）都轉換為 WebP。

WebP 是 Google 開發的現代圖片格式。在相同品質下。檔案大小通常比 JPEG 小 25-35%。

2. 尺寸限制

maxWidth: 2560 和 maxHeight: 1440 確保圖片不會超過 2K 解析度。

如果原圖尺寸較小，不會被放大;

如果較大，會等比例縮小。

這對於手機拍攝的 4K、8K 照片特別有用。

3. 遞迴壓縮邏輯

if (blob.size > targetSize && q - step >= floor) {
  q = +(q - step).toFixed(2);
  attempt(); // 繼續壓縮
}

這段程式碼檢查兩個條件：

檔案是否仍大於目標大小？
品質是否還有下降空間？

只要 1、2 都符合，就會降低品質並重新嘗試壓縮。

Blob 轉 Base64 輔助函式

為了在瀏覽器中預覽和下載圖片，或是調用 API 傳到後端，我們需要將壓縮後的 Blob 物件轉換為 Base64 格式：

function blobToBase64(blob) {
  return new Promise((resolve) => {
    const r = new FileReader();
    r.onloadend = () => resolve(r.result);
    r.readAsDataURL(blob);
  });
}

整合上傳與下載功能

最後，我們監聽檔案上傳事件，執行壓縮流程，並自動觸發下載:

document.getElementById("upload").addEventListener("change", async (e) => {
  const file = e.target.files[0];
  if (!file) return;

  try {
    const compressed = await compressWithFloor(file, 600 * 1024, 0.4, 0.05);
    console.log("final size:", Math.round(compressed.size / 1024), "KB");

    const base64 = await blobToBase64(compressed);
    document.getElementById("preview").src = base64;

    // 取出原始檔名(去掉副檔名)
    const originalName = file.name.replace(/\.[^/.]+$/, "");
    const newFileName = `${originalName}-compress.webp`;

    // 建立下載連結並自動觸發
    const link = document.createElement("a");
    link.href = base64;
    link.download = newFileName;
    link.click();
  } catch (err) {
    console.error("壓縮失敗:", err);
  }
});

檔名處理邏輯

程式會自動處理檔名:

移除原始副檔名：file.name.replace(/\.[^/.]+$/, "")。
加上 -compress.webp 後綴。

例如：vacation.jpg → vacation-compress.webp。

壓縮流程示例

假設上傳一張 5MB 的照片，壓縮過程可能如下:

q=1.00  size=1200KB  → 超過 600KB，繼續
q=0.95  size=950KB   → 超過 600KB，繼續
q=0.90  size=750KB   → 超過 600KB，繼續
q=0.85  size=580KB   → 符合要求，完成！
final size: 580 KB

如果原圖品質很差，即使降到最低品質仍超過 600KB，程式也會在 q=0.40 時停止，避免過度壓縮導致圖片難以辨識。

完整程式碼

以下是完整的可執行範例：

<!DOCTYPE html>
<html lang="zh-TW">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Let's write - 圖片壓縮</title>
  </head>
  <body>
    <h1>Let's write - 圖片壓縮工具</h1>
    <p>筆記文：<a href="https://www.letswrite.tw/compressjs/" target="_blank"></a></p>
    <input type="file" id="upload" accept="image/*" />
    <img id="preview" style="max-width:300px; margin-top:20px;" />

    <script src="https://cdn.jsdelivr.net/npm/compressorjs@1.2.1/dist/compressor.min.js"></script>
    <script>
      function compressWithFloor(
        file,
        targetSize = 600 * 1024,
        floor = 0.4,
        step = 0.05
      ) {
        return new Promise((resolve, reject) => {
          let q = 1.0;

          const attempt = () => {
            new Compressor(file, {
              quality: q,
              mimeType: "image/webp",
              maxWidth: 2560,
              maxHeight: 1440,
              success(blob) {
                console.log(
                  `q=${q.toFixed(2)}  size=${Math.round(blob.size / 1024)}KB`
                );
                if (blob.size > targetSize && q - step >= floor) {
                  q = +(q - step).toFixed(2);
                  attempt();
                } else {
                  resolve(blob);
                }
              },
              error(err) {
                reject(err);
              },
            });
          };

          attempt();
        });
      }

      function blobToBase64(blob) {
        return new Promise((resolve) => {
          const r = new FileReader();
          r.onloadend = () => resolve(r.result);
          r.readAsDataURL(blob);
        });
      }

      // 依序嘗試 q=1.00, 0.95, 0.90, ... ，直到 <=600KB 或 q<0.40
    function compressWithFloor(
      file,
      targetSize = 600 * 1024,
      floor = 0.4,
      step = 0.05,
    ) {
      return new Promise((resolve, reject) => {
        let q = 1.0;

        const attempt = () => {
          new Compressor(file, {
            quality: q,
            mimeType: "image/webp", // 強制轉 WebP
            maxWidth: 2560, // 最大寬度限制
            maxHeight: 1440, // 最大高度限制
            success(blob) {
              console.log(
                `q=${q.toFixed(2)}  size=${Math.round(blob.size / 1024)}KB`,
              );
              if (blob.size > targetSize && q - step >= floor) {
                q = +(q - step).toFixed(2);
                attempt(); // 繼續壓縮
              } else {
                resolve(blob); // 符合大小或到達品質下限
              }
            },
            error(err) {
              reject(err);
            },
          });
        };

        attempt();
      });
    }

    // Blob -> base64
    function blobToBase64(blob) {
      return new Promise((resolve) => {
        const r = new FileReader();
        r.onloadend = () => resolve(r.result);
        r.readAsDataURL(blob);
      });
    }

    document.getElementById("upload").addEventListener("change", async (e) => {
      const file = e.target.files[0];
      if (!file) return;

      const targetSize = 600 * 1024;

      // 檢查原始檔案大小
      if (file.size <= targetSize) {
        console.log(
          `原始檔案大小 ${Math.round(file.size / 1024)}KB，已小於目標大小 ${Math.round(targetSize / 1024)}KB，不需壓縮`,
        );
        alert(`圖片大小已符合要求 (${Math.round(file.size / 1024)}KB)，無需壓縮`);

        // 仍然顯示預覽
        const base64 = await blobToBase64(file);
        document.getElementById("preview").src = base64;
        return;
      }

      try {
        const compressed = await compressWithFloor(file, targetSize, 0.4, 0.05);
        console.log("final size:", Math.round(compressed.size / 1024), "KB");
        const base64 = await blobToBase64(compressed);
        document.getElementById("preview").src = base64;
        const originalName = file.name.replace(/\.[^/.]+$/, "");
        const newFileName = `${originalName}-compress.webp`;
        const link = document.createElement("a");
        link.href = base64;
        link.download = newFileName;
        link.click();
      } catch (err) {
        console.error("壓縮失敗:", err);
      }
    });

    </script>
  </body>
</html>

Demo 與原始碼

想要實際體驗圖片壓縮工具的話，以下是完整的 Demo 頁面和原始碼供大家使用。

使用前，如果這個工具對你有幫助，歡迎到 GitHub 給我一顆星星 ⭐，你的小小動作，對本站都是大大的鼓勵。

Demo：Demo

GitHub 原始碼：GitHub Repository

使用 pm2.web 建立免費 PM2 監控系統

Let's Write — Fri, 26 Sep 2025 13:16:21 +0000

本篇要解決的問題

PM2 是 Node.js 裡常用的 process manager，一般如果是透過網頁監控、重啟，大概會使用官方的 Keymetrics。

但，But！就是這個 But！免費版最多只能監控 4 個 Process，再多就要掏出魔法小卡了。

問了 ChatGPT 後，發現有一個開源的替代方案：pm2.web，可以自己架設，不管幾個 process 都完全免費。

以下筆記如何使用 Vercel + MongoDB Atlas 部署 pm2.web，免費監控我們的 PM2。

架構概念

pm2.web 分成兩部分，如下。

Dashboard

Next.js 寫前端 + API。

本篇選擇放在 Vercel 執行。

Backend

官方文件裡叫 Backend，其實它就是跑在目標伺服器上的 Agent。

Agent 在我們要監控的伺服器上，透過 PM2 BUS API 讀取 process 狀態，再把資料寫到 MongoDB。

Dashboard 與 Backend 之間是透過 MongoDB Atlas 溝通，不需要開防火牆或暴露 192.168.* 內網。

步驟一：MongoDB Atlas 設定

前往 MongoDB Atlas 建一個免費 cluster。

複製連線字串，待會會用到：

在 Network Access 加上 0.0.0.0/0（因為 Vercel 是浮動 IP，否則無法連線）：

步驟二：Vercel 部署 Dashboard

點擊官方文件上的「Deploy」按鈕：

設定環境變數：

MONGODB_URI = 我們的 Atlas 連線字串
NEXTAUTH_SECRET = 自己生成的隨機字串（可用 openssl rand -base64 32，或直接開啟 https://generate-secret.vercel.app/32）

第一次部署後，一定會出現失敗，免緊張、免害怕，選單點擊 Settings → Build & Development Settings → Framework Preset，選 Next.js，之後再重新 Redeploy 一次，就 OK 了。

部署完成後，打開網址會進入註冊頁。

⚠️ 重要提醒：第一個註冊的帳號會自動成為 owner，之後就能在 UI 裡管理權限。

步驟三：安裝 Backend Agent

官方文件：pm2.web - Backend

假設內網伺服器 IP 是 192.168.1.2，進入主機後：

下載與安裝

git clone https://github.com/oxdev03/pm2.web.git
cd pm2.web

# 根目錄先安裝（避免 pm2 報錯）
npm install

# 進入 backend 目錄
cd apps/backend
npm install

# 複製環境變數範例
cp .env.example .env

設定環境變數

編輯 .env 檔：

MONGODB_URI=我們的 Atlas 連線字串

啟動 Agent

接著，終端機要回到專案的根目錄，不能停留在 backend 的資料夾中。

執行以下：

pm2 start npm --name "pm2.web" -- run "start:apps:backend"
pm2 save
pm2 startup  # 重開機後會自動啟動

接著瀏覽器打開 Vercel 提供的網址，就會看到 Dashboard 上出現資料了：

這樣 Backend 就會定期把 PM2 狀態推送到 Atlas，Dashboard 會自動讀取。

效果展示

在 Dashboard 上我們可以：

查看所有 process 的狀態（Running、CPU、Memory 使用率）
遠端重啟、停止 process
監控多台伺服器的 PM2 狀態

總結

照著本筆記文的方式依步驟執行後，我們就能用 Vercel + MongoDB Atlas + pm2.web，打造一個：

✅ 完全免費
✅ 介面美觀，有深色模式
✅ 可控管使用者權限
✅ 透過網站進行多機管理

的 PM2 監控系統，不用因為沒有魔法小卡，被 4 個 process 給限制。

參考資源

使用 Docker 搭配 Node.js 快速建置 Redis 快取系統

Let's Write — Tue, 10 Jun 2025 12:54:09 +0000

本篇要解決的問題

我們在開發時，常常會遇到這樣的情況：

同一個頁面一進來，取得的資料很多都是相同的，比如一個商品的基本資訊、公告訊息的內文。

而大部份資料是由前端調用 API，API 再去資料庫查詢資料，所以會明明資料都是相同的，但每次都要耗掉效能去運算，流量多了，會大量消耗資料庫資源，接著讓系統變慢，使用者等待時間變長。

Redis 的橫空出世，就可以解決這個問題。

Redis 是一個快取資料庫，它的工作就像是一個超快速的暫存櫃。

比方我們去買早餐，如果同一個三明治，早餐店店員都是客人來了才現包，那就要花很多時間準備，客人就要等很久，久了生意就會不好，生意不好就沒有酷 $$ 買烏薩奇寶寶娃娃。

Redis 快取就像是台子上先放好大家常買的三明治，客人來了就直接拿取然後結帳，不用一直等店員製作，速度快很多，這樣子 $$ 進來的也快。

情境換成網站上，Redis 就是把常用的資料放在記憶體裡，這樣 API 就能快速回應，加強使用者體驗。

本篇筆記文會示範如何用 Redis 來做快取機制，並用 Docker 簡單快速地部署 Redis 環境，搭配 Node.js 實作。

用 Docker 安裝 Redis

使用 Docker 來安裝 Redis，可以直接複製貼上以下的 docker-compose.yml。

以下 docker-compose.yml 的內容，會同時啟動兩個服務：

redis-server：Redis 伺服器。
redis-insight：Redis 官方提供的視覺化管理工具，方便查看和管理 Redis 資料。

version: "3.8"

services:
  redis:
    image: redis:8.0.2-alpine
    container_name: redis-server
    ports:
      - "6379:6379"
    command: >
      redis-server --maxmemory 2gb --maxmemory-policy allkeys-lru
    volumes:
      - ./data:/data
    restart: unless-stopped

  redisinsight:
    image: redis/redisinsight:latest
    container_name: redis-insight
    ports:
      - "5540:5540"
    depends_on:
      - redis
    restart: unless-stopped

volumes:
  redis-data:

重要說明

Redis 使用 redis:8.0.2-alpine 這個輕量級的映像檔，是這篇文章寫作時，截至 2025/6 為止的最新版本。

設定 --maxmemory 2gb，是限制 Redis 最多使用 2GB 記憶體，超過時用 allkeys-lru 策略自動淘汰最少使用的資料。避免塞太多資料讓記憶體先炸掉。

RedisInsight 會開在本機的 5540 PORT，可以用瀏覽器打開 http://localhost:5540 來管理 Redis。

啟動指令：

docker-compose up -d

這樣就會在背景啟動 Redis 服務和 RedisInsight。

Node.js 執行 Redis

在 Node.js 裡，我們用 ioredis 這個套件來連接 Redis，操作起來很簡單。

以下示範基本的快取讀寫範例，並附上幾個常用的 Redis 操作。

import Redis from "ioredis";

const redis = new Redis(); // 連到預設 localhost:6379

// 範例資料
const data = { message: "Hello August", time: Date.now() };

// 寫入快取，並設定 60 秒過期時間
await redis.set("api:result", JSON.stringify(data), "EX", 60);

// 讀取快取
const cache = await redis.get("api:result");
if (cache) {
  const parsed = JSON.parse(cache);
  console.log("讀到快取資料：", parsed);
} else {
  console.log("快取不存在或已過期");
}

// 常用 Redis 操作示範：

// 1. 設定鍵值並設定過期時間（EX: 秒，PX: 毫秒）
await redis.set("user:123", JSON.stringify({ name: "August" }), "EX", 120);

// 2. 取得鍵值
const userStr = await redis.get("user:123");

// 3. 刪除鍵
await redis.del("user:123");

// 4. 檢查鍵是否存在，回傳 1 或 0
const exists = await redis.exists("api:result");

// 5. 自增計數器
await redis.incr("page:view");

// 6. 取得自增後的值
const views = await redis.get("page:view");

console.log(`頁面瀏覽數：${views}`);

這些指令是常見的快取或計數器操作，可以依照需求再自行翻閱官方文件，~~或是問 ChatGPT~~。

用 RedisInsight 查看資料

RedisInsight 是 Redis 官方的 GUI 管理工具，在前述的 docker-copmose.yml 就一併安裝好了，在瀏覽器輸入以下網址就可以看到：

http://localhost:5540

連接預設的 Redis 伺服器（localhost:6379），就可以用圖形介面：

查詢所有快取鍵值
查看資料內容（支援 JSON、String、List、Set、Hash 等類型）
監控 Redis 記憶體使用狀況
設定過期時間與刪除資料

實作時，覺得有個介面看，比裝厲害下指令查要舒服多了。

用 Docker 快速架設 Node.js 靜態網站服務

Let's Write — Sat, 07 Jun 2025 02:34:35 +0000

本篇要解決什麼問題

對前端工程師來說，有時只是單純要一個靜態網站，讓主管或業者看到 Demo，卻因為後端、Nginx、Linux 等設定卡關半天。這時候，其實可以用 Node.js 搭配 Express，再加上 Docker，簡單幾個指令，就能快速建起一個 Demo 網站了。

使用 Node.js + Express 快速提供靜態檔案服務

本篇使用了以下技術與工具：

Node.js + Express：提供簡易的靜態檔服務。
Docker：容器化應用，讓執行環境一致、方便搬移與佈署。
docker-compose：簡化啟動流程與指令。

以下檔案，新增在我們想要架起 Demo 的專案資料夾中。

server.js

server.js 檔裡，主要是讓我們使用 Express 來讓 Node.js 能提供靜態檔案的服務，程式碼如下：

// server.js
const express = require("express");
const path = require("path");

const app = express();
const PORT = 3001; // PORT 要修改成自己需要的

// 提供靜態檔案（例如 index.html、images、js、css）
app.use(express.static(path.join(__dirname)));

app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});

這段程式會讓 Node.js 在本機的 3001 PORT 上開啟一個伺服器，並提供當前目錄底下的所有檔案給瀏覽器存取。

PORT 請自行修改想要的，這邊寫 3001 是要避開常用到的 3000。

package.json

server.js 裡有使用 express，因此 package.json 需要安裝。

如果專案裡本來就有 package.json，那就直接執行：

npm install express

如果還沒有 package.json，那就執行以下：

npm init -y
npm install express

docker-compose.yml

這是讓整個 Node.js 專案能在 Docker 裡運行的設定檔，使用官方 node image 搭配 volume 掛載當前資料夾，並自動執行 server：

version: "3.8"
services:
  web:
    image: node:23-alpine3.20
    ports:
      - "3001:3001"
    volumes:
      - .:/usr/src/app
    working_dir: /usr/src/app
    command: node server.js

這邊的 ports，要跟 server.js 裡寫得一樣。

.dockerignore

讓 Docker 避免將不必要的檔案打包進去，例如 .git、node_modules 等：

node_modules
npm-debug.log
Dockerfile
docker-compose.yml
.env

有了以上四個檔案，就可以準備用 Docker 架起 Demo 網站了。

四個檔案都在同一專案資料夾中。

啟動

本機必須要先安裝好 Docker：https://www.docker.com/products/docker-desktop/。

有了 Docker 後，在專案目錄下執行以下指令：

docker-compose up -d

接著打開瀏覽器，輸入 http://localhost:3001，就可以看到你的靜態網站內容了！

專案原始碼連結

本篇說明的檔案，有放在 GitHub 上，取用前請先點擊星星，你的小小動作，對本站都是大大的鼓勵：

https://github.com/letswritetw/letswrite-docker-node-static-site

如果你也常常需要快速測試一份靜態網頁，這個方法可以省下很多時間。

iPhone 的語音辨識功能：語音備忘錄，自動標點分段

Let's Write — Thu, 22 May 2025 11:51:00 +0000

本篇要解決的問題

之前寫過幾篇，是用 OpenAI 的 Whisper API 來語音辨識的功能，都是免費可以使用的：

前陣子驚為天人的發現，原來 iPhone 有這功能了，還會自動加上標點符號以及分段，辨識的速度也很快，看來語音轉文字的功能，市場的需求量很大呀。

語音備忘錄 App 的樣子：

硬體要求

iPhone

iPhone 12 以上。
iOS 18.0 或以上版本。
支援英文、西班牙文、葡萄牙文、義大利文、法文、德文、日文、韓文、繁體中文、簡體中文。

Mac

Mac 也可以，但要是 M 晶片的才行，作業系統是 macOS Sequoia 或以上版本。

使用 iPhone 語音轉文字

語音備忘錄裡的音檔，副檔名必須是「.m4a」。

如果直接在語音備忘錄裡點擊錄音，那就會是這個格式，如果是一般的音檔如 .mp3，就必須要進行轉檔，轉檔方式將在下一段說明，這段先寫怎麼用語音備忘錄來轉成文字。

在語音備忘錄裡點擊音檔後，會看到一個正常的播放器，接著點擊左下角一個很像聲紋的按鈕：

會看到音檔的聲紋，接著再點擊左下角有個「’’」的按鈕：

點擊後，就會進行辨識，會看到畫面上呈現「正在轉錄…」：

iPhone 的辨識速度很快，同樣一個音檔，竟然可以比 Faster Whisper 還快。

辨識完後，就會看到畫面上呈現辨識結果：

更讚的是，會還自動加上標點符，並將文字內容分段，這是 Whisper API 無法一次完成的功能。

想要複製辨識的文字很簡單，點擊右上角「…」符號，就會出現「拷貝逐字稿」的選項，點擊後就複製了：

音檔轉成 m4a

非 Mac

不是用 Mac 的朋友，直接搜尋「xx to m4a」，就會看到很多網站都有提供轉檔的服務。

比方搜尋「mp3 to m4a」，出現的搜尋結果就一大串。

Mac

有 Mac 的朋友，轉檔不用靠線上工具，因為 Mac 本身就有 App 可以轉，就是「QuickTime Player」：

把音檔用 QuickTime Player 打開，接著依次點擊「檔案 > 輸出為 > 只限音訊」：

輸出的檔案就會是 .m4a 的檔案了。

如果已經在 Mac 作業，又是 M 晶片的話，可以直接在 Mac 上打開「語音備忘錄」，把轉好的音檔拖拉進去，點擊音檔後，右上角就會看到「’’」的按鈕，點擊後就會開始進行辨識：

參考資源

GitHub Copilot + Figma MCP Server 實戰：用 AI 快速切版教學

Let's Write — Sat, 12 Apr 2025 12:57:28 +0000

本篇要解決的問題

最近在研究 MCP，剛好在 Threads 上看到有人實測 Figma MCP，想試看看是否真的能透過 AI 進行切版。

實作了一下後，還真的可以，不過目前僅針對簡單設計稿進行測試，結果略有跑版現象，整體效果尚可接受。

但目前就有這成果覺得厲害，再給它一段時間，也許前端工程師可以省掉切版的時間，把心力放到別的地方。

前提是，客戶要很明確的知道自己要什麼 XD，不然靠 AI 微調，還不如人工直接改程式還比較快。

用到的資源

以下是要實作用 Figma MCP 來切版，需要的資源：

Demo 直接搜尋一個有人分享的設計稿：

Responsive Landing Page Design

本篇使用的是 GitHub Copilot，要使用 Agent Mode 必需要是付費的方案，免費的無法使用。

Agent Mode 聽說會逐步自動安裝到 VS Code 的 GitHub Copilot 上，沒有的話可以參照官方文件自行打開：Use agent mode in VS Code。

取得 Figma access token

Figma access token 可以在網頁版上取得，但因為抓設計稿的連結，要是 Figma Desktop 上的才有用，所以建議是直接下載 Desktop，安裝後取得：Figma downloads。

安裝好並登入帳號後，點擊自己的大頭貼 > Settings > Security，中間區塊就會有一個 Personal access tokens，點擊 Generate new token，就可以新增一組。

Token 要存下來，下一步要使用。

VS Code MCP 安裝 Figma MCP

安裝 Filesystem

要讓 Agent 可以新增、讀取我們本機檔案，要裝上 MCP 的 Filesystem。

打開 VS Code 後，按下 shift + cmd + p，輸入 mcp，然後點擊「MCP: 新增伺服器」> 「NPM 套件」，輸入 @modelcontextprotocol/server-filesystem 後按下 enter。

中間會再問一次是不是允設安裝，點擊允許。

接著會要我們填讓 MCP 可以有權限的資料夾路徑，這邊，請，不要，填整台電腦的根目錄，主要是安全性的考量，我們可以開一個資料夾給 MCP 用，然後這邊就填上資料夾的路徑。

記得，不要給整台電腦的根目錄，或是有什麼敏感資料的資料夾路徑。

安裝 Figma MCP

打開 VS Code 後，按下 cammnd + p，就會出現搜尋檔案的輸入框。

搜尋「settings.json」會打開我們的設定檔，這邊會是全域設定，只要 VS Code 有登入自己的帳號，就會同步設定。

因為我們已經安裝了 Filesystem，這邊會看到有一段的設定就是 mcp：

在 "filesystem" 同一層的地方，貼上以下：

"Framelink Figma MCP": {
    "command": "npx",
    "args": [
      "-y",
      "figma-developer-mcp",
      "--figma-api-key=Figma_access_token",
      "--stdio"
    ]
}

Figma_access_token 記得換成上一段中取得的 Figma access token。

取得 Figma 設計稿的連結

記得，一定要是從 Figma Desktop 上取得的才有效，不然 MCP 的權限判斷會失敗。

對著想要讓 Agent 寫程式的區塊，點右鍵 > Copy/Paste as > Copy link to selection：

VS Code GitHub Copilot Agent Mode 的 prompt

GitHub Copilot 要先切換成「代理程式」：

之後貼上以下：

以下設計稿，幫我製作成 html、css，所有的圖片檔，都轉成 png，存進 img 資料夾中：
{Figma 設計區塊的連結}

{Figma 設計區塊的連結} 換成上一步中取得的設計稿連結。

按下 enter 後，Agent 會逐步要授權，都給予後就會產生 HTML、CSS、images 檔案。

這邊之所以多一句「所有的圖片檔，都轉成 png」，是因為 August 測試時，發現 SVG 圖檔會常常遇到問題，不是載不下來，不然就是載很久但還是錯誤的，用 PNG 檔這個問題就少很多。

以下影片，是 August 測試時的 Agent 畫面：

最後 Agent 產生的檔案，打開來後如下：

https://letswritetw.github.io/Figma-Context-MCP/

原始碼：

https://github.com/letswritetw/Figma-Context-MCP/tree/main/docs

可以看到除了圖片有些很怪以外，大致上算正常，前端工程師接手後，稍微調整一下，就可以當一個頁面使用了。

心得

雖然現在的 Figma MCP 切出來的頁面，看上去還是有很怪的地方，但 ChatGPT 爆紅後才過了多久就有了 MCP 呢？再給它一段時間，它會愈來愈能符合需求。

AI 會就這樣取代前端工程師嗎？還很難，因為工程師又不是只有切版而已。

把需求做到 120 分讓客戶買單，需要工程師的經驗。

跟設計師對談理解哪邊要哪些效果，跟 PM 吵架溝通，跟後端喬 API 的規格，都需要經驗，AI 目前還是給一動做一動的方式，人類很多東西無法被取代。

但，有了 AI 幫我們先簡單切版，假設 PM 或企劃，需要臨時跟客戶開會，想要有個東西看的話，就可以拿這個去討論，節省很多工程師的時間。

目前 August 的心態是，不要把 AI 當敵人，把它當會不斷幫助我們，而且還不會覺得累的隨身助理。

所以，一直覺得「Copilot 副駕駛」這個詞用得真好。

使用 Google Apps Script 串接 Google Analytics API，整合多站數據

Let's Write — Sat, 29 Mar 2025 09:09:54 +0000

本篇要解決的問題

一間公司裡可能旗下會有多個網站，想同時查看所有網站的 GA 數據，通常需要開啟多個瀏覽器視窗並排顯示，操作較為繁瑣。

如果可以改由 API 來取得 GA 的數據，工程師就可以把各站的資料顯示在一個頁面上，而不用同時開多個 GA 來看。

開通 GA API

取得 GCP 專案編號

要先有 Google Cloud Platform（GCP）的專案，沒有的話登入自己的 Google 帳號，就可以先增一個。

專案編號就在資訊主頁上：

開通 GA API 功能

在使用 API 前，必須先於 GCP 開通對應的功能。

GCP 的專案點擊選單中的「API 和服務」> 「程式庫」：

搜尋框上搜尋「google analytics data api」，會看到結果清單裡會出現「Google Analytics Data API」，點進去後，再點擊啟用，就完成了：

取得 GA 的資源 ID

看要抓的是哪一個 GA 的資料，進到 GA 後台，進到「管理」，點擊「資源詳細資料」：

接著右上角就會看到資源編號：

調用 GA API 程式碼部份

因為調用 Google 的 API，要先經過認證的程序，但如果是寫在跟 GA 相同帳號的 Google Apps Script，就可以省掉這一段。

Google Apps Script 上新增專案

到 Google Apps Script 的頁面上，新增一個專案：

接著可以直接複製貼上以下的程式碼。

瀏覽量、活躍人數

以下程式碼是抓瀏覽量、活躍人數的：

var propertyId = "xxxxxx";  // 替換成 GA 的資源編號
var startDate = "2025-01-01", // 替換成想要從哪一天開始抓的日期

function getGA4Data() {

  var apiUrl = `https://analyticsdata.googleapis.com/v1beta/properties/${propertyId}:runReport`;

  var payload = {
    "dateRanges": [{
      "startDate": startDate,
      "endDate": "today"
    }],
    "metrics": [
      { "name": "screenPageViews" }, // 瀏覽數
      { "name": "activeUsers" } // 活躍用戶數
    ]
  };

  var options = {
    "method": "post",
    "contentType": "application/json",
    "headers": {
      "Authorization": "Bearer " + ScriptApp.getOAuthToken()
    },
    "muteHttpExceptions": true,
    "payload": JSON.stringify(payload)
  };

  var response = UrlFetchApp.fetch(apiUrl, options);
  var data = JSON.parse(response.getContentText());

  // 檢查回應中是否有 rows 資料
  if (data.rows && data.rows.length > 0) {

    // 取得瀏覽數和活躍用戶數
    var screenPageViews = data.rows[0].metricValues[0].value;
    var activeUsers = data.rows[0].metricValues[1].value;

    // 回傳資料
    return {
      "totalPageViews": screenPageViews,
      "activeUsers": activeUsers
    };

  } else {
    // 若無符合資料，則回傳 0 作為預設值
    return {
      "totalPageViews": 0,
      "activeUsers": 0
    };
  }
}

瀏覽量、活躍人數：指定頁面標題

除了抓全站的資料，可以抓指定網頁的 title 是什麼結尾，比如這邊抓的是「會員中心」為結尾的頁面：

var propertyId = "xxxxxx";  // 替換成 GA 的資源編號
var startDate = "2025-01-01", // 替換成想要從哪一天開始抓的日期
var pageTitle = "會員中心"; // 替換成想要篩選的頁面標題文字

function getGA4DataPage() {

  var apiUrl = `https://analyticsdata.googleapis.com/v1beta/properties/${propertyId}:runReport`;

  var payload = {
    "dateRanges": [{
      "startDate": startDate,
      "endDate": "today"
    }],
    "metrics": [
      { "name": "screenPageViews" }, // 瀏覽數
      { "name": "activeUsers" } // 活躍用戶數
    ],
    "dimensionFilter": {
      "filter": {
        "fieldName": "unifiedScreenName",
        "stringFilter": {
          "value": pageTitle,
          "matchType": "ENDS_WITH"
        }
      }
    }
  };

  var options = {
    "method": "post",
    "contentType": "application/json",
    "headers": {
      "Authorization": "Bearer " + ScriptApp.getOAuthToken()
    },
    "muteHttpExceptions": true,
    "payload": JSON.stringify(payload)
  };

  var response = UrlFetchApp.fetch(apiUrl, options);
  var data = JSON.parse(response.getContentText());

  if (data.rows && data.rows.length > 0) {
    var screenPageViews = data.rows[0].metricValues[0].value;
    var activeUsers = data.rows[0].metricValues[1].value;
    return {
      "totalPageViews": screenPageViews,
      "activeUsers": activeUsers
    };
  } else {
    return {
      "totalPageViews": 0,
      "activeUsers": 0
    };
  }
}

即時人數

var propertyId = "xxxxxx";  // 替換成 GA 的資源編號

function getGA4RealtimeData() {

  var apiUrl = `https://analyticsdata.googleapis.com/v1beta/properties/${propertyId}:runRealtimeReport`;

  var payload = {
    "metrics": [{
      "name": "activeUsers"
    }]
  };

  var options = {
    "method": "post",
    "contentType": "application/json",
    "headers": {
      "Authorization": "Bearer " + ScriptApp.getOAuthToken()
    },
    "muteHttpExceptions": true,
    "payload": JSON.stringify(payload)
  };

  var response = UrlFetchApp.fetch(apiUrl, options);
  var data = JSON.parse(response.getContentText());

  // 取得即時人數
  return data.rows[0].metricValues[0].value;
}

即時人數：指定頁面標題

這邊一樣是抓「會員中心」為結尾的頁面：

var propertyId = "xxxxxx";  // 替換成 GA 的資源編號
var pageTitle = "會員中心"; // 替換成想要篩選的頁面標題文字

function getGA4RealtimeDataPage() {
  var apiUrl = `https://analyticsdata.googleapis.com/v1beta/properties/${propertyId}:runRealtimeReport`;

  // 在 payload 中新增 dimensions 和 dimensionFilter
  var payload = {
    "metrics": [{
      "name": "activeUsers"
    }],
    "dimensions": [{
      "name": "unifiedScreenName"
    }],
    "dimensionFilter": {
      "filter": {
        "fieldName": "unifiedScreenName",
        "stringFilter": {
          "value": pageTitle,
          "matchType": "ENDS_WITH"
        }
      }
    }
  };

  var options = {
    "method": "post",
    "contentType": "application/json",
    "headers": {
      "Authorization": "Bearer " + ScriptApp.getOAuthToken()
    },
    "muteHttpExceptions": true,
    "payload": JSON.stringify(payload)
  };

  var response = UrlFetchApp.fetch(apiUrl, options);
  var data = JSON.parse(response.getContentText());

  var totalActiveUsers = 0;

  // 累加所有匹配頁面的人數
  if (data.rows && data.rows.length > 0) {
    data.rows.forEach(function (row) {
      totalActiveUsers += parseInt(row.metricValues[0].value, 10);
    });
  }

  return totalActiveUsers.toString(); // 返回所有匹配頁面的總人數
}

以 POST 的參數，判斷要給哪種資料

上面一共寫了四個函式，我們需要一個參數，讓 API 知道要回應的是哪個資料。

這邊用的參數是 type，type 不同值，就給不同資料，共有 4 個值可以寫：

data：瀏覽量、活躍人數。
dataPage：瀏覽量、活躍人數：指定頁面標題。
realtimeData：即時人數。
realtimeDataPage：即時人數：指定頁面標題。

// 回應錯誤訊息
function createErrorResponse(message, code) {
  var errorResponse = {
    success: false,
    error: message,
    code: code || 400,
    timestamp: new Date().toISOString()
  };
  var jsonOutput = ContentService.createTextOutput(JSON.stringify(errorResponse));
  jsonOutput.setMimeType(ContentService.MimeType.JSON);
  return jsonOutput;
}

// 處理 POST
function doPost(e) {
  // 確認有傳入內容
  if (!e.postData || !e.postData.contents) {
    return createErrorResponse("無效請求：未收到 POST 資料。" + e.postData);
  }

  // 將 POST 資料解析成 JSON
  var requestData;
  try {
    requestData = JSON.parse(e.postData.contents);
  } catch (error) {
    return createErrorResponse("JSON 格式無效。");
  }

  // 檢查是否有 type 參數
  if (!requestData.type) {
    return createErrorResponse("缺少「type」參數。");
  }

  var output;

  // 根據 type 參數執行不同的邏輯
  switch (requestData.type) {
    // 瀏覽量、活躍人數
    case "data":
      var reportData = getGA4Data();
      output = {
        "totalPageViews": reportData.totalPageViews,
        "activeUsers": reportData.activeUsers
      };
      break;
    // 瀏覽量、活躍人數：指定頁面標題
    case "dataPage":
      var reportData = getGA4DataPage();
      output = {
        "totalPageViews": reportData.totalPageViews,
        "activeUsers": reportData.activeUsers
      };
      break;
    // 即時人數
    case "realtimeData":
      var reportData = getGA4RealtimeData();
      output = {
        "activeUsers": reportData
      };
      break;
    // 即時人數：指定頁面標題
    case "realtimeDataPage":
      var reportData = getGA4RealtimeDataPage();
      output = {
        "activeUsers": reportData
      };
      break;
    default:
      return createErrorResponse("type 錯誤");
  }

  // 回傳 JSON 格式的結果
  var jsonOutput = ContentService.createTextOutput(JSON.stringify(output));
  jsonOutput.setMimeType(ContentService.MimeType.JSON);
  return jsonOutput;
}

Google Apps Script 連結到 GCP 專案

左側選單點擊「設定」，接著頁面往下滑，有一項「 Google Cloud Platform (GCP) 專案」，點擊這項的「變更專案」：

接著輸入框就填上第一步在 GCP 上取得的編號，再點擊「設定專案」就可以了：

如果專案存在，連結就會成功，成功的畫面像這樣：

設定完後，這份 GAS 檔就可以使用 GCP 上開啟的 GA API。

部署 GAS

Google Apps Script 的程式如果要能對外，要部署出去才行。

點擊右上角的「部署」> 「管理部署作業」：

部署的類型是「網頁應用程式」：

「誰可以存取」要選擇「所有人」：

選好後，點擊「部署」，需要授權時就直接授權。

部署成功，就會取得一個網址，這個網址就是對外的 API 網址了：

最後，只要 POST 到這個網址，帶上指定的參數 type，就可以取得我們想要的資料。

手動補權限

如果 POST 後，取到的資料一直是 0，代表部署時提供的權限不完整，就要手動補授權。

點擊左側的「專案設定」，在編輯器中顯示「appsscript.json」資訊清單檔案 打勾：

接著回到編輯器，會看到 appsscript.json 這個檔案，補上以下：

"oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/analytics.readonly"
]

最後再次部署，會出現要補權限的授權，一律給過就行，就可以取得 GA 上的資料了。

完整程式碼

完整的 Google Apps Script 程式碼如下，可以直接複製貼上：