RUNBOOK —— EFK 日志平台与黑盒探测¶

适用对象：接手 monitoring 命名空间日常运维与值班的人。目标是拿着就能做，不假设你熟悉 Elasticsearch。变更实施与回滚过程见 SOP.md；本文面向「平时怎么用、怎么查、怎么救」。

目录¶

服务概览 2. 接入与凭据 3. 日常速查表 4. 日常操作
配置管理 6. 备份与恢复 7. 监控与告警 8. 故障处置
安全与权限 10. 容量与性能 11. 附录

一、服务概览¶

1.1 这是什么¶

集群 rainchen-k8s 的日志聚合与检索平台（EFK），外加面向入口的黑盒探测。前者把 4 个 K8s 节点与 14 台集群外主机的日志集中到 Elasticsearch，由 Kibana 检索；后者用 blackbox-exporter 从集群内主动探测对外入口、端口与证书到期。

1.2 组件构成¶

组件	工作负载	副本	作用	缺失时的后果
Elasticsearch	StatefulSet `elasticsearch`	1	存储与检索日志	日志断流，Kibana 全站不可用
Kibana	Deployment `kibana`	1	日志检索界面	无法看图查日志，ES API 仍可用
Filebeat（集群内）	DaemonSet `filebeat`	4	采集容器 stdout 与节点 `/var/log/messages`	对应节点日志缺失
Filebeat（集群外）	systemd `filebeat.service`	14	采集 14 台主机的 syslog 与领域日志	对应主机日志缺失
blackbox-exporter	Deployment `blackbox-exporter`	1	黑盒探测执行体	所有 `probe_*` 指标停更，探测类告警失效

1.3 依赖¶

依赖	说明	缺失时的直接后果
NFS 服务端 `192.168.31.249`（`nfs-csi-hdd`）	ES 数据盘（50 Gi PVC）	ES 卡在 IO 等待或无法启动；该主机同时承载 4 台 K8s 节点磁盘，属同源故障域
Traefik（k8s-master-01）	Kibana 的 HTTPS 入口 + 集群外 Filebeat 的 9200 TCP 入口	Kibana 打不开；14 台主机日志断流
集群内 DNS（CoreDNS）	Filebeat 经 Service 名连 ES	集群内采集停摆
`artifacts.elastic.co`	仅新增主机时才需要（装 RPM）	只影响新增节点，存量不受影响
宿主内核参数 `vm.max_map_count>=262144`	ES 启动硬要求	ES Pod 启动即退出

1.4 重要性等级¶

中。日志平台故障不影响业务链路，但故障复盘时会「没有日志可查」。其自身可用性问题应当天处理。

二、接入与凭据¶

2.1 访问地址¶

入口	地址	认证	备注
Kibana	`https://kibana.rainchen.top`	Elasticsearch 账号（见 2.2）	浏览器会提示自签证书，选择继续
Elasticsearch（集群内）	`http://elasticsearch.monitoring.svc:9200`	HTTP Basic	仅集群内可达
Elasticsearch（集群外）	`http://192.168.31.10:9200`	HTTP Basic	经 Traefik TCP 透传，供 14 台主机 Filebeat 使用

2.2 凭据清单¶

凭据	用途	存放位置	取用方式
`ELASTIC_PASSWORD`	超级用户 `elastic`，用于 Kibana 登录与排查	`/home/rain/.secrets/efk.env`（600）	`set -a; . /home/rain/.secrets/efk.env; set +a`（不要 `cat` 该文件）
`FILEBEAT_PASSWORD`	采集端写用户 `filebeat_writer`（仅能写 `filebeat*` 索引）	同上	由工程自动渲染进 14 台主机的 `/etc/filebeat/filebeat.yml`（0600 root）
`KIBANA_SYSTEM_PASSWORD`	Kibana 服务账号，日常无需人工使用	同上	同上

Kubernetes 侧同一份口令落在 Secret elasticsearch-credentials（monitoring 命名空间）。 轮换方式：删除 efk.env 中对应行 → 重跑 .venv/bin/python main.py deploy，工程会重新生成并向 ES 与 14 台主机下发；集群内 Filebeat 需 kubectl -n monitoring rollout restart ds/filebeat 才能读到新口令。

三、日常速查表¶

# 1) 组件总览
kubectl -n monitoring get sts,deploy,ds | grep -E "elastic|kibana|filebeat|blackbox"

# 2) ES 健康（在 Pod 内执行，口令取自 Secret）
kubectl -n monitoring exec -it elasticsearch-0 -- bash -lc \
  'curl -s -u "elastic:$ELASTIC_PASSWORD" "http://localhost:9200/_cluster/health?pretty"'

# 3) 索引与大小
kubectl -n monitoring exec elasticsearch-0 -- bash -lc \
  'curl -s -u "elastic:$ELASTIC_PASSWORD" "http://localhost:9200/_cat/indices/filebeat-*?v&s=index"'

# 4) 探测目标状态（经 ES Pod 访问 Prometheus Service）
kubectl -n monitoring exec elasticsearch-0 -- bash -lc \
  "curl -s 'http://kube-prometheus-stack-prometheus.monitoring.svc:9090/api/v1/query?query=probe_success'"

# 5) 集群外某台主机的采集状态
ssh root@192.168.31.16 'systemctl is-active filebeat; tail -5 /var/log/filebeat/filebeat'

# 6) 重启集群内采集端
kubectl -n monitoring rollout restart ds/filebeat

# 7) 重启 ES（单节点，会短暂中断日志写入）
kubectl -n monitoring delete pod elasticsearch-0     # StatefulSet 会自动重建

# 8) 只读校验全链路
cd /home/rain/Documents/k8s_ins/monitoring-p2-20261001 && .venv/bin/python main.py verify

四、日常操作¶

4.1 状态检查¶

kubectl -n monitoring get pods -o wide | grep -E "elastic|kibana|filebeat|blackbox"

预期：elasticsearch-0 1/1、kibana-* 1/1、filebeat-* 4 个（每节点一个）、blackbox-exporter-* 1/1。输出不符 → 见第八章。

4.2 启停¶

对象	停止	启动
Kibana	`kubectl -n monitoring scale deploy/kibana --replicas=0`	改回 `--replicas=1`
集群内 Filebeat	`kubectl -n monitoring delete ds filebeat`（危险：会停全集群采集）	`kubectl apply -f manifests/12-filebeat-k8s.yaml`
单台主机 Filebeat	`ssh root@<host> systemctl stop filebeat`	`systemctl start filebeat`
ES	不建议单独停；直接删除 Pod 会由 StatefulSet 重建	—

4.3 扩容：新增一台集群外主机¶

在 config/default.yaml 的 nodes 下加一行（{host, name, role}），必要时补 filebeat.extra_files； deb 系（Ubuntu/Debian）主机额外加 os_family: deb，并在 platforms 段登记其粗粒度域；
.venv/bin/python main.py deploy --limit <新主机IP>（只对该主机收敛）；
验证：ssh root@<新主机IP> 'systemctl is-active filebeat'。

新节点首次安装需要能访问 artifacts.elastic.co；不通时把制品放到 artifacts/filebeat-8.19.0-x86_64.rpm（RPM 系）或 artifacts/filebeat-8.19.0-amd64.deb（deb 系），工程会自动改走离线分发。

deb 系的两个差异（详见 docs/SOP-onboard-deb-network.md 步骤 2）： - 包查询与安装走 dpkg-query / curl + dpkg -i —— apt-get install <URL> 在本环境不可用 （实测报「无法定位软件包」，rc=100）； - 自监控 textfile 目录随各机 node_exporter 参数不同，由 filebeat.textfile_dir 按族配置（本环境：RPM 系 /var/lib/node_exporter/textfile，dell-R620 为 /opt/node-exporter/textfile）。

4.4 扩容：集群内新增 K8s 节点¶

Filebeat 是 DaemonSet，新节点加入后自动起一个 Pod，无需操作。

4.5 Kibana 分域视图（日志按集群域检索）¶

Kibana 预置了一个「日志分域视图」Dashboard，用于按集群域与日志类别快速定位日志。

入口：https://kibana.rainchen.top/app/dashboards#/view/efk-dashboard-domain-overview

结构：顶部 6 个控件（主机 / K8s Pod / 服务 / 级别 / 集群域 / 日志类别，级联筛选——选中主机后「服务」只列出该主机上出现过的服务）+ 9 个面板——域分布、 日志级别趋势、异常来源 · 按主机、异常来源 · 按 K8s Pod、域×类别、K8s 命名空间分布、 日志量 · 按服务、日志构成 · 服务 × 级别、最近日志明细。默认时间窗 24 小时；点击任一图元即自动过滤全部面板。

按服务看日志的注意事项（2026-10-02 实测）：service.name 自 2026-10-01 23:25 起才有值且不回溯存量—— 近 1 小时覆盖率 88.4%、7 天窗口仅 3.9%，故默认窗口已收为 24h。要看得最准就再收到最近 1 小时。主机侧 messages / secure / cron / maillog / dmesg 类日志按设计不推断服务名；「服务 × 级别」图例中的 (空) 段来自这批日志，属正常，不是采集故障。

排查路径（最常用）：控件里选「主机」或「K8s Pod」定位对象 → 选「级别 = error」筛出问题 → 在「最近日志明细」看原始行。全程不需要手写查询。

按服务看日志（2026-10-02 起）：顶部「服务」控件里选中一个服务（如 systemd、sidekiq），或直接在「日志量 · 按服务」/「日志构成 · 服务 × 级别」图上点击某个服务的柱子——下方「最近日志明细」立即只剩该服务的原始日志行；清空控件选项或点图表空白处即可恢复全量。

字段来源：主机侧 log.level 来自 journald 的 PRIORITY；K8s 容器侧由 Filebeat 按文本格式（JSON / klog / logfmt / 行首级别标记）解析，识别不出的保持空值（见 docs/SOP-log-level-parsing.md §9）。

域模型（2026-10-02 起为两级）：

层级	字段	取值	说明
粗	`platform`	`hpc` / `k8s`	HPC 平台（Slurm · LSF · Lustre · FlexLM · 提交节点）｜K8s 平台
细	`cluster`	`k8s` / `harbor` / `slurm` / `lsf` / `lustre` / `license` / `hpc`	其中 `hpc` 是提交节点 `.28`；`k8s` 为 2026-10-02 新补（此前 K8s 日志无域标签）；`harbor` = 镜像仓库主机 `.31`（platform 记 `k8s`）

改视图内容：编辑声明源 kibana/saved_objects/*.json 后重跑：

cd /home/rain/Documents/k8s_ins/monitoring-p2-20261001
.venv/bin/python main.py kibana --dry-run   # 预览差异，零副作用
.venv/bin/python main.py kibana             # 下发（幂等，第二次零变更）

排障要点：

面板空白、控制台报 Cannot read properties of undefined (reading 'map') → panelsJSON 里的 savedObjectId 没放进 embeddableConfig（见 docs/SOP-kibana-domain-view.md 第五章步骤 2）。
drift 报「Kibana 分域视图：漂移 N 项」→ 有人从 UI 改过对象，按上条命令重放声明即可收敛。
Kibana 登录口令见 §2.2；分域视图的回滚见 docs/SOP-kibana-domain-view.md 第七章。

日志 ↔ 指标互跳（2026-10-02 新增，静态 + 动态）：仪表板底部「查看指标（Grafana）」面板，按域跳转到 Grafana 对应大盘（env-overview / env-slurm / env-lustre / env-lsf / env-flexlm， https://grafana.rainchen.top/d/<uid>）；反向入口在 Grafana 各环境大盘右上角「查看日志（Kibana）」。

动态跳转（第二阶段，2026-10-02）：仪表板底部 p11「按主机日志量」是声明式 Vega 面板，点击柱形按主机所属域打开 Grafana 大盘（带 var-cluster）；Grafana 侧主机 Top15 面板反向带 host.name 跳回本视图。面板声明在 kibana/saved_objects/13-vega-host-metrics.json， 由 log-metrics-crosslink-20261002/build-vega-panel.py 生成（visState 与其内 spec 是双层字符串，勿手改），仪表板挂载在 06 的 p11。
链接口径对齐：集群外 14 台的日志 host.name 与指标 hostname 标签（裸主机名，无端口）逐字相同； K8s 侧日志 host.name 是 Pod 名（且无 cluster 字段），主机对齐须改用 kubernetes.node.name， Vega 面板已过滤掉无域标签的桶。
⚠ 「查看指标」为 legacy visualization（markdown）、Vega 面板同为 visualization，8.19 均可用；升级 Kibana 后需回归这两个面板。
⚠ 动态跳转的 URL filter 编码与 Vega 渲染尚未人工 UI 复验；Kibana 8.19 无公开 API 创建原生 URL drilldown（非独立 saved object），故改用 Vega。
回滚见 log-metrics-crosslink-20261002/backup/README.md。

4.6 网络设备日志与宿主 rsyslog（dell-R620）¶

OpenWrt(.2) 装不了 Filebeat，其日志经 logd 以 UDP 转发到宿主 dell-R620 的 rsyslog，落 /var/log/remote/<来源主机>/<程序>.log，再由宿主 Filebeat 采集（打 platform=network）。

# 宿主：接收端是否在跑（片段 + 端口 + 落盘）
sudo cat /etc/rsyslog.d/30-remote-input.conf              # imudp 514 + 按主机/程序分文件的模板
sudo ls -lR /var/log/remote                               # 预期 OpenWrt/{dropbear,logread}.log
ss -lunH | awk '{print $4}' | grep -E '[:.]514$'          # 预期 0.0.0.0:514（注意 Local 是第 4 列）
# 转发端：OpenWrt 是否指向宿主
ssh root@192.168.31.2 'uci -q get system.@system[0].log_ip; uci -q get system.@system[0].log_proto; /etc/init.d/log status'
# 幂等收敛（两端一起修）与漂移检测
PYTHONPATH="$HOME/py_public_modules" .venv/bin/python main.py deploy
PYTHONPATH="$HOME/py_public_modules" .venv/bin/python main.py drift

⚠ 这条链路由 config/default.yaml 的 network_logs 段驱动（receiver_host / source_host / port / remote_dir）。不要手改宿主 rsyslog 片段或 OpenWrt 的 uci —— 下次 deploy 会收敛回去。宿主是 KVM 宿主机，改 rsyslog 前务必保留语法门禁（实现体已内置：rsyslogd -N1 不通过即回滚片段）。

五、配置管理¶

5.1 配置文件位置¶

内容	位置	生效方式
工程配置（主机清单、版本、ILM、阈值）	`config/default.yaml`	重跑 `main.py deploy`
K8s 资源	`manifests/*.yaml`	`kubectl apply -f`（或重跑 deploy）
集群内 Filebeat 配置	`manifests/12-filebeat-k8s.yaml` 的 ConfigMap	apply 后需 `rollout restart ds/filebeat`
集群外 Filebeat 配置	`artifacts/filebeat-host.yml.tpl`（模板）	重跑 deploy，工程按 sha256 比对后下发；模板内 `host-vnc` 段按角色渲染，仅 hpc-submit(.28) 下发（其余主机连段删除）
宿主 rsyslog 接收片段	`/etc/rsyslog.d/30-remote-input.conf`（由 `modules/network_logs.py` 下发）	重跑 deploy（sha256 一致即跳过；重载后校验 514 在监听）
OpenWrt 日志转发	OpenWrt 的 `uci system.@system[0].log_ip` / `log_proto`	重跑 deploy（回读 `log_ip` 判幂等）
保留期	`config/default.yaml` → `efk.ilm.retention_days`	重跑 deploy（会 PUT 新策略）
Traefik 端口叠加	`manifests/15-traefik-es-port.yaml`	由 deploy 以 helm overlay 方式应用

5.2 易错点¶

不要手改 manifests/ 之外的既有工程：Traefik 的现场 values 是 ../traefik_deploy/values.yaml，任何时候 helm upgrade 都必须两个 -f 都带。
ILM 策略改小保留期不会立刻删数据：ILM 只在索引进入对应 phase 后触发，已有索引按各自 min_age 计算。
kubectl apply 不会删除已从清单中移除的对象（Probe、PrometheusRule 均如此），需要显式 delete。
Filebeat 没有 grok processor（那是 Logstash 的）：写 grok 会让 Filebeat 直接起不来（报 the processor action grok does not exist）。要提取字段用 script 或 dissect（2026-10-02 实测踩到）。
容器 input 的 parser 顺序不可颠倒：parsers 里 container 必须在 multiline 之前——否则续行仍带 CRI 前缀（以时间戳开头），^[[:space:]] 永不匹配，多行合并等于没配。
改采集解析（时间戳/多行）时：timestamp processor 必须带 ignore_failure: true（否则畸形行会被丢弃）与显式 timezone: Asia/Shanghai（日志按本地时间写，Filebeat 进程在 UTC 下运行）。参见 log-parse-20261002/SOP.md 第 5 章。

5.3 ES 插件（IK 中文分词）¶

IK 插件装在 ES 容器内，插件与词典都落在 data PVC 子目录，经 manifests/10-elasticsearch.yaml 的 subPath: plugins 挂到 /usr/share/elasticsearch/plugins，Pod 重建后依旧在。

# ① 查看已装插件（预期：analysis-ik）
kubectl -n monitoring exec elasticsearch-0 -c elasticsearch -- \
  /usr/share/elasticsearch/bin/elasticsearch-plugin list

# ② 验证分词（预期切成 知识库/搭建/方案）
kubectl -n monitoring exec elasticsearch-0 -c elasticsearch -- bash -c \
  'curl -s -u "elastic:$ELASTIC_PASSWORD" -H "Content-Type: application/json" \
   http://localhost:9200/_analyze -d "{\"analyzer\":\"ik_smart\",\"text\":\"知识库搭建方案\"}"'

易错点 - 重装 / 升级该插件时，elasticsearch-plugin install <url> 不会落包内 config/ 词典；缺词典会让索引创建失败、集群转 red（不只是分词不可用）。装完须把包内 config/ 拷到 plugins/analysis-ik/config/ 再重启。 - 词典是在 PVC 上手工补齐的，data PVC 被删则插件与词典一并丢失。 - 完整安装与回滚步骤见 docs/SOP.md 步骤 9.11、docs/IK-INSTALL-RESULT.md。

六、备份与恢复¶

项	现状
ES 数据	位于 PVC `data-elasticsearch-0`（`nfs-csi-hdd`，50 Gi）。未配置 ES 快照仓库（学习环境，日志为可再生成数据）
配置	全部在 git 工作区（`config/` + `manifests/`），随工程版本管理
恢复	数据丢失时：`kubectl -n monitoring delete pod elasticsearch-0` 让 ES 在新 PVC 上重建；历史日志不可恢复，新日志在数分钟内重新汇聚

手工备份（改配置前）：工程按全局规则把备份放 backup/ 并登记台账（见 backup/README.md）。

七、监控与告警¶

7.1 关键指标¶

指标	含义	在哪看
`probe_success`	各探测目标是否可用（1/0）	Prometheus / Grafana 任意面板查询
`probe_ssl_earliest_cert_expiry - time()`	证书剩余秒数	同上
`probe_duration_seconds`	探测耗时	排查「慢但没断」
`elasticsearch_cluster_health_status`	ES 集群健康	Kibana 无内置告警，需查 Prometheus 或 `_cluster/health`

7.2 告警规则¶

manifests/22-blackbox-alerts.yaml（PrometheusRule blackbox-alerts）：

告警	条件	级别	通知
`BlackboxProbeFailed`	`probe_success == 0` 持续 3 分钟	critical	邮件 P1（即时 + 2h 重复）
`BlackboxProbeSlow`	5 分钟均值 > 5s 持续 10 分钟	warning	邮件 P2（12h 重复）
`BlackboxCertExpiringSoon`	证书余期 < 30 天	warning	邮件 P2
`BlackboxCertExpiringCritical`	证书余期 < 14 天	critical	邮件 P1

告警经 Alertmanager 既有分级路由（category=cluster）发送，无需改动 Alertmanager 配置。

7.3 采集器自监控（Filebeat 自身是否健康）¶

端	看哪里	关键指标 / 索引
集群外 14 台	Grafana / Prometheus（经 node_exporter textfile）	`filebeat_scrape_up`（1=端点可达）、`filebeat_events_added_total`、`libbeat_output_events_acked_total`、`libbeat_pipeline_events_retry_total`
K8s 4 节点	Kibana → Stack Monitoring（或查索引 `.monitoring-beats-*`）	各 Beat 的发布/丢弃速率

# 主机侧：直接看 textfile 内容
ssh root@192.168.31.28 'cat /var/lib/node_exporter/textfile/filebeat.prom'

# 主机侧：确认采集自监控的定时器在跑
ssh root@192.168.31.28 'systemctl status env-filebeat-metrics.timer --no-pager | head -5'

# K8s 侧：确认监控索引已建立
kubectl -n monitoring exec elasticsearch-0 -- bash -lc \
  'curl -s -u "elastic:$ELASTIC_PASSWORD" "http://localhost:9200/_cat/indices/.monitoring-beats*?v"'

判读：filebeat_scrape_up=0 表示取不到 Filebeat 自身端点（Filebeat 挂了或 5066 未监听）； libbeat_pipeline_events_retry_total 持续上涨表示写入 ES 受阻（多为 ES 拒绝或磁盘水位）。

八、故障处置¶

场景 1：Kibana 打不开（502 / 超时）¶

症状：浏览器访问 https://kibana.rainchen.top 超时或 502。

诊断

kubectl -n monitoring get pods | grep -E "kibana|elasticsearch"   # 预期均 1/1
kubectl -n monitoring logs deploy/kibana --tail=30                # 关注 ES 连接失败、认证失败
kubectl -n monitoring exec elasticsearch-0 -- bash -lc \
  'curl -s -u "elastic:$ELASTIC_PASSWORD" localhost:9200/_cluster/health?pretty'

处置：ES 未就绪 → 先修 ES（场景 2）。ES 正常但 Kibana 报 401 → kibana_system 口令失配，重跑 main.py deploy 会重置。Traefik 侧 404 → 检查 kubectl -n monitoring get ingressroute kibana。验证：浏览器能打开登录页；日志中无 Unable to connect to Elasticsearch。

场景 2：Elasticsearch Pod 起不来（CrashLoopBackOff / 0/1）¶

症状：kubectl -n monitoring get pod elasticsearch-0 长期非 Ready。

诊断

kubectl -n monitoring logs elasticsearch-0 --tail=40
kubectl -n monitoring get pod elasticsearch-0 -o jsonpath='{.spec.containers[0].readinessProbe}'
ssh root@192.168.31.14 'sysctl -n vm.max_map_count'    # 预期 262144
kubectl -n monitoring exec elasticsearch-0 -- df -h /usr/share/elasticsearch/data

常见根因 1. max virtual memory areas vm.max_map_count too low → 在该 Pod 所在节点重设内核参数（见 SOP 步骤 2）； 2. readinessProbe 为 httpGet（旧版本清单）→ 401 永远不就绪 → 用 manifests/10-elasticsearch.yaml 重新 apply 并 kubectl delete pod elasticsearch-0； 3. 磁盘满 → ES 置只读；按第十章扩容或调小保留期。验证：_cluster/health 返回 status: green，Pod 1/1。

场景 3：Kibana 里看不到新日志（某台主机）¶

症状：某主机日志在 Kibana 中停留不动。

诊断

ssh root@192.168.31.16 'systemctl is-active filebeat; tail -20 /var/log/filebeat/filebeat | grep -iE "error|panic|connection"'
ssh root@192.168.31.16 'curl -s -o /dev/null -w "%{http_code}\n" http://192.168.31.10:9200'
ssh root@192.168.31.16 'sha256sum /etc/filebeat/filebeat.yml'

常见根因 1. 服务未运行 → systemctl status filebeat； 2. 401/403 → 口令失配：重跑 main.py deploy（会重新渲染配置）； 3. 连接被拒 → Traefik 侧 9200 入口缺失：kubectl -n server get deploy traefik -o jsonpath='{.spec.template.spec.containers[0].ports}' 中应含 elasticsearch，缺则重跑 deploy； 4. 配置与期望不一致（sha256 不符）→ 重跑 main.py deploy --limit <host>。验证：filebeat 变为 active，1–2 分钟后 Kibana 中该主机日志恢复写入。

场景 4：某个黑盒目标持续失败¶

症状：收到 BlackboxProbeFailed 邮件，或 probe_success 出现 0。

诊断

# 在 ES Pod 内直连探测接口，绕过 Prometheus 看原始结果
kubectl -n monitoring exec elasticsearch-0 -- bash -lc \
 "curl -s 'http://blackbox-exporter.monitoring.svc:9115/probe?target=https%3A%2F%2F192.168.31.10%2F&module=https_gitlab' | grep -E '^probe_success|^probe_http_status_code'"

处置：区分三类 —— ① 目标真故障（去修目标服务）；② 目标返回码不在 valid_status_codes 内（改 module）；③ 目标路由变更（如从 443 挪到 80，改 target 的协议）。验证：probe_success 回到 1；已存在时间序列的旧值需等 5 分钟过期，期间查询会同时看到新旧目标。

场景 5：采集器自监控报 `filebeat_scrape_up = 0`¶

症状：Grafana 中某台（或全部）主机的 filebeat_scrape_up 为 0。

诊断

host=192.168.31.28
ssh root@$host 'systemctl is-active filebeat; ss -lntp | grep 5066'
ssh root@$host 'curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:5066/stats'
ssh root@$host 'systemctl status env-filebeat-metrics.timer --no-pager | head -5'

常见根因 1. Filebeat 未运行 → systemctl restart filebeat； 2. 5066 未监听 → 配置里 http.enabled 缺失或被改（改完必须重启 Filebeat 才生效）； 3. helper 脚本未跑 → env-filebeat-metrics.timer 不是 active：systemctl enable --now env-filebeat-metrics.timer； 4. 脚本报错 → 手动执行 /usr/bin/python3 /usr/local/bin/env-filebeat-metrics; echo rc=$?。验证：filebeat_scrape_up 变回 1（timer 周期 60 秒，最多等 1 分钟）。

注意：不要去抓 /metrics —— Filebeat 没有 Prometheus 格式端点，只有 /stats（JSON）。

场景 6：网络设备（OpenWrt）日志在 Kibana 里看不到¶

症状：按 platform=network 过滤无结果；或 /var/log/remote/ 长时间不新增文件。

诊断（自上而下，逐段确认断在哪一环）

# 1) 来源在发？OpenWrt 的 logd 指向宿主
ssh root@192.168.31.2 'uci -q get system.@system[0].log_ip'          # 预期 192.168.31.249
# 2) 宿主在收？监听 + 落盘推进
ss -lunH | awk '{print $4}' | grep -E '[:.]514$'                     # 预期 0.0.0.0:514
sudo ls -lt /var/log/remote/OpenWrt/ | head -3                       # 预期 mtime 持续推进
# 3) 采集端在读？registry 是否登记了这些文件
sudo grep -o '"/var/log/remote[^"]*"' /var/lib/filebeat/registry/filebeat/log.json | sort -u
# 4) 是否入库（ES，只读账号）
curl -s -u logwatch_reader:$PW 'http://192.168.31.10:9200/filebeat-*/_count?q=platform:network'

常见根因 1. 第 1 步无值 → OpenWrt 侧被重置：重跑 main.py deploy（network_logs 会写回）； 2. 第 2 步无文件 → 宿主 rsyslog 片段缺失或未重载：重跑 main.py deploy； rsyslog 本身起不来则按 docs/SOP-onboard-deb-network.md 第七章回滚； 3. 第 3 步无登记 → 文件刚生成（扫描间隔 30s，稍等）或权限异常（预期 0640 syslog:adm，Filebeat 以 root 运行）； 4. 以上都正常但 ES 无数据 → 按「场景 3」查投递链路。

验证：platform:network 计数随时间递增；样本中 host_name=OpenWrt、service.name=<程序名>。

九、安全与权限¶

项	说明
账号模型	`elastic`（超管，仅人工使用）；`kibana_system`（Kibana 服务账号）；`filebeat_writer`（角色 `filebeat_writer_role`，仅 `filebeat*` 索引写权限）
凭据位置	本机 `/home/rain/.secrets/efk.env`（600）；K8s Secret `elasticsearch-credentials`；14 台主机 `/etc/filebeat/filebeat.yml`（0600 root）
传输加密	内网 HTTP 明文（`xpack.security.http.ssl=false`）—— 保留认证、放弃加密，属已知折中
Kibana 对外	经 Traefik HTTPS（自签证书），登录仍需 ES 账号
集群外 ES 端口	9200 在 `k8s-master-01` 上对所有内网开放（供 14 台主机推送）
轮换	见 2.2 的轮换说明；轮换后需重启集群内 Filebeat 并以新口令重跑主机侧

十、容量与性能¶

10.1 当前水位基线（2026-10-01 实测）¶

项	实测
ES 资源	requests 3Gi / limits 4Gi（heap 2G）
ES PVC	50 Gi（`nfs-csi-hdd`，宿主导出余量 482 GB）
保留期	ILM `efk-14d`：1 天或 20 GB 滚动，14 天删除
Prometheus TSDB	14 天仅占 5.1 GiB（100 Gi PVC）

10.2 扩容触发条件与操作¶

触发	动作
ES 数据盘使用率 > 80%	调小 `efk.ilm.rollover_max_size` 或 `retention_days`；或扩容 PVC（`nfs-csi-hdd` 支持 `AllowVolumeExpansion`）
ES 频繁 GC / OOM	抬高 `ES_JAVA_OPTS` 堆（不超过内存 limit 一半）与 limits
日志量激增（新增主机/服务）	先看 `_cat/indices` 定位来源，再决定排除或加保留期压力

10.3 已知瓶颈¶

单节点 ES 无副本，节点故障期间日志写入中断（学习环境可接受）；
单副本 Kibana/blackbox，重启期间对应功能短暂不可用；
各主机部署前的旧日志不可回溯，只有采集起点之后的数据（RPM 系 14 台起于 2026-10-01， Harbor 起于 2026-10-02 凌晨，dell-R620 与 OpenWrt 转发起于 2026-10-02 02:07）。

十一、附录¶

11.1 术语¶

词	含义
EFK	Elasticsearch + Filebeat + Kibana（本项目形态，不含 Logstash）
ILM	Index Lifecycle Management，索引生命周期策略，负责滚动与删除
Probe	Prometheus Operator 的探测类 CR，把黑盒探测目标转为抓取配置
filestream	Filebeat 8.x 的采集输入类型，取代旧的 log input

11.2 相关文档¶

变更实施与回滚：SOP.md
纳管扩面（deb 系主机 + 网络设备日志）：SOP-onboard-deb-network.md
监控蓝图与缺口台账：docs/MONITORING-ROADMAP.md
集群监控栈：prometheus_deploy/RUNBOOK.md
备份台账：backup/README.md

11.3 修订记录¶

日期	修改人	内容
2026-10-01	agent	首版：EFK 上线 + 黑盒探测 9 目标 + ILM 14 天
2026-10-02	agent	纳管扩面 1b 步骤 2/3：dell-R620（Ubuntu 24.04，deb 系）与 OpenWrt 转发日志接入；新增 §4.6、§5.1 两行、场景 6；§4.3 补 deb 系差异

来源：/home/rain/Documents/k8s_ins/monitoring-p2-20261001/docs/RUNBOOK.md ｜最后更新：2026-10-13 19:51（由 build/sync.py 同步，请勿在站点侧修改）