服务目录（Service Catalog）

通过扫描基础设施即代码（IaC）文件、配置文件及项目元数据，构建并持续维护一份全面的服务目录。回答以下关键问题：“我们运行了哪些服务？谁负责这些服务？它们依赖哪些组件？当前健康状态如何？”

适用场景包括：“列出我们所有的服务”、“我们有哪些微服务？”、“服务资产清单”、“该服务由谁负责？”、“绘制我们的基础设施拓扑图”、“服务间依赖关系分析”、“平台工程审计”，或搭建内部开发者门户（Internal Developer Portal）。

命令

1. discover — 自动发现服务

在工作区（workspace）中扫描所有常见模式下的服务定义。

Docker 服务

# Docker Compose 服务
find . -maxdepth 4 \( -name "docker-compose.yml" -o -name "docker-compose.yaml" -o -name "compose.yml" -o -name "compose.yaml" \) 
  -not -path '*/node_modules/*' -not -path '*/.git/*' 2>/dev/null | while read f; do
  echo "=== $f ==="
  # 提取服务名称
  python3 -c "
import sys
in_services = False
indent = 0
for line in open('$f'):
    stripped = line.rstrip()
    if stripped == 'services:':
        in_services = True
        continue
    if in_services:
        if stripped and not stripped.startswith(' ') and not stripped.startswith('#'):
            break
        if stripped and not stripped.startswith('  ') or (len(stripped) > 0 and stripped[0] != ' ' and stripped != ''):
            break
        if stripped.endswith(':') and stripped.startswith('  ') and not stripped.startswith('    '):
            name = stripped.strip().rstrip(':')
            print(f'  Service: {name}')
" 2>/dev/null || grep -E '^  \w+:' "$f" | grep -v '^    ' | sed 's/://;s/^  */  Service: /'
done

# Dockerfile（每个通常对应一个服务）
find . -maxdepth 4 \( -name "Dockerfile" -o -name "Dockerfile.*" -o -name "*.Dockerfile" \) 
  -not -path '*/node_modules/*' -not -path '*/.git/*' 2>/dev/null | while read f; do
  DIR=$(dirname "$f")
  BASE=$(head -5 "$f" | grep -oP '(?<=FROM )\S+' | head -1)
  echo "Dockerfile: $f (base: ${BASE:-unknown}) — dir: $DIR"
done

Kubernetes 清单文件（Manifests）

# K8s Deployment、StatefulSet、Service、CronJob 等资源
find . -maxdepth 5 -name "*.yaml" -o -name "*.yml" | 
  xargs grep -l "kind:\s*(Deployment|StatefulSet|Service|CronJob|DaemonSet|Job)" 2>/dev/null | 
  grep -v node_modules | while read f; do
  echo "=== $f ==="
  grep -E "^\\s*(kind|name|namespace|image):" "$f" | head -10
done

# Helm Chart
find . -maxdepth 4 -name "Chart.yaml" -not -path '*/node_modules/*' 2>/dev/null | while read f; do
  echo "=== Helm Chart: $f ==="
  grep -E "^(name|version|description|appVersion):" "$f"
done

应用配置文件

# Node.js 服务（含 start 脚本的 package.json）
find . -maxdepth 3 -name "package.json" -not -path '*/node_modules/*' 2>/dev/null | while read f; do
  HAS_START=$(python3 -c "import json; d=json.load(open('$f')); print('yes' if 'start' in d.get('scripts',{}) else 'no')" 2>/dev/null)
  if [ "$HAS_START" = "yes" ]; then
    NAME=$(python3 -c "import json; print(json.load(open('$f')).get('name','unknown'))" 2>/dev/null)
    echo "Node service: $NAME ($f)"
  fi
done

# Python 服务（含主入口点）
find . -maxdepth 3 -name "pyproject.toml" -not -path '*/vendor/*' 2>/dev/null | while read f; do
  DIR=$(dirname "$f")
  echo "Python project: $f"
  grep -E "^(name|version)" "$f" | head -2
done

# Go 服务
find . -maxdepth 3 -name "go.mod" 2>/dev/null | while read f; do
  MODULE=$(head -1 "$f" | awk '{print $2}')
  echo "Go module: $MODULE ($f)"
done

# Procfile（Heroku/Dokku）
find . -maxdepth 3 -name "Procfile" 2>/dev/null | while read f; do
  echo "=== Procfile: $f ==="
  cat "$f"
done

# Systemd Unit 文件
find . -maxdepth 4 -name "*.service" -not -path '*/.git/*' 2>/dev/null | while read f; do
  echo "Systemd unit: $f"
  grep -E "^(Description|ExecStart|After|Requires)=" "$f" 2>/dev/null
done

CI/CD 流水线（揭示已部署服务）

# GitHub Actions 部署工作流
find .github/workflows -name "*.yml" -o -name "*.yaml" 2>/dev/null | 
  xargs grep -l "deploy" 2>/dev/null | while read f; do
  echo "Deploy workflow: $f"
  grep -E "^\\s*(name|runs-on|env):" "$f" | head -5
done

# GitLab CI 部署阶段
grep -A5 "deploy" .gitlab-ci.yml 2>/dev/null | head -20

2. catalog — 生成服务目录

完成服务发现后，将其汇总为结构化服务目录。对每个服务提取以下信息：

• 名称（Name）：服务标识符
• 类型（Type）：API、Worker、Cron Job、Database、Cache、Queue、Frontend、Gateway 等
• 技术栈（Tech stack）：编程语言、框架、运行时
• 端口（Port）：对外暴露的端口
• 依赖项（Dependencies）：该服务连接的其他服务（源自环境变量、配置文件或代码导入）
• 负责人（Owner）：来自 CODEOWNERS、package.json 的 author 字段、或 git blame 结果
• 仓库地址（Repository）：Git 远程 URL
• 健康检查端点（Health endpoint）：/health、/healthz、/ready、/status 等
• 文档（Documentation）：README、Wiki 链接等

# 从环境变量和配置中检测服务依赖
rg -n "(DATABASE_URL|REDIS_URL|RABBITMQ_URL|KAFKA_BROKERS|MONGO_URI|API_URL|SERVICE_URL)" 
  -g '!node_modules' -g '!vendor' -g '!dist' --type-not binary 2>/dev/null

# 检测服务间通信行为
rg -n "(fetch|axios|http.get|requests.get|grpc|amqp|redis)" 
  -g '!node_modules' -g '!vendor' -g '!dist' -g '!.test.' -g '!.spec.' --type-not binary 2>/dev/null | 
  grep -oP 'https?://[a-zA-Z0-9._/-]+' | sort -u

# 检查 CODEOWNERS 文件
cat CODEOWNERS .github/CODEOWNERS docs/CODEOWNERS 2>/dev/null

# 检查健康检查端点
rg -n "(/health|/healthz|/ready|/status|/ping)" 
  -g '!node_modules' -g '!vendor' --type-not binary 2>/dev/null | head -20

输出服务目录文档示例：

# Service Catalog
Generated: [date] | Services: N | Owners: N teams

## Services

### api-gateway
- **Type:** API Gateway
- **Stack:** Node.js 20, Express
- **Port:** 3000
- **Owner:** @platform-team
- **Dependencies:** auth-service, user-service, redis
- **Health:** GET /health
- **Repo:** github.com/org/api-gateway
- **Docs:** docs/api-gateway.md

### user-service
...

3. deps — 依赖关系图

绘制服务到服务的依赖关系：

api-gateway → auth-service → postgres
api-gateway → user-service → postgres, redis
api-gateway → notification-service → redis, smtp
worker → queue (rabbitmq) → notification-service
frontend → api-gateway

自动识别以下风险模式：

• 循环依赖（Circular dependencies）：A → B → C → A
• 单点故障（Single points of failure）：被超过 3 个其他服务依赖、且无冗余机制的服务
• 缺失健康检查（Missing health checks）：未定义 /health 类端点的服务
• 孤儿服务（Orphaned services）：在配置中声明但未被任何其他服务引用的服务

4. health — 检查服务健康状态

针对已知健康检查端点或本地 Docker 容器的服务执行探活：

# 检查本地 Docker 容器
docker ps --format "{{.Names}}\t{{.Status}}\t{{.Ports}}" 2>/dev/null

# 检查 systemd 服务
systemctl list-units --type=service --state=running 2>/dev/null | grep -v systemd

# 探测健康检查端点
for endpoint in $(rg -o "https?://localhost:[0-9]+/(health|healthz|ready|status)" -g '*.{yml,yaml,json,env}' 2>/dev/null | sort -u); do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" --connect-timeout 3 "$endpoint" 2>/dev/null)
  echo "$endpoint → $STATUS"
done

5. owners — 所有权报告

将服务映射至所属团队或个人：

# 来自 CODEOWNERS
cat CODEOWNERS .github/CODEOWNERS 2>/dev/null | grep -v '^#' | grep -v '^$'

# 来自 package.json 的 author/maintainers 字段
find . -maxdepth 3 -name "package.json" -not -path '*/node_modules/*' 2>/dev/null | while read f; do
  python3 -c "
import json
d = json.load(open('$f'))
name = d.get('name', 'unknown')
author = d.get('author', 'unassigned')
if isinstance(author, dict): author = author.get('name', 'unassigned')
print(f'{name}: {author}')
" 2>/dev/null
done

# 来自 git blame（按目录统计最近 90 天最活跃贡献者）
find . -maxdepth 2 -type d -not -path '*/.git*' -not -path '*/node_modules*' | while read d; do
  TOP=$(git log --since="90 days ago" --format="%an" -- "$d" 2>/dev/null | sort | uniq -c | sort -rn | head -1)
  if [ -n "$TOP" ]; then
    echo "$d: $TOP"
  fi
done 2>/dev/null

将未明确归属的服务标记为风险项。

6. drift — 检测目录漂移（Catalog Drift）

将当前生成的服务目录与先前保存的版本（.service-catalog.json）进行比对，识别变更：

• 新增服务（未存在于旧目录中）
• 下线服务（存在于旧目录中，但当前未扫描到）
• 配置变更（端口、依赖项、技术栈等）
• 负责人变更

建议在 CI 中运行该命令，及时捕获未文档化的基础设施变更。

输出格式

• text（默认）：面向人工阅读的结构化报告，按服务分节展示
• json：机器可读格式：{services: [{name, type, stack, port, deps, owner, health, repo}], graph: {edges: []}}
• markdown：适用于 Wiki 的文档格式，含表格与 Mermaid 依赖关系图
• mermaid：纯 Mermaid 格式的服务依赖关系图

注意事项

• 支持单体仓库（monorepo）与多仓库（multi-repo）架构（可从仓库根目录或组织根目录启动扫描）
• 无需服务实际运行 —— 仅依赖配置文件与源码静态分析
• 若需检测运行中服务的健康状态，则扫描环境必须能访问目标服务
• 所有权识别采用启发式策略（优先级：CODEOWNERS > package.json > git blame），结果需人工复核与修正
• 请将服务目录保存为 .service-catalog.json，以启用 drift 检测能力
• 可作为轻量级替代方案，或作为 Backstage、Port、Cortex 等内部开发者门户工具的数据源