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.x）；
• New Extractors Planned：计划新增的第三方提取器候选清单，按内容类型分类。

要读懂这份路线图，必须确立时间坐标：当前仓库版本号为0.9.35rc461（pyproject.toml），因此v0.7、v0.8 已是"过去式"，v0.9 正在收尾，v1.0 / v2.0 仍是未来愿景。与此同时，docs/Release-Notes-v0.9.md 作为 v0.9 的正式发布说明，恰好提供了"路线图规划 → 实际实现"之间最好的对照材料。

v0.7：Schema 改进——已基本落地的架构重构

路线图中v0.7的核心是"Schema improvements"，规划了 7 项架构级改造。从当前仓库源码看，这些规划绝大多数已经实现，只是部分实现方式与最初设想略有出入：

配置加载逻辑集中化

规划要求"把配置加载逻辑移入 settings.py"。当前仓库实际形成了一层独立的配置子系统 archivebox/config/（含common.py、collection.py、configset.py、django.py等模块），所有配置项以 pydantic 字段集中声明（例如搜索后端SEARCH_BACKEND_ENGINE: str = Field(default="sonic", ...)，见 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.py：

• get_plugin_catalog()通过PluginCatalog.discover(extra_plugin_dirs=[USER_PLUGINS_DIR], runtime="archivebox")在运行时发现插件目录，并缓存目录缓存（lru_cache）；
• get_plugin_name()展示了解析规则：带数字前缀的插件名会被剥掉前缀，例如10_title→title、26_readability→readability、50_parse_html_urls→parse_html_urls（archivebox/plugins/discovery.py）；
• 每个插件通过config.json声明自己的配置 Schema（discover_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_key=True, default=uuid7, editable=False, unique=True)（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_id（archivebox/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_length=100）、自动清理 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 声明django>=6.1，实际已越过 Django 5，直接运行在 Django 6.x 之上，并配套daphne>=4.2.1（ASGI 服务器）与psycopg[binary]>=3.2（PostgreSQL 后端）。

下表汇总 v0.7 规划与当前实现证据：

v0.8：安全加固——权限模型与回放隔离

路线图v0.8规划了三个安全方向，对应 v0.9 发布说明中的"Safer replay"与"More precise privacy"：

1. 为归档页面渲染增加 CSRF/CSP/XSS 防护：v0.9 将管理后台、API、Web UI 与归档页面来源分离；对可信的完整交互式回放使用隔离的*.localhost子域，对普通主机使用禁用 JavaScript 的更安全回放模式，降低不可信归档内容带来的风险（见 docs/Release-Notes-v0.9.md）。
2. 在 docker-compose.yml 中提供安全反向代理：仓库根目录的 docker-compose.yml 与 etc/nginx.conf 提供了现成的反向代理配置参考。
3. 为私有站点归档建立会话 Cookie / 认证的 UX 流程：这一条最终演进为Personas（身份档案）系统——用archivebox persona create --import=chrome <name>导入包含 Cookie 与登录态的 Chrome 用户目录，再用archivebox add --persona=personal <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 与 workers（pyproject.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 wizard（archivebox/core/setup_wizard.py），快照卡片、预览、操作菜单等 UI 全面重设计，官方声称即使在百万级快照数据库上，几乎所有页面都在约 100ms 内返回；
• 全文检索：✅ 已实现，且从路线图规划时的 sonic/ripgrep 扩展出三种后端——SEARCH_BACKEND_ENGINE默认sonic（archivebox/config/common.py），同时支持ripgrep与sqlite（测试中可见SEARCH_BACKEND_ENGINE="sqlite"的用法，见 archivebox/tests/conftest.py）；后端解析统一走 archivebox/search/backends.py；
• 可选 PostgreSQL：psycopg[binary]>=3.2（pyproject.toml），SQLite 仍为默认；
• 自动化 API 面：Django Ninja REST API（archivebox/api/）暴露快照、爬取、结果、标签、用户、token 等资源，另有 webhooks（archivebox/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 项能力，其中两项在当前仓库已有雏形：

1. 归档期间在页面上下文中运行用户脚本 / 扩展：部分推进。v0.9 引入的archivebox mcp服务（archivebox/mcp/server.py、archivebox/cli/archivebox_mcp.py）允许 AI Agent 执行爬取、搜索、管理归档等操作；依赖abx-plugins[opencode]进一步提供基于 Claude 的浏览器交互、自定义内容提取与重复结果清理插件（pyproject.toml）。这可以看作"在页面上下文中运行自定义逻辑"的 AI 驱动形态。
2. Persona 浏览器状态导入导出：Persona 系统配套了 archivebox/personas/importers.py、export_browser_state.js 与 open_browser.js，实现了"导入 Chrome 身份 → 选择身份归档"的闭环。
3. 基于 pywb 的无头浏览器会话录制与 WARC 回放：未在仓库中落地，仍属未来规划。
4. 归档代理支持（上游代理 + 下游代理归档）：未在仓库中落地，仍属未来规划。

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（长期项）

Smaller planned features（短期项）

新提取器规划：从单体清单到插件生态

路线图的 "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-dl（CAD 图纸）、aria2（通用下载）、podcast-archiver（播客）、bdfr（Reddit）、cutycapt（截图）、sourcemap（前端 sourcemap 下载）等。

其余候选按内容类型分类（括号内为路线图原始备注的用途说明）：

注意：以上列表中的"标注 stale"为路线图文档自注，表示作者认为该项目维护状态存疑。该清单属于规划候选而非已实现承诺，具体哪些已进入 abx-plugins 生态，应以运行时archivebox plugins list的发现结果为准。

版本历史与贡献指引

Past Releases 时间线

路线图记录的发布史（时间点为文档作者估计）：

对照 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