Promscale完全上手指南：从安装到精通的3个关键步骤

一、核心功能速览

1.1 数据整合中枢

Promscale就像一个智能数据管家，能将来自Prometheus（时序数据监控系统）、Jaeger（分布式追踪工具）和OpenTelemetry（可观测性框架）的数据统一管理。它通过中间层连接器实现多源数据汇聚，再存储到PostgreSQL/TimescaleDB数据库中。

图1：Promscale核心架构展示数据流向与组件关系

1.2 应用场景

• 全链路监控：电商平台通过整合监控指标与追踪数据，快速定位支付失败问题
• 容量规划：云服务提供商利用历史指标预测服务器资源需求
• 故障排查：运维团队通过关联日志、指标和追踪数据缩短MTTR（平均恢复时间）

二、环境部署指南

2.1 快速启动流程

# 操作目的：获取项目代码
git clone https://gitcode.com/gh_mirrors/pr/promscale

# 操作目的：进入演示环境目录
cd promscale/docker-compose/promscale-demo/

# 操作目的：启动所有服务组件
docker-compose up -d

[!WARNING] 新手易错点

1. 未安装Docker会导致启动失败，需先执行docker --version确认环境
2. 端口冲突时需修改docker-compose.yml中的端口映射
3. 首次启动需耐心等待镜像下载（约5-10分钟）

2.2 验证服务健康的3种检查方法

💡 技巧：按以下顺序检查可快速定位问题

1. 容器状态检查：docker-compose ps确保所有服务状态为"Up"
2. 日志验证：docker-compose logs promscale | grep "ready"查看服务就绪日志
3. 端口测试：访问http://localhost:9201/health查看健康状态接口

三、配置参数解析

3.1 核心配置文件说明

核心代码：docker-compose/promscale-demo/目录下的docker-compose.yml定义了4个关键服务：

• promscale：数据连接器，负责数据接收与处理
• postgres：数据库服务，带TimescaleDB扩展
• grafana：可视化平台，默认账号admin/admin
• jaeger：分布式追踪系统，提供UI界面

3.2 配置差异对比

配置项	默认演示配置	生产环境建议
数据库存储	本地卷挂载	独立数据库集群
资源限制	未设置	CPU: 2核+，内存: 4GB+
持久化策略	基本配置	启用数据压缩与分区
安全认证	关闭	启用TLS与密码认证

📌 重点：生产环境必须修改的3个参数：

• POSTGRES_PASSWORD：设置强密码
• PROMSCALE_DB_URI：使用外部数据库地址
• RETENTION_POLICY：配置数据保留周期

常见问题速查表

问题现象	可能原因	解决方法
服务启动后Grafana无法访问	端口冲突	修改docker-compose.yml中grafana的端口映射
数据写入缓慢	数据库性能不足	增加数据库资源或启用TimescaleDB压缩
Prometheus连接失败	网络配置问题	检查promscale服务的PROMETHEUS_REMOTE_WRITE_URL参数
重启后数据丢失	未配置持久卷	确认postgres服务的volumes配置正确
Jaeger无数据显示	采集配置问题	检查OTLP接收器是否启用