zesheng 的数字花园

知识库维护规范

Properties1
tags运维

7分钟阅读

知识库维护规范

基本原则

  1. 先建入口，再移动文件。
  2. 标准化笔记作为日常使用入口，已整理完成的原始资料可以删除。
  3. 实战复盘优先于泛教程。
  4. 标签少而精，每篇 1-3 个核心标签即可。
  5. 临时内容先归档到 90-收集箱/待确认，确认无用后再删除。

新增故障复盘

使用 排障复盘模板，并挂到对应索引。

必填结构：

  • 现象
  • 环境
  • 排查过程
  • 根因
  • 解决方法
  • 验证结果
  • 预防措施
  • 相关笔记

推荐位置：

类型目录
Linux 故障08-故障复盘
Kubernetes 故障08-故障复盘
Docker/containerd 故障08-故障复盘

新增自动化手册

使用 Shell脚本说明模板 或 部署手册模板。

必填结构：

  • 目标
  • 适用场景
  • 参数配置
  • 核心逻辑
  • 部署方式
  • 验证方法
  • 风险与回滚
  • 相关笔记

推荐位置：

类型目录
Shell 自动化09-自动化与部署
Docker 部署09-自动化与部署
服务部署09-自动化与部署

新增命令速查

使用 命令速查模板。

推荐位置：07-命令速查

适合内容：

  • 高频命令组合。
  • 容易记错的参数。
  • 有风险的删除、清理、变更命令。
  • 排障时需要反复查的命令。

索引维护

索引维护重点
运维知识库总览只放核心入口和常用场景，不放长清单
Linux_排障索引按故障现象组织
Kubernetes_故障排查索引按 Pod、Node、存储、网络、资源策略组织
Shell_自动化索引按日志、守护、安全、调度、数据库组织
Docker_生产实践索引按基础、缓存、Web 入口、相关 Shell 手册组织
PostgreSQL_索引按安装部署、命令速查、备份恢复组织
技术栈索引作为技术栈孵化器，技术内容足够多后再独立建索引

技术栈索引规则

00-索引 只放入口级索引，避免每个技术都新建索引导致目录膨胀。

新增技术内容时，先放入 技术栈索引。满足任意一个条件，再独立建专题索引：

  • 该技术已有 5 篇以上笔记。
  • 经常用于排障或部署。
  • 内容横跨部署、命令、配置、故障等多个栏目。
  • 已经需要分栏目管理。

个人兴趣、游戏配置、生活资料不放入 技术栈索引。

收集箱规则

  1. 空文件、失败剪藏、默认欢迎页先放入 90-收集箱/待确认。
  2. 附件不确定是否引用时，先放入 90-收集箱/待确认附件。
  3. 保留观察后再删除。
  4. 如果发现有价值，再恢复并挂到索引。

命名建议

类型命名方式
故障复盘技术/组件 + 故障现象 + 排查
Shell 手册Shell + 场景 + 动作
Docker 手册Docker + 场景
命令速查命令/工具 + 用法

示例：

附件目录约定

规则只有一条，按目录就地存放，不逐目录登记：

  • 任何存放笔记的目录（含子目录）下，附件一律放在与该目录内笔记同级的 attachments/ 子目录，即 <笔记所在目录>/attachments/。
  • 判断某张附件该放哪，只看引用它的那篇笔记在哪个目录；该 attachments/ 不存在时按需创建，本文档不维护目录清单，避免清单过期。
  • 实例：01-Linux基础知识/attachments/、07-命令速查/attachments/、06-技术栈/attachments/、06-技术栈/阿里云ACP考试/attachments/ —— 这些是同一条规则的产物，不是需要额外登记的名单；新增主题目录时按同样的方式就地建 attachments/ 即可。

统一规则：

  • 附件一律使用 Obsidian 内部引用 ![[文件名.png]]（纯文件名，Obsidian 按全库唯一文件名解析，迁移文件夹时不用改引用）。
  • 上面这条依赖文件名全库唯一，所以附件不要用「幻灯片1.png」这类会在多篇笔记里重复的名字；下载图床图片时保留原始文件名（如 epPgLsge2E.JPG）最省事、天然唯一。
  • 图片等附件来自外部来源（如语雀/图床链接）时，先下载到本地对应目录的 attachments/，再将 ![](http://...) 替换为 ![[文件名.png]]，确保不依赖外链、不会失效。
  • 不使用 images/、assets/ 等其他附件目录名，统一为 attachments/。

Obsidian 客户端设置（Settings → Files & Links → Default location for new attachments）：

  • 选择 In subfolder under current folder（当前文件夹下的子文件夹）。
  • 子文件夹输入框填写 attachments。
  • 这样新粘贴/拖入的图片会自动保存到「当前笔记所在目录的 attachments/」。这条设置本身就是「每目录独立」的实现方式：新增主题目录时不需要改任何设置、也不需要在本文档登记，粘贴的图片会自动落到该目录的 attachments/。

Note

In subfolder under current folder 为较新版本功能，在设置菜单中能看到该项即表示当前 Obsidian 版本支持。