用 ProjQA 管理 30+ 服务的排障知识：中台电商项目实战经验

用 ProjQA 管理 30+ 服务的排障知识：中台电商项目实战经验

本文以一个虚构的电商平台为案例，分享 ProjQA 在多服务、多项目场景下的实战经验：知识库怎么组织、别名表怎么建、文档清洗入库怎么做、以及踩过的坑和解法。

项目背景

假设我们有一个电商平台，技术栈长这样：

• 微服务数量：30+ 个，包括订单、库存、支付、商品、用户、搜索、推荐、消息、风控等
• 部署方式：Docker Compose（开发环境）+ K8S（生产环境）
• 文档现状：散落在 wiki、飞书文档、个人电脑、共享盘，格式混杂（Markdown、Word、PDF、Excel）
• 核心痛点：新人入职问一遍、排障靠群里口述、文档找不到就重新写

目标是：用 ProjQA 把这些文档收拢起来，让 AI Agent 成为"项目知识问答助手"。

一、知识库目录组织

目录结构

经过几轮调整，最终的目录结构长这样：

projqa-docs/
├── 电商平台/
│ ├── FAQ/ # 排障经验、常见问题
│ │ ├── 支付超时排查.md
│ │ ├── 订单状态不一致.md
│ │ ├── 库存超卖处理.md
│ │ └── 搜索无结果排查.md
│ ├── 运维手册/
│ │ ├── 部署指南.md
│ │ ├── 灰度发布流程.md
│ │ └── 数据库迁移指南.md
│ ├── 服务资料/
│ │ ├── 服务清单.md # 全部服务信息一览表
│ │ └── 依赖关系图.md
│ ├── 架构设计/
│ │ └── 整体架构说明.md
│ └── 会议纪要/
│ └── 2026Q3-架构演进.md
├── 技术中台/
│ ├── 架构设计/
│ │ └── 中台架构说明.md
│ └── 服务资料/
│ └── 中台服务清单.md
├── _index.md
└── _aliases.md

分类标准

踩过坑后总结的分类规则：

关键经验：分类不求全，但求一致。一开始只有 3 个分类也够用，后续按需增加。最重要的是全组对"什么文档放哪"有共识。

二、别名映射表实战

别名表是检索命中率的头号功臣。这是实际运营几个月后沉淀下来的映射：

## 服务别名映射

# 电商核心服务
订单服务 -> order-service
订单 -> order-service
库存中心 -> inventory-center
库存 -> inventory-center
支付网关 -> payment-gateway
支付 -> payment-gateway
商品中心 -> product-center
商品 -> product-center
用户中台 -> user-platform
用户中心 -> user-platform
搜索服务 -> search-service
推荐引擎 -> recommendation-engine
消息中心 -> message-center
风控引擎 -> risk-control-engine

# 基础设施
网关 -> api-gateway
注册中心 -> service-registry
配置中心 -> config-center

## 通用缩写映射

K8S -> Kubernetes
K8s -> Kubernetes
PG -> PostgreSQL
MySQL -> MySQL
Redis -> Redis
ES -> Elasticsearch
MQ -> RabbitMQ

## 项目别名映射

电商 -> 电商平台
中台 -> 技术中台

建别名表的经验

1. 对齐团队语言习惯

听组内同事日常怎么称呼服务。有人叫"订单"，有人叫"订单服务"，有人叫"order"——这些都要收录。前期宁可多加，后面再清理。

2. 缩写要全覆盖

团队内部常说的"PG"“ES”“K8S”“MQ”，对外部人来说不一定能对上。全写进别名表，检索时无论用缩写还是全称都能命中。

3. 项目别名不可少

“电商"和"电商平台"是同一个项目，“中台"和"技术中台"也是一个。不映射的话，用户说"中台的服务清单”，索引里路径是"技术中台/服务资料/”，可能匹配不到。

4. 持续积累

别名表不是一次性的工作。每次发现检索没命中，先查是不是别名缺失，是就补上。几个月下来，命中率会稳步提升。

三、文档清洗入库实战

原始文档的问题

实际拿到的文档往往不能直接丢进目录。常见的"脏数据"：

清洗流程

以一份"支付网关部署文档"为例：

原始状态：Word 文档，42 页，含页眉页脚、截图、表格混排，内容分散在 3 个版本中。

清洗步骤：

索引补录实例

清洗后跑脚本，根据待补清单补录：

– [电商平台/运维手册/支付网关部署.md] | 关键词: 支付, payment-gateway, 部署, Docker, Compose, 环境变量, Redis, MySQL, 健康检查 | 简述: 支付网关Docker Compose部署手册，含环境变量和健康检查 | 提问摘要: 支付网关怎么部署? 需要哪些环境变量? §健康检查: 怎么验证部署成功? | mtime: 2026-08-27 10:00:00 | size: 4096

补录后再跑脚本验证：

待补清单: 无（所有索引字段完整）

入库完成。

四、踩过的坑与解法

坑 1：文档放进去但忘了补录

现象：文档放在目录里了，但关键词/简述没补，用户提问时检索不到或者命中了但没有语义信息辅助判断。

解法：养成"放完就跑脚本"的习惯。脚本会列出所有 !! 标记的待补文件，一目了然。补完再跑一次确认"待补清单: 无"。

坑 2：相似文档重复入库

现象：有人写了 支付超时.md，另一个人又写了 支付网关超时排查.md，内容高度重叠。

解法：入库时加 –check-similarity 参数。脚本会提醒文件名相似度高的文档对，然后由人工或 LLM 对比内容后合并。合并后保留一份，删掉另一份。

坑 3：别名表不及时更新

现象：新加了个"风控引擎"服务，别名表里没有映射。用户问"风控怎么部署"，检索不到。

解法：新服务上线时，同步更新别名表。把它作为新服务上线 checklist 的一项。

坑 4：大文档关键词太泛

现象：一份 500 行的部署指南，关键词列了"部署"“Docker”“配置”——太泛了，随便一个运维问题都能命中，反而降低了精准度。

解法：关键词要具体到服务和场景。改为 payment-gateway, 部署, Docker, Compose, 环境变量, Redis, MySQL, 健康检查——既覆盖服务名，也覆盖具体技术点。同时善用提问摘要和章节索引来提升定位精度。

坑 5：跨项目文档混在一起

现象：最初没有按项目分类，所有 FAQ 混在一起。搜"用户服务"本意是找中台的用户中心，结果命中了电商平台的用户模块。

解法：按项目分目录。索引路径自带项目前缀，LLM 能根据提问上下文自动定位到正确项目。

五、问答效果实例

以下是实际使用中的几个典型问答：

案例 1：排障查询

Q：订单状态卡在"支付中"怎么办？

Agent 检索流程：

订单状态卡在"支付中"通常是支付网关返回 504 超时导致。排查步骤：

常见原因：Redis 连接池过小（建议 200）、未配置熔断降级。

来源：电商平台/FAQ/支付超时排查.md

案例 2：服务信息查询

Q：搜索服务用的什么数据库？几个副本？

搜索服务（search-service）使用 Elasticsearch 作为数据存储，生产环境 2 副本。

来源：电商平台/服务资料/服务清单.md

案例 3：跨文档关联

Q：商品中心部署需要什么环境变量？依赖哪些服务？

Agent 检索流程：

商品中心（product-center）部署需要以下环境变量：

• DB_HOST：PostgreSQL 地址
• REDIS_HOST：Redis 地址
• ES_HOST：Elasticsearch 地址

依赖服务：search-service（搜索）、inventory-center（库存校验）。

来源：电商平台/运维手册/部署指南.md §环境变量说明
来源：电商平台/服务资料/依赖关系图.md

六、运营心得

知识库的价值在于"持续投喂"

知识库不是建好就完事了。每次排障后，把问题、原因、解法记录成 FAQ 文档放进去。每次新服务上线，把服务信息更新到服务清单。日积月累，知识库会越来越"聪明"。

入库流程要轻

太重的入库流程没人愿意执行。ProjQA 的入库流程足够轻：放文件 → 跑脚本 → 补几个字段。全流程 2 分钟。团队成员才愿意持续贡献。

索引质量决定问答质量

ProjQA 的检索不靠向量距离，靠索引字段。索引的关键词和提问摘要写得越好，检索越精准。这也是为什么要分级待补机制——确保每份文档的索引字段都补全了。

让 Agent 帮你补索引

手动补关键词/简述/提问摘要虽然不难，但量大时也繁琐。如果你的 Agent 平台支持，直接让 Agent 读文档自动生成这些字段——这正是"智能体即 LLM"原则的用武之地。