DEPLOY_HF.md

Hugging Face Spaces 部署指南

本指南将帮助您将 Turnstile Solver 部署到 Hugging Face Spaces。

📋 前提条件

1. 拥有 Hugging Face 账号
2. 已安装 Git

🚀 部署步骤

1. 创建新的 Space

1. 访问 Hugging Face Spaces
2. 点击 "Create new Space"
3. 填写以下信息：
   • Space name: 您的项目名称（例如：turnstile-solver）
   • License: MIT
   • Select the Space SDK: Docker
   • Space hardware: CPU basic（免费）或更高配置
4. 点击 "Create Space"

2. 准备文件

确保您的项目包含以下文件：

.
├── Dockerfile              # Docker 配置文件
├── api_solver.py          # 主程序文件
├── browser_configs.py     # 浏览器配置
├── db_results.py          # 数据库操作
├── requirements.txt       # Python 依赖
├── proxies.txt           # 代理列表（可选）
└── README_HF.md          # HF Spaces 说明文档（重命名为 README.md）

3. 上传到 Hugging Face

方法 A: 使用 Git（推荐）

# 克隆您的 Space 仓库
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# 复制项目文件到仓库
cp /path/to/your/project/* .

# 重命名 README_HF.md 为 README.md
mv README_HF.md README.md

# 提交并推送
git add .
git commit -m "Initial deployment"
git push

方法 B: 使用 Web 界面

1. 在 Space 页面点击 "Files and versions"
2. 点击 "Add file" > "Upload files"
3. 上传所有必需的文件
4. 确保将 README_HF.md 重命名为 README.md

4. 配置 Space

在 Space 的设置中：

1. Hardware:

   • 免费版：CPU basic（2 vCPU, 16GB RAM）
   • 推荐：CPU upgrade（8 vCPU, 32GB RAM）用于更好的性能

2. Environment variables（可选）:

   • 如果需要，可以添加环境变量

5. 等待部署

• Space 会自动构建 Docker 镜像
• 首次构建可能需要 5-10 分钟
• 构建完成后，服务会自动启动
• 浏览器池初始化需要额外 30-60 秒

6. 验证部署

部署完成后，访问以下端点验证：

# 健康检查
curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health

# 就绪检查
curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/ready

# 主页
https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/

🔧 配置选项

修改浏览器线程数

在 Dockerfile 中修改启动命令：

CMD ["python", "api_solver.py", "--host", "0.0.0.0", "--port", "7860", "--thread", "8"]

启用代理支持

1. 在 proxies.txt 中添加代理
2. 修改 Dockerfile 启动命令：

CMD ["python", "api_solver.py", "--host", "0.0.0.0", "--port", "7860", "--proxy", "--random"]

启用调试模式

CMD ["python", "api_solver.py", "--host", "0.0.0.0", "--port", "7860", "--debug"]

📊 监控和日志

查看日志

1. 在 Space 页面点击 "Logs"
2. 查看实时日志输出
3. 检查浏览器初始化状态

常见日志消息

• "Application startup completed, browser initialization in progress..." - 服务已启动，浏览器正在初始化
• "Browser pool initialized and ready to accept requests" - 服务完全就绪
• "Successfully solved captcha" - 成功解决验证码

⚠️ 注意事项

1. 启动时间:

   • 服务启动后需要 30-60 秒初始化浏览器池
   • 在此期间，API 请求会返回 503 错误
   • 使用 /ready 端点检查就绪状态

2. 资源限制:

   • 免费版 CPU 可能导致性能较慢
   • 建议使用 CPU upgrade 以获得更好性能

3. 超时设置:

   • HF Spaces 有 60 秒的请求超时限制
   • 确保验证码求解在此时间内完成

4. 持久化存储:

   • Space 重启后数据会丢失
   • 数据库结果仅在运行期间保存

🐛 故障排除

Space 一直处于 "Starting" 状态

原因: 服务未能在规定时间内响应健康检查

解决方案:

1. 检查 Dockerfile 是否正确暴露端口 7860
2. 确保 api_solver.py 监听 0.0.0.0:7860
3. 查看日志确认是否有错误

浏览器初始化失败

原因: 系统依赖缺失或资源不足

解决方案:

1. 检查 Dockerfile 中的系统依赖是否完整
2. 升级到更高配置的硬件
3. 减少线程数（--thread 2）

API 返回 503 错误

原因: 浏览器池尚未初始化完成

解决方案:

1. 等待 30-60 秒后重试
2. 使用 /ready 端点检查就绪状态
3. 查看日志确认初始化进度

📞 获取帮助

如果遇到问题，请访问：

• 📢 Telegram 频道: https://t.me/D3_vin
• 💬 Telegram 聊天: https://t.me/D3vin_chat
• 📁 GitHub Issues: https://github.com/D3-vin

📄 许可证

本项目仅供教育用途。使用风险自负。