2025-07-25

[學習筆記] Express.js middleware auth 的業界標準(res.locals)

前言

在 Express.js 認證系統中，常見的做法是在每個需要驗證的路由中直接解析 JWT token。
但有一個更好的實作方式：使用中介軟體將認證結果存放在 res.locals 中。
這不僅是官方建議的做法，也避免了重複解析 token 的效能問題。

TL;DR

使用 res.locals 處理認證是 Express.js 的標準實作：

避免在每個路由重複解析 JWT token
Auth.js、Passport.js 等主流函式庫都採用這種模式
Express.js 官方文檔明確支持這種用法

直接解析 JWT 的缺點

重複工作的效能問題

如果每個路由都直接解析 JWT，會造成不必要的重複運算：

// ❌ 在每個路由重複解析
app.get('/profile', (req, res) => {
  const token = req.headers.authorization?.split(' ')[1]
  const user = jwt.verify(token, JWT_SECRET) // 重複解析
  res.json({ user })
})

app.get('/orders', (req, res) => {
  const token = req.headers.authorization?.split(' ')[1]
  const user = jwt.verify(token, JWT_SECRET) // 又解析一次
  res.json({ orders: getUserOrders(user.id) })
})

程式碼重複與維護困難

每個需要認證的路由都要寫類似的 token 驗證邏輯，違反了 DRY 原則，也增加了維護成本。

錯誤處理不一致

不同路由可能有不同的 token 驗證錯誤處理方式，造成 API 回應不一致。

什麼是 res.locals？

根據 Express.js 官方文檔，res.locals 是一個物件，用來存放請求範圍內的區域變數，這些變數只在當前請求-回應週期中可用。

// Express.js 官方範例
app.use((req, res, next) => {
  res.locals.user = req.user
  res.locals.authenticated = !req.user
  next()
})

主流函式庫的標準實作

Auth.js 官方範例

Auth.js 官方文檔明確展示了使用 res.locals 的標準模式：

import { getSession } from "@auth/express"

export function authSession(req, res, next) {
  res.locals.session = await getSession(req)
  next()
}

app.use(authSession)

// 在路由中使用
app.get("/", (req, res) => {
  const { session } = res.locals
  res.render("index", { user: session?.user })
})

Passport.js 的實作模式

Passport.js 在認證成功時會設置 req.user 屬性，許多開發者會將此資訊複製到 res.locals 以便在視圖中使用：

// 認證中介軟體
app.use((req, res, next) => {
  res.locals.user = req.isAuthenticated() ? req.user : null
  res.locals.isAuthenticated = req.isAuthenticated()
  next()
})

為什麼這是好實作？

1. 官方支持的標準

Express.js 官方文檔說明 res.locals 就是用來存放請求級別的資訊，如認證用戶、用戶設定等。這不是 hack 或 workaround，而是設計用途。

2. 生態系統共識

主流的認證函式庫都採用類似模式：

Auth.js 直接在文檔中展示 res.locals.session
Passport.js 社群普遍使用 res.locals.user
許多教學都展示將認證狀態存放在 res.locals 的模式

3. 分離關注點

// 認證中介軟體 - 只負責認證
function authMiddleware(req, res, next) {
  const token = req.headers.authorization?.split(' ')[1]
  
  if (token) {
    const decoded = jwt.verify(token, JWT_SECRET)
    res.locals.user = decoded
  }
  
  next()
}

// 路由處理器 - 只負責業務邏輯
app.get('/profile', authMiddleware, (req, res) => {
  const { user } = res.locals
  if (!user) {
    return res.status(401).json({ error: 'Unauthorized' })
  }
  res.json({ profile: user })
})

4. 視圖整合優勢

在使用模板引擎時，res.locals 的資料會自動傳遞給視圖：

// 中介軟體設定
app.use((req, res, next) => {
  res.locals.currentUser = req.user
  next()
})

// 在 EJS/Pug 模板中直接使用
// <%= currentUser.name %>

常見的反模式

避免的做法

有些開發者認為過度使用 res.locals 會讓除錯變困難，但這通常是因為：

濫用中介軟體模式 - 把業務邏輯也放在中介軟體裡
過度耦合 - 多個中介軟體互相依賴 res.locals 的順序

正確的使用原則

中介軟體應該用於所有 HTTP 請求共通的事項，且不包含業務邏輯：

// ✅ 好的做法 - 純粹的認證檢查
function authenticate(req, res, next) {
  const token = getTokenFromRequest(req)
  const user = validateToken(token)
  res.locals.user = user
  next()
}

// ✅ 好的做法 - 授權檢查
function requireAuth(req, res, next) {
  if (!res.locals.user) {
    return res.status(401).json({ error: 'Unauthorized' })
  }
  next()
}

// ❌ 避免的做法 - 在中介軟體中處理業務邏輯
function badMiddleware(req, res, next) {
  const user = res.locals.user
  const orders = getUserOrders(user.id) // 業務邏輯不應該在這裡
  res.locals.orders = orders
  next()
}

實務上的最佳實作

標準認證中介軟體

const jwt = require('jsonwebtoken')

function authMiddleware(req, res, next) {
  try {
    const token = req.headers.authorization?.replace('Bearer ', '')
    
    if (token) {
      const decoded = jwt.verify(token, process.env.JWT_SECRET)
      res.locals.user = decoded
      res.locals.isAuthenticated = true
    } else {
      res.locals.user = null
      res.locals.isAuthenticated = false
    }
    
    next()
  } catch (error) {
    res.locals.user = null
    res.locals.isAuthenticated = false
    next()
  }
}

// 授權檢查中介軟體
function requireAuth(req, res, next) {
  if (!res.locals.isAuthenticated) {
    return res.status(401).json({ error: 'Authentication required' })
  }
  next()
}

// 使用方式
app.use(authMiddleware)
app.get('/profile', requireAuth, (req, res) => {
  const { user } = res.locals
  res.json({ user })
})

與 req 自定義屬性的比較

雖然也可以使用 req.user 或 req.data 等自定義屬性，但 res.locals 有幾個優勢：

語意清晰 - 明確表示這是給視圖用的資料
自動傳遞 - 模板引擎會自動取用 res.locals 的資料
標準化 - 社群共識，維護性更好

結論

res.locals 在認證系統中的使用確實是標準實作：

官方支持 - Express.js 和 Auth.js 官方文檔都展示這種用法
生態系統標準 - Passport.js 等主流函式庫採用相同模式
效能考量 - 避免重複解析 JWT 或查詢資料庫
開發體驗 - 控制器可以直接存取用戶資訊

所以下次有人說使用 res.locals 不是好實作時，可以拿出這些官方文檔來證明這確實是被廣泛接受的標準做法。

參考資料

(fin)

2025-07-22

[踩雷筆記] GitHub Action ssh-keyscan not found 問題修復

前情提要

GitHub Action marsen/[email protected] 之前運行正常，但最近開始失敗，錯誤訊息：

1	/usr/app/entrypoint.sh: 9: /usr/app/entrypoint.sh: ssh-keyscan: not found

問題分析

初步檢查

檢查 entrypoint.sh 第9行：

1	ssh-keyscan -t rsa github.com >> /root/.ssh/known_hosts

檢查 Dockerfile 套件安裝：

1 2	FROM node:20-buster-slim RUN apt-get install -y git openssh-client

明明有安裝 openssh-client，為什麼找不到 ssh-keyscan？

根本原因

Debian Buster 生命週期結束

node:20-buster-slim 基於 Debian 10 (Buster)
Debian 10 於 2024年8月達到 End of Life
套件庫不再維護，套件結構可能變化

OpenSSH 套件重組

2024年 OpenSSH 多個版本發布 (9.7, 9.9)
ssh-keyscan 可能從 openssh-client 移到其他套件

Docker 映像自動更新

Docker Hub 會自動重建映像
新版本移除不必要工具以減少攻擊面

解決方案

快速修復（不推薦）

1	RUN apt-get install -y git openssh-client openssh-server

雖然可行，但安裝 SSH 伺服器會增加攻擊面。

正確解法

升級基底映像到支援版本：

# 從過期版本
FROM node:20-buster-slim

# 升級到安全版本  
FROM node:20-bookworm-slim

完整的 Dockerfile 修改：

FROM node:20-bookworm-slim

LABEL version="1.0.12"
LABEL repository="https://github.com/marsen/hexo-action"
LABEL homepage="https://blog.marsen.me"
LABEL maintainer="marsen.lin <[email protected]>"

WORKDIR /usr/app

COPY entrypoint.sh /usr/app/entrypoint.sh
COPY sync_deploy_history.js /usr/app/sync_deploy_history.js

# 安全且最佳化的套件安裝
RUN apt-get update > /dev/null && \
    apt-get install -y git openssh-client > /dev/null && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* && \
    chmod +x /usr/app/entrypoint.sh

ENTRYPOINT ["/usr/app/entrypoint.sh"]

關鍵改進

基底映像升級：buster-slim → bookworm-slim
- Debian 12 取代已 EOL 的 Debian 10
- 更好的安全性和長期支援
最小權限原則：只安裝 openssh-client
- 包含所需的 ssh-keyscan 工具
- 不安裝 SSH 伺服器，減少攻擊面
Docker 最佳實踐：
- 清理 apt 快取減少映像大小
- 使用 && 合併 RUN 指令減少層數

預防措施

使用具體版本標籤而非 latest
定期檢查基底映像的生命週期
建立自動化測試驗證依賴可用性

小結

這次問題的核心是基底映像過期導致的連鎖反應。在容器化開發中，外部依賴的變化往往會影響既有系統。解決方案不是快速修復，而是從根本上升級到安全的長期支援版本。

除錯關鍵思路：分析「為什麼之前可以，現在不行」，往往能找到外部環境變化的線索。

(fin)

2025-06-22

[實作筆記] Ollama 容器化調研筆記

前情提要

最近在搞 AI 模型的本地部署，並試著將 Ollama 容器化。
經過一段時間的調研和實測，想記錄一下目前的進度和對幾個主流方案的看法。

目標

找到穩定的 Ollama 容器化方案
評估各種新興工具的可用性
為未來的產品開發做技術預研

Ollama 簡介

Ollama 是一個開源工具，讓你在本地電腦上輕鬆運行大型語言模型（如 Llama、CodeLlama、Mistral 等）。
安裝簡單，一行指令就能下載和運行各種 AI 模型，無需複雜設定。支援 macOS、Linux 和 Windows。

1 2	# 安裝後直接用 ollama run llama3.2

類似 Docker 的概念，但專門為 AI 模型設計。
還提供 REST API：

1
2
3

# 啟動後自動開啟 API server (預設 port 11434)
curl http://localhost:11434/api/generate \
  -d '{"model": "llama3.2", "prompt": "Hello"}'

沒有 Ollama 的話，你需要：

手動下載模型檔案（通常好幾 GB）
處理不同模型格式（GGUF、GGML 等）
設定 GPU 加速環境
寫代碼載入模型到記憶體
處理 tokenization 和 inference
自己包 API server

Ollama 把這些都幫你搞定了。

選擇

目前採用：Ollama Container + 指令初始化

經過評估，選擇 ollama container 方案最穩定且彈性也最高，

只要需要透過指令的方法來就可以來取模型。

基本用法：

# 啟動 ollama container
docker run -d --name ollama -p 11434:11434 ollama/ollama

# 下載模型
docker exec -it ollama ollama pull llama3.2

Docker Model Runner：值得關注但暫不採用

DMR 在 2025 年 3月隨 Docker Desktop 4.40 推出 Beta 版，

看起來很有潛力，但目前不打算用在產品上。

主因如下

平台支援階段性：最初只支援 Apple Silicon (M1-M4)，5月的 Docker Desktop 4.41 才加入 Windows NVIDIA GPU 支援
實驗階段：工具變化快速，預期會持續改進，對產品開發風險較高
Linux 支援：目前在 Linux (包含 WSL2) 上支援 Docker CE，但整體生態還在發展中

會持續觀察，最新的 Docker Desktop 4.42 甚至支援了 Windows Qualcomm 晶片，發展很快。

Podman AI Lab：概念不錯但有使用限制

Podman AI Lab 提供一份精選的開源 AI 模型清單，概念上跟 DMR 類似，但實際使用上有些考量。

現況支援 GGUF、PyTorch、TensorFlow 等常見格式

提供精選的 recipe 目錄，幫助導航 AI 使用案例和模型

最近與 RamaLama 整合，簡化本地 AI 模型執行

但採用精選模型清單的策略，可能不包含所有想要的模型

相對於 Ollama 的廣泛模型支援，選擇較為有限

不過隨著 RamaLama 能從任何來源簡化 AI 模型的本地服務，未來可能會更靈活。

一些要注意的小問題

Ollama Container 常見坑

GPU 支援：記得加 --gpus all 或用 docker-compose 設定
模型路徑：預設在 /root/.ollama，要持久化記得 mount volume
網路設定：如果在 k8s 環境，注意 service 的 port 設定

Docker Model Runner 評估心得

目前主要在 macOS Apple Silicon 上比較穩定
Linux 支援還在完善中
Windows 支援是最近才加的，需要更多實測

技術選型思考

這次調研讓我想到幾個點：

穩定性 > 新功能：對產品開發來說，穩定性永遠是第一考量
生態完整性：單一工具再好，生態不完善就是硬傷
維護成本：新技術通常需要更多維護工作

下一步

短期計畫：

把 Ollama container 的初始化流程自動化
持續追蹤 DMR 發展
建立技術方案評估標準

中期目標：

等 DMR 穩定後再評估導入
研究其他容器化方案
整理最佳實踐文件

小結

AI 基礎設施變化很快，容器化技術也在演進。目前沒有完美方案，但這個調研過程很有價值。

技術選擇是動態平衡的過程，要在穩定性、功能性、維護成本間找平衡點。

會持續關注這領域的發展，有新發現再分享。

(fin)

2025-06-20

[生活筆記] 2025 常用工具整理 - AI 篇

前情提要

最近 AI 工具如雨後春筍般冒出，整理一些目前在用或值得關注的工具，主要分為對話、開發、專業應用三大類。

對話與通用 AI

Claude

Claude Chat
Anthropic 開發的 AI 助手，擅長寫作、分析、程式開發
支援多模態輸入（文字、圖片、文件）
免費版有使用限制，付費版更穩定

Grok

Grok
xAI 推出的對話式 AI
風格比較直接犀利，會吐槽（特色）
需要 X Premium 會員才能使用

Gemini (Google)

Gemini
Google 最新多模態 AI 助手，支援文字、圖片、程式碼等多種輸入
已整合進 Google Workspace、Android、Chrome 等生態系

Microsoft Copilot

Copilot
微軟全家桶 AI 助手，整合於 Windows 11、Edge、Office 365
支援 Word、Excel、PowerPoint 直接 AI 協作

Perplexity AI

Perplexity
強調即時網路搜尋與問答，支援多語言、引用來源
適合知識查詢、研究輔助

Notion AI

Notion AI
整合於 Notion 筆記/知識管理平台的 AI 助手
支援自動摘要、重寫、腦力激盪等功能

ChatGPT (OpenAI)

ChatGPT
OpenAI 的對話式 AI，支援 GPT-4/4o，應用於對話、程式、資料分析等
免費/付費版皆有

Kimi Chat（Moonshot AI）

Kimi Chat
中文社群討論度高，支援長文閱讀、PDF 分析

Phind

Phind
專為工程師設計的 AI 搜尋與問答平台，程式碼解釋、技術文件查找很強

程式開發工具

程式碼生成與協助

OpenAI Codex
- 雲端軟體工程代理，可同時處理多項開發任務
- 支援功能開發、bug 修復、重構等
GitHub Copilot
- 直接在編輯器中提供程式碼建議
- 可生成整行或整個函數
- 需付費訂閱
Cursor
- AI 程式碼編輯器
- 專注於智能程式開發體驗
- 支援自然語言與程式碼互動
Claude Code
- 官方文件：https://docs.anthropic.com/zh-TW/docs/claude-code/overview
- 產品頁面：
- Anthropic 的命令列工具
- 讓開發者直接從終端委託程式開發任務給 Claude
- 目前還在研究預覽階段
AugmentCode
- AI 驅動的程式碼搜尋與理解平台
- 支援跨專案、跨語言的程式碼查詢、摘要與自動解釋
- 適合大型專案維護、協作與知識傳承

應用開發

Firebase Studio
- Google 的應用開發平台
- 整合多種後端服務
DeepWiki
- AI 驅動的知識搜尋與摘要工具
- 支援多語言、快速整理主題重點，適合研究、學習、資料彙整
- 可用於技術、學術、產業等多種領域

雜七雜八

法律專業 — Harvey AI

專門為法律行業設計的 AI 助手
強調安全性和合規性（重要）

文件研究 — NotebookLM

Google 的筆記和研究工具
可以分析和總結文件
支援多種文件格式上傳

NVIDIA Container Toolkit

NVIDIA 的容器化工具包
主要用於 GPU 加速的容器應用

參考

小結

目前 AI 工具生態系統發展迅速，各家都在搶佔不同的應用場景。
對話類工具已經相當成熟，程式開發輔助工具也越來越實用，專業領域的 AI 應用則剛起步但潛力巨大。
對我個人而言重建自已的工作流程整合 AI 協助已經刻不容緩

(fin)

2025-06-05

[實作筆記] 用 GitLab CI/CD 實現自動打 Tag、Build 與 Push Docker Image 到 Registry

前情提要

在專案自動化部署流程中，讓 CI/CD pipeline 自動產生遞增 tag、build Docker image 並推送到 GitLab Container Registry，是現代 DevOps 的常見需求。

這篇文章記錄我在 GitLab CI/CD 上實作這一流程的經驗。

目標

自動產生遞增 tag（如 ver.1.0.1）
自動 build 並 push Docker image，image tag 與 git tag 同步
支援多專案共用同一份 CI 設定
僅 main 分支觸發

實作

變數抽象化，支援多專案共用

首先，將專案名稱、群組路徑等資訊抽成變數，方便不同專案複用：

variables:
  PROJECT_NAME: my-proj
  GROUP_PATH: my-group
  REGISTRY_PATH: registry.gitlab.com/$GROUP_PATH/$PROJECT_NAME

多階段 Dockerfile 精簡 image

使用 multi-stage build，確保 production image 只包含必要檔案與 production dependencies：

FROM node:23-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM node:23-alpine AS production
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY --from=builder /app/dist ./dist
ENV NODE_ENV=production
EXPOSE 3000
CMD ["npm", "start"]

建議搭配 .dockerignore 避免多餘檔案進入 image。

GitLab CI/CD Pipeline 設定只在 main 分支執行

rules:
  - if: '$CI_COMMIT_BRANCH == "main"'
    when: always
  - when: never

自動產生遞增 tag

採用 major.minor.patch 的版本規則，啟始版號為 ver.1.0.0
先同步 remote tag，避免本地殘留影響
取得最大 patch 號，自動 +1
檢查 tag 是否已存在，確保唯一

script:
  - git fetch --prune --tags
  - git tag -l | xargs -n 1 git tag -d
  - git fetch --tags
  - |
    prefix="ver."
    max_patch=$(git tag -l "${prefix}[0-9]*.[0-9]*.[0-9]*" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | sort -t. -k1,1nr -k2,2nr -k3,3nr | head -n1 | awk -F. '{print $3}')
    if [ -z "$max_patch" ]; then
      new_tag="${prefix}1.0.0"
    else
      major=$(git tag -l "${prefix}[0-9]*.[0-9]*.[0-9]*" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | sort -t. -k1,1nr -k2,2nr -k3,3nr | head -n1 | cut -d. -f1)
      minor=$(git tag -l "${prefix}[0-9]*.[0-9]*.[0-9]*" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | sort -t. -k1,1nr -k2,2nr -k3,3nr | head -n1 | cut -d. -f2)
      patch=$((max_patch + 1))
      new_tag="${prefix}${major}.${minor}.${patch}"
    fi
    # 確保 tag 唯一
    while git rev-parse "$new_tag" >/dev/null 2>&1; do
      patch=$((patch + 1))
      new_tag="${prefix}${major}.${minor}.${patch}"
    done
    echo "new tag is $new_tag"
    echo "NEW_TAG=$new_tag" >> build.env
  - source build.env

自動打 tag 並 push

- git config --global user.email "[email protected]"
- git config --global user.name "gitlab-runner"
- git remote set-url origin https://gitlab-runner:[email protected]/$GITLAB_REPO.git
- git tag "$NEW_TAG"
- git push origin "$NEW_TAG"

Loging、Build & Push Docker image

1
2
3

- docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
- docker build -t $REGISTRY_PATH:$NEW_TAG .
- docker push $REGISTRY_PATH:$NEW_TAG

Docker-in-Docker 設定

DOCKER_TLS_CERTDIR='' 是為了讓 dind 關閉 TLS，讓 CI job 可以直接用明文 TCP 連線 docker daemon，避免 TLS 憑證錯誤。
1
2
3
4
5
services:
- docker:dind
variables:
DOCKER_HOST: tcp://docker:2375/
DOCKER_TLS_CERTDIR: ''
可以參考本文
一些要注意的小問題

DOCKER_TLS_CERTDIR 不能不設定。
tag 跳號或重複？
請務必先刪除本地 tag 再 fetch remote tag。
無法 push tag？
請確認 Deploy Token/PAT 權限，且 remote url 正確。
docker build 失敗，daemon 連不到？
請檢查　gitlab runner 是否有 privileged mode，且 dind 有啟動。
在/etc/gitlab-runner/config.toml中
1
2
3
4
5
6
[[runners]]
name = "docker-runner"
executor = "docker"
[runners.docker]
privileged = true
...

小結

完整 .gitlab-ci.yml 範例如下，

stages:
  - build
variables:
  PROJECT_NAME: my-proj
  GROUP_PATH: my-group
  REGISTRY_PATH: registry.gitlab.com/$GROUP_PATH/$PROJECT_NAME

build-image:
  image: docker:latest
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://docker:2375/
    DOCKER_TLS_CERTDIR: ''
  stage: build
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: always
    - when: never
  script:
    - git fetch --prune --tags
    - git tag -l | xargs -n 1 git tag -d
    - git fetch --tags
    - |
      prefix="ver."
      max_patch=$(git tag -l "${prefix}[0-9]*.[0-9]*.[0-9]*" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | sort -t. -k1,1nr -k2,2nr -k3,3nr | head -n1 | awk -F. '{print $3}')
      if [ -z "$max_patch" ]; then
        new_tag="${prefix}1.0.0"
      else
        major=$(git tag -l "${prefix}[0-9]*.[0-9]*.[0-9]*" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | sort -t. -k1,1nr -k2,2nr -k3,3nr | head -n1 | cut -d. -f1)
        minor=$(git tag -l "${prefix}[0-9]*.[0-9]*.[0-9]*" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | sort -t. -k1,1nr -k2,2nr -k3,3nr | head -n1 | cut -d. -f2)
        patch=$((max_patch + 1))
        new_tag="${prefix}${major}.${minor}.${patch}"
      fi
      while git rev-parse "$new_tag" >/dev/null 2>&1; do
        patch=$((patch + 1))
        new_tag="${prefix}${major}.${minor}.${patch}"
      done
      echo "new tag is $new_tag"
      echo "NEW_TAG=$new_tag" >> build.env
    - source build.env
    - git config --global user.email "[email protected]"
    - git config --global user.name "rag-cicd"
    - git remote set-url origin https://rag-cicd:[email protected]/$GITLAB_REPO.git
    - git tag "$NEW_TAG"
    - git push origin "$NEW_TAG"
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
    - docker build -t $REGISTRY_PATH:$NEW_TAG .
    - docker push $REGISTRY_PATH:$NEW_TAG

這樣設定後，每次 main 分支有 commit，CI/CD 就會自動產生新 tag、build 並推送對應版本的 Docker image 讓大家共用。

(fin)

2025-06-04

[實作筆記] GCP Cloud Run 私有化部署：透過 Load Balancer 實現內網存取與 IP 限制

前情提要

我用 cloud run 建立一個 api 並且有 webhook 的功能
並且希望提供一個對外網址給客戶，而不是 *.run.app 結尾的網址。

在某些場景下，我們不希望 GCP Cloud Run 對外暴露，

例如內部 API Gateway 呼叫、CI/CD 系統內部流程、或僅提供給 VPC 內特定服務存取的微服務。

這次的例子是希望加上 IP 的防護，只允許特定的 IP 呼叫，這時候就會希望：

Cloud Run 不對外公開（Private）
僅允許內網 IP 或 Internal Load Balancer 存取

看似簡單，但 GCP Cloud Run 原生是無伺服器架構，預設就是「公開網址」，要讓它只對內部可見，需要搭配一些 GCP 網路元件操作。這篇筆記會帶你逐步設定，並避開一些常見坑洞。

實作記錄

將 Cloud Run 設為「不公開」
預設 Cloud Run 是公開的，要改為「只有授權的主體可以存取」：
1
2
3
4
5
6
gcloud run services update YOUR_SERVICE \
--ingress internal-and-cloud-load-balancing \
--allow-unauthenticated \
--region YOUR_REGION \
--project YOUR_PROJECT
這樣只有內部的網路才能呼叫 Cloud Run。

也可以透過 GUI 設定，選擇你的 Cloud Run >

Networking > Ingress 選 internal 勾選 Allow Traffic from external Application Load Balancers

可以參考
建立 Serverless NEG（Network Endpoint Group）
可以用 GUI 建立 Loading Blancer >

Edit > Backend configuration >

下拉選單選 Create backend service >

Backend Type 選 Serverless network endpoint group

因為是 Cloud Run
設定 Loading Blancer 的 Backend Service”
LB > Edit backend service

Regions 選擇 Cloud Run 所在的 Region

預設會有一組 Security Policy

Cloud Armor policies > 找到這組 Policy 可以作更細緻的設定，Ex:指定 Ip 呼叫

Loading Blancer URL Map
這是一個額外的設定，情境是原本我已有一組 Domain 與 Backend Service

並且已經設定在 LB 上面，在想要共用 Domain 的情況下，我需要設定 URL Map

保留一組 Path 讓流量打向 Cloud Run，但仍保留其他 API 可以用

LB > Edit > Routing rules > Mode 選擇 Advanced host and path rule

找到指定的 Domain，設定參考如下

defaultService: projects/my-gcp-proj/global/backendServices/my-api
name: path-matcher-7
pathRules:
- paths:
  - /api/v1/*
    service: projects/my-gcp-proj/global/backendServices/my-api
- paths:
  - /cloud-run-app/*
    service: projects/my-gcp-proj/global/backendServices/my-cloud-run-app
    routeAction:
      urlRewrite:
        pathPrefixRewrite: /

以上設定簡單說明如下，

/api/v1/*：導向 my-api，保留原始路徑。
/cloud-run-app/*：導向 my-cloud-run-app，並將路徑重寫為去除 /cloud-run-app 前綴。
其他路徑：預設導向 my-api。

這樣設定可讓多個服務共用同一個負載平衡器並支援乾淨的 URL 管理。

參考

(fin)

2025-05-24

[實作筆記] 我的 Vim 設定

我的 Vim 快捷鍵設定總表，IdeaVim 與 JetBrain：

快捷鍵	模式	功能說明	IdeaVim 設定寫法
zcc	n	清除所有自訂映射	`nmap zcc :mapclear!<CR>`
zso	n	重新載入主 vimrc	`nmap zso :source ~/_ideavimrc<CR>`
zf	n/i	跳到定義（Goto Declaration）	`nmap zf :action GotoDeclaration<CR>` `imap zf <Esc>:action GotoDeclaration<CR>`
zrc, zo	n/i	格式化程式碼（Reformat Code）	`nmap zrc :action ReformatCode<CR>` `imap zrc <Esc>:action ReformatCode<CR>` `nmap zo :action ReformatCode<CR>`
zk	n/i	返回（Back）	`nmap zk :action Back<CR>` `imap zk <Esc>:action Back<CR>`
zj	n/i	AceAction（自訂動作）	`nmap zj :action AceAction<CR>` `imap zj <Esc>:action AceAction<CR>`
ztt	n/i	複製區塊並格式化（自訂巨集）	`nmap ztt y?[F<CR>/{<CR>%o<Esc>p:action ReformatCode<CR>` `imap ztt <Esc>y?[F<CR>/{<CR>%o<Esc>p:action ReformatCode<CR>`
zn	n/i	跳到上一個錯誤（Goto Previous Error）	`nmap zn :action GotoPreviousError<CR>` `imap zn <Esc>:action GotoPreviousError<CR>`
zrr	n/i	重新命名（Rename Element）	`nmap zrr :action RenameElement<CR>` `imap zrr <Esc>:action RenameElement<CR>`
zra	n/i	執行所有單元測試	`nmap zra :action RiderUnitTestRunSolutionAction<CR>` `imap zra <Esc>:action RiderUnitTestRunSolutionAction<CR>`
zrm	n/v	萃取方法（Extract Method）	`nmap zrm :action ExtractMethod<CR>` `vmap zrm :action ExtractMethod<CR>`
zri	n	Inline（內聯變數/方法）	`map zri :action Inline<CR><Esc>`
zrp	n	Introduce Parameter（引入參數）	`map zrp :action IntroduceParameter<CR>`
zrv	n	Introduce Variable（引入變數）	`map zrv :action IntroduceVariable<CR>`
zrf	n	Introduce Field（引入欄位）	`map zrf :action IntroduceField<CR>`
,m	n	顯示檔案結構	`nmap ,m :action FileStructurePopup<CR>`
zrt	n	最近檔案	`nmap zrt :action RecentFiles<CR>`
zgc	n	開啟 Commit 工具視窗	`nmap zgc :action ActivateCommitToolWindow<CR>`
zx	n	快速重構選單	`nmap zx :action Refactorings.QuickListPopupAction <CR>`
zae	n/i	插入 Assert.Equal(,);	`nmap zae aAssert.Equal(,);<Esc>T(i` `imap zae Assert.Equal(,);<Esc>T(i`
zrs	n	新增 class 並格式化（自訂巨集）	`nmap zrs "add? class<CR>2w"bywjopublic <Esc>"bpa()<CR>{<Esc>"apo}<Esc>:action ReformatCode<CR>`
z;	n/i	行尾加分號	`nmap z; $a;<Esc>` `imap z; <Esc>$a;`
,p, ,P	n	黏貼暫存區 0 的內容	`nmap ,p "0p` `nmap ,P "0P`
z,p, z,P	i	插入暫存區 0 的內容	`imap z,p <Esc>"0pa` `imap z,P <Esc>"0Pa`
z,	n	選取括號內內容（vi)）	`:nmap z, vi)`
z.	n	選取大括號內內容（vi}）	`:nmap z. vi}`
	v	連續多次離開選取模式	`:vmap <Esc> <Esc><Esc><Esc>`
jj	i	退出插入模式	`:imap jj <Esc>`
	n	在普通模式下插入 Backspace	`:nmap <BS> a<BS>`
zh	n/i	跳到行首	`:nmap zh ^` `:imap zh <Esc>^i`
zl	n/i	跳到行尾	`:nmap zl $` `:imap zl <End>`
hc	n	Ctrl+C	`:nmap hc ^C`
zb	n/v	單字取代	`:nmap zb bcw` `:vmap zb <Esc>bcw`
zd	i	刪除當前行	`:imap zd <Esc>dd`
j, k	n	軟換行移動	`nmap j gj` `nmap k gk`
qq	n	強制關閉檔案	`nmap qq ZQ`
zq	n	儲存並關閉檔案	`nmap zq :wq<CR>`
	i	刪除當前行	`:imap <C-x> <Esc>dd`
	i	全選	`:imap <C-a> <Esc>ma<CR>ggVG`
,i, ,a	n	替換字元	`:map ,i <Esc>r` `:map ,a <Esc>r`

說明：

n：普通模式（normal mode）
i：插入模式（insert mode）
v：視覺模式（visual mode）
<CR> 代表 Enter 鍵，<Esc> 代表 Esc 鍵

以下是我將 JetBrains（IdeaVim）Vim 快捷鍵移植到 VSCode（VSCodeVim）的對應表，
並說明哪些已成功移植、哪些無法移植及原因：

JetBrains 快捷鍵	VSCode 設定 (before)	VSCode 指令 (commands)	功能說明	可否移植	備註/原因
zrr	[“z”,”r”,”r”]	editor.action.rename	重新命名	✅	完全支援
zf	[“z”,”f”]	editor.action.revealDefinition	跳到定義	✅	完全支援
zrc/zo	[“z”,”r”,”c”]/[“z”,”o”]	editor.action.formatDocument	格式化程式碼	✅	完全支援（你已設 zrc，zo 也可加）
zn	[“z”,”n”]	editor.action.marker.prev	跳到上一個錯誤	✅	完全支援
zrt	[“z”,”r”,”t”]	workbench.action.openRecent	最近檔案	✅	完全支援
,m	[“,”,”m”]	workbench.action.gotoSymbol	檔案結構/大綱	✅	完全支援
zx	[“z”,”x”]	editor.action.refactor	顯示重構選單	✅	完全支援
zgc	[“z”,”g”,”c”]	workbench.view.scm	開啟 Source Control 面板	✅	完全支援
zh	[“z”,”h”]	cursorHome	跳到行首	✅	完全支援
zl	[“z”,”l”]	cursorEnd	跳到行尾	✅	完全支援
zrv	[“z”,”r”,”v”]	editor.action.codeAction.extract.variable	萃取變數	⚠️	VSCodeVim 有選取限制，部分情境下無法觸發
zrm	[“z”,”r”,”m”]	editor.action.codeAction.extract.method	萃取方法	⚠️	VSCodeVim 有選取限制，部分情境下無法觸發
zri	-	-	Inline（內聯變數/方法）	❌	VSCode 沒有公開指令 ID，無法 keybinding
zrp	-	-	Introduce Parameter	❌	VSCode 沒有公開指令 ID，無法 keybinding
zrf	-	-	Introduce Field	❌	VSCode 沒有公開指令 ID，無法 keybinding
ztt	-	-	巨集/多步驟自動化	❌	VSCode 不支援 Vim 巨集或多步驟自動化
zso	-	-	重新載入 vimrc	❌	VSCodeVim 不支援 :source 或重新載入 vimrc
zra	[“z”,”r”,”a”]	testing.runAll	執行所有單元測試	✅	需安裝 VSCode 官方 Testing 功能，已可 keybinding

補充說明

✅：完全支援，已可用於 VSCodeVim。
⚠️：VSCodeVim 有技術限制（如需選取內容，觸發不一定成功）。
❌：VSCode/VSCodeVim 無對應指令或功能，無法移植。
你可以持續用 VSCode 內建的 Cmd+. 或右鍵選單補足無法 keybinding 的重構功能。
zra：VSCode 1.59 以上內建 Testing 功能，指令為 testing.runAll，可直接 keybinding，無需額外外掛。

總結：
我已成功將大部分常用 JetBrains Vim 快捷鍵移植到 VSCode，
僅少數 JetBrains 專屬重構、巨集、vimrc 相關功能因 VSCode 限制無法移植。

(fin)

2025-05-17

[學習筆記] TypeScript 不同寫法的除錯難易比較

前情提要

最近在整理一個專案的 API 路由權限設定，
對同樣的資料結構、不同的寫法，對於型別檢查和除錯有一點小小心得，稍微作個記錄。

情境說明

假設我有一個 API 權限設定如下，每個路由對應一組角色才能訪問：

{
  endpoint: "/admin",
  roles: ["admin", "superuser"]
}

然後我有一個函式 registerPermissions 要吃這個設定。

建議寫法

先給最近建議的寫法，先定義型別，然後變數也套型別
好處是能具體的抓到錯誤，壞處是要多考慮一個型別(命名、擺放位置都會是一個要考量的點)

type PermissionConfig = {
  routes: {
    endpoint: string;
    roles: string[];
  }[];
};

const permissionConfig: PermissionConfig = {
  routes: [
    {
      endpoint: "/admin",
      roles: ["admin", "superuser"],
    },
    {
      endpoint: "/profile",
      roles: "user", // ❌ 馬上紅字報錯
    },
  ],
};

const registerPermissions = (config: PermissionConfig) => {
  // 註冊權限邏輯
};

registerPermissions(permissionConfig);

先定義變數，但沒套型別

這是最不推薦的寫法。雖然寫起來最快、最順手，不用考慮命名和檔案擺放的位置，但錯誤訊息會一大坨，難以閱讀。

在現在這個 AI 時代，也許 AI 能幫你更快理解錯誤，但我還是不建議這麼做。因為一旦習慣這種寫法，很容易錯上加錯。單一錯誤 AI 還能理解，但錯中錯時，AI 也可能會搞不清楚狀況。

const permissionConfig = {
  routes: [
    {
      endpoint: "/admin",
      roles: ["admin", "superuser"],
    },
    {
      endpoint: "/profile",
      roles: "user", // 🧨 這裡故意寫錯，應該是 array
    },
  ],
};

const registerPermissions = (config: {
  routes: {
    endpoint: string;
    roles: string[];
  }[];
}) => {
  // 註冊權限邏輯
};

registerPermissions(permissionConfig);

這種寫法會噴出一堆錯誤。

寫法三：直接 inline 傳入函式

如果沒有共用必要的參數，我通常會推薦 inline 寫法。當然前提是這個方法的複雜度要夠低，讓人容易理解。這樣也可以省去命名和型別檔案擺放位置的煩惱。

const registerPermissions = (config: {
  routes: {
    endpoint: string;
    roles: string[];
  }[];
}) => {
  // 註冊權限邏輯
};

registerPermissions({
  routes: [
    {
      endpoint: "/admin",
      roles: ["admin", "superuser"],
    },
    {
      endpoint: "/profile",
      roles: "user", // ❌ 馬上紅字報錯
    },
  ],
});

小結：推薦寫法

最推薦第一種，但實務上我可能會更多的選擇第三種寫法。
要有上下文，請團隊作好自已的判斷。

(fin)

2025-05-09

[實作筆記] Linux NO Password 執行指令

前情提要

最近在部署某個 webapi server，
這個 webapi 會用一個特別的帳號去執行，但是不會給他設定密碼，
我需要使用 pm2 startup 設定開機自動啟動 webapi 服務。

問題：執行指令會要求輸入密碼

但是我沒有也不打算提供密碼給個 webapi 服務帳號

1 2	sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u marsen --hp /home/marsen [sudo] password for marsen:

嘗試解法：用 visudo 寫 NOPASSWD

為了讓 aiplux 帳號執行特定指令時不需要輸入密碼，可以透過 visudo 編輯 sudoers 檔案。以下是具體步驟：

開啟 sudoers 編輯器：
1
sudo visudo
在檔案中新增以下內容：

1	aiplux ALL=(ALL) NOPASSWD: /usr/lib/node_modules/pm2/bin/pm2

這樣的設定可以確保 aiplux 帳號在執行 /usr/lib/node_modules/pm2/bin/pm2 時不需要輸入密碼，同時避免開放過多權限。

小心資安風險

上面的作法是改自另一位同事的作法，

1 2	echo "marsen ALL=(ALL) NOPASSWD: /usr/bin/apt, /usr/bin/apt-get, /usr/bin/env" \| sudo tee /etc/sudoers.d/marsen >/dev/null chmod 440 /etc/sudoers.d/marsen

這段設定的目的是：

允許 marsen 自由使用 apt 和 apt-get 安裝套件。
使用 env 包裝 PATH 或其他環境變數來執行 pm2。
避免密碼卡住，讓 CI/CD 流程順利執行。

雖然給足夠的權限，可以無密碼執行，但是也帶來很多潛在風險。

資安問題：/usr/bin/env 是個危險洞口

看起來只是想加環境變數用 env，但其實這一條非常危險。為什麼？來看看 env 的本質：

1
2
3

sudo /usr/bin/env bash
sudo /usr/bin/env node
sudo /usr/bin/env python

這些指令會用 root 權限執行對應的 shell 或程式，等於你給了 marsen 完整 root 執行任意程式的能力，這十分危險。

再看 /usr/bin/apt 和 apt-get，同樣是高權限指令。如果沒有限制，也可以被濫用來刪除套件或改動系統。

小結

審慎選擇開放的指令
在自動化流程中，為了避免 sudo 密碼擋路，設定 NOPASSWD 是常見的解法。
但在設定時，務必審慎選擇開放的指令範圍，避免一時圖方便，打開整台主機的後門。
建議只開放必要的指令，並明確指定路徑，確保安全性。

(fin)

2025-05-08

[踩雷筆記] CORS 錯誤的元兇竟然是瀏覽器外掛？

前情提要

最近在本機開發一支簡單的上傳 API，使用 Express.js 搭配 TypeScript。
預期只是在 local 上做個整合測試，前端跑在 localhost:5173，後端是 localhost:3000，照理來說只要 CORS 設好就萬事 OK。

結果——炸了。

問題現象

瀏覽器跳出熟悉的錯誤訊息：

1	Access to fetch at 'http://localhost:3000/upload' from origin 'http://localhost:5173' has been blocked by CORS policy...

一看就是 CORS 錯誤，老問題了，馬上開始排查：

確認 cors() middleware 有設好
檢查 headers 有無正確設定
懷疑是 OPTIONS preflight 沒處理好，也做了補強

怎麼改都一樣。

接著我試了無痕模式，欸？沒事了。
懷疑是瀏覽器快取作怪，清除後還是一樣。
換用 Edge（沒裝任何外掛）測試，正常。

真相大白

這時我就卡關了，因為一切設定看起來都沒問題。

隨口問了新人同事，提到有可能是瀏覽器外掛的問題，我再測試一下

確定是我在 Brave 安裝的外掛「Page Assist - A Web UI for Local AI Models」在搞鬼！

這個外掛可能會偷偷注入 JS 或改寫 request header，導致 CORS 預檢請求出現異常，讓瀏覽器誤以為是 server 設定問題。

我一停用外掛，再次測試，一切正常。

心得與提醒

這次的經驗讓我再次體會：

最難 debug 的錯誤，往往來自你「以為不會出錯」的地方。

給未來的自己幾個建議：

開無痕模式測試：能快速排除快取與外掛的干擾
換乾淨的瀏覽器：有時候 Edge 或 Safari 能救你一命
早點求救：卡住就問，別一個人浪費太多時間在錯的地方打轉，別人可以給你不同觀點

這類奇怪的問題其實很常見，但也正因為難以複製與預期，才更值得記錄下來。

下次遇到奇怪的 CORS 錯誤時，可以考慮是裝的外掛在搞事。

(fin)