服务目录与系统地图全景图
回答“大型系统里谁负责什么、依赖在哪里、出了问题该看哪里，怎样不再靠口口相传”
阅读边界: 服务目录不是漂亮的服务列表，系统地图也不是一张永不更新的大图。它们要把 ownership、依赖关系、接口清单、运行信息、SLO、值班、文档入口和架构决策连接起来。
一句话判断: 如果新同事或值班同学无法在几分钟内找到服务 owner、依赖、告警、文档和发布入口，服务目录还没有真正发挥作用。
服务可发现
owner 可追踪
依赖可视化
运行入口集中
风险可聚合
文档不过期
| 问题 | 根因 | 治理判断 |
|---|
| 不知道某个接口归谁 | 服务 owner、接口 owner 和业务 owner 没有统一登记 | 目录要能从服务、接口、业务域三个维度查到负责人 |
| 事故时到处问依赖关系 | 依赖只存在代码、网关或人的记忆里 | 依赖图要来自运行数据、配置和契约，而不是纯手画 |
| 文档一上线就过期 | 文档与服务生命周期、发布和监控脱节 | 目录应成为文档入口，而不是另一个孤岛 |
| 平台能力没人用 | 默认路径、模板、运行信息和服务画像没有整合 | 服务目录可以成为 IDP 的导航层和治理入口 |
服务画像
名称、业务域、owner、仓库、语言、部署环境、数据存储和上下游依赖要集中可见。
ownership
至少区分服务 owner、业务 owner、值班 owner 和安全 / 数据 owner，避免责任含糊。
依赖地图
结合调用链、网关、消息 Topic、数据库访问和配置生成依赖图，并标注关键链路。
运行入口
告警、Dashboard、日志、Trace、Runbook、发布流水线和值班表应能从同一入口进入。
SLO 与风险
目录不只展示存在什么，也要展示重要性、可靠性目标、事故历史和风险等级。
生命周期治理
创建、变更、迁移、废弃和下线都要更新目录，避免僵尸服务和幽灵依赖。
| 误区 | 为什么危险 | 修正方式 |
|---|
| 先画一张全局大图 | 手画图很快过期，维护成本高 | 从服务目录和运行数据生成关键视图 |
| 只记录技术信息 | 事故和变更更需要 owner、业务影响和操作入口 | 把责任、SLO、文档和值班入口作为一等字段 |
| 目录归平台团队独自维护 | 平台不知道每个服务的真实语义和变化 | 平台提供模板和校验，服务 owner 负责准确性 |
| 检查项 | 最低要求 |
|---|
| 目录字段 | 服务、owner、仓库、环境、接口、依赖、数据、告警和文档入口完整 |
| 更新机制 | 服务创建、依赖变更、owner 变更、下线都能触发目录更新 |
| 自动采集 | 尽量从 CI/CD、运行时、网关、观测系统和配置平台同步信息 |
| 可靠性挂接 | 关键服务挂接 SLO、事故记录、runbook 和值班信息 |
| 权限与公开范围 | 敏感系统、密钥、内网拓扑和安全信息分级展示 |
| 字段组 | 最小字段 | 主要来源 | 验收方式 |
|---|
| 身份字段 | 服务名、业务域、生命周期状态、重要性等级、环境列表 | 服务模板、CMDB、部署平台 | 能从业务域和服务名双向检索；废弃服务有明确状态 |
| 责任字段 | 服务 owner、业务 owner、值班 owner、安全 owner、数据 owner | 团队目录、值班系统、权限系统 | 任一告警、接口或数据资产都能追到当前负责人 |
| 代码与发布 | 仓库、主干分支、CI/CD 流水线、发布入口、回滚入口、变更记录 | 代码平台、流水线、变更系统 | 值班同学无需问人即可找到发布和回滚路径 |
| 运行入口 | Dashboard、日志、Trace、告警规则、Runbook、事故记录、SLO | 可观测性平台、告警系统、事故复盘库 | 从目录进入排障链路不超过三次点击 |
| 依赖与契约 | 上游、下游、API、Topic、数据库、外部供应商、数据契约 | 网关、调用链、消息平台、数据库审计、契约仓库 | 一次依赖变更能自动暴露消费者和影响范围 |
| 保鲜动作 | 触发时机 | 失败信号 | 修正方式 |
|---|
| 创建即登记 | 新服务脚手架、仓库创建或首次部署 | 服务已上线但目录查不到 | 把目录登记做成流水线准入项，而不是上线后补文档 |
| 变更即校验 | owner、依赖、接口、数据资产、告警或 SLO 变化 | 目录字段和运行事实不一致 | 从 CI/CD、网关、观测系统拉取事实，并对人工字段设过期提醒 |
| 事故后修订 | 事故复盘、值班交接或重大故障演练后 | 排障时发现入口缺失、owner 错误、runbook 不可用 | 把目录缺陷列入复盘行动项，并追踪到关闭 |
| 季度清理 | 服务生命周期盘点、成本治理、安全审计 | 出现僵尸服务、无人告警、未知调用或废弃依赖 | 建立下线流程和例外清单，清理前先确认消费者和数据影响 |
| 场景 | 最小落地包 | 验收信号 |
|---|
| 新服务上线 | 服务模板必须登记 owner、仓库、环境、接口、依赖、告警、Dashboard、Runbook 和数据资产 | 服务上线后，值班同学能从目录直接进入排障和发布入口 |
| 事故中寻找影响面 | 依赖图要能从调用链、网关、消息 Topic 和数据库访问汇聚，不只靠手画架构图 | 几分钟内能定位上游、下游、关键链路和业务影响范围 |
| 服务 owner 变更或下线 | owner、值班、文档、告警、消费者和数据依赖同步变更；下线前确认无未知调用 | 目录里没有僵尸服务、幽灵依赖和无人负责的告警 |