一、为什么需要版本管理

知识库建好以后，文件改坏了或者是误删了，无法恢复。再就是没有修改历史，不知道内容何时发生了变化。缺少一个项目看板，追踪灵感落地进度。

个人知识库只需要用轻量化、本地化，不需要复杂的功能即可。如果对 Git 服务器看板的样式不喜欢，还可以用 AI 自己做一个看板项目。这里我主要是为了做个人成长，我不需要太花里胡哨的东西，实用就好。

---

二、方案选型：为什么选 Gitea

知识库建好以后，最好需要安装一个版本管理系统，可以选择 SVN 服务器或者是 Git 服务器。目前各类工具对 Git 的支持非常友好，在 AI 中处理也很方便，所以优先选 Git。

AI 给出了我四个解决方案，然后我选择了 GITEA 这个软件，它比较适合个人知识库。

方案	优点	缺点	适合场景
Gitea	极轻量、单二进制、内置看板、SQLite 免维护	功能比 GitLab 少	个人/小团队本地知识库
GitLab CE	功能最全、CI/CD 强	内存至少 4G+、安装重	团队级 DevOps
Gogs	更轻量	看板较弱、更新慢	只想要 Git 托管
Forgejo	Gitea 分支、完全开源	生态略小	偏好纯开源

---

三、Gitea 安装步骤

前置说明： 本机是 Win11 系统，已经安装了 Obsidian、Claude Code、Git命令工具。

我在本地建好了目录：“D:\Program Files\gitea”
接下来直接丢给 AI，让 AI 帮我下载 GITEA 这个软件。本机操作系统是 win 11，以下是下载脚本：

$dir = "D:\Program Files\gitea"
$url = "https://dl.gitea.com/gitea/1.26.4/gitea-1.26.4-windows-4.0-amd64.exe"

# 创建子目录
New-Item -ItemType Directory -Path "$dir\custom\conf" -Force
New-Item -ItemType Directory -Path "$dir\data" -Force
New-Item -ItemType Directory -Path "$dir\log" -Force

# 下载
Invoke-WebRequest -Uri $url -OutFile "$dir\gitea.exe" -UseBasicParsing

这里踩了个小坑：GitHub Releases 页面在国内经常打不开或者显示空白，一开始以为是版本号写错了，后来才发现是被墙了。换成 dl.gitea.com 这个官方下载站的直链就能正常下载了。

下载完运行：

& "D:\Program Files\gitea\gitea.exe" web --config "D:\Program Files\gitea\custom\conf\app.ini"

浏览器打开 http://localhost:3000，进入首次运行向导。

---

四、数据库选择

安装向导走到数据库这一步，问 AI 该选哪个，AI 建议：个人知识库场景直接选 SQLite3。

数据库	优点	缺点	是否适合
SQLite3	零安装、单文件、备份简单、资源占用最低	高并发下有锁竞争	✅ 个人使用完美
MySQL/MariaDB	并发强、生态成熟	需额外安装服务、配置复杂	没必要
PostgreSQL	更健壮、功能多	更重，配置更复杂	没必要

数据库类型选 SQLite3，数据库文件路径保持默认即可，实际会生成在 D:\Program Files\gitea\data\gitea.db。

备份也很简单：因为整个数据库就是一个文件，把下面两个目录打包或复制即可完成备份：

D:\Program Files\gitea\data
D:\Program Files\gitea\custom

以后如果知识库数据量变大、需要多人协作，可以再迁移到 MySQL 或 PostgreSQL，Gitea 支持这种迁移。现在没必要为未来的可能性增加复杂度。

---

五、创建仓库与项目看板

初始化向导走完，接下来在网页上创建仓库，AI 帮我确认了每个字段该怎么填：

字段	建议
拥有者	admin
仓库名称	Personal-Knowledge-Vault
可见性	私有，个人知识库必须私有
描述	个人知识库 - 笔记、文档与版本管理
.gitignore	先留空，创建后再手动添加
初始化仓库	建议勾选，这样会自动创建 README
默认分支	main

创建完成后，在仓库根目录添加 .gitignore，内容适合 Obsidian / Markdown 知识库：

# Obsidian 临时文件
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/plugins/
.trash/

# 系统文件
.DS_Store
Thumbs.db
desktop.ini

# 临时文件
*.tmp
*.swp

---

六、将本地知识库导入 Gitea

仓库建好了，该把本地已有的知识库目录推上去。本地目录之前没有初始化过 Git，所以走的是这一套命令：

cd D:\Personal-Knowledge-Vault
git init
git add .
git commit -m "Initial commit"
git remote add gitea http://localhost:3000/admin/Personal-Knowledge-Vault.git
git branch -M main
git push -u gitea main

如果本地目录已经是 Git 仓库，只需要加一个远程再推送：

git remote add gitea http://localhost:3000/admin/Personal-Knowledge-Vault.git
git push -u gitea main

这一步没有一次顺利，中间卡了好几次，具体记在下面的踩坑记录里。

---

七、踩坑记录

1. .gitignore 无法重写，报错 unable to unlink old '.gitignore'

编辑器（Obsidian / VS Code）打开着这个文件占用了句柄，Git 没法覆盖。关掉编辑器再重试就解决了。

2. 中文文件名显示乱码

git status 里中文文件名显示成一串转义字符，设置一下就好：

git config --global core.quotepath false
git config --global core.longpaths true

core.quotepath false 让中文文件名正常显示，core.longpaths true 避免 Windows 长路径报错。

3. 本地历史和远程 README 冲突

Gitea 初始化仓库时自动生成了 README，跟本地推送的提交历史对不上，直接 push 被拒绝。用 rebase 合并：

git pull gitea main --rebase

冲突了就手动编辑冲突文件，然后：

git add .
git rebase --continue
git push gitea main

如果 rebase 中途想放弃，git rebase --abort 能退回原状态。

4. 推送时认证失败

嫌每次输密码麻烦，可以生成访问令牌，一次配置以后就不用再输密码。

生成访问令牌的步骤：

1. 打开 http://localhost:3000，点击右上角头像 → 设置
2. 左侧菜单选 应用（不是 GPG 密钥那个页面，容易走错）
3. 在"生成新的令牌"里填个名称，比如 local-pc
4. 权限勾选 write:repository（只需要仓库读写权限）
5. 点击生成，立即复制令牌——这个令牌只显示这一次，关闭页面后无法再次查看

拿到令牌后，把它拼进远程仓库地址：

git remote set-url gitea http://admin:你的令牌@localhost:3000/admin/Personal-Knowledge-Vault.git

之后 git push 就不会再要求输入密码。

如果忘记 admin 密码，也可以在 Gitea 安装目录下用命令行重置：

cd "D:\Program Files\gitea"
.\gitea.exe admin user change-password --username admin --password 新密码

5. __pycache__ 混进了提交

忘记在 .gitignore 加 Python 缓存规则，.pyc 文件被一起提交了。发现后把它从 Git 跟踪中移除：

git rm -r --cached __pycache__

再在 .gitignore 补上：

__pycache__/
*.pyc
*.pyo

6. 开机自启动

每次重启后，由于 gitea 没有自动运行，导致提交文件失败，这里需要一个系统服务让它开机自动运行。

sc create gitea start= auto binPath= "\"D:\Program Files\gitea\gitea.exe\" web --config \"D:\Program Files\gitea\custom\conf\app.ini\""

现在服务已经创建好了，下一步就是运行 sc start gitea 启动它。

---

八、日常使用：提交命令速查

踩完坑之后，日常更新笔记就很简单，三行命令：

cd D:\Personal-Knowledge-Vault
git add .
git commit -m "2026-07-02 更新笔记"
git push

也可以全程在Claude Code中操作。（在Obsidian中安装Claude SideBar扩展）

几个小建议：

• 提交信息按日期或主题写，比如"添加决策日志模板"、“整理参考资料”
• 改错了可以在 Gitea 网页的"提交历史"里翻旧版本