后端数据工程【免费下载链接】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 是一个开源的自托管互联网存档工具self-hosted internet archive它可以把任意 URL、浏览器历史、书签以及 Pocket、Pinboard 等服务的导出数据保存为 HTML、JS、PDF、媒体文件等静态快照。本文以官方文档首页 docs/index.rst 为骨架完整展开其快速上手流程中的每一条命令并结合仓库源码剖析init、install、add、status的底层实现最后给出官方文档的完整导航地图帮助读者从零开始搭建并理解自己的私有网页档案馆。项目定位面向个人与团队的自托管网页存档正如文档首页所声明的ArchiveBox 的定位是 The open-source self-hosted internet archive开源的自托管互联网档案馆。它与在线存档服务的关键区别在于数据自持所有存档内容保存在你自己的目录与数据库中不依赖任何第三方托管服务格式开放每个 URL 的存档结果以标准文件形式HTML、PDF、截图、warc 等落在文件系统中可通过 docs/Publishing-Your-Archive.md 介绍的方式对外发布输入广泛既支持直接传入 URL也支持从文本文件、RSS 订阅源、浏览器书签导出、Pocket/Pinboard 等服务的导出数据导入。仓库根目录 README.md 中对项目的功能描述也与此一致它接收 URL、浏览器历史、书签、Pocket/Pinboard 等输入保存 HTML、JS、PDF、媒体等各类存档产物。这意味着 index.rst 首页所呈现的是整个项目自托管、可保存、可检索、可发布能力的入口。五分钟快速上手从零到第一个存档index.rst 首页给出了一条完整的快速上手命令序列它覆盖了安装 → 初始化 → 装依赖 → 添加链接 → 查看状态的完整闭环mkdir my-archive; cd my-archive/ uv tool install --python 3.13 --prerelease explicit --upgrade archivebox0.9.0rc0,0.10 archivebox init archivebox install archivebox add https://example.com archivebox status下面逐条展开说明并结合源码解释每一条命令背后实际发生了什么。1. 用 uv 安装 ArchiveBox0.9.x 预发布版本uv tool install --python 3.13 --prerelease explicit --upgrade archivebox0.9.0rc0,0.10这条命令使用uv将 ArchiveBox 安装为全局工具tool--python 3.13要求使用 Python 3.13 作为运行环境--prerelease explicit明确允许安装预发布版本因为 0.9 尚未正式发布需要 rc 版本--upgrade如果已安装旧版本则升级到满足版本约束的最新版archivebox0.9.0rc0,0.10版本区间约束在 0.9.0 的候选发布版与 0.10 之间确保使用的是 0.9 系列。安装完成后archivebox命令即进入 PATH可在任意目录执行。官方文档 docs/Install.md 与 docs/Docker.md 分别介绍了原生安装与 Docker / Docker Compose 部署的更多细节macOS 与 Ubuntu 的amd64/arm64为官方支持平台见 docs/Quickstart.md。注意文档首页给出的安装命令面向 0.9.x 开发周期对于正式发布版本请以 docs/Install.md 中对应你平台的方式为准。2.archivebox init初始化集合init是创建新 ArchiveBox 集合collection的入口其命令行入口定义在 archivebox/cli/archivebox_init.pyarchivebox init # 可选参数 archivebox init --force # -f忽略当前目录中的无关文件强制初始化 archivebox init --quick # -q快速模式跳过对 snapshot 目录的重新检查 archivebox init --install # -s/--setup初始化后自动调用 install 安装依赖从 archivebox/cli/archivebox_init.py 的init()实现可以还原它的完整工作流安全校验调用check_not_inside_source_dir()拒绝在源码目录内初始化避免污染代码仓库环境判断检查当前目录是否为空、是否已存在index.sqlite3database_exists()据此决定是初始化新集合还是校验并升级已有集合若目录中已有非 ArchiveBox 文件但无数据库则会报错退出只有加--force才继续创建目录骨架依次创建archives/、sources/、users/、logs/目录并按配置项OUTPUT_PERMISSIONS8 进制权限字符串设置权限位生成集合标识与配置创建.archivebox_id文件写入该集合的唯一 ID随后调用write_config_file({SECRET_KEY: config.SECRET_KEY})生成ArchiveBox.conf配置文件详见下文准备数据库ensure_database_ready()确保 SQLite/PostgreSQL 可用setup_django()完成 Django 初始化随后apply_migrations()执行初始迁移建表创建管理员账号若配置中已设置ADMIN_USERNAME与ADMIN_PASSWORD则自动创建超级用户免去后续手工操作收尾提示如果集合中链接少于 25 个会打印后续操作提示——运行archivebox server后访问 Admin UI 完成 Web 端设置或用archivebox add links.txt添加链接。值得注意的是初始化完成后init会明确提示孤儿快照orphaned snapshot directories的导入与文件系统状态对账需要运行archivebox update。3.archivebox install安装存档所需的外部依赖install负责探测并安装 ArchiveBox 进行网页存档所需的外部二进制依赖Chromium、yt-dlp、wget 等其实现位于 archivebox/cli/archivebox_install.pyarchivebox install # 探测并安装全部依赖 archivebox install wget curl # 只安装 wget 与 curl archivebox install --binproviderspip yt-dlp # 只用 pip 提供者安装 yt-dlp archivebox install --binprovidersbrew,apt # 只用 brew/apt 安装全部依赖 archivebox install --dry-run # 只展示将要执行的动作不真正安装命令参数说明参数说明binaries位置参数要安装的插件名或二进制别名可传多个不传则安装全部--binproviders/-p允许使用的安装提供者逗号分隔pip、npm、brew、apt、env、custom默认*全部--dry-run/-d预演模式只打印将要执行的动作从源码看其内部逻辑分两条路径执行插件路径通过_resolve_install_targets()将用户传入的名字解析为插件名与二进制别名再经由 abx-dl 总线调用run_install()完成插件及其依赖的安装裸二进制路径_install_raw_binary_names()会为当前机器创建/更新Binary记录archivebox.machine.models.Binary将其置为QUEUED状态并调用run_due_binary()立即执行安装。同时install要求必须先有可用的数据库用于存储 Binary 记录因此若尚未初始化它会自动先执行init()。命令结束时还会调用archivebox version展示完整版本信息与已安装的二进制状态。archivebox init --install则把这两步合并为一条命令执行。4.archivebox add把 URL 加入存档队列add是 ArchiveBox 最核心的日常命令负责把 URL 列表加入新的 Crawl抓取任务并执行存档入口在 archivebox/cli/archivebox_add.pyarchivebox add https://example.com # 直接传 URL archivebox add your_urls.txt # 从 stdin 读入 URL 列表 archivebox add --depth1 https://example.com # 递归抓取一层链接 curl -fsSL https://getpocket.com/users/USER/feed/all | archivebox add # 从 RSS 流导入add支持从命令行参数与 stdin 两种方式收集输入_collect_input_urls()通过read_args_or_stdin()统一解析支持纯文本 URL、带#注释的行以及urls字段等格式当没有位置参数且 stdin 非 TTY 时自动读取 stdin。每个 URL 都会经过validate_url()校验。常用参数均在 archivebox/cli/archivebox_add.py 的 CLI 定义中声明参数默认值说明--depth/-d0递归存档链接的跳数仅允许 0–4--max-urls0本次抓取最多快照的 URL 数0 为不限制--crawl-max-size0整个抓取任务的总大小上限支持45mb、1gb等单位0 不限制--crawl-timeout0抓取任务总运行时间上限秒0 不限制--snapshot-max-size0单个快照的大小上限0 不限制--crawl-max-concurrent-snapshots继承配置单个抓取任务内并发快照数最小为 1--tag/-t逗号分隔的标签附加到每个快照上--url-allowlist/--domain-allowlist本次抓取的 URL/域名白名单--url-denylist/--domain-denylist本次抓取的 URL/域名黑名单--parserauto输入解析器auto、txt、html、rss、json、jsonl、netscape等--plugins/-p逗号分隔的提取插件列表如title,favicon,screenshot,singlefile--extract按输出类型选择插件如pdf、image等--personaDefault存档时使用的认证档案persona--only-new/--no-only-new继承ONLY_NEW配置是否跳过已存在的 URL--overwrite/--update是其别名--index-onlyFalse只把 URL 写入索引不立即存档--bgFalse后台模式入队后立即返回由后台 runner 处理从源码可以看到add的核心是创建一条Crawl记录并把相关运行参数冻结到crawl.config中如CRAWL_MAX_URLS、CRAWL_MAX_SIZE、CRAWL_TIMEOUT、SNAPSHOT_MAX_SIZE、URL_ALLOWLIST、URL_DENYLIST、PARSER、ONLY_NEW等然后由 runner 消费该 Crawl先为所有 URL 创建 Snapshot再运行提取插件解析器插件发现的新 URL 会继续生成子 Snapshot直到达到max_depth。执行模式有三种前台模式默认add进程直接接管前台 runner循环执行run_runner_worker([--crawl-id, str(crawl.id)], ...)直到 Crawl 封存SEALED期间会处理CtrlC中断并提示用archivebox run --crawl-idid恢复后台模式--bg仅入队并通过ensure_background_runner()确保有后台 runner 在跑如archivebox server或archivebox run --daemon仅索引模式--index-only只写入索引、不启动 runner。前台模式结束后会打印本次抓取的摘要crawl 输出目录相对DATA_DIR、Admin UI 管理链接、快照总数、总大小与总耗时。5.archivebox status查看集合健康与统计status打印整个集合的信息与统计实现见 archivebox/cli/archivebox_status.pyarchivebox status它依次输出以下几类信息主索引概况DATA_DIR下index.*文件的总大小与文件数链接统计SQL 主索引中的链接总数、archives/*/index.json中的传统链接详情数已索引 / 已存档status 为sealed/ 未存档的快照数磁盘占用递归扫描archives/目录含users/子目录得到的总体积、文件数与目录数当链接数超过常量MAX_STATUS_FS_DIR_SCAN 5000时自动改用数据库统计对Snapshot.output_size求和、统计非空output_files的 ArchiveResult 数量避免整盘递归扫描的性能问题文件系统一致性磁盘上存在的快照目录数present、与数据库记录匹配的目录数valid、以及没有对应数据库记录的孤儿目录数orphaned——出现孤儿目录时status会提示运行archivebox update自动导入用户与最近动态Admin UI 用户列表、最近登录时间、最近下载时间最近快照列表按downloaded_at倒序展示最近 10 个快照的下载时间、输出数量、存档状态、大小、标题与 URL。status是日常巡检集合健康状态最直接的命令索引是否损坏、磁盘占用是否异常、是否存在孤儿目录一目了然。集合的配置与磁盘布局init 之后发生了什么init完成后当前目录会形成 ArchiveBox 的集合骨架其目录结构与配置约定如下my-archive/ ├── ArchiveBox.conf # 集合配置文件INI 格式与数据库中的 Machine.config 双向同步 ├── index.sqlite3 # SQL 主索引PostgreSQL 时替换为外部数据库 ├── .archivebox_id # 集合唯一标识 ├── archives/ # 存档产物目录每个快照一个子目录 ├── sources/ # 导入的原始 URL 源文件 ├── users/ # 按用户组织的快照目录当前布局位于 archives/users/ 之下 └── logs/ # 日志目录配置文件的读写逻辑集中在 archivebox/config/collection.py几个值得注意的实现细节INI 配置与数据库双向镜像ArchiveBox.conf与数据库中Machine.config保持 1:1 同步——write_config_file()写文件后会镜像到数据库Machine.save()时又会调用mirror_machine_config_to_file()写回文件并通过模块级_MIRROR_IN_PROGRESS标志防止循环回写启动时对账sync_machine_and_file()在进程启动时合并文件与数据库两侧的配置键冲突时以修改时间更新的那一侧为准文件 mtime vs.Machine.modified_at按语义分组_resolve_section_for_key()会把不同的配置键归类到对应 INI section核心配置、服务器配置、PLUGINS等未知键统一落入SERVER_CONFIG而不丢失原子写入_write_file_if_changed()仅在内容变化时才原子重写文件避免热循环中的无谓磁盘写写前备份write_config_file()写新配置前会把旧内容备份为ArchiveBox.conf.bak若新配置解析失败则自动回滚。日常修改配置有两种方式直接编辑ArchiveBox.conf或运行archivebox config --set KEYVALUE配置文件头注释中明确指出了该命令。完整配置项参考 docs/Configuration.md存储与备份建议见 docs/Setting-Up-Storage.md。官方文档导航从首页出发的完整阅读路线index.rst 通过 toctree 引入了 docs/Contents.rst后者是整套官方文档的目录树。以仓库根目录为基准这份文档地图整理如下Overview概览文档内容docs/Home.md项目主页文档README.md项目根 README含功能特性与快速开始Getting Started入门文档内容docs/Quickstart.md约 5 分钟的上手流程安装、导出 URL 列表、添加链接、启动 Web UIdocs/Install.md各平台原生安装指南docs/Docker.mdDocker 与 Docker Compose 部署docs/Configuration.md全部配置项参考docs/Security-Overview.md安全模型与加固建议docs/Usage.mdCLI 与 Web UI 的完整用法Guides进阶指南文档内容docs/Setting-Up-Storage.md存档目录、外部存储与备份docs/Setting-up-Authentication.md身份认证与用户管理docs/Setting-up-Search.md全文搜索Sonic 等配置docs/Publishing-Your-Archive.md对外发布你的档案馆docs/Scheduled-Archiving.md定时自动存档docs/Chromium-Install.mdChromium 浏览器依赖安装docs/Upgrading.md版本升级说明docs/Upgrading-or-Merging-Archives.md升级或合并既有档案馆docs/Merging-Collections.md合并多个集合docs/Troubleshooting.md常见问题排查Architecture架构文档内容docs/ArchiveBox-Architecture-Diagrams.md系统架构图与组件关系API ReferenceAPI 参考文档内容docs/apidocs/index.rst由 Sphinx 生成的 Python API 文档覆盖archivebox.api、archivebox.cli、archivebox.config、archivebox.core、archivebox.crawls、archivebox.machine、archivebox.services等全部子模块文件系统布局详见 Usage 文档中的 Disk Layout 章节SQL APIUsage 文档中的 SQL Shell Usage 章节REST API官方 Demo 站点/api端点Meta元信息文档内容docs/Roadmap.md项目路线图docs/Changelog.md变更日志docs/Donations.md捐赠信息docs/Web-Archiving-Community.md网页存档社区资源对于希望从源码层面继续深入本文所讲命令的读者建议按以下路径阅读CLI 入口与参数archivebox/cli/下的archivebox_init.py、archivebox_install.py、archivebox_add.py、archivebox_status.py、archivebox_run.py配置系统archivebox/config/collection.py文件-数据库双向镜像、archivebox/config/common.py配置模型与读取、archivebox/config/constants.pyCONSTANTS路径常量抓取任务模型archivebox/crawls/models.pyCrawl、archivebox/core/models.pySnapshot、ArchiveResult服务层archivebox/services/runner.pyrunner 与安装流程、archivebox/services/crawl_service.py对应测试archivebox/tests/test_cli_init.py、archivebox/tests/test_cli_add.py、archivebox/tests/test_cli_install.py、archivebox/tests/test_cli_status.py等。下一步从能跑到用好走完init → install → add → status这四步你已经拥有了一个可用的私有网页档案馆。接下来的进阶路径建议启动 Web UI运行archivebox server按提示访问 Admin UI 完成首个管理员账号与BASE_URL的 Web 设置向导见 docs/Quickstart.md批量导入历史把浏览器书签/历史、Pocket、Pinboard 等导出为 URL 列表后通过 stdin 导入参见 docs/Quickstart.md 第 2 步配置存档行为编辑ArchiveBox.conf或用archivebox config --set调整SAVE_TITLE、ONLY_NEW、OUTPUT_PERMISSIONS等选项完整清单见 docs/Configuration.md定时自动存档按 docs/Scheduled-Archiving.md 配置每日增量存档数据一致性巡检定期运行archivebox status检查孤儿目录用archivebox update对账导入再配合 docs/Setting-Up-Storage.md 做好备份。至此从官方文档首页出发你已完整掌握 ArchiveBox 的安装、初始化、依赖管理、URL 添加与状态巡检的整条链路并理解了这些命令背后基于Crawl/Snapshot/Binary模型与配置文件双向镜像机制的实现原理。赞分享后端数据工程【免费下载链接】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点击查看免费下载相关推荐Starship 跨 Shell 快速安装与初始化配置指南官方首页文档解读Starship 跨 Shell 快速安装与初始化配置指南官方首页文档解读 本篇文章以 Starship 仓库中西班牙语官方首页文档 docs/es ES/CLI开发工具ArchiveBox自托管网页归档完整指南永久保存互联网内容的终极方案ArchiveBox自托管网页归档完整指南永久保存互联网内容的终极方案 在信息爆炸的互联网时代重要网页随时可能消失或改变。ArchiveBox作为开源自托管后端数据工程ArchiveBox 五分钟快速上手从零初始化、批量导入 URL 到启动 Web 归档服务ArchiveBox 五分钟快速上手从零初始化、批量导入 URL 到启动 Web 归档服务 本篇技术指南以 ArchiveBox 官方 Quickstart后端数据工程上一篇DataHub DynamoDB 元数据摄取进阶配置指南schema_sampling_size 与 include_table_item 实战解析下一篇Dgraph存储压缩比测试不同数据类型的压缩效果创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
