measurementlab/heartbeat

M-Lab Locate Service 技术文档

概述

M-Lab Locate Service（定位服务）是一个负载均衡器，旨在通过访问控制机制提供一致的“预期测量质量”。通常运行在GCP环境（如AppEngine或GKE）中，用于管理访问令牌（access_token）和资源分配，确保测量服务的可靠性和一致性。

核心功能与特性

• 负载均衡：提供资源分配和负载均衡能力，保障服务稳定性。
• 访问控制：通过JSON Web Token（JWT）密钥进行签名和验证，管理访问权限。
• 本地开发支持：支持本地模式运行，可使用本地生成的JWT密钥替代GCP Secret Manager，简化开发调试流程。
• Redis集成：提供docker-compose配置，可快速启动包含Redis的本地服务环境，支持缓存和状态管理。

使用场景与适用范围

适用于M-Lab定位服务的本地开发和测试环境，帮助开发人员在本地构建、运行和调试服务，无需依赖GCP云环境，降低开发门槛。

使用方法与配置说明

本地开发环境配置

1. 密钥管理（Secret Manager）

定位服务在GCP环境中运行时依赖Secret Manager读取签名和验证密钥，本地开发可通过生成本地JWT密钥规避该依赖。

生成JSON Web密钥

使用jwk-keygen工具生成EdDSA算法的JWT密钥（需提前安装该工具）：

sh
jwk-keygen --use=sig --alg=EdDSA --kid=localdev_20220415

生成后将得到私钥（如jwk_sig_EdDSA_localdev_20220415）和公钥（如jwk_sig_EdDSA_localdev_20220415.pub）文件，可复用同一密钥或生成多个密钥。

启动本地服务

在项目目录执行以下命令，使用本地密钥启动服务：

sh
./locate \
    -key-source=local \
    -signer-secret-name ./jwk_sig_EdDSA_localdev_20220415 \
    -verify-secret-name ./jwk_sig_EdDSA_localdev_20220415.pub

启动后访问localhost:8080，可看到使用本地密钥生成的access_token（返回的URL在公共平台无效）。

2. Redis集成

项目提供docker-compose配置文件，用于快速启动包含定位服务和Redis的本地实例。

启动本地服务与Redis

在“locate”项目根目录下执行以下命令，使用默认参数和预计算JWT密钥启动本地构建：

sh
docker-compose up

该命令将启动定位服务和Redis实例，适用于本地开发环境。

连接本地Redis实例

可通过以下方式连接本地Redis：

• 运行cmd/heartbeat命令
• 使用终端执行redis-cli命令直接连接

Docker部署示例

使用docker-compose启动本地环境

项目根目录下的docker-compose.yml配置文件可一键启动定位服务和Redis：

sh
# 在项目根目录执行
docker-compose up

此命令将自动构建并启动服务，集成Redis，适用于本地开发和测试场景。