Apache APISIX server-info 插件全解析节点信息定时上报 etcd 与 Control API 查询实战【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisixserver-info 是 Apache APISIX 中一个全局作用域的基础运维插件它以plugin_attr中配置的周期定时把当前 APISIX 节点的基本运行信息实例 ID、启动时间、版本、主机名、etcd 版本写入 etcd供控制面、Dashboard 或其他运维系统消费。本文将以仓库文档 docs/en/latest/plugins/server-info.md 为主体结合插件源码 apisix/plugins/server-info.lua 与测试用例 t/plugin/server-info.t完整讲解该插件的启用、配置、上报机制、底层实现与验证方法帮助你掌握在传统部署traditional与独立数据面data plane场景下正确使用与排查 server-info 的完整技能。插件定位与作用server-info 插件解决的核心问题是让外部系统随时知道当前集群中有哪些 APISIX 实例在运行、各自是什么版本、何时启动、连的是哪个版本的 etcd。从源码看该插件的元信息定义如下apisix/plugins/server-info.lua#L54-L60local _M { version 0.1, priority 990, name plugin_name, -- server-info schema schema, -- 空 object无用户属性 scope global, -- 全局插件无需绑定 Route/Service }几个关键点scope global表示它属于全局插件启用方式是写入配置文件conf/config.yaml的plugins列表而不是像普通插件那样通过 Admin API 绑定到 Route 上priority 990对应官方推荐配置中注释的优先级见 conf/config.yaml.example#L489不过 server-info 不参与请求处理链该优先级更多是约定层面的排序schema是空对象因此没有任何用户可配置的属性Attributes: None插件本身不接受 Route 级别参数。上报字段详解插件周期性写入 etcd 的数据包含 5 个字段官方文档给出了完整定义docs/en/latest/plugins/server-info.md名称类型说明boot_timeintegerAPISIX 实例的启动时间UNIX 时间戳。热更新时会重置但仅 reload 时不会重置。idstringAPISIX 实例 ID。etcd_versionstringAPISIX 所连接的 etcd 集群版本若到 etcd 的网络发生分区则为unknown。versionstringAPISIX 实例的版本号。hostnamestringAPISIX 所在机器 / Pod 的主机名。这些字段的生成逻辑集中在uninitialized_server_info()函数apisix/plugins/server-info.lua#L83-L92local function uninitialized_server_info() local boot_time get_boot_time() return { etcd_version unknown, hostname core.utils.gethostname(), id core.id.get(), version core.version.VERSION, boot_time boot_time, } endboot_time 与共享内存boot_time并非每次上报重新取时间而是持久化在 nginx 共享内存internal-status中apisix/plugins/server-info.lua#L63-L80首次调用时把模块加载时刻os.time()写入 shdict 键server_info:boot_time后续一律从 shdict 读取。因此从实现上可以推断当 APISIX 进程被完全重启共享内存重新分配时 boot_time 会重置而当通过nginx -s reload之类的热加载方式刷新 worker 时共享内存得以保留boot_time 不会变化——这正对应官方文档中热更新重置、仅 reload 不重置的描述。id 的生成规则id来自 apisix/core/id.lua 的core.id.get()。实例 ID 的确定优先级为apisix/core/id.lua#L136-L167读取conf/apisix.uid文件存在则直接使用该文件在首次启动后生成并复用否则读取本地配置apisix.id字段都没有时生成一个 UUID v4 并写入conf/apisix.uid持久化。这保证了同一实例多次重启后 ID 保持稳定方便运维系统按 ID 追踪节点生命周期。etcd_version 的探测初始化时etcd_version为unknown。在每次上报的report()函数中若检测到该值仍为unknown会通过core.etcd.server_version()查询 etcd 集群版本apisix/plugins/server-info.lua#L164-L181优先取etcdcluster字段为空时退回etcdserver字段。该查询底层封装自 apisix/core/etcd.lua#L499-L506返回形如{etcdcluster: 3.5.0, etcdserver: 3.5.0}的结果。一旦查询失败例如 etcd 网络分区该字段保持unknown并在下一次上报时继续重试。启用插件server-info 是全局插件启用方式是在配置文件conf/config.yaml的plugins列表中加入server-infoplugins: - ... - server-info修改配置后执行apisix reload生效。官方示例配置中该插件位于 gzip 之后、traffic-split 之前并标注了# priority: 990conf/config.yaml.example#L489。需要说明的是插件的_M.init()中有两处主动跳过上报的逻辑apisix/plugins/server-info.lua#L262-L275理解它们对排查为什么 etcd 里没有数据至关重要非 etcd 配置模式当core.config不是config_etcd即使用 standalone / yaml 本地配置未连接 etcd时直接返回因为没有 etcd 可写data plane 角色当deployment.role data_plane时直接返回因为数据面节点不应向 etcd 写入任何数据遵循控制面/数据面职责分离原则。也就是说该插件在传统模式traditional或控制面control plane下才会实际写 etcd。定制上报配置plugin_attr插件的上报行为通过conf/config.yaml的plugin_attr段定制目前仅支持一个参数名称类型默认值说明report_ttlinteger60上报数据在 etcd 中的存活时间秒取值范围 [3, 86400]。注官方文档表格中标注的默认值为 36但当前仓库源码中default_report_ttl 60apisix/plugins/server-info.lua#L29且示例配置 conf/config.yaml.example#L610-L612 与测试用例均使用 60实际生效值以源码实现为准。定制示例plugin_attr: server-info: report_ttl: 60参数校验由attr_schema完成apisix/plugins/server-info.lua#L35-L46report_ttl必须是整数最小 3、最大 86400不合法的配置会在启动日志中报failed to check plugin_attr并跳过初始化。report_ttl 与续租周期的关系report_ttl直接决定了上报/续租的频率。初始化时插件注册了一个定时任务plugin#server-infoapisix/plugins/server-info.lua#L287-L306每轮检查逻辑为if now - start_at (report_ttl / 2) then start_at now report(nil, report_ttl) end即每当距上次上报的时间达到report_ttl / 2秒时就执行一次上报/续租从而保证 etcd 中该 lease 的 TTL 永远过半刷新、不会过期。例如report_ttl: 60时大约每 30 秒写一次 etcd。此外仅 worker 0ngx_worker_id() 0会在启动时通过ngx_timer_at(0, report, report_ttl)立即执行一次初始上报apisix/plugins/server-info.lua#L296-L302避免多 worker 同时写同一份数据造成无谓竞争。底层上报流程与 etcd 租约机制理解上报流程是掌握该插件的关键。核心函数report()apisix/plugins/server-info.lua#L152-L238的执行链路如下读取本地信息从 shdict 读取缓存的 server_info不存在则走uninitialized_server_info()生成补全 etcd 版本若etcd_version unknown则尝试查询 etcd 集群版本定位 etcd 键数据写入键/data_plane/server_info/{id}id 即实例 ID先core.etcd.get(key)探测是否已存在按状态分派键不存在404→set(key, server_info, report_ttl)首次写入并创建 etcd lease键存在但值与本地不一致通过core.table.deep_eq深度比较→ 重新set()更新值一致 → 从 shdict 取回lease_id调用core.etcd.keepalive(lease_id)续租apisix/core/etcd.lua#L509-L521回写缓存续租成功后把最新 server_info JSON 编码写回 shdict 键server_info。首次写入时set()会从 etcd 响应中取出lease_id存入 shdictapisix/plugins/server-info.lua#L127-L149后续所有续租都复用它。这样设计的好处是数据带 TTL 自动过期——如果某实例宕机超过report_ttl秒无人续租其记录会被 etcd 自动清理运维系统无需额外实现节点下线检测。通过 Control API 查询server-info 插件向 Control API 注册了只读端点GET /v1/server_infoapisix/plugins/server-info.lua#L251-L259function _M.control_api() return { { methods {GET}, uris {/v1/server_info}, handler get_server_info, } } endControl API 默认监听127.0.0.1:9090需要确认conf/config.yaml中开启了apisix.enable_control详见 docs/en/latest/control-api.md。启用插件并完成一次上报后即可查询curl http://127.0.0.1:9090/v1/server_info -s | jq .返回示例来自官方文档{ etcd_version: 3.5.0, id: b7ce1c5c-b1aa-4df7-888a-cbe403f3e948, hostname: fedora32, version: 2.1, boot_time: 1608522102 }注意GET /v1/server_info返回的是本地节点的信息直接从 shdict 读取若尚未完成上报则返回初始化默认值而 etcd 中/data_plane/server_info/前缀下保存的是所有上报节点的记录两者用途不同前者适合单节点即时排查后者适合集群级盘点。此外也可以通过 APISIX Dashboard 可视化查看 server info 上报结果。测试用例佐证仓库中的测试用例 t/plugin/server-info.t 从两个维度验证了上述行为TEST 1: sanity checkt/plugin/server-info.t#L51-L79以apisix.id: 123456、report_ttl: 60启用插件等待 2 秒后直接读取 etcd 键/data_plane/server_info/{id}断言返回的 JSON 形如{boot_time:数字,etcd_version:版本,hostname:主机名,id:ID,version:版本}验证了数据确实落到了 etcd 且字段完整TEST 2: get server_info from plugin control APIt/plugin/server-info.t#L83-L104通过内部请求访问/v1/server_info断言返回同样的字段结构验证了Control API 端点的可用性。如果你在自己的环境里复现可以先用etcdctl get /data_plane/server_info/ --prefix直接查看 etcd 中的原始记录再与/v1/server_info的返回对比。删除插件不再需要节点信息上报时只需从conf/config.yaml的plugins列表中移除server-infoplugins: - ...然后执行apisix reload。插件卸载时_M.destroy()会调用timers.unregister_timer(plugin#server-info, true)注销定时任务apisix/plugins/server-info.lua#L310-L312停止后续上报已写入 etcd 的旧记录则会随 lease TTL 到期自动过期无需手工清理。实践要点小结该插件适合在传统部署模式或控制面节点上启用数据面deployment.role: data_plane与 standalone 模式不会产生上报report_ttl是唯一可调参数取值范围 386400 秒上报频率约为report_ttl / 2调小可让节点下线记录更快被清理但会增加 etcd 写入频率etcd 网络异常期间etcd_version会显示为unknown这是预期行为而非故障排障顺序建议先确认plugins列表与plugin_attr配置 → 检查启动日志中的failed to check plugin_attr/failed to create initial timer等错误 → 用etcdctl检查/data_plane/server_info/{id}是否存在 → 用curl验证 Control API 端点。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Apache APISIX server-info 插件全解析节点信息定时上报 etcd 与 Control API 查询实战【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisixserver-info 是 Apache APISIX 中一个全局作用域的基础运维插件它以plugin_attr中配置的周期定时把当前 APISIX 节点的基本运行信息实例 ID、启动时间、版本、主机名、etcd 版本写入 etcd供控制面、Dashboard 或其他运维系统消费。本文将以仓库文档 docs/en/latest/plugins/server-info.md 为主体结合插件源码 apisix/plugins/server-info.lua 与测试用例 t/plugin/server-info.t完整讲解该插件的启用、配置、上报机制、底层实现与验证方法帮助你掌握在传统部署traditional与独立数据面data plane场景下正确使用与排查 server-info 的完整技能。插件定位与作用server-info 插件解决的核心问题是让外部系统随时知道当前集群中有哪些 APISIX 实例在运行、各自是什么版本、何时启动、连的是哪个版本的 etcd。从源码看该插件的元信息定义如下apisix/plugins/server-info.lua#L54-L60local _M { version 0.1, priority 990, name plugin_name, -- server-info schema schema, -- 空 object无用户属性 scope global, -- 全局插件无需绑定 Route/Service }几个关键点scope global表示它属于全局插件启用方式是写入配置文件conf/config.yaml的plugins列表而不是像普通插件那样通过 Admin API 绑定到 Route 上priority 990对应官方推荐配置中注释的优先级见 conf/config.yaml.example#L489不过 server-info 不参与请求处理链该优先级更多是约定层面的排序schema是空对象因此没有任何用户可配置的属性Attributes: None插件本身不接受 Route 级别参数。上报字段详解插件周期性写入 etcd 的数据包含 5 个字段官方文档给出了完整定义docs/en/latest/plugins/server-info.md名称类型说明boot_timeintegerAPISIX 实例的启动时间UNIX 时间戳。热更新时会重置但仅 reload 时不会重置。idstringAPISIX 实例 ID。etcd_versionstringAPISIX 所连接的 etcd 集群版本若到 etcd 的网络发生分区则为unknown。versionstringAPISIX 实例的版本号。hostnamestringAPISIX 所在机器 / Pod 的主机名。这些字段的生成逻辑集中在uninitialized_server_info()函数apisix/plugins/server-info.lua#L83-L92local function uninitialized_server_info() local boot_time get_boot_time() return { etcd_version unknown, hostname core.utils.gethostname(), id core.id.get(), version core.version.VERSION, boot_time boot_time, } endboot_time 与共享内存boot_time并非每次上报重新取时间而是持久化在 nginx 共享内存internal-status中apisix/plugins/server-info.lua#L63-L80首次调用时把模块加载时刻os.time()写入 shdict 键server_info:boot_time后续一律从 shdict 读取。因此从实现上可以推断当 APISIX 进程被完全重启共享内存重新分配时 boot_time 会重置而当通过nginx -s reload之类的热加载方式刷新 worker 时共享内存得以保留boot_time 不会变化——这正对应官方文档中热更新重置、仅 reload 不重置的描述。id 的生成规则id来自 apisix/core/id.lua 的core.id.get()。实例 ID 的确定优先级为apisix/core/id.lua#L136-L167读取conf/apisix.uid文件存在则直接使用该文件在首次启动后生成并复用否则读取本地配置apisix.id字段都没有时生成一个 UUID v4 并写入conf/apisix.uid持久化。这保证了同一实例多次重启后 ID 保持稳定方便运维系统按 ID 追踪节点生命周期。etcd_version 的探测初始化时etcd_version为unknown。在每次上报的report()函数中若检测到该值仍为unknown会通过core.etcd.server_version()查询 etcd 集群版本apisix/plugins/server-info.lua#L164-L181优先取etcdcluster字段为空时退回etcdserver字段。该查询底层封装自 apisix/core/etcd.lua#L499-L506返回形如{etcdcluster: 3.5.0, etcdserver: 3.5.0}的结果。一旦查询失败例如 etcd 网络分区该字段保持unknown并在下一次上报时继续重试。启用插件server-info 是全局插件启用方式是在配置文件conf/config.yaml的plugins列表中加入server-infoplugins: - ... - server-info修改配置后执行apisix reload生效。官方示例配置中该插件位于 gzip 之后、traffic-split 之前并标注了# priority: 990conf/config.yaml.example#L489。需要说明的是插件的_M.init()中有两处主动跳过上报的逻辑apisix/plugins/server-info.lua#L262-L275理解它们对排查为什么 etcd 里没有数据至关重要非 etcd 配置模式当core.config不是config_etcd即使用 standalone / yaml 本地配置未连接 etcd时直接返回因为没有 etcd 可写data plane 角色当deployment.role data_plane时直接返回因为数据面节点不应向 etcd 写入任何数据遵循控制面/数据面职责分离原则。也就是说该插件在传统模式traditional或控制面control plane下才会实际写 etcd。定制上报配置plugin_attr插件的上报行为通过conf/config.yaml的plugin_attr段定制目前仅支持一个参数名称类型默认值说明report_ttlinteger60上报数据在 etcd 中的存活时间秒取值范围 [3, 86400]。注官方文档表格中标注的默认值为 36但当前仓库源码中default_report_ttl 60apisix/plugins/server-info.lua#L29且示例配置 conf/config.yaml.example#L610-L612 与测试用例均使用 60实际生效值以源码实现为准。定制示例plugin_attr: server-info: report_ttl: 60参数校验由attr_schema完成apisix/plugins/server-info.lua#L35-L46report_ttl必须是整数最小 3、最大 86400不合法的配置会在启动日志中报failed to check plugin_attr并跳过初始化。report_ttl 与续租周期的关系report_ttl直接决定了上报/续租的频率。初始化时插件注册了一个定时任务plugin#server-infoapisix/plugins/server-info.lua#L287-L306每轮检查逻辑为if now - start_at (report_ttl / 2) then start_at now report(nil, report_ttl) end即每当距上次上报的时间达到report_ttl / 2秒时就执行一次上报/续租从而保证 etcd 中该 lease 的 TTL 永远过半刷新、不会过期。例如report_ttl: 60时大约每 30 秒写一次 etcd。此外仅 worker 0ngx_worker_id() 0会在启动时通过ngx_timer_at(0, report, report_ttl)立即执行一次初始上报apisix/plugins/server-info.lua#L296-L302避免多 worker 同时写同一份数据造成无谓竞争。底层上报流程与 etcd 租约机制理解上报流程是掌握该插件的关键。核心函数report()apisix/plugins/server-info.lua#L152-L238的执行链路如下读取本地信息从 shdict 读取缓存的 server_info不存在则走uninitialized_server_info()生成补全 etcd 版本若etcd_version unknown则尝试查询 etcd 集群版本定位 etcd 键数据写入键/data_plane/server_info/{id}id 即实例 ID先core.etcd.get(key)探测是否已存在按状态分派键不存在404→set(key, server_info, report_ttl)首次写入并创建 etcd lease键存在但值与本地不一致通过core.table.deep_eq深度比较→ 重新set()更新值一致 → 从 shdict 取回lease_id调用core.etcd.keepalive(lease_id)续租apisix/core/etcd.lua#L509-L521回写缓存续租成功后把最新 server_info JSON 编码写回 shdict 键server_info。首次写入时set()会从 etcd 响应中取出lease_id存入 shdictapisix/plugins/server-info.lua#L127-L149后续所有续租都复用它。这样设计的好处是数据带 TTL 自动过期——如果某实例宕机超过report_ttl秒无人续租其记录会被 etcd 自动清理运维系统无需额外实现节点下线检测。通过 Control API 查询server-info 插件向 Control API 注册了只读端点GET /v1/server_infoapisix/plugins/server-info.lua#L251-L259function _M.control_api() return { { methods {GET}, uris {/v1/server_info}, handler get_server_info, } } endControl API 默认监听127.0.0.1:9090需要确认conf/config.yaml中开启了apisix.enable_control详见 docs/en/latest/control-api.md。启用插件并完成一次上报后即可查询curl http://127.0.0.1:9090/v1/server_info -s | jq .返回示例来自官方文档{ etcd_version: 3.5.0, id: b7ce1c5c-b1aa-4df7-888a-cbe403f3e948, hostname: fedora32, version: 2.1, boot_time: 1608522102 }注意GET /v1/server_info返回的是本地节点的信息直接从 shdict 读取若尚未完成上报则返回初始化默认值而 etcd 中/data_plane/server_info/前缀下保存的是所有上报节点的记录两者用途不同前者适合单节点即时排查后者适合集群级盘点。此外也可以通过 APISIX Dashboard 可视化查看 server info 上报结果。测试用例佐证仓库中的测试用例 t/plugin/server-info.t 从两个维度验证了上述行为TEST 1: sanity checkt/plugin/server-info.t#L51-L79以apisix.id: 123456、report_ttl: 60启用插件等待 2 秒后直接读取 etcd 键/data_plane/server_info/{id}断言返回的 JSON 形如{boot_time:数字,etcd_version:版本,hostname:主机名,id:ID,version:版本}验证了数据确实落到了 etcd 且字段完整TEST 2: get server_info from plugin control APIt/plugin/server-info.t#L83-L104通过内部请求访问/v1/server_info断言返回同样的字段结构验证了Control API 端点的可用性。如果你在自己的环境里复现可以先用etcdctl get /data_plane/server_info/ --prefix直接查看 etcd 中的原始记录再与/v1/server_info的返回对比。删除插件不再需要节点信息上报时只需从conf/config.yaml的plugins列表中移除server-infoplugins: - ...然后执行apisix reload。插件卸载时_M.destroy()会调用timers.unregister_timer(plugin#server-info, true)注销定时任务apisix/plugins/server-info.lua#L310-L312停止后续上报已写入 etcd 的旧记录则会随 lease TTL 到期自动过期无需手工清理。实践要点小结该插件适合在传统部署模式或控制面节点上启用数据面deployment.role: data_plane与 standalone 模式不会产生上报report_ttl是唯一可调参数取值范围 386400 秒上报频率约为report_ttl / 2调小可让节点下线记录更快被清理但会增加 etcd 写入频率etcd 网络异常期间etcd_version会显示为unknown这是预期行为而非故障排障顺序建议先确认plugins列表与plugin_attr配置 → 检查启动日志中的failed to check plugin_attr/failed to create initial timer等错误 → 用etcdctl检查/data_plane/server_info/{id}是否存在 → 用curl验证 Control API 端点。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
