Cyara NetTest 本地部署版 Docker 镜像文档

镜像概述和主要用途

本镜像为 Cyara testRTC nettest 应用的本地部署（自托管）版本，是一个轻量级 HTTPS 应用。支持两种使用场景：

• 本地测试环境：用于开发或测试阶段的网络性能验证
• 生产环境：部署于 ECS 或其他容器化基础设施，提供稳定的网络速度测试服务

核心功能和特性

• 自动 TLS 证书管理：通过环境变量配置完全限定域名（FQDN），自动获取和更新 Let's Encrypt 证书
• 双版本支持：提供 staging（测试版）和 stable（稳定生产版）两种镜像标签
• 持久化存储：通过数据卷保存 ACME 账户信息、证书和挑战文件，避免重复请求证书导致域名被拉黑
• 健康检查机制：内置健康检查接口，支持服务状态监控
• 跨环境适配：兼容本地 Docker 环境及生产级容器化基础设施（如 ECS）

使用场景和适用范围

• 企业内部网络测试：部署于内网服务器，用于员工或业务系统的网络性能自测
• 生产环境网络监控：部署于数据中心或云服务器，对外提供公开可访问的速度测试服务
• 多区域性能对比：通过配置不同区域代码（NETTEST_REGION），实现跨数据中心的网络性能对比

前提条件

硬件与操作系统要求

• CPU：2 核及以上
• 内存：2 GB 及以上
• 存储：至少 15 GB 可用空间
• 操作系统：Linux

网络配置（生产环境必需）

• 公网可解析的域名（FQDN）及对应 A 记录
• 开放并转发端口 80 和 443 至容器（用于 HTTP 重定向及 HTTPS 通信）
• FQDN 需通过环境变量传入容器，以自动获取 TLS 证书

软件依赖

• Docker 环境：需在目标机器安装 Docker（用于运行容器）

镜像标签

提供两种版本标签，区分测试与生产环境：

• staging/latest：测试版（包含最新开发特性，不稳定）
• stable：稳定生产版（经过验证的正式版本）

安装步骤

1. 登录目标机器

通过 SSH 或本地终端访问计划部署的服务器

2. 运行容器

根据使用场景选择以下命令：

生产环境部署（推荐）

bash
docker run -d \
    --restart=always \
    --name=nettest-on-prem \
    --env "FQDN=<DNS A 记录>" \  # 替换为实际域名（如 speedtest.example.com）
    --env "NETTEST_REGION=<数据中心区域代码>" \  # 替换为区域代码（如 "us-west"）
    -p 80:8080 \
    -p 443:8443 \
    -v /persistent-data:/data:Z \  # 本地持久化目录，需提前创建
    docker.io/spearline/speedtest:stable

测试环境部署（自签名证书）

无需 FQDN 和持久化卷，仅用于本地测试：

bash
docker run --rm -d \
    --name=nettest-on-prem \
    -p 80:8080 \
    -p 443:8443 \
    docker.io/spearline/speedtest:staging

配置说明

环境变量

数据卷

• 路径：/data
• 用途：存储 ACME 账户信息、TLS 证书、挑战文件等持久化数据
• 要求：
  • 生产环境必须挂载，否则容器重启后会重复请求证书，可能导致域名被 Let's Encrypt 拉黑
  • 测试环境（无 FQDN 时）可选，使用自签名证书无需持久化

服务监控与验证

部署后可通过以下接口验证服务状态：

关键文件路径

• /app：内置 Node.js 应用目录（仅供参考，不建议修改）
• /data：证书及 ACME 数据存储目录（需通过卷挂载持久化）

技术架构

• 核心组件：NetTest 应用（速度测试核心）
• TLS 管理：Caddy Web 服务器（自动证书申请与续期）
• 测试能力：内置自动化测试模块，支持基础网络性能指标采集

相关资源

• Cyara 支持：[***]
• 代码仓库：[***]

作者

Cyara, Inc. - [***]