第2章 环境准备与依赖安装

2.1 ​操作系统要求与原理

Matrix 框架设计为跨平台运行，但不同操作系统在包管理器、内核参数和性能隔离上存在差异。以下为各系统的最低要求与推荐配置：

2.2 ​Go 运行时环境安装

原理

Matrix 核心运行时采用 Go 编写，依赖 Go 1.22+ 的泛型、telemetry 和 goroutine 调度优化。系统必须安装 Go 并确保 $GOPATH 和 $GOROOT 正确设置。

实现流程

1. 下载官方二进制包（推荐，避免包管理器版本滞后）
2. 设置环境变量：export GOROOT=/usr/local/go; export PATH=$PATH:$GOROOT/bin
3. 验证安装：go version 输出应为 go1.22.2 linux/amd64 或更新。

命令示例

# Linux / macOS
wget https://go.dev/dl/go1.22.5.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc
go version

常见错误与调试

• “go: command not found” —— 检查 PATH 是否包含 /usr/local/go/bin，或重新执行 source ~/.bashrc。
• “go: unsupported GOOS/GOARCH pair” —— 跨编译时出现，确保 GOOS 和 GOARCH 组合正确。
• 版本低于 1.22 —— Matrix 编译将失败，显示类似 requires go1.22 的错误。

2.3 ​Prometheus / InfluxDB 安装

原理

Matrix 支持两种后端存储：Prometheus（内置 tsdb，适合短期告警和趋势）和 InfluxDB（列式存储，适合长期聚合和自定义保留策略）。双存储可在同一集群中共存，通过 matrix-router 进行分流。

安装对比

二进制安装命令

# Prometheus 2.53.0
wget https://github.com/prometheus/prometheus/releases/download/v2.53.0/prometheus-2.53.0.linux-amd64.tar.gz
tar xvf prometheus-*.tar.gz
cd prometheus-*
./prometheus --config.file=prometheus.yml &

# InfluxDB 2.7.5
wget https://dl.influxdata.com/influxdb/releases/influxdb2-2.7.5-linux-amd64.tar.gz
tar xvf influxdb2-*.tar.gz
cd influxdb2-*
./influxd --reporting-disabled &

调试命令

# 检查 prometheus 就绪
curl http://localhost:9090/-/ready
# 检查 influxdb 就绪
curl -v http://localhost:8086/health
# 常见错误：端口被占用 → netstat -tlnp | grep 9090

2.4 ​Docker Compose 快速部署

原理

Docker Compose 将 matrix-agent、Prometheus、InfluxDB、Grafana 打包为多容器声明式部署，降低环境差异。所有容器共享自定义网络 matrix-net，通过服务名互访。

实现流程

1. 安装 Docker 和 Docker Compose v2（apt install docker-compose-plugin）
2. 编写 docker-compose.yml
3. 执行 docker compose up -d
4. 验证：docker compose ps 应显示所有服务为 Running

docker-compose.yml 完整示例

version: "3.9"
services:
  prometheus:
    image: prom/prometheus:v2.53.0
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prom_data:/prometheus
    networks:
      - matrix-net

  influxdb:
    image: influxdb:2.7.5
    ports:
      - "8086:8086"
    environment:
      DOCKER_INFLUXDB_INIT_MODE: setup
      DOCKER_INFLUXDB_INIT_USERNAME: admin
      DOCKER_INFLUXDB_INIT_PASSWORD: matrix@2024
      DOCKER_INFLUXDB_INIT_ORG: matrix
      DOCKER_INFLUXDB_INIT_BUCKET: metrics
    volumes:
      - influx_data:/var/lib/influxdb2
    networks:
      - matrix-net

  matrix-agent:
    build:
      context: ./matrix
    ports:
      - "8080:8080"
    environment:
      MATRIX_PROMETHEUS_URL: http://prometheus:9090
      MATRIX_INFLUXDB_URL: http://influxdb:8086
    depends_on:
      - prometheus
      - influxdb
    networks:
      - matrix-net

volumes:
  prom_data:
  influx_data:

networks:
  matrix-net:
    driver: bridge

调试与常见错误

• 容器无法启动（exited with code 139） —— 通常为 seccomp 限制导致；在 docker run 中添加 --security-opt seccomp=unconfined。
• 网络不通：检查 docker compose down 并重新 up -d；必要时清理网络 docker network prune。
• InfluxDB 不匹配：首次启动会初始化访问令牌，可在 docker compose logs influxdb 中查看，或设置 DOCKER_INFLUXDB_INIT_ADMIN_。

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:9090/-/healthy"]
  interval: 30s
  timeout: 5s
  retries: 3

2.5 ​全量验证命令

完成安装后，执行以下命令确认所有组件就绪：

# 1. Go 版本
go version

# 2. Docker 和 Compose
docker compose version
docker info | grep "Server Version"

# 3. Prometheus 目标发现 (如果已配置)
curl -s http://localhost:9090/api/v1/targets | jq .

# 4. InfluxDB 健康
curl -s http://localhost:8086/health

# 5. Matrix Agent 指标端点 (默认 /metrics)
curl -s http://localhost:8080/metrics | head -20