Git on KnightLi的博客

用 NAS 自建 Git Server 同步本地 Markdown 筆記

Sat, 30 May 2026 16:14:19 +0800

如果已經有一台本地 NAS，又希望筆記盡量保存在自己手裡，可以把 Markdown 筆記放進 NAS 上的 Git Server，再用 Android 和 Windows 用戶端同步。這個方案不依賴公共雲碟，適合 Obsidian、Markor、VS Code、Typora 這類以本地 Markdown 檔案為核心的筆記工具。

它的基本思路很簡單：

NAS 上建立一個 Git 裸倉庫，作為筆記的中央倉庫。
Windows 端 clone 倉庫，用常見編輯器寫筆記。
Android 端 clone 同一個倉庫，用 Git 用戶端拉取和推送。
每次換裝置前先 pull，寫完後再 commit 和 push。

這種方式不是最傻瓜的同步方案，但可控性很好，歷史版本也清楚。只要養成提交習慣，就能把筆記、設定、圖片附件都放在自己的 NAS 上長期保存。

方案適合誰

這套方案適合下面幾類人：

家裡或辦公室已經有 NAS。
筆記主要是 Markdown 檔案。
希望筆記資料保存在本地網路裡，而不是只放在商業雲碟上。
需要 Windows 和 Android 多裝置同步。
能接受 Git 的基本操作，例如 clone、pull、commit、push。

如果你希望完全自動、完全無感同步，Syncthing、WebDAV 或筆記軟體自帶同步可能更省心。Git 更適合重視版本歷史、可回滾、可遷移和可控性的筆記庫。

一、在 NAS 上安裝 Git Server

不同 NAS 系統的入口不一樣，但目標都一樣：讓 NAS 提供一個可以透過 SSH 存取的 Git 倉庫。

常見做法有三種：

方式	適合場景
NAS 套件中心安裝 Git Server	群暉、威聯通等成品 NAS，想少折騰
Docker 部署 Gitea	想要 Web 介面、帳號管理和更完整的 Git 服務
直接用 SSH + 裸倉庫	只給自己用，追求簡單穩定

如果只是個人筆記同步，SSH + 裸倉庫已經夠用。假設 NAS 上有一個專門的 Git 使用者 git，倉庫存放目錄為 /volume1/git，可以在 NAS 終端機裡執行：

1
2
3

mkdir -p /volume1/git/notes.git
cd /volume1/git/notes.git
git init --bare

裸倉庫不直接編輯檔案，只作為同步中心。實際寫筆記的目錄在 Windows 或 Android 本地。

接著確認 SSH 可以存取 NAS：

`1`	`ssh git@192.168.1.10`

如果 NAS 支援 SSH 公鑰登入，建議設定公鑰，避免每次推送都輸入密碼。Windows 和 Android 可以分別產生自己的 SSH key，再把公鑰加入 NAS 的 authorized_keys 或 Git Server 使用者設定裡。

二、Windows 端設定

Windows 端建議安裝 Git for Windows，然後選擇一個本地目錄存放筆記，例如 D:\Notes。

首次 clone：

`1`	`git clone git@192.168.1.10:/volume1/git/notes.git D:\Notes`

進入目錄後，可以建立基本結構：

1
2

cd D:\Notes
mkdir inbox, daily, projects, resources

然後用 Obsidian、VS Code、Typora 或其他 Markdown 編輯器打開 D:\Notes。寫完第一批筆記後提交：

1
2
3

git add .
git commit -m "初始化笔记库"
git push origin main

如果倉庫預設分支是 master，就把命令裡的 main 換成 master。也可以統一改成 main：

1
2

git branch -M main
git push -u origin main

日常使用時，Windows 端可以保持這個節奏：

git pull --rebase
git add .
git commit -m "更新笔记"
git push

三、Android 端設定

Android 端可以使用支援 Git 的用戶端來同步本地 Markdown 目錄。常見選擇包括：

工具	用法
Termux	最靈活，接近 Linux 命令列
MGit	圖形介面 Git 用戶端，適合不想敲太多命令
GitJournal	更像筆記應用，適合簡單 Markdown 筆記

如果選擇 Termux，可以先安裝 Git 和 OpenSSH：

1
2

pkg update
pkg install git openssh

產生 SSH key：

`1`	`ssh-keygen -t ed25519 -C "android-notes"`

把產生的公鑰加入 NAS 的 Git 使用者授權裡。然後在手機本地選擇一個目錄 clone 倉庫：

`1`	`git clone git@192.168.1.10:/volume1/git/notes.git ~/notes`

如果想讓普通 Android 編輯器存取這個目錄，可以把倉庫放到共享儲存目錄，例如：

1
2

cd /sdcard
git clone git@192.168.1.10:/volume1/git/notes.git Notes

之後可以用 Markor、Obsidian Android 或其他 Markdown 編輯器打開 /sdcard/Notes。手機端修改後，再回到 Termux 執行：

cd /sdcard/Notes
git pull --rebase
git add .
git commit -m "手机更新笔记"
git push

Android 上最容易出問題的是權限和路徑。Termux 自己的家目錄更穩定，但部分編輯器不一定能直接存取；/sdcard 方便編輯器存取，但權限、檔案監聽和效能可能受系統限制。可以先用少量筆記測試，再決定最終目錄。

四、Obsidian 和 Joplin 怎麼落地

NAS Git Server 只解決「檔案放在哪裡、怎麼同步」的問題。真正寫筆記時，還需要選擇筆記應用。這裡可以分成 Obsidian 方案和 Joplin 方案。

方案	同步方式	適合人群	注意點
Obsidian + Git	筆記目錄就是 Git 倉庫，Windows 和 Android 都拉取同一個倉庫	想要雙鏈、知識圖譜、外掛生態和純 Markdown 檔案的人	Android 上最好先測試 Git 用戶端和 Obsidian 對同一目錄的存取權限
Joplin + Git	不建議直接把 Joplin 資料庫放進 Git；更適合用 Joplin 自帶同步，或定期匯出 Markdown 到 Git	想要網頁剪藏、端到端加密、傳統筆記本結構的人	Joplin 的本地資料不是普通 Markdown 資料夾，不適合直接當 Git 筆記庫同步

Obsidian 方案

Obsidian 最適合這套 NAS Git 同步方案。原因是它的 vault 本質上就是一個普通資料夾，裡面是 Markdown 檔案、圖片附件和設定檔。你可以直接把 D:\Notes 或 /sdcard/Notes 作為 Obsidian vault。

Windows 端流程：

`1`	`git clone git@192.168.1.10:/volume1/git/notes.git D:\Notes`

然後在 Obsidian 裡打開 D:\Notes。

Android 端流程：

1
2

cd /sdcard
git clone git@192.168.1.10:/volume1/git/notes.git Notes

然後在 Obsidian Android 裡打開 /sdcard/Notes。

Obsidian 方案建議：

單人使用時，可以提交 .obsidian/，讓主題、外掛和部分設定在多裝置間同步。
如果 Android 和 Windows 外掛差異很大，可以只提交筆記正文，不提交 .obsidian/workspace.json 這類裝置狀態檔。
圖片附件建議統一放到 attachments/，避免散落在各級目錄裡。
每次打開 Obsidian 前先 git pull --rebase，寫完後再 commit 和 push。

可以準備一個 .gitignore，減少裝置狀態檔造成的衝突：

1
2
3

.obsidian/workspace.json
.obsidian/workspace-mobile.json
.trash/

Joplin 方案

Joplin 的思路和 Obsidian 不一樣。它雖然使用 Markdown 語法，但本地資料主要由應用資料庫管理，不是一個可以直接拿來 Git 同步的普通 Markdown 資料夾。因此，不建議把 Joplin 的設定目錄或資料庫目錄直接放進 Git 倉庫。

如果你更喜歡 Joplin，有兩種更穩的做法：

做法	說明
使用 Joplin 自帶同步	透過 WebDAV、Nextcloud、Joplin Cloud、Dropbox、OneDrive 等方式同步，NAS 可以提供 WebDAV 或 Nextcloud
定期匯出 Markdown 到 Git	Joplin 作為主力筆記應用，定期把筆記匯出為 Markdown，再提交到 NAS Git 倉庫做備份

如果 NAS 上已經有 WebDAV 或 Nextcloud，Joplin 直接連 NAS 同步會比 Git 更順滑。它還可以啟用端到端加密，適合不想處理 Git 衝突、但又希望資料盡量在自己控制範圍內的人。

Joplin + NAS 的推薦路線是：

NAS 上開啟 WebDAV 或部署 Nextcloud。
Joplin Windows 端設定同一個同步目標。
Joplin Android 端設定同一個同步目標。
需要版本備份時，再定期匯出 Markdown 到 Git 倉庫。

簡單判斷：

想要「本地 Markdown 資料夾 + 雙鏈 + Git 歷史」，選 Obsidian。
想要「傳統筆記應用 + 網頁剪藏 + 加密同步」，選 Joplin。
想把 NAS Git Server 作為主同步中心，Obsidian 更合適。
想把 NAS 當成私有雲同步後端，Joplin 更合適。

五、推薦的筆記目錄結構

筆記庫不要一開始就設計得太複雜。可以先用下面這種結構：

Notes/
  inbox/
  daily/
  projects/
  resources/
  attachments/
  README.md

含義很直觀：

inbox/ 放臨時記錄。
daily/ 放日記、日誌和每日流水。
projects/ 放專案筆記。
resources/ 放長期資料。
attachments/ 放圖片、PDF 和其他附件。

如果使用 Obsidian，可以把這個目錄直接作為 vault。.obsidian/ 設定是否提交，要看個人習慣。單人多裝置使用時可以提交；如果不同裝置外掛差異很大，也可以只提交部分設定。

六、避免同步衝突

Git 同步筆記的關鍵不是命令多複雜，而是習慣要穩定。

建議遵守幾條規則：

換裝置寫筆記前，先執行 git pull --rebase。
寫完一輪後，及時 commit 和 push。
不要在兩台裝置上同時長時間編輯同一個檔案。
圖片和大附件不要無限塞進 Git 倉庫。
定期在 NAS 外再備份一份倉庫。

如果出現衝突，Git 會標出衝突檔案。Markdown 文字衝突通常不難處理，但手機上處理體驗比較差，所以盡量在 Windows 上解決衝突。

七、是否需要自動同步

可以給 Windows 寫一個簡單腳本，把 pull、add、commit、push 串起來。但筆記同步不建議完全無腦自動提交，因為誤刪、空提交、衝突和大附件都可能被自動推上去。

更穩妥的方式是半自動：

打開筆記前先手動拉取。
寫完後執行一個腳本提交。
每次提交訊息簡單說明這次改了什麼。

例如 Windows 可以準備一個 sync-notes.ps1：

git pull --rebase
git add .
git commit -m "更新笔记"
git push

如果沒有變更，git commit 會提示 nothing to commit，這不是問題。

八、這個方案的優缺點

方面	說明
優點	資料在本地 NAS，版本歷史清晰，可回滾，可遷移，適合 Markdown
缺點	需要理解 Git，衝突需要手動處理，移動端體驗不如雲同步順滑
適合	技術使用者、本地優先筆記、個人知識庫、專案文件
不適合	完全不想接觸命令列、需要多人即時協作、頻繁同步大附件

我的建議

如果只是想在 Android 和 Windows 之間同步普通 Markdown 筆記，可以先從最小方案開始：NAS 上一個裸倉庫，Windows 上 Git for Windows，Android 上 Termux 或 MGit。不要一開始就引入複雜權限、自動化腳本和過度分類。

等這套流程跑順以後，再考慮 Gitea、自動備份、SSH key 分裝置管理、附件分倉庫、定時任務等擴展。筆記系統最重要的是長期穩定可用，而不是第一天就把所有功能堆滿。

一句話：NAS Git Server 適合把 Markdown 筆記做成本地優先、可追溯、可遷移的個人資料庫；它不如雲同步省心，但控制權更清楚。

使用 Agent Skills 取代 VS Code 中 Copilot 的「生成提交訊息」功能

Mon, 06 Apr 2026 13:09:49 +0800

VS Code 的 GitHub Copilot「生成提交訊息」是一個非常實用的功能。配額用盡後，重置週期通常會比較長。本文提供一個實作方案：使用本地 Agent Skills 取代這個功能。

問題與目標

本文目標是提供一套可直接落地的替代方案：使用 git-commit-push-zh skill agents 完成標準化提交與推送。

替代方案：`git-commit-push-zh`

該 skill 將「目前改動」收斂為固定流程：

檢查變更狀態。
確認目前分支。
暫存改動。
生成中文提交訊息。
執行 commit。
推送到遠端分支。

對應命令如下：

git status --short
git branch --show-current
git add -A
git commit -m "<中文提交信息>"
git push origin <当前分支>

提交訊息建議規範

建議統一格式：

`1`	`<类型>(<范围>): <中文摘要>`

類型示例：

feat：新增功能
fix：修復問題
docs：文件更新
refactor：程式重構
chore：維護性改動

示例：

feat(site): 新增全站 head 广告脚本注入
fix(i18n): 修正 relref 相关文章链接路径
chore(content): 合并 AI 工作流分类到 AI工具

常見失敗場景

nothing to commit：目前無可提交改動，停止推送即可。
push 失敗：優先檢查權限、遠端分支狀態與衝突。
SSH/權限異常：確認憑證與權限後再重試。

附錄：原始 `SKILL.md`

以下內容為 git-commit-push-zh 的原始文件，原樣保留，便於後續復用與維護。

---
name: git-commit-push-zh
description: 在当前 Git 仓库中将“当前更改”完成一次标准提交流程：检查状态、暂存变更、生成中文提交信息、执行 commit 并 push 到当前分支对应远端。用户提出“提交代码”“提交当前更改”“生成中文提交信息并推送”“git commit push 中文说明”等请求时使用。
---

# 中文提交并推送

使用此技能将当前仓库改动一次性提交并推送到远端。

## 工作流程

1. 查看变更状态：`git status --short`。
2. 确认当前分支：`git branch --show-current`。
3. 暂存当前变更：`git add -A`。
4. 生成中文提交信息（简洁、可检索）。
5. 执行提交：`git commit -m "<中文提交信息>"`。
6. 执行推送：`git push origin <当前分支>`。

## 提交信息规范（中文）

1. 建议格式：`<类型>(<范围>): <中文摘要>`。
2. 类型示例：`feat`、`fix`、`chore`、`docs`、`refactor`。
3. 摘要要求：准确描述本次改动，不写空话。
4. 若仅少量变更，也保持可读性与可检索性。

示例：

- `feat(site): 新增全站 head 广告脚本注入`
- `fix(i18n): 修正 relref 相关文章链接路径`
- `chore(content): 合并 AI 工作流分类到 AI工具`

## 错误处理

1. 若无可提交变更（nothing to commit），明确告知并停止 push。
2. 若 push 失败，先回报关键错误（权限、远端不存在、冲突等）。
3. 常见 SSH/权限问题可在用户确认后重试高权限环境。

## 输出约定

1. 汇报提交哈希、分支名、提交信息。
2. 汇报 push 结果（成功或失败原因）。
3. 仅在确有失败时提供下一步最小操作建议。

Git 如何追蹤檔案可執行權限（+x）

Sun, 29 Mar 2026 10:00:00 +0800

在 Linux 環境中，Git 會追蹤檔案的可執行位（+x）。如果你希望腳本在倉庫中被當作「可執行檔」保留下來，需要用 Git 明確記錄這次權限變更。

為檔案新增可執行權限

1
2
3

git update-index --chmod=+x script.sh
git commit -m "chore: mark script.sh as executable"
git push

這條指令會把 script.sh 的可執行位變更加入暫存區。提交並推送後，其他人在拉取或克隆倉庫時也會保留這個權限狀態。

取消檔案可執行權限

1
2
3

git update-index --chmod=-x script.sh
git commit -m "chore: remove executable bit from script.sh"
git push

驗證是否生效

可以用下面的指令檢查工作區權限：

1
2

git clone xxxxxxxxxxxxxxx
ls -l script.sh

如果看到類似 -rwxr-xr-x，表示檔案包含可執行權限；如果是 -rw-r--r--，則表示不可執行。

說明

git update-index --chmod=+x/-x 只會修改 Git 記錄的檔案模式，不會替代你對檔案內容本身的修改。
在團隊協作中，建議把這類權限調整獨立提交，便於審查與追溯。