用群晖 NAS、Tailscale 和 Git Server 管理个人文档版本

适用场景：群晖 NAS 放在家中，Mac 在外地使用；两端通过 Tailscale 连接；希望用 Git 保存 Markdown、脚本和办公文档的修改历史，不再维护“最终版”“最终版2”“最终版真的最终版”。

一、这套方案解决什么问题

普通文件同步解决的是“把当前文件复制到另一台设备”，Git 解决的是“保存每一次有意义的修改历史”。

最终结构如下：

Mac 工作目录
├── Markdown、脚本和办公文档
├── .git（Mac 本地版本历史）
└── .gitignore（排除规则）
          │
          │ git push / git pull
          ▼
Tailscale 加密网络
          │
          ▼
群晖共享文件夹 /volume1/git-repos
└── work.git（bare 服务器仓库）

各组件的职责：

• Mac 工作目录：日常打开和编辑文件。
• Synology Drive：继续同步普通文件。
• Git：记录主动确认的版本、修改人、时间和说明。
• 群晖 Git Server：保存 Git 远端历史，供备份或其他电脑访问。
• Tailscale：让外地 Mac 安全访问家中 NAS，无需在路由器开放公网 SSH 端口。

二、开始之前

需要准备：

• 一台群晖 NAS，使用 DSM 7；
• MacBook；
• NAS 和 Mac 已加入同一个 Tailscale 网络；
• 一个属于群晖 administrators 群组的 DSM 账户；
• 需要纳入版本管理的工作目录。

本文使用以下占位符：

DSM 用户名：<DSM_USER>
NAS 的 Tailscale IP：<NAS_TAILSCALE_IP>
SSH 端口：22
群晖共享文件夹：git-repos
群晖仓库：work.git
Mac 工作目录：<WORK_DIR>

示例工作目录：

/Users/yourname/Library/CloudStorage/SynologyDrive-example/work

三、准备 Mac 上的 Git

打开“终端”，检查 Git：

git --version

如果提示尚未同意 Xcode 和 Apple SDK 许可，可运行：

sudo xcodebuild -license

阅读至末尾并按提示确认。若已经阅读并明确同意，也可以执行：

sudo xcodebuild -license accept

再次检查：

git --version

配置提交身份：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

姓名和邮箱只是写入提交记录的作者信息，不是群晖登录凭据。配置一次后，Mac 上的仓库默认都会使用它们。

四、配置群晖 Git Server

1. 安装 Git Server

登录 DSM，进入：

套件中心 → 搜索 Git Server → 安装

安装后打开 Git Server，在用户列表中允许实际使用的管理员账户访问；不要允许 guest。

2. 启用 DSM SSH

进入：

控制面板 → 终端机和 SNMP → 终端机

设置：

☐ 启动 Telnet 功能
☑ 启动 SSH 功能
端口：22

不要在家中路由器上转发 SSH 端口。本方案只通过 Tailscale 访问。

Synology 不能作为 Tailscale SSH 服务器，所以这里使用的是 DSM 自带 SSH 服务，只是网络路径经过 Tailscale。参见 Tailscale 的 Synology 说明。

3. 创建仓库存储位置

进入：

控制面板 → 共享文件夹 → 新增

建议设置：

名称：git-repos
所在位置：存储空间 1
回收站：可启用
只允许管理员访问：启用
额外加密：暂时跳过
WriteOnce：不要启用

创建完成后，服务器路径通常是：

/volume1/git-repos

Git 仓库需要持续修改内部对象，因此不适合启用 WriteOnce。

五、确认 Tailscale 和 SSH 连通

如果通过 QuickConnect 登录 DSM，可能无法直接打开 Tailscale 套件页面。这不代表 Tailscale 故障。

可以登录 Tailscale 设备列表，找到 NAS 的 100.x.x.x 地址。

在 Mac 终端连接：

ssh -p 22 <DSM_USER>@<NAS_TAILSCALE_IP>

首次连接会出现服务器指纹确认。核对 IP 确实属于自己的 NAS 后，输入：

yes

随后输入 DSM 密码。密码输入过程中终端不会显示字符。

成功后提示符类似：

<DSM_USER>@nas-name:~$

群晖还会显示一段“不要随意修改系统配置、数据应存放在共享文件夹”的警告。这是正常登录提示，不是错误。

六、规划仓库范围

不必为每个小文件夹都建立一个 Git 仓库。如果目录结构类似：

work/
├── 项目 A/
├── 项目 B/
└── 项目 C/

可以直接把整个 work 作为一个仓库。这样所有子目录统一记录，新建子目录也会自动进入该仓库。

但不要把包含大量无关数据的整个用户目录做成仓库。一个仓库最好对应一个清晰领域，例如：

work.git       工作文档
courses.git    课程资料
notes.git      私人笔记

七、检查真实目录

进入工作目录：

cd "<WORK_DIR>"
pwd

检查是否存在嵌套 Git 仓库：

find . -type d -name .git -prune -print

如果该命令显示子目录，先不要继续。嵌套仓库需要单独规划。

统计 Markdown 数量：

find . -type f -name "*.md" | wc -l

也应检查目录中是否有超大音视频、数据库、缓存、密钥和临时输出。这些内容通常不适合普通 Git。

八、初始化本地仓库

在工作目录执行：

git init -b main
git config core.quotePath false
git config core.fileMode false

三个设置分别表示：

• 创建以 main 为主分支的仓库；
• 让中文文件名正常显示；
• 避免 Synology Drive 或不同系统的权限位差异制造无意义修改。

九、设置 .gitignore

.gitignore 用来告诉 Git 哪些文件不应进入历史。

下面是一份适合“文档 + 脚本”仓库的基础配置：

# macOS and Synology Drive metadata
.DS_Store
.SynologyWorkingDirectory/
.claude/
.work-*/

# Local secrets and private keys
.env
.env.*
*.pem
*.key
*.p12

# Python caches and local environments
__pycache__/
*.py[cod]
.venv/
venv/

# JavaScript dependencies and generated caches
node_modules/
.cache/

# Large media files remain in Synology Drive, not Git
*.mp3
*.wav
*.m4a
*.mp4
*.mov

这份规则采用“默认跟踪，按类型排除”的思路，因此 Markdown、Python、Shell、JavaScript、JSON、Word、Excel 和 PDF 都可以进入仓库。

需要注意：

• Git 可以保存 Word、Excel、PDF 的版本，但不能像 Markdown 那样方便地展示逐行差异；
• 大型二进制文件每次修改可能让仓库明显膨胀；
• .env、私钥和访问令牌不要提交；
• 忽略录音不等于删除录音，文件仍在原目录并继续由 Synology Drive 同步。

Synology Drive 官方文档说明隐藏文件和隐藏文件夹不属于支持的同步对象，因此 .git 通常不会由 Synology Drive 同步；Git 远端仍应通过 git push 单独保存。Synology Drive Client 文档

十、第一次本地提交

先检查 Git 准备纳入哪些文件：

git status --short --untracked-files=all

确认没有密钥、大型媒体或无关文件后：

git add --all
git commit -m "首次纳入工作文档与脚本"

检查结果：

git status
git log -1 --oneline

正常状态应为：

nothing to commit, working tree clean

十一、在群晖创建 bare 仓库

登录 NAS：

ssh -p 22 <DSM_USER>@<NAS_TAILSCALE_IP>

在群晖终端运行：

cd /volume1/git-repos
git init --bare --initial-branch=main work.git
exit

成功信息类似：

Initialized empty Git repository in /volume1/git-repos/work.git/

work.git 是 bare 仓库。它没有供人直接编辑的普通文档目录，而是专门接收和保存 Git 对象及历史。

十二、连接群晖并首次推送

回到 Mac 工作目录：

cd "<WORK_DIR>"

添加远端：

git remote add origin "ssh://<DSM_USER>@<NAS_TAILSCALE_IP>:22/volume1/git-repos/work.git"

检查地址：

git remote -v

首次推送：

git push -u origin main

成功信息类似：

[new branch] main -> main
branch 'main' set up to track 'origin/main'

十三、配置 SSH 公钥，避免反复输入密码

先确认 Mac 是否已有公钥：

find "$HOME/.ssh" -maxdepth 1 -type f -name "*.pub" -print

如果已经有 id_ed25519.pub，执行：

ssh-copy-id -i "$HOME/.ssh/id_ed25519.pub" -p 22 <DSM_USER>@<NAS_TAILSCALE_IP>

输入一次 DSM 密码。成功后会看到：

Number of key(s) added: 1

以后 git push 通常不再需要密码。

如果没有密钥，可先生成：

ssh-keygen -t ed25519 -f "$HOME/.ssh/id_ed25519" -C "macbook-git"

私钥 id_ed25519 必须留在 Mac，不要分享；上传到 NAS 的只是 .pub 公钥。

十四、日常工作流

每次完成一批有意义的修改后：

cd "<WORK_DIR>"
git status
git diff
git add --all
git commit -m "说明本次修改"
git push

例如：

git commit -m "更新主任行动方案并补充任务清单"

其中：

• git status：查看哪些文件发生变化；
• git diff：查看文本具体改了什么；
• git add --all：选择新增、修改和删除；
• git commit：在 Mac 本地创建版本；
• git push：把版本同步到群晖。

在 git diff 中：

• - 表示旧内容；
• + 表示新内容；
• END 表示到达末尾；
• 按 q 退出分页查看器。

断网时仍可正常 commit，恢复网络后再 push。

十五、查看和恢复历史

查看简洁历史：

git log --oneline --decorate

查看某个文件的历史：

git log --follow -- "相对路径/文件.md"

查看某个旧版本的文件内容：

git show <提交编号>:"相对路径/文件.md"

放弃尚未提交的修改：

git restore -- "相对路径/文件.md"

把文件恢复到某个历史版本，并把恢复动作保存成新版本：

git restore --source=<提交编号> -- "相对路径/文件.md"
git add --all
git commit -m "恢复某文件的历史版本"
git push

初学阶段不要随意使用：

git reset --hard

它可能丢弃尚未提交的修改。

十六、多台电脑使用时的注意事项

Synology Drive 会同步普通文件，但不会可靠地同步 .git。因此不要假设另一台电脑上的同名同步目录天然就是同一个 Git 工作副本。

更稳妥的选择有两种：

1. 只指定一台 Mac 负责 Git 提交，其他设备仅通过 Synology Drive 编辑；
2. 在其他电脑上从群晖 git clone 到独立的非同步目录，并使用 git pull、git push 协作。

第二台电脑克隆示例：

git clone "ssh://<DSM_USER>@<NAS_TAILSCALE_IP>:22/volume1/git-repos/work.git"

多台电脑编辑时，开始前先执行：

git pull --rebase

十七、常见问题

1. git status 中中文文件名显示为转义数字

git config core.quotePath false

2. nothing added to commit

表示尚未把修改加入暂存区：

git add --all
git commit -m "提交说明"

3. QuickConnect 无法打开 Tailscale 套件

这是 QuickConnect 的代理限制，不一定是 Tailscale 故障。到 Tailscale 管理后台查找 NAS 地址，然后直接通过 Tailscale IP 连接。

4. Permission denied (publickey,password)

检查：

• DSM SSH 是否启用；
• 用户是否属于 administrators；
• Git Server 是否允许该用户；
• 用户是否拥有 git-repos 共享文件夹读写权限；
• Tailscale IP 和 SSH 端口是否正确。

5. 出现 post-quantum key exchange 警告

新版 OpenSSH 可能提示群晖 SSH 尚未使用后量子密钥交换算法。这通常只是能力提醒，不代表连接或推送失败。当前连接仍经过 SSH 加密，并且网络层还经过 Tailscale。可在未来 DSM/OpenSSH 支持相应算法后升级。

6. 为什么在 File Station 中看不到正常文档结构

因为服务器端使用的是 bare 仓库。它保存 Git 历史，不是供人直接编辑的工作目录。查看文档应使用 Mac 工作副本，或把仓库克隆到另一个工作目录。

十八、备份与安全建议

Git Server 不是完整灾备方案。建议同时：

• 给 git-repos 共享文件夹设置 Hyper Backup；
• 如果 NAS 使用 Btrfs，可启用共享文件夹快照；
• 不在路由器暴露 SSH；
• 保持 Tailscale、DSM 和 Git Server 更新；
• 定期执行一次测试克隆，确认仓库可以恢复；
• 不提交密码、访问令牌、私钥和包含敏感信息的 .env 文件。

十九、最终检查清单

[ ] Mac 的 git --version 正常
[ ] Git 姓名和邮箱已配置
[ ] NAS 与 Mac 在同一 Tailscale 网络
[ ] DSM 已安装 Git Server
[ ] DSM SSH 已启用
[ ] git-repos 共享文件夹已创建
[ ] 本地仓库已初始化
[ ] .gitignore 已检查
[ ] 首次提交已完成
[ ] 群晖 bare 仓库已创建
[ ] origin 地址正确
[ ] git push 成功
[ ] SSH 公钥已配置
[ ] git status 显示 working tree clean

完成这些设置后，日常真正需要记住的只有三件事：

git add --all
git commit -m "我这次改了什么"
git push

这就是用 Git 代替“1.0 版、2.0 版、最终版”的核心工作方式。