零基础从零到一暴露 /metrics 端点（内网访问）的庖丁解牛

一、核心目标与安全原则

▶ 1.目标

• 暴露/metrics端点，返回 Prometheus 格式指标
• 仅允许内网 IP 访问（如10.0.0.0/8,192.168.0.0/16）
• 无外部依赖（纯 PHP 实现）

▶ 2.安全原则

• 禁止公网访问：防止敏感指标泄露（如数据库连接数）
• 最小权限：指标只读，无业务逻辑
• 轻量级：单文件实现，无额外库

二、完整代码实现（单文件）

▶ 1.创建/metrics.php

<?php// metrics.php - Prometheus 指标端点（仅内网访问）// 1. 安全校验：仅允许内网 IP$allowed_networks=['10.0.0.0/8','172.16.0.0/12','192.168.0.0/16','127.0.0.1/32'];functionis_private_ip($ip){foreach($allowed_networksas$network){list($subnet,$bits)=explode('/',$network);$ip_long=ip2long($ip);$subnet_long=ip2long($subnet);$mask=-1<<(32-$bits);if(($ip_long&$mask)==($subnet_long&$mask)){returntrue;}}returnfalse;}// 获取真实 IP（支持代理）$ip=$_SERVER['REMOTE_ADDR']??'0.0.0.0';if(isset($_SERVER['HTTP_X_FORWARDED_FOR'])){$ip=explode(',',$_SERVER['HTTP_X_FORWARDED_FOR'])[0];}if(!is_private_ip(trim($ip))){http_response_code(403);exit('Forbidden: Metrics endpoint only accessible from private networks');}// 2. 设置响应头header('Content-Type: text/plain; version=0.0.4; charset=utf-8');// 3. 收集指标$metrics=[];// 3.1 OPcache 指标if(function_exists('opcache_get_status')){$opcache=opcache_get_status();$metrics[]="# HELP opcache_memory_usage_bytes OPcache memory usage";$metrics[]="# TYPE opcache_memory_usage_bytes gauge";$metrics[]="opcache_memory_usage_bytes{state=\"used\"} ".$opcache['memory_usage']['used_memory'];$metrics[]="opcache_memory_usage_bytes{state=\"free\"} ".$opcache['memory_usage']['free_memory'];$metrics[]="# HELP opcache_hit_rate OPcache hit rate";$metrics[]="# TYPE opcache_hit_rate gauge";$hit_rate=$opcache['opcache_statistics']['misses']>0?$opcache['opcache_statistics']['hits']/($opcache['opcache_statistics']['hits']+$opcache['opcache_statistics']['misses']):1;$metrics[]="opcache_hit_rate ".$hit_rate;}// 3.2 内存使用$metrics[]="# HELP php_memory_usage_bytes PHP memory usage";$metrics[]="# TYPE php_memory_usage_bytes gauge";$metrics[]="php_memory_usage_bytes ".memory_get_usage();// 3.3 请求计数（简单示例）// 生产环境建议用 Redis 或 APCu 存储计数器$metrics[]="# HELP http_requests_total Total HTTP requests";$metrics[]="# TYPE http_requests_total counter";$metrics[]="http_requests_total ".(int)getenv('REQUEST_COUNT')?:1;// 4. 输出指标echoimplode("\n",$metrics)."\n";

三、Nginx 配置（强制内网访问）

▶ 1.添加 location 块

# /etc/nginx/sites-available/your-site server { # ... 其他配置 ... location = /metrics { # 1. 仅允许内网访问 allow 10.0.0.0/8; allow 172.16.0.0/12; allow 192.168.0.0/16; allow 127.0.0.1; deny all; # 2. 转发到 PHP-FPM fastcgi_pass unix:/run/php/php8.1-fpm.sock; include fastcgi_params; fastcgi_param SCRIPT_FILENAME /var/www/html/metrics.php; # 3. 禁用缓存 expires -1; add_header Cache-Control "no-cache, no-store, must-revalidate"; } }

▶ 2.重载 Nginx

sudonginx -t&&sudosystemctl reload nginx

四、验证与测试

▶ 1.内网访问（成功）

# 从内网机器访问curlhttp://your-server/metrics# 输出示例：# HELP opcache_memory_usage_bytes OPcache memory usage# TYPE opcache_memory_usage_bytes gauge# opcache_memory_usage_bytes{state="used"} 12345678# opcache_memory_usage_bytes{state="free"} 87654321# ...

▶ 2.公网访问（拒绝）

# 从公网 IP 访问curlhttp://your-server/metrics# 输出：Forbidden: Metrics endpoint only accessible from private networks

▶ 3.Prometheus 配置

# prometheus.ymlscrape_configs:-job_name:'php-app'static_configs:-targets:['your-server:80']metrics_path:/metrics

五、避坑指南

六、终极心法

**“/metrics 不是端点，
而是系统的脉搏——

• 当你校验 IP，
  你在守护安全；
• 当你暴露指标，
  你在量化状态；
• 当你集成 Prometheus，
  你在铸造可观测性。

真正的系统掌控，
始于对数据的敬畏，
成于对细节的精控。”

结语

从今天起：

1. 所有 PHP 服务暴露/metrics端点
2. Nginx 强制内网访问
3. 用 Prometheus 实现秒级监控

因为最好的系统稳定性，
不是祈祷不崩，
而是让每一比特都可被观测。