个人知识库系统

版本：v1.3 创建时间：2026-04-29 最后更新：2026-04-29

版本记录

版本	时间	更新内容
v1.3	2026-04-29	Gitea Webhook + 宿主机 webhook 接收器：push 后立即 mkdocs build（见运维文档）；cron 建议改为兜底
v1.2	2026-04-29	新增《选型对比-存储与架构》《实施复盘-问题与经验》两篇总结
v1.1	2026-04-29	Gitea 禁止自助注册；只读站点由 Quartz 切换为 MkDocs Material；Memos 手机 Safari 加入主屏幕
v1.0	2026-04-29	初始搭建：Memos + Gitea + Obsidian + Quartz（notes）

延伸阅读（同目录）：选型对比-存储与架构 · 实施复盘-问题与经验 · 运维：Gitea Webhook 触发 MkDocs

---

一、需求背景

1.1 使用场景

职业场景 - 项目管理：技术方案文档、行业调研报告、数据分析（图表/SQL）、项目复盘 - 求职：技术资料学习、算法题思路总结、博客打卡、面试录音复盘 - 职业规划：学习路径 XMind、学习计划与进度追踪 - 技术研究：中间件研究、技术点笔记、职场感悟

生活场景 - 台球：训练心得记录 - 日常琐碎：WiFi 密码、有共鸣的文章/视频、技术博客地址、待学习的技术视频截图、好用网站收藏

1.2 现状痛点

痛点	描述
存储分散	内容散落在备忘录、微信传输助手、语雀、百度网盘、手机相册，找东西要翻很久
分类不清	多个存储源没有统一分类，找技术内容时要跳过大量生活娱乐内容
时间成本高	时隔较久后找到文档，还需要花时间重新梳理熟悉
数据安全隐患	手机照片仅存本地，换手机容易丢失；百度网盘下载速度慢

---

二、选型分析

2.1 架构思路

核心原则：统一入口 + 分类存储

[统一入口层] → 收集、检索、管理所有内容
      ↓
[分类存储层] → 不同类型内容存到最适合的地方
      ↓
[备份容灾层] → 1主+1备，防止数据丢失

内容按类型分为三类：

类型	特点	工具
结构化文档	有体系、需检索	Obsidian
碎片速记	随手记、频率高	Memos
大文件媒体	占空间、需备份	待规划（v2.0）

2.2 工具选型

知识库主体：Obsidian - 本地优先，文件为 Markdown，数据完全自有 - 插件生态丰富，支持双向链接 - 文件结构天然适合 Git 版本管理

碎片速记：Memos - 极轻量，Docker 一键部署 - 手机浏览器直接使用，无需安装 App - 专注速记，不干扰主知识库

私有 Git 托管：Gitea - 开源自建，数据完全自有 - 轻量，适合个人 VPS 部署 - 提供 Obsidian 多设备同步能力

只读网页浏览：MkDocs + Material - Python 生态，Material 主题对移动端侧边栏、搜索、暗色模式支持成熟 - 与标准 Markdown 链接兼容好，适合「知识库 + 文档站」形态 - 构建产物为纯静态 HTML，由 Nginx 托管

反向代理：Nginx + Let's Encrypt - HTTPS 加密访问 - 通过域名访问，替代 IP+端口暴露

---

三、技术实现

3.1 系统架构

iPhone（Memos 随手记）
    ↓ HTTPS
┌─────────────────────────────────┐
│        阿里云服务器               │
│  2核4G 40GB  华东1（杭州）        │
│                                 │
│  ┌─────────┐  ┌──────────────┐  │
│  │  Memos  │  │    Gitea     │  │
│  │ :5230   │  │    :3000     │  │
│  └─────────┘  └──────────────┘  │
│                      ↕          │
│  ┌──────────────────────────┐   │
│  │ MkDocs Material（构建）   │   │
│  │ 输出目录如 /opt/mkdocs-site│   │
│  └──────────────────────────┘   │
│                                 │
│  ┌──────────────────────────┐   │
│  │   Nginx（反向代理 + SSL） │   │
│  └──────────────────────────┘   │
└─────────────────────────────────┘
         ↕ Git sync
Mac 工作机 / Mac 家用机
（Obsidian + Git 插件）

3.2 服务清单

服务	访问地址	用途
Memos	https://memos.teacherhome.top	碎片速记
Gitea	https://git.teacherhome.top	知识库 Git 托管
notes（MkDocs）	https://notes.teacherhome.top	只读网页浏览（Material）

3.3 数据流

Obsidian（Mac写作）
    → Git push（每10分钟自动）
        → Gitea 仓库
            → Cron 定时：git pull + mkdocs build
                → notes.teacherhome.top（静态站点）更新

---

四、配置流程

4.1 服务器环境

• 系统：Alibaba Cloud Linux（基于 RHEL/CentOS）
• 容器：Podman（兼容 Docker CLI）
• Web 服务：Nginx
• SSL：Let's Encrypt（Certbot）

4.2 部署步骤

Step 1：部署 Memos

mkdir -p /data/memos
docker pull docker.m.daocloud.io/neosmemo/memos:stable
docker tag docker.m.daocloud.io/neosmemo/memos:stable neosmemo/memos:stable
docker run -d \
  --name memos \
  --restart unless-stopped \
  -p 5230:5230 \
  -v /data/memos:/var/opt/memos \
  neosmemo/memos:stable

Step 2：部署 Gitea

mkdir -p /data/gitea
docker pull docker.m.daocloud.io/gitea/gitea:latest
docker tag docker.m.daocloud.io/gitea/gitea:latest gitea/gitea:latest
docker run -d \
  --name gitea \
  --restart unless-stopped \
  -p 3000:3000 \
  -p 2222:22 \
  -v /data/gitea:/data \
  gitea/gitea:latest

初始化配置：数据库选 SQLite3，站点 URL 填服务器域名

Step 3：配置 Obsidian

# Mac 本地克隆仓库
git clone https://用户名@git.teacherhome.top/用户名/knowledge-base.git

- 安装 Obsidian，打开克隆的文件夹作为 Vault - 安装插件：Git（Vinzent03，246万下载） - 配置：Auto commit/push interval = 10分钟，hostname 填设备名

Step 4：部署 MkDocs（Material）

# 建议 Python 3.8+（系统自带 3.6 时可用 pyenv / 官方安装包升级）
yum install python3 python3-pip -y   # 或已满足版本则跳过

pip3 install mkdocs-material mkdocs-awesome-pages-plugin

# 工作副本（与 Gitea 裸库同机时可本地 clone）
git config --global --add safe.directory /data/gitea/git/repositories/用户名/knowledge-base.git
git clone /data/gitea/git/repositories/用户名/knowledge-base.git /opt/knowledge-base

# mkdocs.yml 放在 /opt，docs_dir 指向知识库目录（示例）
# site_dir: /opt/mkdocs-site
# 构建：mkdocs build -f /opt/mkdocs.yml

历史：v1.0 曾使用 Quartz（Node），因国内构建依赖外网字体、手机端导航偏顶栏等问题，v1.1 起改为 MkDocs，详见下文「Quartz vs MkDocs」。

Step 5：配置 Nginx + SSL

# 创建反向代理：memos、gitea；notes 站点 root 指向 MkDocs 构建输出目录，例如：
#   root /opt/mkdocs-site;
#   try_files $uri $uri/ /index.html;
# 申请 SSL 证书
certbot --nginx -d memos.teacherhome.top -d git.teacherhome.top
certbot --nginx -d notes.teacherhome.top

# 修复 Memos 上传大小限制
# 在 memos.conf 的 location / 中添加：
# client_max_body_size 20m;

Step 6：自动构建（MkDocs）

• 推荐（实时）：仓库 Push Webhook → 宿主机执行 /opt/rebuild-notes.sh，见 运维-Gitea-Webhook触发MkDocs构建.md。
• 兜底（可选）：cron 低频执行同一脚本，防止 Webhook 偶发失败。

cat > /opt/rebuild-notes.sh << 'EOF'
#!/bin/bash
cd /opt/knowledge-base && git pull
mkdocs build -f /opt/mkdocs.yml
EOF
chmod +x /opt/rebuild-notes.sh

# 示例：仅每小时兜底（有 Webhook 后可去掉每 10 分钟那条）
# (crontab -l; echo "0 * * * * /opt/rebuild-notes.sh >> /var/log/mkdocs-build.log 2>&1") | crontab -

---

五、日常使用 SOP

5.1 两个入口原则

场景	工具	访问方式
手机随手记、碎片想法、WiFi密码、有共鸣的内容	Memos	https://memos.teacherhome.top（加入主屏幕）
技术笔记、项目文档、算法总结、博客草稿	Obsidian	Mac 本地客户端
不确定放哪里	Obsidian 00-收件箱	Mac 本地客户端
手机浏览知识库	MkDocs（Material）	https://notes.teacherhome.top

5.2 日常节奏

随时 - 手机记碎片 → Memos - Mac 写正式内容 → Obsidian（自动10分钟同步）

每天 - 打开 Obsidian，当天的技术笔记/工作文档直接写到对应目录

每周末（15-20分钟） 1. 清空 00-收件箱，把积累内容移到对应文件夹 2. 翻 Memos，有价值的整理成 Obsidian 笔记，无价值的删除

5.3 目录结构

knowledge-base/
├── 00-收件箱/          ← 所有新内容先扔这里
├── 01-职业/
│   ├── 项目/
│   │   ├── 技术方案/
│   │   ├── 行业调研/
│   │   ├── 数据分析/
│   │   └── 项目复盘/
│   ├── 求职/
│   │   ├── 算法题总结/
│   │   ├── 面经复盘/
│   │   └── 博客草稿/
│   ├── 职业规划/
│   └── 技术研究/
├── 02-生活/
│   ├── 台球/
│   └── 日常记录/
└── 03-素材库/

---

六、待规划

近期待完成

• [x] Gitea 关闭用户自助注册（app.ini 中 DISABLE_REGISTRATION = true）
• [x] 手机 Safari 将 Memos 加入主屏幕（见「七、v1.1 迭代说明」）
• [ ] 家用 Mac 配置 Obsidian + Git 同步

v2.0 规划

• [ ] notes（MkDocs）站点访问控制（鉴权 / IP 限制 / Basic Auth 等）
• [ ] 入口统一 + 单点登录（SSO）：一次登录，Memos / Gitea / notes 打通
• [ ] 照片备份方案（Immich，待服务器扩容或购置外置硬盘后实施）
• [ ] 面试录音文件存储方案
• [ ] Nginx Basic Auth 加固（可选）

---

七、v1.1 迭代说明

7.1 Gitea 禁止自助注册

在服务器 app.ini 增加（或通过管理后台关闭注册）：

[service]
DISABLE_REGISTRATION = true

执行 docker restart gitea 生效。新用户仅可由管理员创建。

7.2 Quartz → MkDocs（对比）

维度	Quartz（v1.0）	MkDocs Material（v1.1）
技术栈	Node.js	Python + pip
与 Obsidian 语法	深度适配 wikilink、部分插件语法	标准 Markdown 链接为主；首页等需避免纯 [[wikilink]]
国内构建	OG 等插件易依赖外网字体失败	依赖少，阿里云源装 pip 包即可
手机端体验	顶栏搜索/菜单偏上，单手不便	Material 侧栏 + 搜索成熟，文档站常见布局
主题与扩展	Quartz 插件生态	Material 主题、插件（搜索、代码复制等）成熟
维护成本	需跟踪 Quartz 与 Node 版本	与 Python 版本绑定，建议 3.8+

结论：个人知识库以「手机可读、稳定构建」优先时，MkDocs Material 更合适；Obsidian 仍作为唯一写作源，站点为只读渲染层。

7.3 iPhone：Safari 将 Memos 加到主屏幕

1. Safari 打开 https://memos.teacherhome.top 并登录。
2. 点底栏 分享（方框向上箭头）。
3. 向下滚动，点 添加到主屏幕。
4. 可改名称（如「Memos」）后点 添加。

主屏幕图标即 PWA 式快捷入口，仍走 HTTPS，与「不开放公网端口、仅域名访问」的策略一致。