【应用】Firecrawl-Style Scrape Demo网页爬取效果演示及部署

本项目站内源代码下载地址：https://download.csdn.net/download/s060403072/93384524

文章目录

- [8. 部署指南](#8. 部署指南)
- - [8.1 环境要求 📋](#8.1 环境要求 📋)
  - [8.2 本地开发 💻](#8.2 本地开发 💻)
  - [8.3 生产构建 📦](#8.3 生产构建 📦)
  - [8.4 生产部署 🚀](#8.4 生产部署 🚀)
  - - 方式一：使用项目构建脚本（推荐）
    - 方式二：手动部署
  - [8.5 Caddy 反向代理配置 🔀](#8.5 Caddy 反向代理配置 🔀)
  - [8.6 关键环境变量 🌳](#8.6 关键环境变量 🌳)
- [9. 运维与监控](#9. 运维与监控)
- - [9.1 日志管理 📜](#9.1 日志管理 📜)
  - [9.2 性能优化建议 🚀](#9.2 性能优化建议 🚀)
  - [9.3 常见问题排查 🔧](#9.3 常见问题排查 🔧)
  - [9.4 安全建议 🔒](#9.4 安全建议 🔒)
  - [9.5 备份与恢复 💾](#9.5 备份与恢复 💾)

8. 部署指南

8.1 环境要求 📋

依赖	最低版本	说明
Bun	1.0+	JavaScript 运行时和包管理器。
Node.js	18+	Next.js 构建依赖（Bun 已内置兼容）。
Caddy	2.x	生产环境反向代理服务器。
SQLite	3.x	嵌入式数据库（Prisma 自动管理）。
操作系统	-	Linux / macOS / Windows (WSL)。

8.2 本地开发 💻

安装依赖：
bash 复制代码
```
bun install
```
配置环境变量 ：创建 .env 文件。
复制代码
```
DATABASE_URL="file:./db/custom.db"
```

初始化数据库：

bash 复制代码

bun run db:push   # 创建数据库和表
bun run db:generate # 生成 Prisma Client

启动开发服务器：
bash 复制代码
```
bun run dev
```
访问 http://localhost:3000 即可查看应用。

8.3 生产构建 📦

bash 复制代码

bun run build

此命令会执行 next build，并自动将产物复制到 .next/standalone/ 目录，生成一个可独立运行的、包含所有依赖的部署包。

构建产物结构 ：

复制代码

.next/standalone/
├── server.js            # 入口文件
├── .next/               # 编译后的应用代码
│   └── static/          # 静态资源
└── public/              # 公共资源

8.4 生产部署 🚀

方式一：使用项目构建脚本（推荐）

项目根目录下的 .zscripts/build.sh 脚本可一键完成所有构建、打包步骤，并生成一个包含完整运行环境的 tar.gz 压缩包。

bash 复制代码

BUILD_ID=my-production-build sh .zscripts/build.sh
# 产物位于 /tmp/build_fullstack_my-production-build.tar.gz

方式二：手动部署

构建应用 ：bun run build

准备部署目录 ：

bash 复制代码

mkdir -p /opt/firecrawl-app
cp -r .next/standalone/* /opt/firecrawl-app/
mkdir -p /opt/firecrawl-app/db
cp db/custom.db /opt/firecrawl-app/db/ 2>/dev/null || true
cp Caddyfile /opt/firecrawl-app/

启动应用和代理 ：

bash 复制代码

cd /opt/firecrawl-app
export NODE_ENV=production PORT=3000 DATABASE_URL="file:./db/custom.db"

# 后台启动 Next.js 服务
bun server.js &

# 前台启动 Caddy 反向代理
caddy run --config Caddyfile --adapter caddyfile

8.5 Caddy 反向代理配置 🔀

Caddyfile 是 Caddy 的配置文件，它定义了如何将外部请求转发给内部的 Next.js 应用。

配置解析：
- 监听端口 : :81，即 Caddy 会监听服务器的 81 端口。
- 动态端口转发 : 通过 @transform_port_query 规则，支持在 URL 后添加 ?XTransformPort=端口号 查询参数，将请求转发到指定的端口，方便调试。
- 默认转发 : 所有其他请求默认被转发到 localhost:3000，即 Next.js 应用的服务端口。
安全建议 ：生产环境应将 Caddy 配置为监听 80 和 443 端口，并启用自动 HTTPS。

8.6 关键环境变量 🌳

变量名	默认值	说明
`NODE_ENV`	`development`	运行环境，生产环境请设为 `production`。
`PORT`	`3000`	Next.js 服务监听端口。
`DATABASE_URL`	`file:./db/custom.db`	数据库连接字符串。
`NEXT_TELEMETRY_DISABLED`	`0`	设为 `1` 可禁用 Next.js 遥测数据收集。

9. 运维与监控

9.1 日志管理 📜

日志类型	文件路径	说明
开发服务器日志	`dev.log`	开发模式下的输出日志。
生产服务器日志	`server.log`	生产模式下的输出日志。
mini-services 日志	`.zscripts/mini-service-*.log`	各微服务的独立日志。

常用命令 ：

bash 复制代码

tail -f server.log        # 实时查看
grep -i error server.log  # 搜索错误

9.2 性能优化建议 🚀

⚡ 启用 Gzip 压缩 ：在 Caddy 中启用 encode 指令，压缩传输数据。
📦 静态资源缓存 ：为 _next/static/ 下的资源设置强缓存头。
🔄 抓取结果缓存：对相同 URL 的请求进行短时缓存（如 Redis），减少重复抓取。
🛡️ 实施速率限制：为 API 添加速率限制中间件，防止服务被滥用。

9.3 常见问题排查 🔧

问题现象	可能原因	排查步骤
502 Bad Gateway	Next.js 服务未启动或崩溃	1. `ps aux
抓取接口 500 错误	SDK 调用失败或网络问题	1. 检查 `z-ai-web-dev-sdk` 配置。 2. 测试服务器网络：`curl -I https://example.com`。 3. 查看详细错误日志。
数据库连接失败	`DATABASE_URL` 错误或文件权限	1. 检查环境变量。 2. 确认数据库文件存在且有读写权限。 3. 重新运行 `bun run db:push`。
构建后缺少 server.js	`next.config` 缺少 `output: "standalone"`	检查并确保 `next.config.ts` 中包含 `output: "standalone"`。

9.4 安全建议 🔒

API 鉴权：生产环境建议添加 API Key 或其他鉴权机制。
CORS 配置：根据实际需要配置跨域策略。
URL 白名单：如需限制，可配置可抓取的 URL 白名单。
HTTPS 强制：生产环境务必启用 HTTPS，Caddy 可自动管理证书。

9.5 备份与恢复 💾

数据库备份 ：SQLite 是单文件，备份非常简单。

bash 复制代码

# 手动备份
cp db/custom.db db/custom.db.backup.$(date +%Y%m%d)

# 自动备份脚本示例
#!/bin/bash
BACKUP_DIR="/var/backups/firecrawl"
DB_PATH="/opt/firecrawl-app/db/custom.db"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p "$BACKUP_DIR"
cp "$DB_PATH" "$BACKUP_DIR/custom.db.$DATE"
# 保留最近30天的备份
find "$BACKUP_DIR" -name "custom.db.*" -mtime +30 -delete