个人知识库：实施复盘（问题、坑与方法论）
本文按「目标 → 现象/问题 → 思路 → 路径/结论」整理本次会话中真实踩过的坑与可复用经验。
关联文档：README、选型对比-存储与架构
一、方法论总览
- 先定边界：无 NAS、两台 Mac、一台国内 VPS、有备案域名——在此边界下选「谁常驻在线、谁负责写」。
- 分层解决：入口（Memos / Obsidian）、真相源（Gitea）、只读渲染（MkDocs）、传输安全（HTTPS）分开迭代，避免一次堆满。
- 先跑通再美化：同步通了再折腾主题；网站能打开再优化首页与权限。
- 把「可复现命令」写进文档：同样环境半年后你自己能照着恢复，比依赖记忆可靠。
二、Docker 镜像拉取：GitHub / Docker Hub 超时
目标：在阿里云上拉起 Memos、Gitea 容器。
问题：docker pull 访问 docker.io / github.com 超时，构建环境在国内常见。
思路：换可达的镜像源，或在本机（能访问外网）拉取/下载后 scp 到服务器。
路径 / 结论：
- 使用 DaoCloud 等镜像前缀拉取后再
docker tag成官方名；或 - Mac 克隆 / 下载 → scp 到服务器（Quartz 曾用此路）。
经验：自建服务的第一步往往是「镜像与依赖能稳定拉下来」，应预留镜像源方案，写进运维笔记。
三、Gitea：从裸库本地 clone 报「dubious ownership」
目标：服务器本机用 git clone 把 Gitea 仓库拉到 /opt/knowledge-base，供静态站点构建。
问题：fatal: detected dubious ownership in repository at '/data/gitea/git/repositories/...'。
思路：Git 2.35+ 对「不同属主目录下的仓库」有安全限制，需显式声明为安全目录。
路径 / 结论：
再执行 git clone <裸库路径> <工作目录>。
经验：容器内 Git 数据目录属主常为 git/1000，宿主机用 root 操作时要记得 safe.directory，否则脚本化构建会卡死。
四、Quartz：构建失败 CustomOgImages / fetch failed
目标：用 Quartz 生成 notes 静态站。
问题：插件拉取 Google Fonts 相关资源失败（国内网络），构建中断。
思路：要么关闭该插件，要么改成本地字体 / 可访问镜像；一期以「能稳定构建」优先。
路径 / 结论：注释或关闭 Plugin.CustomOgImages()，个人知识库对 OG 分享图需求可让位给稳定性。
经验：静态站生成器要审视 构建期网络依赖；CI/国内服务器上应默认假设「外网不稳定」。
五、Quartz + Nginx：403 / directory index forbidden
目标：浏览器打开 notes 域名。
问题：public 下无 index.html，Nginx index index.html 导致目录索引被禁止 → 403。
思路：要么生成首页 index.md 让构建产出 index.html，要么临时改 index 指令包含已有入口页（如 README.html）；根本解是 仓库根有 index.md。
路径 / 结论：在知识库根增加 index.md 作为 Quartz/MkDocs 共同友好的首页入口；Nginx 配置与构建产物对齐。
经验：「站点根是否有默认首页文件」是静态站排错的高频检查项。
六、SSL：证书与域名不匹配（ERR_CERT_COMMON_NAME_INVALID）
目标：notes 子域名启用 HTTPS。
问题：新子域未纳入证书 SAN，浏览器报证书域名无效。
思路：每个对外 HTTPS 域名都要有对应证书；Let's Encrypt 用 certbot --nginx -d notes.xxx 单独或合并申请。
路径 / 结论：为 notes.teacherhome.top 执行 Certbot，并保证 DNS A 记录已指向服务器。
经验：每新增一个对外域名，同步检查「DNS + 安全组端口 + 证书」三件套。
七、Memos：上传图片 HTTP 413
目标：在 Memos 里贴图。
问题：Nginx 默认 client_max_body_size 过小（常见 1m），大请求被拒 → 413。
思路：在反向代理的 location 中提高 body 上限。
路径 / 结论：在 Memos 的 server/location 中增加 client_max_body_size 20m;（按需调大），nginx -t 后 reload。
经验：凡带「上传」的 Web 应用，部署清单里应默认包含 Nginx body 限制 检查项。
八、带宽：Memos 上传「慢」、是否压缩
目标：理解上传体验。
问题：手机传原图很慢。
思路：区分「应用是否压缩」与「链路瓶颈」。Memos 不压缩原图；瓶颈在 云服务器套餐上行带宽（如 3Mbps）。
路径 / 结论：Memos 定位 文字 + 小图；大图、相册走 Obsidian/未来媒体方案。
经验：个人 VPS 选型时，上行 Mbps 直接影响「手机 → 服务器」体验，与 CPU 同等重要。
九、Obsidian Git：命令找不到 / 插件名混淆
目标：命令面板里执行 commit/push。
问题：搜 Git: Commit and push 无结果；曾误装 GitHobs（与 Git 同步无关）。
思路：确认安装的是 Vinzent03 的 Git 插件；命令名随版本可能变为 Git: Commit-and-sync 等。
路径 / 结论：插件启用后使用 Commit-and-sync；关闭再开插件可刷新命令注册。
经验：Community 插件以 作者 + 下载量 + 描述含 backup/sync 交叉验证，避免装错同名插件。
十、Tailscale：国区无法安装 App → 改域名方案
目标：手机安全访问内网服务，少暴露端口。
问题：国区 App Store 无 Tailscale；继续折腾外区账号成本高。
思路：在已有 备案域名 前提下，用 Nginx + HTTPS 暴露 443，应用层关闭注册、强密码；后续再加 SSO/Basic Auth。
路径 / 结论：卸载 Tailscale，Memos / Gitea / notes 走 https://*.teacherhome.top。
经验：移动端安装约束会一票否决某个方案；安全模型要在「可落地」前提下设计。
十一、MkDocs Material：pip 依赖版本与 Python 版本
目标：服务器安装 mkdocs-material。
问题：系统 Python 3.6 过旧，依赖要求 pymdown-extensions>=9.4 等无法满足，pip 报错。
思路：升级到 Python 3.8+（官方源、Software Collections、或独立安装包），再装 Material；或锁定与 3.6 兼容的旧版 Material（维护价值低）。
路径 / 结论：以 升级 Python 为主路径；阿里云源加速 pip。
经验：在「阿里云默认镜像」上搭文档站，第一步应 python3 --version，再选 Material 版本。
十二、MkDocs 构建告警：README 与 index 冲突
目标：mkdocs build 成功。
现象：WARNING - Excluding 'README.md' from the site because it conflicts with 'index.md'.
思路：同一目录 index.md 与 README.md 二选一 作为站点入口页；Material 红字关于 MkDocs 2.0 为上游公告，按官方迁移节奏关注即可。
路径 / 结论：保留 index.md 作为首页；根目录 README.md 若需进站点可改名或移到子目录。
经验：MkDocs 的「入口文件命名规则」写进团队/个人规范，避免多人协作时重复踩坑。
十三、Cron：日志路径从 Quartz 迁到 MkDocs
目标：定时构建与日志一致。
问题：crontab 仍写 quartz-build.log，易产生误解。
思路：只改重定向路径；日志文件无需预创建，>> 首次写入会自动创建（注意运行用户权限）。
路径 / 结论：crontab -e 或 sed 替换为 mkdocs-build.log；脚本内命令已是 mkdocs build。
经验：日志文件名与服务名一致，降低半年后排错成本。
十四、首页与双栈：Obsidian wikilink vs MkDocs 链接
目标：手机端首页清晰、可点击跳转。
问题：Obsidian 的 [[wikilink]] 在 MkDocs 中不生效；固定手写路径会在目录变更时失效。
思路：首页用 标准 Markdown 相对链接；顶层分区用 目录入口页 链到各 init.md 或 README；长期可结合 awesome-pages 等自动生成导航。
路径 / 结论：已用 Material 的 grid cards + tip 等增强首页；写作仍以 Obsidian 为主，发布层遵守 MkDocs 约束。
经验：「写作语法」与「发布语法」 要显式区分；必要时在文档中列「发布检查清单」（链接、图片路径、附件）。
十五、版本记录
| 版本 | 日期 | 说明 |
|---|---|---|
| v1.0 | 2026-04-29 | 初稿，覆盖会话内主要问题与处理路径 |