mirror of
https://github.com/OLmatter/glm-coding-helper.git
synced 2026-10-07 13:28:18 +08:00
OLmatter
94886c4ad5
#32: canBuy/isSoldOut regex was only catching 售罄/补货/暂时; buttons showing '抢购人数过多,请刷新再试' still passed canBuy -> wasted clicks. Add those + '请稍后' to the block regex so the script skips and waits instead of clicking a button that won't go through. #33: macos-setup.md already had python-tk but framed as optional; Tk is actually required (one-click-start.command launches a Tk GUI). Reword to make it clear Tk is required, mention python.org installer bundles tkinter, list the error messages users see when it's missing. Also: CRLF fix from earlier, Linux support (PR #34), version bump 23.5 -> 23.6.
246 lines
8.8 KiB
Markdown
246 lines
8.8 KiB
Markdown
# macOS 安装与使用说明
|
||
|
||
本文档面向 **macOS 用户**，说明如何在本机安装并启动 GLM Coding Helper 的本地 OCR 后端。
|
||
Windows 用户请直接看 [README.md](../README.md) 和 [backend_config.md](backend_config.md)。
|
||
|
||
## 适用范围
|
||
|
||
| 项 | 说明 |
|
||
| --- | --- |
|
||
| 系统 | macOS 12–15（PaddlePaddle 官方支持范围） |
|
||
| 架构 | Apple Silicon（arm64，M1 及后续型号） |
|
||
| 后端 | **仅支持 CPU**（见下方「已知限制」） |
|
||
| 验证码识别 | 与 Windows 版完全一致（YOLO + PaddleOCR CPU 流水线） |
|
||
|
||
## 重要前提：macOS 版怎么识别验证码
|
||
|
||
和 Windows 一样，本项目主用的是 **pipeline 后端**（`backend/server.py`）：
|
||
|
||
1. 油猴脚本直接从腾讯验证码组件抓取原图；
|
||
2. 原图 base64 发送到本地后端 `/captcha_direct`；
|
||
3. 后端用本地 YOLO + PaddleOCR 识别；
|
||
4. 脚本按识别坐标点击文字。
|
||
|
||
也就是说，**识别过程不依赖屏幕截图**。Windows 版里那个自动截图验证码弹窗的功能（`scripts/monitor/window_helper.py`）是纯 Win32 实现，**macOS 不支持**，但这不影响主流程——油猴脚本会把图直接发过来。
|
||
|
||
## 前置条件
|
||
|
||
### 1. Apple Silicon 和 Python 3.12
|
||
|
||
当前固定依赖 `paddlepaddle==3.3.1` 在 macOS 上只发布了 arm64 wheel，Intel Mac（x86_64）无法通过本项目脚本安装。先确认架构：
|
||
|
||
```bash
|
||
uname -m
|
||
```
|
||
|
||
输出必须是 `arm64`。
|
||
|
||
兼容范围以 [PaddlePaddle 官方 macOS PIP 安装说明](https://www.paddlepaddle.org.cn/documentation/docs/en/install/pip/macos-pip_en.html) 为准。
|
||
|
||
系统里的 `python3` 可能不是本项目要求的版本。推荐用 Homebrew 安装 3.12：
|
||
|
||
```bash
|
||
brew install python@3.12
|
||
```
|
||
|
||
`one-click-start.command` 会启动 Tk 可视化窗口，**Tk 是必需的**。Homebrew 的 Python 默认不带 tkinter，需要单独安装：
|
||
|
||
```bash
|
||
brew install python-tk@3.12
|
||
```
|
||
|
||
> 也可以直接用 [python.org 官方安装包](https://www.python.org/downloads/macos/)（3.12），官方包自带 tkinter，不需要额外装。但官方安装的 Python 可能不在 PATH 里，`one-click-start.command` 找不到时可以按下面的「手动指定 Python 路径」处理。
|
||
|
||
如果没装 tkinter 会报错 `ModuleNotFoundError: No module named '_tkinter'` 或 `Tk is unavailable`，装好 `python-tk@3.12` 后重新双击 `one-click-start.command` 即可。
|
||
|
||
安装后确认：
|
||
|
||
```bash
|
||
python3.12 --version
|
||
```
|
||
|
||
或访问官方下载页：<https://www.python.org/downloads/macos/>
|
||
|
||
### 2. 油猴脚本
|
||
|
||
在 Chrome / Edge 安装 Tampermonkey 并安装本项目的 `glm-coding-helper.user.js`，步骤和 Windows 完全相同，详见 [README.md](../README.md) 的「安装油猴脚本」一节。
|
||
|
||
### 3. 网络
|
||
|
||
首次安装会从 PyPI 拉取 PaddlePaddle、Ultralytics 等包，**mac 的 wheel 体积较大**，请保持网络畅通。必要时可走国内镜像（见下文「命令行手动安装」）。
|
||
|
||
## 一键安装（推荐）
|
||
|
||
下载 Release 压缩包并解压后，双击：
|
||
|
||
```text
|
||
one-click-start.command
|
||
```
|
||
|
||
首次双击如果被 macOS 的 Gatekeeper 拦截（提示「无法打开」），用以下任一方式解决：
|
||
|
||
- 在 Finder 里**右键点击** `one-click-start.command` → 选择「打开」→ 在弹窗里点「打开」；
|
||
- 或在终端里赋予可执行权限后运行：
|
||
|
||
```bash
|
||
chmod +x one-click-start.command
|
||
./one-click-start.command
|
||
```
|
||
|
||
这个脚本会自动完成：
|
||
|
||
1. 检查 macOS、Apple Silicon 架构和 Python 3.12；
|
||
2. 创建虚拟环境 `.venv_paddle`；
|
||
3. 安装 CPU 依赖（`requirements-backend-cpu.txt`）；
|
||
4. 检查 YOLO 权重；
|
||
5. 以 headless 模式启动后端。
|
||
|
||
启动成功后监听：
|
||
|
||
```text
|
||
http://127.0.0.1:8888
|
||
```
|
||
|
||
## 日常启动（带可视化窗口）
|
||
|
||
环境装好后，日常使用双击：
|
||
|
||
```text
|
||
start-backend-pipeline-gui.command
|
||
```
|
||
|
||
它会弹出 Tk 窗口，实时显示：
|
||
|
||
- **顶部状态栏**：系统状态（启动中 / 运行中）、YOLO / OCR worker 数、监听地址；
|
||
- **中间识别列表**：最近识别结果（提示字、预测字、置信度、yolo/ocr 耗时）；
|
||
- **底部日志框**：后端 stdout 实时滚动。
|
||
|
||
关闭窗口会自动停止后端子进程。
|
||
|
||
如果端口 8888 被占用，脚本会用 `lsof` 检测并提示是否停止占用进程。
|
||
|
||
## 命令行手动安装
|
||
|
||
如果你想手动控制安装过程（例如用国内镜像加速），运行环境搭建脚本：
|
||
|
||
```bash
|
||
./scripts/setup_backend_macos.sh
|
||
```
|
||
|
||
可选参数：
|
||
|
||
```bash
|
||
# 删除并重建 .venv_paddle
|
||
./scripts/setup_backend_macos.sh --recreate
|
||
|
||
# 跳过安装后的导入冒烟测试
|
||
./scripts/setup_backend_macos.sh --no-smoke-test
|
||
|
||
# 用清华镜像加速安装
|
||
./scripts/setup_backend_macos.sh --pip-arg -i --pip-arg https://pypi.tuna.tsinghua.edu.cn/simple
|
||
```
|
||
|
||
脚本完成后，手动启动：
|
||
|
||
```bash
|
||
# GUI 模式（弹 Tk 窗口）
|
||
./.venv_paddle/bin/python backend/gui.py
|
||
|
||
# headless 模式
|
||
./.venv_paddle/bin/python -m backend.server
|
||
|
||
# 指定端口
|
||
CNCAPTCHA_PORT=8888 ./.venv_paddle/bin/python -m backend.server
|
||
```
|
||
|
||
> macOS 启动脚本固定使用 CPU pipeline 后端。如 Python 3.12 不在 PATH，可先设置 `CNCAPTCHA_PYTHON=/完整路径/python3.12`。
|
||
|
||
## 已知限制
|
||
|
||
| 限制 | 说明 |
|
||
| --- | --- |
|
||
| **仅 CPU** | PaddlePaddle 在 macOS 上只提供 CPU wheel，没有 CUDA / GPU 版本，也不支持 Apple Silicon 的 MPS 加速。识别速度会比有 NVIDIA GPU 的机器慢一些，但准确率一致。 |
|
||
| **不支持自动截图弹窗** | 自动截图验证码弹窗（`window_helper.py`）是 Win32 专用功能，macOS 不支持。但**主流程不依赖它**——油猴脚本会直接把验证码原图发到 `/captcha_direct`。 |
|
||
| **macOS 26 及更高版本** | 超出当前 PaddlePaddle 官方文档列出的 macOS 12–15 范围，本项目不承诺可用；可按下方验证步骤实测。 |
|
||
| **首次模型下载** | 第一次启动时 PaddleOCR 会联网下载 PP-OCRv5 模型，体积较大，请耐心等待。 |
|
||
| **识别速度** | Apple Silicon 上 CPU 推理已相当快，但 YOLO + 多个 OCR worker 的并发受物理核数限制。可在仓库根 `config.json`（首次启动自动生成）里手动调整 `workers` / `ocr_workers`。 |
|
||
|
||
## 端口占用排查
|
||
|
||
如果后端启动报端口被占用，但启动器没正确处理，手动排查：
|
||
|
||
```bash
|
||
# 查看 8888 端口的占用进程
|
||
lsof -i :8888
|
||
|
||
# 终止占用进程（替换 <PID>）
|
||
kill <PID>
|
||
```
|
||
|
||
或换一个端口启动：
|
||
|
||
```bash
|
||
CNCAPTCHA_PORT=8889 ./.venv_paddle/bin/python -m backend.server
|
||
```
|
||
|
||
注意油猴脚本默认连 `http://127.0.0.1:8888`，换端口后需要在油猴脚本配置里同步修改后端地址。
|
||
|
||
## macOS 与 Windows 版差异
|
||
|
||
| 项 | Windows | macOS |
|
||
| --- | --- | --- |
|
||
| 启动脚本 | `.cmd` + PowerShell（`.ps1`） | `.command` + bash（`.sh`） |
|
||
| GPU 模式 | 支持（需 NVIDIA GPU + CUDA） | 不支持（仅 CPU） |
|
||
| 自动截图弹窗 | 支持（Win32） | 不支持（走油猴脚本发图） |
|
||
| 环境搭建 | `bootstrap_windows.ps1` | `scripts/setup_backend_macos.sh` |
|
||
| 支持架构 | x86_64 | arm64（Apple Silicon） |
|
||
| 识别模型 | YOLO + PaddleOCR | YOLO + PaddleOCR |
|
||
|
||
## 安装后验证
|
||
|
||
环境安装完成后，先运行：
|
||
|
||
```bash
|
||
./.venv_paddle/bin/python -c "import paddle; paddle.utils.run_check()"
|
||
./.venv_paddle/bin/python -c "import fastapi, uvicorn, psutil, ultralytics, paddleocr, paddlex, cv2, PIL, numpy; print('依赖导入正常')"
|
||
```
|
||
|
||
再启动 headless 后端，并在另一个终端检查健康接口：
|
||
|
||
```bash
|
||
./one-click-start.command
|
||
curl http://127.0.0.1:8888/health
|
||
```
|
||
|
||
只有依赖导入、Paddle 自检和 `/health` 都通过，才说明本机环境确实可用。
|
||
|
||
## 常见问题
|
||
|
||
### 双击 `.command` 提示「无法打开，因为无法验证开发者」
|
||
|
||
macOS Gatekeeper 拦截。右键点击文件 → 「打开」→ 弹窗里点「打开」即可。或在终端里 `chmod +x 文件名.command` 后用命令行运行。
|
||
|
||
### 启动后 OCR worker 一直不 ready
|
||
|
||
首次启动需要下载模型并做 JIT 预热，可能需要 30 秒到几分钟。观察 Tk 窗口底部日志，看到类似 `[ocr] Core N ready` 表示就绪。如果长时间卡住，检查网络（模型下载失败）或查看日志里的错误信息。
|
||
|
||
### `pip install` 很慢或失败
|
||
|
||
mac 的 PaddlePaddle / Ultralytics wheel 体积大，建议用国内镜像：
|
||
|
||
```bash
|
||
./scripts/setup_backend_macos.sh --pip-arg -i --pip-arg https://pypi.tuna.tsinghua.edu.cn/simple
|
||
```
|
||
|
||
### ImportError: paddle / paddleocr
|
||
|
||
通常是没有激活虚拟环境或安装不完整。确认用 `.venv_paddle/bin/python` 启动，而不是系统的 `python3`。重新运行 `./scripts/setup_backend_macos.sh --recreate` 可彻底重建环境。
|
||
|
||
### 提示需要 Python 3.12，但系统已有 Python 3
|
||
|
||
`python3` 可能是 3.14 等不兼容版本，脚本不会再误用它。安装 `python@3.12` 后重试，或明确指定：
|
||
|
||
```bash
|
||
CNCAPTCHA_PYTHON=/opt/homebrew/bin/python3.12 ./scripts/setup_backend_macos.sh
|
||
```
|