mirror of
https://github.com/OLmatter/glm-coding-helper.git
synced 2026-10-07 17:18:45 +08:00
hoywu
8457a65b14
The Linux one-click-start.sh and setup_backend_linux.sh scripts landed in the previous setup commits but were not surfaced in user-facing docs or in the release zip layout, so Linux users had no on-ramp. This commit adds the missing user-facing documentation and ships the Linux entry point in both release zip builders. - README.md: extend 快速开始 / 启动后端 to cover Linux alongside Windows and macOS, update the zip table to mark online-installer as the macOS / Linux recommendation, add Linux quick-start snippet, and refresh 常用文件 / 常用启动方式 to list one-click-start.sh and the new docs/linux-setup.md. Wording tightened so Windows users are not told to follow Linux commands and vice versa. - docs/linux-setup.md: new Chinese-language install guide covering scope, prerequisites (Python 3.12 / uv, NVIDIA GPU optional), one-click and manual setup paths, virtualenv layout, known limitations, port troubleshooting, post-install verification, and a Windows/macOS/Linux comparison table. - one-click-start.sh: refresh the top-of-file comment so it describes the actual entry point (start_backend.py --headless -> captcha_server_headless) instead of the old "pipeline backend" copy from when the Linux path was a stub. - scripts/release/build_portable.ps1: include one-click-start.sh in the portable zip and add a Linux section to the embedded portable README pointing users at online-installer for Linux with a fallback chmod + run snippet. - scripts/release/build_release_zips.ps1: include one-click-start.sh in the common zip items and rewrite ONLINE_INSTALLER_README.txt to give per-platform launch instructions, document auto PyPI mirror detection, the .venv_paddle / .venv_paddle_gpu layout, and link to docs/linux-setup.md. No code logic change; only docs + packaging so Linux is a first-class release target alongside Windows and macOS.
242 lines
7.1 KiB
Markdown
242 lines
7.1 KiB
Markdown
# Linux 安装与使用说明
|
||
|
||
本文档面向 **Linux 用户**，说明如何在本机安装并启动 GLM Coding Helper 的本地 OCR 后端。
|
||
Windows 用户请直接看 [README.md](../README.md)；macOS 用户请看 [macOS 安装与使用说明](macos-setup.md)。
|
||
|
||
## 适用范围
|
||
|
||
| 项 | 说明 |
|
||
| --- | --- |
|
||
| 系统 | 常见 x86_64 Linux 发行版（Arch、Ubuntu、Debian、Fedora 等） |
|
||
| 架构 | x86_64（与 PaddlePaddle / CUDA wheel 发布范围一致） |
|
||
| 后端 | **CPU** 必选；**NVIDIA GPU** 可选（需驱动 + CUDA 兼容环境）；one-click 走 `captcha_server_headless`（与 Windows 主路径同源，非 macOS 的 `backend/server.py` pipeline） |
|
||
| 验证码识别 | 与 Windows 版一致（YOLO + PaddleOCR 流水线） |
|
||
|
||
## 重要前提：Linux 版怎么识别验证码
|
||
|
||
主流程与 Windows 相同：
|
||
|
||
1. 油猴脚本从腾讯验证码组件抓取原图；
|
||
2. 原图 base64 发送到本地后端 `/captcha_direct`；
|
||
3. 后端用本地 YOLO + PaddleOCR 识别；
|
||
4. 脚本按识别坐标点击文字。
|
||
|
||
**识别不依赖屏幕截图**。Windows 上的自动截图验证码弹窗（`scripts/monitor/window_helper.py`）是 Win32 专用，Linux 不支持，但不影响主流程。
|
||
|
||
## 前置条件
|
||
|
||
### 1. Python 3.12 或 uv
|
||
|
||
项目固定使用 **Python 3.12**。任选其一：
|
||
|
||
**方式 A：系统安装 Python 3.12**
|
||
|
||
```bash
|
||
# Arch
|
||
sudo pacman -S python312
|
||
|
||
# Ubuntu / Debian（视发行版仓库而定）
|
||
sudo apt install python3.12 python3.12-venv
|
||
|
||
python3.12 --version
|
||
```
|
||
|
||
**方式 B：用 uv 管理（推荐，脚本会自动检测）**
|
||
|
||
```bash
|
||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||
uv python install 3.12
|
||
```
|
||
|
||
若 Python 不在默认 PATH，可显式指定：
|
||
|
||
```bash
|
||
export CNCAPTCHA_PYTHON=/path/to/python3.12
|
||
```
|
||
|
||
### 2. NVIDIA GPU（可选）
|
||
|
||
`one-click-start.sh` 默认 `--target auto`：**有 NVIDIA GPU 时优先装 GPU 环境**，失败则回退 CPU。
|
||
|
||
确认驱动可用：
|
||
|
||
```bash
|
||
nvidia-smi
|
||
```
|
||
|
||
无独显或驱动未装好时，脚本会自动走 CPU 路径。
|
||
|
||
### 3. 油猴脚本
|
||
|
||
在 Chrome / Edge（Linux 版）安装 Tampermonkey 并安装 `glm-coding-helper.user.js`，步骤与 Windows 相同，见 [README.md](../README.md) 的「安装油猴脚本」一节。
|
||
|
||
### 4. 网络
|
||
|
||
首次安装会从 PyPI 拉取 PaddlePaddle、Ultralytics 等大包。`one-click-start.sh` 在未传 `--pip-arg` 时会**自动探测可用 PyPI 镜像**（清华、阿里、中科大、腾讯，最后官方源）。
|
||
|
||
## 一键安装（推荐）
|
||
|
||
下载 Release 中的 `glm-coding-helper-online-installer-*.zip` 并解压，在终端执行：
|
||
|
||
```bash
|
||
cd /path/to/glm-coding-helper
|
||
chmod +x one-click-start.sh scripts/setup_backend_linux.sh
|
||
./one-click-start.sh
|
||
```
|
||
|
||
> 从 Windows 打的 zip 解压后通常没有可执行位，**必须先 `chmod +x`**，或直接用 `bash one-click-start.sh` 启动。
|
||
|
||
脚本会自动完成：
|
||
|
||
1. 检测 Linux、NVIDIA GPU、Python 3.12 / uv；
|
||
2. 探测 PyPI 镜像并安装依赖；
|
||
3. 创建 `.venv_paddle`（CPU）和/或 `.venv_paddle_gpu`（GPU）；
|
||
4. 检查 YOLO 权重；
|
||
5. 以 **headless** 模式启动 `captcha_server` 后端（`start_backend.py --headless` → `captcha_server_headless.py`，与 Windows 主路径同源，非 macOS 的 `backend/server.py` pipeline）。
|
||
|
||
启动成功后监听：
|
||
|
||
```text
|
||
http://127.0.0.1:8888
|
||
```
|
||
|
||
可选参数：
|
||
|
||
```bash
|
||
./one-click-start.sh --target auto # 默认：有 GPU 优先 GPU，否则 CPU
|
||
./one-click-start.sh --target cpu # 仅 CPU
|
||
./one-click-start.sh --target gpu # 仅 GPU
|
||
./one-click-start.sh --port 8889 # 换端口
|
||
```
|
||
|
||
## 命令行手动安装
|
||
|
||
```bash
|
||
./scripts/setup_backend_linux.sh
|
||
```
|
||
|
||
常用参数：
|
||
|
||
```bash
|
||
# 仅 CPU / 仅 GPU / 同时安装两者
|
||
./scripts/setup_backend_linux.sh --target cpu
|
||
./scripts/setup_backend_linux.sh --target gpu
|
||
./scripts/setup_backend_linux.sh --target both
|
||
|
||
# 删除并重建环境
|
||
./scripts/setup_backend_linux.sh --target cpu --recreate
|
||
|
||
# 手动指定 PyPI 镜像（跳过自动探测）
|
||
./scripts/setup_backend_linux.sh --pip-arg -i --pip-arg https://pypi.tuna.tsinghua.edu.cn/simple
|
||
```
|
||
|
||
安装完成后手动启动：
|
||
|
||
```bash
|
||
# headless（与 one-click-start.sh 相同）
|
||
./.venv_paddle_gpu/bin/python scripts/tools/start_backend.py --headless --mode auto --port 8888
|
||
|
||
# 仅 CPU
|
||
./.venv_paddle/bin/python scripts/tools/start_backend.py --headless --mode cpu --port 8888
|
||
```
|
||
|
||
## 虚拟环境与模式
|
||
|
||
| 目录 | 用途 |
|
||
| --- | --- |
|
||
| `.venv_paddle` | CPU 后端 |
|
||
| `.venv_paddle_gpu` | GPU 后端（需 NVIDIA + CUDA 兼容 Paddle wheel） |
|
||
|
||
`--mode auto` 会优先用 GPU OCR，失败时回退 CPU（需两个环境都已安装）。
|
||
|
||
## 已知限制
|
||
|
||
| 限制 | 说明 |
|
||
| --- | --- |
|
||
| **无 Win32 截图弹窗** | 与 macOS 相同，走油猴脚本 `/captcha_direct` 发图 |
|
||
| **GPU 依赖环境** | 需 NVIDIA 驱动、CUDA 与 `requirements-backend-gpu.txt` 中的 Paddle GPU wheel 匹配 |
|
||
| **首次模型下载** | PaddleOCR 首次运行会联网下载模型，请耐心等待 |
|
||
| **zip 可执行位** | Release zip 在 Linux 上解压后需 `chmod +x`，见上文 |
|
||
|
||
## 端口占用排查
|
||
|
||
```bash
|
||
ss -tlnp | grep 8888
|
||
# 或
|
||
lsof -i :8888
|
||
|
||
kill <PID>
|
||
```
|
||
|
||
换端口：
|
||
|
||
```bash
|
||
CNCAPTCHA_PORT=8889 ./one-click-start.sh
|
||
```
|
||
|
||
油猴脚本默认连 `http://127.0.0.1:8888`，换端口后需在脚本配置里同步修改。
|
||
|
||
## 安装后验证
|
||
|
||
```bash
|
||
./.venv_paddle/bin/python -c "import fastapi, uvicorn, psutil, ultralytics, paddleocr, paddlex, paddle, cv2, PIL, numpy; print('依赖导入正常')"
|
||
```
|
||
|
||
有 GPU 环境时：
|
||
|
||
```bash
|
||
./.venv_paddle_gpu/bin/python -c "import paddle; print('cuda=', paddle.is_compiled_with_cuda())"
|
||
```
|
||
|
||
启动后端并检查健康接口：
|
||
|
||
```bash
|
||
./one-click-start.sh &
|
||
curl http://127.0.0.1:8888/health
|
||
```
|
||
|
||
## Linux 与 Windows / macOS 差异
|
||
|
||
| 项 | Windows | macOS | Linux |
|
||
| --- | --- | --- | --- |
|
||
| 一键启动 | `one-click-start.cmd` | `one-click-start.command` | `one-click-start.sh` |
|
||
| one-click 后端 | `captcha_server.py`（Tk） | `backend.server` pipeline（headless） | `captcha_server_headless.py` |
|
||
| 日常 GUI | one-click 自带 Tk | `start-backend-pipeline-gui.command` → `backend/gui.py` | 无（可手动 `start_backend.py` 不带 `--headless`，需 tkinter） |
|
||
| GPU | 支持 | 不支持 | 支持（NVIDIA） |
|
||
| 环境搭建 | `bootstrap_windows.ps1` | `setup_backend_macos.sh` | `setup_backend_linux.sh` |
|
||
| PyPI 镜像 | 自动探测 | 需手动 `--pip-arg` | 自动探测 |
|
||
|
||
## 常见问题
|
||
|
||
### `Permission denied` 运行 `./one-click-start.sh`
|
||
|
||
```bash
|
||
chmod +x one-click-start.sh scripts/setup_backend_linux.sh
|
||
# 或
|
||
bash one-click-start.sh
|
||
```
|
||
|
||
### 没有找到 Python 3.12
|
||
|
||
安装系统 Python 3.12，或安装 uv 后执行 `uv python install 3.12`。
|
||
|
||
### `pip install` 很慢或超时
|
||
|
||
脚本默认会自动探测国内镜像。若仍失败，手动指定：
|
||
|
||
```bash
|
||
./one-click-start.sh --pip-arg -i --pip-arg https://pypi.tuna.tsinghua.edu.cn/simple
|
||
```
|
||
|
||
### GPU 安装失败，auto 模式还能用吗？
|
||
|
||
可以。`one-click-start.sh` 在 auto 模式下 GPU 失败会自动回退 CPU，并尝试预装 CPU fallback 环境。
|
||
|
||
### 安装日志在哪？
|
||
|
||
```text
|
||
logs/backend-install.log
|
||
```
|
||
|
||
排查环境问题时请附上此文件。
|