搭建轻量个人知识库

背景：对应需求迭代/2026-04/搭建轻量个人知识库.md。
一期目标：在单台阿里云 VPS 上跑通 Memos + Gitea + Obsidian（Git）+ 只读静态站 + HTTPS；写作端为两台 Mac。v1.0 只读站曾用 Quartz（Node），v1.1 起改为 MkDocs Material，初装命令以下文「当前实践」为准，Quartz 仅作历史说明。

1. 技术选型

1.1 边界与原则

边界：无 NAS；两台 Mac（不长期当公网入口）；一台国内 VPS；已备案域名。
原则：统一入口 + 分类存储；知识库主链路 Obsidian → Git → Gitea；需手机随时写的走 Memos（VPS）。

1.2 存储与载体（摘要）

决策点	结论
知识库主存储	Obsidian 本地 Markdown + Gitea 私有仓为远端真相源
碎片速记	Memos 容器部署在 VPS，手机浏览器访问
大文件/相册	一期不落地，v2+ 走 NAS/外置盘等
在线入口	VPS + 域名 + 443，而非家用 Mac 常开

1.3 应用与栈

角色	选型	说明
笔记主体	Obsidian	本地优先；配合 Git 插件定时同步
Git 托管	Gitea	自建、轻量；需 HTTPS 与注册策略
碎片	Memos	Docker 部署；大图/带宽见问题总览
只读站（历史）	Quartz	Node；国内构建易踩外网依赖（见 v1.1 文档）
只读站（当前）	MkDocs Material	Python 3.8+；与标准 Markdown 兼容好
入口与安全	Nginx + Let's Encrypt	反向代理与证书；业务端口不直出公网

2. 架构

iPhone（Memos）
    ↓ HTTPS
┌─────────────────────────────────┐
│ 阿里云 VPS（示例：2核4G，华东）  │
│  Memos :5230   Gitea :3000      │
│  MkDocs 构建 → 静态输出目录      │
│  Nginx（443，反代 + 站点 root）  │
└─────────────────────────────────┘
         ↕ git
Mac（Obsidian + Git 插件）

服务表示例（域名按实际）

服务	用途
memos.*	碎片速记
git.*	Gitea
notes.*	MkDocs 静态站

3. 模块

模块	职责
Memos	手机速记、小图
Gitea	仓库存储、Webhook（v1.3）触发构建
Obsidian	写作、目录与双链
构建机（同 VPS）	`git pull` + `mkdocs build`
Nginx	反代 Memos/Gitea；notes 的 `root`/`try_files`

数据流提要：Obsidian → 定时 Git push → Gitea →（v1.3）Webhook 秒级触发 /opt/rebuild-notes.sh，或低频 cron 兜底 → 静态产出由 Nginx 提供。

4. 方案细节（初装）

4.1 环境

OS：Alibaba Cloud Linux（RHEL 系）
容器：Podman 或 Docker（文档示例为 docker）
Web：Nginx；证书：Certbot

4.2 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

国内拉取：DaoCloud 等镜像前缀 + docker tag 为标准预案（见问题记录 001）。

4.3 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

初始化：SQLite、站点 URL 填域名。宿主机 clone 裸库需 safe.directory，见问题 002。

4.4 Obsidian（客户端）

git clone https://<用户>@git.<域名>/<用户>/knowledge-base.git

插件：Git（Vinzent03），自动 commit/push 间隔按需（如 10 分钟）。
排错：命令名、GitHobs 误装等见问题 008。

4.5 MkDocs Material（服务器）

Python 3.8+（系统 3.6 需升级，见问题 010）。
pip3 install mkdocs-material mkdocs-awesome-pages-plugin
工作副本：例如 git clone 裸库到 /opt/knowledge-base，mkdocs.yml 在 /opt，site_dir 如 /opt/mkdocs-site。
git config --global --add safe.directory '/data/gitea/git/repositories/<owner>/<repo>.git'

4.6 Nginx + SSL

certbot --nginx -d memos.<域名> -d git.<域名>
certbot --nginx -d notes.<域名>

Memos 反代：client_max_body_size（如 20m）避免上传 413。
notes：root 指向 MkDocs 输出；静态站需有 index.html（仓库根 index.md），见问题 004。

4.7 访问策略（替代 Tailscale）

有备案域名时采用 HTTPS + 关闭自助注册等；国区 Tailscale App 不可用时的取舍见问题 009。

5. 与维护的交叉

日常启停、日志、证书、cron/Webhook：见维护手册细则.md
发版与回滚：见上线记录.md
构建自动化（Webhook）：见 v1.3-Gitea-Webhook实时构建.md