# 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 在后。

---

## 二、安装依赖

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

验证 fruit 模块是否可用：
```bash
samba -b | grep MODULE_PATH
ls /usr/lib/*/samba/vfs/fruit.so
```

---

## 三、完整配置文件

```ini
[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 不支持）|

---

## 五、部署步骤

```bash
# 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 提示"连接失败"

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

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

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

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

检查服务端 fruit 模块是否正确加载：
```bash
testparm -v 2>&1 | grep -i fruit
```

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

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

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

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

### 问题 4：Time Machine 备份速度慢

```bash
# 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 提示密码错误但密码正确

```bash
# 重置 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*