发现 · XB 现场笔记

Consul 发现结果取决于健康策略与新鲜度

Thu, 06 Apr 2028 00:00:00 +0000

Consul 服务发现提供注册端点和已经记录的健康观测，不能承诺每个返回端点都会成功响应调用方的下一次请求。实用的运维模型需要分开四件事：注册了什么、哪些检查与该实例有关、查询接受哪些状态，以及这些观测可能已经过去多久。仅仅成功解析到一个地址，并没有自动建立上述全部保证，也没有证明业务请求已经能够完成。

注册记录与健康状态是两回事

catalog 存储注册信息，健康端点再附上检查结果。不加过滤的 /v1/health/service/web 响应，可以包含检查为 critical 的实例。检查失败并不会自动抹去服务注册；显式注销、配置了持续 critical 后自动移除，属于不同的生命周期机制。ACL 也可能影响读者能看到哪些记录，所以查询里缺少实例，不能只归因于健康检查失败。

注册的检查通常从 critical 开始，除非显式提供初始状态。但这并不意味着每个注册服务都一定具有有意义的就绪检查。判断某个服务实例时，需要结合它自己的服务级检查，以及 serfHealth 等节点级检查。同一节点上，数据库服务的检查失败，不会自动让不相关的 Web 服务检查失败；节点级检查变为 critical，则会影响该节点上的服务。不要把“相关检查全部通过”误解成“这台机器上的所有服务检查都必须通过”。

检查结果也不只是布尔值。脚本退出码零表示 passing，一表示 warning，其他退出码表示 critical；HTTP 检查把成功的 2xx 视为健康，把 429 视为 warning，其他响应表示失败。这些状态究竟证明了什么，仍取决于探测内容。TCP 握手成功或进程存在，并不证明应用能完成一次真实请求；检查实现必须与希望验证的能力对应。

DNS 并非总是只返回 passing

HTTP 健康端点的 passing=true 要求相关检查全部 passing。Consul DNS 服务查询的默认策略不同：warning 实例仍可符合候选条件，critical 实例则被排除。配置 dns_config.only_passing=true 后，warning 也会被排除。因此，一个 warning 实例出现在 DNS，却不在 passing-only API 结果里，不一定意味着检查失效，也可能只是两条路径明确采用了不同策略。

比较结果时，应保持服务、数据中心、适用时的命名空间，以及观察时间窗口一致。Consul 的 DNS 通常监听 8600 端口；如果没有配置相应转发，只向系统解析器查询，并不是直接检查 Consul。直接查询能够去掉这一中间环节，但仍然不会自动从调用方网络探测业务端点，也不能证明返回地址在所有网络路径上都可达。

新鲜度包含多个阶段

探测间隔、探测超时、连续失败阈值、agent 到 server 的传播、读取一致性，以及客户端缓存，都可能增加延迟。三十秒间隔不等于端到端三十秒内必定摘除。TTL 检查从最近一次更新计算到期；如果服务在 TTL 中途失败，并不一定还会获得完整的一段新 TTL。应观察真实状态转移，不能把一个配置数字当成所有故障路径的精确上界。

反熵负责修复 agent 本地状态与 catalog 的差异。文档中的周期随集群规模变化，而且是近似间隔；注册变更本身也会触发更新。如果同步持续失败，差异可以跨越多个周期，因此周期同步既不是唯一更新机制，也不是最长收敛时间的保证。网络不可达、权限错误或存储故障，不会因为下一分钟到来就必然消失。

HTTP 查询通常使用 default 一致性模式，DNS 通常允许 stale 读取。consistent HTTP 读取要求 leader 向多数派确认身份，会付出额外代价。然而，更强的 catalog 读取一致性，也无法发现尚未被任何检查观测到的应用故障。注册状态的一致性与真实业务的就绪程度，始终是不同问题，不能互相替代。

坏掉的样子

passing 探测可能检查了错误依赖、从不同网络发起，或者遗漏死锁。反过来，如果每个实例的就绪状态都绑定到同一个共享依赖，共同故障又可能一次摘除整个池。应围绕可用的请求能力和预期降级行为选择检查，同时保留客户端超时及有界恢复路径，不能把注册表当成消除所有请求失败的机制。

不要根据一张 API 与 DNS 不一致的截图就宣布检查没有运行。先检查 warning 策略、相关检查 ID、ACL 可见性、注销行为，以及缓存或陈旧观测。critical 实例继续出现在未过滤的健康响应里，本来就是正常现象，不是服务器忽略过滤条件的证据。只有先确认比较对象与策略，才有依据继续追查异常。

快速验证

把代码保存为 consul_filter.py，执行 python3 consul_filter.py。这个标准库实验使用合成记录，不启动 Consul agent，不发网络请求。它验证筛选差异和陈旧快照风险，并不是 Consul 运行时实现的集成测试。

from copy import deepcopy

nodes = {"n1": "passing", "n2": "critical"}
services = [
 {"ID": "web-1", "Name": "web", "Node": "n1", "Status": "passing"},
 {"ID": "web-2", "Name": "web", "Node": "n1", "Status": "warning"},
 {"ID": "db-1", "Name": "db", "Node": "n1", "Status": "critical"},
 {"ID": "web-3", "Name": "web", "Node": "n2", "Status": "passing"},
]


def health_rows(name):
 # Synthetic snapshot: only the node and THIS service contribute checks.
 return [
 {"ID": item["ID"], "Checks": [nodes[item["Node"]], item["Status"]]}
 for item in services if item["Name"] == name
 ]


def selected(rows, allowed):
 return [row["ID"] for row in rows if all(s in allowed for s in row["Checks"])]


snapshot = health_rows("web")
assert [row["ID"] for row in snapshot] == ["web-1", "web-2", "web-3"]
assert selected(snapshot, {"passing"}) == ["web-1"]
assert selected(snapshot, {"passing", "warning"}) == ["web-1", "web-2"]
print("unfiltered: web-1 web-2 web-3; passing-only: web-1; default DNS policy: web-1 web-2")

previous = deepcopy(snapshot)
services[0]["Status"] = "critical"
current = health_rows("web")
assert selected(previous, {"passing"}) == ["web-1"] # An old snapshot stays old.
assert selected(current, {"passing"}) == []
assert len(current) == 3 # Failing health is not deregistration.
assert selected(current, {"passing", "warning"}) == ["web-2"]
print("service failure changes selection, not registration; an old snapshot still selects web-1")

nodes["n1"] = "critical"
assert selected(health_rows("web"), {"passing", "warning"}) == []
print("node failure excludes both web instances on n1; db-1 never controlled their earlier health")

断言证明不相关的数据库健康不会控制 Web 选择，warning 与 critical 在两种策略下不同，而失败注册仍保留在未过滤视图中。更新当前状态，也不会改写之前复制的快照。最后将节点状态改为 critical，模型会把该节点上的两个 Web 实例都移出符合 DNS 策略的候选集合。这些结果是确定的集合运算，不是实际测得的服务故障摘除延迟。

部署验收仍需在配置的 warning 策略下，对照真实未过滤与 passing-only 健康响应，以及直接 DNS 查询。分别记录检查状态转换和客户端不再使用实例的时刻。本次没有执行这项集成；离线模型没有提供探测时间测量、DNS 报文证据或可用性保证。把模型的适用范围写清楚，才能避免“断言都通过”掩盖尚未验证的运行链路。

来源

Consul Health API，服务实例、检查、passing 过滤和 ACL 可见性，已核验 2026-10-15。
Consul 健康检查，初始状态、脚本及 HTTP 结果与 TTL 到期，已核验 2026-10-15。
Consul DNS 配置，only_passing 与相关检查，已核验 2026-10-15。
Consul DNS 行为，8600 端口和缓存控制，已核验 2026-10-15。
Consul 一致性，agent 更新及近似反熵周期，已核验 2026-10-15。
Consul 一致性模式，HTTP、DNS 默认模式和多数派确认，已核验 2026-10-15。
Consul 健康检查参考，超时、阈值和 critical 服务注销，已核验 2026-10-15。

Sitemap 帮助爬虫发现页面

Wed, 30 Jun 2027 00:00:00 +0000

Sitemap 为爬虫提供一份明确的候选网址清单，适合帮助发现新内容或普通导航中较深的文档。这份列表不会绕过登录、授予抓取权限、保证搜索收录，也不能承诺某天一定重新访问。应把它视为计划公开文档的发布清单，并让清单与规范网址及实际发布状态保持一致。文件成功上传，只能说明某一步交付发生了，不能替代后续抓取和收录证据。

从发布清单生成

使用与公开页面相同的权威内容筛选规则，排除草稿、私有文档和多余的跟踪参数变体。源码目录里存在一个文件，不代表它已经对应公开 URL；反过来，分页、翻译文档或生成路由，也未必与源文件逐一对应。因此需要查看生成器实际输出，而不是仅凭目录列表猜测发布范围。内容筛选与 sitemap 生成相互独立维护，容易出现遗漏或提前暴露未发布入口。

XML sitemap 使用声明的命名空间，以及包含网址条目的 urlset，每个 loc 提供完整网址。XML 转义与 URL 编码解决不同问题：分隔查询参数的与号，需要在 XML 文本里转义，而网址本身的字符也必须符合相应 URI 表示方式。生成后应重新解析文件，确认经过两层处理，仍然得到原本希望发布的网址，不能因为 XML 看起来能打开就省略这一检查。

还要遵守格式的范围与大小条件。通常应列出相应主机及允许位置范围内的网址，受支持的跨站提交安排有额外规则。每份 sitemap 最多五万个网址，未压缩内容不得超过 52,428,800 字节。gzip 可以减少传输量，却不能取消解压后的上限。更大的清单应拆分并使用适当索引，不能为了让文件通过检查而悄悄截断后面的页面。

这份清单本身也是公开数据。私有文档没有出现在导航里，并不意味着它的网址可以放心写入公开 sitemap。发布前应检查生成 XML 是否暴露了不该公开的入口，同时在资源处独立执行访问控制。爬虫发现偏好与权限控制是不同机制，清单筛选不能替代真正的授权检查。

坏掉的样子

XML 合法的文件，仍可能列出跳转、缺失页面或不应进入索引的内容。应同时验证目标与语法，并让目标上的 canonical 声明符合预期清单。某个地址返回二百，却只有登录界面或通用错误页，不能证明列出的文档真正可用。Sitemap 自身成功交付，与其描述的页面是否有用，需要分别检查，不能在一个状态码上完成所有判断。

修改时间也可能失真。提供 lastmod 时，应依据页面有意义的变化，而不是每次构建都刷新所有条目的时间。Google 明确说明，它会使用持续准确的 lastmod，并忽略 priority 和 changefreq。这些字段不是调度接口，把所有页面都标成最高优先级，也不能命令爬虫增加访问。没有可信历史依据时，省略可选字段比编造精确时间更诚实。

Sitemap 不能让私有页面自动公开，也不会覆盖 robots 限制。提交之后，搜索引擎未必选择相同的规范网址，未必读取每一项，更不保证全部进入结果。普通导航仍然应该可用，后续结果则需要依据实际抓取或索引报告判断。不能把上传成功写成发现和收录已经完成，否则发布记录与外部系统的真实状态就会混在一起。

快速验证

保存为 sitemap.py，执行 python3 sitemap.py。标准库实验提供生成的 XML sitemap，以及一个很小的本地发布清单。三个条目公开，其中一个包含两个查询参数；草稿被排除。生成的网址只指向临时回环源站，验证器在请求目标之前先检查范围，因此不会顺着输入访问无关外部主机。这里的清单内容全部是演示数据。

from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread
from urllib.parse import urlsplit
import json
import xml.etree.ElementTree as ET

namespace = 'http://www.sitemaps.org/schemas/sitemap/0.9'
ET.register_namespace('', namespace)
pages = {'/article': True, '/zh/article': True, '/report?year=2026&region=west': True, '/draft': False}
state = {'bad_entry': False}


class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 if self.path == '/sitemap.xml':
 root = ET.Element(f'{{{namespace}}}urlset')
 paths = [path for path, public in pages.items() if public]
 if state['bad_entry']:
 paths.append('/missing')
 for path in paths:
 item = ET.SubElement(root, f'{{{namespace}}}url')
 ET.SubElement(item, f'{{{namespace}}}loc').text = f'http://127.0.0.1:{self.server.server_port}{path}'
 status, data, kind = 200, ET.tostring(root, encoding='utf-8', xml_declaration=True), 'application/xml'
 else:
 status = 200 if pages.get(self.path) else 404
 data, kind = (b'published page' if status == 200 else b'missing'), 'text/plain'
 self.send_response(status)
 self.send_header('Content-Type', kind)
 self.send_header('Content-Length', str(len(data)))
 self.end_headers()
 self.wfile.write(data)

 def log_message(self, *args):
 pass


server = ThreadingHTTPServer(('127.0.0.1', 0), Handler)
thread = Thread(target=server.serve_forever)
thread.start()
try:
 def fetch(path):
 connection = HTTPConnection('127.0.0.1', server.server_port, timeout=5)
 try:
 connection.request('GET', path)
 response = connection.getresponse()
 return response.status, response.read()
 finally:
 connection.close()

 def validate(data):
 root = ET.fromstring(data)
 assert root.tag == f'{{{namespace}}}urlset'
 locations = [item.text for item in root.findall(f'{{{namespace}}}url/{{{namespace}}}loc')]
 assert len(locations) == len(set(locations))
 for location in locations:
 parsed = urlsplit(location)
 assert (parsed.scheme, parsed.hostname, parsed.port) == ('http', '127.0.0.1', server.server_port)
 path = parsed.path + ('?' + parsed.query if parsed.query else '')
 status, _ = fetch(path)
 if status != 200:
 raise ValueError(f'listed URL returned {status}: {path}')
 return locations

 status, data = fetch('/sitemap.xml')
 assert status == 200 and b'&amp;' in data
 locations = validate(data)
 assert len(locations) == 3 and all('/draft' not in value for value in locations)
 assert any('?year=2026&region=west' in value for value in locations)
 state['bad_entry'] = True
 _, invalid = fetch('/sitemap.xml')
 try:
 validate(invalid)
 except ValueError as error:
 rejection = str(error)
 else:
 raise AssertionError('missing destination accepted')
 print(json.dumps({'public_urls': len(locations), 'query_round_trip': True,
 'draft_excluded': True, 'invalid_destination_rejected': rejection,
 'indexing_tested': False}))
finally:
 server.shutdown()
 thread.join()
 server.server_close()

第一份 sitemap 在正确命名空间中包含三个不重复 loc。原始 XML 将查询分隔符写成 &，解析后则恢复成网址中预期的与号。三个目标均返回二百，草稿没有进入清单。示例没有填入可选修改日期，因为它不存在能够支持这些日期的发布历史来源。验证输出保留各项结论，而不是仅记录解析器没有报错。

随后实验加入一个缺失目标，但 sitemap 仍是合法 XML，获取它的 HTTP 状态也仍为二百。第二次验证会在列出的地址返回四零四时失败，说明语法检查不能证明清单有效。验证器报告问题，而不是在检查过程中静默删掉坏条目，避免把错误隐藏成已经通过的发布结果。清单修正应当回到生成输入完成。

实验没有联系搜索引擎，小验证器也没有实现全部协议限制和索引规则。它验证的是所列案例的生成、转义、命名空间、唯一性、本地范围及目标可达性。真正发布之前，还应把 sitemap 与完整的计划公开清单比较，并在对外声明的网址读取已发布文件。这样建立的是实际交付证据，不是对爬虫后续选择的控制承诺。

来源

Sitemaps.org protocol，XML 结构、网址编码、范围及大小限制，已核验 2026-09-13。
Google: build and submit a sitemap，规范网址、有意义的 lastmod 及不采用的提示字段，已核验 2026-09-13。

robots.txt 引导抓取，但不授予或禁止访问

Fri, 02 Oct 2026 00:00:00 +0000

robots.txt 向实现 Robots Exclusion Protocol 的自动客户端传达抓取规则，可以减少对昂贵或无用路径的遍历，但服务器不会因此自动按照文件内容拦截请求。RFC 9309 明确区分这些规则与访问授权。应把它当作面向合作爬虫的公开接口，真正能否读取受保护资源，仍由认证和授权机制决定。配置中写了禁止抓取，不等于服务器已经建立了权限边界。

对准目标爬虫与实际路径

标准文件位于相应方案和 authority 的 /robots.txt，放在应用子目录下的同名文件，不会自动成为整个源站的策略。User-agent 分组标识规则面向的爬虫产品，通配分组按协议为其他代理提供适用规则。路径规则针对请求目标匹配，大小写不同可能产生不同结果。路由变化时应重新检查具体 URL，不能只看规则文字仍然像原来的样子。

文件应以 UTF-8 纯文本形式提供，并明确实际响应。宽泛的静态站回退规则，可能在 robots 路径返回二百和首页内容；这只证明 HTTP 已经交付，不能证明爬虫取得了预期策略。复杂的 Allow、Disallow 组合、转义和通配模式，需要对照协议及真实爬虫实现验证。一个简单解析器案例不能替整个规则集合证明所有边界行为正确。

坏掉的样子

在 robots.txt 中列出私有路径，并不会隐藏路径；公开的规则文件反而可能告诉别人它在哪里。客户端可以完全不读策略就直接请求，合作爬虫自己作出的不抓取决定，也不会转化为源站上的访问规则。确实需要限制的内容，应在请求授权的位置执行限制；Disallow 行不能替代账号权限或其他实际访问检查。公开规则和私有资源的保护条件必须分开维护。

抓取与收录也是不同问题。Google 文档说明，被禁止抓取的 URL 仍可能因为其他来源的链接出现在搜索结果里。如果爬虫无法读取页面，也可能看不到页面上希望它执行的 noindex 指令。公开内容需要按目标选择合适的收录控制，私有内容则要使用真实访问限制。不能认为阻止内容下载，就会自动移除所有已存在的搜索记录或外部引用。

策略获取失败同样有不同语义。RFC 9309 允许爬虫在文件不可用时访问资源，例如收到四开头的 HTTP 响应；如果服务器或网络错误导致文件无法到达，例如五开头的响应，爬虫起初必须假定完全禁止。规范还定义了长期失败与缓存副本的处理。部署坏了 robots 文件，可能改变抓取行为，不应只把它当成少了一份装饰性文本。

爬虫缓存还会带来发布延迟。RFC 9309 通常建议不要使用超过二十四小时的缓存策略，但文件无法到达时存在例外；这不是所有爬虫都会准点更新的承诺。源站已经成功更新，不代表每个爬虫都重新取到了规则。应分别保存当前响应、预期策略和实际观察到的爬虫行为，不能拿其中一种证据替另一种。sitemap 指针有助于发现地址，但不会授予访问权限，也不能保证每个列出的网址一定被抓取或收录。发现、抓取、读取与收录，是需要区分的多个步骤。

快速验证

保存为 robots.py，运行 python3 robots.py。临时回环 HTTP 服务提供一份简短 robots 文件及无害演示内容。脚本先获取实际策略，再把收到的文本交给 Python 的 RobotFileParser。选择的路径只使用简单 Disallow 前缀，没有规则冲突，也不涉及复杂通配处理；这样可以把验证集中在规则建议与服务器实际拦截的区别上。

from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread
from urllib.robotparser import RobotFileParser
import json


class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 if self.path == '/robots.txt':
 status, data = 200, b'User-agent: *\nDisallow: /private/\n'
 elif self.path in ('/private/report', '/public'):
 status, data = 200, b'public demonstration data\n'
 else:
 status, data = 404, b'missing\n'
 self.send_response(status)
 self.send_header('Content-Type', 'text/plain; charset=utf-8')
 self.send_header('Content-Length', str(len(data)))
 self.end_headers()
 self.wfile.write(data)

 def log_message(self, *args):
 pass


server = ThreadingHTTPServer(('127.0.0.1', 0), Handler)
thread = Thread(target=server.serve_forever)
thread.start()
try:
 origin = f'http://127.0.0.1:{server.server_port}'

 def fetch(path):
 connection = HTTPConnection('127.0.0.1', server.server_port, timeout=5)
 try:
 connection.request('GET', path)
 response = connection.getresponse()
 return response.status, response.read().decode()
 finally:
 connection.close()

 status, rules = fetch('/robots.txt')
 assert status == 200
 parser = RobotFileParser(origin + '/robots.txt')
 parser.parse(rules.splitlines())
 decisions = {path: parser.can_fetch('ExampleBot', origin + path)
 for path in ('/private/report', '/public', '/Private/report')}
 assert decisions == {'/private/report': False, '/public': True, '/Private/report': True}
 direct_status, direct_body = fetch('/private/report')
 assert direct_status == 200 and direct_body == 'public demonstration data\n'
 print(json.dumps({'parser_decisions': decisions, 'direct_http_status': direct_status,
 'direct_http_body': direct_body, 'search_index_tested': False}))
finally:
 server.shutdown()
 thread.join()
 server.server_close()

解析器拒绝 /private/report，允许 /public，也允许大小写不同的 /Private/report。这些只是返回给调用方的判断。随后脚本故意不采用解析器的拒绝结果，而是直接发送普通 HTTP GET 请求 /private/report。服务器仍返回二百和公开演示文字，证明策略文件没有自动安装访问屏障。这里的“private”只是演示路径名，里面没有真实私密材料。

本轮没有重跑这个未改动的套接字实验。实验没有任何搜索引擎或索引服务参与，只验证这个解析器在选定输入上的匹配，以及客户端决定与源站执行之间的区别。它不能证明标准库完整符合 RFC 的所有细节，也不能预测每个爬虫的行为。发布策略之前，应检查代表性的允许与拒绝地址，核对实际响应，并独立确认资源的授权要求已满足。这样才能把抓取偏好与真正的访问保护都落实到各自正确的位置。

来源

RFC 9309: Robots Exclusion Protocol，建议性规则、路径匹配与可用性处理，已核验 2026-10-15。
Google: introduction to robots.txt，抓取控制及其不能保证阻止收录的边界，已核验 2026-10-15。
Python 3.14: urllib.robotparser，本地实验实际使用的解析器接口，已核验 2026-10-15。