retriever (Team Retriever)

🔍 Retriever-云原生分布式观测平台

查看《项目报告》以获取最深入的细分：

• 项目总结

部署到AWS VPC的生产就绪可观察性堆栈，具有分布式跟踪、指标和警报功能

    

______________________________________________________________________

📋 目录

• 概述
• 建筑
• 先决条件
• 安装
• 部署
• 服务
• 认证
• 配置
• 监控和警报
• 故障排除
• 定制
• 清理

______________________________________________________________________

🎯 概述

寻回犬是一种 云原生可观察性平台 直接部署到您的AWS帐户中。它基于久经考验的开源工具构建，提供分布式跟踪、spanmetrics收集和智能警报，所有这些都在您的VPC中安全运行。使用内置的MCP服务器，它允许在一个环境中使用Cursor进行有用的调试工作流。

主要特点

• 📊 分布式追踪 通过Jaeger实现请求流可视化
• 📈 指标收集 通过Prometheus进行性能监控
• 🚨 智能警报 通过AlertManager与Slack集成
• 💾 永久存储 通过OpenSearch实现长期跟踪保留
• 🤖 AI集成 通过MCP服务器进行AI驱动的可观测性分析
• 🔒 缺省巩固安全 使用JWT身份验证和TLS加密
• ☁️ 云原生 部署到AWS ECS Fargate（无服务器容器）
• 🏗️ 基础设施即代码 使用Terraform进行可重复部署
• 🚀 一个命令部署 通过CLI-无需手动配置AWS控制台

为什么是寻回犬？

传统的可观察性平台要求：

• 复杂的手动设置和配置
• 按GB定价的昂贵SaaS订阅
• 供应商锁定和数据驻留问题
• 有限的定制选项

Retriever提供：

• ✅ 自托管在您的AWS帐户中（您控制您的数据）
• ✅ 通过CLI进行一次命令部署
• ✅ 使用Terraform实现自动化基础设施配置
• ✅ 完全访问源代码以进行自定义
• ✅ 仅为AWS基础设施付费（不收取每GB费用）
• ✅ 支持TLS、身份验证和自动扩展的生产就绪

______________________________________________________________________

🏗️ 建筑

高级概述

High-Level Architecture

AWS资源已创建

🔑 关键组件

______________________________________________________________________

📦 先决条件

必需

1. AWS帐户

- 管理员权限或足够的IAM权限 - 帐户必须支持您所在地区的Fargate

1. AWS-CLI 已配置凭据

   aws configure
   # or use environment variables:
   # export AWS_ACCESS_KEY_ID=...
   # export AWS_SECRET_ACCESS_KEY=...
   # export AWS_REGION=us-east-1

1. 现有VPC基础架构

- 至少有2个公共子网的VPC（用于ALB） - 1个专用子网（用于ECS任务） - 已连接互联网网关 - 专用子网的NAT网关

1. 域名 （适用于TLS）

- 您拥有一个域名（例如example.com） - 添加DNS记录的能力 - 域可以托管在任何地方（AWS Route53、DigitalOcean、Cloudflare等）

可选的

• Slack工作区 （用于警报通知）

- 用于发布消息的Webhook URL

______________________________________________________________________

🚀 安装

1.️⃣ 安装检索器CLI

# Clone the repository
git clone https://github.com/TeamRetriever/retriever.git
cd retriever/cli

# Install dependencies
npm install

# Build the CLI
npm run buildF

# Link globally (makes 'retriever' command available)
npm link

验证安装：

retriever --version

2.️⃣ 初始化配置

运行交互式安装向导：

retriever init

CLI将提示您：

1. AWS配置

- 地区（例如美国东部-1） - VPC ID - 公用子网ID（ALB高可用性需要2个） - 专用子网ID（用于ECS任务）

1. TLS证书设置

- 域名（例如observability.example.com） - 自动创建ACM证书 - 提供要添加的DNS验证记录

1. DNS验证

- 将CNAME记录添加到DNS提供商 - CLI等待验证完成（约5分钟）

1. JWT身份验证

- 生成加密安全的JWT密钥 - AWS Secrets Manager中的存储 - 创建初始访问令牌（有效期为10年）

1. Slack集成 （可选）

- 提示配置Slack webhook - 如果你不想收到Slack通知，请跳过

配置已保存到 .retriever-config.json:

{
  "region": "us-east-1",
  "vpcId": "vpc-xxxxx",
  "publicSubnetId1": "subnet-xxxxx",
  "publicSubnetId2": "subnet-xxxxx",
  "privateSubnetId": "subnet-xxxxx",
  "certificateArn": "arn:aws:acm:...",
  "domain": "observability.example.com",
  "jwtToken": "eyJhbGciOiJIUzI1NiIs..."
}

______________________________________________________________________

🚀 部署

部署基础设施

retriever deploy

发生了什么：

1. ✅ 验证AWS凭据和配置
2. ✅ 检查/创建ECS任务执行角色
3. ✅ 为Terraform状态设置S3后端
4. ✅ 初始化地形
5. ✅ 显示部署计划（要创建的资源）
6. ❓ 请求确认
7. 🚀 部署所有基础设施（约10-15分钟）

- 创建ECS集群 - 推出7项Fargate服务 - 配置应用程序负载平衡器 - 设置服务连接网格 - 配置安全组

1. ✅ 验证部署运行状况

输出：

✅ Deployment Complete!

Your Retriever observability platform is now running!

Load Balancer DNS: retriever-alb-xxxxxxxxx.us-east-1.elb.amazonaws.com

Next steps:
  1. Point your DNS A record for observability.example.com to:
     retriever-alb-xxxxxxxxx.us-east-1.elb.amazonaws.com
  2. Access Retriever at: https://observability.example.com
  3. Configure your applications to send traces to the collector

━━━ Access Information ━━━

Your JWT Access Token:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

This token is required to:
  • Log in to the web UI (paste when prompted)
  • Access the MCP server (use as Bearer token)
  • Valid for 10 years from generation

Token also saved in .retriever-config.json

🌐 服务

🔍 Jaeger用户界面

网址： https://your-domain.com/

查看分布式跟踪、分析服务依赖关系和调试性能问题。

特征：

• 按服务、操作、标签搜索痕迹
• 可视化跟踪范围和时间
• 分析服务依赖关系
• 比较跟踪性能

📊 普罗米修斯

网址： https://your-domain.com/prometheus

查询指标、可视化数据和查看活动警报。

有用的查询：

# Request rate by service
rate(calls_total[1m])

# Error rate
rate(calls_total{http_status_code=~"5.."}[1m])

# P95 Latency
histogram_quantile(0.95, rate(duration_milliseconds_bucket[5m]))

# Request rate by HTTP method
sum by(http_method) (rate(calls_total[1m]))

# Top services by request volume
topk(5, sum by(service_name) (rate(calls_total[5m])))

🚨 AlertManager

网址： https://your-domain.com/alertmanager

查看活动警报、静音和通知历史记录。

特征：

• 查看射击警报
• 创建静音以抑制通知
• 查看警报路由和分组
• 检查Slack通知状态

🤖 MCP服务器

人工智能与Claude Desktop集成的API端点。

集成： 配置Claude Desktop以进行连接：

{
  "mcpServers": {
    "retriever": {
      "url": "https://your-domain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_JWT_TOKEN"
      }
    }
  }
}

______________________________________________________________________

🔐 认证

所有服务均受保护 JWT身份验证 通过身份验证代理。

访问Web UI

1. 导航到 https://your-domain.com
2. 系统将提示您输入令牌
3. 粘贴您的JWT令牌（来自 .retriever-config.json)
4. 令牌存储在您的浏览器会话中

API访问

将您的JWT代币用作Bearer代币：

curl https://your-domain.com/prometheus/api/v1/query \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d 'query=up'

生成新令牌

# Generate a new token using existing secret
retriever generate-token

# Regenerate secret (invalidates all existing tokens)
retriever generate-token --regenerate-secret

______________________________________________________________________

⚙️ 配置

Spanmetrics连接器

Jaeger收集器会自动将跟踪转换为度量：

connectors:
  spanmetrics:
    histogram:
      explicit:
        buckets: [100us, 1ms, 2ms, 6ms, 10ms, 100ms, 250ms]
    dimensions:
      - name: http.method
      - name: http.status_code
      - name: service_name

生成的指标：

• calls_total -请求计数器（按服务、方法、状态）
• duration_milliseconds -延迟直方图

警报规则

配置于 terraform/infrastructure/prometheus/alert_rules.yml:

Slack集成

在AWS Secrets Manager中更新Slack webhook：

aws secretsmanager update-secret \
  --secret-id retriever-slack-webhookurl \
  --secret-string "https://hooks.slack.com/services/YOUR/WEBHOOK/URL" \
  --region us-east-1

retriever deploy --force-recreate

______________________________________________________________________

数据流

Your App → Collector → OpenSearch (traces)
                    └→ Spanmetrics → Prometheus (metrics)

1. 应用程序发送跟踪 通过OTLP（端口4317/4318）连接到收集器
2. 收集器进程跟踪：

- 在OpenSearch中存储以实现长期保留 - 通过spanmetrics连接器生成指标

1. Prometheus抓取指标 来自收集器（端口8889）

🐛 故障排除

检查部署状态

# View ECS service status
aws ecs list-services --cluster retriever --region us-east-1

# Check if services are running
aws ecs describe-services \
  --cluster retriever \
  --services rvr_query rvr_auth_proxy rvr_collector \
  --region us-east-1 \
  --query 'services[*].{Name:serviceName,Running:runningCount,Desired:desiredCount}'

常见问题

❌ “证书验证失败”

原因： DNS验证CNAME未添加或未传播

检查验证状态：

aws acm describe-certificate \
  --certificate-arn your-cert-arn \
  --region us-east-1 \
  --query 'Certificate.Status'

修复： 添加所示的CNAME记录 retriever init 您的DNS提供商。

❌ 访问UI时“未经授权”

原因： JWT令牌无效或已过期

修复：

# Generate new token
retriever generate-token

# Token is displayed - copy and paste into UI

❌ Jaeger中没有出现任何痕迹

验证收集器是否可访问：

# Test gRPC endpoint
grpcurl -d '{"message":"test"}' \
  your-domain.com:4317 \
  opentelemetry.proto.collector.trace.v1.TraceService/Export

# Check collector logs for errors
aws logs tail /ecs/rvr_collector --region us-east-1 --since 5m

检查Prometheus是否正在抓取：

# View targets in Prometheus UI
open https://your-domain.com/prometheus/targets

# Check alert evaluation
open https://your-domain.com/prometheus/alerts

验证AlertManager配置：

# View AlertManager config
aws logs tail /ecs/rvr-test-alertmanager --region us-east-1 --since 5m | grep "config"

______________________________________________________________________

🛠️ 定制

修改警报阈值

1. 编辑 terraform/infrastructure/prometheus/alert_rules.yml
2. 更改阈值：

   - alert: HighLatency
     expr: histogram_quantile(0.95, rate(duration_milliseconds_bucket[5m])) > 200  # Changed from 100ms
     for: 10m  # Changed from 5m

添加自定义警报规则

编辑 terraform/infrastructure/prometheus/alert_rules.yml:

- alert: LowRequestRate
  expr: sum(rate(calls_total[5m]))  ⚠️ **警告：** 避免高基数维度，如 `user_id`, `request_id`，或 `trace_id`。它们呈指数级增长度量序列计数和Prometheus内存使用量。

______________________________________________________________________

## 🧹 清理

### 销毁所有基础设施

Navigate to infrastructure directory

cd terraform/infrastructure

Destroy all AWS resources

terraform destroy

Confirm with 'yes' when prompted

**被删除的内容：**

- ✅ 所有ECS服务和任务
- ✅ 负载均衡器和目标群体
- ✅ 安全组
- ✅ 服务连接配置
- ❌ VPC，子网（不由Retriever管理）
- ❌ ACM证书（需要手动删除）
- ❌ S3状态桶（为安全起见保留）
- ❌ Secrets Manager机密（为安全起见保留）

### 手动清理（可选）

**删除ACM证书：**

aws acm delete-certificate \ --certificate-arn your-cert-arn \ --region us-east-1

**删除机密管理器机密：**

JWT secret

aws secretsmanager delete-secret \ --secret-id retriever/jwt-secret \ --force-delete-without-recovery \ --region us-east-1

Slack webhook

aws secretsmanager delete-secret \ --secret-id retriever-slack-webhookurl \ --force-delete-without-recovery \ --region us-east-1

**删除S3状态存储桶：**

Empty bucket first

aws s3 rm s3://retriever-tfstate-YOUR-ACCOUNT-ID --recursive

Delete bucket

aws s3 rb s3://retriever-tfstate-YOUR-ACCOUNT-ID

## 📚 其他资源

- [Jaeger文档](https://www.jaegertracing.io/docs/)
- [Prometheus文档](https://prometheus.io/docs/)
- [开放遥测技术规范](https://opentelemetry.io/docs/)
- [AWS ECS最佳实践](https://docs.aws.amazon.com/AmazonECS/latest/bestpracticesguide/)
- [Terraform AWS提供商文档](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)

______________________________________________________________________

## 📝 许可证

该项目是开源的，可在 [MIT许可证](LICENSE).

## 🤝 贡献

欢迎投稿、问题和功能请求！请随时查看 [问题页面](../../issues).

## 📧 支持

如有疑问或支持：

- 在GitHub上打开一个问题
- 检查 [故障排除](#-troubleshooting) 部分
- 查看地形日志： `terraform/infrastructure/terraform.log`

______________________________________________________________________

**内置于❤️ 在AWS上实现生产可观察性**