kina-archive 1.1.0

网页时光机 - 多浏览器截图、像素级/感知哈希对比、网页变更追踪

🕐 kina-archive

网页时光机 - 截图、对比、追踪、回溯

定期对网页截图，自动检测视觉变化，生成时间轴对比报告。

---

目录

• 功能特性
• 安装部署
• 使用方法
• 对比模式说明
• 反 Bot 检测
• 截图对比原理
• 应用场景
• 技术栈
• 作者
• 更新日志
• License

---

功能特性

• 多浏览器支持：Chrome / Edge / Firefox 自动检测，可指定优先级，各浏览器使用独立截图参数
• 反检测：模拟真实 User-Agent，绕过基础 Bot 检测
• 多种对比模式：像素级 / 感知哈希 / 内容结构
• 忽略区域：支持排除动态背景、广告等干扰区域，支持百分比坐标（如 100%,20%）
• HTML 报告：自动生成带时间轴的对比报告，图片自动打包到 report_assets/，可独立分享
• 日志系统：支持 --verbose 详细日志和 --quiet 静默模式
• 截图超时：支持 --timeout 自定义超时时间
• 跨平台：Windows / macOS / Linux 全支持

---

安装部署

从 PyPI 安装（推荐）

pip install kina-archive

从源码安装

# 克隆仓库
git clone https://github.com/muyi3919/kina-archive.git
cd kina-archive

# 安装
pip install -e .

浏览器依赖

至少安装以下浏览器之一：

浏览器	Windows	macOS	Linux
Google Chrome	官网下载	官网下载	sudo apt install chromium-browser
Microsoft Edge	官网下载	官网下载	-
Mozilla Firefox	官网下载	官网下载	sudo apt install firefox

---

使用方法

基础截图

# 自动检测浏览器
kina-archive snapshot https://kina.ink

# 指定浏览器
kina-archive snapshot https://kina.ink --browser edge

# 指定超时时间（默认 60 秒）
kina-archive snapshot https://kina.ink --timeout 120

对比模式（解决动态背景问题）

# 感知哈希模式 - 忽略背景图变化，推荐用于随机背景站点
kina-archive snapshot https://kina.ink --mode phash

# 内容结构模式 - 关注布局结构，忽略颜色/背景变化
kina-archive snapshot https://kina.ink --mode content

# 像素级模式（默认）- 最严格，适合静态页面
kina-archive snapshot https://kina.ink --mode pixel

忽略区域

如果你的页面有动态背景图、轮播广告等干扰区域，可以排除：

# 忽略顶部 300px 区域（绝对像素坐标）
kina-archive snapshot https://kina.ink --ignore 0,0,1920,300

# 忽略顶部 20% 区域（百分比坐标，适配不同分辨率）
kina-archive snapshot https://kina.ink --ignore 0,0,100%,20%

# 忽略多个区域（分号分隔）
kina-archive snapshot https://kina.ink --ignore "0,0,1920,300;0,800,1920,280"

持续监控

# 每小时监控，使用感知哈希模式（适合动态背景站点）
kina-archive watch https://kina.ink -i 3600 --mode phash

# 监控 10 次后停止
kina-archive watch https://kina.ink -i 1800 -c 10 --mode phash

# 静默模式（只输出错误）
kina-archive watch https://kina.ink -i 3600 --quiet

# 详细日志模式
kina-archive watch https://kina.ink -i 3600 --verbose

生成报告

# 生成 HTML 报告
kina-archive report

# 报告会自动将截图和差异图复制到 report_assets/ 目录
# 将整个目录打包即可独立分享

其他命令

命令	说明
kina-archive history https://kina.ink -l 20	查看历史
kina-archive report	生成报告
kina-archive stats	查看统计
kina-archive --version	查看版本
kina-archive --help	查看帮助

---

对比模式说明

模式	适用场景	特点
pixel	静态页面、UI 测试	像素级严格对比，背景变化会触发告警
phash	动态背景、随机图片	感知哈希，忽略细微视觉差异，推荐用于博客/个人站
content	布局监控、结构对比	关注页面结构，忽略颜色和背景变化

---

反 Bot 检测

部分网站（如开启阿里云 ESA、Cloudflare 等 CDN 防护的站点）可能会拦截 headless 浏览器请求，显示验证码页面。

解决方案：

1. 使用真实浏览器：工具已内置 User-Agent 伪装和反自动化检测参数
2. 指定不同浏览器尝试：--browser edge 或 --browser firefox
3. 使用感知哈希模式：--mode phash 可减少因验证码页面导致的误报
4. 在服务器部署：将工具部署到与目标网站同 IP 段的服务器，避免 CDN 拦截
5. 忽略干扰区域：--ignore 排除验证码弹窗区域

---

截图对比原理

• 像素级：逐像素对比 RGB 差异，阈值 30
• 感知哈希：缩放至 32x32 计算平均灰度哈希，汉明距离比对
• 内容结构：检测边缘梯度变化，关注布局而非颜色

---

应用场景

• 监控博客改版效果（用 phash 模式忽略随机背景）
• 追踪竞品网站更新
• 记录网页历史状态
• 检测友链页面变更
• 验证部署是否生效
• UI 回归测试（用 pixel 模式）

---

技术栈

• Python 3.8+
• Pillow（图像处理）
• SQLite（数据存储）
• Chrome / Edge / Firefox Headless（截图引擎）

---

作者

kina漫记 · kina.ink

---

更新日志

v1.1.0 (2026-06-25)

修复：

• 修复 report 命令 KeyError: 'margin' 崩溃
• 修复 Firefox/Edge 浏览器截图参数错误导致完全失效
• 修复 diff 图同一天被覆盖的问题
• 修复 HTML 报告图片路径失效（现自动打包到 report_assets/）
• 修复 CI 测试配置
• 统一版本号为 1.1.0

新增：

• 日志系统（--verbose / --quiet）
• 截图超时参数（--timeout）
• 百分比坐标忽略区域（--ignore 0,0,100%,20%）
• --version 查看版本
• 数据库上下文管理器
• 更多单元测试

优化：

• 阈值硬编码提取为常量
• 浏览器截图参数分离
• setup.py 依赖自动同步

详见 CHANGELOG.md

---

License

MIT License

---

🕐 kina-archive — 记录网页的每一个瞬间