cortexproject/cortex

Cortex Docker镜像文档

镜像概述和主要用途

Cortex 是一个为 Prometheus 提供水平扩展、高可用、多租户支持的长期存储解决方案。作为 CNCF 孵化项目，Cortex 被广泛应用于生产环境（如 Weave Cloud 和 Grafana Cloud），主要作为 Prometheus 的 remote write 目标，并提供与 Prometheus 兼容的查询 API。

核心功能和特性

水平扩展

Cortex 可跨集群中的多台机器运行，突破单节点的吞吐量和存储限制。支持将多个 Prometheus 服务器的指标发送到单个 Cortex 集群，并在统一位置执行全局聚合查询。

高可用

集群模式下，Cortex 可在机器间复制数据，确保机器故障时无监控数据间隙，保障图表连续性。

多租户隔离

支持在单个集群中隔离多个独立 Prometheus 数据源的数据和查询，允许不可信方共享集群资源，同时保证数据隔离。

长期存储

支持 S3、GCS、Swift 和 Microsoft Azure 作为长期存储后端，实现数据持久化存储（超出单节点生命周期），适用于长期容量规划。

使用场景和适用范围

• 大规模 Prometheus 监控：统一接收多个 Prometheus 实例的指标，实现全局指标聚合与查询。
• 多团队共享监控基础设施：通过多租户隔离，支持不同团队/项目共享 Cortex 集群，降低运维成本。
• 长期指标存储与分析：利用云存储后端（如 S3）存储历史指标，支持长期趋势分析和容量规划。
• 高可用监控系统：通过集群部署和数据复制，确保监控系统无单点故障。

部署与使用方法

前置要求

• Docker 19.03+ 或兼容的容器运行时
• 长期存储后端（如 S3、GCS，测试环境可使用本地存储）
• Prometheus 2.0+（用于数据写入）

Docker 快速启动

基本启动命令（单节点测试，使用块存储）

bash
docker run -d \
  --name cortex \
  -p 9009:9009 \  # HTTP API 端口
  -p 9095:9095 \  # 健康检查端口
  -e CORTEX_BLOCKS_STORAGE_ENABLED=true \
  -e CORTEX_BLOCKS_STORAGE_BACKEND=local \
  -e CORTEX_BLOCKS_STORAGE_LOCAL_DIRECTORY=/data \
  -v $(pwd)/cortex-data:/data \
  cortexproject/cortex:latest \
  -config.file=/etc/cortex/config-blocks.yaml

注意：生产环境需替换为分布式存储后端（如 S3），并配置集群模式。

docker-compose 部署示例（集群模式简化版）

yaml
version: '3'

services:
  cortex:
    image: cortexproject/cortex:latest
    container_name: cortex
    ports:
      - "9009:9009"   # HTTP API
      - "9095:9095"   # 健康检查
      - "7946:7946"   # 节点发现（gossip）
    environment:
      - CORTEX_TENANT_ID=default  # 默认租户 ID（多租户场景需动态配置）
      - CORTEX_BLOCKS_STORAGE_ENABLED=true
      - CORTEX_BLOCKS_STORAGE_BACKEND=s3
      - CORTEX_BLOCKS_STORAGE_S3_ACCESS_KEY_ID=AKIAEXAMPLE
      - CORTEX_BLOCKS_STORAGE_S3_SECRET_ACCESS_KEY=secret
      - CORTEX_BLOCKS_STORAGE_S3_BUCKET=my-cortex-bucket
      - CORTEX_BLOCKS_STORAGE_S3_ENDPOINT=s3.amazonaws.com
      - CORTEX_RING_BACKEND=memberlist  # 分布式一致性协调
    volumes:
      - ./cortex-config:/etc/cortex
      - ./cortex-data:/data
    command: -config.file=/etc/cortex/config.yaml
    restart: unless-stopped

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    restart: unless-stopped

Prometheus 配置示例（prometheus.yml）

yaml
global:
  scrape_interval: 15s

remote_write:
  - url: "http://cortex:9009/api/v1/push"
    headers:
      X-Scope-OrgID: "default"  # 与 Cortex 租户 ID 匹配

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

配置说明

核心环境变量

关键配置文件说明

Cortex 配置通过 -config.file 指定，推荐使用官方提供的块存储配置模板（config-blocks.yaml），主要配置段包括：

• blocks_storage：存储后端详细配置（如 S3 访问密钥、桶名称）
• limits：租户级限流配置（如每秒查询数、指标保留时间）
• distributor：数据写入分发配置
• querier：查询服务配置

注意事项

存储后端迁移

• 块存储（Blocks Storage）：自 v1.10.0 起推荐使用，替代传统的 Chunk Storage。
• Chunk Storage 弃用通知：Chunk Storage 已在 v1.10.0 中弃用，计划在 v1.14.0 中移除，需尽快迁移至块存储。

多租户配置

• 生产环境需通过请求头 X-Scope-OrgID 传递租户 ID，而非环境变量 CORTEX_TENANT_ID。
• 租户隔离需在配置中启用 auth_enabled: true，并配合外部认证系统（如 OAuth2、API Key）。

官方文档与资源

• Cortex 架构概述
• 块存储配置指南
• Prometheus 集成文档

社区支持

• Slack：CNCF Slack #cortex 频道（需通过 slack.cncf.io 注册）
• 邮件列表：***
• GitHub 议题：https://github.com/cortexproject/cortex/issues