devopsaitoolkit/devops-error-library
GitHub: devopsaitoolkit/devops-error-library
一个社区维护的结构化 DevOps 错误知识库，为运维工程师提供真实生产错误的根因分析、诊断命令和修复方案，并支持离线 CLI 搜索。
Stars: 0 | Forks: 0
# DevOps 错误库
**真实的 DevOps 与云基础设施错误开源百科全书 —— 可搜索、结构化且经过实战检验。**
[](./errors/README.md)
[](./errors/README.md)
[](https://creativecommons.org/licenses/by/4.0/)
[](./CONTRIBUTING.md)
[](https://github.com/devopsaitoolkit/devops-error-library/actions)
*一个不断增长的、由社区维护的故障排查参考，涵盖 Kubernetes、Docker、Terraform、OpenStack、Linux 等 —— 每个生产错误单列一页，附带真实的日志、真实的诊断命令以及可用的本地搜索 CLI。*
当系统在凌晨 3 点发生故障时，你不需要聊天机器人来猜测 —— 你需要的是确切的错误字符串、原因、用于确认的只读命令，以及经验丰富的 SRE 真正会执行的修复方案。**DevOps Error Library** 就是这样的参考资料：一个精心挑选、结构化的知识库，其中每个错误都存放在 [`errors/
/`](./errors/) 下各自的 Markdown 页面中，并在 CI 中经过验证和索引，以实现快速离线搜索。
它目前记录了 **涵盖 14 项技术的约 167 个真实错误** —— Kubernetes、Docker、Terraform、OpenStack、Linux、GitLab、Prometheus、Grafana、RabbitMQ、Redis、PostgreSQL、MySQL、Ceph 和 Linstor —— 其架构设计可扩展至 **10,000+**。这一数字每周都在增长，并且[欢迎贡献](./CONTRIBUTING.md)。
## ✨ 为什么会有这个项目 / 功能
互联网上的大多数错误“解决方案”要么零散分布、陈旧过时，要么是机器自动生成的填充内容。这个库恰恰相反：
- **一个错误，一个页面。** 每个条目都是一个独立的 Markdown 文件 —— 易于阅读、链接、对比和审查。
- **固定且可预测的结构。** 每次都是完全一致的 14 个部分。你永远知道*解决方案*和*诊断命令*在哪个位置。
- **真实的生产日志。** 错误消息是工程师实际粘贴到搜索框中的原封不动的字符串 —— 包括现实中的各种变体。
- **真实的只读诊断命令。** 每个 `kubectl`、`docker`、`terraform`、`openstack` 或 `journalctl` 命令都是资深工程师在排查时会安全执行的。
- **快速本地搜索 CLI。** `errlib search` 完全离线对 JSON 索引进行工作 —— 无需 SaaS、无遥测、无需注册。
- **几乎零依赖。** `errlib` 工具仅需要 Python ≥ 3.10 和 PyYAML。语料库本身只是纯粹的 Markdown。
- **经过 CI 验证。** 每次提交 pull request 时都会检查 front matter、部分内容、slug 和生成的索引 —— 不会有格式错误的页面被合并。
- **对 SEO 友好、易于阅读的标题和 slug。** 页面的命名方式与人们的搜索习惯相同（如 "Kubernetes CrashLoopBackOff"、"Terraform State Lock"），因此也可以通过浏览器轻松找到。
## 📁 目录概述
每个错误都是位于 `errors//` 下的 Markdown 文件。由于 OpenStack 内容庞大，因此按服务对其进行了进一步拆分。
```
errors/
├── README.md # generated index — categories + counts
├── kubernetes/
│ ├── kubernetes-crashloopbackoff.md
│ ├── kubernetes-imagepullbackoff.md
│ └── ...
├── docker/
├── terraform/
├── linux/
├── gitlab/
├── prometheus/
├── grafana/
├── rabbitmq/
├── redis/
├── postgresql/
├── mysql/
├── ceph/
├── linstor/
└── openstack/ # split by service
├── nova/
├── cinder/
├── neutron/
├── glance/
├── keystone/
├── heat/
├── horizon/
├── swift/
├── placement/
└── ironic/
```
请参阅 [`errors/README.md`](./errors/README.md) 中的实时统计。
## 🔎 搜索
`errlib` CLI 为你提供离线全文搜索、过滤、验证、索引和统计功能。
### 安装
```
git clone https://github.com/devopsaitoolkit/devops-error-library.git
cd devops-error-library
pip install -e .
```
这将安装 `errlib` 控制台脚本（需要 Python ≥ 3.10，仅需 PyYAML）。
### 搜索错误库
```
# 跨标题、消息、tags 和 bodies 的自由文本搜索
errlib search "CrashLoopBackOff"
# 按 technology 和 severity 筛选
errlib search --tech kubernetes --severity high
# 按 tag 筛选
errlib search --tag scheduling
# 仅匹配 error message（非常适合粘贴 log 行）
errlib search --message "no valid host"
# 限制结果数量
errlib search "permission denied" --limit 5
```
输出示例：
```
[high ] Kubernetes CrashLoopBackOff
kubernetes/kubernetes-crashloopbackoff.md (kubernetes) score=42
[high ] Kubernetes OOMKilled
kubernetes/kubernetes-oomkilled.md (kubernetes) score=18
2 result(s).
```
### 其他命令
```
errlib validate # validate front matter + sections + slugs (what CI runs)
errlib index # build the JSON search index
errlib stats # per-technology document counts
errlib new "Kubernetes Evicted Pod" --tech kubernetes --severity high
```
`errlib new` 也可接受 `--tags tag1,tag2` 和 `--subdir `（用于 OpenStack 服务）。向任何命令传入 `--root ` 即可指向不同的 `errors/` 目录树。
## 📄 错误页面格式
每个页面都以 YAML front matter 开头，随后遵循相同的 14 个部分。规范模板位于 [`ERROR_TEMPLATE.md`](./ERROR_TEMPLATE.md) 中。
```
---
title: "Kubernetes CrashLoopBackOff"
slug: kubernetes-crashloopbackoff
technologies: [kubernetes]
severity: high # info | low | medium | high | critical
tags: [kubernetes, pod, scheduling, crashloopbackoff, production]
related: [kubernetes-imagepullbackoff, kubernetes-oomkilled]
last_reviewed: 2026-06-27
---
```
固定的部分，顺序如下：
1. **Error Message** —— 原始的日志/CLI 字符串（加上真实的变体）
2. **Description** —— 含义及其来源
3. **Technologies** —— 组件 / 子系统
4. **Severity** —— 运营影响，用于分诊处理
5. **Common Causes** —— 按在生产环境中发生的频率排序
6. **Root Cause Analysis** —— 针对*机制*的分析，而非仅仅停留在表面症状
7. **Diagnostic Commands** —— 真实的**只读**命令
8. **Expected Results** —— 健康与异常输出的样子
9. **Resolution** —— 带编号的、可操作的修复步骤
10. **Validation** —— 如何确认修复生效
11. **Prevention** —— 避免再次发生的防护措施
12. **Related Errors** —— 指向相邻页面的链接
13. **References** —— 官方文档 + 深度指南
14. **Tags** —— 用于搜索和导航
一个完整的真实示例：[`errors/kubernetes/kubernetes-crashloopbackoff.md`](./errors/kubernetes/kubernetes-crashloopbackoff.md)。
## 🧭 浏览
- 📚 **所有分类与统计：** [`errors/README.md`](./errors/README.md)
- ☸️ **Kubernetes：** [`errors/kubernetes/`](./errors/kubernetes/)
- 🐳 **Docker：** [`errors/docker/`](./errors/docker/)
- 🌍 **Terraform：** [`errors/terraform/`](./errors/terraform/)
- ☁️ **OpenStack：** [`errors/openstack/`](./errors/openstack/)
- 🐧 **Linux：** [`errors/linux/`](./errors/linux/)
每个分类文件夹都有各自生成的 `README.md`，其中列出了每个错误及其严重程度和标签。
## 🗺 路线图
语料库是基础。其他所有内容都会读取相同的 Markdown 目录树和 JSON 索引。请查看 [`ROADMAP.md`](./ROADMAP.md) 了解完整计划。即将推出的亮点功能：
- 🔍 **CLI 搜索工具** —— 本地模糊搜索*（已通过 `errlib` 完成部分）*
- 🌐 **静态文档站点** + **Web 搜索 UI**
- 🔌 **基于 JSON 索引的 REST API**
- ⚙️ **GitHub Action** —— 在 CI 失败时展示匹配的错误
- 🤖 **基于语料库的 AI 故障排查建议**
- 🧠 **MCP 服务器** —— 允许 AI Agent 查询该库
- 🧩 **VS Code 扩展**
- 👍 **社区投票** + **错误热度排名**
## ❓ 常见问题解答
**这是 AI 生成的垃圾内容吗？**
不是。每个页面都是手工构建、由人工审核，并针对固定 schema（front matter + 14 个部分 + slug 规则）在 CI 中进行了验证。我们的标准是*资深工程师*级别的质量：真实的错误字符串、真实的只读命令，绝无捏造的日志。
**如何离线搜索？**
执行 `pip install -e .`，然后运行 `errlib search ""`。它完全针对本地 JSON 索引运行 —— 无需网络、无需账号、无遥测。可使用 `--tech`、`--tag`、`--severity` 和 `--message` 进行过滤。
**如何添加错误？**
运行 `errlib new "" --tech <tech>` 生成页面骨架，使用真实日志和只读诊断命令填写各个部分，运行 `errlib validate`，然后提交 PR。完整指南见 [`CONTRIBUTING.md`](./CONTRIBUTING.md)。
**质量标准是什么？**
质量重于数量。要求包含原封不动的错误消息、仅限只读的诊断命令、正确的 front matter、与文件名匹配的 kebab-case slug，以及有用的标签和相关链接。如果 `errlib validate` 失败，CI 就会失败。
**规模最终会有多大？**
该结构设计为可扩展至记录 **10,000+** 个错误。我们目前有约 167 个且在持续增长中 —— 请在[路线图](./ROADMAP.md)中查看各项技术的扩展目标。
**涵盖了哪些技术？**
目前包括：Kubernetes、Docker、Terraform、OpenStack（按服务划分）、Linux、GitLab、Prometheus、Grafana、RabbitMQ、Redis、PostgreSQL、MySQL、Ceph 和 Linstor。随着贡献者的加入，还会增加更多技术。
**遵循什么许可证？**
错误内容采用 **CC BY 4.0** 协议；`errlib` 代码和脚本采用 **MIT** 协议。详情见[许可证](#-license)。
## 🏛 架构
这个库在设计上刻意追求简单且持久：一棵纯 Markdown 文件树是唯一的真相来源。`errlib` 工具读取该目录树、进行验证，并将其编译为 JSON 索引。后续的一切 —— 无论是今天的 CLI，还是计划中明天的 Web UI、REST API 和 MCP 服务器 —— 都读取相同的索引。没有数据库、没有供应商锁定，一切都在 Git 中进行完全的版本管理。
```
errors/**/*.md (the corpus — Markdown, one error per file)
│
▼
errlib index / validate → errlib/index.json (the JSON search index)
│
├──▶ errlib search (local CLI — available today)
├──▶ static docs site / web search UI (planned)
├──▶ REST API (planned)
└──▶ MCP server / AI agents (planned)
```
## 📚 更多故障排查资源
- 📝 [DevOps AI Toolkit 博客](https://devopsaitoolkit.com/blog)上的深度指南
- 🚑 用于实时事件分诊的 [AI Incident Response Assistant](https://devopsaitoolkit.com/dashboard/incident-response)
- 📬 获取最新错误和 DevOps 技巧的[新闻通讯](https://devopsaitoolkit.com/newsletter)
## 📄 许可证
- **错误内容**（`errors/` 下的所有内容，以及 `ERROR_TEMPLATE.md`）：[知识共享署名 4.0 国际许可 (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/) —— 可在任何地方使用，只需注明来源于 DevOps Error Library。
- **代码**（`errlib/`、`scripts/`）：[MIT](https://opensource.org/licenses/MIT)。
如果这个库在你的故障排查中帮到了你，请给本仓库点个 ⭐ 并[贡献下一个错误](./CONTRIBUTING.md)。</div><div><strong>标签：</strong>Docker, ECS, Homebrew安装, Terraform, 子域名突变, 安全防御评估, 恶意代码分类, 自定义请求头, 请求拦截, 运维知识库, 逆向工具, 错误排查, 防御加固</div></article></div>
<!-- 人机验证 -->
<script>
(function () {
var base = (document.querySelector('base') && document.querySelector('base').getAttribute('href')) || '';
var path = base.replace(/\/?$/, '') + '/cap-wasm/cap_wasm.min.js';
window.CAP_CUSTOM_WASM_URL = new URL(path, window.location.href).href;
})();
</script>
</body>
</html>