个人知识库一期落地复盘
事实范围：一次个人项目从「分散笔记」到 Memos + Gitea + Obsidian + MkDocs notes + Webhook 的落地；依据为实施期文档与问题记录，非业务指标复盘。
用户使用说明：产品介绍.md
1. 需求目标 vs 落地结果（可核对）
| 目标维度 | 计划/期望 | 落地结果（客观） |
|---|---|---|
| 碎片入口随时可用 | VPS 上的 Memos，HTTPS | 已提供域名入口；大图受 Nginx body 与 上行带宽 约束（已记录工单） |
| 知识库 Markdown 自有 | Obsidian + 私有 Git | Gitea；关闭自助注册 |
| 手机可读只读站 | 稳定构建 + 移动布局 | MkDocs Material；构建不依赖 Quartz 的外网 OG 链路 |
| 多端同步 | Git | Obsidian Git 插件定时 push；服务端工作副本 pull |
| 更新延迟 | 可接受 | v1.3 前置最坏约 cron+push ~20min；Webhook 后为 通常秒级 |
| v1.0 未规划项 | 相册/录音/SSO | 明确列入「待规划」，未混入一期强行交付 |
不足（与目标差距）：家用第二台 Mac 未完成同步配置（仍为待办）；notes 无访问控制；大媒体链路未建立。
2. 技术方案文档 vs 实际路径
| 文档/设想路径 | 实际路径 |
|---|---|
| 可能用 Tailscale 缩小暴露面 | 国区 无法安装 Tailscale App → 改为 域名 + HTTPS + 关注册 |
| notes 静态站 Quartz | 外网字体/OG 插件导致国内构建不稳 → 换 MkDocs |
| 仅 cron 更新 notes | pull+push 叠加延迟明显 → Gitea Webhook + adnanh/webhook，cron 兜底 |
| 单次 Certbot | 新增 notes 子域时曾出现证书 SAN 不匹配 → 单独申请/核对 DNS |
亮点：分层迭代（先同步与可达，再渲染与美化，再延迟优化）在本次中减少了「一次推倒」风险。
3. 关键动作复盘与 5Why 示例
案例 A：Webhook 返回 200 但站点不更新（摘录本质链）
现象：Gitea Delivery 成功，前端 notes 仍旧。
- Why 没变？—— 构建脚本未真正拉到新提交或未写对输出目录。
- Why 脚本失败未暴露？—— 一度仅看 HTTP 200，未跟
journalctl/git 报错。 - Why git 在脚本里报错？—— systemd 拉起的服务 无 HOME，且裸库
dubious ownership。 - Why 环境与属主成这样？—— webhook 在非登录环境执行；仓库由容器用户属主创建。
- Why 未在预演中发现？—— 手工在 shell 里跑脚本 与 服务实际环境 不一致，缺一条「服务环境试跑」检查。
结论动作：service 写明 Environment=HOME=...、safe.directory 配齐；对钩先试 curl，再看日志与输出目录时间戳。可复现检查已写入 维护手册细则。
案例 B：Quartz → MkDocs（价值判断链）
现象：静态站生成失败或体验不理想。
连续追问收敛到：国内构建链路是否默认不可信外网、移动端信息架构是否匹配「文档站」，从而 换栈优于长期修补 Quartz 插件与外网依赖。（详细对比见需求 v1.1 与技术实现同名篇。）
4. 经验提炼
4.1 对开发者（可执行）
- 自建第一步：镜像与依赖
docker pull/pip/GitHub 是否可达；预备 镜像前缀 / scp。 - 每新增 HTTPS 域名：DNS → 安全组 → cert 三件一起验收。
- 上传类应用：默认检查 Nginx
client_max_body_size。 - 容器内发起的回源：厘清 127.0.0.1 归属（容器≠宿主机），Webhook、DB 常见问题源。
- 静态站：根
index.md/index.html是否与 Nginxindex一致。 - Python 云上环境：动笔前
python3 --version再锁 Material。
4.2 对 AICode（提示与协作）
- 先复述 硬性边界（无 NAS、国区商店、单机 VPS），再给方案，避免先推荐装不上的 App。
- 任何「定时 + 推送」链路，追问 端到端最坏延迟，主动建议 Webhook 或队列。
- 生成脚本时默认补 在非交互 systemd 环境下的 env（
HOME、PATH、safe.directory）。 - 命令类答案尽量 可复制、可存档到仓库，与「只靠会话记忆」对比。
5. 沉淀：SOP 与 Check-list
5.1 标准程序（成功案例归纳）
SOP-01：新 VPS 拉起 Memos + Gitea（镜像加速）→ 配 Nginx 反代与 body 上限 → Certbot。
SOP-02：服务器工作副本 git clone 裸库前执行 git config --global --add safe.directory <裸库路径>。
SOP-03：MkDocs 首页采用 index.md；根 README 若参与站点需处理与 index 的 互斥规则。
SOP-04：上 Webhook 时 Gitea ALLOWED_HOST_LIST + 容器访问宿主机 host-gateway/IP + curl 试钩子 + journalctl 跟一条完整构建。
日常使用（收件箱节奏、Memos/Obsidian 分工）：见 产品介绍。
5.2 避坑 Check-list（失败教训→进场必勾）
- [ ] Pull 超时：镜像源预案已写进上线记录了吗？
- [ ] 静态 403：site 根是否存在 index.html（由 index.md 产出）？
- [ ] 证书报错：新增子域是否已进 SAN？
- [ ] Memos 贴图：413：查 Nginx body；巨慢：查 套餐上行Mbps（非 Memos「压缩」能解）。
- [ ] MkDocs：wikilink 不可当发布语法；改用 Markdown 链接。
- [ ] systemd 钩子：HOME、
NO_MKDOCS_2_WARNING（如需）、safe.directory。 - [ ] Obsidian：Git 插件 作者+Vinzent03+Commit-and-sync，避免同名误装。
5.3 模板与自动化（重复劳动）
| 重复项 | 建议 |
|---|---|
同一套 Cron/Webhook/rebuild-notes.sh |
已通过 脚本 + systemd 固定；变更更新 上线记录 |
| 大版本选型讨论 | 飞书/文档复盘模板：背景、方案、否决原因、OWNER、日期 |
| 问题闭环 | 问题总览：全局序号 + 详情五段 |
6. 后续可读性
- v2：notes 访问控制 / SSO / 相册与录音——与 Markdown 主线 分仓设计（选型文档已预埋）。