ArchiveBox 路线图全解：从 v0.7 Schema 演进到 v2.0 分布式归档的技术蓝图

ArchiveBox 路线图全解从 v0.7 Schema 演进到 v2.0 分布式归档的技术蓝图【免费下载链接】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导读本文以仓库内的官方路线图文档 docs/Roadmap.md 为骨架系统梳理 ArchiveBox 从 v0.7 到 v2.0 的功能演进规划并对照当前仓库实际代码当前版本为0.9.35rc461见 pyproject.toml逐一验证每个规划项的落地状态。读完本文你将掌握 ArchiveBox 的架构演进脉络Schema 重构、安全加固、性能工程化、无头浏览器控制、分布式归档愿景、哪些功能已经实现、哪些仍在规划中以及新提取器插件生态的扩展方式可作为评估、贡献和二次开发 ArchiveBox 的路线图参考。阅读提示路线图文档本身是一份动态规格说明书其中部分内容写于较早版本阶段因此本文采用规划 vs 现状双重视角先用文档原文还原规划意图再用当前仓库源码/发布说明确认落地情况。路线图文档的定位与版本坐标docs/Roadmap.md是 ArchiveBox 的官方贡献路线图由四大板块构成Planned Specification按v0.7 / v0.8 / v0.9 / v1.0 / v2.0分阶段的技术规划文档作者明确标注这不是定论只是粗略估计Major long-term changes / Smaller planned features长期与短期功能清单其中已完成的条目用 ✅ 标记Past Releases历史发布记录从 v0.1.x 到 v0.9.xNew Extractors Planned计划新增的第三方提取器候选清单按内容类型分类。要读懂这份路线图必须确立时间坐标当前仓库版本号为0.9.35rc461pyproject.toml因此v0.7、v0.8 已是过去式v0.9 正在收尾v1.0 / v2.0 仍是未来愿景。与此同时docs/Release-Notes-v0.9.md 作为 v0.9 的正式发布说明恰好提供了路线图规划 → 实际实现之间最好的对照材料。v0.7Schema 改进——已基本落地的架构重构路线图中v0.7的核心是Schema improvements规划了 7 项架构级改造。从当前仓库源码看这些规划绝大多数已经实现只是部分实现方式与最初设想略有出入配置加载逻辑集中化规划要求把配置加载逻辑移入 settings.py。当前仓库实际形成了一层独立的配置子系统 archivebox/config/含common.py、collection.py、configset.py、django.py等模块所有配置项以 pydantic 字段集中声明例如搜索后端SEARCH_BACKEND_ENGINE: str Field(defaultsonic, ...)见 archivebox/config/common.py运行时再注入 Django settings。相比路线图最初移入 settings.py的提法最终实现更彻底——配置被抽成了独立包便于被 CLI、Web、API、插件共享。提取器插件化从散落代码到插件目录规划要求把所有提取器移入插件风格目录并各自注册自己的配置同时批评当时提取器输出路径如output.pdf散落在代码库各处应上移为插件配置文件顶部的常量。从源码结构看这一规划在 v0.9 已经完成且比路线图更进一步提取器本体被拆到了外部包abx-plugins与abx-dl中见 pyproject.toml 的依赖声明仓库内的 archivebox/plugins/ 只保留发现、表单、钩子与视图四类集成点。插件发现机制在 archivebox/plugins/discovery.pyget_plugin_catalog()通过PluginCatalog.discover(extra_plugin_dirs[USER_PLUGINS_DIR], runtimearchivebox)在运行时发现插件目录并缓存目录缓存lru_cacheget_plugin_name()展示了解析规则带数字前缀的插件名会被剥掉前缀例如10_title→title、26_readability→readability、50_parse_html_urls→parse_html_urlsarchivebox/plugins/discovery.py每个插件通过config.json声明自己的配置 Schemadiscover_plugin_configs()并遵循{PLUGIN}_ENABLED、{PLUGIN}_TIMEOUT、{PLUGIN}_BINARY三类特殊配置键约定archivebox/plugins/discovery.py。由此输出路径散落各处的问题被命名空间化输出目录取代每个提取器写入自己可预期的文件夹这与 v0.9 发布说明中extractors now write to a predictable namespaced folder的描述一致。主键从时间戳迁移到 UUID / 哈希规划要求移除作为主键的 timestamps改用 hashes、UUIDs 或其他 slug。当前实现选择的是UUID具体为 uuid7 派生哈希Snapshot.id CompactUUIDField(primary_keyTrue, defaultuuid7, editableFalse, uniqueTrue)archivebox/core/models.py同时保留了基于 URL 的哈希作为派生产物url_hash属性返回sha256(url.encode()).hexdigest()[:8]archivebox/core/models.py迁移历史中可看到主键迁移的完整轨迹0029_migrate_archiveresult_to_uuid_pk、0030_alter_archiveresult_idarchivebox/core/migrations/。可以推断路线图中switch to sha256 of URL as unique link ID的长期目标最终落地为UUID 做主键 sha256 短哈希做 URL 指纹的组合方案兼顾唯一性与可读性。Tag 成为真正的 ManyToMany 模型规划要求把 Tag 变为与 Snapshots 关联的真实 ManyToMany 模型。当前源码完全落地Tag是继承ModelWithUUID的真实 Django 模型archivebox/core/models.py名称唯一max_length100、自动清理 HTML、提供slug派生属性通过中间模型SnapshotTag与 Snapshot 建立多对多关系表名为core_snapshot_tags并声明unique_together [(snapshot, tag)]archivebox/core/models.py。目录布局迁移系统与多快照支持规划要求建立独立于索引的文件夹布局迁移系统与允许同一站点跨时间保存多个快照。当前实现体现在文件系统迁移由迁移0028_alter_snapshot_fs_version及测试 archivebox/tests/test_snapshot_filesystem_migration.py 覆盖v0.9 的目录布局为archive/users/{user}/snapshots/YYYYMMDD/{domain}/{uuid}/archivebox/core/models.py 与 #L1426按日期 域名 快照 UUID 三级组织天然支持同一站点的多次快照并存路线图中提到的旧式#2020-01-01时间戳 hack 已被该布局取代。Django 从 3 升级到 6规划要求从 Django 3 升级到 Django 5。当前 pyproject.toml 声明django6.1实际已越过 Django 5直接运行在 Django 6.x 之上并配套daphne4.2.1ASGI 服务器与psycopg[binary]3.2PostgreSQL 后端。下表汇总 v0.7 规划与当前实现证据规划项v0.7落地状态实现证据配置加载逻辑集中化✅ 已实现独立 config 子系统archivebox/config/提取器移入插件目录并自注册配置✅ 已实现拆分为外部 abx-plugins/abx-dlarchivebox/plugins/discovery.py、pyproject.toml输出路径常量化、命名统一✅ 已实现命名空间化输出目录ModelWithOutputDir基类archivebox/base_models/models.py移除时间戳主键改用 hash/UUID✅ 已实现uuid7 主键 sha256 url_hasharchivebox/core/models.py、#L3131建立文件夹布局迁移系统✅ 已实现迁移 0028、test_snapshot_filesystem_migration.pyTag 变为真实 ManyToMany 模型✅ 已实现SnapshotTagcore_snapshot_tagsarchivebox/core/models.py支持同一站点多快照✅ 已实现YYYYMMDD/domain/uuid布局Django 3 → 5✅ 已超额完成Django ≥ 6.1pyproject.tomlv0.8安全加固——权限模型与回放隔离路线图v0.8规划了三个安全方向对应 v0.9 发布说明中的Safer replay与More precise privacy为归档页面渲染增加 CSRF/CSP/XSS 防护v0.9 将管理后台、API、Web UI 与归档页面来源分离对可信的完整交互式回放使用隔离的*.localhost子域对普通主机使用禁用 JavaScript 的更安全回放模式降低不可信归档内容带来的风险见 docs/Release-Notes-v0.9.md。在 docker-compose.yml 中提供安全反向代理仓库根目录的 docker-compose.yml 与 etc/nginx.conf 提供了现成的反向代理配置参考。为私有站点归档建立会话 Cookie / 认证的 UX 流程这一条最终演进为Personas身份档案系统——用archivebox persona create --importchrome name导入包含 Cookie 与登录态的 Chrome 用户目录再用archivebox add --personapersonal url按爬取任务选择身份命令示例见 docs/Release-Notes-v0.9.md。Persona 的实现位于 archivebox/personas/importers.py、models.py、forms.py配套 docs/Configuration.md 中的DEFAULT_PERSONA配置项——它比旧的COOKIES_FILE低层逃逸机制更推荐。另外v0.9 还落地了路线图未明确写到的按快照粒度的权限模型每个 Snapshot 可设为 public / unlisted / private权限在Snapshot.bulk_create时从 Crawl 继承并固化进配置archivebox/core/models.py。v0.9性能与工程化——规划与实现的偏差同样值得关注路线图v0.9只列了两条性能规划而实际 v0.9 的工程量远超于此。有意思的是这两条规划都没有按原样实现任务队列规划 huey实际落地为 workers 应用规划设想引入 huey把归档过程拆分为任务队列 工作池执行。从当前源码看最终方案没有采用 huey而是自建了一套基于数据库的可恢复任务体系archivebox/workers/ 应用承载队列语义基类ModelWithQueue含ACTIVE_STATE_LEASE_SECONDS、RETRY_AT_MAX等队列参数见 archivebox/workers/models.py常驻进程由 supervisord 管理archivebox server通过supervisor依赖拉起 daphne 与 workerspyproject.toml并配套supervisord_watchdog、runner_watch管理命令archivebox/workers/management/commands/archivebox/machine/models.py 中的Process模型将 Crawl、提取器运行都固化为数据库对象支持存活状态、恢复、调度与审计v0.9 发布说明称之为durable database objects。结果上路线图要解决的可中断恢复、多 worker 并行目标达成了但实现路径从引入 huey 队列库变成了数据库任务对象 进程监管。Chrome 常驻规划 pyppeteer2实际落地为插件化 Chrome 管理规划设想引入 pyppeteer2 包装 Chrome避免每个提取器都开关一次浏览器。实际方案是Chrome 行为由 abx-plugins 中的 chrome 提取器插件管理pyproject.toml 的abx-plugins依赖并在 v0.9 实现了按爬取任务的浏览器隔离——每个 Crawl 独立跟踪 Chrome 进程、profile、标签页与会话减少并发任务互相干扰资源清理更可靠docs/Release-Notes-v0.9.md。超预期落地的工程化内容v0.9 实际交付远超两条性能规划包括打包分发路线图Major long-term changes中 ✅ 标记的 pip/apt/pkg/brew 发行版全部落实v0.9 新增uv tool install archivebox原生安装路径Homebrew 与 Debian 包作为同一运行时的薄包装docs/Release-Notes-v0.9.md可选的 Web GUI✅ 已实现且 v0.9 加入了浏览器端 setup wizardarchivebox/core/setup_wizard.py快照卡片、预览、操作菜单等 UI 全面重设计官方声称即使在百万级快照数据库上几乎所有页面都在约 100ms 内返回全文检索✅ 已实现且从路线图规划时的 sonic/ripgrep 扩展出三种后端——SEARCH_BACKEND_ENGINE默认sonicarchivebox/config/common.py同时支持ripgrep与sqlite测试中可见SEARCH_BACKEND_ENGINEsqlite的用法见 archivebox/tests/conftest.py后端解析统一走 archivebox/search/backends.py可选 PostgreSQLpsycopg[binary]3.2pyproject.tomlSQLite 仍为默认自动化 API 面Django Ninja REST APIarchivebox/api/暴露快照、爬取、结果、标签、用户、token 等资源另有 webhooksarchivebox/api/webhooks.py与django-signal-webhooks依赖定时任务内置Crawl 与导入的周期调度直接存入数据库由服务端执行不再依赖外部 cron爬取限额与保留策略新增运行时长、深度、体积、输出保留等上限配置crawls/migrations/中可见add_crawl_limits、split_crawl_snapshot_size_limits、crawl_delete_at等迁移。v1.0无头浏览器全面控制——部分推进中路线图v1.0规划了 4 项能力其中两项在当前仓库已有雏形归档期间在页面上下文中运行用户脚本 / 扩展部分推进。v0.9 引入的archivebox mcp服务archivebox/mcp/server.py、archivebox/cli/archivebox_mcp.py允许 AI Agent 执行爬取、搜索、管理归档等操作依赖abx-plugins[opencode]进一步提供基于 Claude 的浏览器交互、自定义内容提取与重复结果清理插件pyproject.toml。这可以看作在页面上下文中运行自定义逻辑的 AI 驱动形态。Persona 浏览器状态导入导出Persona 系统配套了 archivebox/personas/importers.py、export_browser_state.js 与 open_browser.js实现了导入 Chrome 身份 → 选择身份归档的闭环。基于 pywb 的无头浏览器会话录制与 WARC 回放未在仓库中落地仍属未来规划。归档代理支持上游代理 下游代理归档未在仓库中落地仍属未来规划。v2.0联邦 / 分布式归档愿景——纯未来项路线图v2.0提出了四项分布化设想用 ZFS/merkle 树存储归档输出的子资源哈希、用 DHT 把 merkle 哈希:文件分片分配给节点、为哈希附加人类可读标签标题/URL/标签/文件类型等、以及分布式标签查询系统。在Major long-term changes中对应的条目是通过 DHT torrent/ipfs/ZeroNet 共享归档资产。从当前仓库源码看这些内容均无代码落地属于长期愿景仅可参考 docs/Setting-Up-Storage.md 等现有存储文档理解其基础。长期与短期功能清单盘点路线图正文中带 ✅ 标记的条目逐一对照当前仓库如下Major long-term changes长期项规划条目状态说明 / 证据pip / apt / pkg / brew 打包发行✅ 完成uv tool install archivebox、Homebrew/Debian 薄包装docs/Release-Notes-v0.9.md可选的 Web GUI✅ 完成archivebox/core/views.py、archivebox/templates/Django SQLite 迁移系统 JSON/HTML 导出✅ 完成archivebox/core/migrations/ 共 50 个迁移模块化内部组件✅ 完成以拆分 abx 包实现abxbus / abxpkg / abx-plugins / abx-dlpyproject.toml以 URL 的 sha256 作为唯一链接 ID✅ 以UUID 主键 sha256 短哈希落地url_hasharchivebox/core/models.py支持同一页面跨时间多快照✅ 完成YYYYMMDD/domain/uuid布局自定义 puppeteer 脚本 部分AI Agent 方向推进MCP abx-plugins[opencode]带不同访问权限的命名集合✅ 完成按快照权限public/unlisted/privatedocs/Release-Notes-v0.9.mdDHT torrent/ipfs/ZeroNet 共享❌ 未实现属 v2.0 愿景Smaller planned features短期项规划条目状态说明 / 证据正文提取为 Markdownreadability/mercury✅ 完成插件目录中可见26_readabilityarchivebox/plugins/discovery.py提取后的全文搜索sonic / ripgrep✅ 完成SEARCH_BACKEND_ENGINE默认 sonic支持 ripgrep/sqlitearchivebox/search/backends.py下载 YouTube 等视频网站的字幕✅ 完成索引化仍为 TODO路线图自注TODO: submit subtitle files to the full-text search index精选图 / 缩略图提取❌ 未见独立实现仍属候选关键词自动打标签类似 Pocket❌ 未实现仍属候选自动生成摘要段落NLP❌ 未实现仍属候选原站不可达时从 archive.org 补抓❌ 未实现仍属候选用 ArchiveNow 推送到多个第三方服务❌ 未实现仍属候选新提取器规划从单体清单到插件生态路线图的 New Extractors Planned 板块列出了大量第三方下载工具候选。在 v0.7 插件化改造完成后这些提取器不再直接写进本仓库而是进入 abx-plugins 生态由PluginCatalog在运行时发现archivebox/plugins/discovery.py。仓库本身只保留插件集成点与表单/视图archivebox/plugins/forms.py、archivebox/plugins/views.py。路线图中明确点名的新增提取器候选包括gallery-dl图库、forum-dl论坛、scihub-dl论文、cad-dlCAD 图纸、aria2通用下载、podcast-archiver播客、bdfrReddit、cutycapt截图、sourcemap前端 sourcemap 下载等。其余候选按内容类型分类括号内为路线图原始备注的用途说明类别候选工具用途说明社交媒体instaloaderInstagram、tdlTelegram、tiktokget / TikTok-Downloader-Bot / tiktok-downloader / tiktok-scraper / tiktok-save / tiktok-to-ytdlp 等TikTok 系列、twspace-dlTwitter Spaces标注 stale视频 / 直播you-get、TwitchDownloader / twitch-dlTwitch、lux通用音视频、cobalt通用音视频、webvideo-downloaderBilibili/iQIYI/Tencent Video/MGTV/WeTV、svtplay-dl、yle-dl、widevine-dl加密视频音频 / 音乐streamripQobuz/Tidal/Deezer/SoundCloud、music-dl / musicdl、bandcamp-dl、spotify-downloader / SpotiFlyer / spotify-dl、qobuz-dl、podgrab标注 stale等图片 / 漫画gallery-dl标注 ⭐、imgbrd-grabber、comic-dl / animdl / mangal / monkey-dl动漫漫画、docker-icloudpd、Image-Downloader文本 / 论坛forum-dl标注 ⭐、newspaper4k标注 ⭐、SCrawler多平台爬取、article-extractor、RedditDownloader / bulk-downloader-for-reddit标注 staleMOOC / 教育coursera-dl、khan-dl、Moodle-DL、acloud-dl、udemy-downloader、Mooc_Downloader标注 stale、edx-dl标注 stale、Skillshare-DL标注 stale等再归档 / WARCwayback-machine-downloader、Archive.org-Downloader、grab-site、archivenow、warcraft、wasapi-downloader、warc_downloader、heritrix3、Website-downloader其他Hitomi-Downloader、BBDown / biliup / bilili / BilibiliDownBilibili 系列、gplaycliGoogle Play、kemono-dlPatreon/gumroad、hakuneko漫画、dli-downloader印度数字图书馆、gaana-dl标注 stale、matterport-dl虚拟看房标注 stale注意以上列表中的标注 stale为路线图文档自注表示作者认为该项目维护状态存疑。该清单属于规划候选而非已实现承诺具体哪些已进入 abx-plugins 生态应以运行时archivebox plugins list的发现结果为准。版本历史与贡献指引Past Releases 时间线路线图记录的发布史时间点为文档作者估计版本阶段备注v0.1.x✅ 已发布约 2017 年前早于 git 历史v0.2.x✅ 已发布约 2018/12v0.3.x✅ 已发布约 2019/03v0.4.x✅ 已发布约 2019/04v0.5.x✅ 已发布约 2020/11v0.6.x✅ 已发布约 2021/032022️ 维护者休假期路线图自注 sabbatical / coding hiatusv0.7.x✅ 已发布约 2023/11架构重构主线v0.8.x 发布中约 2024/05安全主线v0.9.x 路线图写作时的下一版即当前仓库所在版本线对照 pyproject.toml 的0.9.35rc461可以确认 v0.9 已进入候选发布阶段。UI/UX 改进方向路线图列出的 UI/UX 改进议题快照管理、归档浏览、Django 升级相关 UI、大规模集合可用性等大部分已在 v0.9 通过全站 UI 重设计覆盖快照卡片化、预览、操作菜单、归档结果视图、移动端适配、实时进度展示爬取/快照/进程/提取器状态在运行中实时更新。需要进一步了解可参考 docs/Quickstart.md 与 docs/Usage.md。给贡献者的实践提示路线图末尾有一段重要声明原文措辞大意对于这些重大长期任务请先联系维护者再动手——其中多项工作已在进行中与已有工作不一致的 PR 可能被拒绝。结合当前仓库贡献者应重点熟悉提取器/插件开发通过 archivebox/plugins/hooks.py 与外部 abx-plugins 的插件契约接入遵循命名空间化输出目录约定Schema 变更走 Django 迁移系统archivebox/core/migrations/并为文件系统布局变更配套迁移测试参考 archivebox/tests/test_snapshot_filesystem_migration.py测试基线pytest测试集中在 archivebox/tests/配置见 pyproject.toml。结语从docs/Roadmap.md出发对照当前仓库可以看到一条清晰的主线v0.7 完成了Schema 与架构现代化插件化、UUID 化、Tag 模型化、Django 升级v0.8 完成了安全加固按快照权限、回放隔离、Persona 认证v0.9 则以远超原规划的实际工程量交付了性能与工程化数据库化任务体系、多后端搜索、PostgreSQL、REST API、MCP、内置调度与打包发行。而 v1.0 的无头浏览器全面控制仍部分处于愿景阶段v2.0 的分布式归档则完全是未来蓝图。这份路线图最有价值的地方正在于它让读者可以同时看到当初想做什么与最终做成了什么之间的演进关系——这对评估 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考