企业官网建设流程全解析

1. 为什么Easypack这类部署工具必须把监控"顺便"装好

刚开始做自动化部署的时候，我一度觉得监控是另一条线上的事：部署工具负责把服务拉起来，Prometheus、Grafana这些到时候单独找运维同事再配置就行。直到有一次，我用Ansible批量部署了一套服务，进程确实都起来了，端口也确实listen了，所有人验收通过。结果第二天早上业务方告诉我页面打不开，我ssh上去一看，某个核心服务因为启动后健康检查不过被容器编排系统反复重启，CPU跑满，日志疯狂刷错。那一刻我才意识到——部署完成不等于服务可用，而"服务是否可用"这件事，只有监控体系能回答。

Easypack这种基于Ansible的部署工具，最核心的价值是"一条命令把环境拉起来"。但如果你拉起来的环境是个瞎子，没有指标采集、没有告警、没有数据留痕，那这套自动化只完成了一半。Prometheus是当前监控体系里最主流的选择之一，生态成熟，部署简单，易用性很高。把Prometheus支持直接集成到Easypack里，意味着每次部署业务服务的同时，监控体系会自动跟着就位，不需要单独花半天时间手工装exporter、改配置、重启服务。

这篇文章面向的读者，主要是已经在用Ansible做批量部署、或者想在自己的部署工具里加监控能力的运维和开发同学。如果你对Prometheus只有概念了解、没实操过，也没关系，我会从角色设计、Playbook编写、配置模板、上线排错这几个层面一步步拆开讲，把过程中踩过的坑和验证方法一并写出来。核心就一句话：让"部署完成"和"可观测"同时发生。

2. Easypack监控角色的整体设计：先想清楚装什么、怎么装

2.1 最小可用组合不是只有Prometheus一个组件

很多人提到"增加Prometheus支持"，第一反应是装一个Prometheus就完事了。实际落地的时候你会发现，单一Prometheus根本不解决监控问题——它只是把指标存下来，谁来采集？数据存在哪儿？怎么看？告警怎么发？这些全都要配套。

我在Easypack里最终规划的监控栈，是下面这套组合：

之所以强调"最小可用组合"，是因为监控体系本身也是个有依赖链的系统：Prometheus要抓node_exporter的/metrics端口，Grafana要连Prometheus的数据源，Alertmanager要接收Prometheus推送的告警。Easypack作为部署工具，必须把这条链一次性打通，而不是装完Prometheus就把剩下的扔给使用者。

2.2 Ansible角色怎么拆：一个role管一个组件

Easypack本身对Ansible的使用方式是标准的role组织。新增Prometheus支持时，我没有偷懒把一堆task塞进一个playbook里，而是按组件拆成了独立role。这样做的好处是：使用者可以按需选择——有人只需要Prometheus加node_exporter，有人想把Grafana一起装了，有人甚至只需要exporter配合已有的Prometheus，那就不装Server。

角色目录大概是这个形态：

easypack/ ├── inventory/ │ └── hosts.ini ├── playbooks/ │ ├── deploy_with_monitoring.yml │ └── deploy_core.yml ├── roles/ │ ├── prometheus_server/ │ │ ├── tasks/ │ │ │ └── main.yml │ │ ├── templates/ │ │ │ ├── prometheus.yml.j2 │ │ │ └── prometheus.service.j2 │ │ ├── defaults/ │ │ │ └── main.yml │ │ └── vars/ │ │ └── main.yml │ ├── node_exporter/ │ │ ├── tasks/ │ │ ├── templates/ │ │ └── defaults/ │ ├── cadvisor/ │ │ ├── tasks/ │ │ └── templates/ │ └── grafana/ │ ├── tasks/ │ └── templates/

这种结构最大的好处是复用。Easypack以后如果增加别的服务，直接在playbook里include对应role即可；如果某个组件需要单独升级，也不会牵连其他任务的执行顺序。

2.3 参数化设计：哪些值必须留成变量，哪些写死也没关系

第一次写Prometheus相关role的时候，我把抓取间隔、数据保留天数、监听端口全都写死在templates里。结果换了一台配置偏低的主机，想调整一下scrape_interval，得改模板再跑一遍ansible-playbook，非常烦。

后来我总结了一套参数维度的经验，分三档：

• 必须留变量：端口、数据目录、镜像版本、告警通知地址、抓取目标列表。这些在不同环境、不同机器上几乎必然不同。
• 留默认变量即可：抓取间隔、评估间隔、日志级别、保留策略。道理上可能按需调整，但大多数场景用默认值就行，放在defaults目录里，使用者想改随时可以改。
• 直接写死也可以：Prometheus容器内的二进制路径、exporter默认端口（比如node_exporter固定用9100）、service文件里的启动参数。写死能显著减少配置复杂度。

比如端口，node_exporter的9100基本是行业默认，你写成变量反而给使用者在两个地方配置的机会，容易产生不一致。而Prometheus的9090、Grafana的3000这种端口，虽然也是默认，但也经常因为和目标机器上已有服务冲突需要调整，所以必须写成变量。

3. 核心Playbook实现细节：从拉镜像到服务自启动

3.1 镜像版本的锁定策略

Easypack部署服务时既有二进制方式也有容器方式，Prometheus这套监控栈我全部采用容器化部署，统一用docker管理。这里有个我踩过坑的细节：镜像tag绝对不能写latest。

原因很简单：Prometheus和Grafana的版本迭代很快，latest在两次部署间隔中可能已经变了好几个版本，配置格式、默认参数、甚至PromQL语法都可能出现向后不兼容的变化。你三个月前写的服务发现配置，今天新部署一套环境，因为镜像换了导致配置解析失败，这种问题排查起来非常隐蔽。

我在Easypack里用的是这种写法：

prometheus_image: "prom/prometheus:v2.53.0" node_exporter_image: "prom/node-exporter:v1.8.2" cadvisor_image: "gcr.io/cadvisor/cadvisor:v0.49.1" grafana_image: "grafana/grafana:11.1.0"

版本全部锁在defaults/main.yml里，升级时显式改动版本号，再执行playbook滚动更新。这样每次部署出来的监控栈版本是确定性的，出问题能明确知道是哪个版本的行为。

另外一个小建议：如果部署环境是内网隔离的，记得提前在几台机器上docker pull好镜像，或者搭一个内网镜像仓库，否则每次部署都要从外网拉镜像，慢且不稳定。Easypack的文档里我特意加了这一步的说明。

3.2 生成Prometheus主配置：模板里不只是静态配置

Prometheus的配置文件是这套监控栈的核心。我的做法是提供一个Jinja2模板，把需要动态变化的部分全部参数化。

# roles/prometheus_server/templates/prometheus.yml.j2 global: scrape_interval: {{ prometheus_scrape_interval }} evaluation_interval: {{ prometheus_evaluation_interval }} scrape_configs: - job_name: 'prometheus' static_configs: - targets: ['localhost:9090'] - job_name: 'node' static_configs: - targets: {{ node_exporters | default([]) }} - job_name: 'cadvisor' static_configs: - targets: {{ cadvisor_targets | default([]) }}

初次看到这个模板的人可能会问：node_exporter不是部署在目标机器上吗，为什么它的targets还要单独定义？这里面有个Easypack特定的场景——一套Easypack可能管多台服务器，每台服务器都装了node_exporter，Prometheus需要把每台机器的地址都列为抓取目标。

所以在playbook执行时，需要先通过Ansible的add_host或set_fact把所有运行了node_exporter的主机IP收集起来，再渲染进模板。这里用一个非常关键的Ansible特性：role之间共享变量渲染顺序。我通常把整个部署拆成两个play：第一个play跑exporter类role，收集IP；第二个play跑prometheus_server role，渲染配置时就用第一个play收集到的变量。

3.3 node_exporter和cAdvisor的部署要点

node_exporter是监控栈里最容易装的组件，容器方式一条命令就能跑起来。但有几个细节不注意会出问题：

第一，必须挂载宿主机根目录。node_exporter的核心价值是读取宿主机的/proc和/sys文件，如果不挂载，容器内部看到的是容器自己的/proc，采集到的CPU、内存、磁盘数据全是错的。Easypack里的docker启动参数是这样写的：

docker run -d \ --name node_exporter \ --restart=always \ --network=host \ --pid=host \ -v /proc:/host/proc:ro \ -v /sys:/host/sys:ro \ -v /:/rootfs:ro \ prom/node-exporter:v1.8.2 \ --path.rootfs=/rootfs \ --path.procfs=/host/proc \ --path.sysfs=/host/sys

注意这里我用了--network=host而不是映射端口。node_exporter的9100端口如果走docker端口映射，会在iptables层面多一层转发，在有些系统上会带来不必要的连接跟踪问题。直接host网络最简单可靠。

第二，cAdvisor的权限问题。cAdvisor要读取容器运行时数据，在docker模式下需要挂载docker.sock，而且对cgroup的访问需要特权模式。安全的写法是只给它必要的capabilities：

docker run -d \ --name cadvisor \ --restart=always \ --network=host \ --privileged \ -v /:/rootfs:ro \ -v /var/run:/var/run:ro \ -v /sys:/sys:ro \ -v /var/lib/docker/:/var/lib/docker:ro \ -v /dev/disk/:/dev/disk:ro \ gcr.io/cadvisor/cadvisor:v0.49.1

--privileged看起来有点重，但cAdvisor官方文档目前也是推荐这个方式，我自己试过不加特权模式在部分内核版本上会采集不到容器网络指标，与其排查这种古怪问题，不如按官方推荐配置走。

3.4 数据持久化和存储周期：不配置等于白部署

Prometheus容器如果用默认配置启动，数据是存储在容器可写层里的。这意味着容器一旦删除重建，所有历史监控数据全部丢失，之前采集的指标、构建的警报状态统统归零。这显然是无法接受的。

Easypack里对Prometheus的数据目录做了如下处理：

prometheus_data_dir: "/data/prometheus"

对应的task里先创建宿主机目录，再通过-v挂载进容器：

-v {{ prometheus_data_dir }}:/prometheus

同时把--storage.tsdb.retention.time参数设为默认保留15天：

--storage.tsdb.retention.time={{ prometheus_retention_time | default('15d') }}

这里有一个值得强调的坑：容器内运行Prometheus时，数据目录的属主问题。Prometheus容器内是以nobody用户运行的，而宿主机挂载出来的目录如果是root属主，容器内nobody没有写入权限，启动时会报错，服务直接起不来。解决办法也很简单，在task里先把这个目录的属主改成nobody对应的uid（通常为65534）：

- name: Create Prometheus data directory file: path: "{{ prometheus_data_dir }}" state: directory owner: "65534" group: "65534"

这个小问题曾经让我在部署验证阶段浪费了近一个小时，服务看着启动了，但日志里全是mkdir /prometheus: permission denied，然后进程反复退出。后来我意识到容器内外用户映射的问题后，在文档里专门标注了这一点。

4. 抓取配置的模板化设计：静态目标、标签与动态发现的权衡

4.1 静态目标到底写在哪里最灵活

上一节里我给出了一个简单的prometheus.yml模板，其中node_exporter和cAdvisor的目标列表都是变量。实际使用中，这个变量到底怎么传，有两种常见的实现路径。

第一种：直接在inventory文件里定义。比如hosts.ini里给每台机器分组：

[monitored_hosts] 10.0.0.11 10.0.0.12 10.0.0.13

然后在prometheus_server role的vars里写：

node_exporters: "{{ groups['monitored_hosts'] | map('regex_replace', '$', ':9100') | list }}"

这种写法逻辑上很顺，但有个问题：Ansible的group概念和监控target的概念完全绑定了。如果某台机器装了exporter但不应该被Prometheus采集，你还得单独再建组，维护成本偏高。

第二种：通过set_fact在运行时动态构建。我实际更常用这种方式，因为Easypack的使用场景是"一套部署流程拉通多个服务"，exporter可能在多个不同组的机器上都存在。我在node_exporter的role里写了一个事实收集的task：

- name: Set node_exporter target fact set_fact: node_exporter_target: "{{ inventory_hostname }}:9100" when: - node_exporter_enabled | default(true)

然后在prometheus_server role的play里，通过hostvars汇总所有host的node_exporter_target，渲染进模板。这个做法稍微绕一点，但好处是targets列表完全由实际部署了exporter的机器决定，不存在"配置文件里写了但机器没装导致抓取失败"的状态漂移。

4.2 标签规范一定要早定

Prometheus的label设计直接影响后续所有查询和告警。Easypack里我规定了每个static_config必须带两个标签：env和role。比如：

- job_name: 'node' static_configs: - targets: {{ node_exporter_targets }} labels: env: {{ deploy_env }} role: 'node-exporter'

刚开始可能觉得这是多此一举，但一旦你有多个环境、多套业务，你就会发现没有标签的指标完全没法筛选。比如同样的node_memory_Active_bytes，在测试环境和生产环境数值完全不同，没有env标签你根本分不清哪条曲线是哪台机器的。

一个我遇到过很多次的场景：配置告警时想排除测试环境的低负载通知，如果没有env标签，你要么为每个环境单独写一套告警规则，要么在Alertmanager里做复杂的match过滤。有了env标签，一条规则加个env="production"的选择器就解决了。

4.3 抓取间隔和超时之间的数字关系

Prometheus抓取指标时有几个时间参数容易混淆：scrape_interval、scrape_timeout、evaluation_interval。我见过不少配置，scrape_interval设成5s，scrape_timeout默认10s，表面看没问题，实际上一旦目标响应慢，抓取会进入重叠状态，造成指标缺失和告警误报。

Prometheus官方有个原则：scrape_timeout必须小于scrape_interval，否则等于允许了串行抓取的重叠。合理的配置是：

scrape_interval: 15s scrape_timeout: 10s evaluation_interval: 15s

大多数场景下这个组合是稳的。如果目标机器很多或者exporter响应慢，可以把scrape_interval拉大到30s，但timeout保持在10s左右即可。监控粒度和系统开销之间要平衡，不是所有指标都需要5秒抓一次。Easypack里我把这三项全部参数化，但默认值就是15s/10s/15s，覆盖绝大多数场景。

5. 部署完成后的第一轮验证：别只看容器起来了

5.1 三层验证法：容器、端口、数据

每次执行完ansible-playbook，我都要做三层验证，缺一层都不放心。

第一层是容器状态。docker ps看看Prometheus、node_exporter、cAdvisor、Grafana是不是都处于Up状态，如果有容器反复重启，立刻docker logs看报错。这一层只证明容器活着。

第二层是HTTP端点。Prometheus的web界面在http://<host>:9090，node_exporter的metrics在http://<host>:9100/metrics，cAdvisor在http://<host>:8080/metrics（注意cAdvisor默认端口随版本变化，新版本已改用自定义端口）。用curl探一下这些端点：

curl -s http://127.0.0.1:9090/-/healthy curl -s http://127.0.0.1:9100/metrics | head -n 20

如果第二层通过，证明服务对外端口正常监听，HTTP响应符合预期。但到这里仍然不知道Prometheus内部是否成功抓取到了数据——这个要查第三层。

第三层是Targets状态和数据查询。浏览器打开Prometheus UI，进Status -> Targets页面，所有target的State应该是UP。再到Graph页面执行一条最简单的查询：

up

正常情况下你看到的up指标值全都是1。如果出现0或没有数据，说明抓取链路还有问题，得回去查网络、端口、配置。

5.2 自监控：先让Prometheus把自己管起来

Prometheus有一套自身运行状态的指标，比如prometheus_tsdb_head_series（当前时序数量）、prometheus_engine_query_duration_seconds（查询耗时）、up本身（目标是否在线）。把这些指标配置成告警，可以在监控体系自身出问题的时候及时通知你。

Easypack里的Prometheus默认配置就包含了对自身(target:localhost:9090)的抓取。在此基础上，我在rules里加了一条最基础的告警规则：

groups: - name: prometheus-self rules: - alert: PrometheusTargetMissing expr: up == 0 for: 1m labels: severity: critical annotations: summary: "Target {{ $labels.instance }} is down"

这条规则看起来简单，但实用性极高。它的意思是：任何一个被抓取目标连续1分钟处于down状态，就触发告警。它既能发现业务服务挂了，也能发现监控对象本身挂了——非常适合作为整个监控体系的"最低保障线"。

5.3 浏览器访问与首次打开Grafana的注意事项

Grafana默认监听3000端口，第一次打开会让你设置管理员密码。Easypack里我在grafana的task中通过环境变量预设了初始管理员：

-e GF_SECURITY_ADMIN_USER=admin \ -e GF_SECURITY_ADMIN_PASSWORD={{ grafana_admin_password }}

这样使用者打开页面直接用预设账号登录，不用走初始化向导。接下来要在Grafana里添加Prometheus数据源。这个过程也可以自动化——通过Grafana的API创建数据源：

curl -X POST http://admin:{{ grafana_admin_password }}@localhost:3000/api/datasources \ -H "Content-Type: application/json" \ -d '{ "name": "Prometheus", "type": "prometheus", "url": "http://localhost:9090", "access": "proxy", "isDefault": true }'

我在Easypack里专门写了一个grafana_init的task，用uri模块完成数据源注册。这么做的原因很朴素：如果每次装完Grafana都要使用者手动在界面上点五六步，那"部署工具自带监控"的体验就大打折扣了。

6. 上线后真正会踩的坑：权限、时间、告警沉默

6.1 容器挂在宿主机目录时的权限地图

前面提到Prometheus数据目录的uid 65534问题，其实容器挂载的权限坑不止这一个。Grafana同样有这个问题——它的数据目录（/var/lib/grafana）如果权限不对，容器启动会报chown: invalid user: 'grafana'之类的错误。

我在Easypack里统一处理了这些权限问题：

Grafana容器内运行用户是grafana，uid是472，这个数字是固定的，可以放心写进task。Alertmanager和Prometheus一样是用nobody用户运行，都是65534。每次新增一个挂载目录的组件，我都习惯先查一下官方Dockerfile里面定义的USER，再设置宿主机目录属主，避免启动即崩溃。

另外还有一个容易忽略的点：配置文件的属主和权限。Prometheus的配置文件如果权限是0644且属主root，容器内nobody可以读取，没问题；但如果目录本身对nobody没有读权限，同样会启动失败。Ansible的template模块生成的临时文件默认是0600属主root，如果直接挂载到容器内，可能会遇到读不了的问题。我习惯在template task之后显式指定owner和mode：

- name: Copy prometheus config template: src: prometheus.yml.j2 dest: "{{ prometheus_config_dir }}/prometheus.yml" owner: "65534" group: "65534" mode: "0644"

6.2 时区和时间戳：为什么Prometheus查不到数据

监控系统对时间极为敏感。Prometheus内部存储的时序数据是有时间戳的，查询时默认按当前时间对齐。如果部署Prometheus的机器时区不对（比如容器用的UTC，而宿主机是北京时间），你在UI上看到的曲线可能整体偏移8小时，或者因为总是落在"未来"而显示无数据。

我遇到过一次很隐蔽的情况：Prometheus容器运行在UTC时区，Grafana的浏览器端却自动按本地时区显示，结果两条曲线对比时，时间轴对不上，看起来像是采集xx家数据有延迟，实际上纯粹是时区偏移导致的展示问题。

解决方式统一加上时区环境变量：

-e TZ=Asia/Shanghai

并且在Grafana里，把默认Preferences的时区设置成Asia/Shanghai，包括Grafana配置文件的default_timezone项。我的建议是：所有容器都显式设置TZ环境变量，不要依赖宿主机的时区继承。因为容器在很多基础镜像是基于UTC构造的，不显式设置，时区就是UTC。

6.3 告警沉默了：Alertmanager与规则之间的链路检查

配置好Prometheus和Alertmanager后，有一个我踩了很久的坑：Prometheus界面的Alerts页面里规则已经显示为Firing，但邮件/微信通知始终发不出来。问题出在Prometheus和Alertmanager的对接参数上。

Prometheus推送告警到Alertmanager时，默认通过--web.alertmanager-url参数或配置文件里的alerting块指定地址。在容器方式部署时，如果Prometheus容器内用localhost访问Alertmanager，指到的是Prometheus容器自己，肯定连不上。必须使用宿主机IP或者docker network内的别名。

Easypack里我用的方案是：Prometheus和Alertmanager都加入到同一个docker bridge网络，通过容器名访问：

alerting: alertmanagers: - static_configs: - targets: - 'alertmanager:9093'

这里的alertmanager是docker网络内的容器名。这个配置如果不匹配，Prometheus的--web.alertmanager-url参数可能又被显式指定成别的值，导致配置文件里的alerting块被忽略。我建议干脆不用启动参数，全部在配置文件里管理Alertmanager地址，减少两处配置冲突的可能。

还有一个常见坑是Alertmanager的--config.file路径和容器内的路径不一致。我在Easypack里把Alertmanager配置目录挂载到了/etc/alertmanager，启动参数必须写成--config.file=/etc/alertmanager/alertmanager.yml，少一个字母都起不来，启动日志还会显示无法加载配置。

7. 从单机到多节点：扩展Easypack监控能力的几个方向

7.1 多机多组：把targets从静态变动态

前面提到静态targets靠hostvars汇总，这个方案在机器数量少于五六十台时非常稳定。一旦监控的主机数量涨到一两百台，每次部署时把所有主机IP全部写进一个配置文件会变得不可维护，而且Prometheus的配置文件会非常长，修改时容易出错。

这时候建议引入服务发现机制。Prometheus支持多种服务发现，Easypack里我预留了file_sd接口作为下一步扩展。配置方式是在prometheus.yml里这样写：

- job_name: 'node' file_sd_configs: - files: - '/etc/prometheus/sd/node/*.yml' refresh_interval: 30s

部署工具生成静态targets JSON/YAML文件放到这个目录，Prometheus会自动侦测文件变化并更新抓取目标。这样Easypack每新增一台机器，只需要往sd目录写一个文件，不需要重启Prometheus。相比直接修改主配置，这种方式更优雅，也能避免配置文件语法错误导致Prometheus整体挂掉的风险。

7.2 告警路由：不同环境不同通知策略

单机阶段的告警规则可以直接用Alertmanager的默认route把全部告警发到同一个渠道。但Easypack这种部署工具通常要支持多套环境（测试、预发、生产），不同环境的告警重要程度完全不同。

我在Alertmanager配置里按env名称做了简单路由：

route: group_by: ['alertname'] group_wait: 10s group_interval: 2m repeat_interval: 4h routes: - match: env: 'production' receiver: 'team-prod' continue: true - match: env: 'staging' receiver: 'team-dev'

关键点是repeat_interval。默认4小时重复发送一次告警，可以在告警持续期间不造成轰炸式的通知疲劳。但如果是生产环境的严重告警，你可能希望重复频率高一点，那就单独在production这个route里覆盖为1h。

7.3 版本升级策略与优雅滚动更新

Prometheus和Grafana的版本更新频率不低，Easypack管理这套监控栈需要一套可重复执行的升级流程。我的做法是：镜像版本号写在defaults/main.yml里，升级时只改版本号，重新跑一次playbook。

这里要注意的一个细节是：docker容器启动参数发生了变化时，ansible的docker_container模块默认不会自动重建容器。必须显式设置pull: true和image变化时触发重建。我在task里写了这样一个逻辑：

- name: Ensure Prometheus container is running docker_container: name: prometheus image: "{{ prometheus_image }}" state: started restart_policy: always pull: "{{ prometheus_image_updated | default(false) }}"

如果使用比较老的模块版本，可能不支持这个字段，那就用command模块配合docker inspect自己判断镜像是否变化，再决定是否需要docker rm和docker run。升级过程中的数据安全靠的是上一节讲的目录挂载，容器可以随便换，数据留在宿主机上就不会丢。

从Easypack这个项目里的实践来看，给一个成熟的Ansible部署工具增加Prometheus支持，最难的部分不是写playbook本身，而是把监控体系的各个子组件之间的依赖关系梳理清楚，并让这套关系在自动化脚本里稳定复现。当我第一次看到一条up曲线稳定显示为1、告警规则正常进入Firing状态、Grafana面板自动展现出业务服务的指标时，那种"部署环境一夜之间从裸奔变成全副武装"的感觉，确实挺踏实的。后面再碰到新环境要部署，Easypack跑完的那一刻，我心里就知道：服务起来了，监控也盯着了，剩下的就是正常迭代了。