Initial commit: combine nas_tool, nas_webdav, sync-utils

2026-02-18 22:59:43 +08:00
commit 526c6a5521
77 changed files with 7898 additions and 0 deletions
@@ -0,0 +1,207 @@
+# Time Machine NAS Connection Troubleshooting
+
+## Issue
+Time Machine shows "Connecting to backup disk..." but never completes, even though:
+- ✅ NAS is accessible from Finder
+- ✅ User `zjgump` is in administrators group (has full permissions)
+- ✅ Network connectivity is fine (ping works, SMB works in Finder)
+
+## Root Cause Analysis
+
+### Key Finding
+**`zjgump` is in the administrators group** - This means:
+- Explicit file permissions won't apply to SMB/file protocols
+- Admin users have full access by default
+- The "Permission denied" errors are NOT about file permissions
+
+### Actual Issues
+1. **Credential Cache Mismatch**: macOS has saved credentials for `DS224plus` (without .local) but Time Machine tries to use `DS224plus.local`
+2. **Stale Mounts**: Manual mounts interfere with Time Machine's automatic mounting
+3. **Time Machine Process Permissions**: Time Machine runs as a different user than your login user
+
+## Solutions
+
+### Solution 1: Clear Credentials and Let Time Machine Mount Itself (Recommended)
+
+1. **Unmount all existing mounts:**
+   ```bash
+   diskutil unmount "/Volumes/Time Machine Folder" 2>/dev/null
+   sudo umount -f /Volumes/.timemachine/* 2>/dev/null
+   ```
+
+2. **Clear saved credentials:**
+   - Open **Keychain Access**
+   - Search for `DS224plus`
+   - Delete ALL entries related to DS224plus
+   - Also search for `Time Machine` and delete related entries
+
+3. **Remove Time Machine destination:**
+   - System Settings → General → Time Machine
+   - Remove the existing backup disk (click `-` button)
+
+4. **Re-add Time Machine:**
+   - Click "Add Backup Disk..."
+   - Select "Time Machine Folder" on "DS224plus.local" (the one with `.local`)
+   - When prompted, enter `zjgump` credentials
+   - **Let Time Machine mount it itself** - don't mount it manually first
+
+### Solution 2: Use a Dedicated Time Machine User (Best Practice)
+
+Synology recommends using a **dedicated non-admin user** for Time Machine:
+
+1. **On Synology DSM:**
+   - Control Panel → User & Group → Create
+   - Create user: `tm-backup` (or similar)
+   - **Do NOT add to administrators group**
+   - Set password
+
+2. **Grant permissions:**
+   - Control Panel → Shared Folder → Time Machine Folder → Edit → Permissions
+   - Add `tm-backup` user with **Read/Write** permission
+   - Check "Apply to this folder, sub-folders and files"
+
+3. **Configure Time Machine on NAS:**
+   - Control Panel → File Services → Time Machine
+   - Select "Time Machine Folder" as the shared folder
+   - Select `tm-backup` as the user (or leave blank for all users)
+
+4. **On macOS:**
+   - Remove existing Time Machine destination
+   - Add Backup Disk → Select "Time Machine Folder – DS224plus.local"
+   - When prompted, use `tm-backup` credentials (not `zjgump`)
+
+### Solution 3: Fix Credential Cache for Admin User
+
+If you want to keep using `zjgump` (admin user):
+
+1. **Clear all DS224plus credentials:**
+   ```bash
+   security delete-internet-password -s "DS224plus" 2>/dev/null
+   security delete-internet-password -s "DS224plus.local" 2>/dev/null
+   ```
+
+2. **Remove Time Machine destination**
+
+3. **Manually connect via Finder first:**
+   - Finder → ⌘K → `smb://DS224plus.local`
+   - Connect as `zjgump`
+   - This will save the credential properly
+
+4. **Then add Time Machine:**
+   - System Settings → Time Machine → Add Backup Disk
+   - Select "Time Machine Folder – DS224plus.local"
+   - It should use the saved credential
+
+### Solution 4: Use IP Address Instead of Hostname
+
+If Bonjour (.local) is causing issues:
+
+1. **Find NAS IP:**
+   ```bash
+   ping -c 1 DS224plus.local | grep PING
+   # Or check your router's DHCP table
+   ```
+
+2. **Connect via IP:**
+   - System Settings → Time Machine → Add Backup Disk
+   - If it doesn't show up, manually mount first:
+     - Finder → ⌘K → `smb://192.168.1.172/Time Machine Folder`
+     - Connect as `zjgump`
+   - Then add the mounted share in Time Machine
+
+## Diagnostic Commands
+
+### Check Current Mounts
+```bash
+mount | grep -i "timemachine\|ds224plus"
+```
+
+### Check Time Machine Logs
+```bash
+log show --predicate 'subsystem == "com.apple.TimeMachine"' --last 10m --info | tail -50
+```
+
+### Check Saved Credentials
+```bash
+security find-internet-password -s "DS224plus"
+security find-internet-password -s "DS224plus.local"
+```
+
+### Test SMB Connection
+```bash
+smbutil status DS224plus.local
+```
+
+### Check Time Machine Configuration
+```bash
+tmutil listbackups
+defaults read /Library/Preferences/com.apple.TimeMachine
+```
+
+## Common Errors and Fixes
+
+### "Time Machine could not back up the disk because it is nearly full"
+- **Cause**: The **source disk** (Macintosh HD) is nearly full, NOT the destination (NAS)
+- **Symptoms**: Error says disk is "nearly full" but NAS shows plenty of space (e.g., 1.67TB available)
+- **Fix**: Free up space on your Mac's internal disk:
+  1. Run the diagnostic script: `./free_disk_space.sh`
+  2. Run the cleanup script: `./fix_time_machine_disk_full.sh`
+  3. Or manually:
+     - Empty Trash: `rm -rf ~/.Trash/*`
+     - Clean caches: `rm -rf ~/Library/Caches/*`
+     - Review Downloads folder (often has large files)
+     - Use macOS Storage Management: Apple Menu → About This Mac → Storage → Manage
+- **Why**: Time Machine needs free space on the source disk to:
+  - Create local snapshots
+  - Stage files for backup
+  - Maintain the backup process
+- **Minimum**: Aim for at least 5-10GB free space for Time Machine to work properly
+
+### "Deleted files but space not freed" / "Stuck Time Machine snapshot"
+- **Cause**: APFS snapshots (especially Time Machine local snapshots) hold onto deleted file space
+- **Symptoms**: 
+  - Deleted 20GB+ of files but disk space didn't increase
+  - Error: "Stale NFS file handle" when trying to delete snapshots
+  - `tmutil listlocalsnapshots /` shows snapshots that can't be deleted
+- **Fix**:
+  1. **Quick fix - Restart Mac**: Often the simplest solution - snapshots are released after restart
+  2. **Remove Time Machine destination temporarily**:
+     - System Settings → Time Machine → Remove backup disk
+     - Delete snapshot: `sudo tmutil deletelocalsnapshots <date>`
+     - Re-add Time Machine destination
+  3. **Use the fix script**: `./fix_stuck_snapshot.sh` (guides you through the process)
+  4. **Force purge**: `sudo purge` (if available)
+- **Why**: Time Machine creates local snapshots before backing up. If the backup destination (NAS) is unreachable or has a stale connection, the snapshot gets stuck and holds onto space from deleted files.
+- **Prevention**: Ensure Time Machine can reliably connect to backup destination
+
+### "Permission denied" on mount point
+- **Cause**: Manual mount with wrong permissions
+- **Fix**: Unmount and let Time Machine mount it itself
+
+### "Connecting to backup disk..." hangs
+- **Cause**: Credential cache mismatch or stale mount
+- **Fix**: Clear credentials, unmount all, re-add
+
+### "Server may not exist or unavailable"
+- **Cause**: Using wrong hostname (DS224plus vs DS224plus.local)
+- **Fix**: Always use `.local` version or IP address
+
+## Prevention
+
+1. **Don't manually mount Time Machine shares** - let Time Machine do it
+2. **Use dedicated non-admin user** for Time Machine (best practice)
+3. **Keep credentials in sync** - if you change NAS password, update on Mac
+4. **Use `.local` hostname** - more reliable than IP or NetBIOS name
+
+## Notes
+
+- Admin users (`zjgump`) bypass file-level permissions on Synology
+- Time Machine runs as `_backup` user on macOS, not your login user
+- Bonjour (`.local`) is preferred over NetBIOS for Time Machine
+- Manual mounts can interfere with Time Machine's automatic mounting
+
+
+
+
+
+