0xsongsu/cf-clearance-scraper 项目安装与部署全指南

项目概述

0xsongsu/cf-clearance-scraper 是一个用于自动化处理网站验证和验证码的工具。该项目通过集成多种技术栈，提供了一套完整的解决方案，帮助开发者处理常见的网页防护机制。

安装方式选择

一键部署（推荐）

对于大多数用户，推荐使用一键部署方式，这种方式自动化程度高，能自动处理环境依赖问题。

Mac 系统部署

1. 找到项目中的 一键部署-MAC.command 文件
2. 双击运行该文件
3. 如遇安全提示，按系统指引允许执行

常见问题处理：

• 若提示"未打开"错误，可右键文件选择"打开"
• 或在终端执行权限修复命令：

  chmod +x 一键部署-MAC.command
  xattr -d com.apple.quarantine 一键部署-MAC.command
  

Windows 系统部署

1. 找到项目中的 一键部署-WIN.bat 文件
2. 双击运行该批处理文件

一键部署优势：

• 自动安装 Node.js 运行环境
• 自动配置 Chrome 浏览器
• 自动处理项目依赖
• 零配置启动服务
• 支持局域网多设备访问

手动安装

适合需要自定义配置或有特定环境需求的用户。

基础环境准备

• Node.js 16 或更高版本
• 操作系统支持：macOS/Windows/Linux
• 内存要求：至少 1GB 可用内存

安装步骤

1. 获取项目源代码
2. 进入项目目录
3. 安装 Node.js 依赖
4. 启动服务

# 获取项目代码
git clone 项目仓库地址
cd cf-clearance-scraper

# 安装依赖
npm install

# 启动服务
npm start

验证码功能安装

如需使用验证码解决功能，需要额外配置 Python 环境。

Python 环境配置步骤

1. 进入验证码解决器目录
2. 创建 Python 虚拟环境
3. 激活虚拟环境
4. 安装依赖
5. 配置 Playwright 浏览器

# 进入目录
cd captcha-solvers/hcaptcha

# 创建虚拟环境
python3 -m venv venv

# 激活环境
# Mac/Linux:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# 安装依赖
pip install -e hcaptcha-challenger/

# 安装浏览器
playwright install chromium

Docker 部署方式

对于熟悉容器化技术的用户，可以使用 Docker 快速部署。

# 获取项目代码
git clone 项目仓库地址
cd cf-clearance-scraper

# 使用 Docker Compose 启动
docker-compose up -d

常见问题排查

验证码相关问题

1. 模块未正确安装

   • 确保在虚拟环境中执行安装
   • 检查依赖是否完整

2. 浏览器缺失问题

   • 确认 Playwright 是否正确安装
   • 执行浏览器安装命令

3. API 密钥配置

   • 确保 .env 文件中的 API 密钥已更新
   • 重启服务使配置生效

环境配置问题

1. 浏览器启动失败

   • 确保系统安装了必要的浏览器依赖
   • 检查浏览器路径配置

2. Node.js 版本问题

   • 使用 nvm 管理多版本
   • 确保使用兼容的 Node.js 版本

3. 权限问题

   • 为脚本添加执行权限
   • 处理 Mac 系统的隔离属性

安装验证

完成安装后，建议进行以下验证步骤：

1. 运行部署自检脚本
2. 启动服务并检查日志
3. 执行快速功能测试
4. 验证监控面板可访问

# 部署自检
./tests/deployment_check.sh

# 功能测试
node tests/quick_test.js

性能优化建议

• 生产环境建议设置合理的浏览器实例限制
• 开发环境可降低资源占用
• 低内存设备需调整内存使用上限

总结

本文详细介绍了 0xsongsu/cf-clearance-scraper 项目的多种安装方式，从最简单的一键部署到手动安装和 Docker 部署，涵盖了不同用户的需求。同时提供了详细的故障排查指南和验证方法，帮助用户顺利完成项目部署。

对于初次接触此类工具的用户，建议从一键部署开始，逐步了解项目结构和配置方式。遇到问题时，可参考故障排查部分或查看详细的日志信息。