企业官网建设流程全解析

sql_exporter Docker部署实战：多阶段构建、CONFIG环境变量与健康检查清单

【免费下载链接】sql_exporterDatabase agnostic SQL exporter for Prometheus项目地址: https://gitcode.com/gh_mirrors/sqle/sql_exporter

sql_exporter是一个数据库无关（Database agnostic）的 SQL 指标导出器，专为Prometheus监控系统设计。本文带你用Docker 部署 sql_exporter，看懂它的多阶段构建 Dockerfile，掌握CONFIG 环境变量用法，并附一份可落地的健康检查清单。

🎯 一、sql_exporter 是什么？为什么值得用？

sql_exporter 是一个配置驱动的 Exporter：它执行你定义的 SQL 查询，把查询结果转换成 Prometheus 指标。

它内置支持以下数据库（只要有对应 Go 驱动就能扩展）：

它的核心设计理念是：指标和查询完全由配置定义。SQL 查询被分组到"采集器（Collector）"中——例如query stats、I/O stats或你自己的pricing data freshness。你可以快速定义自定义采集器来监控数据质量，而不需要写任何代码。

项目结构速览（方便后文对照）：

• Dockerfile：多阶段构建定义
• cmd/sql_exporter/main.go：程序入口，CONFIG 环境变量在这里生效
• config/config.go：配置解析与校验逻辑
• examples/sql_exporter.yml：开箱即用的配置示例
• examples/mssql_standard.collector.yml：SQL Server 标准采集器
• documentation/sql_exporter.yml：完整带注释的参考配置
• Makefile：构建脚本，提供make docker一键构建镜像

🐳 二、Dockerfile 揭秘：多阶段构建如何瘦身镜像？

打开项目根目录的Dockerfile，你会发现这是一个教科书式的多阶段构建（Multi-stage Build），总共只有不到 15 行：

# 第一阶段：构建阶段 FROM quay.io/prometheus/golang-builder AS builder ADD . /go/src/github.com/free/sql_exporter WORKDIR /go/src/github.com/free/sql_exporter RUN make # 第二阶段：运行阶段 FROM quay.io/prometheus/busybox:glibc COPY --from=builder /go/src/github.com/free/sql_exporter/sql_exporter /bin/sql_exporter EXPOSE 9399 ENTRYPOINT [ "/bin/sql_exporter" ]

它的工作方式分两步：

1. 构建阶段（builder）：使用 Prometheus 官方的 Go 构建镜像quay.io/prometheus/golang-builder，把源码拷贝进去并执行make，编译出sql_exporter二进制文件。编译环境（Go 工具链、依赖库等）全部留在这个阶段。
2. 运行阶段：切换到极简的quay.io/prometheus/busybox:glibc基础镜像，只通过COPY --from=builder把编译好的二进制拷贝到/bin/sql_exporter。

多阶段构建带来的好处：

• 📦镜像小：最终镜像不含 Go 编译器和依赖，体积远小于单阶段构建
• 🔒更安全：运行镜像里只有二进制和最小系统库，攻击面小
• 🚀启动快：静态编译的 Go 二进制直接作为ENTRYPOINT，冷启动几乎是瞬间的

此外还声明了：

• EXPOSE 9399：指标服务默认监听端口
• ENTRYPOINT [ "/bin/sql_exporter" ]：容器启动即运行导出器，后续参数（如-web.listen-address）会作为命令行参数传入

⚡ 三、CONFIG 环境变量：Docker 部署的关键一步

很多新手部署时最大的困惑是："容器里的配置放在哪？" sql_exporter 的答案是CONFIG 环境变量。

在入口文件cmd/sql_exporter/main.go中可以看到这段关键逻辑：程序启动时会检查环境变量CONFIG，如果设置了，就用它覆盖-config.file的默认值sql_exporter.yml。

优先级关系如下（从高到低）：

这意味着你不需要修改 Dockerfile，只需在运行时用-e CONFIG=...指定容器内的配置文件路径即可。

🚀 四、Docker 部署 sql_exporter：完整四步走

第 1 步：获取源码

git clone https://gitcode.com/gh_mirrors/sqle/sql_exporter cd sql_exporter

第 2 步：准备配置文件

参考examples/sql_exporter.yml创建你自己的配置（下面是一个最小示例）：

# 全局默认值 global: scrape_timeout_offset: 500ms min_interval: 0s max_connections: 3 max_idle_connections: 3 # 单目标模式：target 与 jobs 二选一 target: data_source_name: 'sqlserver://prom_user:prom_password@dbserver1:1433' collectors: [mssql_standard] # 采集器定义文件（支持通配符） collector_files: - "*.collector.yml"

把配置和采集器文件（如examples/mssql_standard.collector.yml）放到同一目录，例如./deploy/。

💡注意：配置中target（单目标）和jobs（多任务多目标）必须且只能定义其一，否则启动即报错，这个校验在config/config.go中实现。

第 3 步：构建并启动容器

# 构建镜像（也可直接使用官方发布的镜像） docker build -t sql-exporter:latest . # 启动：挂载配置目录 + CONFIG 环境变量 docker run -d \ --name sql_exporter \ -p 9399:9399 \ -v $(pwd)/deploy:/etc/sql_exporter \ -e CONFIG=/etc/sql_exporter/sql_exporter.yml \ sql-exporter:latest

各参数含义：

• -p 9399:9399：映射默认端口（可用-web.listen-address参数修改）
• -v $(pwd)/deploy:/etc/sql_exporter：把宿主机配置目录挂载进容器
• -e CONFIG=...：告诉容器读取哪个配置文件

第 4 步：验证

# 健康检查 curl http://localhost:9399/healthz # 拉取指标 curl http://localhost:9399/metrics

✅ 五、健康检查清单（Checklist）

部署完成后，建议按以下清单逐项验证。所有端点均在cmd/sql_exporter/main.go中注册：

补充两个实战要点：

1. up=0是"数据库挂了"，不是"exporter 挂了"：sql_exporter 设计上与数据库共享故障域。判断服务本体是否存活请用/healthz，判断数据库是否可连请用/metrics的up指标。
2. 超时保护：exporter 会自动读取 Prometheus 的抓取超时头（X-Prometheus-Scrape-Timeout-Seconds），并减去配置中的scrape_timeout_offset（默认 500ms），避免 Prometheus 先超时。该逻辑位于cmd/sql_exporter/promhttp.go。

🔍 六、常见问题快速排查

Q1：容器启动后立即退出？先docker logs sql_exporter看日志。最常见原因是配置校验失败（如target/jobs同时定义、采集器名称重复、DSN 缺失），配置解析逻辑见config/config.go，错误信息非常明确。

Q2：改了配置不生效？确认CONFIG环境变量指向的路径与你挂载的目录一致，且collector_files的通配符能匹配到采集器文件（相对路径是相对于配置文件所在目录解析的）。

Q3：想覆盖数据库连接串但不想改配置？单目标模式下可用参数-config.data-source-name覆盖配置中的 DSN（定义于exporter.go），方便在不同环境复用同一份配置。

📌 总结

sql_exporter 用不到 15 行的多阶段构建 Dockerfile，把 Go 编译环境挡在最终镜像之外，产出了一个小巧、安全、秒启的监控组件；CONFIG 环境变量让配置文件"外部化"，实现零改 Dockerfile 的部署灵活性；配合/healthz、/metrics、/sql_exporter_metrics三个端点，就能搭建一套职责清晰的健康检查体系。

按照本文的"四步部署 + 六项检查清单"，你现在就可以把任意受支持的数据库接进 Prometheus 了。🎉

【免费下载链接】sql_exporterDatabase agnostic SQL exporter for Prometheus项目地址: https://gitcode.com/gh_mirrors/sqle/sql_exporter