Chever John 的博客

证书基础与一次 Traefik “Not secure” 排查实录

cheverjonathan@gmail.com (Chenwei Jiang) — Wed, 21 Jan 2026 00:00:00 GMT

TL;DR

现象：访问 https://traefik.example.local/dashboard/，Chrome/Safari 提示 Not secure；Firefox 正常。
根因：macOS Trust 验证器不接受通配符证书 *.example.local 对子域名 traefik.example.local 的匹配（OpenSSL 接受，Apple Trust 不接受）。
修复：签发显式域名证书 traefik.example.local，替代通配符赌博。
一句话：验证器规则决定一切，不是"证书坏了"。

这不是"证书坏了"的问题，而是"证书被验证的方式不同"。在 Linux/OpenSSL 眼里没问题，在 macOS/Apple Trust 眼里却不合格。

本文分两部分：证书的基础知识 + 今天这起排查的完整链路。

证书基础（够用就好）

先把最关键的概念拎出来：

证书链：叶子证书 → 中间证书（可选）→ 根 CA。浏览器只信任它认识的根 CA。
SAN（Subject Alternative Name）：域名匹配完全看这里，CN 已经退居二线。
信任库：macOS 有系统 Keychain；Firefox 有自己一套；Chrome/Safari 走系统信任。
验证结果：同一张证书，在不同验证器里可能得出不同结论。

一句话总结：证书“正确”不等于“被当前验证器接受”。

问题现象与影响范围

访问 https://traefik.example.local/dashboard/#/，Chrome/Safari 都提示 Not secure。

影响范围：

❌ Chrome（依赖 macOS System Keychain）
❌ Safari（依赖 macOS System Keychain）
✅ Firefox（使用自己的证书存储，不受影响）

可复现前提：

macOS 版本：Sonoma 14.x+（其他版本可能表现不同）
CA 已导入 macOS Keychain 并设置为"始终信任"
证书由 mkcert 签发（版本 1.4.4）
服务端在 10.0.0.100

我希望先回答三个问题：

域名是否解析到了正确的服务器？
证书链是否完整、域名是否匹配？
浏览器信任库是否真的认可这张证书？

假设清单（按排除顺序）

在开始排查前，先列出可能的根因假设：

H1：CA 未正确导入系统信任库
- 验证方法：检查 macOS Keychain，确认 CA 证书存在且为"始终信任"
- 预期：如果 CA 不在信任库，所有浏览器都会报错（但 Firefox 正常，所以可能性低）
H2：证书链不完整（缺少中间证书）
- 验证方法：openssl s_client -showcerts 查看证书链深度
- 预期：自签 CA 通常只有两层（leaf + root），mkcert 默认就是完整的
H3：SAN 不包含目标域名
- 验证方法：openssl x509 -text 查看 Subject Alternative Name 字段
- 预期：如果 SAN 缺失或不匹配，OpenSSL 也会报错（但 curl 通过了，所以可能性低）
H4：验证器规则差异（OpenSSL vs Apple Trust）
- 验证方法：用 security verify-cert 模拟 macOS 系统验证
- 预期：这是最可能的根因 —— 不同验证器对通配符的 hostname matching 规则不同

接下来逐条验证。

验证流程可视化

下面这个图展示了4层验证的递进关系（不执行任何操作，仅用于理解）：

#!/usr/bin/env bash
# 验证流程：4层检查，定位到底是哪一层不认

cat <<'EOF'

┌─────────────────────────────────────────────────────────┐
│  Layer 1: DNS Resolution                                │
│  dig traefik.example.local +short                       │
│  ✅ Result: 10.0.0.100                                   │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 2: Certificate Content (SAN)                     │
│  openssl s_client + grep "Subject Alternative Name"     │
│  ✅ Result: DNS:*.example.local, DNS:example.local      │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 3: OpenSSL Validator (Linux/curl)                │
│  curl -Iv https://traefik.example.local/                │
│  ✅ Result: SSL certificate verify ok                   │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 4: Apple Trust Validator (macOS)                 │
│  security verify-cert -n traefik.example.local          │
│  ❌ Result: Host name mismatch                          │
└─────────────────────────────────────────────────────────┘

关键发现：Layer 3 ✅ but Layer 4 ❌
→ 不同验证器对通配符的 hostname matching 规则不同
→ Chrome/Safari 依赖 Apple Trust (Layer 4)

EOF

排查链路（按顺序）

1) DNS 是否正确

dig traefik.example.local +short

预期输出：

10.0.0.100

观察：DNS 指向正确，网络层没问题。

结论：排除网络连通性问题，继续验证证书层。

2) 证书链与 SAN 是否正确

openssl s_client -connect traefik.example.local:443 -servername traefik.example.local -showcerts 2>/dev/null | openssl x509 -text -noout | grep -A2 "Subject Alternative Name"

预期输出（关键部分）：

X509v3 Subject Alternative Name:
    DNS:*.example.local, DNS:example.local

观察：SAN 包含通配符 *.example.local，按 RFC 6125 理论应该匹配 traefik.example.local。

结论：证书字段本身没问题，排除 H3（SAN 缺失）。

3) 用 OpenSSL 验证（通过）

curl -Iv https://traefik.example.local/ 2>&1 | grep -E "SSL certificate verify|subject:"

预期输出：

* SSL certificate verify ok.
* subject: CN=*.example.local

观察：OpenSSL 验证器认为证书有效，hostname 匹配通过。

结论：OpenSSL 认为没问题，排除 H2（证书链不完整）。

4) 用 macOS 系统验证（失败）

# 先导出证书到临时文件（如果还没导出）
echo | openssl s_client -connect traefik.example.local:443 -servername traefik.example.local 2>/dev/null | \
  openssl x509 > /tmp/traefik-leaf.pem

# macOS 系统级验证
security verify-cert -c /tmp/traefik-leaf.pem -p ssl -n traefik.example.local -L -v

预期输出（关键错误）：

...certificate verification failed
...Host name mismatch

观察：Apple Trust 明确拒绝了这个通配符对 traefik.example.local 的匹配。

结论：Apple Trust 认为这个 SAN 不能匹配目标域名。这是关键转折：OpenSSL OK，但 Apple Trust 不 OK。Chrome/Safari 都依赖后者。命中 H4（验证器规则差异）。

根因判断

根因不是"CA 没安装"，也不是"证书链缺失"，而是：

macOS 的主机名校验没有接受通配符证书对 traefik.example.local 的匹配。

这不是理论推测，是系统验证器的实际结果。

最小可行修复

不要赌通配符，直接签发显式域名证书。

mkcert -cert-file traefik.example.local.pem -key-file traefik.example.local-key.pem "traefik.example.local"

如果你希望保留通配符与根域：

mkcert -cert-file traefik.example.local.pem -key-file traefik.example.local-key.pem \
  "traefik.example.local" "*.example.local" "example.local"

然后在 Traefik TLS 配置里替换证书，重启服务即可。

一张排查清单（以后直接复用）

DNS 指向是否正确（dig）
SAN 是否包含目标域名（openssl x509 -text）
OpenSSL 验证结果（curl -Iv）
macOS 验证结果（security verify-cert）
浏览器是否使用系统信任库

复盘与预防

一句话教训

这次最值钱的证据： security verify-cert 的 Host name mismatch 输出 —— 它直接证明了问题不在"CA 信任"而在"hostname 验证规则"。

如果只能记住一件事： 不要用"在我电脑上能打开"来判断证书是否正确。不同验证器（OpenSSL / Apple Trust / Firefox NSS）对同一张证书可能得出不同结论。

预防性清单（下次签发证书时直接照做）

对于内网自签 CA（mkcert/自建 CA）：

优先签发显式域名，不要赌通配符的跨平台兼容性
如果必须用通配符，用 security verify-cert 在 macOS 上提前验证
保留签发命令记录（包含完整 SAN 列表），方便后续重新签发

对于公网证书（Let's Encrypt 等）：

申请时同时包含 example.com 和 *.example.com（如果需要覆盖根域和子域）
验证时至少在 3 个平台测试：Linux (OpenSSL) / macOS (Apple Trust) / Windows (Schannel)

验证模板（可复用脚本）：

#!/usr/bin/env bash
# 快速验证证书在多个验证器下的表现

DOMAIN="traefik.example.local"

echo "==> OpenSSL 验证"
curl -Iv https://${DOMAIN}/ 2>&1 | grep -E "SSL certificate verify|subject:"

echo "==> macOS 验证 (需要在 macOS 上运行)"
# 先导出证书
echo | openssl s_client -connect ${DOMAIN}:443 -servername ${DOMAIN} 2>/dev/null | \
  openssl x509 > /tmp/cert-to-verify.pem
# 系统验证
security verify-cert -c /tmp/cert-to-verify.pem -p ssl -n ${DOMAIN} -L -v

echo "==> 检查 SAN"
openssl s_client -connect ${DOMAIN}:443 -servername ${DOMAIN} /dev/null | \
  openssl x509 -text -noout | grep -A2 "Subject Alternative Name"

最终结论

证书问题最容易被"我已经导入 CA 了"这句话带偏。真正决定一切的，是验证器的规则，而不是你的主观印象。

这一次的结论非常清晰： 用显式域名证书替代通配符，Chrome/Safari 立刻恢复安全状态。

自建服务部署与运维经验：一些踩坑与总结（模板）

cheverjonathan@gmail.com (Chenwei Jiang) — Thu, 08 Jan 2026 00:00:00 GMT

部署经验总结（Traefik + Docker Compose + 域名访问 + 共享中间件）

这篇文章总结了本仓库这次连续部署多个服务（dockhand、vaultwarden、Checkmate、Miniflux(rss)）的经验、踩坑点、排查手法，以及我个人的部署习惯（也是本仓库后续建议遵循的“默认做法”）。

目标与底线

只允许域名访问：服务不对外暴露宿主机端口，避免 IP:端口 绕过认证/暴露管理面。
统一入口：对外只开 80/443，由 Traefik 统一反代、签发证书、加安全头。
共享基础中间件：MongoDB / Redis / PostgreSQL 这类通用组件集中维护、统一复用，避免每个应用重复起一套浪费资源。
Never break userspace（不破坏现有服务）：所有变更优先考虑是否会影响已在线服务（路由冲突、端口冲突、网络冲突、认证方式冲突）。

目录组织与“我的部署习惯”

每个应用一个目录：例如 dockhand/、vaultwarden/、Checkmate/、v2/（Miniflux）。
每个应用目录下有一个可直接运行的 docker-compose.yml：避免依赖上游仓库示例分散在 contrib/ 里不好维护。
共享中间件单独一个项目：新增 middlewares/，集中跑 postgres/mongodb/redis。
- 共享中间件只加入内部网络：对外不暴露任何端口。
- 应用通过 external network 方式加入共享网络获取 DB/缓存能力。
Traefik 统一网络：所有需要被 Traefik 访问的业务容器都加入 traefik_proxy 外部网络。
不滥用文件路由：优先使用 Docker labels（docker provider）。file provider 只用于少数“非容器化目标”或特殊转发。

标准部署模板（核心套路）

1）禁止宿主机端口暴露

对外服务统一做法：

用 expose:（仅容器网络可见）替代 ports:（宿主机可见）。
由 Traefik 通过 label 路由到容器端口。

这能一次性解决：

端口冲突（例如宿主机 3000 已被别的服务占用）
IP:端口绕过域名（安全风险）

2）Traefik labels（域名路由 + TLS + 安全头）

常规标签集合（示意）：

traefik.enable=true
traefik.http.routers..rule=Host(`miniflux.example.me`)
traefik.http.routers..entrypoints=websecure
traefik.http.routers..tls.certresolver=letsencrypt
traefik.http.routers..middlewares=security-headers@file
traefik.http.services..loadbalancer.server.port=

3）多网络容器必须指定 Traefik 网络

当容器同时加入：

traefik_proxy（给 Traefik 用）
infra_backend（给数据库/缓存用）

Traefik 可能选错 IP（选到它不在的网络），导致 504 Gateway Timeout。

解决：在该容器 labels 增加：

traefik.docker.network=traefik_proxy

本次 Checkmate 就是典型案例：加了这条后，504 立即消失。

共享中间件（middlewares 项目）

设计原则

高内聚低耦合：中间件只提供网络服务，不掺杂业务逻辑。
最小权限：默认不对外暴露端口，只在 Docker 内部网络给应用用。
数据持久化统一管理：卷在 middlewares 项目里集中维护（便于备份/迁移）。

经验要点

共享网络使用固定名字（例如 infra_backend），各应用 external: true 加入。
应用连接字符串里使用共享网络的服务名（例如 postgres/mongodb）。
不同应用之间尽量使用不同的 DB / schema / user，避免互相污染数据。

应用级注意点（本次踩坑记录）

Dockhand（容器管理面，风险极高）

必须禁用宿主机端口映射，只允许域名 + Traefik 访问。
必须加认证：用 Traefik basicAuth 中间件保护。
不建议再叠加复杂逻辑，越简单越不容易出事故。

Vaultwarden（Bitwarden 兼容服务）

这是最容易“自作聪明搞坏客户端”的服务：

不要对整个站点加 BasicAuth：官方客户端/浏览器插件会直接不可用。
正确做法：仅保护 /admin（管理后台）：
- /、/api、/identity 等客户端路径必须无 BasicAuth 阻挡。
遇到“插件能打开但登录失败”，先看：
- Cloudflare 是否给 API 下发 challenge（见下文）
- /api 是否被客户端当作 ServerConfig（必要时在 Traefik 做精确重写到 /api/config）

Checkmate（多网络 + Mongo）

共享 Mongo 后，容器加入多个网络会触发 Traefik 选错网络：
- 直接导致 504
- 用 traefik.docker.network=traefik_proxy 一把解决

Miniflux（miniflux.example.me）

Miniflux 只支持 PostgreSQL，不需要 Mongo/Redis（除非你额外跑 RSSHub、Browserless 等）。
HEAD / 返回 405 是可接受的（GET 正常即可），不要把它误判成服务挂了。

Cloudflare 的坑：客户端/插件集体“无法登录”

这次出现过两次同源问题：

Vaultwarden 浏览器插件：请求被 Cloudflare challenge 拦截 → 返回 403
Reeder（Google Reader API）：请求被 Cloudflare challenge 拦截 → 返回 403

共同特征：

响应头出现：server: cloudflare + cf-mitigated: challenge
请求根本到不了 Traefik/应用日志

解决策略（推荐优先级）：

A：该子域名切 DNS only（灰云）：最稳，不需要客户端做任何配合。
B：保留橙云，但对该 Host/路径跳过挑战：
- 至少放行：/api、/identity、/reader/api/0、/accounts/ClientLogin 等 API 路径

经验结论：

“能在浏览器里打开 ≠ 客户端能用”：浏览器能做人机验证，客户端做不了。

排错手册（从快到慢）

1）先判定“请求到没到服务器”

如果 Cloudflare 403 challenge：请求没到服务器，先处理 Cloudflare/WAF。
如果 Traefik 404/504：请求到 Traefik，但路由/网络/后端不可达。
如果后端 4xx/5xx：请求到应用，查应用日志与配置。

2）Traefik 侧排查

看 access log：该 Host 的请求落到了哪个 router/service、返回码是多少。
多网络容器：优先怀疑 traefik.docker.network 缺失。
同域名多路由来源：优先怀疑 file-provider 与 docker-provider 冲突（删掉旧 file 路由）。

3）应用侧排查

docker logs 看启动是否成功、是否监听端口、是否连上 DB。
检查是否误用了 ports: 导致端口冲突/暴露。

最终安全清单（上线前必做）

宿主机无业务端口暴露（只保留 80/443）
管理面必须有认证（dockhand、vaultwarden /admin 等）
数据库/缓存不对公网暴露
Traefik 路由无冲突（同 Host 不重复定义 file-provider + docker-provider）
Cloudflare 不对 API 下发 challenge（客户端/插件/第三方集成会挂）

日常排查：Minisforum N100 小主机随机掉盘/卡顿失去响应（DNS 服务运行 1 天+）

cheverjonathan@gmail.com (Chenwei Jiang) — Tue, 16 Dec 2025 00:00:00 GMT

这是一篇“日常排查记录”模板文章。我会尽量只写事实 + 证据链，避免凭感觉下结论。

TL;DR

问题现象：DNS 服务跑着跑着失去响应；整机出现明显顿卡；偶发（疑似）掉盘/IO 异常。
触发特征：随机出现，通常在连续运行 1 天+ 后发生。
恢复方式：关机断电并静置一段时间后恢复正常。
当前结论（概率表达）：____（例如：高概率与散热/供电/存储控制器复位相关）。

影响范围

直接影响：____（例如：内网所有设备 DNS 解析超时/失败）。
间接影响：____（例如：依赖域名解析的服务/容器全部异常）。
影响时段：____（开始时间/持续多久/是否自动恢复）。

环境信息（可复现前提）

硬件

CPU：Intel® N100（4C/4T，6MB Cache，最高 3.4GHz）
GPU：Intel® UHD Graphics
内存：8GB LPDDR5（单通道，板载，4800MHz）
存储：UFS 2.1 256G
无线：Intel AX200/201（Wi‑Fi 6 / Bluetooth 5.2）
有线：2.5G RJ45 ×1（支持 PoE IEEE 802.3at）
接口：USB 3.2 Gen2 Type‑A ×2；USB 3.2 Gen2 Type‑C ×1（Alt DP/PD）；HDMI ×1
电源：65W USB‑C Power Delivery 适配器

软件

实际运行系统：Linux（当前内核版本为 6.8.12-5-pve；出厂为 Windows 11 Home）
内核版本（如 Linux）：6.8.12-5-pve
引导加载器（GRUB）：grub2 2.06-13+pmx2
DNS 软件：____（dnsmasq / unbound / AdGuard Home / Pi‑hole / 其它）
部署方式：____（systemd / Docker / 其它）
其它常驻服务：____
日志策略：____（落盘频率/轮转策略/是否写入同一磁盘）

问题描述（只写事实）

首次出现时间：____
复现频率：大约每 ____ 小时/天一次（随机）。
故障时可观测症状：
- DNS：____（超时/拒绝/解析慢）
- 系统：____（SSH/远程桌面是否可达？CPU/内存是否飙升？）
- 存储：____（挂载点消失/只读/IO error/设备重置/掉盘）
- 网络：____（ping 是否丢包？网卡是否 reset？）
故障后的恢复动作：____（关机静置 ____ 分钟后恢复；“重启”是否也能恢复：____）
与负载的关系：____（高 QPS/日志写入/其它任务是否更容易触发）

当场止血（按时间线）

目的：先恢复核心服务，避免数据损坏，再谈定位。

T+0：____（例如：将上游 DNS 临时切换到路由器/公网 DNS）
T+5m：____（例如：停止 DNS 服务/停止高 IO 服务）
T+10m：____（例如：采集日志/抓取指标快照）
结果：____（是否恢复？持续多久？）

我关心的“数据结构”（证据链要对齐时间戳）

一个时间线：故障开始时间、温度峰值、IO 错误、服务超时，必须能对齐。
一个核心问题：是“DNS 服务死了”，还是“机器/存储子系统死了导致 DNS 表现为死”。

假设清单（按优先级）

H1：散热/过热导致保护或降频，继而触发系统不稳定
- 证据：____（温度曲线/thermal throttle log）
H2：供电不稳（PD/PoE/适配器）导致存储控制器或系统 reset
- 证据：____（kernel reset/电源事件/规律性）
H3：存储介质或控制器问题（UFS/NVMe/SATA）导致 IO 卡死或设备消失
- 证据：____（I/O error、timeout、device reset、SMART/health）
H4：软件层资源耗尽（FD/内存泄漏/日志写爆/IO 打满）
- 证据：____（ulimit、内存曲线、iowait、磁盘写入量）
H5：驱动/内核 bug（省电策略/设备电源管理）
- 证据：____（特定模块报错、升级/降级内核后变化）

数据采集（故障发生时我必须抓到什么）

不要靠“感觉像过热/像掉盘”，用日志说话。

温度/风扇：____（例如 Linux：sensors、/sys/class/thermal/；Windows：HWiNFO）
系统日志：____（Linux：journalctl；Windows：事件查看器）
存储相关日志：____（I/O error、timeout、reset、file system remount read-only）
资源指标：____（CPU、load、iowait、内存、swap、磁盘吞吐）
DNS 指标：____（QPS、缓存命中、上游延迟、失败率）
客户端验证：____（dig/nslookup 的失败表现）

关键证据（粘 3~5 段就够）

证据 1（定性）：

[time] ____

证据 2（支持链路）：

[time] ____

证据 3（排除项）：

[time] ____

排查过程（尝试 → 观察 → 结论）

尝试 A：____

改动：____
观察：____
结论：____（支持/否定哪条假设）

尝试 B：____

改动：____
观察：____
结论：____

尝试 C：____

改动：____
观察：____
结论：____

结论（概率表达，不装确定）

高概率主因：____
次要因素：____
我排除的方向：____（必须给证据）

解决方案（短期止血 vs 长期修复）

短期止血（马上能做）

____（例如：加强散热/开盖/外接风扇）
____（例如：限制功耗/关闭省电策略）
____（例如：降低日志落盘/开启轮转/把日志写到另一块盘）

长期修复（一次到位）

____（例如：更换电源/更换存储/更新 BIOS/固件）
____（例如：调整机箱风道/加导热垫/改善安装位置）
____（例如：升级/更换系统与内核版本）

验证标准

连续运行：____ 天无复现
温度上限：CPU ≤ ____°C；存储 ≤ ____°C
日志：无 I/O error / reset / remount read-only

复盘

这次最值钱的证据：____
下次更早做的事：____（例如：加监控、告警、故障自动抓日志）
仍未解决的问题：____

尝试方案：依赖 192.168.22.12（PVE 宿主）上的监控 LXC（192.168.22.19）持续监测 192.168.22.18（Minisforum）

目标：把“感觉像过热/像掉盘/像 DNS 挂了”变成一条可对齐时间戳的证据链：温度曲线 + IO/内核报错计数 + DNS 可用性探测 + 主机可达性。
注意：不要把账号密码写进任何配置文件/仓库。下面所有登录步骤都默认你手动输入密码或（更推荐）使用 SSH key。

额外坑：`22` 端口通，但 `ssh` 仍然卡住/断线（跨网段更常见）

这个坑很容易误导人：你看到 nc 显示 22/tcp open，就以为网络没问题；但 ssh 仍然会在握手阶段卡住，最后报超时或 Broken pipe。

场景（这次真实遇到的拓扑）

客户端网段：192.168.11.0/24
目标主机：192.168.22.12（PVE）
同网段跳板/对照：192.168.22.18（从这里 ssh 到 .12 通畅）
同时发生的信号：DNS 服务（例如 192.168.22.53:53）出现超时（反查/解析失败会放大 SSH 的握手耗时）

现象（典型表现）

nc -vz -G 2 192.168.22.12 22 显示 succeeded（TCP 三次握手没问题）
ssh root@192.168.22.12 卡住，随后出现：
- ssh_dispatch_run_fatal: Connection to 192.168.22.12 port 22: Operation timed out
- 或 Read from remote host 192.168.22.12: Operation timed out / client_loop: send disconnect: Broken pipe

快速判定（先把“端口通”细分）

看 SSH banner 是否能立即返回（只测协议，不涉及认证）：

nc -v 192.168.22.12 22

正常情况会快速看到类似 SSH-2.0-OpenSSH_...。如果连上但 banner 很久不出/不出，说明问题更像在 sshd/系统层（例如 DNS 反查阻塞、系统负载、网络策略导致后续数据不稳定），不是“单纯端口被挡”。

抓 SSH 卡在哪一步（留证据用）：

ssh -vvv -o ConnectTimeout=5 -o ServerAliveInterval=5 -o ServerAliveCountMax=1 root@192.168.22.12

最小修复（优先消灭 DNS/GSSAPI 造成的特殊情况）

如果你能从同网段主机（例如 .22.18）登录到 .22.12，优先在 服务端做这两个改动（对内网环境通常更稳、更“少坑”）：

编辑 .22.12 的 /etc/ssh/sshd_config，确保存在：

UseDNS no
GSSAPIAuthentication no

校验并重启：

sshd -t && systemctl restart ssh
systemctl status ssh --no-pager

直觉解释：当 DNS/反查不稳定时，UseDNS yes 可能让 SSH 在握手/审计阶段等待解析结果；把它关掉能让“特殊情况”消失。

如果仍然不稳：按“跨网段三件套”继续排除

回程路由是否正确（目标机必须知道怎么回 192.168.11.0/24）：

ip route get 192.168.11.12

防火墙/ACL：除了放行 22/tcp，还要确保回程方向与状态跟踪规则一致（尤其是网关/NAT/策略路由）。
MTU/分片问题：跨网段、隧道、PPPoE 场景容易出现“能握手但数据阶段不稳”；建议在 Linux 上用带 DF 的大包 ping 做一次验证（必要时先临时把 MSS/MTU 调小验证）。

总体架构（最少但够用）

192.168.22.19（监控端 LXC，运行在 192.168.22.12 这台 PVE 上）：Prometheus + Grafana + blackbox_exporter（可选 Pushgateway）
192.168.22.18（被监控端）：nodeexporter（主机指标）+（可选）smartctlexporter（磁盘健康）+ 自定义 textfile 指标（内核/IO error 计数）

这套东西的“数据结构”很简单：

时序指标（Prometheus）：每 15s 抓一次，故障前后至少覆盖 48 小时。
主动探测（blackbox_exporter）：从 .19 主动 ping / tcp 探测 .18/.54，区分“机器死了”和“服务死了”。
告警（可选）：故障发生时把时间戳钉死（邮件/Telegram/飞书随你，先把规则跑起来）。

尝试 D：监控栈落地（Prometheus + Grafana + blackbox_exporter）

D0. 前置检查（网络与端口）

在 192.168.22.19 上确认能到达 192.168.22.18：

ping 192.168.22.18
Test-NetConnection 192.168.22.18 -Port 22

后续会用到的端口（按默认值）：

.18:9100 node_exporter
.18:9633 smartctl_exporter（可选）
.19:9090 Prometheus
.19:3000 Grafana
.19:9115 blackbox_exporter
.19:9091 Pushgateway（可选）

如果你有防火墙/安全组，先放行 .19 -> .18 的 9100/9633/22，以及 .19 -> .54 的 53/3000（只在内网开放就行）。

D1. 在 192.168.22.18 部署 node_exporter（systemd 方式，最稳）

在 .18 执行（版本号你可以换新，但别用“latest”，排查时要可追溯）：

export VER="1.7.0"
curl -fsSL -o /tmp/node_exporter.tar.gz "https://github.com/prometheus/node_exporter/releases/download/v${VER}/node_exporter-${VER}.linux-amd64.tar.gz"
tar -C /tmp -xzf /tmp/node_exporter.tar.gz
install -m 0755 /tmp/node_exporter-${VER}.linux-amd64/node_exporter /usr/local/bin/node_exporter

useradd --system --no-create-home --shell /usr/sbin/nologin nodeexp || true
mkdir -p /var/lib/node_exporter/textfile_collector
chown -R nodeexp:nodeexp /var/lib/node_exporter

cat >/etc/systemd/system/node_exporter.service <<'EOF'
[Unit]
Description=Prometheus Node Exporter
After=network-online.target
Wants=network-online.target

[Service]
User=nodeexp
Group=nodeexp
ExecStart=/usr/local/bin/node_exporter \
  --web.listen-address=:9100 \
  --collector.textfile.directory=/var/lib/node_exporter/textfile_collector
Restart=on-failure
RestartSec=2

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now node_exporter
systemctl status node_exporter --no-pager

验证（在 .12 或任意内网机器）：

curl -fsS http://192.168.22.18:9100/metrics | head

D2.（可选但强烈建议）在 192.168.22.18 增加“内核/IO 错误计数”自定义指标

做法：用 node_exporter 的 textfile collector 每分钟吐一个计数指标（避免你事后翻日志翻到吐）。

cat >/usr/local/bin/collect_kernel_error_metrics.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

OUT="/var/lib/node_exporter/textfile_collector/kernel_errors.prom"
TMP="$(mktemp)"

# Count kernel messages in last 10 minutes (adjust if needed)
COUNT="$(journalctl -k --since "10 min ago" --no-pager 2>/dev/null | \
  grep -Eic 'I/O error|timeout|reset|remount read-only|EXT4-fs error|BTRFS error|blk_update_request|nvme|ufs' || true)"

NOW="$(date +%s)"

{
  echo "# HELP kernel_error_events_10m Number of kernel error-like events in last 10 minutes"
  echo "# TYPE kernel_error_events_10m gauge"
  echo "kernel_error_events_10m ${COUNT}"
  echo "# HELP kernel_error_scrape_time_seconds Last collect time"
  echo "# TYPE kernel_error_scrape_time_seconds gauge"
  echo "kernel_error_scrape_time_seconds ${NOW}"
} >"${TMP}"

mv "${TMP}" "${OUT}"
EOF

chmod +x /usr/local/bin/collect_kernel_error_metrics.sh

cat >/etc/systemd/system/kernel-error-metrics.service <<'EOF'
[Unit]
Description=Collect kernel error metrics for node_exporter textfile collector

[Service]
Type=oneshot
ExecStart=/usr/local/bin/collect_kernel_error_metrics.sh
EOF

cat >/etc/systemd/system/kernel-error-metrics.timer <<'EOF'
[Unit]
Description=Run kernel error metrics collector every 60s

[Timer]
OnBootSec=30s
OnUnitActiveSec=60s
AccuracySec=1s

[Install]
WantedBy=timers.target
EOF

systemctl daemon-reload
systemctl enable --now kernel-error-metrics.timer
systemctl list-timers --no-pager | grep kernel-error-metrics || true

验证：

curl -fsS http://192.168.22.18:9100/metrics | grep -E '^kernel_error_events_10m|^kernel_error_scrape_time_seconds' || true

D3.（可选）在 192.168.22.18 部署 smartctl_exporter（磁盘健康）

说明：如果你的“UFS 2.1”设备不支持 SMART/health，这一步可能拿不到有效数据；但做了不亏（能拿到就直接中大奖）。

apt-get update
apt-get install -y smartmontools

export VER="0.12.0"
curl -fsSL -o /tmp/smartctl_exporter.tar.gz "https://github.com/prometheus-community/smartctl_exporter/releases/download/v${VER}/smartctl_exporter-${VER}.linux-amd64.tar.gz"
tar -C /tmp -xzf /tmp/smartctl_exporter.tar.gz
install -m 0755 /tmp/smartctl_exporter-${VER}.linux-amd64/smartctl_exporter /usr/local/bin/smartctl_exporter

useradd --system --no-create-home --shell /usr/sbin/nologin smartctl-exp || true

cat >/etc/systemd/system/smartctl_exporter.service <<'EOF'
[Unit]
Description=Prometheus Smartctl Exporter
After=network-online.target
Wants=network-online.target

[Service]
User=smartctl-exp
Group=smartctl-exp
ExecStart=/usr/local/bin/smartctl_exporter --web.listen-address=:9633
Restart=on-failure
RestartSec=2

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now smartctl_exporter

验证：

curl -fsS http://192.168.22.18:9633/metrics | head

D4. 在 192.168.22.12（PVE）用 LXC 部署 Prometheus + Grafana + blackbox_exporter（推荐）

你说 .12 也是 PVE 主机，那就别在宿主机上堆 Docker 了：直接建一个 LXC 容器跑监控栈，数据/配置独立、可迁移、也更符合“排查期可控变更”的原则。

D4.1 在 PVE（.12）创建一个 Debian LXC 容器

你可以用 PVE Web UI 创建，也可以用命令行。下面是命令行示例（按你的环境替换、；监控 LXC IP 固定为 192.168.22.19）：

# 在 PVE 宿主机 192.168.22.12 执行
pct create  local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst \
  --hostname monitoring \
  --cores 2 --memory 2048 --swap 512 \
  --rootfs local-lvm:8 \
  --net0 name=eth0,bridge=vmbr0,ip=192.168.22.19/24,gw= \
  --unprivileged 1

# 让容器内 systemd 工作更顺滑
pct set  -features keyctl=1,nesting=1

pct start

这篇文章里我们把监控 LXC 的 IP 固定为：192.168.22.19。

D4.2 在容器内安装 Prometheus（systemd）

进入容器：

pct exec  -- bash

在容器内执行：

apt-get update
apt-get install -y ca-certificates curl tar

useradd --system --no-create-home --shell /usr/sbin/nologin prometheus || true
mkdir -p /etc/prometheus /var/lib/prometheus
chown -R prometheus:prometheus /etc/prometheus /var/lib/prometheus

export VER="2.54.1"
curl -fsSL -o /tmp/prometheus.tar.gz "https://github.com/prometheus/prometheus/releases/download/v${VER}/prometheus-${VER}.linux-amd64.tar.gz"
tar -C /tmp -xzf /tmp/prometheus.tar.gz
install -m 0755 /tmp/prometheus-${VER}.linux-amd64/prometheus /usr/local/bin/prometheus
install -m 0755 /tmp/prometheus-${VER}.linux-amd64/promtool /usr/local/bin/promtool
cp -r /tmp/prometheus-${VER}.linux-amd64/consoles /etc/prometheus/
cp -r /tmp/prometheus-${VER}.linux-amd64/console_libraries /etc/prometheus/
chown -R prometheus:prometheus /etc/prometheus

创建 /etc/prometheus/prometheus.yml（抓 .18 的 exporter + 主动探测；DNS 用 .54 的 AdGuardDNS）：

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: "minisforum-node"
    static_configs:
      - targets: ["192.168.22.18:9100"]

  - job_name: "minisforum-smartctl"
    static_configs:
      - targets: ["192.168.22.18:9633"]

  - job_name: "blackbox-icmp"
    metrics_path: /probe
    params:
      module: [icmp]
    static_configs:
      - targets:
          - 192.168.22.18
          - 192.168.22.54
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9115

  - job_name: "blackbox-tcp"
    metrics_path: /probe
    params:
      module: [tcp_connect]
    static_configs:
      - targets:
          - 192.168.22.18:22
          - 192.168.22.18:9100
          - 192.168.22.54:53
          - 192.168.22.54:3000
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9115

创建 systemd 服务：

cat >/etc/systemd/system/prometheus.service <<'EOF'
[Unit]
Description=Prometheus
After=network-online.target
Wants=network-online.target

[Service]
User=prometheus
Group=prometheus
ExecStart=/usr/local/bin/prometheus \
  --config.file=/etc/prometheus/prometheus.yml \
  --storage.tsdb.path=/var/lib/prometheus \
  --storage.tsdb.retention.time=30d
Restart=on-failure
RestartSec=2

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now prometheus
systemctl status prometheus --no-pager

D4.3 在容器内安装 blackbox_exporter（systemd）

useradd --system --no-create-home --shell /usr/sbin/nologin blackbox || true
mkdir -p /etc/blackbox_exporter
chown -R blackbox:blackbox /etc/blackbox_exporter

export VER="0.25.0"
curl -fsSL -o /tmp/blackbox.tar.gz "https://github.com/prometheus/blackbox_exporter/releases/download/v${VER}/blackbox_exporter-${VER}.linux-amd64.tar.gz"
tar -C /tmp -xzf /tmp/blackbox.tar.gz
install -m 0755 /tmp/blackbox_exporter-${VER}.linux-amd64/blackbox_exporter /usr/local/bin/blackbox_exporter

cat >/etc/blackbox_exporter/blackbox.yml <<'EOF'
modules:
  icmp:
    prober: icmp
    timeout: 5s

  tcp_connect:
    prober: tcp
    timeout: 5s
EOF

chown -R blackbox:blackbox /etc/blackbox_exporter

cat >/etc/systemd/system/blackbox_exporter.service <<'EOF'
[Unit]
Description=Prometheus Blackbox Exporter
After=network-online.target
Wants=network-online.target

[Service]
User=blackbox
Group=blackbox
ExecStart=/usr/local/bin/blackbox_exporter \
  --config.file=/etc/blackbox_exporter/blackbox.yml \
  --web.listen-address=:9115
Restart=on-failure
RestartSec=2

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now blackbox_exporter
systemctl status blackbox_exporter --no-pager

D4.4 在容器内安装 Grafana（systemd）

不要把 Grafana 的 admin 密码写进任何配置文件/仓库。建议安装完后手动设置。

apt-get install -y apt-transport-https software-properties-common wget gpg
mkdir -p /etc/apt/keyrings
wget -qO- https://apt.grafana.com/gpg.key | gpg --dearmor >/etc/apt/keyrings/grafana.gpg
echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" >/etc/apt/sources.list.d/grafana.list
apt-get update
apt-get install -y grafana

systemctl enable --now grafana-server
systemctl status grafana-server --no-pager

设置 admin 密码（在容器内执行）：

grafana-cli admin reset-admin-password

D4.5 访问地址与最小验证

Prometheus：http://192.168.22.19:9090
Grafana：http://192.168.22.19:3000
blackbox_exporter：http://192.168.22.19:9115

最小验证：

curl -fsS "http://192.168.22.19:9090/-/ready"
curl -fsS "http://192.168.22.19:9115/probe?module=icmp&target=192.168.22.18" | head

D5. Grafana 面板与关键观察点（对应 H1~H5）

你不需要“花里胡哨的大盘”。就盯下面这些就够了：

H1 过热/降频：
- CPU 温度（如果可见）：node_thermal_zone_temp 或 node_hwmon_temp_celsius
- CPU load/iowait：node_load1、rate(node_cpu_seconds_total{mode="iowait"}[5m])
H2 供电/复位：
- uptime/重启点：node_boot_time_seconds（突然变化 = reboot）
- blackbox 探测：probe_success{job=~"blackbox-.*"}
H3 存储/控制器异常：
- 关键：kernel_error_events_10m（你自己定义的）
- IO time：rate(node_disk_io_time_seconds_total[5m])
- 文件系统只读（如果发生）：node_filesystem_readonly
H4 资源耗尽：
- 内存：node_memory_MemAvailable_bytes
- FD（如果启用）：node_filefd_allocated/node_filefd_maximum（视 exporter 版本）
H5 驱动/省电策略/网卡 reset：
- 网络错误：rate(node_network_receive_errs_total[5m])、rate(node_network_transmit_errs_total[5m])
- 同样看 kernel_error_events_10m 的变化点

D6. 告警规则（把时间戳钉死）

你至少要有三条告警（其余都是锦上添花）：

机器不可达（icmp probe 失败）
DNS 端口不可达（tcp probe 到 53 失败）
内核/IO 错误突增（kernel_error_events_10m 超过阈值）

告警接收渠道先别纠结，先让 Prometheus “能触发告警”这件事成立；否则你复现那一刻还是会错过。

尝试 E：在 192.168.22.18 用 LXC 部署 AdGuardDNS（IP 固定为 192.168.22.54）+ DNS 真实查询探测

目标：把 DNS 业务从宿主机里隔离出来，并且把 DNS 的 IP 固定到 192.168.22.54，这样监控/告警的 target 不会因为容器漂移而失效。
重点：排查“宿主机是否先死”，所以 nodeexporter / 自定义 IO 错误计数 / smartctlexporter 仍然部署在宿主 .18；DNS 服务放到容器里只是为了更可控地观测“业务侧”。

E0. 在 PVE（.18）创建 AdGuardDNS 的 LXC 容器（192.168.22.54）

示例（按你的环境替换、）：

# 在 PVE 宿主机 192.168.22.18 执行
pct create  local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst \
  --hostname adguarddns \
  --cores 1 --memory 1024 --swap 256 \
  --rootfs local-lvm:4 \
  --net0 name=eth0,bridge=vmbr0,ip=192.168.22.54/24,gw= \
  --unprivileged 1

pct set  -features keyctl=1,nesting=1
pct start

E1. 在容器内安装 AdGuard Home（作为 AdGuardDNS）

进入容器：

pct exec  -- bash

在容器内执行（固定版本，排查期可追溯）：

apt-get update
apt-get install -y ca-certificates curl tar

export VER="0.107.57"
curl -fsSL -o /tmp/adguardhome.tar.gz "https://github.com/AdguardTeam/AdGuardHome/releases/download/v${VER}/AdGuardHome_linux_amd64.tar.gz"
tar -C /opt -xzf /tmp/adguardhome.tar.gz

/opt/AdGuardHome/AdGuardHome -s install
systemctl status AdGuardHome --no-pager

访问初始化页面（首次配置）：

管理口：http://192.168.22.54:3000
DNS：192.168.22.54:53（UDP/TCP）

你要把内网客户端 DNS 指向 192.168.22.54。如果你有 DHCP/路由器下发 DNS，就统一从那里改，别一个个设备手动改。

E1. DNS 真实查询探测（不靠 blackbox 的“端口可达”，直接用 `dig` 验证解析链路）

做法：在 192.168.22.19（监控端 LXC）定时执行 dig，把“成功/失败、延迟”推送到 Pushgateway。这一步不依赖 AdGuard 管理口账号密码，可观测性更干净。

在监控端（.12 的 monitoring LXC）里可选安装 Pushgateway（systemd）：

apt-get update
apt-get install -y ca-certificates curl tar

useradd --system --no-create-home --shell /usr/sbin/nologin pushgateway || true
mkdir -p /etc/pushgateway /var/lib/pushgateway
chown -R pushgateway:pushgateway /etc/pushgateway /var/lib/pushgateway

export VER="1.10.0"
curl -fsSL -o /tmp/pushgateway.tar.gz "https://github.com/prometheus/pushgateway/releases/download/v${VER}/pushgateway-${VER}.linux-amd64.tar.gz"
tar -C /tmp -xzf /tmp/pushgateway.tar.gz
install -m 0755 /tmp/pushgateway-${VER}.linux-amd64/pushgateway /usr/local/bin/pushgateway

cat >/etc/systemd/system/pushgateway.service <<'EOF'
[Unit]
Description=Prometheus Pushgateway
After=network-online.target
Wants=network-online.target

[Service]
User=pushgateway
Group=pushgateway
ExecStart=/usr/local/bin/pushgateway --web.listen-address=:9091
Restart=on-failure
RestartSec=2

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now pushgateway
systemctl status pushgateway --no-pager

Prometheus 增加一个 scrape（在同一台监控容器里就用 127.0.0.1）：

- job_name: "pushgateway"
  honor_labels: true
  static_configs:
    - targets: ["127.0.0.1:9091"]

在监控端新增探测脚本（把固定为 192.168.22.54）：

cat >/opt/monitoring/dns_probe_push.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

DNS_IP="192.168.22.54"
NAME="www.baidu.com"
PUSH_URL="http://127.0.0.1:9091/metrics/job/dns_probe/instance/${DNS_IP}"

OUT="$(dig +tries=1 +time=2 +stats @"${DNS_IP}" "${NAME}" A 2>/dev/null || true)"

# success=1 if we got an ANSWER section with at least one A record
if echo "${OUT}" | grep -qE '^;; ANSWER SECTION:'; then
  SUCCESS=1
else
  SUCCESS=0
fi

# Parse query time in ms from "Query time: 12 msec"
LAT_MS="$(echo "${OUT}" | awk -F': ' '/^;; Query time:/{print $2}' | awk '{print $1}' || true)"
LAT_MS="${LAT_MS:-0}"

cat </dev/null
# TYPE dns_probe_success gauge
dns_probe_success ${SUCCESS}
# TYPE dns_probe_latency_ms gauge
dns_probe_latency_ms ${LAT_MS}
METRICS
EOF

chmod +x /opt/monitoring/dns_probe_push.sh

用 cron/systemd timer 每 15s~60s 跑一次（排查期建议 15s）：

crontab -e
# 每分钟 4 次
*/1 * * * * /opt/monitoring/dns_probe_push.sh
*/1 * * * * sleep 15; /opt/monitoring/dns_probe_push.sh
*/1 * * * * sleep 30; /opt/monitoring/dns_probe_push.sh
*/1 * * * * sleep 45; /opt/monitoring/dns_probe_push.sh

这一步的意义：当你复现“DNS 不通”时，你能立刻看到是 解析延迟逐步升高、还是 直接成功率掉到 0，并且与宿主机 iowait/错误计数 对齐。

E2.（可选）AdGuard Home 业务指标（需要管理口凭据，务必不要进仓库）

如果你确实想看 AdGuard 自身的统计（blocked/allowed/qps/upstream latency），可以在 .12 上跑一个 AdGuard exporter，读取 AdGuard 的管理 API 再暴露成 Prometheus 指标。

关键原则：

凭据只放在 .12 本机的 root-only 文件里（例如 /opt/monitoring/secrets/adguard.env，chmod 600）
不要写进本文仓库、更不要写进 compose 文件

（这里不强制指定 exporter，你用哪个就以其文档为准；排查阶段我更看重 E1 的 DNS 真实探测 + 宿主机指标。）

验证标准（这套监控是否“抓得住问题”）

连续运行：至少 7 天（你说通常 1 天+ 触发，7 天才有统计意义）
当复现发生时必须能回答：
- 先断的是 icmp 还是 tcp/53？
- kernel_error_events_10m 是否在故障前 0~10 分钟上升？
- iowait 是否先飙升（cpu iowait/disk io_time）？
- node_boot_time_seconds 是否变化（是否实际重启）？
- dns_probe_success/dns_probe_latency_ms 在故障前是“逐步变坏”还是“瞬断”？

日常排查：PVE 跨 VLAN Ping 不通（默认网关指错 + OpenWrt LAN 区误开 NAT）

cheverjonathan@gmail.com (Chenwei Jiang) — Fri, 05 Dec 2025 00:00:00 GMT

这是一篇“日常排查记录”。只写可验证的事实、证据链和最小修复，不写玄学。

TL;DR

现象：跨 VLAN ping 超时；目标机本地抓包却能看到 echo reply 已经发出。
根因 1（决定性）：PVE 刻意以 OpenWrt（192.168.22.13）作为默认网关做 QoS/流量处理，但 没有为其它内网 VLAN 配置显式路由，导致回程流量走默认路由“拐进” OpenWrt，主网关看不到 reply（典型非对称路径）。
根因 2（放大器）：OpenWrt 把 lan zone 开了 masq=1，把内网互访流量也 SNAT 改源成 192.168.22.13，让路径与会话变得不可预期。
修复：
- 保留 PVE 默认网关为 OpenWrt（192.168.22.13），但为内网网段（如 192.168.11.0/24、192.168.183.0/24）添加静态路由指向主网关（192.168.22.1）
- OpenWrt 关闭 lan zone 的 masq
预防：内网只路由不 NAT；如果默认网关必须指向旁路（QoS/代理），就把“内网路由”和“公网默认路由”明确拆开；用 tcpdump + ip route get 走 SOP。

背景（拓扑与角色）

家庭网络是多 VLAN：

Cloud Gateway Fiber（主网关）：负责三层路由与 VLAN 间转发
- VLAN11：192.168.11.0/24（GW 192.168.11.1）
- VLAN22（PVE/实验）：192.168.22.0/24（GW 192.168.22.1）
- VLAN183：192.168.183.0/24（GW 192.168.183.1）
OpenWrt（旁路/二级网关）：192.168.22.13/24（br-lan，fw3 + iptables，带旁路代理脚本）
PVE：192.168.22.12/24（vmbr0）
测试机：
- 192.168.183.235（VLAN183）
- 192.168.11.29（VLAN11）

简化数据路径（正常设计）应该是：

VLAN183 ↔ VLAN22：都由 Fiber 做三层转发
OpenWrt 如果要做“上网/代理出口”，应该只在真正的 wan 出口做 NAT/代理，而不是改写内网互访流量

用 shell 画出拓扑与数据路径（ASCII）

下面这个脚本不会改任何配置，只是把拓扑和两条关键路径打印出来，方便读者“看见数据怎么走”：

#!/usr/bin/env bash
set -euo pipefail

# Print the topology and the two paths (bad vs fixed).
cat <<'EOF'

                    +------------------------------+
                    |   Cloud Gateway Fiber (L3)   |
                    |   VLAN11: 192.168.11.1       |
                    |   VLAN22: 192.168.22.1       |
                    |   VLAN183: 192.168.183.1     |
                    +---------------+--------------+
                                    |
                                  VLAN22
                                    |
                   +----------------+----------------+
                   |                                 |
        +----------v-----------+          +----------v-----------+
        |  OpenWrt (side GW)   |          |        PVE           |
        |  192.168.22.13       |          |  192.168.22.12       |
        |  QoS / traffic mgmt  |          |  vmbr0               |
        +----------------------+          +----------------------+

Clients:
  VLAN183 host: 192.168.183.235
  VLAN11  host: 192.168.11.29

Problem #1 (before):
  192.168.183.235 -> Fiber -> PVE
  PVE reply -> (default gw) OpenWrt -> [NAT/proxy/unknown] -> ???   (Fiber never sees the reply)

Fix idea:
  Keep PVE default gw = OpenWrt (for QoS),
  but route internal subnets via Fiber.

Problem #2 (amplifier):
  OpenWrt LAN masquerade (SNAT) rewrites east-west traffic,
  making internal routing/session behavior unpredictable.

EOF

事件与影响

事件 1：VLAN183 ping 不通 PVE

发起端：192.168.183.235 执行 ping 192.168.22.12 一直超时
PVE 本机抓包能看到：
- ICMP echo request 到达
- ICMP echo reply 发出
但在主网关 Fiber（br22/br0）抓包只看到 request，看不到 reply

这意味着：PVE 的 reply 根本没走回 Fiber —— 问题不是“主网关丢包”，而是“回程路径压根没经过主网关”。

事件 2：修复后，VLAN11 仍 ping 不通 PVE

192.168.11.29 ping 不通 192.168.22.12
但可以 ping 通 192.168.22.13（OpenWrt）

这暴露出第二个问题：OpenWrt 的 NAT 行为在破坏内网互访的可预期性。

排查过程（证据链）

1）先证明主网关本身可用

在 Fiber 上验证：

Fiber 能 ping 通 192.168.183.235 与 192.168.22.12
ip route 显示 192.168.22.0/24 与 192.168.183.0/24 为直连

结论：Fiber 的基础三层与直连网段没问题。

2）逐跳抓包：定位“reply 消失在哪一跳”

抓包观察到：

PVE 本机：request/reply 都存在（说明 PVE 会回包）
Fiber 的 br22/br0：只有 request，没有 reply

结论：reply 在到达 Fiber 之前就“拐走了”。

3）用 `ip route get` 让路由决策自己说话

在 PVE 上：

ip route 显示默认路由：default via 192.168.22.13 dev vmbr0
ip route get 192.168.183.235 显示：via 192.168.22.13

关键结论（问题 1 根因）：PVE 没有到其它内网 VLAN 的显式路由，因此对 192.168.183.0/24 的回包自然走默认路由交给 OpenWrt。只要 OpenWrt 这边出现 NAT/代理/错误路由中的任意一种，主网关就可能完全看不到 reply。

这就是典型的非对称路由：

正向：183 → Fiber → 22 → PVE（正常）
回程：PVE → OpenWrt → （NAT/代理/错误路由/黑盒）（不可控）

4）验证 OpenWrt 的防火墙实现与 NAT 配置

为了排除“背后还有一套规则系统”的不确定性，确认 OpenWrt 是 fw3 + iptables（无 nftables），然后检查到：

lan zone 开启了 masq='1'

关键结论（问题 2 根因）：OpenWrt 把内网互访也做了 SNAT，源地址被改成 192.168.22.13，会让跨 VLAN 的会话与回程路径变得混乱（尤其叠加旁路代理/策略导流时）。

解决方法（最小改动）

修复 1：保留默认网关为 OpenWrt，但把“内网路由”显式指回主网关 Fiber

需求前提：PVE 默认网关必须是 192.168.22.13（OpenWrt），因为你要在 OpenWrt 上做 QoS/流量处理；那就别动默认路由，改成“内网网段走 Fiber，其他流量仍走 OpenWrt”。最简单且最可控的做法是给 PVE 加静态路由。

临时验证（示例只覆盖本次出现问题的 VLAN11/VLAN183，可按你的实际 VLAN 增加）：

# Keep default via OpenWrt for QoS / traffic management
# default via 192.168.22.13

# Route internal VLANs via the primary L3 gateway (Fiber)
ip route replace 192.168.183.0/24 via 192.168.22.1 dev vmbr0
ip route replace 192.168.11.0/24  via 192.168.22.1 dev vmbr0

验证思路：

ip route get 192.168.183.235 应该显示 via 192.168.22.1
在 Fiber 的 br22/br0 上应该能抓到 echo reply

持久化（Proxmox 常见在 /etc/network/interfaces 的 vmbr0，用 post-up 写死最直接）：

post-up ip route replace 192.168.183.0/24 via 192.168.22.1 dev vmbr0
post-up ip route replace 192.168.11.0/24  via 192.168.22.1 dev vmbr0
post-down ip route del 192.168.183.0/24 via 192.168.22.1 dev vmbr0 || true
post-down ip route del 192.168.11.0/24  via 192.168.22.1 dev vmbr0 || true

验证：

Fiber 的 br22/br0 能抓到 echo reply
192.168.183.235 → ping 192.168.22.12 恢复

修复 2：关闭 OpenWrt 的 `lan` zone NAT

uci set firewall.@zone[0].masq='0'
uci commit firewall
/etc/init.d/firewall restart

验证：

192.168.11.29 → ping 192.168.22.12 恢复
内网互访源 IP 保持真实，后续排障和访问控制都更简单

预防措施（别再制造“网络玄学”）

内网之间只路由，不做 NAT
- lan / 内网 zones：masq=0
- 只有真正的公网出口（wan）才 masq=1
如果默认网关必须指向旁路（QoS/代理），就把路由拆清楚
- 默认路由可以指向 OpenWrt，但 所有内网网段必须有显式静态路由 指回主网关（或用策略路由按目的网段分流）
- 原则很简单：内网东西向流量走“可预期的三层”，不要让它掉进 NAT/代理黑盒
固定排障 SOP（Standard Operating Procedure：标准排查流程）
- 这句话的意思是：遇到类似“跨 VLAN ping 不通”的问题，不要靠猜，按同一套步骤用证据把问题钉死。
- 第一步：先用抓包回答 3 个问题：request 到没到？目标回没回？reply 消失在哪一跳？
  - 在目标机上：tcpdump -ni vmbr0 icmp
  - 在主网关上（目标 VLAN 口 / 发起 VLAN 口）：tcpdump -ni br22 icmp、tcpdump -ni br0 icmp
- 第二步：用路由决策输出替代“想当然”
  - 在 PVE 上：ip route + ip route get 192.168.183.235
  - 在 OpenWrt/Fiber 上：ip route get 192.168.183.235（确认下一跳到底是谁）
- 第三步：优先把数据路径变简单
  - 内网互访先恢复为“纯路由、真实源地址、可预期回程”，再去叠加 QoS/代理/策略导流
旁路代理要“明确排除内网网段”
- 内网网段不应被透明导入 VPN/隧道
- 先保证纯路由可用，再谈代理与加速

一句话教训

当你觉得“ICMP 在搞幽灵”的时候，大概率不是协议栈坏了，而是你把默认网关/NAT 配成了黑盒。

个人如何正确使用 Claude

cheverjonathan@gmail.com (Chenwei Jiang) — Wed, 17 Sep 2025 00:00:00 GMT

随着 AI 助手越来越深入地融入我们的日常工作流程，理解如何正确利用 Claude 这样的工具可以显著提升你的生产力和决策质量。这份全面指南将帮助你最大化从 Claude 获得的价值，同时保持良好的使用习惯和现实的期望。

理解 Claude 的核心优势

在深入具体用例之前，了解 Claude 擅长什么是至关重要的：

1. 文本分析和处理

Claude 可以快速分析、总结和从大量文本中提取洞察。无论你在处理研究论文、会议记录还是技术文档，Claude 都能帮助你识别关键点和模式。

2. 创意和技术写作

从起草邮件到编写代码，Claude 可以协助各种形式的内容创作，同时保持你的个人声音和风格偏好。

3. 问题解决和研究

Claude 可以帮助将复杂问题分解为可管理的组件，并提供寻找解决方案的结构化方法。

4. 学习和解释

需要解释什么吗？Claude 可以根据你的专业水平和学习风格调整解释方式。

基本最佳实践

从清晰、具体的提示开始

好的示例： "帮我写一封专业邮件，礼貌地拒绝周四下午的会议请求，建议下周的替代时间，并保持合作的语调。"

糟糕示例： "帮我写封邮件。"

你提供的上下文和具体性越多，Claude 就越能针对你的需求定制回应。

迭代和完善

不要期望第一次就得到完美的结果。使用后续提示来：

要求澄清或扩展特定要点
请求不同的方法或风格
提供对什么有效、什么无效的反馈

验证重要信息

虽然 Claude 知识渊博，但总是要验证关键事实，特别是涉及：

医疗或法律建议
财务决策
时事或快速变化的信息
技术规格或要求

个人实用案例

职业发展

邮件沟通：

起草适当语调的专业邮件
总结冗长的邮件链
为非技术受众翻译复杂的技术概念

文档创建：

创建结构化报告和演示文稿
撰写求职申请材料
制定项目计划和时间表

学习和技能发展：

获得复杂主题的解释
练习面试问题
学习新的编程语言或框架

个人生产力

研究和规划：

比较重大购买的选项
规划旅行行程
研究个人感兴趣的话题

创意项目：

为兴趣爱好或副业项目头脑风暴
获得创意写作的反馈
规划活动或庆祝活动

日常生活管理：

创建膳食计划和购物清单
组织和优先处理任务
起草重要的个人信件

高级技巧

上下文管理

在对话开始时提供相关背景信息：

你的角色和专业水平
你工作的具体环境或约束
你的目标和成功标准

思维链提示

对于复杂问题，要求 Claude "逐步思考"或"解释你的推理"。这通常会产生更全面和准确的回应。

角色扮演场景

要求 Claude 承担特定角色或观点：

"作为高级软件工程师审查我的代码"
"像不熟悉这个话题的人那样回应"
"从潜在客户的角度看"

模板创建

为重复性任务开发可重用的提示：

会议总结模板
邮件回复框架
问题解决方法论

Claude 不能做什么

理解局限性对有效使用至关重要：

实时信息

Claude 的训练有知识截止时间，无法访问当前网络信息或实时数据。

个人数据访问

Claude 无法访问你的个人文件、邮件或私人信息，除非你在对话中明确分享。

执行操作

Claude 无法直接在外部系统中执行操作、发送邮件或代表你进行购买。

替代人类判断

虽然 Claude 可以提供见解和建议，但重要决策应始终涉及人类判断和专业知识。

维护隐私和安全

信息分享

避免分享敏感个人信息（社保号、密码、财务详情）
谨慎处理专有或机密商业信息
在寻求特定场景帮助时考虑匿名化数据

数据保留

了解平台的数据保留政策
不要依赖 Claude 在单独对话之间记住信息
保留重要见解或决策的自己记录

建立有效工作流程

1. 定义你的用例

识别 Claude 可以为你的日常工作增加价值的具体、重复性任务。

2. 开发标准提示

为你最常见的用例创建和完善提示模板。

3. 设定现实期望

理解 Claude 是增强你能力的工具，而不是替代你的思考和判断。

4. 衡量影响

跟踪 Claude 的使用如何影响你的生产力和工作质量。

5. 保持更新

AI 能力发展迅速。及时了解新功能和最佳实践。

避免常见陷阱

过度依赖

不要在基本思考或决策制定上变得依赖 Claude。用它来增强你的能力，而不是替代它们。

提示懒惰

避免模糊或最小化的提示。在清晰沟通上投入时间会产生更好的结果。

忽略上下文

记住为复杂或专业主题提供充分的上下文。

假设完美

总是审查和验证 Claude 的输出，特别是对于重要任务。

结论

当明智和战略性地使用时，Claude 可以成为专业和个人环境中的强大盟友。成功的关键在于理解其优势和局限性，发展清晰的沟通模式，并保持适当的怀疑和验证实践。

从简单的用例开始，逐步建立你的技能，并始终记住 Claude 在增强你的人类智能而非试图替代它时最为有效。通过实践和正确的方法，你会发现 Claude 成为你个人和专业工具包中的宝贵工具。

记住：目标不是将 Claude 用于一切，而是以正确的方式将其用于正确的事情。

在这个 AI 时代，你真的会敲代码嘛？！！！

cheverjonathan@gmail.com (Chenwei Jiang) — Fri, 15 Aug 2025 00:00:00 GMT

最近 AI 实在是太凶了，大家都沉迷于对 AI 发号施令，然后发现一大堆报错的代码被写出来。（事实上你可能自己也看不懂 AI 写的代码）。

当然懂 AI 的人，晓得使用 Prompt Engineering 嘛。不过我还是想巩固一下软件工程的基本功。

面向对象、设计原则、设计模式、编程规范、重构。

编程范式/编程风格

主流的编程范式/编程风格有三种：

面向过程
面向对象
函数式编程

其中，面向对象这种编程风格又是其中最主流的。（现在比较流行的编程语言大部分都是面向对象编程语言）。

设计原则

解释定义：代码设计的经验总结。

原则一般听起来很抽象，定义描述比较模糊。

难点：需要掌握设计初衷、能够解决哪些编程问题，有哪些应用场景。

常用的设计原则如下：

SOLID 原则
也许你会有疑问，为什么就只有 SOLID 原则会有五个额外的类似于子原则的东西。
咳咳，我也有这个问题，所以我查了，查到了。
SOLID 被称为面向对象设计的基石，是因为它提供了一套具体而非抽象的工具，用于解决软件开发中的实际问题。
每个子原则针对的是不同层面的设计缺陷。它之所以特殊，恰恰是因为它不是一个模糊的单一规则，而是五个具体、可操作的设计原则的组合
- 单一职责原则 (Single Responsibility Principle)
- 开闭原则 (Open/Closed Principle)
- 里氏替换原则 (Liskov Substitution Principle)
- 接口隔离原则 (Interface Segregation Principle)
- 依赖反转原则 (Dependency Inversion Principle)
- 简洁设计原则
KISS原则 (Keep It Simple, Stupid)
DRY原则 (Don't Repeat Yourself)
YAGNI原则 (You Aren't Gonna Need It)
LOD 法则

设计模式

解释定义：针对于软件开发中经常遇到的一些设计问题，总结出来的一套解决方案或者设计思路。

大部分设计模式要解决的都是代码的可扩展性问题。

难点：了解它们都能解决哪些问题，掌握典型的应用场景，并且懂得不过度应用。

有哪些：经典的设计模式有 23 种。

随着编程语言的演进，

一些设计模式（比如 Singleton）也随之过时，甚至成了反模式；

一些则被内置在编程语言中（比如 Iterator）；

还有一些新的设计模式诞生（比如 Monostate）。

23 种经典的设计模式，可以分为三大类：创建型、结构型、行为型。

创建型

常用的有：单例模式、工厂模式（工厂方法和抽象工厂）、建造者模式。

不常用的有：原型模式。

结构型

常用的有：代理模式、桥接模式、装饰者模式、适配器模式。

不常用的有：门面模式、组合模式、享元模式。

行为型

常用的有：观察者模式、模板模式、策略模式、职责链模式、迭代器模式、状态模式。

不常用的有：访问者模式、备忘录模式、命令模式、解释器模式、中介模式。

编程规范

定义解释：主要解决的是代码的可读性问题。相对于设计原则、设计模式，更加具体、更加偏重代码细节。即便你可能对设计原则不熟悉、对设计原则不了解，最起码掌握基本的编码规范。

比如，如何给变量、类、函数命名，如何写代码注释，函数不宜过长、参数不能过多等。

这一块有很多经典的书可以去看就完事了，《重构》、《代码大全》、《代码整洁之道》等。

这一块每条编码规范都很简单、明确，记一下就行了，只需要照着来就可以。不像设计原则，需要融入很多个人的理解和思考。

重构

只要工程一直在进行，这个项目一直有人，那么软件就会需要持续迭代，那么新的功能需求一定会推动着之前的需求进行代码重构，这是保证代码质量不下降的有效手段。有效避免代码腐化到无可救药的地步。

而重构的工具，就是之前提到的所有的那些，编程范式、设计原则、设计模式、编程规范。

虽然使用设计模式可以提高代码的可扩展性，但过度不恰当地使用，也会增加代码的复杂度，影响代码的可读性。

在开发初期，除非特别必须，我们一定不要过度设计，应用复杂的设计模式。

而是当代码出现问题的时候，我们再针对问题，应用原则和模式进行重构。

这样就能有效避免前期的过度设计。

务必掌握的知识点

如下：

重构的目的（why）、对象（what）、时机（when）、方法（how）；
保证重构不出错的技术手段：单元测试和代码的可测试性；
两种不同规模的重构：大重构（大规模高层次）和小重构（小规模低层次）。

五者之间的联系

关于面向对象、设计原则、设计模式、编程规范和代码重构，这五者的关系如下：

面向对象编程因为其丰富的特性（封装、抽象、继承、多态），可以实现很多复杂的设计思路，是很多设计原则、设计模式等编码实现的基础。
设计原则是指导我们代码设计的一些经验总结，对于某些场景下，是否应该应用某种设计模式，具有指导意义。比如，“开闭原则” 是很多设计模式（策略、模版等）的指导原则。
设计模式是针对软件开发中经常遇到的一些设计问题，总结出来的一套解决方案或者设计思路。应用设计模式的主要目的是提高代码的可扩展性。从抽象程度上来讲，设计原则比设计模式更抽象。设计模式更加具体、更加可执行。
编程规范主要解决的是代码的可读性问题。编程规范相对于设计原则、设计模式，更加具体、更加偏重代码细节、更加能落地。持续的小重构依赖的理论基础主要就是编程规范。

事实上这篇文章主要的作用就是，为了编写高质量代码这一件事。当追本溯源，之后很多事情怎么做，代码怎么实现，就清楚了。

mindmap
  root((编写高质量代码))
    面向对象
      封装、抽象、继承、多态
      面向对象编程 VS 面向过程编程
      面向对象分析、设计、编程
      接口 VS 抽象类
      基于接口而非实现编程
      多用组合少用继承
      贫血模型和充血模型
    设计原则
      SOLID 原则
        SRP 单一职责
        OCP 开闭
        LSP 里氏替换
        ISP 接口隔离
        DIP 依赖倒置
      其他
        DRY 原则
        KISS 原则
        YAGNI 原则
        LOD 法则
    编程规范
      20 条最快速改善代码质量的编程规范
    代码重构
      目的、对象、时机、方法
      单元测试与代码可测试性
      大重构（大规模高层次）
      小重构（小规模低层次）
    设计模式
      创建型
        常用
          单例模式
          工厂模式（工厂方法与抽象工厂）
          建造者模式
        不常用
          原型模式
      结构型
        常用
          代理模式
          桥接模式
          装饰者模式
          适配器模式
        不常用
          门面模式
          组合模式
          享元模式
      行为型
        常用
          观察者模式
          模板模式
          策略模式
          责任链模式
          迭代器模式
          状态模式
        不常用
          访问者模式
          备忘录模式
          命令模式
          解释器模式
          中介者模式

mindmap
  root((编写高质量代码))
    面向对象
      封装、抽象、继承、多态
      面向对象编程 VS 面向过程编程
      面向对象分析、设计、编程
      接口 VS 抽象类
      基于接口而非实现编程
      多用组合少用继承
      贫血模型和充血模型
    设计原则
      SOLID 原则
        SRP 单一职责
        OCP 开闭
        LSP 里氏替换
        ISP 接口隔离
        DIP 依赖倒置
      其他
        DRY 原则
        KISS 原则
        YAGNI 原则
        LOD 法则
    编程规范
      20 条最快速改善代码质量的编程规范
    代码重构
      目的、对象、时机、方法
      单元测试与代码可测试性
      大重构（大规模高层次）
      小重构（小规模低层次）
    设计模式
      创建型
        常用
          单例模式
          工厂模式（工厂方法与抽象工厂）
          建造者模式
        不常用
          原型模式
      结构型
        常用
          代理模式
          桥接模式
          装饰者模式
          适配器模式
        不常用
          门面模式
          组合模式
          享元模式
      行为型
        常用
          观察者模式
          模板模式
          策略模式
          责任链模式
          迭代器模式
          状态模式
        不常用
          访问者模式
          备忘录模式
          命令模式
          解释器模式
          中介者模式

ps：再附上一大堆关键词，可以慢慢看。

系统架构原则高内聚低耦合原则最小知识原则（迪米特法则）组合优于继承原则关注点分离原则契约式设计原则云原生设计原则弹性设计原则可观测性原则不可变基础设施原则服务自治原则声明式配置原则安全设计原则纵深防御原则最小权限原则安全默认配置原则职责分离原则失效安全原则

老系统的性能优化改造

cheverjonathan@gmail.com (Chenwei Jiang) — Mon, 30 Jun 2025 00:00:00 GMT

老系统的在最开始创建、编写代码创造出来的时候，最终系统的性能和可维护性，完全取决于编码者的水平。

当你接手的系统，遇到下面这些情况的时候，这篇文章或许可以给你一点帮助：

没有监控
没有告警
没有业务成功率
乐观锁频繁失败
系统响应时间黑盒（是的，你的业务方，使用者只是一味地跟你讲，系统很慢，但是具体不知道满在哪里）
日志查问题很复杂

是的，上面就是我一个月以来遇到的备儿头疼的问题。

一个月之期已到，所以我开始操刀，对这套系统进行一系列的性能优化了。

首先，要对系统的整体情况摸清除，所谓优化，你至少知道你自己优化了个啥。业务方也应该知道自己使用的系统到底慢在了哪里。

所以你需要做的事情就是，制定系统的基线。

制定系统的基线

系统的基线，是对系统在正常运行状态下各项关键性能指标的量化描述。

它是系统性能优化的起点，也是衡量优化效果的标准参照。简单来说，系统基线就是你的系统的"健康体检报告"，记录了系统在各种条件下的性能表现。（1，2）

系统基线包含以下这些

一个完整的系统基线应该包括以下方面：

性能指标

响应时间（平均、P95、P99）
吞吐量（QPS/TPS）
延迟（Latency）
并发处理能力

资源使用情况

CPU 使用率
内存占用及分配情况
磁盘 I/O
网络 I/O
连接池使用状况

业务指标

业务成功率
错误率
关键业务流程的完成时间

系统稳定性指标

系统平均无故障时间（MTBF）
系统崩溃恢复时间（MTTR）
锁竞争情况（如你提到的乐观锁失败率）

Google MapReduce

cheverjonathan@gmail.com (Chenwei Jiang) — Mon, 05 May 2025 00:00:00 GMT

这不就机会来了，乘着五一假期，好好解读一下这个最著名的论文之一，《MapReduce: Simplified Data Processing on Large Clusters》。

当然这篇文章我还受 “木鸟杂记” 的文章 影响很深，所以我的这篇文章纯粹是两篇文章的结合 + 我自己的一些思想。

之前一直听组里的老大哥说，MapReduce 分布式有多么厉害，那今天机会就来了～

Introduction

MapReduce 在论文中其实是一个概念。但是在另外一种情况下，它也可以是一种编程模型，也可以是支持该模型的一种分布式系统实现。当然我找到一篇文章^[1]把这个概念解释的更好，如下：

MapReduce 是谷歌 2004 年（Google 内部是从 03 年写出第一个版本）发表的论文里提出的一个概念。
在 Google 的语境里，MapReduce 既是一种编程模型，也是支持该模型的一种分布式系统实现。它的提出，让没有分布式系统背景的开发者，也能较轻松的利用大规模集群以高吞吐量的方式来处理海量数据。

这篇文章^[1]还有一句话解释了应用这项技术的解决问题思路：找到需求的痛点（如海量索引如何维护，更新和排名），对处理关键流程进行高阶抽象（分片 Map，按需 Reduce），以进行高效的系统实现（所谓量体裁衣）。

而在这其中，如何找到一个合适的计算抽象，是最难的部分，既要对需求有直觉般的了解，又要具有极高的计算机科学素养

上面 👆 这句话还是出自于引用 “木鸟杂记” 的文章。

我们回到论文，其实可以发现，在论文的第一页纸，Google 大佬就说清楚了这是个啥。

As a reaction to this complexity, we designed a new abstraction that allows us to express the simple computations we were trying to perform but hides the messy details of parallelization, fault-tolerance, data distribution and load balancing in a library.
意思是我们抽象了一个东西用来表达一种计算方式。这可以隐藏很多概念性的东西（并行化、容错性、数据分布和负载均衡）。
这种东西就是起源于 Lisp 和许多其他函数式语言中的 map 和 reduce 原语（primitives）。
We realized that most of our computations involved applying a map operation to each logical “record” in our input in order to compute a set of intermediate key/value pairs, and then applying a reduce operation to all the values that shared the same key, in order to combine the derived data appropriately.
我们的大部分计算，基本上都涉及到对输入中的每个逻辑 Record 应用 map 操作，以计算其中一组中间 key/val pair，然后对拥有相同的 key 的所有值应用 reduce 操作，以一种适当地组合导出数据。
Our use of a functional model with userspecified map and reduce operations allows us to parallelize large computations easily and to use re-execution as the primary mechanism for fault tolerance.
我们使用用户指定的 map 和 reduce 操作的 func module。这样就可以实现并行化大型计算。

我发现最后一句话很有意思，

use re-execution as the primary mechanism for fault tolerance.

使用 “重新执行/re-execution” 作为容错的主要机制。

OK，这篇论文的 Abstract 内容来咯：

Section 1 就是上面的这个 Introduction, Introduction;
Section 2 describes the basic programming model and gives several examples, [Programming Model](#Programming Model);
Section 3 describes an implementation of the MapReduce interface tailored towards our cluster-based computing environment, Implementation; 基于集群计算环境定制的 MapReduce 接口的实现。
Section 4 describes several refinements of the programming model that we have found useful; 几个编程模型的改进。
Section 5 has performance measurements of our implementation for a variety of tasks; 实现各种任务的性能测量。
Section 6 explores the use of MapReduce within Google including our experiences in using it as the basis for a rewrite of our production indexing system; MapReduce 在 Google 中的应用。
Section 7 discusses related and future work;

Programming Model

Map 的 Key 是正常的 Key，value 这边就假想为一个字符串数组吧。

这个 MapReduce，通俗来讲，就是两个函数，map 函数和 reduce 函数。

Map 函数接收一个输入对，并生成一组 intermediate key/value，然后 MapReduce library 将所有与同一 key 关联 intermediate value 组合在一起。

Example

下面是一段伪代码，祖父级别，来自于原论文：

map(String key, String value):
    // key: document name
    // value: document contents
    for each word w in value:
      EmitIntermediate(w, "1");

reduce(String key, Iterator values):
    // key: a word
    // values: a list of counts
    int result = 0;
    for each v in values:
      result += ParseInt(v);
    Emit(AsString(result));

上面这是一个经典的 MapReduce 单词计数（Word Count）实现，这是 MapReduce 编程模型中最常见的示例之一。

key：文档名称
value：文档的完整内容（文本字符串）

其中的 EmitIntermediate 表示的是 MapReduce 框架提供的用于输出中间键值对（intermediate key/val）。每次调用这个函数，就会产生一个键值对：（单词，“1”），表示该单词出现了一次。

举个例子，处理文档内容 "hello world hello"：

第一个单词 "hello" → EmitIntermediate("hello", "1")
第二个单词 "world" → EmitIntermediate("world", "1")
第三个单词 "hello" → EmitIntermediate("hello", "1")

Map 阶段输出的中间结果：

("hello", "1")
("world", "1")
("hello", "1")

Shuffle Stage（框架自动完成）

在 Map 和 Reduce 之间，MapReduce 框架自动执行 Shuffle 操作：

收集所有的 mapper 的输出；
按键（单词）排序；
将具有相同键的所有值分组在一起；

所以上面的示例经过 Shuffle 之后：

("hello", ["1", "1"])
("world", ["1"])

Reduce 函数

Shuffle 之后就是 Reduce 函数的工作了，上面的伪代码的作用其实就是累加，不多做解释。

完整执行流程

下面是一个更大的示例，展示整个 MapReduce 执行流程：

假设有三个文档：

document1.txt: "hello world"
document2.txt: "hello mapreduce"
document3.txt: "mapreduce world example"

Map 阶段（并行执行）

Mapper 1 处理 document1.txt:

EmitIntermediate("hello", "1")
EmitIntermediate("world", "1")

Mapper 2 处理 document2.txt:

EmitIntermediate("hello", "1")
EmitIntermediate("mapreduce", "1")

Mapper 3 处理 document3.txt:

EmitIntermediate("mapreduce", "1")
EmitIntermediate("world", "1")
EmitIntermediate("example", "1")

Shuffle 阶段（框架自动完成）：

("hello", ["1", "1"])
("world", ["1", "1"])
("mapreduce", ["1", "1"])
("example", ["1"])

Reduce 阶段（并行执行）：

Reducer 处理 "hello":

result = 0
result += 1 = 1
result += 1 = 2
Emit("2")  # 输出 ("hello", "2")

以此类推处理其他单词...

最终得出

("hello", "2")
("world", "2")
("mapreduce", "2")
("example", "1")

MapReduce 框架的作用

在这个过程中，MapReduce 框架负责：

将输入数据分割成多个分片，分配给不同的 Mapper
并行执行多个 Map 任务
执行 Shuffle 操作，重组和排序中间结果
并行执行多个 Reduce 任务
收集和整合 Reduce 输出
处理任务失败和重试
优化数据本地性，尽量在数据所在节点处理数据

这种模式使开发者能够专注于业务逻辑（Map 和 Reduce 函数），而无需关心并行化、分布式计算和容错等复杂问题。

More Examples

当然这里还有更多的样例。

Distributed Grep

工作原理

在这个示范 example 中，

Map 函数检查输入文本的每一行，如果匹配指定模式，则发出该行。
Reduce 函数是一种简单的恒等函数（identity function），直接将中间结果复制到输出。

应用价值

这种模式非常适合在大规模分布式文件系统中快速查找特定模式的文本行。它充分利用了 MapReduce 的并行处理能力，在数 TB 甚至 PB 级别的日志文件中查找特定错误信息时效率极高。

Count of URL Access Frequency（URL 访问频率统计）

工作原理

Map 函数: 处理网页请求日志，对每个 URL 发出键值对
Reduce 函数: 将同一 URL 的所有计数相加，输出

应用价值

这是网站分析中的基础操作，对于了解网站流量分布、识别热门内容和检测异常访问模式至关重要。在大型网站中，日志数据量可能达到每天数 TB，使用 MapReduce 可以有效处理这种规模的数据。

Reverse Web-Link Graph（反向网络链接图）

工作原理

Map 函数: 分析网页内容，对每个发现的链接，输出 <目标URL, 源URL>
Reduce 函数: 收集目标 URL 的所有源 URL，输出 <目标URL, 源URL列表>

应用价值

反向链接图是现代搜索引擎的核心数据结构之一，用于以下场景：

PageRank 等网页重要性算法的基础数据
分析网站间的引用关系
发现影响力较大的内容创作者
为网站管理员提供反向链接分析工具

构建完整的网络反向链接图是一项计算密集型任务，MapReduce 模型非常适合这种自然可并行化的问题。

Term-Vector per Host（每主机词向量统计）

工作原理

Map 函数: 分析文档内容，从 URL 提取主机名，输出 <主机名, 文档词向量>
Reduce 函数: 合并同一主机的所有词向量，过滤低频词，输出 <主机名, 汇总词向量>

应用价值

这种分析对于理解网站内容特征非常有价值：

可以用于网站的主题分类
帮助搜索引擎优化
内容相似性比较
竞争对手网站内容分析
内容推荐系统的基础数据

Inverted Index

工作原理

Map 函数: 解析每个文档，输出 <单词, 文档ID> 键值对
Reduce 函数: 接收给定单词的所有文档 ID，排序后输出 <单词, 文档ID列表> 键值对

应用价值

倒排索引是现代搜索引擎的基础数据结构，用于：

全文搜索: 快速找到包含查询词的所有文档
短语搜索: 通过位置信息实现精确短语搜索
TF-IDF 计算: 为信息检索系统提供词频统计
关键词高亮: 帮助前端展示匹配的文本片段
相关性排序: 为搜索结果提供基础数据

MapReduce 特别适合构建倒排索引，因为它可以高效地并行处理大量文档，并在 Reduce 阶段自然地实现索引合并。

Distributed Sort

工作原理

Map 函数: 提取每条记录的键，输出 <键, 记录> 键值对
Reduce 函数: 直接输出接收到的所有键值对，不做任何修改

这个看似简单的例子实际上巧妙利用了 MapReduce 框架的两个核心特性：

分区机制 (Partitioning): 确保具有相同范围键的记录被发送到同一个 Reducer
排序属性 (Sorting): 确保 Reducer 接收到的键按顺序排列

MapReduce 框架的特殊贡献:

在分布式排序中，MapReduce 框架做了大部分重要工作：

自定义分区器 (Custom Partitioner):

// 示例：范围分区器
func RangePartitioner(key string, numReducers int) int {
    // 根据键的范围确定应该发送到哪个reducer
    // 这确保了全局排序
    if key < "D" {
        return 0
    } else if key < "N" {
        return 1
    } else {
        return 2
    }
}

排序比较器 (Sort Comparator):

// 定义键的自然排序顺序
func KeyComparator(key1, key2 string) int {
    return strings.Compare(key1, key2)
}

应用价值

分布式排序是许多大数据处理工作流的基础操作：

数据预处理: 准备大规模数据集进行进一步分析
日志分析: 按时间戳排序大量日志记录
构建索引: 为数据库或搜索引擎创建排序索引
合并已排序数据: 将多个已排序的数据集合并为一个
TopN 查询: 快速找出某个指标的前 N 条记录

总体 Examples 分析与比较

示例展示了 MapReduce 模型的多功能性和适应性：

分布式 Grep: 最简单的一种应用，基本上只用到了 Map 功能，适合简单的过滤操作
URL 访问频率统计: 经典的单词计数变种，体现了 MapReduce 在统计聚合上的优势
反向网络链接图: 展示了如何使用 MapReduce 构建复杂的关系图和索引结构
每主机词向量统计: 结合了文本分析和聚合功能，适用于高级内容分析

Implementation（实现）

MapReduce 接口的多种不同实现方式都是可能的。

正确的选择取决于具体环境（具体问题具体分析的意思）。

例如，一种实现可能适用于小型共享内存机器，另一种适用于大型 NUMA 多处理器，还有一种则适用于更庞大的联网机器集群。

下面是 Google 广泛使用的一种计算环境。

This section describes an implementation targeted to the computing environment in wide use at Google: large clusters of commodity PCs connected together with switched Ethernet [4].
In our environment:
(1) Machines are typically dual-processor x86 processors running Linux, with 2-4 GB of memory per machine.
(2) Commodity networking hardware is used – typically either 100 megabits/second or 1 gigabit/second at the machine level, but averaging considerably less in overall bisection bandwidth.
(3) A cluster consists of hundreds or thousands of machines, and therefore machine failures are common.
(4) Storage is provided by inexpensive IDE disks attached directly to individual machines. A distributed file system [8] developed in-house is used to manage the data stored on these disks. The file system uses replication to provide availability and reliability on top of unreliable hardware.
(5) Users submit jobs to a scheduling system. Each job consists of a set of tasks, and is mapped by the scheduler to a set of available machines within a cluster.

(1) 机器通常配备双处理器 x86 架构，运行 Linux 系统，每台机器内存为 2‑4 GB。

(2) 采用商用网络硬件 —— 通常在机器层面为 100 兆比特 / 秒或 1 千兆比特 / 秒，但整体二分带宽的平均值显著较低。

(3) 一个集群由数百或数千台机器组成，因此机器故障是常有的事。

(4) 存储由廉价的 IDE 磁盘提供，这些磁盘直接连接到各台机器上。一个内部开发的分布式文件系统 [8] 用于管理存储在这些磁盘上的数据。该文件系统通过数据复制在不可靠的硬件基础上提供可用性和可靠性。

(5) 用户向调度系统提交作业。每个作业由一组任务构成，并由调度器映射至集群内一组可用机器上。

执行过程

The Map invocations are distributed across multiple machines by automatically partitioning the input data into a set of M splits. The input splits can be processed in parallel by different machines. Reduce invocations are distributed by partitioning the intermediate key space into R pieces using a partitioning function (e.g., hash(key) mod R). The number of partitions (R) and the partitioning function are specified by the user.
Following figure shows the overall flow of a MapReduce operation in our implementation. When the user program calls the MapReduce function, the following sequence of actions occurs (the numbered labels in Figure correspond to the numbers in the list below):

这个在用户 Program 中的 MapReduce Library 首先将文件分成 M 个 pieces，每个 piece 大小通常是 16 ～ 64 MB；
Master 上的程序 Copy 是特殊的，其他的 workers 会由 master 派活。这通常有 M 个 map tasks 和 R 个 reduce tasks 来分配。
There are M map tasks and R reduce tasks to assign. The master picks idle workers and assigns each one a map task or a reduce task.

这里有一个 idle 单词，idle workers 是指空闲工作节点，在 Google 的 MapReduce 架构中，整个计算任务是分布式执行的，包括：
1. Master（主节点）：一个特殊的程序副本，负责任务调度和协调整个计算过程
2. Workers（工作节点）：其余的程序副本，负责执行实际的计算任务
3. Idle workers（空闲工作节点）：指当前没有在执行任何任务、处于等待状态的 worker 节点 1
我希望这能够解释清楚什么是 Idle workers。
所以这一块通俗来讲，整个 MapReduce 的工作流程与空闲工作节点相关：
1. 当计算任务开始时，系统会启动多个程序副本，其中一个作为主节点，其余作为工作节点
2. 主节点维护整个集群的状态，包括每个工作节点是否处于空闲状态 2
3. 当主节点检测到某个工作节点是"空闲"的（即没有正在执行任务）时，会从待处理的 M 个 Map 任务或 R 个 Reduce 任务中选择一个分配给该工作节点
执行 map 任务的 Worker，会读取被分配到的输入切片，从输入切片中解析出键值对，然后将这个 pair 传递给用户定义的 map 函数。
这些中间键值对，由 map 生产并 buffer 在内存中。
A worker who is assigned a map task reads the contents of the corresponding input split. It parses key/value pairs out of the input data and passes each pair to the user-defined Map function. The intermediate key/value pairs produced by the Map function are buffered in memory

事实上 Hadoop 就是这么干的。
buffered 的中间结果 pairs 会被定期写入到本地 disk，然后被 partitioning 函数分片成 R 个 regions。
这些位于本地 disk 的 bufferd 的 pairs 又会被传递回到 master，这是为了让 master 可以将这些 pairs 的 locations 告知到 reduce workers。
Periodically, the buffered pairs are written to local disk, partitioned into R regions by the partitioning function.
The locations of these buffered pairs on the local disk are passed back to the master, who is responsible for forwarding these locations to the reduce workers.
当一个 reduce worker 收到上面的 buffered 的 pairs 的 locations 的时候，会通过 RPC 来读取这些对应的 partition 的数据。
当一个 reduce worker 已经读取完所有的数据之后，会按照 key 进行排序。这样就可以将所有拥有同样 key 的数据排序到一块去了。
When a reduce worker is notified by the master about these locations, it uses remote procedure calls to read the buffered data from the local disks of the map workers.
When a reduce worker has read all intermediate data, it sorts it by the intermediate keys so that all occurrences of the same key are grouped together.
The sorting is needed because typically many different keys map to the same reduce task.
If the amount of intermediate data is too large to fit in memory, an external sort is used.

如果 intermediate data（中间数据键值对）too large 的话，那么就会需要外部排序程序了。这里面就是一些性能优化的点了。

第 4 步和第 5 步骤合在一块就叫做 shuffle

之后，Reduce Worker 会遍历这些排好序的 intermediate data 数据，然后将这些数据以及其 key 相关的 data 传递到用户的 reduce 函数。
Reduce 函数的输出会被追加到最终的输出文件
The reduce worker iterates over the sorted intermediate data and for each unique intermediate key encountered, it passes the key and the corresponding set of intermediate values to the user’s Reduce function.
The output of the Reduce function is appended to a final output file for this reduce partition.
当所有的 map 任务和 reduce 任务都完成之后，master 会唤醒用户程序。
在这个角度，用户程序就会被返回一个最终的计算结果（MapReduce call）。
When all map tasks and reduce tasks have been completed, the master wakes up the user program. At this point, the MapReduce call in the user program returns back to the user code.

Master Data Structures

理解一下 MapReduce 框架中的 Master 节点所维护的关键数据结构以及其在任务调协中的核心职责。

Master 节点实际上是整个 MapReduce 执行过程的"大脑"，它维护以下重要数据：

任务状态记录：对每个 map 和 reduce 任务，master 节点都会记录其当前状态 5：
- idle（空闲）：待分配的任务
- in-progress（进行中）：已分配给 worker 但尚未完成的任务
- completed（已完成）：执行完毕的任务
Worker 机器标识：对于非空闲状态的任务，master 节点会记录执行该任务的 worker 机器的身份标识，用于跟踪任务执行情况和处理故障 5
中间文件元数据：对于已完成的 map 任务，master 会存储该任务产生的中间结果文件的位置和大小信息

Master 作为信息传递的渠道

Master 节点扮演着中间结果定位信息的传递渠道角色。当一个 map 任务完成后，它会告知 master 节点产生了哪些中间文件，以及这些文件的位置和大小信息 2。

此外额外补充信息，Google 的 MapReduce 实现是有作业（Job）级别的封装，每一个 Job 包含一系列任务（Task），即 Map Task 和 Reduce Task。

那么如果要维护一个正在运行的 Job 的元信息，就势必要保存所有正在执行的 Task 的状态，以及其所在的机器 ID 等等信息。

这些信息对 reduce 任务至关重要，因为 reduce 任务需要知道从哪里获取它需要处理的数据。

而且，Master 也充当了一种从 Map Task 输出到 Reduce Task 的信息 Channel。master 节点会增量地将这些信息推送给正在执行 reduce 任务的 worker 节点 1。

每一个 Map Task 结束时，会将其输出的中间结果的位置信息通知 Master，Master 再将其转给对应的 Reduce Task，Reduce Task 再去对应位置拉取对应 size 的数据。

注意，由于 Map Task 的结束时间不统一，这个通知 -> 转发 -> 拉取 的过程是增量的。那么不难推测出，reduce 侧对中间数据排序的应该是一个不断 merge 的过程，不大可能是等所有数据就位了再全局排序。 —— from 木鸟

The master keeps several data structures. For each map task and reduce task, it stores the state (idle, in-progress, or completed), and the identity of the worker machine (for non-idle tasks).
The master is the conduit through which the location of intermediate file regions is propagated from map tasks to reduce tasks. Therefore, for each completed map task, the master stores the locations and sizes of the R intermediate file regions produced by the map task. Updates to this location and size information are received as map tasks are completed. The information is pushed incrementally to workers that have in-progress reduce tasks.

例子解释一下 Master Data Structure 的作用

拿一个日志分析系统来说明 Master 在 MapReduce 过程中的作用。

工作原理

场景描述

有一个分布式系统生成了大量日志文件（数 TB）
需要分析每小时内各服务的错误率
日志文件分散存储在 100 个服务器上

MapReduce 处理流程

任务初始化：
- 将输入分为 1000 个 splits，创建 1000 个 Map 任务；
- 设置 10 个 Reduce 任务（按小时分组）；
- Master 将所有任务状态初始化为 idle；
Map 阶段：
- Master 将 idle 的 Map 任务分配给可用的 Worker，优先分配给存储数据的本地节点；
- 假设有 50 个 Worker 可用，每个 Worker 可同时处理 2 个任务；
- Map 任务处理日志 entries，按小时分组，输出 <小时，错误信息> 对；
Map 输出处理：
- 某 Worker 完成 Map-42 任务，生成 10 个中间文件（对应 10 个 Reduce 任务）
- Worker 向 Master 报告：
```
完成 Map-42，生成文件：
- worker3:/tmp/job7/map_42_reduce_0.out (2.3 MB)
- worker3:/tmp/job7/map_42_reduce_1.out (1.7 MB)
- ...其他8个文件
```
  - Master 记录这些文件位置和大小信息
  - Master 更新 Map-42 状态为 completed
信息传递：
- 如果 Worker3 在完成 Map-42 后崩溃
- Master 检测到心跳丢失，将 Worker3 上的所有 in-progress 任务重置为 idle
- 已完成的 Map-42 不需重做，但其中间文件不可访问
- Master 将重新调度 Map-42 给其他 Worker 执行

机制优缺点

优点：

简单高效的协调机制：Master 集中管理任务状态和中间文件位置，简化了分布式系统设计
增量数据传输：中间结果信息的增量推送允许 Reduce 任务尽早开始获取和处理数据
良好的容错性：Master 可以检测 Worker 故障并重新调度任务，确保计算的可靠性
数据本地性优化：Master 可以根据数据位置分配任务，减少网络传输

缺点：

单点故障问题：Master 本身成为单点故障源，如果 Master 崩溃，整个作业将失败 5
可扩展性瓶颈：
- 当任务数量极大时，Master 需要维护大量状态信息
- 频繁的状态更新会给 Master 带来高负载
网络瓶颈：所有中间文件位置信息都经过 Master 传递，可能导致网络拥塞
复杂的故障恢复：如果 Map 任务已完成但中间文件丢失（如 Worker 存储故障），需要重新执行 Map 任务

针对 Master 设计缺陷的常见解决方案

在分布式系统中，最忌讳的就是单点。因为往往这样的分布式架构，如果 Master 节点出现了故障，那么整套系统的可用性就为 0 了。所以我们做的很多事情，就是在强化 Master 节点。

我们从 “强化 Master 节点” 这个角度去思考解决方案：

Master 高可用设计
1. 实现 Master 的主从机制，可以类似 etcd、consul 这样进行分布式协调服务选举主 Master，利用租约一类的设计完成；
2. 实现 Master 节点的热备份和故障转移；
分层架构
1. 引入二级 Master 或者区域 Master 分担负载；
2. YARN 之类的现代框架将资源管理与任务调度分离，增强了可扩展性，一定程度上隔离了风险故障；

从 ”强化存储中间文件信息存储“ 这个角度出发，思路可以有，分布式存储元数据：

分布式元数据存储：
- 将任务状态和中间文件信息存储在分布式系统中
- 支持快照和持久化，便于故障恢复

从 ”增强 Worker“ 角度出发：

直接 Worker 通信：
- 允许 Worker 之间直接通信交换中间结果位置
- 减轻 Master 负担，但增加系统复杂性

从 ”任务粒度调整“ 角度出发：

动态任务粒度调整：
- 根据任务规模和集群状态动态调整任务大小
- 小型作业使用较粗粒度任务减少管理开销，大型任务使用细粒度任务提高并行度

Failure Tolerance

分布式系统，在处理大量的数据的时候，同时也一定面临着分布式机器上的各种错误，如何优雅地处理这些错误，也是必学的一门课。

这里的论文大概分为三种 Failure：

[Worker Failure](#Worker Failure)
[Master Failure](#Master Failure)
[Semantics in the Presence of Failures](#Semantics in the Presence of Failures)

Worker Failure

master 会定期去 ping 各个 worker 节点，如果没有响应的话，那么 master 就会将其标记为 failed 节点。

这个时候不管是已经完成还是未完成的 map tasks 都会被标记为最初的状态 idle state。然后等待被调度到其他正常的 workers 上去。

然后这一段 map tasks 就会被重新执行，重新存储到本地 disk 上去，然后 master 会将这些信息继续通报给 Reduce workers。

这个时候呢，如果 Reducer worker 已经处理了 map tasks 其中的某个一个单独 task，那么它不用再从 master 提供的信息中继续去拿处理数据，如果没处理，就继续拿。

在 Reducer worker 侧，当发现自己处理的某一段 map tasks 上的 map worker 出现了故障，举个例子，这个 Reduce 程序是 R5，他正在处理 Worker-37 上的 map 任务（41 ～ 51），当 R5 处理到 M47 的时候，发现出现了故障，那么它的应对措施（伪代码）如下：

传输中断处理：如果 R5 正在从 Worker-37 拉取数据时连接中断，会触发异常处理流程

// 简化的伪代码
try {
    fetchMapOutput(worker37, mapTaskId47);
} catch (FetchFailureException e) {
    // 等待Master通知新的数据位置
    waitForNotification(mapTaskId47);
    // 获取新的数据位置后重试
    fetchMapOutput(worker51, mapTaskId47);
}

数据一致性：R5 会丢弃从 Worker-37 已部分拉取的不完整数据

if (partialData && dataSource != currentSourceForTask) {
    discardPartialData();
    fetchFromNewSource();
}

通知机制：Master 通过以下方式通知 Reduce 任务

1. 心跳响应中包含更新的Map输出位置信息
2. RPC调用通知状态变更
3. Reduce任务定期轮询Master获取最新映射信息

我再额外引申一些联想，上面的一系列操作，体现了实际的分布式架构设计模型中常用的一些技术点下：

关键技术点

乐观并发模型：MapReduce 采用乐观策略，不阻止多个 Worker 同时处理同一数据，而是在需要时重新计算
幂等性保证：Map 和 Reduce 函数被设计为幂等操作，确保重复执行不会影响最终结果
增量通知机制：Master 增量通知 Reduce 任务，减少不必要的数据传输和重新计算
数据验证：通常使用校验和验证数据完整性，确保即使使用已获取的数据也能保证计算正确性

Master Failure

Google 的论文对于 Master 故障的处理相对来说很简单：通过检查点机制保存状态，但在 Master 实际故障时会终止整个作业。

这种设计基于两个考虑：

单点特性：系统中通常只有一个 Master 节点，故障概率相对较低；
简化设计：简单的故障处理机制减少了系统复杂度；

然而，在关键生产环境中，这种简单的处理方式显然难以满足高可用需求。

随着分布式系统的发展，更健壮的 Master 故障处理机制应该被严肃认真滴考虑一下。考虑方案如下：

主备高可用架构

+---------------+   复制状态   +---------------+
|  Active Master |------------->| Standby Master|
+---------------+              +---------------+
        ^                              |
        | 心跳                         | 故障转移
        |                              v
+--------------------------------------------+
|              ZooKeeper集群                  |
+--------------------------------------------+
        ^                              ^
        |                              |
+---------------+              +---------------+
|   Worker-1    |              |   Worker-N    |
+---------------+              +---------------+

实现：

使用 ZooKeeper 等进行 Leader 选举
通过同步复制或共享存储保持状态一致
心跳监测机制检测故障
平滑接管避免作业中断

分布式状态管理

// 使用分布式存储系统保存状态
func (m *Master) updateTaskState(taskID string, state TaskState) {
    // 更新内存状态
    m.taskStates[taskID] = state

    // 同步更新到分布式存储
    etcdClient.Put(context.Background(),
                  fmt.Sprintf("/mapreduce/tasks/%s/state", taskID),
                  string(state))
}

// 从分布式存储恢复状态
func recoverMasterState() *Master {
    master := newMaster()

    // 从etcd读取所有任务状态
    resp, _ := etcdClient.Get(context.Background(),
                             "/mapreduce/tasks/", clientv3.WithPrefix())

    for _, kv := range resp.Kvs {
        // 解析键值并恢复状态
        taskID, field := parseKey(string(kv.Key))
        if field == "state" {
            master.taskStates[taskID] = TaskState(kv.Value)
        }
        // 其他字段类似处理...
    }

    return master
}

应用级故障恢复
现代系统如 YARN 将 MapReduce 的 Master 分为两个角色：
1. ResourceManager：集群资源管理（全局角色）
2. ApplicationMaster：单个作业协调（每个作业一个）
这种设计带来两个优势：
- ResourceManager 故障不会影响正在运行的作业
- ApplicationMaster 故障只影响单个作业，可以独立恢复

客户端弹性恢复

为支持 Master 故障后的客户端重试，需要确保 MapReduce 操作的幂等性：

// 客户端重试逻辑
func executeMapReduceWithRetry(job *MapReduceJob, maxRetries int) Result {
    // 为每个作业生成唯一ID，支持幂等执行
    if job.JobID == "" {
        job.JobID = generateUniqueID()
    }

    var lastError error
    for i := 0; i < maxRetries; i++ {
        result, err := submitMapReduceJob(job)
        if err == nil {
            return result
        }

        lastError = err
        if !isMasterFailureError(err) {
            // 非Master故障错误，直接返回
            return nil, err
        }

        log.Printf("Master failure detected, retrying job %s (%d/%d)...",
                  job.JobID, i+1, maxRetries)
        time.Sleep(retryBackoff(i))
    }

    return nil, fmt.Errorf("all retries failed: %v", lastError)
}

示范用例：金融交易数据分析系统

下面通过一个金融交易数据分析系统的例子来说明不同 Master 故障处理策略的效果：

场景描述

任务：处理全球金融市场一天的交易数据(10TB)并计算风险指标
时间要求：必须在市场开盘前完成(有严格的时间窗口)
可靠性要求：结果必须 100%准确，不允许数据丢失

对比不同故障处理策略

原始 MapReduce 方案(简单重启)

晚上10:00 - 作业开始，预计4小时完成
凌晨01:30 - Master故障，计算被中断(已完成约70%)
凌晨01:35 - 运维人员接到告警，手动重启作业
凌晨01:40 - 新作业从头开始计算
凌晨05:40 - 作业完成，但已超过市场开盘时间
结果：业务影响严重，无法按时提供风险分析

改进方案(高可用 Master)

晚上10:00 - 作业开始，预计4小时完成
凌晨01:30 - 主Master故障
凌晨01:30.5 - 备Master自动接管(500毫秒故障转移)
            - 备Master从共享存储恢复状态
            - 重置进行中任务状态为idle
凌晨01:35 - 系统重新调度中断的任务
凌晨04:15 - 作业正常完成
结果：系统自动恢复，业务正常进行

Semantics（语义） in the Presence of Failures

MapReduce 提供了一个关键的承诺：在确定性操作时，分布式并行执行的结果与顺序执行完全一致。

这个特性极大简化了分布式程序的复杂性。

那么是如何实现这个“计算结果一致性” 的呢？

关键机制：原子提交

MapReduce 通过精心设计的原子提交机制实现结果一致性：

临时文件策略
任务完成流程
冗余执行处理

原子操作的核心作用

原子操作时整个容错机制的基础，主要体现在两个层面：

Master 数据结构更新
文件系统原子重命名，举个例子，Reduce 任务完成时的原子重命名操作，只有一个执行实例能成功命名，换言之，如果有一个命名好的文件，那就意味着已经成功执行了一个实例了

确定性与非确定性操作的语义区别

Map Reduce 框架对不同类型的操作提供不同级别的语义保证：

确定性操作的强语义保证

当 map 和 reduce 函数是确定性的（相同输入总是产生相同输出）时：

全局一致性：整个计算的结果与单机顺序执行完全相同
重复执行不变性：任务执行多次，结果不变
故障透明性：用户无需关心故障处理细节

# 确定性Map函数示例
def map_word_count(doc_id, document):
    for word in document.split():
        emit(word, 1)  # 相同输入总是产生相同输出

# 确定性Reduce函数示例
def reduce_word_count(word, counts):
    emit(word, sum(counts))  # 相同输入总是产生相同的和

非确定性操作的弱语义保证

当 map 或 reduce 函数是非确定性的（相同输入可能产生不同输出）时：

部分一致性：单个 reduce 任务的输出等同于某次顺序执行的相应输出
分片间不一致性：不同 reduce 任务可能对应不同的顺序执行结果
"部分"顺序执行等价：结果不等同于任何单次顺序执行的完整结果

# 非确定性Map函数示例
def map_with_random(doc_id, document):
    for word in document.split():
        # 添加随机噪声，使得相同输入产生不同输出
        random_value = random.random()
        emit(word, random_value)

实例解析

这边那两个实例来解释和理解“故障情况下的语义保证”：

两个场景：

分析网站用户行为程序，计算每个 URL 的独特访问者数量；
广告点击分析系统；

计算每个 URL 的独特访问者数量

考虑一个具体场景：分析网站用户行为数据，计算每个 URL 的独特访问者数量。

分布式系统配置

100 个 Map 任务(M0-M99)：每个处理一个日志分片
10 个 Reduce 任务(R0-R9)：按 URL 哈希分区
Map 输出：对
Reduce 操作：去重计数用户 ID

确定性操作场景

假设所有操作都是确定性的：

M42 任务在 Worker-A 上执行，生成输出
Worker-A 故障，M42 输出不可访问
M42 在 Worker-B 上重新执行，生成相同的输出
R3 读取 M42(Worker-B 执行)的输出
R7 读取 M42(Worker-B 执行)的输出

结果：R3 和 R7 都处理了相同的 M42 输出，最终整体结果等价于顺序执行

非确定性操作场景

假设 Map 函数使用随机采样来降低数据量：

M42 首次在 Worker-A 上执行，随机采样生成输出 X
R3 开始执行并读取了 M42 的输出 X
Worker-A 故障，M42 输出 X 不可访问
M42 在 Worker-B 重新执行，随机采样生成不同的输出 Y
R7 执行并读取 M42 的新输出 Y

结果：

R3 处理了基于样本 X 的数据
R7 处理了基于不同样本 Y 的数据
最终结果不等同于任何单次顺序执行的结果

实时广告点击分析系统

系统需求

分析广告点击流数据，计算每小时广告转化率
处理数据量：每小时数十亿点击事件
需要输出：每个广告 ID 的点击次数和转化次数

数据流设计

输入：点击事件流(adid, eventtype, timestamp, userid, ...) Map 函数：提取(adid, event_info)键值对 Reduce 函数：按广告 ID 聚合统计点击和转化

确定性实现

# 确定性Map函数
def map_ad_events(_, event):
    ad_id = event['ad_id']
    event_type = event['event_type']
    info = {
        'clicks': 1 if event_type == 'click' else 0,
        'conversions': 1 if event_type == 'conversion' else 0
    }
    emit(ad_id, info)

# 确定性Reduce函数
def reduce_ad_stats(ad_id, event_infos):
    total_clicks = sum(info['clicks'] for info in event_infos)
    total_conversions = sum(info['conversions'] for info in event_infos)

    result = {
        'ad_id': ad_id,
        'clicks': total_clicks,
        'conversions': total_conversions,
        'conversion_rate': total_conversions / total_clicks if total_clicks > 0 else 0
    }
    emit(ad_id, result)

故障情况下的一致性：即使某些 Worker 故障并导致任务重新执行，最终计算的广告统计结果仍然准确，因为操作是确定性的。

非确定性实现（采样）

# 非确定性Map函数(使用随机采样)
def map_ad_events_sampled(_, event):
    # 随机采样10%的事件
    if random.random() <= 0.1:  # 非确定性!
        ad_id = event['ad_id']
        event_type = event['event_type']
        # 因为是10%采样，权重需要乘以10
        info = {
            'clicks': 10 if event_type == 'click' else 0,
            'conversions': 10 if event_type == 'conversion' else 0
        }
        emit(ad_id, info)

故障情况下的不一致性：

如果 Map 任务 M25 处理的是美国地区的点击数据，并且：

M25 首次执行时采样了一组事件 X
Reduce 任务 R3（处理广告 ID 1000-1999）读取了这个输出
M25 执行的 Worker 故障，导致 M25 重新执行
第二次执行采样了不同的事件集合 Y
Reduce 任务 R7（处理广告 ID 6000-6999）读取了新输出

结果：

广告 ID 1500 的统计数据基于样本 X
广告 ID 6500 的统计数据基于样本 Y
不同广告之间的相对性能比较可能不一致

实现要点与最佳实践

优先使用确定性操作：
- 尽可能设计确定性的 Map 和 Reduce 函数
- 将不确定性因素（如随机性）封装在预处理或后处理阶段
处理非确定性需求：
- 使用伪随机数生成器并提供固定种子
- 将随机状态作为输入参数而非函数内生成
确保幂等性：
- 设计能多次安全执行的操作
- 输出命名使用任务 ID 而非时间戳
原子性保证：
- 利用底层文件系统或数据库的事务能力
- 实现"先写临时，后原子重命名"的模式

MapReduce 的这种语义保证设计平衡了系统的一致性需求与工程实现复杂度，为分布式计算提供了实用而强大的模型。确定性操作的强一致性保证特别有价值，它让程序员可以像编写顺序程序一样思考分布式计算，极大降低了分布式编程的复杂性。

Locality（局部性）

计算机科学中常用的一个原理，叫做局部性原理 （locality reference，这里特指空间局部性），说的是程序在顺序执行时，访问了一块数据，接下来大概率会访问该数据（物理位置上）旁边的一块数据。很朴素的断言，却是一切 cache 发挥作用的基础，计算机存储因此也形成了由慢到快，由贱到贵，由大到小的存储层次体系（硬盘 -> 内存 -> 缓存 -> 寄存器）。

在分布式环境中，这个层次体系至少还要再罩上一层 —— 网络 IO。这也就是论文中的第一句 “Network bandwidth is a relatively scarce resource in our computing environment”。

在 MapReduce 系统中，我们也会充分利用输入数据的 locality。只不过这次，不是将数据加载过来，而是将程序调度过去（Moving Computation is Cheaper than Moving Data）。如果输入存在 GFS 上，表现形式将为一系列的逻辑 Block，每个 Block 可能会有几个（一般是三个）物理副本。对于输入每个逻辑 Block，我们可以在其某个物理副本所在机器上运行 Map Task（如果失败，就再换一个副本），由此来尽量减小网络数据传输。从而降低了延迟，节约了带宽。

Network bandwidth is a relatively scarce resource in our computing environment. We conserve network bandwidth by taking advantage of the fact that the input data (managed by GFS [8]) is stored on the local disks of the machines that make up our cluster. GFS divides each file into 64 MB blocks, and stores several copies of each block (typically 3 copies) on different machines. The MapReduce master takes the location information of the input files into account and attempts to schedule a map task on a machine that contains a replica of the corresponding input data. Failing that, it attempts to schedule a map task near a replica of that task’s input data (e.g., on a worker machine that is on the same network switch as the machine containing the data). When running large MapReduce operations on a significant fraction of the workers in a cluster, most input data is read locally and consumes no network bandwidth.

Task Granularity（任务粒度）

深入分析一下 MapReduce 框架中任务粒度（Task Granularity）的核心设计原则、影响因素和最佳实践。

任务粒度的基本概念

MapReduce 将计算任务分为两个阶段：

M: Map 任务的数量（输入数据被分割成 M 个片段）
R: Reduce 任务的数量（中间键空间被分成 R 个分区）

任务粒度指的是每个单独任务处理的数据量大小，它是 MapReduce 框架中一个关键的设计参数。

论文中有一个很重要的观点，“M and R should be much larger than the number of worker machines“。

M 和 R 应该远大于 Worker 机器数量

动态负载均衡

// 简化的负载均衡场景
100个Map任务, 10台机器
- 机器1-9: 每台处理10个任务，均匀负载
- 机器10: 硬件较慢，只完成5个任务
- 任务分配器自动将剩余5个任务重新分配给已完成任务的机器

当每台机器处理多个小任务而非单个大任务时，快速的机器可以处理更多任务，慢速机器处理较少，自然形成了基于性能的工作分配。

加速故障恢复

假设:
- 2000台机器，每台执行约100个Map任务
- 单台Worker-37故障，已完成92个Map任务

影响:
- 传统设计(每台机器1个大任务): 丢失整个Worker-37的计算结果
- 细粒度设计: 只需重新执行92个小任务，分散到其他1999台机器
- 恢复速度: 约为传统方法的1/20(平均每台机器分担不到1个额外任务)

当一个 worker 故障时，它已完成的多个小任务可以迅速分散到集群中的其他机器上重新执行，显著加快恢复速度

任务粒度的实际限制因素

尽管细粒度任务有明显优势，但不能无限增加 M 和 R 的值。主要限制包括：

Master 节点的调度与存储开销
```
// Master需要维护的状态数据量
存储空间 ≈ O(M + R) + O(M * R)
   - O(M + R): 任务状态信息
   - O(M * R): Map输出位置信息(每个Map任务为每个Reduce生成一个分区)
```
论文指出，Master 节点需要做 O(M + R)次调度决策，并且在内存中维护 O(M * R)的状态信息。虽然每个 Map/Reduce 任务对的状态只占约 1 字节，但数量庞大时仍会造成显著开销。
输出文件的管理限制
Reduce 任务的数量 R 通常受到用户需求的限制，因为每个 Reduce 任务会生成一个独立的输出文件。如果应用需要生成固定数量的输出文件（如按地区分组的报告），这会直接约束 R 的选择
任务启动开销
```
// 任务启动开销累积
总启动开销 ≈ (任务启动时间 * (M + R))
```
每个任务启动都有固定开销（进程创建、JVM 启动、资源分配等）。
任务过小会导致大量时间浪费在非计算性工作上。

Google 实践中的参数选择

论文提供了 Google 实际使用的参数作为参考：

Map 任务大小：通常选择 16MB-64MB 的输入数据量，这个范围有利于数据本地性优化
Reduce 任务数量：通常设为预期使用的 worker 机器数量的小倍数

实际应用规模：

典型参数:
- M = 200,000 (Map任务数)
- R = 5,000 (Reduce任务数)
- Worker = 2,000 (机器数)

平均每台机器:
- 执行约100个Map任务
- 执行约2-3个Reduce任务

这种配置充分体现了"任务数远多于机器数"的设计理念

任务粒度优化的多维度考量

数据本地性与任务粒度

数据本地性，是 MapReduce 框架的核心优化策略，指的是“将计算移动到数据所在位置”，而非通过网络传输大量数据。这一概念在分布式系统中极为重要，因为网络传输通常是主要瓶颈。

粒度太大为何减少并行度

当 Map 任务粒度过大时：

集群节点利用不充分
资源绑定时间长
调度灵活性降低

粒度太小为何增加非本地执行概率

数据本地性在 MapReduce 中分为三个层级：

节点本地性(Node Locality): 数据与执行任务的节点位于同一服务器
机架本地性(Rack Locality): 数据与执行节点在同一机架但不同服务器
跨机架(Off-Rack): 数据需要从其他机架传输

当任务粒度过小时：

调度竞争激烈

假设：集群有1000个节点，每个节点数据块分布均匀

- 小粒度(1MB/任务)：产生1,000,000个任务
- 每个节点平均存储1000个数据块
- 同时有多个任务竞争相同节点的执行槽位
- 当节点A的槽位都被占用，即使还有本地数据块未处理
- 调度器被迫将这些任务分配给非本地节点B

调度复杂度提高

大量小任务导致调度过载:
- Master需要做出更多调度决策(O(M)复杂度)
- 调度延迟增加，最优本地性决策可能错失
- 调度器可能退化为贪心策略，优先满足可用性而非最佳本地性

资源碎片化

每个任务都有固定开销:
- JVM启动: ~1秒
- 资源分配: ~0.5秒
- 状态报告: 持续占用少量资源

过多小任务导致:
- 资源大量用于管理开销而非实际计算
- 节点资源碎片化，难以高效分配

16-64MB 为何是理想任务粒度

这个范围并非随机选择，而是基于多种技术因素的平衡点：

分布式文件系统块大小
```
HDFS默认块大小: 64MB-128MB(早期版本)
GFS块大小: 64MB(Google文件系统，MapReduce最初设计环境)
```
当 Map 任务粒度与文件系统块大小相近时，可以实现最优的数据本地性 5。一个 Map 任务处理一个或少数几个块是最理想的情况。
网络与磁盘性能比率分析
MapReduce 设计之初(2003-2004 年)，集群环境下：
```
数据中心网络带宽: ~1Gbps(共享)
实际可用节点带宽: ~100Mbps
磁盘顺序读取速度: ~50-100MB/s

传输64MB数据:
- 本地读取时间: <1秒
- 网络传输时间: ~5秒

性能差距: 5倍以上
```
根据这个性能差距，选择 16-64MB 的粒度可以在数据需要通过网络传输时，将额外开销控制在合理范围内。

任务启动开销与执行时间比例

假设任务固定开销:
- JVM启动: ~1秒
- 资源分配: ~0.5秒
- 状态报告: ~0.2秒
总固定开销: ~1.7秒

处理不同大小数据所需时间(假设100MB/s处理速度):
- 1MB: 0.01秒 (开销比: 99%)
- 10MB: 0.1秒 (开销比: 94%)
- 16MB: 0.16秒 (开销比: 91%)
- 64MB: 0.64秒 (开销比: 73%)
- 128MB: 1.28秒 (开销比: 57%)
- 1GB: 10秒 (开销比: 15%)

16-64MB 范围在固定开销与实际计算时间之间取得了合理平衡

故障恢复粒度考量

场景：1000节点集群，处理10TB数据

节点故障影响:
- 1GB粒度: 重新计算~10个任务，每个~10秒，串行~100秒
- 64MB粒度: 重新计算~160个任务，每个~0.64秒，并行~几秒

适中的 16-64MB 粒度使得失败任务可以迅速并行重新执行，而不会造成大量计算浪费

内存与排序效率

Map 和 Reduce 任务都需要在内存中进行数据操作：

早期节点内存: 4-8GB
系统和框架开销: ~1-2GB
可用应用内存: ~3-6GB

考虑多任务并行执行:
- 每节点10个并行任务
- 每任务可用内存: ~300-600MB
- 安全工作内存: ~100-200MB

16-64MB的输入通常能在这个内存限制内高效处理

实验验证的经验值
Google 在论文中提到这个范围，很可能是基于大量实际实验和生产工作负载分析得出的最佳实践 2。随着硬件演进，现代系统可能会调整这个范围，但基本原理依然适用。

图解

数据本地性随任务粒度变化的趋势:

      ^
      |                    最优范围
本地  |             ******
执行  |         ****      *****
比例  |      ***               ***
      |    **                     **
      |  **                         **
      |**                             **
      +---------------------------------->
        小                               大
                  任务粒度

这个曲线说明：

粒度太小时，调度竞争导致本地执行比例下降
粒度太大时，并行度降低，导致整体效率下降
16-64MB 范围位于曲线顶点附近，是实际应用中的最佳平衡点

虽然 16-64MB 是一个很好的起点，但最佳粒度应根据具体应用场景调整：

计算密集型任务: 可以使用较大粒度(如 64-128MB)
IO 密集型任务: 应使用较小粒度(如 16-32MB)
异构集群: 可考虑动态调整粒度，适应不同节点能力
高内存需求: 如果单任务内存需求大，应相应减少粒度

通过合理设置任务粒度，可以实现数据本地性、并行度和系统开销的最佳平衡，从而获得 MapReduce 框架的最优性能。

Backup Tasks（备份任务）

这个东西，是 Google 为了解决“掉队者”（stragglers）而设计的。

One of the common causes that lengthens the total time taken for a MapReduce operation is a “straggler”: a machine that takes an unusually long time to complete one of the last few map or reduce tasks in the computation.

为了解决慢任务问题引入的重要优化。

Straggler 问题：分布式系统中的关键挑战

"掉队者"(Stragglers)指那些异常缓慢完成任务的机器，它们会严重拖慢整个 MapReduce 作业的完成时间。在大规模分布式环境中，这个问题尤为突出。

主要原因

硬件问题：

- 磁盘错误：可纠正错误将读取速度从30MB/s降至1MB/s
- 网络问题：网卡故障导致带宽下降
- CPU或内存故障：处理能力显著下降

资源竞争：

- 多任务调度冲突：其他作业占用CPU、内存资源
- I/O争用：多进程争夺磁盘或网络I/O
- 内存压力：内存不足导致频繁页面交换

软件问题：

- 配置错误：如Google遇到的处理器缓存被禁用bug(性能降低100倍)
- GC暂停：垃圾回收引起的长时间暂停
- 系统更新：后台服务或更新占用资源

Stragglers 的影响

在 MapReduce 作业中，作业完成时间受限于最后一个完成的任务。当 99%的任务都快速完成，而少数几个任务异常缓慢时，整个作业的完成时间将被这些慢任务所主导 4。

典型情景：

10,000 个 Map 任务，预期 1 小时内完成
9,990 个任务在 58 分钟内完成
10 个 stragglers 可能需要额外 2-3 小时
结果：整个作业耗时超过 3 小时而非 1 小时

备份任务机制：优雅解决方案

Google 设计的备份任务机制是一种简单而有效的策略，通过适度的资源冗余来减少总体执行时间。

工作原理详解

// 备份任务调度的伪代码实现
func (m *Master) scheduleBackupTasks() {
    // 当作业接近完成时触发
    if m.progressRate() > 0.95 { // 95%任务已完成
        // 查找所有运行时间超过平均值的进行中任务
        inProgressTasks := m.getInProgressTasks()
        for _, task := range inProgressTasks {
            if task.runningTime() > m.averageTaskTime() * 1.5 {
                // 为可能的straggler创建备份任务
                m.scheduleBackupExecution(task)
            }
        }
    }
}

// 任务完成处理
func (m *Master) markTaskCompleted(taskID string, workerID string) {
    task := m.tasks[taskID]

    if task.State == TaskCompleted {
        // 任务已被另一个执行实例(主执行或备份)完成
        return
    }

    // 标记任务完成
    task.State = TaskCompleted

    // 取消该任务的其他执行实例
    m.cancelOtherExecutions(taskID, workerID)
}

核心设计要点

触发时机：
- 仅在 MapReduce 作业接近完成时启动
- 通常是在 95%以上的任务完成后
- 针对的是最后剩余的几个运行中任务

判定标准：

Master维护任务执行统计信息:
- 平均任务完成时间
- 各任务已运行时间
- 执行速度(如已处理数据量/已运行时间)

当某任务运行时间显著高于平均值时,被判定为潜在straggler

执行策略：
- 不取消原任务，而是并行启动备份执行
- 在不同机器上调度备份任务
- 首个完成(主执行或备份)的结果被采用
- 另一个执行实例被取消
资源管理：
- 经过调优，通常只增加几个百分点(1-5%)的资源使用
- 只为少数任务创建备份，避免资源浪费
- 优先使用空闲资源进行备份执行

备份任务的实际效果

论文给出了一个具体的性能改进案例：

排序程序性能对比:
- 启用备份任务: 基准时间T
- 禁用备份任务: 1.44×T (多44%的执行时间)

资源使用增加: <5%
时间减少: ~30%
整体效率提升: 显著

这表明备份任务机制是一个高投入产出比的优化：用少量额外计算资源换取显著的速度提升

深入剖析：备份任务调度策略

备份任务不是简单地为所有慢任务创建副本，而是采用智能调度策略：

1. 任务选择机制

// 简化的备份任务选择算法
function selectTasksForBackup() {
    candidateTasks = []

    // 每种判断慢任务的方法
    metrics = [
        {name: "绝对运行时间", threshold: avg * 1.5},
        {name: "进度速率", threshold: avgRate * 0.5},
        {name: "预估剩余时间", threshold: avgRemaining * 2}
    ]

    // 使用多种指标识别慢任务
    for each task in runningTasks:
        for each metric in metrics:
            if task.value(metric) > metric.threshold:
                candidateTasks.add(task)
                break

    // 排序并限制备份数量
    return prioritize(candidateTasks).limit(maxBackups)
}

2. 机器选择策略

备份任务的机器选择也是关键因素：

优选条件:
1. 无故障历史的机器
2. 数据本地性好的机器
3. 当前负载较低的机器
4. 硬件配置较好的机器

3. 动态调整机制

// 动态调整备份任务数量
function adjustBackupThreshold() {
    // 监控集群资源使用率
    clusterUtilization = getCurrentClusterUtilization()

    if clusterUtilization > 0.9 { // 高负载
        // 减少备份任务，只处理极端慢的任务
        increaseBackupThreshold(0.2)
    } else if clusterUtilization < 0.7 { // 低负载
        // 增加备份任务，更积极预防慢任务
        decreaseBackupThreshold(0.1)
    }
}

备份任务的演进与现代实现

原始 MapReduce 的备份任务策略在现代系统中得到了进一步改进：

1. Hadoop 的推测执行(Speculative Execution)

Hadoop 实现了类似的机制，但增加了更多配置选项：



  mapreduce.map.speculative
  true


  mapreduce.reduce.speculative
  true


  
  mapreduce.job.speculative.slownodethreshold
  1.0

2. LATE 调度器

UC Berkeley 提出的 LATE(Longest Approximate Time to End)调度器改进了备份任务机制：

LATE调度器优化:
1. 基于估计剩余时间而非已运行时间判断stragglers
2. 考虑节点异构性，针对性能不均集群优化
3. 设置推测任务上限，避免资源浪费
4. 优先在快速节点上执行备份任务

这种改进使得备份任务机制在异构环境中表现更佳

3. Spark 的推测执行

Spark 在继承 MapReduce 理念的同时，对备份任务机制做了进一步优化：

// Spark推测执行配置
spark.speculation                     true
spark.speculation.interval            100ms
spark.speculation.multiplier          1.5
spark.speculation.quantile            0.75

Spark 引入了任务持续时间分布的概念，使用分位数而非简单平均值来判断异常情况，进一步提高了识别准确率。

关键实施挑战与解决方法

1. 误判问题

备份任务机制可能会误判正常但处理数据复杂的任务为 stragglers：

解决方案:
1. 结合数据特征(如输入大小、复杂度)评估预期执行时间
2. 使用机器学习模型预测任务执行时间
3. 引入任务进度报告机制，评估实际完成百分比

2. 资源调度冲突

备份任务可能与其他作业竞争资源：

解决方案:
1. 资源池隔离，为备份任务预留特定资源
2. 优先级机制，根据集群负载动态调整备份任务优先级
3. 公平调度器集成，考虑整体资源分配策略

3. 网络拥塞

备份任务可能增加网络流量：

解决方案:
1. 数据本地性优先，尽量在数据本地节点执行备份
2. 差异化传输，只传输必要的数据子集
3. 网络感知调度，避免在网络瓶颈区域增加负载

总结

备份任务机制是 MapReduce 框架中的一个关键创新，它通过少量资源冗余换取显著的性能提升。其核心思想是：

专注于关键路径：只优化影响总体完成时间的任务
资源效率权衡：用 1-5%的额外资源换取 30%+的速度提升
概率对抗策略：不试图预测具体哪个任务会慢，而是为所有可能的慢任务准备备份

这一机制充分体现了分布式系统设计的精髓：接受部分失败是不可避免的，并通过冗余和并行执行来优雅地应对它。现代大数据系统普遍采用了这一核心思想，进一步证明了其在大规模分布式计算中的价值。

这篇论文除了 Mapper 和 Reducer 这两个基本的原语，该系统还提供了一些后面事实上也成为了公认的标配的扩展原语：Partitioner、Combiner 和 Reader/Writter。

Partitioning Function

MapReduce 中的分区函数(Partitioning Function)，这是 MapReduce 框架中的重要扩展机制。

核心概念

分区函数是 MapReduce 中连接 Map 和 Reduce 阶段的关键组件，它决定了哪些中间键值对被发送到哪个 Reduce 任务。

// 分区函数的基本定义
type PartitionFunc func(key interface{}, numPartitions int) int

核心作用:

确定 Map 输出的中间键值对分配给哪个 Reduce 任务处理，最终影响输出文件组织
控制最终输出文件的数量和内容组织方式
影响数据在集群中的分布和负载均衡

默认哈希分区机制

MapReduce 提供了简单高效的默认分区策略：

// 默认哈希分区实现
public int getPartition(K key, V value, int numReduceTasks) {
    return (key.hashCode() & Integer.MAX_VALUE) % numReduceTasks;
}

特点:

简单高效: 计算开销小，适用于大多数场景
相对均衡: 通过哈希函数将键均匀分散到各分区
确定性: 相同键总是映射到相同分区，保证聚合正确性

数据流程示意图:

    Map输出          分区函数            Reduce任务
 [K1:V1, K2:V2]    hash(K) % R    ->    Reduce-0
 [K3:V3, K4:V4]                   ->    Reduce-1
 [K5:V5, K6:V6]                   ->    Reduce-2
       ...                               ...

自定义分区函数的使用场景

论文指出，某些场景下需要特定的分区逻辑，例如处理 URL 数据时希望同一主机的 URL 都进入同一个输出文件 6。

当然不止这个，还可以根据地理位置分区。

现代 MapReduce 框架中的分区扩展

现代分布式计算框架在 Google 原始 MapReduce 的分区函数基础上进行了多种扩展：

Hadoop 中的分区器实现

// Hadoop TotalOrderPartitioner示例
// 用于全局排序的分区器
public class TotalOrderPartitioner, V>
    extends Partitioner {

    private TrieNode trie;  // 采用Trie树存储分割点
    private K[] splitPoints;   // 数据分割点

    @Override
    public int getPartition(K key, V value, int numPartitions) {
        return trie.findPartition(key);
    }

    // 使用采样数据初始化分区分割点
    public void setConf(Configuration conf) {
        // 从分布式缓存加载采样数据
        Path partFile = new Path(TotalOrderPartitioner.getPartitionFile(conf));
        // 初始化trie和分割点
        // ...
    }
}

范围分区

// 范围分区器伪代码
func RangePartitioner(key interface{}, boundaries []interface{},
                     numPartitions int) int {
    // 使用二分查找确定键值落在哪个范围
    index := sort.Search(len(boundaries), func(i int) bool {
        return compareKeys(key, boundaries[i]) < 0
    })

    return index
}

// 初始化时进行数据采样确定分区边界
func determinePartitionBoundaries(sampleSize int, numPartitions int) []interface{} {
    samples := collectRandomSamples(sampleSize)
    sort.Sort(samples)

    // 选择均匀分布的分割点
    boundaries := make([]interface{}, numPartitions-1)
    for i := 0; i < numPartitions-1; i++ {
        boundaries[i] = samples[(i+1)*sampleSize/numPartitions]
    }

    return boundaries
}

范围分区的优势:

保留顺序关系，便于范围查询
适用于有序数据集的处理
支持数据倾斜优化

分区策略与数据倾斜

分区函数的选择直接影响数据分布均衡性，不合理的分区可能导致严重的数据倾斜问题，比如下面这种情况：

// 数据倾斜示例
数据集: 1000万用户行为记录
键分布: 90%的记录来自10%的热门用户

使用用户ID直接哈希:
- Reducer-1: 处理2,000万条记录 (热门用户集中)
- Reducer-2: 处理200万条记录
- ...
- Reducer-10: 处理100万条记录

那么我可以应对的分区策略如下：

// 组合键分区策略
public class BalancedPartitioner extends Partitioner {
    @Override
    public int getPartition(Text key, Text value, int numReduceTasks) {
        String originalKey = key.toString();

        // 检测热点键
        if (isHotKey(originalKey)) {
            // 为热点键添加随机前缀以分散负载
            int randomSuffix = ThreadLocalRandom.current().nextInt(numReduceTasks);
            return randomSuffix;
        } else {
            // 非热点键使用正常哈希
            return (originalKey.hashCode() & Integer.MAX_VALUE) % numReduceTasks;
        }
    }

    private boolean isHotKey(String key) {
        // 根据预先统计或采样识别热点键
        // 实际应用中可能使用布隆过滤器等数据结构
        return HOT_KEYS_SET.contains(key);
    }
}

分区函数在 MapReduce 执行流程中的位置角色

分区函数在 MapReduce 执行过程中的位置和作用：

Map阶段      →     分区阶段     →     Shuffle阶段    →    Reduce阶段
(数据处理)        (分区函数)        (网络传输)         (聚合处理)

Map输出        分区键值对         分组排序           Reduce处理
    →  Partition(K1)=0  →  传送到Reducer-0  →  所有相同键
       Partition(K2)=1     传送到Reducer-1     在同一Reducer处理
...           ...                 ...

执行细节:

Map 任务完成键值对处理后，调用分区函数确定每个键值对的目标分区
按分区将键值对写入本地磁盘（为每个分区生成一个临时文件）
Reduce 任务从多个 Map 任务获取属于其分区的所有数据
分区函数保证相同键的所有值都被发送到同一个 Reduce 任务

高级分区技术和最佳实践

实际上，我还发现了一些新的分区技术。

自适应分区

核心思想：根据实际数据分布动态调整分区决策，是处理不均匀数据的有效方法。

工作原理

分为两个阶段，

第一阶段：数据分析阶段，此阶段主要功能：

收集键频率统计：记录每个键出现的次数
数据分布分析：识别热点键和数据倾斜情况
生成分区策略：根据分析结果，计算最优分区策略

第二阶段：优化执行阶段，此阶段主要功能：

应用优化策略：基于第一阶段统计结果的分区决策
动态负载均衡：跟踪分区负载，动态调整热点键分配
实际数据处理：执行业务逻辑处理

热点键识别与处理策略

热点键识别是自适应分区的关键环节：

热点键处理策略：

散列扩展：将单个热点键扩展为多个逻辑键
动态负载均衡：实时监控并平衡各分区的数据量
键重组合并：将多个低频键合并处理

这一块还有太多太多可以讲的东西了，一些实际情况中要遇到的挑战。

混合分区策略

比如可以使用 url、timestamp 时间戳、geopoint 地理网格分区。现代流处理系统（如 Kafka、Flink）中的分区概念与 MapReduce 密切相关；

Ordering Guarantees（MapReduce 排序保证）

排序保证的核心

MapReduce 框架确保同一分区内的中间键值对按键递增顺序处理。这是框架提供的重要保证，不需要开发者额外编码实现。

技术实现与优势

实现机制：

Map阶段 → 分区 → 排序 → 归并 → Reduce处理
               ↑       ↑
             框架自动完成

这种排序保证带来两大关键优势：

高效随机访问：生成的文件可支持二分查找等快速检索

// 有序文件随机查找示例
position = binarySearch(file, targetKey)
record = file.seek(position)

连续键处理：便于流式处理、时间序列分析等场景

// 连续键处理示例
currentKey = null
for (key, value) in sortedData:
    if key != currentKey:
        // 处理键边界
    // 处理当前记录

实际应用示例

构建索引系统：搜索引擎倒排索引生成

时间序列数据处理：有序事件日志分析

// 时间序列事件检测
T1: 用户登录
T2: 查看商品
T3: 添加购物车
T4: 购买
// 有序数据使模式识别更简单

增量导出和更新：按时间戳排序的变更记录

MapReduce 的这一排序保证，加上分区机制，为大规模数据处理提供了强大而灵活的框架基础，使各种复杂数据处理变得简单高效。

Combiner Function

核心概念与工作原理

Combiner 是 MapReduce 框架的关键优化组件，在 Map 端执行部分数据聚合，减少网络传输量。

工作流程:
Map输出 → Combiner本地聚合 → 网络传输 → Reducer最终聚合

适用条件：

Map 输出的中间键有大量重复
Reduce 函数具有可交换和可结合性（如求和、求最大值）

性能优势示例

以单词计数为例：

无Combiner时:
Map1输出: <"hello",1>, <"world",1>, <"hello",1>, <"hello",1> // 4条记录传输
Map2输出: <"hello",1>, <"hadoop",1>, <"hello",1> // 3条记录传输
总网络传输: 7条记录

使用Combiner后:
Map1输出: <"hello",3>, <"world",1> // 2条记录传输
Map2输出: <"hello",2>, <"hadoop",1> // 2条记录传输
总网络传输: 4条记录 (减少43%)

对于遵循 Zipf 分布的数据(如单词频率)，Combiner 可显著减少网络传输，提升性能。

与 Reduce 的区别

Reducer 输出写入最终结果文件
Combiner 输出写入中间文件，随后传输给 Reducer

Combiner 是 MapReduce 框架提高数据处理效率的重要优化手段，通过"预聚合"显著减少数据传输量和处理时间，对于聚合类操作尤为有效。

Input and Output Types

支持不同的输入数据的格式。如下所示：

1. TextInputFormat（默认）
   - 每行作为一个记录
   - 键: 行偏移量(LongWritable)
   - 值: 行内容(Text)
   - 智能分片: 确保在行边界分割

2. KeyValueTextInputFormat
   - 按分隔符(默认Tab)将每行分为键值
   - 适用: 简单结构化文本数据

3. SequenceFileInputFormat
   - 读取二进制序列文件(键值对)
   - 支持压缩、高效随机访问
   - 常用于MapReduce作业间传递数据

4. DBInputFormat
   - 从关系数据库读取记录
   - 支持SQL查询作为数据源

这体现了这套框架的灵活性和扩展性。

MapReduce 的输入输出接口设计使其能处理多样化数据源：

- HDFS文件
- 本地文件系统
- S3、Azure Blob等云存储
- HBase、MongoDB等NoSQL数据库
- Kafka流数据

通过实现适当的 InputFormat/OutputFormat，开发者可以将 MapReduce 与几乎任何数据源/目标集成，体现了框架的强大扩展性，使其适用于各种大数据处理场景。

Side-effects

在某些情况下，MapReduce 的用户会发现，一些在 map 和 reduce operator 中生成的辅助文件作为额外输出是很便利的。

我们可以依靠写代码，将这种 side-effects 具有原子性和幂等性。

通常情况下，应用程序会写入一个临时文件，并在该文件完全生成后对其进行原子重命名，重命名该文件。

对副作用有两个基本要求：

原子性(Atomic)：生成过程必须是原子的，通常通过临时文件+重命名实现
幂等性(Idempotent)：操作可重复执行，对任务重试很重要

一些常见的应用

实践中常见应用：

生成调试日志文件
创建优化的索引结构
输出特殊格式数据(如模型文件)
写入监控指标数据

Skipping Bad Records

如其名，跳过错误的记录。

MapReduce 中，确定性崩溃记录是常见挑战：

特定记录导致 Map/Reduce 任务必然失败
无法修复 Bug（如第三方闭源库问题）
少量记录丢失在大规模统计分析中可接受

工作流程：
1. 检测 → 2. 报告 → 3. 识别 → 4. 跳过

应用场景

此机制特别适用于：

大规模数据清洗：个别格式异常记录不阻塞整体处理
第三方库集成：处理外部组件对特定输入的脆弱性
容忍数据不完整：统计分析允许小比例数据丢失

通过跳过机制，MapReduce 提升了框架容错性，确保作业能够在面对局部数据问题时继续完成，这对生产环境中的大规模数据处理至关重要 1 2.

Status Information

MapReduce Master 节点提供内置 HTTP 服务器，展示作业执行状态和各项指标。

核心监控指标

状态页面展示的关键信息：

- 任务计数：已完成/进行中/等待任务数
- 数据量度：输入字节/中间数据字节/输出字节
- 处理速率：字节/秒、记录/秒
- 日志链接：各任务的标准输出和标准错误
- 失败信息：失败节点及其处理的任务

Counters

MapReduce 计数器是一种轻量级分布式统计机制，用于跟踪作业执行过程中的各类事件和指标。

系统实现机制

计数器值的收集与聚合流程：

Worker节点计数 → 定期汇报(ping) → Master聚合 → 最终结果

关键技术点：

分布式收集：计数器值通过心跳消息(ping)附带传输，避免额外通信开销
全局聚合：Master 节点汇总所有成功任务的计数器值
重复消除：消除重复执行(备份任务、失败重试)产生的重复计数
实时展示：当前计数值在 Master 状态页面实时更新

Performance（性能）

论文中提到的两个性能测试代表了 MapReduce 框架应对两种典型大数据处理场景的能力：

测试场景分析

模式搜索测试
：在约 1TB 数据中搜索特定模式
- 这代表了"从大数据集提取少量有价值信息"的计算模式
- 典型应用如日志分析、异常检测、特定记录查找等
大数据排序测试
：对约 1TB 数据进行排序
- 这代表了"将数据从一种表示转换为另一种表示"的计算模式
- 典型应用如 ETL 过程、数据预处理、重组数据等

下面将会从五个角度对整套 mapreduce 分布式框架，进行性能分析：

Cluster Configuration
Grep
Sort
Effect of Backup Tasks
Machine Failures

Cluster Configuration（集群配置分析）

先是给定了一个集群配置：

// 集群配置概要
type ClusterConfig struct {
    Nodes           int     // 约1800台机器
    CpuPerNode      int     // 每节点2个2GHz Intel Xeon (支持超线程)
    MemoryPerNode   string  // 每节点4GB (实际可用2.5-3GB)
    DisksPerNode    int     // 每节点2个160GB IDE磁盘
    NetworkBandwidth string  // 千兆以太网
    NetworkTopology string   // 两级树状交换网络
    RootBandwidth   string   // 100-200Gbps聚合带宽
    Latency         string   // 节点间<1ms延迟
}

分析：

这是一个计算和 I/O 能力均衡的集群设计，特别适合 MapReduce 的分治模型
存储层面，每节点有超过 300GB 的总存储空间，对于 TB 级数据处理提供了足够的本地存储
网络层面采用树状拓扑，虽然简单但可能在 shuffle 阶段形成瓶颈
节点间低延迟(<1ms)对 reduce 阶段的数据传输极为有利
集群规模(1800 节点)使得处理 TB 级数据时能够有效并行化

Grep

这是典型的"从海量数据中提取少量信息"场景：

// Grep任务配置
type GrepJobConfig struct {
    InputSize       string  // 约1TB (10^10条100字节记录)
    Pattern         string  // 三字符模式(匹配92,337条记录)
    InputSplits     int     // M=15000(每块约64MB)
    ReduceTasks     int     // R=1(单一输出文件)
    PeakScanRate    string  // >30GB/s(1764个workers时)
    TotalTime       int     // 约150秒(包括60秒启动开销)
}

性能分析：

扩展性表现：从图表 2 看出，随着 worker 数量增加，扫描率线性提升至 30GB/s，表明 MapReduce 在 map 密集型任务上有优秀的水平扩展能力
I/O 绑定特性：Grep 本质上是 I/O 密集型工作，测试达到 30GB/s 的吞吐率接近理论上 1764 个节点的磁盘 I/O 总和上限
优化机会：约 60 秒的启动开销(占总时间 40%)显示了一个优化点 - GFS 元数据操作和任务分发可进一步优化
R=1 设计：单 reduce 设计适合这种"过滤"场景，但也意味着最终结果汇集可能成为瓶颈(本例数据量小，未表现出来)

Sort

整个 MapReduce 框架能力的综合测试：

// Sort任务特征分析
type SortJobAnalysis struct {
    InputSize       string  // 约1TB (10^10条100字节记录)
    InputRate       string  // 峰值13GB/s(低于Grep因需写中间数据)
    ShufflePattern  string  // 两阶段模式，与reduce任务分批相关
    OutputRate      string  // 2-4GB/s(双副本写入，实际物理写入4-8GB/s)
    MapTasks        int     // M=15000(每块约64MB)
    ReduceTasks     int     // R=4000(分区策略利用键分布知识)
    TotalTime       int     // 891秒(接近TeraSort基准1057秒)
}

技术分析：

数据流水线：测试清晰展示 MapReduce 三阶段流水线 - map 阶段(0-200 秒)、shuffle 阶段(200-600 秒)和 reduce 阶段(600-850 秒)
资源瓶颈转移：
- 0-200 秒：瓶颈在磁盘 I/O 和 CPU(解析数据)
- 200-600 秒：瓶颈转为网络带宽(shuffle)
- 600-850 秒：瓶颈为排序计算和输出磁盘 I/O
局部性优化效果：输入率(13GB/s)高于 shuffle 率的主因是数据局部性优化，大部分读取走本地磁盘而非网络
复制开销：输出率(2-4GB/s)较低主要因为 GFS 双副本策略，实际物理写入是这个速率的两倍

Effect of Backup Tasks

图 3 还能看到一些东西：

// 备份任务影响分析
type BackupTaskAnalysis struct {
    WithBackup      int     // 正常执行，总时间891秒
    WithoutBackup   int     // 1283秒，增加44%
    StragglerDelay  int     // 最后5个reduce任务额外花费300秒
    EfficiencyGain  string  // 备份任务机制提高44%性能
}

专业解读：

掉队者问题严重性：数据清晰展示了分布式系统中"掉队者问题"(straggler problem)的严重性 - 仅 5 个慢任务就使总时间增加 44%
根本原因分析：掉队者通常源于：
- 硬件异常(如磁盘性能下降、内存错误)
- 资源竞争(如其他进程干扰)
- 数据倾斜(某些 reduce 任务处理数据量显著多于其他)
云原生环境意义：在共享资源的云环境中，掉队者问题更加普遍，备份任务机制是确保性能可预测性的关键

Machine Failures

图 3 还能看到

// 故障恢复能力分析
type FaultToleranceAnalysis struct {
    NodesKilled     int     // 200个(约11.5%的节点)
    RecoveryPattern string  // 短暂的负输入率，然后快速恢复
    TotalTime       int     // 933秒，仅增加5%
    KeyMechanism    string  // 自动检测失败并重新执行任务
}

分析：

失败影响可视化：图表中的负输入率直观地展示了节点故障如何导致已完成工作的丢失和重做需求
快速恢复原理：
- 任务状态追踪：master 节点持续追踪每个任务的状态
- 心跳检测：通过周期性心跳检测 worker 失败
- 任务重新调度：将失效节点的任务重新分配给健康节点
- 冗余执行：关键是 MapReduce 设计让任何节点都能处理任何任务
对比传统系统：传统 MPP 数据库在 11%节点故障时通常会完全失败或性能下降 50%以上，MapReduce 的 5%性能损失凸显其卓越的容错能力

Experience

这段内容摘自 Jeff Dean 和 Sanjay Ghemawat 的 MapReduce 论文，详细描述了 MapReduce 在 Google 内部的早期发展历程和应用情况。

技术发展历程

MapReduce 库的首个版本开发于 2003 年 2 月，并在同年 8 月进行了重大增强 1，包括：

局部性优化（locality optimization）
跨工作节点的任务执行动态负载平衡
其他性能优化

应用领域广泛性

MapReduce 在 Google 内部得到了广泛应用，涵盖多个领域：

大规模机器学习问题
Google News 和 Froogle（早期的 Google Shopping）产品的聚类问题
流行查询报告数据提取（如 Google Zeitgeist）
从大规模网页语料库中提取属性（如用于本地化搜索的地理位置）
大规模图计算

爆发式增长

从图表可以看出，MapReduce 在 Google 内部的使用呈现指数级增长：

2003 年初：接近 0 个实例
2004 年 9 月底：接近 900 个实例

这种快速增长表明 MapReduce 在 Google 内部获得了极高的认可和应用价值。

成功原因分析

MapReduce 取得成功的关键因素：

简化分布式计算：使开发者能够编写简单程序并在数千台机器上高效运行
加速开发周期：大幅缩短开发和原型设计周期
降低技术门槛：让没有分布式/并行系统经验的程序员也能轻松利用大规模计算资源

规模与效率分析（2004 年 8 月数据）

从表格数据可以得出以下见解：

使用广泛：单月内执行了 29,423 个 MapReduce 作业
处理效率高：平均作业完成时间为 634 秒（约 10.5 分钟）
计算规模大：
- 使用了相当于 79,186 天的机器计算时间
- 处理了 3,288 TB 的输入数据
- 产生了 758 TB 的中间数据
- 输出了 193 TB 的结果数据
任务分布特征：
- 每个作业平均使用 157 台工作机器
- 平均每个作业有 1.2 次工作节点失效（表明系统具有良好的容错能力）
- 平均每个作业有 3,351 个 map 任务和 55 个 reduce 任务
代码复用性：
- 395 个独特的 map 实现
- 269 个独特的 reduce 实现
- 426 个独特的 map/reduce 组合

Large-Scale Indexing

MapReduce 在 Google 网络搜索索引系统中的应用，这是 MapReduce 最重要的应用案例之一。

Google 搜索索引系统概述

Google 使用 MapReduce 重写了其整个生产索引系统，该系统负责生成 Google 网络搜索服务所需的数据结构 1。这个索引系统具有以下特点：

输入数据：来自爬虫系统抓取的大量网页文档，存储在 GFS (Google File System) 文件中
数据规模：原始内容超过 20TB
处理流程：索引过程由 5-10 个 MapReduce 操作序列组成

有机会我再去看一下这套系统的设计，再进一步做一下分析。

MapReduce 和一些其他的并行计算系统的对比分析

MapReduce 的关键优势在于：

受限但强大的编程模型：通过限制编程模型，实现了自动并行化和透明的容错机制
大规模扩展能力：能扩展到数千个处理器的规模
自动处理机器故障：对比其他系统将故障处理细节留给程序员

特性设计

局部性优化 (Locality Optimization)
MapReduce 的局部性优化借鉴了主动磁盘 (Active Disks) 技术：
- 核心思想：将计算推送到靠近本地磁盘的处理元素，减少通过 I/O 子系统或网络发送的数据量
- 实现差异：MapReduce 在直接连接少量磁盘的普通处理器上运行，而非直接在磁盘控制器处理器上运行
- 优势：显著减少网络传输，提高大规模数据处理效率
备份任务机制 (Backup Tasks)
这一机制类似于 Charlotte 系统中的积极调度机制 (eager scheduling)：
- 创新点：MapReduce 增加了跳过错误记录的机制，解决了简单积极调度中反复失败导致整个计算无法完成的问题
- 实现方式：当任务接近完成时，调度冗余执行的任务，大大减少了非均匀性（如慢速或卡住的工作节点）对完成时间的影响
集群管理系统
MapReduce 实现依赖于内部集群管理系统：
- 功能：负责在大量共享机器上分发和运行用户任务
- 类似系统：Condor 等工作负载管理系统

与其他系统的技术比较

MapReduce vs. NOW-Sort
MapReduce 的排序功能在操作上类似于 NOW-Sort：
- 相似点：源机器（map worker）对数据进行分区并将其发送给 R 个 reduce worker，每个 reduce worker 在本地排序
- 差异点：MapReduce 具有用户可定义的 Map 和 Reduce 函数，使其应用范围更广
MapReduce vs. River
River 提供了一种进程通过分布式队列发送数据进行通信的编程模型：
```
- **共同目标**：在异构硬件或系统扰动引入的不均匀性存在的情况下，提供良好的平均情况性能
```
- 实现方法差异：
  - River：通过谨慎调度磁盘和网络传输来实现平衡的完成时间
  - MapReduce：通过限制编程模型，将问题划分为大量细粒度任务，并在可用工作节点上动态调度这些任务，使得更快的工作节点处理更多任务
MapReduce vs. BAD-FS
尽管编程模型完全不同，且 BAD-FS 针对广域网执行作业，两者仍有根本相似之处：
1. 都使用冗余执行来从故障引起的数据丢失中恢复
2. 都使用位置感知调度来减少通过拥塞网络链路发送的数据量
MapReduce vs. TACC
TACC 是一个旨在简化高可用网络服务构建的系统：
- 共同点：都依赖重新执行作为实现容错的机制

技术创新总结

MapReduce 的主要技术创新可归纳为以下几点：

简化的并行编程模型：通过限制编程模型，使框架能够自动处理并行化和容错
大规模容错实现：扩展到数千处理器规模，自动处理机器故障
细粒度任务分解：将问题分解为大量细粒度任务，实现更好的负载均衡和故障恢复
动态任务调度：根据工作节点的速度动态分配任务，优化整体性能
冗余执行优化：在作业结束时调度冗余任务，显著减少在存在非均匀性情况下的完成时间

这些创新和设计选择使 MapReduce 成为一个独特而强大的分布式计算框架 1，它不仅借鉴了以前系统的优点，还通过简化的编程模型和自动化的故障处理解决了大规模分布式计算的关键挑战。MapReduce 的设计思想后来极大地影响了 Hadoop 等开源大数据处理框架的发展 5，成为现代大数据处理的基础。

Conclusions（结论）

嗯是的，这篇论文为什么这么有名，论文的 conclusions 也讲清楚了。如下：

MapReduce 成功的三大关键因素

1. 简单易用的编程模型

MapReduce 的首要成功因素是其简洁的编程接口：

// 用户只需定义这两个函数，无需关心分布式系统复杂性
func Map(key, value string) []KeyValue { /* 用户定义的映射逻辑 */ }
func Reduce(key string, values []string) string { /* 用户定义的归约逻辑 */ }

这种设计对开发者极为友好，因为它：

隐藏了并行化的复杂细节
自动处理容错机制
内置了局部性优化
提供了透明的负载均衡

这使得即使没有分布式系统经验的程序员也能轻松编写高效的分布式程序 1。

2. 强大的表达能力

MapReduce 模型能够轻松表达各种不同类型的计算问题，在 Google 内广泛应用于：

网络搜索服务数据生成
大规模排序
数据挖掘
机器学习
其他众多系统

这种通用性使 MapReduce 成为 Google 内部的基础计算框架 1。

3. 出色的扩展性

MapReduce 实现能够扩展到包含数千台机器的大型集群：

// 伪代码：MapReduce调度过程
func Schedule(input []string, mappers int, reducers int) Result {
    // 自动处理:
    // 1. 任务分配与并行化
    // 2. 机器故障检测与恢复
    // 3. 数据本地性优化
    // 4. 中间结果管理
}

这使其能够高效处理 Google 遇到的大规模计算问题，为大数据处理奠定了基础 3。

研究团队的三大关键经验

1. 受限编程模型的价值

研究表明，通过有意识地限制编程模型，可以获得巨大的系统优势：

易于并行化和分布计算
自然地实现容错机制
降低开发和维护成本

这种"少即是多"的理念，与其他尝试提供完全通用并行编程环境的系统形成鲜明对比 1。

2. 网络带宽是稀缺资源

研究团队发现网络带宽是分布式系统中的宝贵资源，因此许多优化都针对减少网络传输：

局部性优化：优先从本地磁盘读取数据，减少跨网络数据传输
本地中间数据存储：将中间结果写入本地磁盘而非分布式存储，节省网络带宽

这些设计在大规模集群中特别重要，因为数据传输可能成为系统瓶颈 1 3。

3. 冗余执行的重要性

冗余执行是 MapReduce 的一项关键创新，用于：

减少慢速机器（stragglers）的影响
优雅处理机器故障
防止数据丢失

// 伪代码：MapReduce中的冗余任务调度
func scheduleBackupTasks(slowTasks []Task) {
    for _, task := range slowTasks {
        if time.Now() - task.StartTime > slowThreshold {
            // 在另一台机器上启动相同任务的备份副本
            launchDuplicateTask(task)
        }
    }
}

这种机制显著提高了大型分布式系统的可靠性和性能一致性 3 5。

MapReduce 的技术遗产

MapReduce 论文的结论揭示了它不仅仅是一个技术创新，更是一种全新的大规模数据处理范式：

架构思想影响：MapReduce 的设计理念影响了后来的 Hadoop、Spark 等众多大数据处理框架
编程模型革新：证明了简化的编程模型可以解决复杂的分布式计算问题
工程实践变革：改变了构建大规模数据处理系统的方法，从专家系统转变为通用框架
商业价值创造：为后来的大数据生态系统奠定了基础，创造了巨大的商业价值 4 5

总的来说，MapReduce 通过简单而强大的抽象，成功解决了大规模分布式数据处理的核心挑战，使得处理海量数据变得触手可及，这也是为什么它在 Google 内部和整个行业中都取得了巨大成功的根本原因。

References

[1] [MapReduce: Simplified Data Processing on Large Clusters](https://www.qtmuniao.com/2019/04/30/map-reduce/)

高并发API管理场景下的网关架构设计

cheverjonathan@gmail.com (Chenwei Jiang) — Thu, 27 Feb 2025 00:00:00 GMT

整体架构设计原则

在高并发 API 管理场景下，网关架构需要遵循以下核心设计原则：

分层架构设计
```
流量入口层 → 处理层 → 路由层 → 后端服务层
```
采用严格分层的架构，每一层关注点分离，使系统更易于横向扩展和纵向优化
无状态设计
设计无状态的网关节点，确保任何网关实例都能处理任何请求，这是支撑高并发的基础。会话状态与用户信息应存储在分布式缓存或专门的状态存储系统中。

高性能技术栈选择

底层技术选型
1. 数据面：基于高性能代理如 Envoy、NGINX 或基于 Go/Rust 自研组件
2. 控制面：采用高效的配置管理和服务发现机制
异步 IO 模型
1. 采用非阻塞 IO 模型(如 Go 的 goroutine+channel、Rust 的 tokio、Node.js 的事件循环)
2. 避免使用传统的线程池模型，减少上下文切换开销

多级缓存架构

全局分布式缓存层

客户端 → CDN → 边缘缓存 → API网关本地缓存 → 服务缓存

多维度缓存策略
1. 路由信息缓存：本地高速缓存+定期更新
2. 认证信息缓存：分布式令牌验证结果缓存
3. 响应数据缓存：基于内容特性的智能缓存策略

动态扩缩容设计

灵活的部署架构

多区域 → 多可用区 → 多集群 → 多实例

弹性伸缩策略
1. 预测式扩容：基于历史流量模式预测扩容需求
2. 反应式扩容：根据实时指标(CPU、内存、请求队列深度)触发扩容
3. 平滑缩容：确保连接优雅关闭和请求完成处理

高效流量控制机制

多级限流设计

flowchart LR
    Client --> GlobalLimit[全局限流层]
    GlobalLimit --> ServiceLimit[服务级限流]
    ServiceLimit --> APILimit[API级限流]
    APILimit --> UserLimit[用户级限流]
    UserLimit --> Backend[后端服务]

自适应流控算法
1. 令牌桶+漏桶组合：解决突发流量与稳定流量的平衡
2. 基于请求优先级的差异化处理：核心 API 优先保障
3. 自适应限流：基于后端服务健康度动态调整限流阈值

网关集群高可用设计

多区域部署架构
1. 地理级别冗余：跨区域部署确保区域级故障隔离
2. 就近接入：智能 DNS 或全局负载均衡实现流量就近接入4
故障隔离策略
```
客户端分组 → 网关实例分组 → 后端服务分组
```
1. 舱壁模式：将客户端请求隔离到不同的网关实例组
2. 熔断机制：智能熔断设计，基于错误率、延迟等多维度指标
3. 降级策略：定义清晰的服务降级路径和回退机制

请求处理优化

请求处理流水线

接收请求 → 认证授权 → 请求转换 → 路由决策 → 负载均衡 → 后端调用 → 响应处理

性能优化技术
1. 批处理：合并碎片化请求减少网络往返
2. 请求折叠：合并对相同资源的并发请求1
3. 并行处理：跨服务请求并行化处理
4. 响应流式处理：大型响应的流式传输
5. 零拷贝技术：减少数据复制环节

高效通信协议

协议支持和优化
1. HTTP/2 多路复用：减少连接建立开销
2. gRPC 支持：高效二进制传输与流处理
3. WebSocket 优化：长连接管理与心跳机制
连接池管理
1. 动态调整的后端连接池
2. 长连接复用与保活策略
3. 连接预热机制避免冷启动延迟

全链路可观测性

多维度监控体系

基础设施指标 → 网关性能指标 → API调用指标 → 业务指标

实时监控与预警
1. 健康检查：主动和被动健康检测结合
2. 性能分析：请求延迟分布、队列深度等关键指标
3. 异常检测：基于机器学习的异常行为识别

配置热更新机制

动态配置架构
1. 分布式配置中心+本地缓存
2. 配置变更事件通知机制
3. 增量配置更新减少资源消耗
灰度发布能力
1. 配置变更的金丝雀发布
2. 流量迁移的平滑切换
3. 紧急回滚机制

微服务架构下的挑战：API网关的救赎之路

cheverjonathan@gmail.com (Chenwei Jiang) — Fri, 27 Dec 2024 00:00:00 GMT

在日常上网冲浪的时候看到一篇文章，结合公司实际业务有感。

面临挑战

这篇文章大概讲述了在微服务架构下客户端应用如何访问微服务的问题。主要面临以下挑战：

API 粒度不匹配：微服务通常提供细粒度 API，而客户端需要综合数据，导致客户端需要与多个服务交互
客户端需求差异：不同客户端（桌面浏览器、移动端、第三方应用）需要不同的数据结构和量
网络性能差异：移动网络通常比内网慢且延迟高，影响用户体验
服务实例动态变化：服务实例数量和位置（主机+端口）会不断变化
协议多样性：后端服务可能使用不同协议，有些对 Web 不友好

具体细节就不补充了。可以私聊 hhhhhh 交流。

解决方案

然后作者给出了他的解决方案，就是实现 API Gateway 模式：

实现统一入口：设计一个 API 网关作为所有客户端的单一入口点
请求处理方式：
- 简单代理/路由请求到对应服务
- 扇出请求到多个服务并聚合结果
客户端特定 API：为不同客户端提供定制化 API，而非一刀切方案
实现横切关注点：加入认证、授权、SSL 终止、缓存等功能

文章还介绍了一个变种：Backends for frontends(BFF) 模式，即为每种客户端类型（Web 应用、移动应用、第三方应用）设计专用 API 网关。

个人分析：

优点

集中化管理：所有 API 流量通过单一入口，便于统一监控、追踪和治理

在某金融机构实施后，安全事件响应时间从小时级降至分钟级，因为所有可疑流量都能在网关层快速识别。

横切关注点统一实现：认证、授权、限流等功能只需在网关层实现一次

协议转换与聚合：将内部多种协议转换为统一外部接口，减少客户端请求次数，某电商将 7 次独立调用合并为 1 次聚合 API，移动端加载时间减少 68%。

解耦实现：客户端与微服务内部结构解耦，服务可独立演进而不影响客户端

流量控制：具备智能路由、负载均衡、熔断降级能力，提高系统弹性

上面这些内容都是老生常谈的了。

缺点

潜在单点故障：所有流量依赖单一组件，若设计不当可能成为系统瓶颈，当燃这个就得看高可用分布式架构师的能力啦～

延迟增加：增加额外网络跳转，可能增加响应时间（通常为 5-10ms）

复杂度陡增：随着规模扩大，网关可能变得臃肿且难以维护

一家大型企业的 API 网关积累了超过 200 个定制化处理逻辑，最终导致无人敢修改代码。

团队协作挑战：网关变更需要跨团队协调，可能形成开发瓶颈

适用场景

中小型微服务架构：服务数量适中（10-50 个），客户端类型有限
安全要求高的系统：需要统一安全策略的金融、医疗等领域
混合协议环境：内部服务使用不同协议（REST、gRPC、AMQP 等）
需要统一网关治理：企业级应用需要集中化 API 治理策略

核心功能与实现效果

然后他还给出了他的 API 网关提供三大核心功能：

反向代理/网关路由：使用第 7 层路由重定向 HTTP 请求
请求聚合：将多个内部微服务请求聚合为单个客户端请求
横切关注点与网关卸载：集中实现通用功能

优势

客户端与微服务解耦：隔离客户端与微服务架构细节
提供最优 API：为各类客户端提供定制化 API
减少请求次数：单次请求获取多服务数据，降低网络开销
简化客户端逻辑：复杂调用逻辑从客户端迁移到 API 网关
协议转换：将公共 Web 友好 API 协议转换为内部协议

缺点

增加复杂性：新增一个需要开发、部署和管理的组件
增加响应时间：额外网络跳转可能增加延迟（对大多数应用影响不大）
单点故障风险：单一 API 网关可能成为瓶颈或单点故障

果然和我所想的是一样的。

实际部署策略

┌───────────┐  ┌───────────┐  ┌─────────────┐
│  Web BFF  │  │ Mobile BFF│  │ Third-party │
│           │  │           │  │   BFF       │
└─────┬─────┘  └─────┬─────┘  └─────┬───────┘
      │              │              │
      ▼              ▼              ▼
┌─────────────────────────────────────┐
│        Core API Gateway             │
│    (认证、监控、限流、基础路由)         │
└─────────────────────────────────────┘
      │              │              │
      ▼              ▼              ▼
┌─────────┐     ┌───────────┐     ┌───────────┐
│ 服务集群1│     │ 服务集群2   │     │ 服务集群3  │
└─────────┘     └───────────┘     └───────────┘

规模化考量

小型应用（5-15 个微服务）：
- 推荐：单一 API 网关
- 理由：简单高效，避免过度设计
中型应用（15-50 个微服务）：
- 推荐：基础 API 网关+少量关键 BFF
- 理由：平衡复杂性和客户端优化需求
大型应用（50+微服务）：
- 推荐：完整三层架构（边缘网关+BFF 层+内部网关）
- 理由：支持组织扩展和复杂业务领域

决策要点

选择 API 网关策略时需考虑：

组织结构：Conway 法则表明系统设计往往反映组织结构
扩展预期：考虑 3-5 年内的业务增长和多样化
运维能力：评估团队管理多个网关的能力
一致性需求：业务对 API 行为一致性的要求程度
性能预算：额外网络跳转的延迟影响评估

无论选择何种模式，都应保持网关层轻量化，避免业务逻辑下沉过多导致"智能管道"反模式，并建立良好的监控体系，确保网关层性能与稳定性。

网关性能瓶颈分析与优化技术（私藏）

cheverjonathan@gmail.com (Chenwei Jiang) — Thu, 18 Jul 2024 00:00:00 GMT

2025-03-07 更新：最近小红书的网关实践，我看他们就遵守了下面的好多条。—— 《小红书推出自研 Rust 高性能七层网关 ROFF》

这篇文章分两部分：

性能瓶颈分析方法
上手实际来分析一下 APISIX、Kong、Nginx

性能瓶颈分析方法

性能瓶颈分析方法（真）

这一部分真讲方法。

监控指标分析

延迟指标：监控请求延迟（Latency）和集成延迟（Integration Latency）
错误率指标：监控 4XX 和 5XX 错误率，找出系统故障点
吞吐量指标：请求计数（Count）和每秒请求数（RPS）
缓存命中指标：监控 CacheHitCount 和 CacheMissCount 比率

系统资源监控

CPU 使用率分析
内存消耗分析
网络 IO 监控
磁盘 IO 监控（尤其是日志和缓存）

请求流分析

请求处理链路追踪
热点路径识别
串行处理瓶颈发现

基础架构层面优化

硬件资源优化

增加 CPU 核心数和内存容量
使用 SSD 存储提高 IO 速度
采用高性能网卡降低网络延迟
合理评估和调整容器资源限制（在 Kubernetes 环境中）

网络优化

优化网络拓扑结构
减少网络跳数
使用 CDN 加速静态内容
实施 DNS 优化
网关与后端服务部署在同一网络区域

操作系统调优

调整 TCP/IP 栈参数（如增大连接队列）
优化文件描述符限制
调整内核参数（如 somaxconn、tcpfintimeout）
在 Linux 环境下优化客户端线程数

网关配置层面优化

连接池优化

配置适当的数据库连接池大小（建议至少与预期客户端数量相当）—— Oracle 的数据库管理员必知
调整后端服务连接池参数
设置连接超时和重试策略
实施连接保活机制

HTTP 优化

启用 HTTP keep-alive 重用 TCP 连接 —— oracle 的性能实践
配置合适的 chunked encoding 策略
调整 HTTP 标头大小限制
设置合理的请求/响应超时时间

缓存策略优化

实施响应缓存减少后端调用 —— Amazon 的 api 优化实践
配置缓存键策略和 TTL（存活时间）
实施多级缓存策略
缓存验证和失效策略优化

请求处理优化

并发处理优化

增加工作线程数量
实施异步处理模式
优化线程池配置
使用事件驱动架构处理高并发请求

负载均衡策略

实施智能负载均衡算法（加权轮询、最少连接等）
配置动态负载均衡策略
实施服务健康检查和自动故障转移
根据后端服务能力调整权重

路由优化

优化路由查找算法
实施路由缓存
配置路由预热策略
基于流量特征的智能路由

数据处理优化

消息处理优化

配置"溢出到磁盘"的策略处理大型消息（如设置为>4MB 的消息写入磁盘）3
实施请求/响应压缩1
优化序列化/反序列化过程
减少不必要的数据转换

协议优化

使用 HTTP/2 降低延迟并提高并行处理能力
在适当场景下使用 WebSocket 等长连接协议
考虑使用 gRPC 提高微服务间通信效率
实施协议升级策略

监控与日志优化

日志优化

减少不必要的追踪信息（将生产环境设置为 ERROR 或 FATAL 级别）3
禁用或减少访问日志记录3
禁用事务日志以减轻磁盘 IO 负担3
实施异步日志写入策略

监控优化

禁用实时监控减少开销3
禁用或减少流量监控3
配置合理的监控采样率
实施智能告警阈值，避免监控系统负载过高

安全性能优化

身份验证优化

缓存认证结果
使用轻量级 Token 验证
实施分级认证策略
优化 JWT 处理流程

SSL/TLS 优化

使用 Session 复用减少握手开销
配置 OCSP 装订（Stapling）
实施 TLS 连接池
选择高效加密套件

高级优化策略

熔断与限流

实施请求限流保护后端系统
配置熔断器防止系统过载
实施退避算法处理重试
流量整形优化请求分布

服务网格集成

与 Istio/Envoy 等服务网格集成
下放部分网关功能至边车代理
实施网关与服务网格的协同策略
利用服务网格提供的流量管理能力

架构优化

考虑多级网关架构（边缘网关+内部网关）
实施边缘计算减少延迟
领域驱动的 API 网关设计
基于流量特征的网关分片

通过系统地分析上述各方面的性能瓶颈，并应用相应的优化技术，可以显著提升网关的性能、吞吐量和可靠性。最关键的是要根据实际系统特点和业务需求，选择最合适的优化策略组合，并通过持续监控和调优来保持系统的高性能状态。

上手实际来分析一下

Nginx 网关

主要性能瓶颈

连接处理能力瓶颈
- 默认工作进程配置可能不匹配服务器 CPU 核心数
- 连接池大小限制导致高并发下连接拒绝
- 文件描述符限制引起"too many open files"错误
配置复杂度瓶颈
- 静态配置文件需要手动修改和重新加载
- 大规模路由规则导致配置维护困难
- 配置变更需要重新加载，可能导致请求中断
SSL 处理瓶颈
- SSL 握手开销大，高并发下 CPU 使用率飙升
- 密钥交换算法效率低下
- 会话缓存配置不当导致重复握手

优化方法

工作进程和连接优化
- 将worker_processes设置为与 CPU 核心数匹配
- 增加worker_connections值（通常可设为 4096 或更高）
- 使用worker_cpu_affinity绑定工作进程到特定 CPU 核心
- 调整系统文件描述符限制（ulimit -n）
事件处理优化
- 启用multi_accept和accept_mutex
- 使用epoll事件处理模型（在 Linux 系统上）
- 调整worker_aio_requests提高异步 IO 性能
HTTP 优化
- 配置keepalive_timeout和keepalive_requests参数
- 开启sendfile、tcp_nopush和tcp_nodelay选项
- 实施gzip压缩减少传输数据量
- 设置client_body_buffer_size和client_max_body_size限制请求大小
SSL 性能优化
- 启用ssl_session_cache shared提高会话重用率
- 配置 OCSP stapling 减少握手延迟
- 使用 ECC 证书减少计算开销
- 优先选择高性能加密套件（如 AES-GCM）

Kong 网关

老牌好用网关。

主要性能瓶颈

数据库依赖瓶颈
- PostgreSQL/Cassandra 数据库查询成为性能瓶颈
- 配置变更时数据库压力增大
- 分布式部署下数据库一致性挑战
Lua 脚本处理瓶颈
- 插件执行链过长导致请求延迟增加1
- Lua VM 内存使用不当导致性能下降
- JIT 编译限制影响动态脚本性能
JWT 验证瓶颈
- JWT 验证处理开销大，在高百分位延迟明显2
- 在 99.99 百分位延迟方面，Kong 的延迟可达到 NGINX 的 3 倍2

优化方法

数据库优化
- 使用 DB-less 模式减少数据库依赖
- 增加数据库连接池大小（kong.conf 中的 pg_pool 参数）
- 实施数据库读写分离（主从架构）
- 考虑使用声明式配置而非数据库存储
插件链优化
- 只启用必要的插件，减少处理链长度
- 调整插件执行顺序（高频使用的轻量插件前置）
- 为插件配置独立缓存（如 rate-limiting 插件的 Redis 缓存）
- 监控并优化长耗时插件
缓存优化
- 配置lua_shared_dict缓存大小
- 调整插件级别缓存 TTL
- 使用外部 Redis 缓存提高命中率
- 配置实体缓存减少数据库查询
连接池优化
- 调整 upstream_keepalive 参数（通常设置为 100-200）
- 增加 nginxupstreamkeepalive_timeout 值
- 设置合理的 nginxupstreamkeepalive_requests 值
- 增加 nginxhttpclientbodybuffer_size 处理大请求体

APISIX 网关

主要性能瓶颈

etcd 依赖瓶颈
- etcd 集群稳定性影响网关配置传播
- 配置变更频繁导致 etcd 压力增大
- etcd 读写延迟影响动态路由更新
路由匹配瓶颈
- 大量精细化路由导致匹配延迟增加
- 复杂正则表达式路由降低匹配效率
- 路由缓存更新不及时导致路由错误

优化方法

etcd 优化
- 构建高可用 etcd 集群
- 优化 etcd 配置（如设置合理的心跳间隔）
- 实施 etcd 分片减轻单节点压力
- 增加 config_center.timeout 参数值（默认 30 秒）
路由优化
- 使用前缀匹配代替完全正则表达式
- 增加路由缓存 TTL
- 减少路由规则复杂度，拆分过于复杂的规则
- 使用域名或主机名前置过滤

Envoy 网关

主要性能瓶颈

xDS 配置更新瓶颈
- 动态配置更新导致资源再分配开销
- Control Plane 通信延迟影响配置下发
- 大量监听器和集群配置导致内存占用高
过滤器链处理瓶颈
- HTTP 过滤器链过长导致处理延迟增加
- 复杂过滤逻辑导致 CPU 使用率高
- Lua 过滤器执行效率低于原生过滤器

优化方法

xDS 配置优化
- 实施增量 xDS 减少配置更新开销
- 优化 Control Plane 通信（如使用 gRPC 流而非轮询）
- 设置合理的配置缓存 TTL
- 使用聚合发现服务(ADS)确保配置一致性
过滤器优化
- 减少过滤器链长度，仅保留必要过滤器
- 优先使用原生 C++过滤器而非 Lua 或 WASM
- 调整过滤器执行顺序（高频执行的前置）
- 为关键过滤器启用统计监控

不同网关性能对比与选择建议

性能对比

在标准 API 调用测试中，NGINX API 管理模块的性能可达到 Kong 的 2 倍以上数据支撑
在延迟方面，NGINX 添加的延迟比 Kong 低 20-30%数据支撑
在 CPU 效率方面，NGINX 比 Kong 高效 40%左右数据支撑
在 JWT 验证场景下，NGINX 可处理的 API 调用数是 Kong 的 2 倍以上数据支撑

选择建议

NGINX 适合场景：
- 静态路由配置的稳定 API 网关需求
- 以性能和低延迟为首要考量的场景
- 资源受限环境下的轻量级网关需求
- 主要提供反向代理和负载均衡功能
Kong 适合场景：
- 需要丰富 API 管理功能（身份验证、限流、转换等）
- 追求开发便利性的团队（RESTful API 配置）
- 具有动态路由需求的微服务架构
- 可以承受一定性能损失换取功能丰富性
APISIX 适合场景：
- 追求动态路由与高性能平衡的团队
- 有服务发现集成需求的云原生架构
- 需要细粒度流量控制的场景
Envoy 适合场景：
- Kubernetes/Istio 服务网格基础架构
- 需要高级可观测性的现代云架构
- 追求可编程性和扩展性的 DevOps 团队

通过理解不同网关的性能瓶颈特点和优化方法，您可以根据自身业务特点和技术栈选择最适合的网关类型，并实施有针对性的性能优化，以获得最佳的网关性能与功能平衡。

总结

网关性能优化是一个系统性的工作，需要从多个层面进行分析和优化。通过以上提供的分析方法、优化技术和代码示例，您可以针对不同的性能瓶颈进行有针对性的优化。关键在于:

建立完善的性能监控系统，及时发现性能瓶颈1
采用多级缓存策略减少重复计算和网络请求
优化连接池管理，提高连接复用效率
实现高效的负载均衡算法，智能分发请求
使用定期基准测试，持续评估和优化性能

对于云原生环境中的网关，还可以考虑利用Kubernetes的自动扩缩容能力，动态调整网关实例数量以应对流量变化。

内核是如何接受网络包的

cheverjonathan@gmail.com (Chenwei Jiang) — Tue, 27 Feb 2024 00:00:00 GMT

整体一览图

感谢张彦飞大佬的图。

在你基本上了解了什么是网卡驱动、硬中断、软中断和 ksoftirqd 线程之后，可以给出一个如上图所示的内核收包的路径示意图。

大致过程如下：

当网卡收到数据之后，以 DMA 的方式把网卡收到的帧写到内存里，再向 CPU 发起一个中断，以通知 CPU 有数据到达。
当 CPU 收到中断请求之后，会去调用网络设备驱动注册的中断处理函数。
网卡的中断处理函数并不做过多工作，发出软中断请求，然后尽快释放 CPU 资源。
ksoftirqd 内核线程检测到有软中断请求到达，调用 poll 开始轮询收包，收到后交由各级协议栈处理。对于 TCP 包来说，会被放到用户 socket 的接收队列中。

做一切之前的基础准备工作

Linux 驱动、内核协议栈等模块在能够接收网卡数据包之前，要做很多的准备工作才行。如下：

提前创建好 ksoftirqd 内核线程；
要注册好各个协议对应的处理函数；
网卡设备子系统要提前初始化好；
网卡要启动好。

初始化工作

创建 ksoftirqd 内核线程

Linux 的软中断都是在专门的内核线程（ksoftirqd）中进行的，因此我们非常有必要看一下这些线程是怎么初始化的。

首先，这个线程的数量不是 1 个，而是 N 个，其中 N 等于你的机器的核数。

系统初始化的时候在 kernel/smpboot.c 中调用了 smpboot_register_percpu_thread 这个函数，该函数进一步执行到 spawn_ksoftirqd（位于 kernel/softirq.c）来创建出 softirqd 线程，执行过程如下图所示：

网络子系统初始化

在网络子系统的初始化过程中，会为每个 CPU 初始化 softnetdata，也会为 RXSOFTIRQ 和 TX_SOFTIRQ 注册处理函数，流程如图 2.4 所示。

Linux 内核通过调用 subsys_initcall 来初始化各个子系统。

重点！！！这里说的网络子系统的初始化，会执行 netdevinit 函数。

就是这里的 subsysinitcall(netdevinit) 中的 netdev_init 函数。代码如下：

static int __init net_dev_init(void)
{
    ......

    /*
     *    Initialise the packet receive queues.
     */

  /*
   * 为每个 CPU 都申请一个 softnet_data 数据结构，这个数据结构里的 poll_list 用于等待驱动程序将其 poll 函数注册进来，稍后网卡驱动程序初始化的时候就可以看到这一过程了。
   */
        for_each_possible_cpu(i) {
        struct softnet_data *sd = &per_cpu(softnet_data, i);

        memset(sd, 0, sizeof(*sd));
        skb_queue_head_init(&sd->input_pkt_queue);
        skb_queue_head_init(&sd->process_queue);
        sd->completion_queue = NULL;
        INIT_LIST_HEAD(&sd->poll_list);
    ......
  }
  ......
    /*
     * open_softirq 为每一种软中断都注册了一个处理函数。
     * NET_TX_SOFTIRQ 的处理函数为 net_tx_action；
     * NET_RX_SOFTIRQ 的处理函数为 net_rx_action；
     */
  open_softirq(NET_TX_SOFTIRQ, net_tx_action);
    open_softirq(NET_RX_SOFTIRQ, net_rx_action);
}

subsys_initcall(net_dev_init);

继续跟踪 opensoftirq 后发现这个注册的方式是记录在 softirqvec 变量里的。后面 softirqd 线程收到软中断的时候，也会使用这个变量来找到每一种软中断对应的处理函数。

void open_softirq(int nr, void (*action)(struct softirq_action *))
{
    softirq_vec[nr].action = action;
}

协议栈注册

网卡驱动初始化

每个驱动程序都会使用 module_init 向内核注册一个初始化函数，当驱动程序加载的时候，内核会调用这个函数。

调用完成后，linux 内核就会知道这个驱动的相关信息，比如 igb 网卡驱动的 igbdrivername 和 igb_probe 函数地址等。

当网卡设备被识别之后，内核会调用其驱动的 probe 方法，（继续拿 igb 网卡驱动举例子），igbdriver 的 probe 方法是 igbprobe。

igb_probe 方法的作用就是，尽快让设备处于 ready 状态。

此外，还有一步比较关键，注册了 NAPI 机制必需的 poll 函数，这个对于 igb 网卡驱动来说，就是 igb_poll。

初始化完成之后

启动网卡

上面所有的初始化都完成以后，就可以启动网卡了。一般启动网卡的顺序都差不多，如下图所示：

igb_open 代码如下：

static int __igb_open(struct net_device *netdev, bool resuming)
{
  // 分配传输描述符数组
  err = igb_setup_all_tx_resources(adapter);
  // 分配接收描述符数组
    err = igb_setup_all_rx_resources(adapter);

  // 注册中断处理函数
  err = igb_request_irq(adapter);
    if (err)
        goto err_req_irq;

  // 启用 NAPI
      for (i = 0; i < adapter->num_q_vectors; i++)
        napi_enable(&(adapter->q_vector[i]->napi));
    ......
}

igbopen 函数又调用了 igbsetupalltxresources 和 igbsetupallrxresources。在 igbsetupallrx_resources 这一步操作中，分配了 RingBuffer，并建立了内存和 Rx 队列的映射关系。

static int igb_setup_all_rx_resources(struct igb_adapter *adapter)
{
    ......

    for (i = 0; i < adapter->num_rx_queues; i++) {
        err = igb_setup_rx_resources(adapter->rx_ring[i]);
        ...
    }

    return err;
}

使用 for 循环，然后搭配 igbsetuprxresources 函数，创建了若干个队列。igbsetuprxresources 函数如下：

int igb_setup_rx_resources(struct igb_ring *rx_ring)
{
    struct device *dev = rx_ring->dev;
    int size;

    // 1. 申请 igb_rx_buffer 数组内存
    size = sizeof(struct igb_rx_buffer) * rx_ring->count;

    rx_ring->rx_buffer_info = vzalloc(size);
    if (!rx_ring->rx_buffer_info)
        goto err;

    /* Round up to nearest 4K */
    // 2. 申请 e1000_adv_rx_desc DMA 数组内存
    rx_ring->size = rx_ring->count * sizeof(union e1000_adv_rx_desc);
    rx_ring->size = ALIGN(rx_ring->size, 4096);

    rx_ring->desc = dma_alloc_coherent(dev, rx_ring->size,
                       &rx_ring->dma, GFP_KERNEL);
    if (!rx_ring->desc)
        goto err;

    // 3. 初始化队列成员
    rx_ring->next_to_alloc = 0;
    rx_ring->next_to_clean = 0;
    rx_ring->next_to_use = 0;

    return 0;

err:
    vfree(rx_ring->rx_buffer_info);
    rx_ring->rx_buffer_info = NULL;
    dev_err(dev, "Unable to allocate memory for the Rx descriptor ring\n");
    return -ENOMEM;
}

上述源码可见，实际上一个 RingBuffer 的内部不是仅有一个环形队列数组，而是有两个：

igbrxbuffer 数组：这个数组是内核使用的，通过 vzalloc 申请的；
e1000advrxdesc 数组：这个数组是网卡硬件使用的，通过 dmaalloc_coherent 分配。

然后其实还有最后一步中断函数的注册，注册过程看 igbrequestirq。

OK，上面就是所有的准备工作了～接下里啊就是接受数据包了。

开始接受数据包

这一部分包括了，硬中断处理

硬中断处理

首先，当数据帧从网线抵达网卡的时候，第一站是网卡的接收队列。网卡在分配给自己的 RingBuffer 中寻找可用的内存位置，找到后 DMA 引擎会将数据 DMA 到网卡之前关联的内存里，到这个时候 CPU 都是无感的。

当 DMA 操作完成后，网卡会向 CPU 发起一个硬中断，通知 CPU 有数据到达。硬中断的处理过程如下图：

在之前的“启动网卡”这一部分中，讲到网卡的硬中断注册的处理函数是 igbmsixring。

// file: drivers/net/ethernet/intel/igb/igb_main.c
static irqreturn_t igb_msix_ring(int irq, void *data)
{
    struct igb_q_vector *q_vector = data;

    /* Write the ITR value calculated from the previous interrupt. */
    igb_write_itr(q_vector);

    napi_schedule(&q_vector->napi);

    return IRQ_HANDLED;
}

其中的 igbwriteitr 只记录硬件中断频率。顺着 napischedule 调用一路跟踪下去，你就会发现，Linux 在硬中断里只完成简单必要的工作，剩下的大部分的处理都是转交给软中断的。通过以上代码可以看到，硬中断处理过程真的非常短，只是记录了一个寄存器，修改了一下 CPU 的 polllist，然后发出一个软中断，就这样，硬中断的工作就算是完成了。

ksoftirqd 内核线程处理软中断

网络包的接收处理过程主要都在 ksoftirqd 内核线程中完成，软中断都是在这里处理的，流程如下所示：

网络协议栈处理

netifreceiveskb 函数会根据包的协议进行处理，假如是 UDP 包，将包依次送到 iprcv、udprcv 等协议处理函数中进行处理。如下图：

IP 层处理

Linux 在 IP 层做的操作，在代码 net/ipv4/ip_input.c 这个代码文件中。

总结

网络模块是 Linux 内核中最复杂的模块了。整个过程，涉及到了许多内核组件之间的交互，如网卡驱动、协议栈、内核 ksoftirqd 线程等。看起来很复杂，但实际整体大概还是很清晰的。简单总结如下。

当用户执行完 recvfrom 调用之后，用户进程就通过系统调用进行到内核态工作了。如果接收队列没有数据，进程就进入睡眠状态被操作系统挂起。这块相对简单，接下来就是 LInux 各个内核组件之间的工作了。

首先在开始收包之前，Linux 要做许多的准备工作：

创建 ksoftirqd 内核线程，为它设置好它自己的线程函数，后面指望着它来处理软中断；
协议栈注册，Linux 要实现许多协议，比如 ARP、ICMP、IP、UDP 和 TCP，每一个协议都会将自己的处理函数注册一下，这样会方便包来了之后迅速找到对应的处理函数；
网卡驱动初始化，每个驱动都有一个初始化函数，内核会让驱动也初始化一下。在这个初始化过程中，准备好自己的 DMA，并且把 NAPI 的 poll 函数地址告诉内核；
启动网卡，分配 RX、TX 队列，注册中断对应的处理函数。

准备工作完成之后，接下来就是数据到来。第一个迎接它的是网卡：

网卡将数据帧 DMA 到内存的 RingBUffer 中，然后向 CPU 发起中断通知；
CPU 响应中断请求，调用网卡启动时注册的中断处理函数；
中断处理函数只是发起了软中断请求，其他的什么也没有干；
内核线程 ksoftirqd 发现有软中断请求到来，先关闭硬中断；
ksoftirqd 线程开始调用驱动的 poll 函数收包；
poll 函数将收到的包送到协议栈注册的 ip_rcv 函数中；
iprcv 函数将包送到 udprcv 函数中（对于 TCP 包是送到 tcprcvv4）。

一些总结

问题一：RingBuffer 究竟是什么，为什么 RingBuffer 会丢包？

RingBuffer 是内存中特殊的一块区域，是一种环形队列数组，事实上这个数据结构包括了 igbrxbuffer 环形队列数组、e1000advrx_desc 环形队列数组及众多的 skb。

如果 RingBuffer 代表的是指针数组，那么是预先分配好的，如果是 skb，那么是随着收包过程而动态申请的。

问题二：软中断和硬中断分别是什么？

Linux 网络栈中数据包接收的关键流程：

硬件阶段：网卡将接收到的数据包放入 RingBuffer
硬中断触发：网卡产生硬中断通知 CPU
硬中断处理：添加网卡设备到 softnet_data 结构的 poll_list 双向链表
软中断触发：触发 NET_RX_SOFTIRQ 软中断
软中断处理：遍历 poll_list 列表，执行网卡驱动的 poll 函数收取网络包
协议栈处理：将数据包转发到 ip_rcv、udp_rcv、tcp_rcv_v4 等协议处理函数

这描述的是 Linux NAPI (New API) 机制，一种高效处理网络数据包的方法。

RingBuffer 在网络栈中的实际应用

网卡 RX/TX 环形缓冲区

/* 简化的网卡 RX Ring 结构 */
struct e1000_rx_desc {
    __le64 buffer_addr;    /* 数据缓冲区地址 */
    __le16 length;         /* 数据包长度 */
    __le16 checksum;       /* 校验和 */
    __u8  status;          /* 描述符状态 */
    __u8  errors;          /* 错误码 */
    __le16 special;
};

实际上，一个 Intel 网卡的 RX Ring 可能包含 256 个这样的描述符，形成一个环形结构。

硬中断与软中断协作的实际例子

在 Intel 82599 网卡的驱动中：

/* 硬中断处理程序 */
static irqreturn_t ixgbe_msix_lsc(int irq, void *data)
{
    struct net_device *netdev = data;

    /* 禁用网卡中断 */
    ixgbe_disable_interrupt();

    /* 将设备添加到 poll_list */
    napi_schedule(&adapter->q_vector[vector]->napi);

    return IRQ_HANDLED;
}

/* NAPI poll 函数 */
static int ixgbe_poll(struct napi_struct *napi, int budget)
{
    struct ixgbe_q_vector *q_vector = container_of(napi, struct ixgbe_q_vector, napi);
    struct ixgbe_adapter *adapter = q_vector->adapter;
    int work_done = 0;

    /* 从 RingBuffer 中批量收包，最多处理 budget 个 */
    work_done = ixgbe_clean_rx_irq(q_vector, budget);

    /* 如果工作未完成，保持在 poll_list 中 */
    if (work_done < budget) {
        napi_complete(napi);
        ixgbe_enable_interrupt();
    }

    return work_done;
}

git 推送大文件 repo

cheverjonathan@gmail.com (Chenwei Jiang) — Wed, 27 Dec 2023 00:00:00 GMT

看一下我的效果

我的需求：我想要阅读 Linux 源码，使用 git 管理我阅读的 Linux 源码，使用我自建的 gitlab 保存我阅读的源码。然后发现简单的 git push 一个 2GB 的 linux 源码文件会出现问题。

所以我就写了个脚本以期来解决这个问题。

脚本内容如下：

#!/bin/bash

# 配置参数（请根据需要修改）
REMOTE_NAME="origin"              # 远程仓库名称
BRANCH_NAME="main"                # 目标分支名
REMOTE_URL="git@gitlab.cheverjohn.me:CheverJohn/linux.git"  # 远程仓库地址
BATCH_SIZE=500                    # 每批文件数量
COMMIT_MESSAGE="批量上传文件"      # 提交信息

# 颜色配置
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[0;33m'
BLUE='\033[0;34m'
NC='\033[0m' # 无颜色

# 检查是否在git仓库中
if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
    echo -e "${YELLOW}当前目录不是git仓库，正在初始化...${NC}"
    git init
    echo -e "${GREEN}Git仓库已初始化${NC}"
else
    echo -e "${GREEN}Git仓库已存在${NC}"
fi

# 检查远程仓库是否已配置
if ! git remote | grep -q "$REMOTE_NAME"; then
    echo -e "${YELLOW}添加远程仓库 $REMOTE_NAME: $REMOTE_URL${NC}"
    git remote add $REMOTE_NAME $REMOTE_URL
    echo -e "${GREEN}远程仓库已添加${NC}"
else
    CURRENT_URL=$(git remote get-url $REMOTE_NAME 2>/dev/null || echo "")
    if [ "$CURRENT_URL" != "$REMOTE_URL" ]; then
        echo -e "${YELLOW}更新远程仓库URL: $REMOTE_URL${NC}"
        git remote set-url $REMOTE_NAME $REMOTE_URL
        echo -e "${GREEN}远程仓库URL已更新${NC}"
    else
        echo -e "${GREEN}远程仓库已正确配置${NC}"
    fi
fi

# 确保主分支存在
if ! git show-ref --quiet refs/heads/$BRANCH_NAME; then
    echo -e "${YELLOW}创建分支 $BRANCH_NAME...${NC}"
    git checkout -b $BRANCH_NAME
    echo -e "${GREEN}分支 $BRANCH_NAME 已创建${NC}"
else
    echo -e "${GREEN}分支 $BRANCH_NAME 已存在${NC}"
    git checkout $BRANCH_NAME
fi

# 获取所有未跟踪和已修改的文件
echo -e "${BLUE}获取待上传的文件列表...${NC}"
FILES=($(git ls-files --others --exclude-standard) $(git diff --name-only))
TOTAL_FILES=${#FILES[@]}

if [ $TOTAL_FILES -eq 0 ]; then
    echo -e "${YELLOW}没有找到需要添加的文件，尝试添加所有文件...${NC}"
    git add -A
    FILES=($(git diff --name-only --cached))
    TOTAL_FILES=${#FILES[@]}

    if [ $TOTAL_FILES -eq 0 ]; then
        echo -e "${RED}错误: 没有找到要推送的文件${NC}"
        exit 1
    fi
else
    # 添加所有文件到暂存区
    echo -e "${BLUE}添加所有文件到暂存区...${NC}"
    git add -A
fi

echo -e "${GREEN}找到 $TOTAL_FILES 个文件需要上传${NC}"

# 计算批次数
BATCH_COUNT=$(( ($TOTAL_FILES + $BATCH_SIZE - 1) / $BATCH_SIZE ))
echo -e "${GREEN}将分为 $BATCH_COUNT 批次上传${NC}"

# 首先提交所有文件
echo -e "${BLUE}提交所有文件...${NC}"
git commit -m "$COMMIT_MESSAGE"

# 分批推送
echo -e "${BLUE}开始分批推送...${NC}"
git push -u $REMOTE_NAME $BRANCH_NAME

if [ $? -eq 0 ]; then
    echo -e "${GREEN}所有文件已成功推送到远程仓库${NC}"
else
    echo -e "${YELLOW}常规推送失败，尝试使用批量方式推送...${NC}"
    # 使用git batch push方式（参考了搜索结果中的示例）
    # 基于 git_batch_push.sh 的思路，但简化了实现

    # 使用git rev-list获取所有提交
    COMMITS=($(git rev-list --reverse HEAD))
    TOTAL_COMMITS=${#COMMITS[@]}

    if [ $TOTAL_COMMITS -eq 0 ]; then
        echo -e "${RED}错误: 没有找到提交记录${NC}"
        exit 1
    fi

    echo -e "${GREEN}找到 $TOTAL_COMMITS 个提交，将分批推送${NC}"

    # 计算批次数（每批500个提交）
    COMMIT_BATCH_SIZE=500
    COMMIT_BATCH_COUNT=$(( ($TOTAL_COMMITS + $COMMIT_BATCH_SIZE - 1) / $COMMIT_BATCH_SIZE ))

    echo -e "${GREEN}将分为 $COMMIT_BATCH_COUNT 批次推送提交${NC}"

    # 分批推送提交
    for ((i=0; i<$COMMIT_BATCH_COUNT; i++)); do
        START=$(($i * $COMMIT_BATCH_SIZE))
        END=$((($i + 1) * $COMMIT_BATCH_SIZE))

        if [ $END -gt $TOTAL_COMMITS ]; then
            END=$TOTAL_COMMITS
        fi

        BATCH_END_INDEX=$((END - 1))
        TARGET_COMMIT=${COMMITS[$BATCH_END_INDEX]}

        echo -e "${BLUE}推送批次 $((i+1))/${COMMIT_BATCH_COUNT} (提交 $((START+1))-$END)...${NC}"

        if git push $REMOTE_NAME $TARGET_COMMIT:refs/heads/$BRANCH_NAME; then
            echo -e "${GREEN}批次 $((i+1)) 成功推送${NC}"
        else
            echo -e "${RED}批次 $((i+1)) 推送失败${NC}"
            echo -e "${YELLOW}尝试另一种推送方法...${NC}"

            # 如果上面的方法失败，尝试另一种批量推送方法
            if [ $i -eq 0 ]; then
                # 第一批次，创建新分支
                git push $REMOTE_NAME $BRANCH_NAME
            else
                # 获取上一批次的末尾提交
                PREV_END=$(($START - 1))
                PREV_COMMIT=${COMMITS[$PREV_END]}
                CURR_COMMIT=${COMMITS[$BATCH_END_INDEX]}

                echo -e "${BLUE}使用范围推送 $PREV_COMMIT..$CURR_COMMIT${NC}"
                git push $REMOTE_NAME $PREV_COMMIT:refs/heads/$BRANCH_NAME $CURR_COMMIT:refs/heads/$BRANCH_NAME
            fi
        fi

        echo
    done
fi

echo -e "${GREEN}分批上传过程完成!${NC}"

运行方法很简单。

chmod +x git_batch_push.sh

然后在当前文件夹运行脚本即可。

最终效果

常用密码学：GPG 加密文件（实践向）

cheverjonathan@gmail.com (Chenwei Jiang) — Tue, 26 Sep 2023 00:00:00 GMT

本篇文章主要是在实践，然后会简单介绍一下原理。

整篇文章，前期会讲一个简单原理，然后会从如何创建 gpg 密钥、如何管理自己的密钥（管理密钥相关命令）、实战：使用自己创建的 gpg 密钥去解密传输的加密文件三个部分开始讲完整个文章。

原理简介

使用 GPG Encrypting and decrypting doc 的原理其实就像文档中的一段话，如下

The procedure for encrypting and decrypting documents is straightforward with this mental model. If you want to encrypt a message to Alice, you encrypt it using Alice's public key, and she decrypts it with her private key. If Alice wants to send you a message, she encrypts it using your public key, and you decrypt it with your key.

整个过程就是，我拿我的私钥加密我想要发给你的文件。然后你拿我的公钥，解密我想要发给你的，但是被我加密的文件。

这么一个过程。

这篇文章主要就是，简单快速过一下 gpg 是如何加密文档内容的。

本篇文章分为两部分，首先是创建一个可用的 gpg 密钥。

如何创建 gpg 密钥

[Se] gpg --list-keys
gpg: checking the trustdb
gpg: no ultimately trusted keys found

首先 list 一下我的机器当前是否有个 gpg key。可以看到是没有的，此处主要是指有没有 gpg public key。同样看看 private key。

[Se] gpg --list-secret-keys
[Se]

啥也没有。

一个命令搞定一切

开始创建。

详细步骤从一个 gpg --full-generate-key 开始，命令如下：

[Se] gpg --full-generate-key
gpg (GnuPG) 2.4.0; Copyright (C) 2021 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) RSA and RSA
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
   (9) ECC (sign and encrypt) *default*
  (10) ECC (sign only)
  (14) Existing key from card
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (3072) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
         0 = key does not expire
        = key expires in n days
      w = key expires in n weeks
      m = key expires in n months
      y = key expires in n years
Key is valid for? (0) 0
Key does not expire at all
Is this correct? (y/N) y

GnuPG needs to construct a user ID to identify your key.

Real name: Chenwei Jiang
Email address: cheverjonathan@gmail.com
Comment: Used for learning
You selected this USER-ID:
    "Chenwei Jiang (Used for learning) "

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.

gpg: revocation certificate stored as '/home/cheverjohn/.gnupg/openpgp-revocs.d/D1DED33E8FE9CA4B315A488968CC99424BF9EF81.rev'
public and secret key created and signed.

pub   rsa4096 2023-09-19 [SC]
      D1DED33E8FE9CA4B315A488968CC99424BF9EF81
uid                      Chenwei Jiang (Used for learning) 
sub   rsa4096 2023-09-19 [E]

详细分阶段解释一下命令

想了想，还是需要简单分全阶段讲一下发生了什么。

第一阶段：选择加密签名用算法

第一阶段，可以看到需要你选择加密算法。而我选择了 1，这表示加密和签名都适用了 RSA 算法。

[Se] gpg --full-generate-key
gpg (GnuPG) 2.4.0; Copyright (C) 2021 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) RSA and RSA
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
   (9) ECC (sign and encrypt) *default*
  (10) ECC (sign only)
  (14) Existing key from card
Your selection? 1

第二阶段：选择密钥的长度

密钥越长越安全，我这边选择了 4096。

RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (3072) 4096
Requested keysize is 4096 bits

第三阶段：设定密钥的有效期

设定有效期。

Please specify how long the key should be valid.
         0 = key does not expire
        = key expires in n days
      w = key expires in n weeks
      m = key expires in n months
      y = key expires in n years
Key is valid for? (0) 0
Key does not expire at all
Is this correct? (y/N) y

这边演示的话，配置了 Key does not expire at all。

第四阶段：个人信息

这一部分会最终用来生成你的 user id。

GnuPG needs to construct a user ID to identify your key.

Real name: Chenwei Jiang
Email address: cheverjonathan@gmail.com
Comment: Used for learning
You selected this USER-ID:
    "Chenwei Jiang (Used for learning) "

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O

这边我设置了我的 Real name 为 “Chenwei Jiang”，我的 Email address 为 “cheverjonathan@gmail.com“。以及一个 comment。这些都是我常用的一些基本信息，此处主要就是用来演示。

得到的结果 —— 一个 USER-ID 为 "Chenwei Jiang (Used for learning) cheverjonathan@gmail.com"。

如何管理自己的密钥（管理密钥相关命令）

这边讲了我该如何在一台宿主机上，管理我的很多密钥呢。

列出密钥

列出密钥分两种，一种是公钥，一种是私钥。

[Se] gpg --list-keys
gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
/home/cheverjohn/.gnupg/pubring.kbx
-----------------------------------
pub   rsa4096 2023-09-19 [SC]
      D1DED33E8FE9CA4B315A488968CC99424BF9EF81
uid           [ultimate] Chenwei Jiang (Used for learning) 
sub   rsa4096 2023-09-19 [E]

上面的命令显示了。

其中仔细的部分。

/home/cheverjohn/.gnupg/pubring.kbx
-----------------------------------
pub   rsa4096 2023-09-19 [SC]
      D1DED33E8FE9CA4B315A488968CC99424BF9EF81
uid           [ultimate] Chenwei Jiang (Used for learning) 
sub   rsa4096 2023-09-19 [E]

其中第一行，显示公钥文件名。

值	解释
/home/cheverjohn/.gnupg/pubring.kbx	第一行显示公钥文件名（pubring.kbx）
pub rsa4096 2023-09-19 [SC] D1DED33E8FE9CA4B315A488968CC99424BF9EF81	第二行显示公钥特性（4096 位，Hash 字符串以及生成的时间。
uid [ultimate] Chenwei Jiang (Used for learning) cheverjonathan@gmail.com	第三行显示“用户 ID”。
sub rsa4096 2023-09-19 [E]	第四行显示私钥特征。

输出密钥

公钥文件位于 ~/.gnupg/pubring.kbx 以二进制形式存储，使用 armor 参数可以将其转换为 ASCII 码显示。

使用命令，展示输出为 public-key.txt 和 private-key.txt，命令如下：

[gpg] pwd
/home/cheverjohn/Se/gpg
[gpg] ls
[gpg] ls -la
total 0
drwxr-xr-x. 1 cheverjohn cheverjohn  0 Sep 19 23:36 .
drwxr-xr-x. 1 cheverjohn cheverjohn 34 Sep 19 23:36 ..
[gpg] gpg --armor --output public-key.txt --export 'Chenwei Jiang (used for learning) '
[gpg] ls
public-key.txt
[gpg] cat public-key.txt
-----BEGIN PGP PUBLIC KEY BLOCK-----

mQINBGUJt+QBEADAzoLPAdK8GfJ/5Ouxh2rOrMsClMmoOznMm2GOBcqSaQsdmP4G
................................................................
oM3YFFujtMxK/cQ/KkbmwAtlMkWx5x8RT/dJ
=NMtR
-----END PGP PUBLIC KEY BLOCK-----
[gpg]

如上图所示，这是展示 public-key.txt 的步骤，详细命令如下：

gpg --armor --output public-key.txt --export 'Chenwei Jiang (used for learning) '

下面是展示 private-key.txt 的步骤，详细步骤如下：

[gpg] ls
public-key.txt
[gpg] gpg --armor --output private-key.txt --export-secret-keys
[gpg] ls
private-key.txt  public-key.txt
[gpg]

其中如果之前设置了密码的话，这个操作是需要密码的，需要密码的命令如下：

gpg --armor --output private-key.txt --export-secret-keys

上传公钥

公钥服务器是网络上专门存储用户公钥的服务器。--send-keys 子命令可以实现。

公钥服务器没有检查机制，任何人都可以用你的名义上传公钥，所以没法保证服务器上的公钥的可靠性。

一般我们在自己的网站上公布一个公钥指纹，用来让别人核对下载的公钥是否为真。--fingerprint 子命令可以生成公钥指纹。

实战/实践出真知

这一部分我将按照导出公钥，使用私钥加密，在另外一台设备上使用公钥进行解密。

此处我将展示如何加密一个内容为 “hello world” 的文件，然后在异地进行解密。

步骤，将分为加密、解密

详细步骤如下

创建文件，命令如下：

[gpg] touch demo.txt
echo "hello world" > demo.txt
[gpg] ls
demo.txt  private-key.txt  public-key.txt
[gpg] cat demo.txt
hello world
[gpg]

其中，创建文件的命令如下，可复制直接使用：

touch demo.txt
echo "hello world" > demo.txt

然后我们就得到了一个 demo.txt 文件，里边的内容就是 hello world。

对该文件加密，加密过程如下：

[gpg] ls
demo.txt  private-key.txt  public-key.txt
[gpg] gpg --recipient 'cheverjonathan@gmail.com' --output demo.gpg --encrypt demo.txt
[gpg] ls
demo.gpg  demo.txt  private-key.txt  public-key.txt
[gpg] cat demo.gpg
�
..............
�&5p�.�)I�槹iQ%
[gpg]

加密命令如下：

gpg --recipient 'cheverjonathan@gmail.com' --output demo.gpg --encrypt demo.txt

这边可以看到 demo.gpg 文件就是已经加密好之后的文件。

对该文件解密，解密过程如下：

[gpg] gpg --output demo --decrypt demo.gpg
gpg: encrypted with rsa4096 key, ID 13C117D5FEC4F051, created 2023-09-19
      "Chenwei Jiang (Used for learning) "
[gpg] ls
demo  demo.gpg  demo.txt  private-key.txt  public-key.txt
[gpg] cat demo
hello world
[gpg]

解密命令如下：

gpg --output demo --decrypt demo.gpg

输入这行命令之后，需要输入之前的密码，然后就能得到文件。

上面主要是在本机上使用本地的密钥加密文件，并在本地解密的过程。

接下来开始，开始......

在其他电脑上获取到文件并加密，然后由原主机使用私钥进行解密

首先我们将 public-key.txt 传到其他主机，这边你可以通过 GitHub 的功能将文件上下传，我这边省事，将上面过程得出的如下文件树：

cheverjohn@Dell-G33579 git:(doc/test-gpg*)% tree ~/workspace/Opensource/github.com/Chever-John/cheverjohn.me/docs/wait-for-publish/gpg
.
├── demo
├── demo.gpg
├── demo.txt
├── private-key.txt
└── public-key.txt

中的 private-key.txt 删除后，将文件上传到 GitHub 上。

可以看到我在另外一台主机上下载了 public-key.txt 文件，如下文件树所示：

cheverjohn:wait-for-publish/ git:(doc/test-gpg*)$ tree gpg                                                                   [0:54:06]
gpg
├── demo
├── demo.gpg
├── demo.txt
└── public-key.txt

1 directory, 4 files

然后我接下来要做的就是，使用这个 public-key.txt 去加密一个文件，然后将这个文件传回最初拥有私钥的主机上，并交由它进行解密得到内容。

首先我们需要将这个 public-key.txt 导入到本地。命令如下：

gpg --import public-key.txt

命令执行结果如下：

cheverjohn:gpg/ git:(doc/test-gpg*)$ gpg --import public-key.txt                                                             [1:20:11]
gpg: key 3BE465D20064251C: public key "Chenwei Jiang (Learning second) " imported
gpg: Total number processed: 1
gpg:               imported: 1

然后我们需要使用这个 public-key 对文本进行加密。

首先我们需要创建一个文件 hello-no-encrypt.txt，一系列操作如下：

cheverjohn:gpg/ git:(doc/test-gpg*)$ touch hello-no-encrypt.txt                                                              [1:16:07]
cheverjohn:gpg/ git:(doc/test-gpg*)$ nvim hello-no-encrypt.txt                                                               [1:16:15]
cheverjohn:gpg/ git:(doc/test-gpg*)$ cat hello-no-encrypt.txt                                                                [1:16:24]
Hello Sasa!
cheverjohn:gpg/ git:(doc/test-gpg*)$ tree                                                                                    [1:16:28]
.
├── demo
├── demo.gpg
├── demo.txt
├── hello-no-encrypt.txt
└── public-key.txt

1 directory, 5 files

我们需要对这个文件进行加密，然后传给拥有私钥的宿主机进行解密。

加密文件整个流程如下：

cheverjohn:gpg/ git:(doc/test-gpg*)$ gpg --output hello-encrypted.gpg --encrypt --recipient 'Chenwei Jiang (Learning second) ' hello-no-encrypt.txt
gpg: 617C5542800731C1: There is no assurance this key belongs to the named user

sub  rsa4096/617C5542800731C1 2023-09-21 Chenwei Jiang (Learning second) 
 Primary key fingerprint: 5588 D37D AF51 50FD 9186  47E7 3BE4 65D2 0064 251C
      Subkey fingerprint: A038 0DA1 D481 62C7 517C  D6C6 617C 5542 8007 31C1

It is NOT certain that the key belongs to the person named
in the user ID.  If you *really* know what you are doing,
you may answer the next question with yes.

Use this key anyway? (y/N) y

加密命令如下：

gpg --output hello-encrypted.gpg --encrypt --recipient 'Chenwei Jiang (Learning second) ' hello-no-encrypt.txt

然后我们需要将这个加密之后的文件 hello-decrypted.gpg 上传到拥有私钥的机器上。

这边还是选择 GitHub 来作为文件传输工具～

这边可以看到我在宿主机（拥有密钥的机器）上拿到了文件，开始进行解密，看到如下：

[gpg] tree                                                                                                         git:(doc/test-gpg)
.
├── demo
├── demo.gpg
├── demo.txt
├── hello-encrypted.gpg
├── hello-no-encrypt.txt
└── public-key.txt

1 directory, 6 files

接下来需要对 hello-encrypted.gpg 进行解密。解密过程如下：

[gpg] gpg --output hello-decrypted.txt --decrypt hello-encrypted.gpg                                               git:(doc/test-gpg)
gpg: encrypted with rsa4096 key, ID 617C5542800731C1, created 2023-09-21
      "Chenwei Jiang (Learning second) "
[gpg] ls                                                                                                        git:(doc/test-gpg*)  ✱
demo  demo.gpg  demo.txt  hello-decrypted.txt  hello-encrypted.gpg  hello-no-encrypt.txt  public-key.txt
[gpg] cat hello-decrypted.txt                                                                                   git:(doc/test-gpg*)  ✱
Hello Sasa!

解密的命令如下：

gpg --output hello-decrypted.txt --decrypt hello-encrypted.gpg

gnupg.org 官方手册

你好，我是 Chever John

cheverjonathan@gmail.com (Chenwei Jiang) — Tue, 27 Dec 2022 00:00:00 GMT

你好！

我是 Chever John，一名软件工程师。

如何在 APISIX Ingress Controller 中运行 Go 插件运行器

cheverjonathan@gmail.com (Chenwei Jiang) — Fri, 29 Apr 2022 00:00:00 GMT

如标题所说。

背景描述

在社区中闲逛时，我发现有用户对"如何在 APISIX Ingress 环境中使用多语言插件"感到困惑。我恰好是 go-plugin-runner 的用户，对 APISIX Ingress 项目也有一些了解，于是就有了这份文档。

方案描述

基于 go-plugin-runner 插件的 0.3 版本和 APISIX Ingress 的 1.4.0 版本，本文通过构建集群、构建镜像、自定义 helm chart 包，最后部署资源的步骤。保证完全基于本文档可以推导出最终结果。

go-plugin-runner: 0.3
APISIX Ingress: 1.4.0

kind: kind v0.12.0 go1.17.8 linux/amd64
kubectl version: Client Version: v1.23.5/Server Version: v1.23.4
golang: go1.18 linux/amd64

开始

构建集群环境

选择 kind 来构建本地集群环境。命令如下：

cat <


构建 go-plugin-runner 可执行文件
如果你已经完成了插件的编写，就可以开始编译可执行文件来与 APISIX 一起运行。
本文推荐两种打包构建选项。
将打包过程放入 Dockerfile 中，在后续构建 docker 镜像时完成编译过程。
你也可以按照本文档使用的方案，先构建可执行文件，然后将打包的可执行文件复制到镜像中。
如何选择方案应该根据你的本地硬件考虑。这里选择第二种方案的原因是，我想依托我强大的本地硬件来提高构建速度，加快流程。
进入 go-plugin-runner 目录
选择一个文件夹地址 /home/chever/api7/cloud_native/tasks/plugin-runner，将我们的 apisix-go-plugin-runner 项目放置在这个文件夹中。
成功放置后，文件树如下所示：
chever@cloud-native-01:~/api7/cloud_native/tasks/plugin-runner$ tree -L 1
.
└── apisix-go-plugin-runner

1 directory, 0 files

然后你需要进入 apisix-go-plugin-runner/cmd/go-runner/plugins 目录，在该目录中编写你需要的插件。本文将使用默认插件 say 进行演示。
chever@cloud-native-01:~/api7/cloud_native/tasks/plugin-runner/apisix-go-plugin-runner$ tree cmd
cmd
└── go-runner
    ├── main.go
    ├── main_test.go
    ├── plugins
    │   ├── fault_injection.go
    │   ├── fault_injection_test.go
    │   ├── limit_req.go
    │   ├── limit_req_test.go
    │   ├── say.go
    │   └── say_test.go
    └── version.go
    
2 directories, 10 files

编写完插件后，正式开始编译可执行文件，这里注意应该构建静态可执行文件，而不是动态的。
包编译命令如下。
CGO_ENABLED=0 go build -a -ldflags '-extldflags "-static"' .

这样就成功打包了一个静态编译的 go-runner 可执行文件。
在 apisix-go-plugin-runner/cmd/go-runner/ 目录中，你可以看到当前文件树如下所示：
chever@cloud-native-01:~/api7/cloud_native/tasks/plugin-runner/apisix-go-plugin-runner/cmd/go-runner$ tree -L 1
.
├── go-runner
├── main.go
├── main_test.go
├── plugins
└── version.go

1 directory, 4 files

请记住路径 apisix-go-plugin-runner/cmd/go-runner/go-runner，我们稍后会用到它。
构建 Docker 镜像
这里构建镜像是为了后续使用 helm 安装 APISIX 做准备。
编写 Dockerfile
回到路径 /home/chever/api7/cloud_native/tasks/plugin-runner，在该目录中创建一个 Dockerfile，这里给出一个演示。
ARG ENABLE_PROXY=false

# Build Apache APISIX
FROM api7/apisix-base:1.19.9.1.5

ADD ./apisix-go-plugin-runner /usr/local/apisix-go-plugin-runner

ARG APISIX_VERSION=2.13.1
LABEL apisix_version="${APISIX_VERSION}"

ARG ENABLE_PROXY
RUN set -x \
    && (test "${ENABLE_PROXY}" != "true" || /bin/sed -i 's,http://dl-cdn.alpinelinux.org,https://mirrors.aliyun.com,g' /etc/apk/repositories) \
    && apk add --no-cache --virtual .builddeps \
        build-base \
        automake \
        autoconf \
        make \
        libtool \
        pkgconfig \
        cmake \
        unzip \
        curl \
        openssl \
        git \
        openldap-dev \
    && luarocks install https://github.com/apache/apisix/raw/master/rockspec/apisix-${APISIX_VERSION}-0.rockspec --tree=/usr/local/apisix/deps PCRE_DIR=/usr/local/openresty/pcre \
    && cp -v /usr/local/apisix/deps/lib/luarocks/rocks-5.1/apisix/${APISIX_VERSION}-0/bin/apisix /usr/bin/ \
    && (function ver_lt { [ "$1" = "$2" ] && return 1 || [ "$1" = "`echo -e "$1\n$2" | sort -V | head -n1"`" ]; };  if [ "$APISIX_VERSION" = "master" ] || ver_lt 2.2.0 $APISIX_VERSION; then echo 'use shell ';else bin='#! /usr/local/openresty/luajit/bin/luajit\npackage.path = "/usr/local/apisix/?.lua;" .. package.path'; sed -i "1s@.*@$bin@" /usr/bin/apisix ; fi;) \
    && mv /usr/local/apisix/deps/share/lua/5.1/apisix /usr/local/apisix \
    && apk del .builddeps \
    && apk add --no-cache \
        bash \
        curl \
        libstdc++ \
        openldap \
        tzdata \
    # forward request and error logs to docker log collector
    && ln -sf /dev/stdout /usr/local/apisix/logs/access.log \
    && ln -sf /dev/stderr /usr/local/apisix/logs/error.log

WORKDIR /usr/local/apisix

ENV PATH=$PATH:/usr/local/openresty/luajit/bin:/usr/local/openresty/nginx/sbin:/usr/local/openresty/bin

EXPOSE 9080 9443

CMD ["sh", "-c", "/usr/bin/apisix init && /usr/bin/apisix init_etcd && /usr/local/openresty/bin/openresty -p /usr/local/apisix -g 'daemon off;'"]

STOPSIGNAL SIGQUIT

这份 Dockerfile 配置文档，来源于这个链接。我做的唯一修改如下：
ARG ENABLE_PROXY=false

# Build Apache APISIX
FROM api7/apisix-base:1.19.9.1.5

ADD ./apisix-go-plugin-runner /usr/local/apisix-go-plugin-runner

ARG APISIX_VERSION=2.13.1
LABEL apisix_version="${APISIX_VERSION}"

ARG ENABLE_PROXY


将 /home/chever/api7/cloud_native/tasks/plugin-runner 目录中的所有 /apisix-go-plugin-runner 文件打包到 Docker 镜像中。注意可执行文件 apisix-go-plugin-runner/cmd/go-runner/go-runner 的位置和上面 Dockerfile 中 /usr/local/apisix-go-plugin-runner 目录的位置，得出可执行文件在 Docker 镜像中的最终位置如下。
/usr/local/apisix-go-plugin-runner/cmd/go-runner/go-runner

请记住这个地址。我们将在其余配置中使用它。
开始构建 Docker 镜像
基于 Dockerfile 开始构建 Docker 镜像。命令在 /home/chever/api7/cloud_native/tasks/plugin-runner 目录中执行。命令如下：
docker build -t apisix/forrunner:0.1 .

命令解释：构建一个名为 apisix/forrunner 的镜像，并标记为 0.1 版本。
将镜像加载到集群环境
kind  load docker-image apisix/forrunner:0.1 

将镜像加载到 kind 集群环境中，以便在 helm 安装过程中拉取自定义本地镜像进行安装。
安装 APISIX Ingress
自定义 helm chart
这一部分重点是修改官方 helm 包中的 values.yaml 文件，使其能够安装本地打包的镜像，并正确运行 go-plugin-runner 可执行文件。
获取官方 helm chart
首先，用以下命令获取最新的 apisix helm chart 包：
helm fetch apisix/apisix

文件树如下：
chever@cloud-native-01:~/api7/cloud_native/tasks/plugin-runner$ tree -L 1
.
├── apisix-0.9.1.tgz
└── apisix-go-plugin-runner

1 directory, 1 file

解压
解压 apisix-0.9.1.tgz 文件，准备重写配置。解压命令如下。
tar zxvf apisix-0.9.1.tgz

文件树如下：
chever@cloud-native-01:~/api7/cloud_native/tasks/plugin-runner$ tree -L 1
.
├── apisix
├── apisix-0.9.1.tgz
└── apisix-go-plugin-runner

2 directories, 1 file

更改 values.yaml
进入 apisix 文件夹，修改 values.yaml 文件。两处更改如下：
image:
  repository: apisix/forrunner
  pullPolicy: IfNotPresent
  # Overrides the image tag whose default is the chart appVersion.
  tag: 0.1

第一处更改将 helm 安装的镜像设置为你自己本地打包的镜像。
extPlugin:
  enabled: true
  cmd: ["/usr/local/apisix-go-plugin-runner/cmd/go-runner/go-runner", "run"]

第二处更改设置了运行容器后 go-runner 在容器中的位置。
压缩修改后的 helm chart
配置完成后，压缩 apisix 文件。压缩命令如下：
tar zcvf apisix.tgz apisix/

获得压缩文件，此时文件树如下：
chever@cloud-native-01:~/api7/cloud_native/tasks/plugin-runner$ tree -L 1
.
├── apisix
├── apisix-0.9.1.tgz
├── apisix-go-plugin-runner
└── apisix.tgz

2 directories, 2 files

执行 helm 安装命令
创建命名空间
安装前，先用以下命令创建命名空间：
kubectl create ns ingress-apisix

然后使用 helm 安装 APISIX，命令如下：
helm install apisix ./apisix.tgz --set gateway.type=NodePort --set ingress-controller.enabled=true --namespace ingress-apisix --set ingress-controller.config.apisix.serviceNamespace=ingress-apisix

创建 httpbin 服务和 ApisixRoute 资源
创建一个 httpbin 后端资源，与部署的 ApisixRoute 资源一起运行，以测试功能是否正常工作。
创建 httpbin 服务
用以下命令创建 httpbin 服务：
kubectl run httpbin --image kennethreitz/httpbin --port 80

用以下命令暴露端口：
kubectl expose pod httpbin --port 80

创建 ApisixRoute 资源
创建 go-plugin-runner-route.yaml 文件来启用 ApisixRoute 资源，配置文件如下：
apiVersion: apisix.apache.org/v2beta3
kind: ApisixRoute
metadata:
  name: plugin-runner-demo
spec:
  http:
  - name: rule1
    match:
      hosts:
      - local.httpbin.org
      paths:
      - /get
    backends:
    - serviceName: httpbin
      servicePort: 80
    plugins:
    - name: ext-plugin-pre-req
      enable: true
      config:
        conf:
        - name: "say"
          value: "{\"body\": \"hello\"}"

创建资源的命令如下：
kubectl apply -f go-plugin-runner-route.yaml

测试
用以下命令测试用 Golang 编写的插件是否正常工作：
kubectl exec -it -n ${namespace of Apache APISIX} ${Pod name of Apache APISIX} -- curl http://127.0.0.1:9080/get -H 'Host: local.httpbin.org'

这里我从 kubectl get pods --all-namespaces 命令推导出 ${namespace of Apache APISIX} 和 ${Pod name of Apache APISIX} 参数分别是 ingress-apisix 和 apisix-55d476c64-s5lzw，执行命令如下：
kubectl exec -it -n ingress-apisix apisix-55d476c64-s5lzw -- curl http://127.0.0.1:9080/get -H 'Host: local.httpbin.org'

期望得到的响应是：
chever@cloud-native-01:~/api7/cloud_native/tasks/plugin-runner$ kubectl exec -it -n ingress-apisix apisix-55d476c64-s5lzw -- curl http://127.0.0.1:9080/get -H 'Host: local.httpbin.org'
Defaulted container "apisix" out of: apisix, wait-etcd (init)
hello

Chever John 的博客

证书基础与一次 Traefik “Not secure” 排查实录

TL;DR

证书基础（够用就好）

问题现象与影响范围

假设清单（按排除顺序）

验证流程可视化

排查链路（按顺序）

1) DNS 是否正确

2) 证书链与 SAN 是否正确

3) 用 OpenSSL 验证（通过）

4) 用 macOS 系统验证（失败）

根因判断

最小可行修复

一张排查清单（以后直接复用）

复盘与预防

一句话教训

预防性清单（下次签发证书时直接照做）

最终结论

自建服务部署与运维经验：一些踩坑与总结（模板）

部署经验总结（Traefik + Docker Compose + 域名访问 + 共享中间件）

目标与底线

目录组织与“我的部署习惯”

标准部署模板（核心套路）

1）禁止宿主机端口暴露

2）Traefik labels（域名路由 + TLS + 安全头）

3）多网络容器必须指定 Traefik 网络

共享中间件（middlewares 项目）

设计原则

经验要点

应用级注意点（本次踩坑记录）

Dockhand（容器管理面，风险极高）

Vaultwarden（Bitwarden 兼容服务）

Checkmate（多网络 + Mongo）

Miniflux（miniflux.example.me）

Cloudflare 的坑：客户端/插件集体“无法登录”

排错手册（从快到慢）

1）先判定“请求到没到服务器”

2）Traefik 侧排查

3）应用侧排查

最终安全清单（上线前必做）

日常排查：Minisforum N100 小主机随机掉盘/卡顿失去响应（DNS 服务运行 1 天+）

TL;DR

影响范围

环境信息（可复现前提）

硬件

软件

问题描述（只写事实）

当场止血（按时间线）

我关心的“数据结构”（证据链要对齐时间戳）

假设清单（按优先级）

数据采集（故障发生时我必须抓到什么）

关键证据（粘 3~5 段就够）

排查过程（尝试 → 观察 → 结论）

尝试 A：____

尝试 B：____

尝试 C：____

结论（概率表达，不装确定）

解决方案（短期止血 vs 长期修复）

短期止血（马上能做）

长期修复（一次到位）

验证标准

复盘

尝试方案：依赖 192.168.22.12（PVE 宿主）上的监控 LXC（192.168.22.19）持续监测 192.168.22.18（Minisforum）

额外坑：22 端口通，但 ssh 仍然卡住/断线（跨网段更常见）

场景（这次真实遇到的拓扑）

现象（典型表现）

快速判定（先把“端口通”细分）

最小修复（优先消灭 DNS/GSSAPI 造成的特殊情况）

如果仍然不稳：按“跨网段三件套”继续排除

总体架构（最少但够用）

尝试 D：监控栈落地（Prometheus + Grafana + blackbox_exporter）

D0. 前置检查（网络与端口）

D1. 在 192.168.22.18 部署 node_exporter（systemd 方式，最稳）

D2.（可选但强烈建议）在 192.168.22.18 增加“内核/IO 错误计数”自定义指标

D3.（可选）在 192.168.22.18 部署 smartctl_exporter（磁盘健康）

D4. 在 192.168.22.12（PVE）用 LXC 部署 Prometheus + Grafana + blackbox_exporter（推荐）

D4.1 在 PVE（.12）创建一个 Debian LXC 容器

D4.2 在容器内安装 Prometheus（systemd）

D4.3 在容器内安装 blackbox_exporter（systemd）

额外坑：`22` 端口通，但 `ssh` 仍然卡住/断线（跨网段更常见）

E1. DNS 真实查询探测（不靠 blackbox 的“端口可达”，直接用 `dig` 验证解析链路）

3）用 `ip route get` 让路由决策自己说话

修复 2：关闭 OpenWrt 的 `lan` zone NAT