后端数据工程【免费下载链接】ArchiveBox Open source self-hosted web archiving. Takes URLs/browser history/bookmarks/Pocket/Pinboard/etc., saves HTML, JS, PDFs, media, and more...项目地址https://gitcode.com/gh_mirrors/ar/ArchiveBox点击查看免费下载导读本文档基于 ArchiveBox 仓库中 old/Architecture.md 所描述的产品功能架构蓝图展开系统梳理了这个开源自托管网页归档工具在 UI 层的五大核心应用模块——采集入口Getting Started、Crawls爬虫、Scheduler调度器、SourcesURL 来源管理与 Alerts告警。文章不仅完整继承原文档对每个页面交互流程、可选配置项与底层数据模型的描述还结合 archivebox/crawls/models.py、archivebox/personas/models.py、archivebox/core/models.py 等源码深入讲解Crawl、CrawlSchedule、Persona、ArchiveResult等核心模型的真实字段与调用链。读完本文你可以理解 ArchiveBox 从输入 URL到产出快照的完整数据流掌握爬虫深度、调度频率、来源类型与告警条件在 UI 与代码层面的真实落点并据此规划自己的归档自动化方案。一、架构总览一个 URL 进入 ArchiveBox 的五条通道old/Architecture.md开篇即用 What do you want to capture? 定义了 ArchiveBox UI 的产品形态它不是一个单一的添加链接页面而是围绕五种采集诉求分别设计了独立的应用入口用户诉求对应页面/模块核心能力现在保存一些 URL[Add page]添加页粘贴 URL、上传含 URL 的文件、从远程位置拉取 URL从浏览器导入[Import page]导入页浏览器扩展、iOS/Android App、bookmarks.html、browser_history.sqlite3从第三方书签服务同步[Sync page]同步页Pocket、Pinboard、Instapaper、Wallabag、Zapier/N8N/IFTTT 等按计划定时归档[Schedule page]调度页由 Scheduler App 支撑的周期性快照归档整个网站[Crawl page]爬虫页深度、外链、父级链接、页数、请求频率等控制值得说明的是原文档中这条 Getting Started 清单带有明显的产品规划色彩部分条目在代码中尚未以独立 App 形式落地因此本文将其定位为架构蓝图来解读并结合仓库中已经成型的crawls、personas、core等 Django App 还原其在实现层的真实形态。所有从代码推断的内容本文均会给出对应源码路径以便读者自行验证。二、Crawls App网站级递归归档的执行单元2.1 交互层要回答的问题Crawls 是原文档中描述最完整、也是当前仓库实现最成熟的模块。从 UI 交互看创建一次爬虫需要回答What are the starting URLs?—— 起始 URL/域名列表How many hops to follow?—— 递归跟随多少跳深度Follow links to external domains?—— 是否跟随外链Follow links to parent URLs?—— 是否跟随父级链接Maximum number of pages to save?—— 最多保存多少页面Maximum number of requests/minute?—— 每分钟最大请求数限速。2.2 实现层Crawl 模型与配置快照在代码中这些交互选项对应 archivebox/crawls/models.py 第 150 行起的Crawl模型class Crawl(ModelWithDeleteAfter, ModelWithOutputDir, ModelWithConfig, ModelWithHealthStats, ModelWithQueue): urls models.TextField(blankFalse, nullFalse, help_textNewline-separated list of URLs to crawl) config models.JSONField(defaultdict, nullTrue, blankTrue) permissions models.GeneratedField(...) # 由 config__PERMISSIONS 生成 max_depth models.PositiveSmallIntegerField(default0, validators[MinValueValidator(0), MaxValueValidator(4)]) tags_str models.CharField(max_length1024, blankTrue, nullFalse, default) persona models.ForeignKey(personas.Persona, on_deletemodels.SET_NULL, nullTrue, blankTrue) status ModelWithQueue.StatusField(defaultModelWithQueue.StatusChoices.QUEUED) retry_at ModelWithQueue.RetryAtField(defaulttimezone.now)从源码可以看出几个关键设计URL 输入格式灵活urls是以换行分隔的 URL 文本但 crawls/models.py 第 693-714 行 的_iter_url_lines()显示它同时支持纯文本行与JSONL 记录每行一个 JSON 对象取其中的url字段并且以#开头的行会被当作注释跳过。这意味着你可以在起始 URL 列表里混入带元数据的 JSONL 条目。深度有硬上限max_depth的取值范围被限定在 04默认 0只抓起始页本身避免失控的无限递归。配置以快照固化新建Crawl时save()会调用 archivebox/config/common.py 中的build_crawl_config_snapshot(personapersona, overridesconfig)将当时的全局配置、Persona 配置与本次覆盖项合并成一个 JSON 快照存入config字段。这样即使后续修改了全局配置历史爬虫仍按创建时的配置执行实现配置冻结迁移0018_freeze_crawl_config_snapshots正是为此设计。2.3 限流与配额CRAWL_MAX_URLS 与并发控制原文档中Maximum number of pages to save在代码层面对应配置项CRAWL_MAX_URLS。count_urls_for_limit()crawls/models.py 第 716-730 行会统计已入队 已快照的去重 URL 数量remaining_url_capacity()/remaining_snapshot_capacity()则分别计算剩余可入队与可快照的配额从而让直接输入的 URL与递归发现的 URL共享同一个总量预算。Maximum number of requests/minute对应的则是CRAWL_MAX_CONCURRENT_SNAPSHOTS最大并发快照数。crawls/models.py 第 331-336 行 会将该配置值规范化为不小于 1 的整数并在其为空时从配置中移除由爬虫运行器archivebox/services/runner.py在实际执行时据此限流。2.4 生命周期QUEUED → STARTED → SEALED 与暂停/取消Crawl的状态机定义在 crawls/models.py 第 179-195 行初始状态QUEUED激活状态STARTED终态SEALED归档封存RUNNABLE_STATES (QUEUED, STARTED)INACTIVE_STATES (PAUSED, SEALED)FINAL_STATES (SEALED,)封存后可按DELETE_AFTER策略自动清理delete_after_final_statuses。代码还提供了三个面向 UI/API 的管理操作pause()/resume()暂停爬虫时会将所有处于开放状态的子 Snapshot 一并唤醒/暂停crawls/models.py 第 227-250 行cancel()将爬虫与所有活动子快照标记为待封存交由运行器执行清理钩子crawls/models.py 第 252-283 行标签扇出修改tags_str时apply_snapshot_tag_diff()会以分块bulk_create的方式把新增/删除的标签同步到该爬虫的全部子 Snapshot 上crawls/models.py 第 412-450 行。2.5 CLI 入口爬虫的命令行入口位于 archivebox/cli/archivebox_crawl.pyarchivebox crawl支持--depth/-d默认 0、--tag/-t逗号分隔标签、--status/-s初始状态等创建参数以及按状态、URL 包含、最大深度过滤和分页查询参数archivebox crawl pause / resume / seal子命令配合--dry-run可安全地批量操作爬虫状态。这与 UI 层的 crawls/admin.py 及 REST APIarchivebox/api/v1_crawls.py共享同一套模型与状态机。三、Scheduler AppCrawlSchedule 与定时触发机制3.1 交互层要回答的问题调度页Schedule page在原文档中需要用户配置What URL(s)?—— 归档哪些 URLHow often?—— 多久跑一次Do you want to discard old snapshots after x amount of time?—— 是否在 x 时间后丢弃旧快照对应DELETE_AFTERAny filter rules?—— 过滤规则Want to be notified when changes are detected?—— 变更检测后是否通知跳转到 Alerts Appredirect[Alerts app/create new alert(crawlself)]。此外原文档还给出了两条关键的伪代码/查询语句直接点明了调度器的数据模型Choose Schedule check for new URLs: Schedule.objects.get(pkxyz) Choose Destination Crawl to archive URLs using: Crawl.objects.get(pkxyz)3.2 实现层CrawlSchedule 与模板 Crawl在代码中调度器对应 archivebox/crawls/models.py 第 42 行 起的CrawlSchedule模型Django 应用标签为crawlsverbose name 为 Scheduled Crawlclass CrawlSchedule(ModelWithUUID, ModelWithNotes): template: Crawl models.ForeignKey(Crawl, on_deletemodels.CASCADE, nullFalse, blankFalse) schedule models.CharField(max_length64, blankFalse, nullFalse) is_enabled models.BooleanField(defaultTrue) config models.JSONField(defaultdict, nullTrue, blankTrue) label models.CharField(max_length64, blankTrue, nullFalse, default)这里印证了原文档的设计调度器本身不保存 URL 列表而是通过template外键指向一个模板 Crawl这个模板 Crawl 承载urls、max_depth、tags_str、persona与notes。每次到点触发时enqueue()crawls/models.py 第 126-147 行会基于模板复制出一个新的Crawl实例return Crawl.objects.create( urlstemplate.urls, configbuild_crawl_config_snapshot(personapersona, overridescrawl_config), max_depthtemplate.max_depth, tags_strtemplate.tags_str, persona_idtemplate.persona_id, labellabel, notestemplate.notes, scheduleself, statusCrawl.StatusChoices.QUEUED, retry_atqueued_at, created_bytemplate.created_by, )调度配置项SCHEDULE_KIND支持两种模式kind属性crawls/models.py 第 110-112 行crawl默认每次触发复制一个普通 Crawl 入队update触发时不创建 Crawl而是直接调用archivebox_update.run_scheduled_maintenance()执行全库维护dispatch()方法crawls/models.py 第 114-124 行。3.3 调度频率别名与 cron 表达式原文档在调度频率处列出了 1 分钟 / 5 分钟 / 1 小时 / 1 天等选项。实现层位于 archivebox/crawls/schedule_util.py基于croniter解析支持别名minute/minutely→* * * * *hour/hourly→0 * * * *day/daily→0 0 * * *week/weekly→0 0 * * 0month/monthly→0 0 1 * *year/yearly→0 0 1 1 *支持标准 cron 表达式如0 */6 * * *validate_schedule()在save()时即校验合法性crawls/models.py 第 77 行非法值会抛出ValueErrornext_run_for_schedule()计算下一次触发时间CrawlSchedule.next_run_at与is_due()crawls/models.py 第 102-108 行据此判断是否到点由运行器轮询调度。3.4 过滤器与 ONLY_NEW 语义原文档中调度器的 Filters 配置包括URL patterns to include / exclude—— 包含/排除的 URL 模式ONLY_NEW—— 三选一语义Ignore URLs if already saved once已保存过就忽略/save URL each time it appears每次出现都保存/only save is last save x time ago仅当上次保存超过 x 时间后。这些规则在实现层对应归档前的是否值得保存判断逻辑。测试用例 archivebox/tests/test_config_ONLY_NEW.py 与 archivebox/tests/test_config_URL_filters.py 分别覆盖了 ONLY_NEW 模式与 URL 过滤器的行为插件系统通过 archivebox/plugins/hooks.py 中的钩子如 URL 是否应被归档、是否应再次抓取接入这一决策点。CLI 侧对应archivebox schedule子命令archivebox/cli/archivebox_schedule.py。四、Sources AppURL 来源管理与多路导入4.1 交互层要回答的问题Sources App 在架构蓝图中负责管理 ArchiveBox 从中拉取 URL 的来源核心是一个Wizard向导流程Choose URI选择来源地址文档勾选列表包括Web UI / CLI本地文件系统路径监视目录中新增的含 URL 文件远程 URLRSS/JSON/XML feedChrome 浏览器配置同步用 gmail 登录拉取书签/历史Pocket、Pinboard、Instapaper、Wallabag 等第三方服务Zapier、N8N、IFTTT 等自动化平台远程服务器 FTP/SFTP/SCP 路径AWS/S3/B2/GCP 对象存储桶XBrowserSync登录拉取书签。Choose extractor选择提取器auto/RSS/Pocket/ 等自动嗅探或指定格式解析。Specify extra Config补充凭据credentials、提取器调优项如verify_ssl、cookies。Provide credentials提供凭据API Key、用户名/密码或 OAuth。4.2 实现层对照需要说明的是原文档描绘的 Sources App 是一个覆盖面很广的规划蓝图。在当前仓库实现层与从外部拉取 URL直接对应的是 archivebox/personas/importers.py浏览器书签/历史导入以及archivebox add的多输入形态见下文 4.3。而文档中勾选的 S3/B2/GCP、XBrowserSync、Zapier/N8N/IFTTT 等更多属于可扩展的集成方向仓库以插件系统archivebox/plugins/提供挂载点。因此建议读者把这一节当作产品形态清单理解并优先使用当前版本已稳定的入口。4.3 Add 页的多形态输入现有版本的实际入口原文档 Getting Started 中 [Add page] 的三个能力——粘贴 URL、上传含 URL 的文件、从远程位置拉取 URL——在命令行侧由archivebox addarchivebox/cli/archivebox_add.py完整承接支持直接传入 URL 或本地文件路径标准输入stdin管道喂入 URL 列表从远程 URL 拉取内容并解析其中的链接解析格式包括bookmarks.html导出、RSS/XML feed、Markdown、纯文本等配合--parser指定解析器。测试 archivebox/tests/test_cli_piping.py 验证了 stdin/管道输入链路archivebox/tests/test_cli_add.py 覆盖了本地文件与远程 URL 的解析行为。这一入口同时覆盖了原文档中 [Import page] 的上传 bookmarks.html 导出文件能力而浏览器扩展 / iOS / Android App 则通过 REST APIarchivebox/api/v1_api.py接入。五、Alerts App条件触发与多渠道通知5.1 交互层要回答的问题Alerts App 是原文档中数据模型定义最具体的一个模块完整交互流程分为四步① 创建告警选择条件condition站点宕机某 URL 的 Snapshot 成功率低于 x%站点视觉变化超过 x%截图 diff站点文本内容变化超过 x%文本 diff出现某关键词 / 消失某关键词某个 AI prompt 返回了某些结果。② 选择告警阈值threshold任一条件满足any condition is met所有条件满足all conditions are met对 x% 的 URL 满足在 x% 的时间内满足。③ 选择通知方式List[AlertDestination]最大告警频率maximum alert frequency目标类型email / Slack / Webhook / Google Sheet / logfile目标信息邮件地址、Slack channel、Webhook URL。④ 选择作用域scope文档用返回 QuerySet 的查询精确定义了三层对象ArchiveResult 作用域按提取器所有提取器 / 仅截图 / 仅 readability-mercury 文本 / 仅视频 / 仅 html / 仅 headersSnapshot 作用域按 URL所有域名 / 特定域名 / 某标签下所有域名 / 某标签分类下所有域名 / 匹配某正则的 URLCrawl 作用域所有爬虫 / 特定爬虫 / 某用户的爬虫 / 使用某 Persona 的爬虫。5.2 实现层AlertDestination 模型草案原文档直接给出了数据模型草案class AlertDestination(models.Model): destination_type: [email, slack, webhook, google_sheet, local logfile, b2/s3/gcp bucket, etc.] maximum_frequency filter_rules credentials alert_template: JINJA2 json/text template that gets populated with alert contents对照当前仓库Alert/AlertDestination尚属于架构蓝图阶段仓库中尚未存在同名的 Django 模型可通过archivebox/api/admin.py与archivebox/core/models.py的模型清单确认。因此本节内容应按设计稿阅读alert_template使用 JINJA2 模板填充告警内容maximum_frequency负责限频credentials存放各目标渠道的凭据。5.3 支撑该模块的现有设施虽然 Alerts App 尚未落地但构建它所需的底层设施在仓库中已经存在可以视为该模块的实现基础ArchiveResult 状态与提取器分类archivebox/core/models.py 第 3761 行 的ArchiveResult模型拥有statusqueued/started/paused/backoff/succeeded/failed/skipped/noresults与plugin字段第 3901 行标识产生该结果的提取器插件按提取器筛选 ArchiveResult的告警作用域可以直接建立在这两个字段上。Snapshot 聚合统计ArchiveResult.status_counts()core/models.py 第 3866-3870 行与snapshot_ids_with_majority_status()第 3872-3890 行提供了计算某个 Snapshot 的成功率/失败率所需的聚合查询站点宕机类条件可直接复用。Webhook 基础设施archivebox/api/webhooks.py 已实现设置变更信号的 webhook 推送测试 archivebox/tests/test_settings_signal_webhooks.py 覆盖了其行为——Alerts 的 Webhook 通知目标可复用该通道。Persona 作用域Crawl 上的persona外键见 2.2 节使按 Persona 筛选爬虫天然成立。关键词/内容差异检测快照的文本与截图产物由提取器产出如 readability 文本、screenshot差异计算可基于core/preview_util.py的预览产物配合 archivebox/services/archive_result_service.py 的产物管理实现。5.4 Persona告警与爬虫共享的浏览器身份由于告警作用域多次引用 Persona这里补充其实现细节。archivebox/personas/models.py 第 84 行 的Persona模型继承ModelWithConfig表示一个浏览器归档会话身份每个 Persona 派生四类路径CHROME_USER_DATA_DIR→PERSONAS_DIR/name/chrome_profileCHROME_DOWNLOADS_DIR→PERSONAS_DIR/name/chrome_downloadsCOOKIES_FILE→PERSONAS_DIR/name/cookies.txt存在时AUTH_STORAGE_FILE→PERSONAS_DIR/name/auth.json存在时。get_derived_config()会把ACTIVE_PERSONA、PERSONAS_DIR等自动注入配置这意味着用登录态抓取某个站点与按 Persona 限定告警范围在配置层面是自洽的。导入浏览器状态的脚本位于 archivebox/personas/importers.py 与 archivebox/personas/export_browser_state.js。六、从架构蓝图到当前实现演进关系小结综合上文可以把old/Architecture.md中的五大模块与当前仓库实现做一张对照表帮助读者快速定位设计稿与代码的对应关系架构蓝图模块当前实现落点状态Add page粘贴/上传/远程拉取archivebox/cli/archivebox_add.py、REST API已实现Import page浏览器导入archivebox/personas/importers.py、浏览器扩展/移动端 API已实现桌面端为主Sync page第三方书签服务archivebox add --parser...多格式解析部分实现其余靠插件扩展Crawls App网站爬取archivebox/crawls/models.py 的Crawl、archivebox/cli/archivebox_crawl.py已实现Scheduler App定时调度CrawlSchedule模型、archivebox/crawls/schedule_util.py、archivebox/cli/archivebox_schedule.py已实现Sources App来源管理向导插件系统 archivebox/plugins/ 提供挂载点蓝图为主Alerts App条件告警依赖ArchiveResult/Snapshot统计与 archivebox/api/webhooks.pyAlertDestination模型草案见原文档蓝图为主这条演进路径也提示了一个使用要点以当前仓库版本为准。新增 URL 用archivebox add整站递归抓取用archivebox crawl周期性归档用archivebox schedule浏览器书签/历史导入用 Persona 相关命令archivebox/cli/archivebox_persona.py而告警与统一来源管理则适合关注 AGENTS.md 与插件钩子文档以跟踪后续迭代。结语old/Architecture.md是一份面向产品与工程的功能架构蓝图它把用户想捕获什么拆解成了 Add / Import / Sync / Schedule / Crawl 五类交互并在数据层勾勒出CrawlSchedule → Crawl → Snapshot → ArchiveResult的归档流水线与AlertDestination告警模型。通过对照 archivebox/crawls/models.py、archivebox/core/models.py 与 archivebox/personas/models.py 的源码本文验证了其中 Crawls 与 Scheduler 两大模块已经以完整的 Django 模型、cron 调度工具与 CLI 命令落地而 Sources 与 Alerts 仍以设计稿形式存在其底层依赖提取器状态、聚合统计、Webhook 通道、Persona 身份均已就绪。对于希望深入 ArchiveBox 二次开发或自动化集成的读者这份对照关系可以作为阅读源码的路线图。赞分享后端数据工程【免费下载链接】ArchiveBox Open source self-hosted web archiving. Takes URLs/browser history/bookmarks/Pocket/Pinboard/etc., saves HTML, JS, PDFs, media, and more...项目地址https://gitcode.com/gh_mirrors/ar/ArchiveBox点击查看免费下载相关推荐OpenProject 快速入门从零安装、启动并验证你的项目管理平台OpenProject 快速入门从零安装、启动并验证你的项目管理平台 OpenProject 是一款开源的 Web 项目管理软件覆盖任务管理、甘特图、敏捷看后端前端项目管理企业应用协同办公20亿参数秒级响应GLM-Edge-V-2B重新定义边缘AI多模态交互20亿参数秒级响应GLM Edge V 2B重新定义边缘AI多模态交互 导语 智谱AI最新发布的GLM Edge V 2B多模态模型以20亿参数实现每秒70网页爬虫后端Transformers Image Processor 图像处理器完全指南从像素值预处理到后端架构Transformers Image Processor 图像处理器完全指南从像素值预处理到后端架构 图像处理器Image Processor是 T后端数据工程上一篇无需注销EnvPane如何实现macOS环境变量实时生效的技术揭秘下一篇告别能看不能下猫抓插件浏览器资源嗅探使用全攻略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考