零基础玩转Promscale：从部署到配置全攻略

Promscale 是基于PostgreSQL和TimescaleDB构建的统一指标与追踪可观测性后端，专为时序数据存储和Prometheus集成设计。本文将通过问题导向的实操指南，帮助你快速掌握环境部署、核心模块功能及配置优化技巧，即使零基础也能轻松上手。

3分钟快速上手

通过以下核心命令，3分钟内启动完整的Promscale演示环境：

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/pr/promscale

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

# 启动所有服务
docker-compose up -d

🔍 验证方法：执行 docker-compose ps 查看服务状态，所有服务状态为 Up 即表示启动成功。访问 http://localhost:3000 (Grafana) 和 http://localhost:16686 (Jaeger UI) 确认服务可用。

核心模块功能速查表

目录路径	核心功能	关键组件
cmd/promscale/	Promscale连接器主程序	数据接收、处理与写入逻辑
migration-tool/	Prometheus数据迁移工具	支持Prometheus数据导入导出
docker-compose/	环境部署配置	含高可用、演示等多种场景的Docker Compose文件
docs/	项目文档与资源	架构图、操作手册、最佳实践
pkg/	核心代码库	数据库交互、API处理、查询引擎等模块

如何理解Promscale架构？

Promscale采用分层架构设计，核心由连接器和数据库两部分组成：

• 数据流入层：支持Prometheus远程写入、Jaeger追踪数据及OpenTelemetry协议
• 处理层：通过Promscale Connector实现数据转换与优化
• 存储层：基于PostgreSQL+TimescaleDB+Promscale扩展，提供高效时序数据存储

环境部署与配置实战

如何快速部署完整环境？

推荐使用docker-compose/promscale-demo/目录下的配置文件，一键启动包含以下服务的完整观测栈：

# 进入演示目录
cd promscale/docker-compose/promscale-demo/

# 启动服务（后台运行）
docker-compose up -d

⚠️ 注意事项：首次启动需下载约1GB镜像，请确保网络通畅。服务启动后默认暴露端口：

• Grafana: 3000
• Jaeger UI: 16686
• Promscale Connector: 9201

常见配置场景对比

配置场景	适用场景	核心配置项	生产环境优化建议
演示环境	功能验证与学习	默认配置，单节点部署	仅用于测试，不可直接用于生产
高可用环境	生产部署	docker-compose/high-availability/ 目录下配置，多节点冗余	1. 启用数据卷持久化 2. 配置监控告警 3. 定期备份数据库
自定义集成	与现有Prometheus/Jaeger集成	修改promscale服务的REMOTE_WRITE_URL等环境变量	1. 使用私有镜像仓库 2. 配置TLS加密 3. 限制资源使用量

🔍 配置验证方法：修改配置后执行 docker-compose logs promscale 查看服务日志，确认无错误信息。

数据迁移工具使用技巧

使用migration-tool/工具迁移Prometheus历史数据：

# 编译迁移工具
cd promscale/migration-tool/cmd/prom-migrator/
go build -o prom-migrator

# 执行数据迁移（示例）
./prom-migrator --source-url=http://prometheus:9090 --target-url=http://promscale:9201

⚠️ 注意事项：迁移前确保目标Promscale服务已正常运行，建议在低峰期执行迁移操作。

生产环境注意事项

1. 资源配置：根据数据量调整PostgreSQL内存（建议至少4GB）和Promscale连接器CPU核心数
2. 数据备份：定期备份PostgreSQL数据目录，推荐使用TimescaleDB的备份工具
3. 监控告警：通过docs/mixin/目录下的Grafana仪表盘模板监控系统状态
4. 安全加固：禁用默认密码，配置网络访问控制，启用数据库SSL连接

通过以上步骤，你已掌握Promscale的核心部署与配置方法。如需深入学习，可参考项目docs/目录下的官方文档，获取更多高级功能与最佳实践。