ntfsmac 开发者入门:从 setup.sh 构建 vendored 二进制到可复现 Alpine 运行时与 anylinuxfs 审计流程
ntfsmac 开发者入门:从 setup.sh 构建 vendored 二进制到可复现 Alpine 运行时与 anylinuxfs 审计流程
ntfsmac 是一款让 Apple Silicon 上的 macOS 免内核扩展、免修改 SIP 即可读写 NTFS(及 ext2/3/4)的开源工具。本文将带你走一遍 ntfsmac 的开发者构建链:从 setup.sh 一键引导环境、构建 vendored 二进制,到由 sources.lock 钉死的可复现 Alpine 运行时,再到 anylinuxfs 升级的只读审计流程,帮助开发者快速理解这个"microVM + NFS"项目的工程骨架。
先看懂架构:为什么构建这么"讲究"
ntfsmac 的核心思路是:macOS 不直接读写 NTFS,而是启动一个基于 libkrun 的 Linux microVM,由 guest 内的 ntfs-3g 完成真实的挂载与写入,再通过 host-only 的 vmnet 网桥以 NFS 暴露给 macOS 挂载。
macOS ── NFS (soft mount) ──> vmnet host-only 网桥 ──> libkrun microVM ──> ntfs-3g ──> NTFS 卷
正因为涉及虚拟机启动、内核镜像、guest 代理程序等大量二进制组件,ntfsmac 的所有依赖都必须可复现、可审计、版本钉死。这也是本文后面三件事的共同主题:
| 环节 | 关键脚本 | 职责 |
|---|---|---|
| 环境引导 | setup.sh | 工具链检查 → 拉取子模块 → 构建 vendored 二进制 |
| 运行时钉死 | build/sources.lock | 以精确 commit / digest / sha256 固定每个来源 |
| 升级审计 | build/audit-anylinuxfs-update.sh | 只读评估 anylinuxfs 候选版本,永不自动跟进 |
准备工作:Apple Silicon 与工具链门槛
构建环境只支持 arm64,非 Apple Silicon 主机会在预检阶段直接拒收。build/preflight.sh 会逐项检查 git、cargo、rustc、go、umoci、lld、codesign 等工具的存在与版本,并额外断言两个关键静态库:
- util-linux:
libblkid.a/libuuid.a静态归档。anylinuxfs 依赖 libblkid 做宿主侧文件系统探测,静态链接后才不会出现"换台机器就找不到 dylib 而启动失败"的问题; - gettext:
libintl.a,静态 libblkid 的运行时符号依赖。
preflight 只检查、不安装,缺什么会明确告诉你要 brew install 哪个包——这是刻意的"不擅自动环境"设计。
一键引导:setup.sh 构建 vendored 二进制
拿到源码后(注意 vendor/src/anylinuxfs 是 git 子模块,需要一起拉取),整个构建入口只有一个命令:
git clone --recurse-submodules https://gitcode.com/gh_mirrors/nt/ntfsmac
cd ntfsmac
./setup.sh
setup.sh 按固定顺序串联了真实构建步骤:
- 工具链预检 —— 执行 build/preflight.sh,失败即中止;
- 拉取子模块 ——
git submodule update --init --recursive,同步 build/sources.lock 中ANYLINUXFS_COMMIT钉死的 anylinuxfs 版本; - 构建 vendored 二进制 —— 调用 build/build-all.sh,首次运行需要编译 cargo + go 源码,耗时较长;
- 安装 CLI —— 完成后执行
./install.sh,再跑ntfsmac diagnose做健康检查。
build-all.sh 内部:一次构建产出了什么
build/build-all.sh 是装配主编排,依次执行:
- fetch-prebuilt:build/fetch-prebuilt.sh 按 sources.lock 下载 libkrunfw 内核 Image 与
modules.squashfs、Apple 签名的vmnet-helper,先验 sha256 再解包,不匹配立即删除产物并中止; - build-gvproxy:从源码构建 gvproxy 网络代理(上游默认用预编译件,ntfsmac 选择自建并锁定该决策);
- init-rootfs:构建 Alpine 根文件系统(见下一节),同时产出并 vendored 到
vendor/bin/init-rootfs; - 静态 libblkid 阶段:build/build-libblkid-static.sh 把 Homebrew 已编译好的静态归档整理成无 dylib 依赖的 stage 目录;
- cargo build anylinuxfs / vmproxy:host 侧 CLI 与 aarch64-unknown-linux-musl 目标的 guest 代理;
- cargo test:三个 crate 的单测全部在 host 目标上运行;
- sign.sh 签名:调用 build/sign.sh 嵌入
com.apple.security.hypervisor等 entitlements——历史上这里曾只做过裸codesign -s -,导致签名合法但无权限、真机上 VM 无法启动,现已固化进流水线。
所有中间产物都在仓库外的无空格缓存目录进行(krun-init-blob 的构建脚本无法处理路径空格),最终二进制落入 vendor/bin/。
可复现的 Alpine 运行时:digest 钉死,永不 :latest
Alpine guest 镜像的复现性由三处协同保证:
① sources.lock 双值钉死。 build/sources.lock 同时固定 tag 与 digest:
ALPINE_TAG=3.23.5
ALPINE_DIGEST=sha256:d858bb54...
任何一处写成 TODO-UNRESOLVED 都会让 cli/lib/runtime-alpine.sh 中的 runtime_alpine_load 直接 HARD-STOP,这是"绝不跟随浮动引用"的硬约束。
② 构建前独立验 digest。 build/init-rootfs.sh 在拉取之前先访问注册表 manifest,取 linux/arm64 平台条目的 digest 与钉值比对,不匹配立即中止——先证明、后拉取。
③ 版本化缓存 + 打包门禁。 运行时缓存目录由 tag、digest 前缀与 anylinuxfs commit 共同派生(形如 alpine-3.23.5-<digest12>-<commit12>),新旧版本并排共存、升级永不删除旧缓存;而 build/verify-runtime-alpine.sh 作为发布门禁,直接扫描交付二进制内嵌的镜像引用:包含 alpine:latest 即判 FAIL,不含 digest-only 引用同样 FAIL。
此外,guest 内安装哪些包由 build/alpine-packages.trimmed.txt 这份审计过的精简清单决定,构建时会替换上游内嵌的默认包列表(只改缓存副本,子模块本身永不编辑)。
anylinuxfs 升级审计:只读预检,人工决策
anylinuxfs 是 microVM 的核心上游,ntfsmac 对它的策略写得很直白(docs/dev/ANYLINUXFS_UPDATE_POLICY.md):既不跟随 origin/main,也不跟随最新 tag,更不允许机器人自动合并。一次被接受的升级是一个基于当前 main 创建的独立审查单元。
审计流程分三步:
第一步:显式 fetch 候选对象,再跑只读预检。
git -C vendor/src/anylinuxfs fetch --prune origin
./build/audit-anylinuxfs-update.sh v0.19.0
build/audit-anylinuxfs-update.sh 会校验:子模块必须停在锁定的 ANYLINUXFS_COMMIT 且工作区干净、origin 必须是受审计的 anylinuxfs 官方仓库、候选必须是锁定 pin 的直系后代;然后输出从锁点到候选的精确 commit 列表与变更文件清单,区分"依赖清单漂移"与"源码路径漂移",并把 ntfsmac 的 Alpine 转换(patch 兼容性)在一次性临时归档上演练一遍——全程不 checkout 候选、不改 pin,结束后用 git status 再证明仓库未被触碰。
第二步:预检通过 ≠ 批准。 预检的输出固定以 decision=pending_manual_review 收尾。随后要按 docs/dev/ANYLINUXFS_UPDATE_POLICY.md 的八项检查清单完成人工审查:发布范围与信任边界源码走读、Cargo/Go 依赖与 lock 审查、本地 patch 兼容性、自动化门禁(./tests/run-all.sh + GUI 构建)、Apple Silicon 真机硬件矩阵,以及决策与回滚方案——旧 pin 永远保留为回滚目标。
第三步:更新钉点。 只有审查完成后,才在同一个 commit 中同步更新子模块、ANYLINUXFS_COMMIT、ANYLINUXFS_VERSION 及耦合组件 pin(如 VMPROXY_VERSION),并把证据追加到 build/AUDIT.md——只追加,不重写历史。
这个仓库里甚至附了一次真实的 dry-run 记录:v0.19.0 候选的完整 delta 是 12 个文件、仅 Cargo/Go 清单变更,预检通过,最终决策是 deferred(暂缓,非拒绝),用于验证审计工作流本身而不触碰生产 pin。
构建完成后:测试门禁与真机验证
CLI 侧的自动化测试统一由 tests/run-all.sh 发现并运行 tests/cli/ 下全部 *.bats 用例(依赖 bats-core)。GUI 侧则是 swift build 编译 Package.swift 描述的目标,或直接用 Xcode 打开。
在真实硬件上,ntfsmac diagnose 是验证整条链的只读健康检查:它会报告 vendored 二进制完整性、anylinuxfs 检出版本与审计版本的对比、Alpine 缓存状态(up/missing/legacy/interrupted/mismatch)等,且永不下载或删除任何缓存。挂载成功后,菜单栏弹出窗会列出检测到的 NTFS 卷、容量与设备号,并提供 Mount/Diagnose 入口:
偏好设置窗口则提供了重安装特权 helper、完整卸载 ntfsmac 等开发者运维入口,配合 ntfsmac uninstall 可清理 CLI、运行时状态与 GUI 特权 helper:
小结:三句话记住 ntfsmac 的工程纪律
- 一切可复现:
setup.sh→preflight→build-all.sh,每个来源由 build/sources.lock 以 commit / digest / sha256 钉死,构建缓存与运行时缓存版本化并存; - 子模块永不就地编辑:所有对 anylinuxfs 的转换都发生在仓库外的缓存副本上,patch 标记失配即 HARD-STOP;
- 升级只读预检 + 人工决策:
audit-anylinuxfs-update.sh只回答"是否值得审",批准权永远在带完整证据的人工评审手里。
想深入架构分期与构建顺序的完整规划,可继续阅读 CONTRIBUTING.md 中引用的 PLAN.md 与 SECURITY.md;构建决策的完整证据链都沉淀在 build/AUDIT.md 中。

