深色模式
知识库建设
摘要：知识库的价值不在存了多少，而在于需要时能否三分钟内找到。本文给出按"使用场景"分类的方法、可检索的命名规范，以及用脚本做全文检索与过期清理。
适用环境
bash
mkdir -p kb/{runbooks,sop,postmortems,faq,architecture}
cd kb
command -v rg >/dev/null || echo "可用 grep -r 替代"1
2
3
2
3
操作步骤
第 1 步：按使用场景分类，不按组织架构分类
bash
cat > taxonomy.md <<'EOF'
| 目录 | 场景 | 内容 |
| --- | --- | --- |
| runbooks | 出事了 | 故障处理手册 |
| sop | 要操作 | 标准作业程序 |
| postmortems | 复盘了 | 事故复盘 |
| faq | 有疑问 | 常见问题 |
| architecture | 要理解 | 架构与依赖说明 |
EOF1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
分类标准只有一个：读者在什么处境下会打开它。
第 2 步：文件命名可检索
bash
# 命名：<类别>-<对象>-<动作>.md，全小写短横线
cat > naming.md <<'EOF'
好：runbook-pay-timeout.md、sop-mysql-backup.md
坏：新建文档1.md、pay相关.md、最终版2.md
EOF1
2
3
4
5
2
3
4
5
第 3 步：每篇文档带可检索的元信息
bash
cat > template.md <<'EOF'
---
title: <标题>
description: <一句话，会被搜索命中>
date: 2026-10-09
tags: [<标签>]
owner: <维护人>
---
EOF1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
第 4 步：提供全文检索
bash
# 命令行检索：按关键词定位文件与行
cat > kb-search.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
q=$1
rg -n --color=never -i "$q" . -g '*.md' | head -30 || echo "未命中: $q"
EOF
chmod +x kb-search.sh && ./kb-search.sh "连接池"1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
第 5 步：定期清理过期内容
bash
# 找出 180 天未修改且无 owner 的文档，标记为待确认
cat > kb-stale.sh <<'EOF'
#!/usr/bin/env bash
find . -name '*.md' -mtime +180 | while read -r f; do
grep -qi 'owner:' "$f" || echo "待确认: $f"
done
EOF
chmod +x kb-stale.sh && ./kb-stale.sh1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
验证
bash
# 1. 检索脚本能命中已知关键词
./kb-search.sh "回滚" | head -3
# 2. 文件名均为小写短横线
find . -name '*.md' | grep -E '[A-Z_ ]' | head
# 3. 每篇都有 description 元信息
grep -L 'description:' $(find . -name '*.md') | head1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
常见坑
按团队/项目目录分类
读者不知道问题属于哪个团队就会迷路。按场景分类才是用户视角。
文档堆积无人维护
三年不更新的文档比没有文档更危险（会误导）。设置 owner 与过期标记机制。
把敏感信息写进知识库
密码、密钥、真实用户数据一旦入库就会广泛扩散。知识库只放脱敏内容，密钥走专用系统。