（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