SakuraFrp 自动签到（main + sakura_frp_auto_check + SakuraFrpQiandao），已排除 .env 与日志

2026-08-27 21:43:38 +08:00
commit 2a9f96fb18
21 changed files with 2209 additions and 0 deletions
@@ -0,0 +1,171 @@
+# SakuraFrp 自动签到脚本
+
+使用 Playwright 驱动浏览器，并通过 AI 视觉识别完成 SakuraFrp 九宫格验证码签到。
+
+## 功能特性
+
+- 自动登录 SakuraFrp 账户
+- AI 视觉识别九宫格验证码
+- 自动点击匹配的验证码格子
+- 失败自动重试，默认最多 10 次
+- 支持 GitHub Actions 定时执行
+- 支持邮件通知和日志归档
+
+## 本地运行
+
+### 1. 环境准备
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+本项目默认优先使用本机已安装的 Chrome，不需要下载 ChromeDriver，也不强制执行 `playwright install chromium`。
+
+如果本机没有 Chrome，或希望使用 Playwright 托管浏览器，可以执行：
+
+```bash
+python -m playwright install chromium
+```
+
+### 2. 配置环境变量
+
+创建 `.env` 文件：
+
+```env
+SAKURAFRP_USER=your_username
+SAKURAFRP_PASS=your_password
+
+BASE_URL=https://api.example.com/v1
+API_KEY=your_api_key
+MODEL=your_model_name
+
+MAX_RETRIES=10
+HEADLESS=false
+CHROME_BINARY_PATH=
+
+# 是否将验证码图片转换为 base64（可选）
+# 可接受：true/false, 1/0, yes/no, on/off
+# 通过第三方适配器接入的服务可能不支持直接使用图片 URL，此时设为 true。
+IMAGE_AS_BASE64=false
+```
+
+`CHROME_BINARY_PATH` 可选。留空时会自动查找系统 Chrome；如果你的 Chrome 不在默认位置，可以显式指定：
+
+```env
+CHROME_BINARY_PATH=C:\Program Files\Google\Chrome\Application\chrome.exe
+```
+
+Playwright 只复用 Chrome 可执行文件，不会读取你日常 Chrome 的用户目录、Cookie、历史记录或扩展。
+
+### 3. 运行脚本
+
+```bash
+python main.py
+```
+
+## GitHub Actions 部署
+
+工作流文件位于 `.github/workflows/sakurafrp_sign.yml`，默认每天北京时间 9:00 执行，也支持手动触发。
+
+需要配置以下 Secrets：
+
+| 名称 | 说明 |
+| --- | --- |
+| `SAKURAFRP_USER` | SakuraFrp 用户名 |
+| `SAKURAFRP_PASS` | SakuraFrp 密码 |
+| `BASE_URL` | OpenAI 兼容 API 地址 |
+| `API_KEY` | API 密钥 |
+| `MODEL` | 多模态模型名称 |
+
+邮件通知为可选配置：
+
+| 名称 | 说明 |
+| --- | --- |
+| `EMAIL_USERNAME` | 发件邮箱 |
+| `EMAIL_PASSWORD` | 邮箱授权码或应用密码 |
+| `RECEIVER_EMAIL` | 收件邮箱，默认发给自己 |
+| `SMTP_SERVER` | SMTP 服务器，默认 `smtp.gmail.com` |
+| `SMTP_PORT` | SMTP 端口，默认 `587` |
+
+Actions 使用 GitHub runner 自带 Chrome，并执行 `python -m playwright install-deps chromium` 安装 Linux 运行依赖，避免每次下载 Playwright Chromium 大包。
+
+## 项目结构
+
+```text
+SakuraFrp-Qiandao/
+├── .github/workflows/sakurafrp_sign.yml
+├── automation.py          # Playwright 签到主流程
+├── captcha_handler.py     # GeeTest 验证码识别和点击
+├── config.py              # 环境变量和日志配置
+├── human_simulator.py     # 简单人类操作模拟
+├── main.py                # 程序入口
+├── send_email.py          # 邮件通知
+├── requirements.txt       # Python 依赖
+└── README.md
+```
+
+## 配置说明
+
+### 定时任务时间
+
+修改 `.github/workflows/sakurafrp_sign.yml` 中的 cron 表达式：
+
+```yaml
+schedule:
+  - cron: '0 1 * * *'  # UTC 1:00 = 北京时间 9:00
+```
+
+常用时间对照：
+- `0 1 * * *` - 每天 9:00（北京时间）
+- `0 13 * * *` - 每天 21:00（北京时间）
+- `0 1,13 * * *` - 每天 9:00 和 21:00
+
+### AI 模型推荐
+
+支持任何兼容 OpenAI API 的多模态模型：
+
+- OpenAI: `gpt-4o`
+- 阿里通义: `qwen-vl-plus`, `qwen-vl-max`
+- 智谱 AI: `glm-4v`
+- GitHub Copilot: 可通过第三方 OpenAI 兼容适配层接入
+- ModelScope: 各种开源视觉模型
+
+## 故障排查
+
+### 验证码识别失败
+
+尝试更换更强的视觉模型，或增加 `MAX_RETRIES`。模型需要支持图片输入，并兼容 OpenAI Chat Completions API。
+
+### 模型返回非标准响应
+
+脚本会记录完整响应结构。如果响应中包含 `error` 或 `errors`，会直接终止，因为刷新验证码无法修复模型 API 错误。
+
+### Playwright 下载 Chromium 失败
+
+如果出现 `timed out`、`ECONNRESET` 或 `Failed to download Chrome for Testing`，通常是网络到 Playwright/CDN 下载源不稳定。推荐直接使用系统 Chrome，并在 `.env` 中按需设置 `CHROME_BINARY_PATH`。
+
+### 登录失败
+
+检查 `SAKURAFRP_USER` 和 `SAKURAFRP_PASS` 是否正确，必要时关闭无头模式查看页面行为：
+
+```env
+HEADLESS=false
+```
+
+### 未收到邮件
+
+确认邮箱开启 SMTP，并使用授权码或应用专用密码，不要直接使用普通登录密码。
+
+## 注意事项
+
+请勿频繁触发签到，避免被限流。妥善保管账号密码、API Key 和邮箱授权码。
+
+## 相关链接
+
+- [SakuraFrp 官网](https://www.natfrp.com/)
+- [Playwright 文档](https://playwright.dev/python/)
+- [GitHub Actions 文档](https://docs.github.com/en/actions)
+- [copilot-api](https://github.com/caozhiyuan/copilot-api)
+- [LiteLLM](https://github.com/BerriAI/litellm)