（Ubuntu 24 ― 單節點 / systemd / Playwright MS）

前提條件 #

• 已在 /home/firecrawl 建置完成，且 systemd 服務
  firecrowl-server・firecrowl-workers・firecrowl-playwright
  正在運作中
• Node.js 20 & pnpm 10 已安裝
• Redis 在 localhost:6379 運作中

STEP 0 停止服務 & 備份 #

sudo systemctl stop firecrowl-server firecrowl-workers firecrowl-playwright
cd /home
sudo cp -r firecrawl firecrawl_backup_$(date +%Y%m%d)

STEP 1 更新儲存庫至最新版本 #

1. 註冊安全目錄（僅首次）

   git config --global --add safe.directory /home/firecrawl

2. 淺層擷取至最新提交

   cd /home/firecrawl
   git fetch --depth 1 origin main
   git reset --hard origin/main

STEP 2 清除並重新安裝相依套件 #

cd /home/firecrawl/apps/api
rm -rf node_modules pnpm-lock.yaml package-lock.json
pnpm install                                # 取得最新相依項目
pnpm approve-builds --all                   # 允許 postinstall 腳本

新增缺少的套件（本次所需） #

# Playwright 本體
pnpm add -D playwright
# domhandler 類型缺失對策
pnpm add -D domhandler @types/domhandler

STEP 3 原始碼修正（類型錯誤處理） #

對下列 3 個檔案套用修補程式。

// 省略 … 
const meta = info.metadata as any;
return `${info.timestamp} ${info.level} [${meta.module ?? ""}:${meta.method ?? ""}]: ${info.message}`;
// 省略 …

documents: documents as unknown as string[],

import { Cheerio, load } from "cheerio";
import { AnyNode } from "domhandler";

STEP 4 切換至正式環境建置方式 (tsc→dist) #

4-1 在 package.json 新增腳本 #

"scripts": {
  "build": "tsc",
  "start:prod": "npm run build && node dist/src/index.js"
}

4-2 修改 systemd 服務 #

/etc/systemd/system/firecrowl-server.service

[Service]
WorkingDirectory=/home/firecrawl/apps/api
EnvironmentFile=/home/firecrawl/apps/api/.env
ExecStart=/usr/bin/pnpm run start:prod
Restart=always
RestartSec=5

sudo systemctl daemon-reload

STEP 5 建置 & 重新啟動服務 #

cd /home/firecrawl/apps/api
pnpm run build
sudo systemctl restart firecrowl-server firecrowl-workers firecrowl-playwright

STEP 6 運作確認 #

• sudo systemctl status firecrowl-server 為 active (running)
• curl http://localhost:3002/test → 200 OK
• 瀏覽器：http://<IP>:3002/admin/<TEST_API_KEY>/queues 正常顯示
• http://<IP>:3000/html?url=https://example.com → 傳回 HTML

營運中的更新（今後） #

1. git pull & pnpm install
2. pnpm run build
3. sudo systemctl restart firecrowl-server firecrowl-workers