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

溪~源

471人浏览 · 2026-08-28 22:40:04

溪~源 · 2026-08-28 22:40:04 发布

用 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

分类标准

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

分类	放什么	谁维护	更新频率
FAQ	排障记录、已知问题与解决方案	全组	随时（排障后立即记录）
运维手册	部署、发布、迁移操作流程	运维 + 开发	较稳定
服务资料	服务信息档案、依赖关系	架构组	服务变更时
架构设计	技术方案、架构决策	架构组	较稳定
会议纪要	关键决策记录	各负责人	会后

关键经验：分类不求全，但求一致。一开始只有 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. 持续积累

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

三、文档清洗入库实战

原始文档的问题

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

问题	示例	处理方式
页眉页脚残留	每页都有"内部文档请勿外传"	清除
水印文字	PDF 转出的文本里混入水印	清除
格式混乱	Word 导出后层级错乱	重新整理标题层级
多文档内容重叠	三份文档都讲了支付部署	合并为一份
文件名不清晰	`新建文本文档(3).txt`	重命名为有意义的名字

清洗流程

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

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

清洗步骤：

提取文本：用平台 Word 解析能力提取文本内容
清理噪音：去掉页眉页脚、水印文字、目录页码
整理结构：统一标题层级（#/##/###），列表用 - 或 1.
合并去重：对比三个版本，取最新内容，合并不同版本中各自独有的信息
生成关键词：支付, payment-gateway, 部署, Docker, Compose, 环境变量, 健康检查, Redis, MySQL
写简述：支付网关服务的 Docker Compose 部署手册，含环境变量配置和健康检查验证
生成提问摘要：支付网关怎么部署? 需要哪些环境变量? §健康检查: 怎么验证部署成功? §常见问题: 启动失败怎么处理?
保存入库：projqa-docs/电商平台/运维手册/支付网关部署.md

索引补录实例

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

- [电商平台/运维手册/支付网关部署.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 检索流程：

别名映射：订单 → order-service，支付中 → payment-gateway
索引匹配：提问摘要"支付超时怎么排查?" 高度匹配
读取：电商平台/FAQ/支付超时排查.md

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

检查 payment-gateway 服务是否存活
检查 Redis 连接池是否耗尽
检查下游支付渠道响应时间
渠道侧超时则触发熔断，切换备用渠道

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

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

案例 2：服务信息查询

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

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

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

案例 3：跨文档关联

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

Agent 检索流程：

别名映射：商品中心 → product-center
索引匹配：命中部署指南 + 服务清单 + 依赖关系图
读取多个候选文档

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

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

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

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