jamesyc/TimeCapsuleSMB
GitHub: jamesyc/TimeCapsuleSMB
该项目通过在 Apple Time Capsule 上安装定制的 Samba 4 服务器，使旧设备支持现代 SMB3 协议，从而在新版 macOS 上继续用于网络共享和 Time Machine 备份。
Stars: 601 | Forks: 21
# TimeCapsuleSMB
Apple AirPort Time Capsule 仅支持 AFP 和 SMB1。Apple 在 macOS 27 中移除了对 AFP 的支持（并在很早之前就从 macOS 中移除了对 SMB1 的支持）。这是一套可以直接在 Time Capsule 上运行的现代 Samba 设置；macOS 27 可以将 Time Capsule 作为网络共享进行连接，并将其用于 Time Machine 备份。
本项目包含 2 个部分：
- 一个经过修改以适配 Apple Time Capsule 的 Samba 4 分支
- 用于安装 Samba 二进制文件的安装程序，支持通过 python 或 **macOS GUI 应用** 进行安装。
这现在完全适用于所有 Time Capsule。Time Capsule 将运行其自带的 Samba 4.24.3 服务器，通过 Bonjour 进行广播（在 macOS 上自动显示在“网络”文件夹中），并接受经过身份验证的 SMB3 连接。然后，你应该能够打开 Finder，选择“连接到服务器”，并使用普通的 SMB URL，而无需依赖 Apple 的旧技术栈。你也应该能够将该磁盘用于 Time Machine 备份：
你将获得完整重现的 Apple 体验：安装完成后，即使设备的 IP 地址发生变化，你也不必再为此担心。它会自动显示在设置应用的 Time Machine 中，并且它会使用 mDNS/Bonjour，因此即使 IP 地址不是静态的并且发生了更改，它也能正常工作。
“Install”或 `deploy` 脚本会将文件安装到 Time Capsule 上的 `/mnt/Flash` 中，以及在硬盘根目录下创建一个 `.samba4` 文件夹。`uninstall` 脚本会移除这些受管理的文件，并可选择在之后重启设备。
NetBSD 6 设备会在开机时自动启动。**较旧的 NetBSD 4 设备可能需要在每次重启后手动执行 `activate`**，或者你可以使用此功能刷新固件（添加一个 boot hook）以允许其在重启时自动启动 Samba。如果你在重启后没有运行 `activate` 命令或没有刷新 boot hook，那么较旧的 Time Capsule 将无法自动启动 Samba！
当前的身份验证模型接受任何用户名，而 Samba 密码即当前 Time Capsule 的设备密码。在启动时，设备会读取其实时的 AirPort `syPW` 值并在 RAM 中生成 Samba 密码文件，因此设备密码的更改会在重启后被识别。已禁用来宾访问。
AirPort Extreme 设备不在官方支持范围内。不过非官方地讲，它们可以正常工作。请注意，这是安装到硬盘上的，因此对于没有硬盘的 AirPort Extreme 将无法使用（因为闪存上没有足够的空间来存储二进制文件）。
## 环境要求
你需要：
- 一台与 Time Capsule 连接在同一局域网内的 macOS 14+ 或 Linux 机器
- Time Capsule 的密码
对于 python 设置，你需要：
- Python 3.9+
- 本地安装了 `smbclient` 以供 `doctor` 使用
- macOS 用户需要安装 Homebrew
在首次设置期间，如果有必要，`configure` 可以在 Time Capsule 上启用 SSH。
此外，如果你是专家并希望 DIY 安装，可以将适用于 NetBSD 6 设备的 [/bin/samba4/smbd](/bin/samba4/smbd)、适用于 NetBSD 4 小端序设备的 [/bin/samba4-netbsd4le/smbd](/bin/samba4-netbsd4le/smbd) 或适用于 NetBSD 4 大端序设备的 [/bin/samba4-netbsd4be/smbd](/bin/samba4-netbsd4be/smbd) 复制到 Time Capsule 上并自行设置。这些二进制文件是静态编译的，因此你不需要其他任何东西。可用的二进制文件保存在本仓库的 [bin/](bin) 目录下，普通用户的工作流程会直接使用这些签入的文件。你不需要自己构建 Samba，但如果你想自己重新构建 `smbd`，请在 NetBSD 机器上运行 `build/` 中的脚本。
## 快速开始（macOS 应用）
1. 从这里下载该应用的最新版本：https://github.com/jamesyc/TimeCapsuleSMB/releases
2. 解压应用并运行。如果你收到“无法打开”的警告，你需要手动为此应用禁用 Gatekeeper。
3. 确保已授予*本地网络*权限（系统设置 → 隐私与安全性 → 本地网络 → 确保 TimeCapsuleSMB 已被允许，然后退出/重新打开应用）。授予权限后关闭并重新打开应用。
4. 点击左侧边栏的“Add Device”，并选择你的设备。
5. 输入你的设备密码，然后点击“Save Device”。
6. 等待应用为你的 Time Capsule 启用 SSH。
- 如果失败，请关闭应用、重新打开应用、移除已保存的设备，然后再试一次。
- 此外，也可以尝试重启你的设备。
7. 点击左侧边栏中已添加的设备，然后点击“Install/Update”标签页。
8. 点击“Install/Update”以部署到设备。
- 如果部署到设备失败，请尝试从应用中移除已保存的设备，然后返回到上面的第 4 步再次“Add Device”。有时需要部署多次才能将所有文件复制过去。
- 有报告称设备可能会在部署期间重置，请查看[此 issue](https://github.com/jamesyc/TimeCapsuleSMB/issues/177) 了解更多信息。
9. （仅适用于第 1 至 4 代设备）进入维护页面的“Persistent NetBSD4 Boot Hook”部分。安装固件补丁以允许设备在重启后自动启动 Samba。点击“Back Up and Inspect”和“Plan Patch”检查是否可以安装；然后运行“Write Patch”将其刷入你的设备。
10. （可选）等待 5-10 分钟让 Samba 完全启动，然后进入 Checkup 标签页并运行一次 Checkup。
请[阅读 FAQ](FAQ.md) 了解更多信息。如果你遇到通过 FAQ 无法解决的问题，如果你能[在这里提交一个 issue](https://github.com/jamesyc/TimeCapsuleSMB/issues) 寻求帮助，我将不胜感激。
## 快速开始（使用 python）
下载（或运行 `git clone`）此仓库到你的 Mac 或 Linux 机器上的一个文件夹中。
从仓库的根目录开始，需要运行的常规快速启动命令如下：
1. `./tcapsule bootstrap`
2. `.venv/bin/tcapsule configure` 保存配置/设置文件
3. `.venv/bin/tcapsule deploy` 根据配置文件部署到 Time Capsule
4. `.venv/bin/tcapsule doctor` 检查一切是否正常
5. `.venv/bin/tcapsule flash` 备份闪存，并使用 `.venv/bin/tcapsule flash --patch` 为其打补丁
如果你遇到任何问题：
- 在 NetBSD 4 设备重启后，如果 Samba 没有自动启动，请执行 `.venv/bin/tcapsule activate`
- 如果在部署前需要修复内部磁盘，请执行 `.venv/bin/tcapsule fsck`
- 使用 `.venv/bin/tcapsule discover` 列出所有 mDNS/Bonjour 设备
- 使用 `.venv/bin/tcapsule repair-xattrs` 修复磁盘上由于 xattrs 损坏而导致的任何损坏文件
- 如果你以后想移除 TimeCapsuleSMB，请执行 `.venv/bin/tcapsule uninstall`
完成 Time Capsule 的设置后，如果你想将其从 Mac 上移除，只需删除这个 `TimeCapsuleSMB` 文件夹即可。所有的脚本/二进制文件/等均存储在 `TimeCapsuleSMB` 文件夹中（因此如果你想清理你的 Mac，只需删除该文件夹即可）。
如果你发现任何 bug，如果你能[在这里提交一个 issue](https://github.com/jamesyc/TimeCapsuleSMB/issues) 寻求帮助，我将不胜感激。
## 第 1 步：准备你的主机
运行：
```
./tcapsule bootstrap
```
此命令会准备此文件夹中的本地 Python 环境。它会创建 `.venv` 文件夹，安装用于发现、部署和验证的 Python 依赖项，并将本地 `tcapsule` 命令设置到该 virtualenv 中。
如果缺少 `smbclient` 或 `sshpass`，`bootstrap` 将尝试在 macOS 14+ 上使用 Homebrew 或在 Linux 上使用检测到的包管理器进行安装。较旧的 macOS 版本只能在手动安装 `smbclient` 和 `sshpass` 后继续。NetBSD 4 设备需要 `sshpass`，因为它们的固件不提供可用的远程 `scp`。
如果你是第一次使用该仓库，这是你唯一应该使用仓库本地启动器运行的命令。在此步骤之后，请使用 `.venv/bin/tcapsule ...` 来运行命令。
在继续之前，你可以检查一下仅限本地仓库的安装：
```
.venv/bin/tcapsule paths
.venv/bin/tcapsule validate-install
```
## 第 2 步：创建本地配置
运行：
```
.venv/bin/tcapsule configure
```
这会在仓库文件夹中写入一个隐藏的 `.env` 文件，其他的 `tcapsule` 命令会使用该文件作为本地设备配置。
在 `configure` 开始时，该工具首先会尝试通过 mDNS/Bonjour 在本地网络上发现你的 Time Capsule。如果找到，它会为你预填充 SSH 目标。如果未找到，则会回退到常规的手动提示流程。
`configure` 还会检查 SSH 是否可达。如果 SSH 关闭，它会使用内置的 Python 3 ACP 客户端启用 SSH，重启设备，等待 SSH 启动，然后继续正常的探测流程。如果密码错误，它会再次询问，而不是写入一个损坏的 `.env` 文件。
你在此处输入的密码将作为 `TC_PASSWORD` 存储在本地，以便该工具可以继续使用 SSH 和 ACP。受管理的 Samba runtime 会在启动时读取 Time Capsule 上当前的设备密码。换句话说，设置完成后，你通常使用以下方式进行连接：
- 用户名：`admin`（或任何其他密码）
- 密码：你在配置期间输入的相同 Time Capsule 密码
Samba 不直接使用 Apple 的内部密码后端。启动脚本会读取 AirPort `syPW` 设置，请求 `mdns-advertiser` 生成 NT hash，并在 `smbd` 启动前写入仅存在于 RAM 中的 Samba 认证文件。
## 第 3 步：进行部署
运行：
```
.venv/bin/tcapsule deploy
```
此步骤会在设备上安装（或更新）Samba。它会验证签入的二进制文件，并将 payload 和启动文件复制到 Time Capsule。Samba 密码文件会在受管理的 runtime 暂存时，每次都在设备的 RAM 中生成。你可以为新版本运行 `deploy` 进行更新。
在第 5 代 NetBSD 6 设备上，`deploy` 会重启设备，以便新的 runtime 能干净地启动。
在较旧的第 1 至 4 代 NetBSD 4 设备上，`deploy` 也会重启以清除 RAM 磁盘，等待 SSH 恢复，然后运行 `/mnt/Flash/rc.local`。对于之后不包含在 `deploy` 内的重启，较旧的设备仍然需要执行 `tcapsule activate`。
默认情况下，`tcapsule deploy` 会在部署后重启，然后等待设备恢复。如果你想跳过重启确认提示，可以运行：
```
.venv/bin/tcapsule deploy --yes
```
还有其他一些标志，例如 `--no-nbns`、`--no-reboot` 和 `--dry-run`，但除非你有特定原因要使用它们，否则请保持原样。`--no-reboot` 会上传文件、停止 manager 进程和 `wcifsfs`，并通过运行 `/mnt/Flash/rc.local` 立即启动已部署的 runtime。
如果你想要在不更改设备的情况下获取机器可读的部署计划，请使用：
```
.venv/bin/tcapsule deploy --dry-run --json
```
## 第 4 步：刷新（Flash）或按需再次激活
这适用于较旧的第 1 至 4 代设备。运行：
```
.venv/bin/tcapsule flash
```
备份你设备上的闪存。然后运行：
```
.venv/bin/tcapsule flash --patch
```
然后，这将会打上一个小型的 boot hook 启动器（仅限主固件 bank）。它只是告诉设备在每次启动时运行 `/mnt/Flash/rc.local` 文件。
在受支持的设备上，`tcapsule flash --patch` 可以安装持久化 boot hook，而 `tcapsule flash --restore` 可以从 Apple 目录下载的 Apple 官方固件中所选的活动 bank。这两种写入模式都仅修改一个 bank 并保持另一个闪存 bank 不变，然后在 ACP 接受写入后通过回读已写入的 bank 来运行验证。Patch 模式通常需要精确选择一个安全的活动 bank；`--force` 仅适用于 patch 模式，它会绕过备份/活动候选预检以直接针对主 bank。
Patch 模式在写入成功后无法发送重启或关机命令。在 `tcapsule flash --patch` 报告成功后，用户需要手动
拔下设备电源以进行重启，然后等待几分钟让设备启动并运行 `tcapsule doctor`。Restore 模式可以通过 `tcapsule flash --restore --reboot` 请求软件重启；之后，使用 `tcapsule flash --check-apple` 验证活动 bank 是否与 Apple 官方固件匹配。
如果你不想 patch 设备，请运行：
```
.venv/bin/tcapsule activate
```
它会再次启动 Samba，而无需重新复制文件。
对于较旧的第 1 至 4 代硬件，由于固件默认不会持久化自动启动 Samba 所需的 boot hook，因此目前这在每次重启后都是必需的。
不幸的是，如果你没有运行 `flash`，对于不会自动启动 Samba 的旧设备，你需要在*每次*重启后运行 `activate`。
## 第 5 步：验证结果
运行：
```
.venv/bin/tcapsule doctor
```
这是一个非破坏性的诊断命令。`tcapsule doctor` 会检查：
- 必需的本地工具是否存在
- 你的 `.env` 是否存在、完整且有效
- 签入的二进制文件是否存在并与预期的校验和匹配
- SSH 是否可达
- 配置的远程网络接口、检测到的设备兼容性以及选择的 payload 系列是否合理
- 受管理的 runtime 是否已启动：
- `smbd` 是否正在运行并绑定到 TCP 445
- 受管理的 mDNS 接管是否处于活动状态
- NBNS 响应程序会被检查，除非被禁用
- 设备当前正在广播和提供的内容：
- Bonjour 实例名称
- Bonjour 主机标签
- Samba NetBIOS 名称
- Samba 共享名称
- SMB 是否可达
- Bonjour `_smb._tcp` 广播是否可见并且可以解析
- 经过身份验证的 SMB 列举是否确实有效并包含活动共享名称
- 经过身份验证的 SMB 文件操作在该共享上是否同样有效
- 活动 Samba 配置中的 `xattr_tdb:file` 是否指向持久化存储而不是 RAM 磁盘
如果你想要 JSON 格式的结果而不是人类可读的文本，请使用：
```
.venv/bin/tcapsule doctor --json
```
## 第 6 步：如有需要，日后将其移除
运行：
```
.venv/bin/tcapsule uninstall
```
这将从内部磁盘中移除受管理的 TimeCapsuleSMB payload，并从 `/mnt/Flash` 中移除加载器文件。Apple 会在每次重启后清除设备上的文件系统，`/mnt/Flash` 除外，所以我们才将加载器脚本安装在那里。如果你删除了 `/mnt/Flash` 中的 7 个 payload 文件，删除硬盘上的 `.samba4` 文件夹，然后重启，你就可以将你的机器恢复到出厂干净状态。
默认情况下，`uninstall` 在重启 Time Capsule 之前会进行询问。如果你想跳过重启确认提示，请使用：
```
.venv/bin/tcapsule uninstall --yes
```
如果你想在不更改设备的情况下预览卸载计划，请使用：
```
.venv/bin/tcapsule uninstall --dry-run
.venv/bin/tcapsule uninstall --dry-run --json
```
卸载成功意味着受管理的 payload 和启动文件在重启后已消失。它**不会**检查之后是否启用了 Apple SMB 或 AFP。这些服务可能是开启或关闭的，具体取决于设备自身的设置。
如果你想移除文件但不立即重启，请使用：
```
.venv/bin/tcapsule uninstall --no-reboot
```
## 从 Finder 连接
部署完成且 Time Capsule 重启后，你应该能够从 Finder 进行连接。该设备应该会显示在“网络”文件夹中，或者通过以下方式显示：
```
smb://.local/
```
当 Finder 提示输入凭据时，请使用：
- 用户名：`admin` 或任何用户名
- 密码：你的 Time Capsule 密码
## 技术说明
本 README 的其余部分技术性更强，解释了为什么该仓库会以这种方式构建。
## 设计
Time Capsule 硬件非常老旧且受限。它有三个相关的存储区域：
- `/mnt/Flash`，它是持久化的，但只有约 900KB 的可用空间。
- `/mnt/Memory`，它是一个 16MB 的 ramdisk
- 挂载在 `/Volumes/dk2` 或 `/Volumes/dk3` 下的内部 HDD，它容量很大但由 Apple 管理，并且在闲置时会卸载。出于这个原因，你无法从这个位置运行二进制文件。
不幸的是，“把一个二进制文件复制到某处就算完事”并不是让 `smbd` 运行起来的可行选项。因此，当前的过程是：
1. 将完整的 `smbd` payload 保留在宽裕的内部硬盘上。
2. 在闪存上只保留一个非常小的 `rc.local` 启动脚本。
3. 在启动时，等待内部磁盘出现并挂载。
4. 将 runtime 二进制文件复制到 `/mnt/Memory` 中。
5. 从 `/mnt/Memory` 而不是 Apple 稍后可能会决定卸载的大磁盘中启动 Samba。
6. 使用一个单独的微型 mDNS 助手广播 `_smb._tcp`。
这就是该仓库同时包含以下内容的原因：
- [bin/samba4/smbd](bin/samba4/smbd)
- [bin/mdns/mdns-advertiser](bin/mdns/mdns-advertiser)
以及启动文件，例如：
- [src/timecapsulesmb/assets/boot/samba4/rc.local](src/timecapsulesmb/assets/boot/samba4/rc.local)
- [src/timecapsulesmb/assets/boot/samba4/boot.sh](src/timecapsulesmb/assets/boot/samba4/boot.sh)
- [src/timecapsulesmb/assets/boot/samba4/manager.sh](src/timecapsulesmb/assets/boot/samba4/manager.sh)
Time Capsule 给我们带来了其他限制：
- NetBSD 6 源代码不支持 earmv4 构建，因此我们需要从 NetBSD 7 进行构建。
- Samba 3.x 很容易编译，但它不支持在 NetBSD 6 上使用 SMB2 进行目录遍历。这显然是一个已知 bug。
- Samba 4.0.x 也有同样的问题
- Samba 4.2.x 编译起来要困难得多，并且存在 `talloc` / `loadparm` 的 use-after-free runtime bug
- Samba 4.3.x 是第一个可以作为网络共享正常工作的版本，但它不支持用于 Time Machine 备份的 vfs_fruit
- Samba 4.8.x 是第一个完全正常工作的版本；目前的构建版本提供的是 Samba 4.24.3。
## 故障排除
也请阅读 [FAQ.md](FAQ.md)。
### Time Capsule 没有出现在 Finder 中
运行：
```
.venv/bin/tcapsule doctor
```
然后直接检查 Bonjour：
```
dns-sd -B _smb._tcp local.
```
要检查该工具本身的发现结果，请运行：
```
.venv/bin/tcapsule discover --json
```
如果系统正常工作，你应该看到一个带有 Time Capsule 当前设备名称的 `_smb._tcp` 服务。
Finder 并不总是最好的首选诊断工具。即使 Finder 浏览速度缓慢或出现问题，该服务也可能已启动且正确。
### Finder 仍然无法连接
尝试重启，然后明确尝试直接输入地址：
```
smb://.local/
```
如有必要，请使用 `.env` 中的 IP 地址代替。关键是将“Bonjour 浏览出现了奇怪现象”与“SMB 本身损坏”区分开来。
### 部署显示刚重启后 SMB 列举失败
如果设备已重新连接到网络但仍在完成启动，则可能会发生这种情况。这些旧的 Time Capsule CPU 速度并不快。
稍等片刻，然后运行：
```
.venv/bin/tcapsule doctor
```
### 我想要完整的技术细节
请阅读：
- [DETAIL.md](DETAIL.md)
这更详细地解释了工程限制、历史上的死胡同以及当前的实现。
## 安全说明
这应被视为仅限局域网 (LAN) 的设置。不要将此 SMB 服务直接暴露给公共互联网！不要向其转发端口。我已经使用 M1 Macbook Pro 和 A1470 Time Capsule 进行了测试。实际情况可能有所不同。
另请注意，当前的身份验证模型在 Time Capsule 上将内部 SMB 访问权限映射到 `root`。对于这种旧固件来说，这是一个故意的兼容性选择，因为 Time Capsule 上运行的 NetBSD 6 版本在 Samba 尝试切换用户时会报错。
这些命令默认启用了日志记录和遥测功能。错误和异常会被记录下来，以便日后轻松调查。
## 面向开发者和维护者
签入的二进制文件已经构建好了。如果你想自己重新构建它们，维护者的构建流程位于 [build/](build) 下，并且依赖于一个 NetBSD VM。
主要的构建输出是：
- [bin/samba4/smbd](bin/samba4/smbd)
- [bin/samba4-netbsd4le/smbd](bin/samba4-netbsd4le/smbd)
- [bin/samba4-netbsd4be/smbd](bin/samba4-netbsd4be/smbd)
- [bin/mdns/mdns-advertiser](bin/mdns/mdns-advertiser)
- [bin/mdns-netbsd4le/mdns-advertiser](bin/mdns-netbsd4le/mdns-advertiser)
- [bin/mdns-netbsd4be/mdns-advertiser](bin/mdns-netbsd4be/mdns-advertiser)
- [bin/nbns/nbns-advertiser](bin/nbns/nbns-advertiser)
- [bin/nbns-netbsd4le/nbns-advertiser](bin/nbns-netbsd4le/nbns-advertiser)
- [bin/nbns-netbsd4be/nbns-advertiser](bin/nbns-netbsd4be/nbns-advertiser)
你将获得完整重现的 Apple 体验：安装完成后，即使设备的 IP 地址发生变化，你也不必再为此担心。它会自动显示在设置应用的 Time Machine 中，并且它会使用 mDNS/Bonjour，因此即使 IP 地址不是静态的并且发生了更改，它也能正常工作。
“Install”或 `deploy` 脚本会将文件安装到 Time Capsule 上的 `/mnt/Flash` 中，以及在硬盘根目录下创建一个 `.samba4` 文件夹。`uninstall` 脚本会移除这些受管理的文件，并可选择在之后重启设备。
NetBSD 6 设备会在开机时自动启动。**较旧的 NetBSD 4 设备可能需要在每次重启后手动执行 `activate`**，或者你可以使用此功能刷新固件（添加一个 boot hook）以允许其在重启时自动启动 Samba。如果你在重启后没有运行 `activate` 命令或没有刷新 boot hook，那么较旧的 Time Capsule 将无法自动启动 Samba！
当前的身份验证模型接受任何用户名，而 Samba 密码即当前 Time Capsule 的设备密码。在启动时，设备会读取其实时的 AirPort `syPW` 值并在 RAM 中生成 Samba 密码文件，因此设备密码的更改会在重启后被识别。已禁用来宾访问。
AirPort Extreme 设备不在官方支持范围内。不过非官方地讲，它们可以正常工作。请注意，这是安装到硬盘上的，因此对于没有硬盘的 AirPort Extreme 将无法使用（因为闪存上没有足够的空间来存储二进制文件）。
## 环境要求
你需要：
- 一台与 Time Capsule 连接在同一局域网内的 macOS 14+ 或 Linux 机器
- Time Capsule 的密码
对于 python 设置，你需要：
- Python 3.9+
- 本地安装了 `smbclient` 以供 `doctor` 使用
- macOS 用户需要安装 Homebrew
在首次设置期间，如果有必要，`configure` 可以在 Time Capsule 上启用 SSH。
此外，如果你是专家并希望 DIY 安装，可以将适用于 NetBSD 6 设备的 [/bin/samba4/smbd](/bin/samba4/smbd)、适用于 NetBSD 4 小端序设备的 [/bin/samba4-netbsd4le/smbd](/bin/samba4-netbsd4le/smbd) 或适用于 NetBSD 4 大端序设备的 [/bin/samba4-netbsd4be/smbd](/bin/samba4-netbsd4be/smbd) 复制到 Time Capsule 上并自行设置。这些二进制文件是静态编译的，因此你不需要其他任何东西。可用的二进制文件保存在本仓库的 [bin/](bin) 目录下，普通用户的工作流程会直接使用这些签入的文件。你不需要自己构建 Samba，但如果你想自己重新构建 `smbd`，请在 NetBSD 机器上运行 `build/` 中的脚本。
## 快速开始（macOS 应用）
1. 从这里下载该应用的最新版本：https://github.com/jamesyc/TimeCapsuleSMB/releases
2. 解压应用并运行。如果你收到“无法打开”的警告，你需要手动为此应用禁用 Gatekeeper。
3. 确保已授予*本地网络*权限（系统设置 → 隐私与安全性 → 本地网络 → 确保 TimeCapsuleSMB 已被允许，然后退出/重新打开应用）。授予权限后关闭并重新打开应用。
4. 点击左侧边栏的“Add Device”，并选择你的设备。
5. 输入你的设备密码，然后点击“Save Device”。
6. 等待应用为你的 Time Capsule 启用 SSH。
- 如果失败，请关闭应用、重新打开应用、移除已保存的设备，然后再试一次。
- 此外，也可以尝试重启你的设备。
7. 点击左侧边栏中已添加的设备，然后点击“Install/Update”标签页。
8. 点击“Install/Update”以部署到设备。
- 如果部署到设备失败，请尝试从应用中移除已保存的设备，然后返回到上面的第 4 步再次“Add Device”。有时需要部署多次才能将所有文件复制过去。
- 有报告称设备可能会在部署期间重置，请查看[此 issue](https://github.com/jamesyc/TimeCapsuleSMB/issues/177) 了解更多信息。
9. （仅适用于第 1 至 4 代设备）进入维护页面的“Persistent NetBSD4 Boot Hook”部分。安装固件补丁以允许设备在重启后自动启动 Samba。点击“Back Up and Inspect”和“Plan Patch”检查是否可以安装；然后运行“Write Patch”将其刷入你的设备。
10. （可选）等待 5-10 分钟让 Samba 完全启动，然后进入 Checkup 标签页并运行一次 Checkup。
请[阅读 FAQ](FAQ.md) 了解更多信息。如果你遇到通过 FAQ 无法解决的问题，如果你能[在这里提交一个 issue](https://github.com/jamesyc/TimeCapsuleSMB/issues) 寻求帮助，我将不胜感激。
## 快速开始（使用 python）
下载（或运行 `git clone`）此仓库到你的 Mac 或 Linux 机器上的一个文件夹中。
从仓库的根目录开始，需要运行的常规快速启动命令如下：
1. `./tcapsule bootstrap`
2. `.venv/bin/tcapsule configure` 保存配置/设置文件
3. `.venv/bin/tcapsule deploy` 根据配置文件部署到 Time Capsule
4. `.venv/bin/tcapsule doctor` 检查一切是否正常
5. `.venv/bin/tcapsule flash` 备份闪存，并使用 `.venv/bin/tcapsule flash --patch` 为其打补丁
如果你遇到任何问题：
- 在 NetBSD 4 设备重启后，如果 Samba 没有自动启动，请执行 `.venv/bin/tcapsule activate`
- 如果在部署前需要修复内部磁盘，请执行 `.venv/bin/tcapsule fsck`
- 使用 `.venv/bin/tcapsule discover` 列出所有 mDNS/Bonjour 设备
- 使用 `.venv/bin/tcapsule repair-xattrs` 修复磁盘上由于 xattrs 损坏而导致的任何损坏文件
- 如果你以后想移除 TimeCapsuleSMB，请执行 `.venv/bin/tcapsule uninstall`
完成 Time Capsule 的设置后，如果你想将其从 Mac 上移除，只需删除这个 `TimeCapsuleSMB` 文件夹即可。所有的脚本/二进制文件/等均存储在 `TimeCapsuleSMB` 文件夹中（因此如果你想清理你的 Mac，只需删除该文件夹即可）。
如果你发现任何 bug，如果你能[在这里提交一个 issue](https://github.com/jamesyc/TimeCapsuleSMB/issues) 寻求帮助，我将不胜感激。
## 第 1 步：准备你的主机
运行：
```
./tcapsule bootstrap
```
此命令会准备此文件夹中的本地 Python 环境。它会创建 `.venv` 文件夹，安装用于发现、部署和验证的 Python 依赖项，并将本地 `tcapsule` 命令设置到该 virtualenv 中。
如果缺少 `smbclient` 或 `sshpass`，`bootstrap` 将尝试在 macOS 14+ 上使用 Homebrew 或在 Linux 上使用检测到的包管理器进行安装。较旧的 macOS 版本只能在手动安装 `smbclient` 和 `sshpass` 后继续。NetBSD 4 设备需要 `sshpass`，因为它们的固件不提供可用的远程 `scp`。
如果你是第一次使用该仓库，这是你唯一应该使用仓库本地启动器运行的命令。在此步骤之后，请使用 `.venv/bin/tcapsule ...` 来运行命令。
在继续之前，你可以检查一下仅限本地仓库的安装：
```
.venv/bin/tcapsule paths
.venv/bin/tcapsule validate-install
```
## 第 2 步：创建本地配置
运行：
```
.venv/bin/tcapsule configure
```
这会在仓库文件夹中写入一个隐藏的 `.env` 文件，其他的 `tcapsule` 命令会使用该文件作为本地设备配置。
在 `configure` 开始时，该工具首先会尝试通过 mDNS/Bonjour 在本地网络上发现你的 Time Capsule。如果找到，它会为你预填充 SSH 目标。如果未找到，则会回退到常规的手动提示流程。
`configure` 还会检查 SSH 是否可达。如果 SSH 关闭，它会使用内置的 Python 3 ACP 客户端启用 SSH，重启设备，等待 SSH 启动，然后继续正常的探测流程。如果密码错误，它会再次询问，而不是写入一个损坏的 `.env` 文件。
你在此处输入的密码将作为 `TC_PASSWORD` 存储在本地，以便该工具可以继续使用 SSH 和 ACP。受管理的 Samba runtime 会在启动时读取 Time Capsule 上当前的设备密码。换句话说，设置完成后，你通常使用以下方式进行连接：
- 用户名：`admin`（或任何其他密码）
- 密码：你在配置期间输入的相同 Time Capsule 密码
Samba 不直接使用 Apple 的内部密码后端。启动脚本会读取 AirPort `syPW` 设置，请求 `mdns-advertiser` 生成 NT hash，并在 `smbd` 启动前写入仅存在于 RAM 中的 Samba 认证文件。
## 第 3 步：进行部署
运行：
```
.venv/bin/tcapsule deploy
```
此步骤会在设备上安装（或更新）Samba。它会验证签入的二进制文件，并将 payload 和启动文件复制到 Time Capsule。Samba 密码文件会在受管理的 runtime 暂存时，每次都在设备的 RAM 中生成。你可以为新版本运行 `deploy` 进行更新。
在第 5 代 NetBSD 6 设备上，`deploy` 会重启设备，以便新的 runtime 能干净地启动。
在较旧的第 1 至 4 代 NetBSD 4 设备上，`deploy` 也会重启以清除 RAM 磁盘，等待 SSH 恢复，然后运行 `/mnt/Flash/rc.local`。对于之后不包含在 `deploy` 内的重启，较旧的设备仍然需要执行 `tcapsule activate`。
默认情况下，`tcapsule deploy` 会在部署后重启，然后等待设备恢复。如果你想跳过重启确认提示，可以运行：
```
.venv/bin/tcapsule deploy --yes
```
还有其他一些标志，例如 `--no-nbns`、`--no-reboot` 和 `--dry-run`，但除非你有特定原因要使用它们，否则请保持原样。`--no-reboot` 会上传文件、停止 manager 进程和 `wcifsfs`，并通过运行 `/mnt/Flash/rc.local` 立即启动已部署的 runtime。
如果你想要在不更改设备的情况下获取机器可读的部署计划，请使用：
```
.venv/bin/tcapsule deploy --dry-run --json
```
## 第 4 步：刷新（Flash）或按需再次激活
这适用于较旧的第 1 至 4 代设备。运行：
```
.venv/bin/tcapsule flash
```
备份你设备上的闪存。然后运行：
```
.venv/bin/tcapsule flash --patch
```
然后，这将会打上一个小型的 boot hook 启动器（仅限主固件 bank）。它只是告诉设备在每次启动时运行 `/mnt/Flash/rc.local` 文件。
在受支持的设备上，`tcapsule flash --patch` 可以安装持久化 boot hook，而 `tcapsule flash --restore` 可以从 Apple 目录下载的 Apple 官方固件中所选的活动 bank。这两种写入模式都仅修改一个 bank 并保持另一个闪存 bank 不变，然后在 ACP 接受写入后通过回读已写入的 bank 来运行验证。Patch 模式通常需要精确选择一个安全的活动 bank；`--force` 仅适用于 patch 模式，它会绕过备份/活动候选预检以直接针对主 bank。
Patch 模式在写入成功后无法发送重启或关机命令。在 `tcapsule flash --patch` 报告成功后，用户需要手动
拔下设备电源以进行重启，然后等待几分钟让设备启动并运行 `tcapsule doctor`。Restore 模式可以通过 `tcapsule flash --restore --reboot` 请求软件重启；之后，使用 `tcapsule flash --check-apple` 验证活动 bank 是否与 Apple 官方固件匹配。
如果你不想 patch 设备，请运行：
```
.venv/bin/tcapsule activate
```
它会再次启动 Samba，而无需重新复制文件。
对于较旧的第 1 至 4 代硬件，由于固件默认不会持久化自动启动 Samba 所需的 boot hook，因此目前这在每次重启后都是必需的。
不幸的是，如果你没有运行 `flash`，对于不会自动启动 Samba 的旧设备，你需要在*每次*重启后运行 `activate`。
## 第 5 步：验证结果
运行：
```
.venv/bin/tcapsule doctor
```
这是一个非破坏性的诊断命令。`tcapsule doctor` 会检查：
- 必需的本地工具是否存在
- 你的 `.env` 是否存在、完整且有效
- 签入的二进制文件是否存在并与预期的校验和匹配
- SSH 是否可达
- 配置的远程网络接口、检测到的设备兼容性以及选择的 payload 系列是否合理
- 受管理的 runtime 是否已启动：
- `smbd` 是否正在运行并绑定到 TCP 445
- 受管理的 mDNS 接管是否处于活动状态
- NBNS 响应程序会被检查，除非被禁用
- 设备当前正在广播和提供的内容：
- Bonjour 实例名称
- Bonjour 主机标签
- Samba NetBIOS 名称
- Samba 共享名称
- SMB 是否可达
- Bonjour `_smb._tcp` 广播是否可见并且可以解析
- 经过身份验证的 SMB 列举是否确实有效并包含活动共享名称
- 经过身份验证的 SMB 文件操作在该共享上是否同样有效
- 活动 Samba 配置中的 `xattr_tdb:file` 是否指向持久化存储而不是 RAM 磁盘
如果你想要 JSON 格式的结果而不是人类可读的文本，请使用：
```
.venv/bin/tcapsule doctor --json
```
## 第 6 步：如有需要，日后将其移除
运行：
```
.venv/bin/tcapsule uninstall
```
这将从内部磁盘中移除受管理的 TimeCapsuleSMB payload，并从 `/mnt/Flash` 中移除加载器文件。Apple 会在每次重启后清除设备上的文件系统，`/mnt/Flash` 除外，所以我们才将加载器脚本安装在那里。如果你删除了 `/mnt/Flash` 中的 7 个 payload 文件，删除硬盘上的 `.samba4` 文件夹，然后重启，你就可以将你的机器恢复到出厂干净状态。
默认情况下，`uninstall` 在重启 Time Capsule 之前会进行询问。如果你想跳过重启确认提示，请使用：
```
.venv/bin/tcapsule uninstall --yes
```
如果你想在不更改设备的情况下预览卸载计划，请使用：
```
.venv/bin/tcapsule uninstall --dry-run
.venv/bin/tcapsule uninstall --dry-run --json
```
卸载成功意味着受管理的 payload 和启动文件在重启后已消失。它**不会**检查之后是否启用了 Apple SMB 或 AFP。这些服务可能是开启或关闭的，具体取决于设备自身的设置。
如果你想移除文件但不立即重启，请使用：
```
.venv/bin/tcapsule uninstall --no-reboot
```
## 从 Finder 连接
部署完成且 Time Capsule 重启后，你应该能够从 Finder 进行连接。该设备应该会显示在“网络”文件夹中，或者通过以下方式显示：
```
smb://标签：Samba, Time Machine, 内存分配, 嵌入式系统, 硬件改造, 网络存储, 网络文件共享, 逆向工具