macos-timemachine/README.md

macOS 13 (Ventura) + Ubuntu 20.04 Samba 配置指南

适用版本：macOS 13 Ventura / Ubuntu 20.04 LTS / Samba 4.x

---

一、核心原理

macOS 通过 Apple SMB 扩展（AAPL） 与 Samba 交互，依赖以下三个 VFS 模块协同工作：

模块	作用
fruit	实现 AAPL 协议扩展，支持 Time Machine、macOS 元数据
streams_xattr	将 macOS 扩展属性（xattr）映射到 Linux 文件系统
catia	转义 macOS/Windows 文件名中的非法字符（如 : * ?）

三个模块必须同时声明：vfs objects = catia fruit streams_xattr
顺序固定：catia 在前，fruit 居中，streams_xattr 在后。

---

二、安装依赖

apt update
apt install -y samba samba-vfs-modules attr

验证 fruit 模块是否可用：

samba -b | grep MODULE_PATH
ls /usr/lib/*/samba/vfs/fruit.so

---

三、完整配置文件

[global]
    workgroup = WORKGROUP
    server string = %h server (Samba, Ubuntu)
    log file = /var/log/samba/log.%m
    max log size = 1000
    logging = file

    # ── 协议：macOS 13 要求最低 SMB2 ──────────────────────────
    server min protocol = SMB2
    server max protocol = SMB3

    # ── 认证：Ventura 默认 NTLMv2，禁用旧弱协议 ──────────────
    security = user
    map to guest = bad user
    guest account = nobody
    ntlm auth = ntlmv2-only
    # 注意：不要启用 lanman auth / null passwords，macOS 13 会拒绝

    # ── 字符集 ────────────────────────────────────────────────
    unix charset = UTF-8

    # ── Apple 扩展：全局开启，只需声明一次 ───────────────────
    fruit:aapl = yes
    fruit:nfs_aces = no
    fruit:copyfile = no
    fruit:delete_empty_adfiles = yes

    obey pam restrictions = yes
    unix password sync = yes
    passwd program = /usr/bin/passwd %u
    passwd chat = *Enter\snew\s*\spassword:* %n\n *Retype\snew\s*\spassword:* %n\n *password\supdated\ssuccessfully* .
    pam password change = yes


# ── 普通文件共享（允许 Guest 匿名访问）────────────────────────
[files]
    path = /mnt/sda1/500Gfiles
    browseable = yes
    writable = yes
    read only = no
    guest ok = yes
    public = yes
    create mask = 0777
    directory mask = 0777
    vfs objects = catia fruit streams_xattr   # ← 必须！
    fruit:time machine = no
    fruit:encoding = native
    fruit:metadata = stream


# ── 私有文件共享（需要账号密码）──────────────────────────────
[sdbfiles]
    path = /mnt/sdb1/files
    browseable = yes
    writable = yes
    read only = no
    guest ok = no
    valid users = ubuntu
    create mask = 0644
    directory mask = 0755
    vfs objects = catia fruit streams_xattr   # ← 必须！
    fruit:time machine = no
    fruit:encoding = native
    fruit:metadata = stream


# ── Time Machine 专用共享 ─────────────────────────────────────
[timemachine]
    comment = Time Machine Backup
    path = /mnt/sda1/timemachine
    browseable = yes
    writable = yes
    read only = no
    guest ok = no
    valid users = ubuntu                      # 只允许指定用户备份
    create mask = 0600
    directory mask = 0700
    vfs objects = catia fruit streams_xattr   # ← 必须！
    fruit:time machine = yes                  # ← 关键开关
    fruit:time machine max size = 200G        # 防止磁盘被填满，按需调整
    fruit:encoding = native
    fruit:metadata = stream

---

四、关键参数说明

4.1 协议版本

参数	推荐值	说明
server min protocol	SMB2	macOS 13 不支持 SMB1/NT1，设低了会被拒绝
server max protocol	SMB3	支持加密和多通道，性能更好

⚠️ 旧配置中常见的 NT1 会导致 macOS 13 连接失败。

4.2 认证方式

参数	推荐值	说明
ntlm auth	ntlmv2-only	macOS 13 默认只发送 NTLMv2
lanman auth	不设置/no	旧协议，macOS 13 不用且会降低安全性
null passwords	不设置/no	macOS 13 不支持空密码认证

4.3 fruit 参数

参数	说明
fruit:aapl = yes	开启 Apple 扩展协商，必须在 [global] 中声明
fruit:time machine = yes	将共享标记为 Time Machine 目标磁盘
fruit:time machine max size	限制 TM 最大使用空间（支持 G/T）
fruit:encoding = native	使用原生 UTF-8 编码存储文件名
fruit:metadata = stream	元数据存为流，避免污染目录
fruit:nfs_aces = no	禁用 NFS ACL，避免权限混乱
fruit:copyfile = no	禁用 APFS 服务端拷贝（普通 Linux FS 不支持）

---

五、部署步骤

# 1. 创建 Time Machine 目录并设置权限
mkdir -p /mnt/sda1/timemachine
chown ubuntu:ubuntu /mnt/sda1/timemachine
chmod 700 /mnt/sda1/timemachine

# 2. 为 Samba 用户设置密码（独立于系统密码）
smbpasswd -a ubuntu

# 3. 验证配置语法
testparm

# 4. 重启服务
systemctl restart smbd nmbd

# 5. 设置开机自启
systemctl enable smbd nmbd

---

六、macOS 端配置

6.1 添加 Time Machine 磁盘

1. 系统设置 → 通用 → Time Machine
2. 点击 添加备份磁盘
3. 选择 timemachine（局域网内应自动发现）
4. 若未发现，手动输入：smb://192.168.x.x/timemachine
5. 输入 Samba 用户名和密码

6.2 手动挂载普通共享

Finder → 前往 → 连接服务器（⌘K）
smb://192.168.x.x/files       # 匿名访问
smb://192.168.x.x/sdbfiles    # 账号访问

---

七、常见问题排查

问题 1：macOS 提示"连接失败"

# 服务端检查
systemctl status smbd
journalctl -u smbd -f

# 测试连通性（在 Mac 终端）
smbutil view //ubuntu@192.168.x.x

问题 2：Time Machine 找不到共享磁盘

# Mac 终端执行，刷新网络发现
defaults write com.apple.NetworkBrowser BrowseAllInterfaces 1
killall Finder

检查服务端 fruit 模块是否正确加载：

testparm -v 2>&1 | grep -i fruit

问题 3：上传文件报错或权限不足

# 检查共享目录权限
ls -la /mnt/sda1/timemachine

# 确认用户存在于 Samba 数据库
pdbedit -L

# 检查 xattr 支持（必须 ext4/xfs 挂载时带 user_xattr）
mount | grep sda1
# 若无 user_xattr，编辑 /etc/fstab 添加该选项后 remount

问题 4：Time Machine 备份速度慢

# smb.conf [global] 添加性能优化参数
socket options = TCP_NODELAY IPTOS_LOWDELAY SO_RCVBUF=131072 SO_SNDBUF=131072
read raw = yes
write raw = yes
use sendfile = yes
aio read size = 16384
aio write size = 16384

问题 5：macOS 提示密码错误但密码正确

# 重置 Samba 密码
smbpasswd -x ubuntu    # 删除旧条目
smbpasswd -a ubuntu    # 重新添加

---

八、配置检查清单

• vfs objects = catia fruit streams_xattr 在每个共享中都有声明
• fruit:aapl = yes 在 [global] 中声明
• server min protocol = SMB2（不是 NT1）
• ntlm auth = ntlmv2-only（不是 yes）
• lanman auth 和 null passwords 未启用
• Time Machine 共享的 fruit:time machine = yes
• Time Machine 目录所有者为对应 Samba 用户
• smbpasswd -a <用户名> 已设置 Samba 密码
• testparm 无报错
• smbd / nmbd 服务正常运行

---

最后更新：2026-04-14