calltelemetry/traceroute

Traceroute Service 镜像文档

镜像概述

Traceroute Service 是一个基于 Elixir/OTP 构建的高性能分布式网络路径追踪服务，提供 HTTP REST API 和 NATS 消息两种接口，用于诊断网络路径。该服务利用 Elixir/OTP 的 supervision trees 实现高容错性，支持并发请求处理和超时管理，适合分布式系统中的网络诊断场景。

核心功能与特性

• HTTP REST API：提供简单的 HTTP POST 端点处理 traceroute 请求
• NATS 集成：通过 NATS 消息系统实现事件驱动的 traceroute 处理
• 容错设计：基于 Elixir/OTP 监督树架构，确保服务可靠性
• 结构化输出：JSON 格式响应，包含详细的网络路径信息
• 容器化部署：支持 Docker 部署，内置健康检查
• 测试覆盖：89% 测试覆盖率，包含属性测试
• 性能优化：并发请求处理与超时管理机制

环境要求

• Elixir：1.18.4+
• Erlang/OTP：26.2.5.2+
• NATS Server：用于消息驱动处理（可选，仅 NATS 模式需要）
• 权限要求：需要 ICMP 操作权限（CAP_NET_RAW 或特权模式）

安装与部署

本地开发

bash
# 克隆仓库
git clone <repository-url>
cd traceroute

# 安装依赖
mix deps.get

# 设置环境变量
source local-test.env  # 如有可用环境配置文件

# 运行测试
mix test

# 启动服务
mix run --no-halt

Docker 部署

bash
# 构建镜像
docker build -t traceroute:latest .

# 推荐方式：使用 CAP_NET_RAW 权限（更安全）
docker run --cap-add=NET_RAW -p 4100:4100 traceroute:latest

# 替代方式：完全特权模式（安全性较低）
docker run --privileged -p 4100:4100 traceroute:latest

安全说明：镜像默认以非 root 用户（appuser:1001）运行，仅通过 CAP_NET_RAW capability 获取 ICMP 操作所需权限，符合安全最佳实践。

配置说明

环境变量

NATS 配置

服务通过以下配置连接 NATS 进行分布式消息处理：

elixir
# 配置位于 lib/tracer.ex
%{
  host: System.get_env("NATS_HOST", "nats"),
  port: String.to_integer(System.get_env("NATS_PORT", "4222"))
}

API 使用指南

HTTP REST API

端点：POST /traceroute

请求示例：

bash
curl -X POST http://localhost:4100/traceroute \
  -H "Content-Type: application/json" \
  -d '{"host": "google.com"}'

响应示例：

json
{
  "status": 200,
  "body": {
    "result": "ok",
    "message": "Traceroute successful to google.com",
    "next_hop_ip": "172.217.14.46",
    "next_hop_hostname": "lga25s78-in-f14.1e100.net",
    "next_hop_fqdn": "lga25s78-in-f14.1e100.net"
  }
}

NATS 消息 API

主题：traceroute.request

消息格式：

json
{
  "body": "google.com",
  "reply_to": "response.topic"
}

响应：与 HTTP API 响应结构类似，通过指定的 reply_to 主题返回

架构设计

核心组件

• Tracer：主应用监督者
• Tracer.Worker：traceroute 执行逻辑
• Tracer.Web.Handler：HTTP 请求处理器
• NATS.Listener：NATS 消息处理器
• Tracer.Web.Supervisor：Web 服务器监督者

数据流程

1. HTTP 请求流程：Tracer.Web.Handler → Tracer.Worker → 响应
2. NATS 消息流程：NATS.Listener → Tracer.Worker → 回复

关键函数（Tracer.Worker）

• trace/1：执行 traceroute 的主函数
• clean_timeouts/1：过滤超时响应
• get_last_hop/1：提取有效跳数信息
• process_results/2：格式化响应数据

测试指南

运行测试

bash
# 运行所有测试
mix test

# 运行测试并生成覆盖率报告
mix test --cover

# 运行特定测试文件
mix test test/trace/worker_test.exs
mix test test/trace/handler_test.exs

# 排除集成测试
mix test --exclude integration

测试覆盖率

当前覆盖率：89.0%

测试结构

• 单元测试：test/trace/worker_test.exs、test/trace/handler_test.exs
• 集成测试：test/integration_test.exs
• NATS 测试：test/nats_listener_test.exs
• 监督者测试：test/trace/supervisor_test.exs
• 属性测试：基于 StreamData 的生成器测试（因复杂度暂注释）

测试依赖

elixir
# mix.exs 中的测试依赖
{:mox, "~> 1.1", only: :test},           # 模拟框架
{:stream_data, "~> 1.0", only: :test},   # 属性测试
{:excoveralls, "~> 0.18", only: :test},  # 覆盖率报告
{:ex_machina, "~> 2.8", only: :test}     # 测试数据生成

Docker 相关

Dockerfile 概述

dockerfile
FROM elixir:1.18.4 AS builder
# 多阶段构建优化生产镜像
# 包含 libssl 用于加密操作

DevSpace 配置（Kubernetes 开发）

yaml
# devspace.yaml
deployments:
  - name: traceroute
    helm:
      chart:
        name: ./charts/traceroute

监控与调试

日志

服务提供结构化日志：

• Info：成功的 traceroute 操作
• Error：失败操作、权限问题
• Debug：NATS 连接状态

健康检查

• HTTP 端点提供基本连接性检查
• NATS 连接状态监控
• 进程监督与自动重启机制

生产环境注意事项

安全性

• 权限控制：ICMP 操作需要特定权限（CAP_NET_RAW 或特权模式）
• 输入验证：所有主机输入均经过验证
• 错误处理：权限错误时优雅降级

性能

• 并发请求：支持多 traceroute 操作同时运行
• 超时处理：可配置超时防止操作挂起
• 内存管理：自动垃圾回收与进程清理

部署命令

bash
# 生产构建
MIX_ENV=prod mix release

# 生产 Docker 构建
docker build --build-arg BUILD_ENV=prod -t traceroute:prod .

# Kubernetes 部署
kubectl apply -f k8s/

贡献指南

开发环境设置

1. 安装指定版本依赖（见 .tool-versions）
2. 运行 mix setup 安装依赖
3. 确保本地 NATS 服务器运行
4. 运行测试验证环境：mix test

代码质量

bash
# 代码格式化
mix format

# 静态分析
mix credo

# 类型检查（如已配置）
mix dialyzer

# 完整质量检查套件
mix quality

添加测试

• 纯函数编写单元测试
• API 端点编写集成测试
• 使用 Mox 模拟外部依赖
• 边缘情况使用属性测试

参考资源

• Elixir 文档
• OTP 设计原则
• NATS.io 文档
• https://github.com/msantos/gen_icmp

许可证

详见 LICENSE 文件。

支持

问题与支持：

1. 查看现有测试获取使用示例
2. 检查日志获取错误详情
3. 确保 ICMP 操作权限正确配置
4. 验证 NATS 连接状态