# photo

**Repository Path**: siwpan/photo

## Basic Information

- **Project Name**: photo
- **Description**: 图片爬虫（自 media-collection 拆分）
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-11-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

> ⚠️ **已不再维护 / Archived — No longer maintained**
>
> 本仓库已停止开发投入，仅作归档保留，不再接收功能更新或 issue。代码保持原样，仅供历史参考。
> _This repository is no longer maintained. It is archived as-is for historical reference only._

# 简易图片爬虫（Image Crawler）

> 仓库：<https://gitee.com/siwpan/photo> ｜ 许可：MIT（见 [LICENSE](LICENSE)）

> **谱系（2026-08-27）**：本工具的提取语义已并入 image-scraper 源族（photo.json，A 模式纯配置源）；本桌面版维持独立发行与维护。

> 版本 **14.1.0** · 纯 Tkinter 桌面应用 · 最低运行 Python **3.10**
>
> 完整文档见 [`docs/`](docs/)：运行手册 [RUNBOOK](docs/RUNBOOK.md) · 配置参考 [CONFIG](docs/CONFIG.md) · 贡献指南 [CONTRIBUTING](docs/CONTRIBUTING.md) · 更新日志 [CHANGELOG](docs/CHANGELOG.md) · 架构决策 [ADR](docs/adr/README.md)

一个基于 Tkinter 的桌面小工具：输入网页 URL，自动解析并下载页面中的图片到本地目录。

## 文档

本项目配套文档集中在 [`docs/`](docs/)：

| 文档 | 用途 |
|------|------|
| [RUNBOOK.md](docs/RUNBOOK.md) | 安装、运行、首次配置、故障排查、跑测试 |
| [CONFIG.md](docs/CONFIG.md) | 配置项完整参考表（CrawlerConfig 单一真相源） |
| [CONTRIBUTING.md](docs/CONTRIBUTING.md) | 贡献流程、分支 / 测试 / 文档 / commit 规范 |
| [CHANGELOG.md](docs/CHANGELOG.md) | Keep a Changelog 风格版本记录 |
| [adr/README.md](docs/adr/README.md) | 架构决策记录（ADR）索引与撰写约定 |

## 功能特性

- 🖥️ 图形界面（Tkinter），操作简单
- 🔍 广泛抓取图片来源：
  - `<img>` 的 `src` / `data-src` / `data-original` / `data-lazy-src` / `srcset`
  - `<picture><source>` 的 `srcset` / `data-srcset`（响应式图片）
  - 行内 `style` 与 `<style>` 块中的 CSS `background-image`
- 🧵 多线程**并发**下载（线程池，默认 8 线程、界面可配置 1~32 + 连接池复用），UI 不卡顿（子线程通过队列回传日志/进度，线程安全）
- 📊 **实时进度面板**：进度条 + 百分比、下载速度（MB/s）、ETA 预估、已下载总量（独立「瞬时计数器」逐块刷新，丝滑显示，允许重试造成的轻微误差）
- 📦 爬取结束后在日志汇总**成功张数与合计下载大小**；汇总字节基于成功落盘文件、仅成功才累加，重试不会重复计入（与实时显示分两套统计）
- ⚙️ 「选项」面板可配置**并发线程数**与**预览缓存上限**（10~2000，默认 150；控制多少张预览字节驻留内存），预览缓存上限旁带「恢复默认」按钮一键还原；无需改代码
- 🎨 **主题切换**：浅色 / 深色 / 跟随系统（跟随系统通过注册表读取 Windows 深色模式），以及**自定义配色**（「自定义...」打开取色器，调背景/面板/文本/强调/输入区/危险六主色，自动派生其余，保存即生效并持久化；对话框内可一键「重置为浅色 / 深色」还原内置调色板，且**重置时主窗口实时预览**该主题效果）。选择持久化保存到 `.crawlerrc`，下次启动自动恢复
- 🔎 **下载前链接缩略图预览**：点「分析网页」后，自动并发抓取每张图的缩略图，贴在「图片链接」页每行的复选框旁，**先看清再决定下不下**；点击缩略图可用系统程序打开预览原图。抓到的原始字节会被缓存（**LRU 上限保护**，上限可在「选项」面板配置，默认 150，几百张大图也不会撑爆内存），「下载选中」时若命中缓存则直接落盘，**不重复下载**（被上限淘汰的链接会在下载时自动重新抓取，正确性不受影响）
- 📈 **预览抓取进度指示**：分析网页并生成缩略图预览时，进度条 / 百分比 / 状态栏实时显示「正在生成预览 N/M · 已生成 X · 跳过 Y」，可区分「成功生成缩略图」与「因抓取失败/超限而跳过」的数量，先看清预览进度再勾选
- 🖼️ **下载预览**：右侧「下载预览」画廊实时显示已下载图片的缩略图（Pillow 生成），点击缩略图用系统默认程序打开原图；窗口可在左右分栏间拖拽调整
- 💾 **配置统一存取（含窗口状态）**：URL、保存目录、并发线程数、**预览缓存上限**、主题、**窗口尺寸与左右分栏比例**统一持久化到 `.crawlerrc`，启动自动恢复（主题切换/改目录/分析/关闭窗口/调整窗口大小均自动保存）；另可用「保存配置 / 加载配置」导出/导入命名 JSON 文件（同样含预览缓存上限，与界面可配置项一致）
- ⏹ 随时「停止」，分块下载中即可中断（停止信号通过 `threading.Event` 即时生效）
- 📛 文件名自动去重，避免同名图片互相覆盖
- 🛡️ 自动清理文件名非法字符，并防目录穿越
- 🔁 下载失败自动重试（指数退避）
- ⏱️ 图片间礼貌间隔，避免打爆目标站
- 📏 单图体积上限（默认 20MB），超出自动跳过
- 🛰️ **代理支持**：「增强选项」可填写单代理或逗号分隔的代理池，按请求轮换（带失败冷却），规避 IP 频率封锁
- 🕵️ **User-Agent 轮换**：内置真实浏览器 UA 池，每次请求随机轮换，降低被单一标识识别为爬虫的概率
- 🤖 **遵守 robots.txt**（可开关）：基于标准库 `urllib.robotparser` 按域名检查，默认关闭以免误伤；获取失败 fail-open 放行
- 🔄 **断点续传**：开启后用 HTTP `Range` 头从已下载部分继续，中途停止不浪费已下载字节
- 🧭 **软封锁识别**：页面返回 200 但实为“验证人机 / 拦截”页时给出告警，避免误以为解析成功
- 🖼️ **更广的图片源解析**：新增 Open Graph / Twitter / `itemprop` / `<link rel=image_src>`、JSON-LD 结构化数据、SVG `<image>`、`<video poster>`、`<a>` 图片直链，以及更多懒加载属性（`data-srcset` / `data-lazy` 等）
- 🏷️ **扩展名按魔数修正**：下载后依文件头魔数校正扩展名，解决 URL 无扩展名或扩展名不准导致文件类型错误的问题
- ⏱️ **礼貌延时**：「增强选项」可设每张图随机延时区间，模拟人工节奏，降低被打封概率
- 🔗 **连接池 + 自动重试**：底层 `requests.Session` 挂载 `urllib3` 重试适配器（429/5xx 指数退避）与连接池复用，并发更稳定

## v2 增强（反爬 / 代理 / 礼貌抓取）

在「选项」下方新增了「增强选项」面板，可配置：

| 选项 | 说明 | 默认 |
|------|------|------|
| 代理 | 单代理 URL，或逗号分隔的代理池（按请求轮换、失败冷却） | 空（不使用） |
| UA 轮换 | 每次请求从内置真实浏览器 UA 池随机轮换 | 开 |
| 遵守 robots.txt | 抓取前按域名检查 robots 规则；获取失败则放行 | 关 |
| 断点续传 | 用 `Range` 头从已下载部分继续 | 关 |
| 礼貌延时 | 每张图之间随机延时区间（秒），模拟人工节奏 | 0 ~ 0.5 |

> 上述「增强选项」配置项的字段名、类型、默认值与取值约束的完整定义，见 [配置参考 docs/CONFIG.md](docs/CONFIG.md)（单一真相源 `CrawlerConfig`）。

反爬与礼貌抓取策略参考了 2025–2026 年社区最佳实践：UA 轮换 + 完整请求头（含
`Referer` 防盗链）+ 随机延时 + 代理池，并以 `robots.txt` 与“像人一样访问”为底线。
代理凭据请勿写入源码；生产环境建议使用环境变量或受信任的代理服务。

## 安装

依赖已哈希锁定，生产 / CI 统一使用 `requirements.lock`：

```bash
python -m pip install --upgrade pip
python -m pip install -r requirements.lock --require-hashes
```

> 需要本地已安装 Tcl/Tk（Windows / macOS 通常自带；Linux 需 `sudo apt install python3-tk`）。
> 最低运行 **Python 3.10**（注意 `pyproject.toml` 当前 `requires-python = ">=3.7"` 与实测不符，待对齐）。
> 旧文件 `requirements.txt` 无哈希、**不要用于生产安装**；重新生成锁文件见 [docs/RUNBOOK.md](docs/RUNBOOK.md)。

## 使用

```bash
python main.py
```

1. 在「目标网页」填入 URL（如 `https://example.com/gallery`）
2. 在「保存位置」选择或确认下载目录（默认 `downloaded_images/`），「选项」中可调整「并发线程数」（1~32，默认 8）与「主题」
3. 点「分析网页」：抓取并列出全部图片链接，进度条会显示「正在生成预览 N/M · 已生成 X · 跳过 Y」直至缩略图预览生成完毕；在右侧「图片链接」页勾选要下载的项（可全选/全不选/反选，点缩略图可预览大图）。需要代理 / 反爬 / 礼貌抓取，可在「增强选项」面板提前配置（代理、UA 轮换、遵守 robots、断点续传、礼貌延时）
4. 点「下载选中」：仅下载已勾选项（命中预览缓存的直接落盘，不再重复下载），进度条/百分比/速度/ETA 实时更新，右侧「下载预览」同步显示缩略图，可随时点「停止」
5. 窗口尺寸与左右分栏比例会自动存入 `.crawlerrc`，下次启动原样恢复；也可用「保存配置 / 加载配置」导出/导入命名 JSON；点任意缩略图用系统默认程序打开原图

## 项目结构

按职责拆分为「Mixin + 协调器」：`ImageCrawlerApp` 继承各 Mixin，单一类身份不变，`self.*` 全部有效。

| 文件 | 说明 |
|------|------|
| `main.py` | 入口：构造 Tk 根窗口并启动 `ImageCrawlerApp`（同时 re-export 测试用到的符号） |
| `app.py` | `ImageCrawlerApp`：GUI 协调器，组合下方各 Mixin；含窗口构造、UI 消息泵、按钮状态机、窗口几何 |
| `constants.py` | 共享常量：缩略图尺寸、并发数、预览缓存上限等 |
| `theme.py` | `ThemeMixin` + 调色板 THEMES：系统深色检测、配色解析、自定义配色与实时预览 |
| `config.py` | `ConfigMixin`：`.crawlerrc` 持久化 + JSON 配置导入/导出 |
| `linkpanel.py` | `LinkPanelMixin`：图片链接勾选 / 缩略图预览面板（Notebook 标签页） |
| `stats.py` | `StatsMixin`：下载/预览统计、格式化、预览缓存 LRU 上限控制 |
| `crawl.py` | `CrawlMixin`：分析网页、并发抓取预览、并发下载、停止（调用 `crawler_core`） |
| `crawler_core.py` | 纯逻辑：URL 解析（含 OG/JSON-LD/SVG 等）、去重、下载、`ProxyRotator` / `RobotsChecker` / 断点续传 / 魔数修正（无 GUI 依赖，可测试） |
| `tests/test_crawler.py` | 纯函数单元测试 |
| `tests/test_main.py` | 主题解析 / 配置持久化 / 格式化等纯逻辑测试 |
| `requirements.txt` | 依赖（已废弃，无哈希，勿用） |
| `.crawlerrc` | 统一配置（主题 / 自定义配色 / URL / 保存目录 / 线程数 / 预览缓存上限 / 窗口几何 / 分栏比例，自动生成，已被 .gitignore 忽略） |

## 测试

```bash
python -m unittest discover -s tests -p "test_*.py" -v
```

## 注意事项

- 仅用于合法授权的爬取，请遵守目标网站的 `robots.txt` 与相关法规。可在「增强选项」开启“遵守 robots.txt”。
- v2 已内置并发（线程池）、代理池轮换、UA 轮换与礼貌延时；大规模采集请结合受信任的代理服务并合理设置延时，避免对目标站造成压力。