ArchiveBox 集合合并完全指南从旧版archive/timestamp/目录迁移到数据库感知的合并【免费下载链接】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 集合Collection合并的实战技术指南核心场景是将两个或多个旧版 ArchiveBox 集合的数据合并为一个新集合并正确处理数据库记录与磁盘快照目录之间的所有权关系。读完本文你将掌握旧版 timestamp 目录的导入合并流程、当前版本集合的正确合并思路、archivebox update三阶段迁移的底层原理以及直接操作index.sqlite3修改/新增用户记录的方法。为什么直接复制目录无法合并当前版本的集合ArchiveBox 的数据集合由两大部分组成数据库SQLiteindex.sqlite3与磁盘上的快照输出目录。当前版本以本仓库为准文件系统布局版本为0.9.4见 archivebox/core/models.py 中_fs_current_version()的快照数据存放在archive/users/username/timestamp/布局之下而Crawl、Snapshot、用户、权限以及状态机记录全部由数据库拥有。因此直接复制当前版本的archive/users/...目录树是无法安全合并的数据库才是这些记录的唯一权威来源磁盘目录只是它的输出投影archivebox init故意不导入孤立orphaned的当前布局目录。这一点在 archivebox/cli/archivebox_init.py 中有直接证据初始化时打印Skipping orphan snapshot import during init.并提示用户要导入孤立的快照目录并协调文件系统状态请运行archivebox update。结论对于当前版本的集合合并必须走数据库感知database-aware的迁移路径或者导出源 URL 后重新归档到目标集合。单独复制当前版本的 Snapshot 目录本质上是一次备份操作而不是一次合并。遗留legacy集合的合并5 步工作流下面这套流程专门用于旧版集合——其特征是真实快照目录位于archive/timestamp/目录名是纯数字时间戳。archivebox update可以把这些遗留目录导入到一个全新的索引中。[!WARNING] 合并前必须备份每一个集合。确认源条目是真实包含数据的遗留 timestamp 目录并检查路径冲突而不是允许一个集合覆盖另一个集合。第 1 步将两个旧集合都升级到最新版本先按照 docs/Upgrading.md 中的升级说明将参与合并的每个旧集合升级到当前 ArchiveBox 版本cd /path/to/archivebox1/data archivebox init archivebox status cd /path/to/archivebox2/data archivebox init archivebox status # ... 如果要合并超过两个集合对每个集合重复相同操作升级时archivebox init会校验并更新已有集合检查待执行的 Django 迁移并自动应用同时创建/校验archive/、sources/、logs/等目录结构见 archivebox/cli/archivebox_init.py。archivebox status用于确认两个集合都已就绪、无挂起的迁移。第 2 步创建用于存放合并结果的全新空集合mkdir -p /path/to/archivebox_new/data cd /path/to/archivebox_new/data archivebox init新集合会生成自己的index.sqlite3、ArchiveBox.conf与目录骨架。它不会导入任何旧数据——这正是后面导入步骤的前提。第 3 步把每个旧集合中的真实遗留archive/timestamp/目录复制进来rsync --archive --infoprogress2 /path/to/archivebox1/data/archive/ /path/to/archivebox_new/data/archive/ rsync --archive --infoprogress2 /path/to/archivebox2/data/archive/ /path/to/archivebox_new/data/archive/ # ... 如果要合并超过两个集合对每个集合重复相同操作注意这里只复制真实遗留数据目录不要复制当前版本的archive/users/树。--infoprogress2用于显示总体进度--archive保留权限与时间戳属性。第 4 步在新集合中运行archivebox update导入遗留目录cd /path/to/archivebox_new/data archivebox update这一步是合并的核心。从源码看update()在 archivebox/cli/archivebox_update.py 中被定义为一个三阶段操作Phase 1排空drain旧版archive/目录——drain_old_archive_dirs()archivebox/cli/archivebox_update.py扫描archive/下所有符合旧版时间戳命名规则的目录对每个目录先尝试Snapshot.load_from_directory()从index.jsonl/index.json读取 urltimestamp 并查找已有记录找不到则用create_from_directory()创建新快照并归入自动生成的[migration] orphaned snapshotsCrawl无法识别的无效目录会被move_directory_to_invalid()移入data/invalid/YYYYMMDD/见 archivebox/core/models.py。已迁移完成的目录其fs_version被推进到当前版本旧路径在验证后移除。Phase 2筛选数据库中存在但文件系统版本过期的 Snapshot 行——process_all_db_snapshots()archivebox/cli/archivebox_update.py仅对fs_version处于迁移链中的行进行排队。Phase 3运行快照级文件系统维护直至空闲。其中的遗留目录判定逻辑在 archivebox/core/models.py 的is_legacy_archive_dir()目录名必须是能转换为数字的时间戳且落在 788918400 ~ 2082758400约 1995-2036 年范围内且不是保留目录名、不以.开头。第 5 步验证合并结果cd /path/to/archivebox_new/data archivebox status # 可选强制更新快照索引文件正常情况是惰性更新 archivebox update --index-onlyarchivebox status会列出新集合中的全部条目确认来自各旧集合的快照都已出现。--index-only从源码上看archivebox/cli/archivebox_update.py 的 click 选项注释为 Backfill available search indexes from existing archived content只会对已封存SEALED状态的快照补齐缺失的搜索索引reindex_snapshots()见 archivebox/cli/archivebox_update.py不会重新打开快照执行归档因此是安全的补充维护。关于为何 Snapshot 索引文件通常采用惰性更新快照的index.html/index.json等索引文件是在 Snapshot 保存、文件系统迁移或相关维护动作触发时按需写入的而不是每次导入都全量重建这样可以让导入阶段只聚焦数据库记录与目录迁移避免不必要的全量 IO。测试用例 archivebox/tests/test_cli_update_reindex_snapshots.py 中的test_update_imports_orphaned_snapshots与test_update_migrates_every_declared_filesystem_version验证了孤立目录导入与各声明版本0.7.0/0.8.0/0.8.5/0.9.x的文件系统迁移路径。合并后的清理与可选元数据合并确认新索引中已存在全部 Snapshot 后旧归档中遗留的index.sqlite3、index.json、index.html等主索引文件就可以安全删除了它们只服务于旧集合新集合已有自己的索引。如果这些数据对你重要可以自行合并以下根级内容ArchiveBox.conf你的 ArchiveBox 配置选项如SECRET_KEY、OUTPUT_PERMISSIONS、ADMIN_USERNAME等建议以新集合为准手工取舍sources/以原始格式导入的所有 URL 副本可合并去重后复制到新集合logs/ArchiveBox 的错误日志与调试信息可按需归档保留。直接修改 ArchiveBox 的 SQLite3 数据库如果需要自动化修改 ArchiveBox 数据库例如通过 Ansible 脚本添加用户可以直接修改 SQLite3 数据库。这在目标主机没有安装 CLI 时也常常用得上把index.sqlite3复制到安装了 ArchiveBox 的本地机器修改完成后复制回去即可Docker/CLI/GUI/Web 形态的 ArchiveBox 共享同一套数据库 schema/格式。cd ~/archivebox/data # 进入你的 archivebox 集合目录 sqlite3 index.sqlite3 # 用 sqlite3 shell 打开数据库示例修改现有用户的邮箱UPDATE auth_user SET email someNewEmailexample.com, is_superuser 1 WHERE username someUsernameHere;示例新增带哈希密码的用户注意这只是演示直接操作数据库的示例。首次初始化请打开 Admin UI 创建第一个管理员。第 1 步用 Django 的make_password生成哈希密码。务必使用拥有该集合的 ArchiveBox 安装所捆绑的 Django 版本archivebox shell -c from django.contrib.auth.hashers import make_password; print(make_password(somePasswordHere, someSaltHere, pbkdf2_sha256))在 Python 交互式 shell 中等价于 from django.contrib.auth.hashers import make_password make_password(somePasswordHere, someSaltHere, pbkdf2_sha256) # 选择一个密码和一个盐可以是任意 12 个字符 pbkdf2_sha256$...$someSaltHere$...这里用到的archivebox shell在源码上等价于 Django 的交互式 shellarchivebox/cli/archivebox_shell.py 会优先调用shell_plus否则回退到 Django 自带shell命令所以你可以直接导入并使用项目 Django 环境中的任何模块。第 2 步用生成的哈希密码在 SQLite3 中直接插入新用户行cd ~/archivebox/data # 进入你的 archivebox 集合目录 sqlite3 index.sqlite3 # 用 sqlite3 shell 打开数据库INSERT INTO auth_user (password, last_login, is_superuser, username, first_name, last_name, email, is_staff, is_active, date_joined) VALUES (GENERATED_PASSWORD_HASH, NULL, 0, someUsername, , , someEmailexample.com, 0, 1, 2022-03-22 23:34:02.333042)把上面 SQL 中的用户名、邮箱和来自 Python 输出的密码哈希替换成你的实际值。第 3 步用新用户登录确认生效访问http://admin.archivebox.localhost:8000/admin/login/用户名someUsername密码somePasswordHere。数据库故障排查遇到与合并或数据库相关的问题如迁移失败、index.sqlite3损坏、用户无法登录等可以参考 docs/Troubleshooting.md 中的 Database 一节。此外archivebox/tests/test_cli_update_reindex_snapshots.py 与 archivebox/tests/test_cli_update.py 中的测试用例覆盖了更新/导入流程的常见边界情况可作为排查时的行为参考。相关文档docs/Upgrading.md —— 版本升级含合并两个或多个已有归档一节合并前必须先升级docs/Usage.md —— 磁盘布局Disk Layout与大型归档Large Archives说明docs/Security-Overview.md —— 输出目录Output Folder的安全模型docs/Troubleshooting.md —— 数据库相关问题排查archivebox/cli/archivebox_update.py ——archivebox update三阶段实现archivebox/core/models.py ——Snapshot的文件系统迁移与遗留目录判定实现。总结合并 ArchiveBox 集合的关键在于认清数据库拥有记录、磁盘目录只是输出投影这一事实。旧版集合走复制archive/timestamp/archivebox update导入的路径当前版本集合则必须采用数据库感知的迁移或导出 URL 重新归档的方式。全程务必先备份、先升级、后合并并验证路径冲突。【免费下载链接】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），仅供参考 ArchiveBox 集合合并完全指南：从旧版 `archive/＜timestamp＞/` 目录迁移到数据库感知的合并
ArchiveBox 集合合并完全指南从旧版archive/timestamp/目录迁移到数据库感知的合并【免费下载链接】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 集合Collection合并的实战技术指南核心场景是将两个或多个旧版 ArchiveBox 集合的数据合并为一个新集合并正确处理数据库记录与磁盘快照目录之间的所有权关系。读完本文你将掌握旧版 timestamp 目录的导入合并流程、当前版本集合的正确合并思路、archivebox update三阶段迁移的底层原理以及直接操作index.sqlite3修改/新增用户记录的方法。为什么直接复制目录无法合并当前版本的集合ArchiveBox 的数据集合由两大部分组成数据库SQLiteindex.sqlite3与磁盘上的快照输出目录。当前版本以本仓库为准文件系统布局版本为0.9.4见 archivebox/core/models.py 中_fs_current_version()的快照数据存放在archive/users/username/timestamp/布局之下而Crawl、Snapshot、用户、权限以及状态机记录全部由数据库拥有。因此直接复制当前版本的archive/users/...目录树是无法安全合并的数据库才是这些记录的唯一权威来源磁盘目录只是它的输出投影archivebox init故意不导入孤立orphaned的当前布局目录。这一点在 archivebox/cli/archivebox_init.py 中有直接证据初始化时打印Skipping orphan snapshot import during init.并提示用户要导入孤立的快照目录并协调文件系统状态请运行archivebox update。结论对于当前版本的集合合并必须走数据库感知database-aware的迁移路径或者导出源 URL 后重新归档到目标集合。单独复制当前版本的 Snapshot 目录本质上是一次备份操作而不是一次合并。遗留legacy集合的合并5 步工作流下面这套流程专门用于旧版集合——其特征是真实快照目录位于archive/timestamp/目录名是纯数字时间戳。archivebox update可以把这些遗留目录导入到一个全新的索引中。[!WARNING] 合并前必须备份每一个集合。确认源条目是真实包含数据的遗留 timestamp 目录并检查路径冲突而不是允许一个集合覆盖另一个集合。第 1 步将两个旧集合都升级到最新版本先按照 docs/Upgrading.md 中的升级说明将参与合并的每个旧集合升级到当前 ArchiveBox 版本cd /path/to/archivebox1/data archivebox init archivebox status cd /path/to/archivebox2/data archivebox init archivebox status # ... 如果要合并超过两个集合对每个集合重复相同操作升级时archivebox init会校验并更新已有集合检查待执行的 Django 迁移并自动应用同时创建/校验archive/、sources/、logs/等目录结构见 archivebox/cli/archivebox_init.py。archivebox status用于确认两个集合都已就绪、无挂起的迁移。第 2 步创建用于存放合并结果的全新空集合mkdir -p /path/to/archivebox_new/data cd /path/to/archivebox_new/data archivebox init新集合会生成自己的index.sqlite3、ArchiveBox.conf与目录骨架。它不会导入任何旧数据——这正是后面导入步骤的前提。第 3 步把每个旧集合中的真实遗留archive/timestamp/目录复制进来rsync --archive --infoprogress2 /path/to/archivebox1/data/archive/ /path/to/archivebox_new/data/archive/ rsync --archive --infoprogress2 /path/to/archivebox2/data/archive/ /path/to/archivebox_new/data/archive/ # ... 如果要合并超过两个集合对每个集合重复相同操作注意这里只复制真实遗留数据目录不要复制当前版本的archive/users/树。--infoprogress2用于显示总体进度--archive保留权限与时间戳属性。第 4 步在新集合中运行archivebox update导入遗留目录cd /path/to/archivebox_new/data archivebox update这一步是合并的核心。从源码看update()在 archivebox/cli/archivebox_update.py 中被定义为一个三阶段操作Phase 1排空drain旧版archive/目录——drain_old_archive_dirs()archivebox/cli/archivebox_update.py扫描archive/下所有符合旧版时间戳命名规则的目录对每个目录先尝试Snapshot.load_from_directory()从index.jsonl/index.json读取 urltimestamp 并查找已有记录找不到则用create_from_directory()创建新快照并归入自动生成的[migration] orphaned snapshotsCrawl无法识别的无效目录会被move_directory_to_invalid()移入data/invalid/YYYYMMDD/见 archivebox/core/models.py。已迁移完成的目录其fs_version被推进到当前版本旧路径在验证后移除。Phase 2筛选数据库中存在但文件系统版本过期的 Snapshot 行——process_all_db_snapshots()archivebox/cli/archivebox_update.py仅对fs_version处于迁移链中的行进行排队。Phase 3运行快照级文件系统维护直至空闲。其中的遗留目录判定逻辑在 archivebox/core/models.py 的is_legacy_archive_dir()目录名必须是能转换为数字的时间戳且落在 788918400 ~ 2082758400约 1995-2036 年范围内且不是保留目录名、不以.开头。第 5 步验证合并结果cd /path/to/archivebox_new/data archivebox status # 可选强制更新快照索引文件正常情况是惰性更新 archivebox update --index-onlyarchivebox status会列出新集合中的全部条目确认来自各旧集合的快照都已出现。--index-only从源码上看archivebox/cli/archivebox_update.py 的 click 选项注释为 Backfill available search indexes from existing archived content只会对已封存SEALED状态的快照补齐缺失的搜索索引reindex_snapshots()见 archivebox/cli/archivebox_update.py不会重新打开快照执行归档因此是安全的补充维护。关于为何 Snapshot 索引文件通常采用惰性更新快照的index.html/index.json等索引文件是在 Snapshot 保存、文件系统迁移或相关维护动作触发时按需写入的而不是每次导入都全量重建这样可以让导入阶段只聚焦数据库记录与目录迁移避免不必要的全量 IO。测试用例 archivebox/tests/test_cli_update_reindex_snapshots.py 中的test_update_imports_orphaned_snapshots与test_update_migrates_every_declared_filesystem_version验证了孤立目录导入与各声明版本0.7.0/0.8.0/0.8.5/0.9.x的文件系统迁移路径。合并后的清理与可选元数据合并确认新索引中已存在全部 Snapshot 后旧归档中遗留的index.sqlite3、index.json、index.html等主索引文件就可以安全删除了它们只服务于旧集合新集合已有自己的索引。如果这些数据对你重要可以自行合并以下根级内容ArchiveBox.conf你的 ArchiveBox 配置选项如SECRET_KEY、OUTPUT_PERMISSIONS、ADMIN_USERNAME等建议以新集合为准手工取舍sources/以原始格式导入的所有 URL 副本可合并去重后复制到新集合logs/ArchiveBox 的错误日志与调试信息可按需归档保留。直接修改 ArchiveBox 的 SQLite3 数据库如果需要自动化修改 ArchiveBox 数据库例如通过 Ansible 脚本添加用户可以直接修改 SQLite3 数据库。这在目标主机没有安装 CLI 时也常常用得上把index.sqlite3复制到安装了 ArchiveBox 的本地机器修改完成后复制回去即可Docker/CLI/GUI/Web 形态的 ArchiveBox 共享同一套数据库 schema/格式。cd ~/archivebox/data # 进入你的 archivebox 集合目录 sqlite3 index.sqlite3 # 用 sqlite3 shell 打开数据库示例修改现有用户的邮箱UPDATE auth_user SET email someNewEmailexample.com, is_superuser 1 WHERE username someUsernameHere;示例新增带哈希密码的用户注意这只是演示直接操作数据库的示例。首次初始化请打开 Admin UI 创建第一个管理员。第 1 步用 Django 的make_password生成哈希密码。务必使用拥有该集合的 ArchiveBox 安装所捆绑的 Django 版本archivebox shell -c from django.contrib.auth.hashers import make_password; print(make_password(somePasswordHere, someSaltHere, pbkdf2_sha256))在 Python 交互式 shell 中等价于 from django.contrib.auth.hashers import make_password make_password(somePasswordHere, someSaltHere, pbkdf2_sha256) # 选择一个密码和一个盐可以是任意 12 个字符 pbkdf2_sha256$...$someSaltHere$...这里用到的archivebox shell在源码上等价于 Django 的交互式 shellarchivebox/cli/archivebox_shell.py 会优先调用shell_plus否则回退到 Django 自带shell命令所以你可以直接导入并使用项目 Django 环境中的任何模块。第 2 步用生成的哈希密码在 SQLite3 中直接插入新用户行cd ~/archivebox/data # 进入你的 archivebox 集合目录 sqlite3 index.sqlite3 # 用 sqlite3 shell 打开数据库INSERT INTO auth_user (password, last_login, is_superuser, username, first_name, last_name, email, is_staff, is_active, date_joined) VALUES (GENERATED_PASSWORD_HASH, NULL, 0, someUsername, , , someEmailexample.com, 0, 1, 2022-03-22 23:34:02.333042)把上面 SQL 中的用户名、邮箱和来自 Python 输出的密码哈希替换成你的实际值。第 3 步用新用户登录确认生效访问http://admin.archivebox.localhost:8000/admin/login/用户名someUsername密码somePasswordHere。数据库故障排查遇到与合并或数据库相关的问题如迁移失败、index.sqlite3损坏、用户无法登录等可以参考 docs/Troubleshooting.md 中的 Database 一节。此外archivebox/tests/test_cli_update_reindex_snapshots.py 与 archivebox/tests/test_cli_update.py 中的测试用例覆盖了更新/导入流程的常见边界情况可作为排查时的行为参考。相关文档docs/Upgrading.md —— 版本升级含合并两个或多个已有归档一节合并前必须先升级docs/Usage.md —— 磁盘布局Disk Layout与大型归档Large Archives说明docs/Security-Overview.md —— 输出目录Output Folder的安全模型docs/Troubleshooting.md —— 数据库相关问题排查archivebox/cli/archivebox_update.py ——archivebox update三阶段实现archivebox/core/models.py ——Snapshot的文件系统迁移与遗留目录判定实现。总结合并 ArchiveBox 集合的关键在于认清数据库拥有记录、磁盘目录只是输出投影这一事实。旧版集合走复制archive/timestamp/archivebox update导入的路径当前版本集合则必须采用数据库感知的迁移或导出 URL 重新归档的方式。全程务必先备份、先升级、后合并并验证路径冲突。【免费下载链接】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），仅供参考