# Arch Mirror

使用 Python 3.9+ 在 Linux / macOS 镜像指定的 Arch Linux ISO HTTP 目录，不需要第三方依赖。网站仅用于下载脚本、配置运行命令；实际下载在执行脚本的机器上进行。

## 使用

```bash
# 完整镜像（包括 ISO、压缩包、签名、校验文件及子目录）
python3 mirror.py --output ./mirror

# 只镜像目录 HTML、HTML 页面和图片
python3 mirror.py --output ./mirror --assets-only

# 自定义备查目录、超时、失败重试次数
python3 mirror.py --output /srv/arch-latest --records /srv/arch-records --timeout 120 --retries 3
```

默认源：<https://fastly.mirror.pkgbuild.com/iso/latest/>。可通过 `--source` 指定其他 HTTP(S) 目录，地址以 `/` 结尾。

每次运行会重新抓取源站当前可发现的文件，在镜像目录同级的临时目录中下载。全部下载成功并保存备查清单后，切换为新的目录，然后删除旧目录。源站已消失或不再被页面链接的文件会被清理；从完整模式切换为 `--assets-only` 也会移除之前的二进制文件。网络失败或下载不完整时不切换镜像，保留旧目录，并记录失败。本脚本不实现断点续传或增量下载。完整模式可能需要较大流量，更新期间需同时容纳旧、新两份镜像。

镜像目录是**本脚本专用目录**。首次运行使用新目录或空目录；脚本拒绝接管非空且未被其管理的目录。已管理目录中的额外本地文件也会随旧快照被删除，请把自己的文件保存在目录外。脚本使用 `.arch-mirror.json` 标记状态，使用同级锁文件阻止同一输出目录并发执行。

目录替换由两次重命名组成，会有短暂的路径切换间隙。常规异常会回滚；如果在两次重命名之间断电或遭遇 `SIGKILL`，旧数据仍在同级 `.目录名.previous-运行ID` 中，可手动改名恢复。源站在遍历期间发生版本更新时可能导致失败或时间上的混合快照；本脚本验证传输长度并记录本地 SHA-256，不验证发行版签名或源站 checksum。

## 整理备查

HTTP 目录通常不公开上游符号链接的类型或目标。本脚本按内容建立安全的相对符号链接：优先读取本轮 `sha256sums.txt`，已有内容的实际 SHA256 与清单一致时，别名不再下载正文；无可用清单时下载后按实际摘要去重。清单只作复用提示，不能代替发行版签名验证。不同内容不会只凭同名、大小或 ETag 合并。

JSON/CSV 记录 `link_target`、`transfer` 和 `transferred_bytes`；文字摘要区分逻辑大小、HTTP 正文下载量和去重后内容大小。符号链接只指向本轮镜像内的普通文件，月更时与整个新快照一起切换，不指回旧目录。

默认在 `<镜像目录>.records/` 下按 UTC 时间与随机 ID 为每次运行归档。旧备查记录保留，实际镜像文件仅保留当前版本。

```text
mirror/                         当前镜像
  index.html
  arch/...
  .arch-mirror.json              当前镜像状态
mirror.records/
  latest.json                   最近一次完全成功的记录指针
  20261030T150000Z-a1b2c3d4/
    manifest.json               完整运行结果、文件元数据及增删变化
    files.csv                   可用表格软件打开的下载清单（UTF-8 BOM）
    summary.txt                 便于直接查看的文件列表、大小、摘要和变化
```

每个下载文件记录相对路径、来源/最终 URL、字节数、SHA-256、Content-Type、下载时间以及源站返回的 ETag / Last-Modified。完整 JSON 包含新增、内容变更、删除和过滤 URL 列表。失败记录中的文件列表是本次已完成下载的部分，临时文件随后清理，不代表已发布的镜像。

## 仅 HTML 和图片模式

`--assets-only` 会遍历目录索引和扩展名为 `.html`、`.htm`、`.xhtml` 的 HTML 页面，下载它们链接或引用的常见图片（PNG/JPEG/GIF/SVG/WebP/AVIF/ICO/BMP/TIFF/APNG）。按扩展名过滤后还会检查 HTTP Content-Type，不请求 ISO、压缩包、签名、校验文本、CSS、JS 等其他文件。这里的“图片”指网页图片，**不包含 ISO 磁盘映像**。

仅抓取同协议、同主机、指定源目录内的链接，不访问父目录、外站或带查询参数的链接；HTTP 跳转也受此范围约束。不会猜测未被 HTML 链接的文件，也不运行 JavaScript。保存原始 HTML，目录 URL 映射为 `index.html`；在仅素材模式下，原 HTML 中的二进制下载链接仍存在，但本地没有对应文件。建议通过 `python3 -m http.server --directory ./mirror 8000` 浏览目录。

## 验证

```bash
python3 -m unittest discover -s tests -v
```

测试使用本地临时 HTTP 源验证递归、过滤二进制请求、旧文件清理、模式切换、失败保留旧镜像、备查摘要、越界和并发保护。真实源站验证结果见 `verification/VERIFICATION.md`。网站源代码在 `sites/arch-mirror/`。