Web · XB 现场笔记

nginx 选择第一个匹配正则，不会计算通用具体程度分数

Mon, 27 Dec 2027 00:00:00 +0000

nginx 不会给所有 location 表达式计算一份通用的具体程度分数。普通前缀按匹配长度选择，精确 location 可以结束搜索，竞争正则则按声明顺序求值。某个表达式在人看来更窄，也可能输给前面更宽的正则。把这些选择规则混在一起，是许多看似仔细的路由变更影响意外路径的原因，必须分别理解每类规则。

坏掉的样子

通用 .css 后缀正则，可以先于后面的 /assets/ 限定正则获胜。后者因为包含目录，看起来似乎更具体，但 nginx 不会比较两个模式在语义上谁更窄。在这里的平面结构中，只要两者都匹配，顺序就决定使用哪个配置。路径更长或正则文字更多，都不是正则之间的额外优先分。

调整普通前缀顺序是另一回事。把 /assets/ 移到 / 之前，不会让它“更优先”；在采用前缀结果时，更长匹配本来就决定它获胜。如果把所有 location 都当成同一个先匹配先使用列表，审阅可能做出无效调整，却漏掉真正控制故障路径的正则顺序。修改文本与修改行为之间，需要通过规则和请求证据连接。

较短的 ^~ 前缀，也不是整个子树的永久保护层。如果存在更长的普通前缀并被选中，较短的标记前缀就不再是抑制正则阶段的候选。因此，新增一个看似无害的更详细前缀，可能让原来停留在标记 location 的请求重新被后缀正则接管。这种变化不能仅凭新增块自身内容看出来。

nginx 1.28.0 平面 location 分别遵循精确终止、最长前缀与正则顺序规则；路由标记不验证下游策略。

快速验证

下文结果归属于历史文章报告，本轮没有重跑；保留的验证文件中未找到原始集成运行日志。运行需备好本地固定镜像并启用 Python 断言；清理仅尽力执行，不能据此保证所有资源已删除。

使用宿主 Python、Docker 和固定 nginx 镜像运行脚本。实测为 Linux arm64 上的 nginx 1.28.0、Docker 29.3.1。它构建两份临时配置，分别执行 nginx -t，再通过宿主回环端口发送真实请求。每份配置都只使用平面 location，结束时尝试清理自己的容器、镜像标签和私有网络，不修改既有服务：

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True);target.write_text(content)
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'

prefixes=[
 'location / { return 200 "fallback"; }',
 'location /assets/ { return 200 "asset-prefix"; }',
 'location = /assets/exact.css { return 200 "exact"; }',
 'location ^~ /static/ { return 200 "static-prefix"; }',
 'location /static/dynamic/ { return 200 "dynamic-prefix"; }']
regexes=[r'location ~ \.css$ { return 200 "generic-css"; }',r'location ~ ^/assets/ { return 200 "asset-regex"; }']
for reverse,expected in [(False,'generic-css'),(True,'asset-regex')]:
 ordered_prefixes=list(reversed(prefixes)) if reverse else prefixes
 ordered_regexes=list(reversed(regexes)) if reverse else regexes
 locations='\n'.join(ordered_prefixes+ordered_regexes)+'\n'+r'location ~* \.txt$ { return 200 "case-folded-text"; }'
 with lab(config(locations)) as (container,request):
 cases={'/assets/file.css':expected,'/assets/exact.css':'exact','/static/file.css':'static-prefix','/static/dynamic/file.css':'generic-css','/static/dynamic/plain':'dynamic-prefix','/README.TXT':'case-folded-text','/elsewhere.CSS':'fallback','/elsewhere':'fallback'}
 for path,wanted in cases.items():
 status,headers,body=request(path);assert status==200 and body.decode()==wanted,(path,status,body)
print('reversing the matching regex declarations changes the winner; the first matching regex is not necessarily the most specific')
print('exact locations and longest-prefix selection ignore declaration order; a longer ordinary prefix can make a shorter ^~ prefix irrelevant')

第一份配置把 .css 正则放在 /assets/ 开头的正则之前，请求 /assets/file.css 返回 generic-css。第二份反转两个正则，相同请求改为返回 asset-regex。请求没有变得更具体或更宽泛，变化的只有两个同时匹配模式的顺序。这为“正则自动选最具体”的说法提供直接反例。

脚本还在两份配置之间反转普通前缀声明，它们相关结果保持稳定。/static/dynamic/plain 仍使用更长普通前缀，无关路径仍进入宽泛默认处理。这个对照把前缀文本重排与正则文本重排分开，不会因为两种操作都叫调整顺序，就假定它们具有相同路由效果。判断改动影响时，应先识别被移动的是哪类块。

精确 /assets/exact.css 在两份配置中都获胜，虽然这个路径也匹配两条正则，它始终返回 exact。实验因此包含一条有意不受正则顺序影响的路径，避免把“第一个匹配正则”说成无条件覆盖所有其他 location 类型的规则。完整优先关系比一句简化口号更能解释边界。

/static/file.css 留在 ^~ /static/ 中，返回 static-prefix。但 /static/dynamic/file.css 具有更长普通前缀，于是 .css 正则仍会被考虑，并返回 generic-css。这验证了 ^~ 对被选中前缀的限定：修饰符属于那个 location，而不是隐藏地继承到每个更深前缀上的保护。

大小写修饰符单独验证。~* 文本文件模式匹配 /README.TXT；区分大小写的 .css 模式不匹配 /elsewhere.CSS，后者进入默认处理。这些结论针对实验中的明确正则和 Linux 环境，不是声称所有文件系统路径或所有平台都遵守相同大小写规则。匹配方式与文件读取方式也应分别判断。

让重叠在审阅中可见

对每条正则，找出也匹配更早表达式的路径，并记录预期由谁处理。测试既要覆盖两个模式重叠，也要覆盖两者都不匹配的情况。只在单条正则孤立存在时测试，无法发现后来有人在前面加入另一个表达式时引入的优先冲突。重叠本身应成为可审阅的契约，而不是偶然顺序。

当精确或前缀 location 能自然表达路由时，可以使用它们，并让有意存在的正则重叠容易理解。正则本身并非错误，但其顺序会成为服务契约的一部分。包含配置发生变化也可能改变有效顺序，因此需要检查完整加载配置，不能只审阅脱离上下文的文件片段，再根据局部排列推断结果。

在已有标记前缀下面增加更长前缀时，重新测试经该路径进入的后缀请求，不要假定旧 ^~ 仍控制它。最后，验证获胜块中的缓存头、代理与访问控制等实际行为。选中预期标记只证明路由，不能证明块内每项策略都正确，更不能替代真实服务处理链的回归检查。

来源

nginx core location directive，第一个匹配正则、前缀优先关系与大小写修饰符，已核验 2026-10-15。
How nginx processes a request，已选 server 内的配置选择，已核验 2026-10-15。
nginx 1.28.0 core implementation，指定版本的前缀与正则 location 搜索行为，已核验 2026-10-15。

框架策略明确谁可以嵌入当前页面

Thu, 23 Sep 2027 00:00:00 +0000

点击劫持利用用户对界面的误判，让一个动作落到并非其真实意图的控件上。恶意父页面可以把被嵌入的应用放在误导性视觉层后面，使用户点击实际进入该应用中的真实按钮。父页面不必能够读取子页面的文档结构，用户仍然可以与框架里的内容交互。因此，同源读取限制不能替代应用是否允许被嵌入的独立决定，也不能仅靠看不到对方文档就判断点击过程安全。

被嵌入的响应可以通过内容安全策略禁止任何祖先嵌入，或者明确列出允许的祖先来源。这里写的应当是获准包含当前文档的页面来源。假设商户页面嵌入支付页面，应由支付页面的策略允许商户来源；仅列出支付组件自己的来源，并不能表达商户有权嵌入它。配置之前先明确哪一份响应属于子页面、哪个来源是父页面，可以避免把允许列表方向写反。

把限制放到正确的响应上

嵌入祖先指令回答谁能嵌入当前文档，框架来源指令则回答当前文档自己可以加载哪些框架。给子页面设置严格的 frame-src，并不会阻止另一个父页面嵌入它。默认来源全部拒绝，也不会作为 frame-ancestors 的回退值。这些指令控制的是关系中的不同方向，不能仅因为名字都涉及框架，就把其中一个当成另一个的替代品。

嵌入祖先指令不能通过 CSP 的 meta 元素生效，必须通过响应头交付。遇到多层嵌套时，每一级祖先都需要符合策略，而不只是直接父级。某个组件即使可以合法放在指定应用中，当该应用本身又被放进未经许可的外层框架时，仍可能被阻止。因此制定允许列表时，要审阅整个预期嵌入链，不能只凭最内层组件和它紧邻的容器作判断。

坏掉的样子

一次部署可能只给容器页面增加了策略，却让真正敏感的子页面响应保持不受限制；另一次部署可能把策略写入 HTML 元数据，看到配置文字存在就误以为浏览器会执行。应检查实际被框架加载的响应，并验证浏览器是否渲染。仅收到二百状态，既不能证明嵌入成功，也不能证明没有框架防护，因为浏览器可以收到文档后，拒绝在当前祖先环境中显示它。

互相冲突的响应头也可能误导审阅者。在支持这套规则的现代浏览器里，强制执行的嵌入祖先策略优先于该响应的 X-Frame-Options。给允许某个父来源的策略再附加一个 DENY，并不必然得到期望中的更严格结果。如果确实需要保留多个响应头，应让它们与实际受众和浏览器支持约定一致，不能假定它们都像多份 CSP 那样自然取限制交集。

快速验证

将代码保存为 frame-policy.py，执行 python3 frame-policy.py --serve，并打开打印出的父页面地址。本次实际使用 Python 3.14.4 与 Chrome 152。父服务和子服务位于不同的本机回环端口，六份子响应只有合成说明文字，以及表示成功渲染的消息。父页面只接受预期子来源发来的消息并展示结果，结束后按控制键加 C 关闭两个临时服务，不会操作真实账号或业务控件。

import json
import sys
from http.server import BaseHTTPRequestHandler, HTTPServer
from threading import Event, Thread
from urllib.request import urlopen

paths = ["open", "csp-block", "xfo-block", "csp-allow", "meta", "frame-src"]
requests = []


class Child(BaseHTTPRequestHandler):
 def log_message(self, *args):
 pass

 def do_GET(self):
 name = self.path.lstrip("/")
 assert name in paths
 requests.append(name)
 meta = ('<meta http-equiv="Content-Security-Policy" content="frame-ancestors \'none\'">'
 if name == "meta" else "")
 body = ("<!doctype html><meta charset=utf-8>" + meta + "<p>Rendered: " + name + "</p>"
 "<script>parent.postMessage({frame:" + json.dumps(name) + "}," + json.dumps(app_origin) + ");</script>").encode()
 self.send_response(200)
 self.send_header("Content-Type", "text/html; charset=utf-8")
 self.send_header("Content-Length", str(len(body)))
 self.send_header("Cache-Control", "no-store")
 if name == "csp-block":
 self.send_header("Content-Security-Policy", "frame-ancestors 'none'")
 elif name == "xfo-block":
 self.send_header("X-Frame-Options", "DENY")
 elif name == "csp-allow":
 self.send_header("Content-Security-Policy", "frame-ancestors " + app_origin)
 self.send_header("X-Frame-Options", "DENY")
 elif name == "frame-src":
 self.send_header("Content-Security-Policy", "frame-src 'none'")
 self.end_headers()
 self.wfile.write(body)


class Parent(BaseHTTPRequestHandler):
 def log_message(self, *args):
 pass

 def do_GET(self):
 if self.path == "/events":
 body = json.dumps(requests).encode()
 kind = "application/json"
 else:
 body = ("""<!doctype html><meta charset="utf-8"><title>Frame policy lab</title>
<h1>Which child responses can this parent embed?</h1><pre id="result">Waiting for frame messages...</pre>
<button id="check">Show server requests</button><div id="frames"></div><script>
const child=""" + json.dumps(child_origin) + ";const names=" + json.dumps(paths) + """;
window.received=[];
window.snapshot=async()=>{
 const result={rendered:[...window.received].sort(),serverRequests:await (await fetch('/events')).json()};
 document.getElementById('result').textContent=JSON.stringify(result,null,2);return result;
};
addEventListener('message',event=>{
 if(event.origin===child && names.includes(event.data?.frame)) {
 window.received.push(event.data.frame);
 document.getElementById('result').textContent=JSON.stringify(window.received,null,2);
 }
});
document.getElementById('check').onclick=()=>window.snapshot();
for(const name of names) {
 const frame=document.createElement('iframe');frame.src=child+'/'+name;frame.title=name;
 frame.width=240;frame.height=100;document.getElementById('frames').append(frame);
}
</script>""").encode()
 kind = "text/html; charset=utf-8"
 self.send_response(200)
 self.send_header("Content-Type", kind)
 self.send_header("Content-Length", str(len(body)))
 self.end_headers()
 self.wfile.write(body)


child = HTTPServer(("127.0.0.1", 0), Child)
app = HTTPServer(("127.0.0.1", 0), Parent)
child_origin = f"http://127.0.0.1:{child.server_port}"
app_origin = f"http://127.0.0.1:{app.server_port}"
threads = [Thread(target=server.serve_forever, daemon=True) for server in (child, app)]
for thread in threads:
 thread.start()
try:
 for name in paths:
 with urlopen(child_origin + "/" + name, timeout=5) as response:
 assert response.status == 200
 if name == "csp-allow":
 assert response.headers["Content-Security-Policy"] == "frame-ancestors " + app_origin
 assert response.headers["X-Frame-Options"] == "DENY"
 response.read()
 requests.clear()
 print(json.dumps({"app_url": app_origin, "child_origin": child_origin,
 "wire_responses": 6}), flush=True)
 if "--serve" in sys.argv:
 Event().wait()
except KeyboardInterrupt:
 pass
finally:
 for server in (child, app):
 server.shutdown()
 server.server_close()
 for thread in threads:
 thread.join(timeout=5)

开放子页面应正常渲染；csp-block 被禁止祖先嵌入策略拒绝，xfo-block 被 DENY 拒绝。csp-allow 虽然同时发送 DENY，但强制祖先策略明确允许当前父来源，因此正常渲染。meta 页面也会渲染，因为该交付方式不能执行嵌入祖先指令；frame-src 页面同样渲染，因为它限制的是子页面接下来自己加载的框架，而不是正在验证的父子嵌入关系。

预期结果是四条成功渲染消息与六条服务端请求记录。点击页面中的查看服务端请求按钮，可以同时核对两者；浏览器检查还记录了两个被拒框架对应的响应阻止错误。单独运行 Python 探针时，六份响应都会返回二百状态，说明只读响应头不能替代渲染验证。本例只验证一个浏览器中的单层嵌入，没有验证真实账号操作或全部嵌套集成。发布前还应让合法路径与被拒父来源经过实际代理和内容分发层，确认目标子响应仍然保有预期策略。

文章的单层浏览器实验中，六份子响应均为 HTTP 200，但只有 open、csp-allow、meta 与 frame-src 渲染。csp-allow 的强制祖先策略允许父来源，并优先于 X-Frame-Options DENY。实际嵌套集成仍需单独验收。

来源

MDN CSP frame-ancestors，允许的嵌入父级、祖先检查及不支持的 meta 交付方式，已核验 2026-09-13。
MDN CSP frame-src，控制当前文档自己加载的框架，已核验 2026-09-13。
MDN X-Frame-Options，禁止嵌入与同源嵌入限制，已核验 2026-09-13。
W3C CSP Level 3，嵌入祖先策略的执行及其与 X-Frame-Options 的关系，已核验 2026-09-13。

SSRF 让服务器替你去开门

Sun, 05 Sep 2027 00:00:00 +0000

服务端请求伪造会让服务器发出由攻击者选择或影响的请求。缩略图服务、导入器、Webhook 测试器或文档渲染器，可能到达请求用户无法直接访问的目标。服务器贡献的是自己的网络位置，以及这条具体抓取路径实际附带的凭据；取一个地址并不意味着进程可见的所有账号凭据都会自动加入请求。评估风险应从真实连接与认证方式开始。

先看清委托了什么权限

内部服务、回环管理端点和云元数据服务，在可达时都是重要目标。后果取决于认证、响应是否可见、允许的方法和网络策略。盲 SSRF 即使不返回目标正文，也可能触发动作或暴露时间信息。不能只凭功能名称给严重程度排位，而应确认它能联系什么，以及一次联系可以产生什么结果，尤其注意有副作用的内部接口。

在 EC2 上，实例附加了角色且相关访问被允许时，角色凭据可能通过元数据提供。角色名称列表与具体角色的凭据文档是不同请求。这些临时凭据代表该角色获得的权限，并不等于无限 AWS 访问，也不保证是实例上每个应用实际采用的凭据。目标没有角色、端点不可达或权限不足时，风险形态会不同，需要依照部署事实判断。

IMDSv2 要求先用 PUT 获取令牌，再在后续元数据请求中提供令牌。强制使用它可以挡住简单、没有认证头的单次 GET 路径，但不能解决能够控制必要方法和请求头的任意 SSRF。应结合最小权限角色与有效网络限制。元数据还可能通过 IPv4，以及启用并受支持时的 IPv6 到达；检查时不能只处理一种地址族。

解析、解析域名，并保留已检查的目标

允许列表应描述功能真正需要的目标。如果可以，接收资源标识而不是任意 URL。否则，应使用与 HTTP 客户端解释一致的解析器，限制协议、主机和端口。不需要的 userinfo 和歧义语法应拒绝，不能因为字符串某处出现了允许的域名，就认定目的地已经获准。解析函数有返回值，也不等于输入符合业务策略。

例如，位于 @ 前面的 trusted.example 是用户信息，不证明目标主机可信。旧式数字 IPv4 写法在不同解析器和解析库中可能有不同解释。IPv6 回环是 ::1，并不是 127.0.0.1，所以搜索一个固定字符串远远不够。一个运行时的解析结果，也不能直接成为另一个客户端行为的可移植保证。验证应围绕实际使用的组件版本建立。

解析允许的域名后，要按照预期网络策略检查返回的全部地址。只允许公网抓取时，应拒绝回环、私有、链路本地、多播以及其他禁止范围。地址库和登记规则会演进，因此要测试真正部署的版本。全球可路由也不代表目标是获准的、可信的或无害的服务；地址分类与业务允许列表解决的是不同问题，应同时保留。

坏掉的样子

先检查 DNS，再让客户端自行重新解析，会留下检查与使用之间的空隙。应通过受支持的传输机制固定经过验证的连接地址，同时保留原本的 TLS 主机名、证书校验和 HTTP authority。代理可能独立解析；因此须检查真实出口路径、重试与回退连接，不能假设一次本地预检控制了它们。固定地址也不能以关闭证书验证为代价。

重定向引入新目标。没有需要就关闭；需要时则在跟随每一跳之前重新执行验证，包括解析与地址选择。已经允许的域名不能为任意 Location 背书。出口策略是独立的限制层，应与工作负载需要的服务相符，并覆盖相关地址族。入口允许列表、解析检查和网络隔离相互补充，不能把其中一个配置项当成万能保证。

返回二百并不单独证明 SSRF，返回四百类错误也不能证明禁止的请求没有发生。应用可能包装错误、返回缓存，或者先联系目标再拒绝。应通过可控观察端点确认实际请求，区分响应处理和网络行为。不要为了让示例显得可信，就探测真实元数据凭据；安全测试应该使用合成响应，并明确获得对测试目标的授权。

批准数据不证明实际传输。策略须对应真实抓取路径，包括解析、重定向、重试、代理与 TLS 身份。

快速验证

保存为 ssrf_policy.py，执行 python3 ssrf_policy.py。这个刻意收窄的离线策略用传入的地址快照代替 DNS。公网地址只是输入值，程序不会联系它。所有决定都发生在内存中，不使用凭据、不创建套接字、不访问元数据，也不更改网络控制。这样可以验证拒绝规则，而不把真实服务暴露给实验请求。

import ipaddress
from urllib.parse import urlsplit

ALLOWED = {'cdn.example.test'}


def approve(url, addresses):
 # Deliberately narrow input language for this offline model.
 if any(ord(c) <= 32 or ord(c) >= 127 for c in url) or '\\' in url:
 raise ValueError('unsupported URL characters')
 parts = urlsplit(url)
 if parts.scheme != 'https' or parts.hostname not in ALLOWED:
 raise ValueError('scheme or host denied')
 if parts.username is not None or parts.password is not None or parts.fragment:
 raise ValueError('userinfo or fragment denied')
 if parts.port not in (None, 443):
 raise ValueError('port denied')
 if not addresses:
 raise ValueError('empty resolution')
 checked = []
 for text in addresses:
 address = ipaddress.ip_address(text)
 if '%' in text or address.is_multicast or not address.is_global:
 raise ValueError('non-public address denied')
 checked.append(str(address))
 return parts.hostname, tuple(checked)


def rejected(label, url, addresses):
 try:
 approve(url, addresses)
 except ValueError:
 print('rejected:', label)
 return
 raise RuntimeError('unexpected acceptance: ' + label)


url = 'https://cdn.example.test/logo.png'
# Address values only. There is no DNS lookup, socket, or HTTP request.
public_snapshot = ['8.8.8.8']
name, pinned = approve(url, public_snapshot)
rejected('userinfo on allowed host', 'https://attacker@cdn.example.test/logo.png', public_snapshot)
rejected('userinfo host confusion', 'https://cdn.example.test@169.254.169.254/', public_snapshot)
rejected('decimal host', 'https://2130706433/', ['127.0.0.1'])
rejected('loopback IPv6', 'https://[::1]/', ['::1'])
rejected('link-local answer', url, ['169.254.169.254'])
rejected('mixed answers', url, ['8.8.8.8', '127.0.0.1'])
rejected('multicast answer', url, ['224.0.0.1'])
rejected('redirect destination', 'https://internal.example.test/', ['10.0.0.1'])
rejected('changed DNS answer', url, ['127.0.0.1'])
if pinned != ('8.8.8.8',) or name != 'cdn.example.test':
 raise RuntimeError('approved snapshot changed')
print('PASS: public fixture accepted; nine denied cases; approved address snapshot retained')

预期打印九条拒绝结果和 PASS。允许的合成域名加一个公网地址建立成功路径。允许主机上的用户信息、用户信息造成的主机混淆、允许列表外的数字与 IPv6 主机、链路本地和混合答案、多播、重定向主机，以及改变后的 DNS 答案都会失败。此前批准的地址元组保持不变。数字与 IPv6 URL 先被主机允许列表拒绝，因此这两项并未独立测试 IPv6 地址分类分支。本轮源码复核没有执行示例。

这里测试的是决策与数据保存，不是生产抓取实现。它没有执行 DNS、传输层固定、代理、TLS、真实重定向或响应大小限制，因此通过测试不能证明某个 HTTP 库确实连接了批准地址。集成测试仍须验证这些连接关系，并覆盖超时和资源上限，使用隔离目的地和合成响应，避免把局部规则通过误写成整条网络路径已得到证明。

来源

OWASP: SSRF Prevention Cheat Sheet，预期目标、地址验证与重定向，已核验 2026-10-15。
AWS: Instance Metadata Service，IMDSv2 令牌请求与端点行为，已核验 2026-10-15。
RFC 3986: URI Generic Syntax，authority、userinfo 与主机语法，已核验 2026-10-15。
Python: ipaddress，地址分类与版本变化，已核验 2026-10-15。

CSRF 检查请求到底来自哪里

Sat, 04 Sep 2027 00:00:00 +0000

浏览器可能为攻击者触发的请求附带会话 Cookie。CSRF 防御检查请求上下文是否可信，却不能证明用户真的看过或有意批准某个动作。

本图描述文章的服务端夹具，不是浏览器实测。SameSite 只减少 Cookie 发送；可信上下文不证明用户意图，XSS 与认证仍需独立防护。

浏览器判别是否带上 Cookie,依据的是目标域名、路径、Secure、SameSite 及其他浏览器规则,而不是「这次请求是由用户先前的什么意图触发的」。于是,来自攻击者网站的页面,也能驱动受害者的浏览器发出一条改变状态的请求——改密、改资料——并且这条请求会带上已登录的会话 Cookie。服务器看到这样一条请求,会以为它来自合法用户。这正是关键:请求带了凭据,并不能证明这是用户的本意;浏览器只是在执行它的 Cookie 规则,而不是用户的意志。

令牌把动作与来源绑定

对策是让「改变状态的动作」带一个攻击者无法预料的参数。服务端为每个会话生成一个不可预测的反 CSRF 令牌,在它自己的表单里带上,提交时再比对;攻击者的跨站页面既没有这个令牌,校验就会失败。配合严格的方法约束——不要让 GET 去改变状态——让「带令牌」成为改变状态的唯一途径。比对必须严格:缺失或不匹配就拒绝,而且绝不接受攻击者自带的 origin。

SameSite 是浏览器护栏

SameSite=Strict 不在跨站请求中发送该 Cookie；显式设置 Lax 时，使用安全方法的顶层导航仍可携带它。这些限制减少凭据被跨站运送的机会，但本设计仍要求服务端校验令牌。同站范围大于同源，浏览器支持和请求上下文也会影响结果。示例采用服务端保存的同步令牌，而非双提交 Cookie；两种模式不能仅因为都叫令牌，就混为同一种实现。源内脚本注入可以替用户发出合法上下文中的请求，所以还需单独防御 XSS。

把 Origin 当作来源信号

请求存在 Origin 时先检查它；缺失时，服务端可以检查 Referer 的来源部分。两个字段都可能缺失，Origin 也可能是字面值 null，不能把这些情况当作同源证据。本夹具有意同时要求有效令牌和可信来源信号，缺一即拒绝；实际兼容策略也应明确写出，不能默默跳过整个保护。应比较完整的协议、主机与端口，不能只匹配域名前缀，防止相似域名通过。

Sec-Fetch-Site 提供额外浏览器上下文，但表示站点关系，不等于完整来源匹配。命令行客户端可以伪造这些首部，来源检查针对的是浏览器被诱发的请求，不是用户认证或人类意图证明。反过来说，curl 能伪造首部，也不意味着攻击页面能够让受害者浏览器任意发送它们。不同威胁模型应分别理解，不能据此撤销浏览器侧防护。

坏掉的样子

第一种是把状态变更放在获取方法后面。图片与链接就能触发,宽松的站点隔离仍会在顶层获取导航里带上会话,伪造的跳转带着真实凭据到达,服务端却误以为是用户本意。排查时只看是否登录成功没有意义,还要看这条改变状态的请求能不能被一行标签触发。

第二种是显式跨站 Cookie 没有配套保护。SameSite=None; Secure 允许跨站传送，改变状态的接口仍需其他 CSRF 防御。现代浏览器会拒绝缺少 Secure 的 None Cookie，不能把它描述为普遍放行；旧版行为也不能用作安全保证。开发环境为了联调开放跨站传送，上线后忘记核对令牌和来源规则，仍可能留下真实攻击路径。

第三种是缺失令牌时跳过校验。处理器仅在参数存在时比对,接口路径干脆跳过校验,或者把令牌放在查询串里,经引用头与日志到处扩散,攻击者拿到就能重放。源内脚本注入也可能窃取或使用令牌，这是另一个必须防御的边界。正确做法是缺失与不匹配一律拒绝,且只接受请求体或专用首部里的值。

第四种是子域信任过大。站点隔离比的是站点而非来源,受控子域与主站可能同站；若它能设置父域 Cookie，就可能干扰会话处理或为天真的双提交方案种下已知令牌。优先使用主机范围的会话 Cookie，并拒绝含义不明的重复 Cookie。登录接口若不做同样的双校验,还会留下登录伪造,攻击者用自己的账号让受害者登录,后续操作全部记在攻击者账下。每种失败里凭据都是有效的,凭据都不足以独立说明请求合法。

快速验证

把下面程序存为 csrf_probe.py,运行 python3 csrf_probe.py。它只用标准库模拟服务端关卡:方法必须是大写的 POST,令牌必须与会话值一致,来源信号必须吻合。不起网络服务,不碰浏览器,各组用例可独立执行。固定令牌只是测试数据，真实服务必须为会话生成不可预测的值。

from hmac import compare_digest
from urllib.parse import urlsplit
import sys

EXPECTED_ORIGIN = "https://bank.example"
SESSION_TOKEN = "token-issued-with-own-form"

def decide(method, origin, referer, token):
 """模拟服务端关卡：仅 POST 变更、令牌与来源信号必须同时通过。"""
 if method != "POST":
 return 405, "state change requires POST"
 if not isinstance(token, str) or not token.isascii() or not compare_digest(token, SESSION_TOKEN):
 return 403, "missing or wrong token"
 if origin:
 if origin != EXPECTED_ORIGIN:
 return 403, "origin mismatch"
 elif referer:
 base = urlsplit(EXPECTED_ORIGIN)
 try:
 seen = urlsplit(referer)
 except ValueError:
 return 403, "referer mismatch"
 if seen.scheme != base.scheme or seen.netloc != base.netloc:
 return 403, "referer mismatch"
 else:
 return 403, "no origin signal"
 return 200, "transfer accepted"

def check(actual, expected, label):
 assert actual == expected, f"{label}: got {actual}, want {expected}"
 print(f"{label}: {actual[0]} {actual[1]}")

check(decide("POST", EXPECTED_ORIGIN, "", SESSION_TOKEN),
 (200, "transfer accepted"), "legitimate form post")
check(decide("POST", "https://evil.example", "", SESSION_TOKEN),
 (403, "origin mismatch"), "forged cross-site post")
check(decide("POST", EXPECTED_ORIGIN, "", ""),
 (403, "missing or wrong token"), "missing token")
check(decide("POST", "", "https://bank.example/transfer", SESSION_TOKEN),
 (200, "transfer accepted"), "referer fallback navigation")
check(decide("GET", EXPECTED_ORIGIN, "", SESSION_TOKEN),
 (405, "state change requires POST"), "state change over GET")

check(decide("POST", "", "", SESSION_TOKEN),
 (403, "no origin signal"), "missing origin signal")
check(decide("POST", "https://evil.bank.example", "", SESSION_TOKEN),
 (403, "origin mismatch"), "same-site subdomain")
check(decide("POST", EXPECTED_ORIGIN, "", "令牌"),
 (403, "missing or wrong token"), "non-ASCII token")
check(decide("POST", "", "https://[", SESSION_TOKEN),
 (403, "referer mismatch"), "malformed referer")

print("PASS: legitimate, forged, and missing-token cases behave differently")
print(sys.version)

合法的同源提交带对令牌返回成功,伪造来源即使令牌正确也返回禁止,缺失令牌即使来源正确同样拒绝。回退到引用头的同源请求正常放行,获取方法改状态返回方法不允许,正好说明安全方法为何重要。预期输出以成功标记结尾并打印解释器版本,全部断言通过才算成功,任一组失败都会直接抛出异常中断。

补充用例还拒绝缺失来源、同站子域、非 ASCII 令牌与格式错误的引用地址。这个夹具只验决策逻辑，不验浏览器是否真的按站点隔离丢弃凭据，也不验传输加密与会话过期。其字面比较刻意没有实现 URL 规范化，因此显式写出等价默认端口也可能被拒绝。上线前应在隔离环境里使用虚构账号和真实浏览器，测试实际路由的跨站与同站行为，检查请求头、拒绝结果及业务副作用。

来源

MDN：跨站请求伪造（CSRF），攻击形态、令牌与 SameSite 防御，已核验 2026-10-19。
OWASP：跨站请求伪造防护速查表，关于令牌与 SameSite 的指引，已核验 2026-10-19。
RFC 6265：HTTP 状态管理机制，基础 Cookie 作用域；此 RFC 不定义 SameSite，已核验 2026-10-19。

显式启用 gzip，再验证协商与解码后的字节

Sun, 29 Aug 2027 00:00:00 +0000

gzip 是响应内容编码：nginx 可以发送压缩表示，由接受该编码的客户端解码。启用它需要 gzip on；gzip_types 扩展有资格压缩的 MIME 类型，却不会单独激活压缩。最终结果取决于响应、请求方能力和实际生效配置。只有压缩后仍能正确还原目标内容，较小正文才有价值，不能把“传输字节变少”与“功能已经正确”直接画等号。

坏掉的样子

在 gzip off 下列出 MIME 类型，不会让响应变成 gzip。另一个常见遗漏是 gzip_vary on。nginx 并不会仅因为发生压缩，就无条件添加 Vary: Accept-Encoding；该行为受对应指令控制。共享缓存需要知道哪些请求头维度影响表示选择，否则不同解码能力的客户端可能拿到不合适的已存响应。压缩成功和缓存选择正确是两个需要分别检查的结果。

最小长度设置的契约比名称暗示的更窄。gzip_min_length 根据响应 Content-Length 字段确定长度，不一定知道未指定长度响应的最终大小。因此，一个很短的动态流式响应仍可能被压缩，而同样短的静态文件会因为已知长度低于阈值而跳过压缩。不能从阈值配置推断所有小响应都不会进入压缩路径。

测量方法也可能误导。解压后输出文件的大小，不是压缩传输正文大小；压缩正文字节也不包含全部 HTTP 分帧、响应头和 TLS 流量。.gz 等文件扩展名本身不能证明实际编码。解释任何表面上的带宽节省之前，都应检查真实 Content-Encoding，并解码核对字节，否则可能只是把两种不同计量对象放在一起比较。

解码后应还原同一份字节。依据原文与明确限制静态绘制；未为本图重跑原文夹具。

快速验证

下文集成实验的结果保留自历史运行记录；本次修订没有重新执行该实验，不能将这些记录当成本次环境的新实测。

将脚本保存为 check-gzip.py，准备 Python、Docker 和固定镜像后运行。记录环境为 Linux arm64 上的 nginx 1.28.0，以及一个小型 Python 后端。nginx 显式开启三级 gzip，在内置 HTML 资格之外允许 JSON，设置 1,024 字节下限，并显式启用 Vary。服务只发布到宿主回环，实验完成后清理自己的资源：

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True)
 target.write_bytes(content if isinstance(content,bytes) else content.encode())
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 request.port=port
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'
import gzip,hashlib
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def log_message(self,*args):pass
 def do_GET(self):
 self.send_response(200);self.send_header('Content-Type','application/json')
 self.send_header('Connection','close');self.end_headers();self.wfile.write(b'{"ok":true}\n');self.close_connection=True
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
payload=json.dumps({'message':'compressible nginx response '*1000}).encode()
locations='''
location = /disabled.json { gzip off; gzip_types application/json; }
location = /novary.json { gzip_vary off; }
location = /stream { proxy_pass http://backend:8081; }
'''
extra='''
types { application/json json; text/html html; application/octet-stream bin; }
gzip on; gzip_types application/json; gzip_vary on; gzip_min_length 1024; gzip_comp_level 3;
'''
files={name:payload for name in ['large.json','other.bin','page.html','disabled.json','novary.json']};files['tiny.json']=b'{"ok":true}\n'
with lab(config(locations,extra),files,backend) as (_,request):
 results={}
 for encoding in ['gzip','identity','gzip;q=0','br']:
 status,h,b=request('/large.json',headers={'Accept-Encoding':encoding});assert status==200
 if encoding=='gzip':assert h['content-encoding']=='gzip' and gzip.decompress(b)==payload and len(b)<len(payload)
 else:assert 'content-encoding' not in h and b==payload
 assert h['vary']=='Accept-Encoding'
 results[encoding]={'encoding':h.get('content-encoding','identity'),'body_bytes':len(b)}
 for path,encoded in [('/tiny.json',False),('/other.bin',False),('/page.html',True),('/disabled.json',False),('/novary.json',True),('/stream',True)]:
 status,h,b=request(path,headers={'Accept-Encoding':'gzip'});assert status==200
 assert (h.get('content-encoding')=='gzip')==encoded,(path,h)
 decoded=gzip.decompress(b) if encoded else b
 assert decoded==(files['tiny.json'] if path=='/stream' else files[path[1:]])
 if path=='/novary.json':assert 'vary' not in h
 results[path]={'encoding':h.get('content-encoding','identity'),'body_bytes':len(b),'vary':h.get('vary')}
 results['decoded_sha256']=hashlib.sha256(payload).hexdigest()
 print(json.dumps(results,sort_keys=True))

大型合成 JSON 表示共有 28,015 字节。请求携带 Accept-Encoding: gzip 时，记录到的响应传输正文为 246 字节，Python gzip 解码器能逐字节还原原内容。这份负载刻意包含大量重复文本，用于验证压缩确实发生且内容完整；它的压缩比不能当成生产 JSON、JavaScript 或任意文本的收益预测，更不能直接换算成固定页面加速倍数。

接受 identity、设置 gzip;q=0，或只声明 br 的请求，都得到没有 Content-Encoding 的原始字节。质量值为零表示不接受 gzip；声明 Brotli 也不会在此 nginx 配置中自动安装 Brotli 压缩器，而该请求仍允许 identity。对于具备压缩资格的大响应，包括未压缩变体在内，都能看到 Vary: Accept-Encoding，使选择维度得到明确表达。

同一份合成数据按不具压缩资格的二进制类型提供时保持原样；按 HTML 类型提供时，即使没有在 gzip_types 列出 HTML，仍具备压缩资格。另一个 location 显式设置 gzip off，尽管列出了 JSON，也不会压缩。这些对照把类型资格与总开关区分开来，避免把每次没有 Content-Encoding 都误判为客户端协商失败。

12 字节的静态 JSON 响应因为已知长度低于下限而保持未压缩。后端返回相同的 12 字节，但不提供 Content-Length，而以关闭连接结束响应；nginx 将其压缩为 32 字节。因此，下限并不保证所有微小响应都跳过压缩，这份具体的小负载反而增长了。选择策略时需要考虑长度是否已知，不能只根据最终文件大小反推配置一定如何工作。

最后一个 location 保持 gzip 开启，却关闭 gzip_vary。正文仍以 gzip 到达，但没有 Vary 字段。这个对照让缺失缓存选择维度的问题可以直接观察，无需先让真实共享缓存错误交付一次内容。实验核对的是响应头策略；部署后的缓存是否按该维度正确选择，还应通过实际缓存路径验证。

用有代表性的响应调整策略

选择实际字节适合压缩的内容类型。已经压缩的媒体或归档通常很难从再次编码中获益，而重复文本可能显著缩小。这里的字节计数实验没有测量 CPU 成本。忙碌服务选择压缩等级前，应比较代表性大小、不同设置、服务器利用率和客户端延迟，不应把合成数据的高压缩率当成通用容量结论。

经过代理时，响应元数据也要保持准确。Content-Encoding 告诉接收方怎样解码表示，Vary 告诉缓存哪些请求字段影响选择。如果应用已经发送编码响应，应单独审阅那条路径，而不是给未编码字节补一个会误导客户端的头。最终有判定力的验证始终是：协商结果正确、响应头与正文一致，并且实际解码后逐字节匹配目标内容。

来源

nginx gzip module，启用 gzip、MIME 资格、Content-Length 阈值与 Vary，已核验 2026-10-15。
RFC 9110 HTTP Semantics，Accept-Encoding、Content-Encoding 与表示选择，已核验 2026-10-15。

请求限流保护的是 key 所命名的预算

Sat, 28 Aug 2027 00:00:00 +0000

请求速率限制作用于 key 表达的身份，不会自动理解人、账户或端点。limit_req_zone 为这些 key 值保存共享状态，limit_req 则在处理请求时应用对应区域。两个 location 使用相同区域和 key，可以消耗同一份预算。因此，选择变量实际上是在定义公平性与执行边界，并不是只给配置找一个方便填写的字符串。

原文描述 nginx 1.28.0、两个 worker 与 rate=1r/m。结果来自历史记录，不是本次实测。所示 limit_req 配置没有突发或延迟实验；实际拒绝与 dry run 放行是不同结果。当前审核为已修订、执行受阻。本次未重跑，也未增加页面或发布验证。

坏掉的样子

客户端可控标识可能把一个表面上的限制变成许多独立额度。如果修改查询参数就能改变 key，不可信客户端就能选择另一份预算。空 key 更直接：nginx 不会统计 key 求值为空的请求。身份变量缺失时，请求可能无声地离开原本计划的限流范围。只测试正常携带身份的访问，会漏掉这条重要边界。

IP key 衡量的是地址，它可能代表 NAT 或中间层后面的很多用户。转发地址头要先经过明确信任策略，才能成为身份输入。相信任意 X-Forwarded-For，会让调用者制造身份；忽略真实可信代理的地址链，又可能把所有用户放进代理自身的一份预算。两种错误都不能靠提高速率解决，因为问题首先在于限制对象选错了。

共享内存的范围也很重要。区域在同一 nginx 实例的 worker 之间共享，不会自动形成跨无关进程或机器的全局计数器。兼容的平滑 reload 可以保留区域状态。如果假定每次重载配置都会重置全部额度，就可能在测试或恢复操作中，把继续出现的拒绝误判为部署坏了。应区分配置换代、进程换代与共享状态生命周期。

快速验证

下文结果是原文报告的历史观察，保留审计只有静态检查，没有运行产物；本次没有重跑夹具，不能把原文报告当作独立核实的运行证据。

将脚本保存为 check-limit-keys.py。需要 Python、可丢弃的本地 Docker 守护进程、构建和运行容器的权限，以及兼容当前平台的固定镜像。Docker 上下文或环境覆盖不能选择远端守护进程，因为请求访问本机回环地址。构建的 --network none 只限制构建步骤联网，不保证镜像解析无需访问仓库。清理操作忽略返回码，只能算尝试，资源是否删除需要另行核对。原始报告使用两个 worker 的 nginx 1.28.0 和可丢弃 HTTP 后端。每分钟一个请求时，相关观察必须在额度恢复之前完成；这是经过时间记账，不是固定分钟窗口。不同公开测试 key 隔离案例：

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None,extra_ports=()):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True)
 target.write_bytes(content if isinstance(content,bytes) else content.encode())
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 published=[arg for value in (8080,*extra_ports) for arg in ('-p','127.0.0.1::'+str(value))]
 docker('run','-d','--name',containers[0],'--network',name,*published,tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 request.port=port;request.network=name
 request.ports={int(key.split('/')[0]):int(value[0]['HostPort']) for key,value in details['NetworkSettings']['Ports'].items() if value}
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
import json
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def log_message(self,*args):pass
 def do_GET(self):
 body=json.dumps({'path':self.path,'method':self.command}).encode()
 self.send_response(200);self.send_header('Content-Length',str(len(body)));self.end_headers();self.wfile.write(body)
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
from concurrent.futures import ThreadPoolExecutor
extra='''
limit_req_zone $arg_client zone=identity:1m rate=1r/m;
limit_req_zone $binary_remote_addr zone=address:1m rate=1r/m;
limit_req_status 429;
add_header X-Limit $limit_req_status always; add_header X-Worker $pid always;
'''
locations='''
location /a { limit_req zone=identity; proxy_pass http://backend:8081; }
location /b { limit_req zone=identity; proxy_pass http://backend:8081; }
location /dry { limit_req zone=identity; limit_req_dry_run on; proxy_pass http://backend:8081; }
location /ip { limit_req zone=address; proxy_pass http://backend:8081; }
location /open { proxy_pass http://backend:8081; }
'''
configuration=config(locations,extra).replace('worker_processes 1;','worker_processes 2;')
with lab(configuration,backend=backend) as (proxy,request):
 results={}
 assert request('/a?client=one')[0]==200 and request('/b?client=one')[0]==429
 assert request('/a?client=two')[0]==200
 results['same_zone_cross_location']=[200,429];results['changed_untrusted_key']=200
 empty=[request('/a') for _ in range(2)];assert all(r[0]==200 for r in empty)
 assert all(r[1].get('x-limit') is None for r in empty)
 results['empty_keys']=[{'status':r[0],'limit':r[1].get('x-limit')} for r in empty]
 first=request('/ip',headers={'X-Forwarded-For':'192.0.2.1'})
 second=request('/ip',headers={'X-Forwarded-For':'192.0.2.2'})
 assert first[0]==200 and second[0]==429;results['forged_forwarding_header']=[200,429]
 first=request('/dry?client=dry');second=request('/dry?client=dry')
 assert first[0]==second[0]==200 and second[1]['x-limit']=='REJECTED_DRY_RUN'
 results['dry_run']={'status':second[0],'limit':second[1]['x-limit']}
 first=request('/a?client=shared');assert first[0]==200;workers={first[1]['x-worker']}
 deadline=time.monotonic()+8
 while time.monotonic()<deadline and len(workers)<2:
 with ThreadPoolExecutor(max_workers=8) as pool:
 replies=list(pool.map(lambda _:request('/b?client=shared'),range(8)))
 assert all(r[0]==429 for r in replies);workers.update(r[1]['x-worker'] for r in replies)
 assert len(workers)==2,workers
 results['shared_budget_worker_ids']=sorted(workers)
 docker('exec',proxy,'nginx','-s','reload')
 wait(lambda:request('/open')[1]['x-worker'] not in workers)
 reply=request('/a?client=shared');assert reply[0]==429 and reply[1]['x-worker'] not in workers
 results['graceful_reload']={'status':reply[0],'worker':reply[1]['x-worker']}
 print(json.dumps(results,sort_keys=True))

/a?client=one 成功，随后 /b?client=one 返回 429，因为两个 location 使用同一区域。把查询身份改为 two，请求又成功。这适合受控演示，却恰好说明未经验证的查询参数不适合作为抵抗滥用的唯一生产身份。系统确实执行了它收到的 key 规则，但规则选择的主体可能不符合业务意图。

两次不带 client 参数的请求都成功，而且没有 X-Limit 决定值，因为空 key 没有被计数。当身份来自可选请求头或认证结果时，这个对照尤其重要：变量非空的正常流量看起来可能正确受限，而缺少变量的请求却绕过了原本的计数。必须显式测试身份缺失，不能仅从正常路径推断所有请求都在预算内。

按 IP 限制的 location 收到两次携带不同伪造 X-Forwarded-For 的请求，第一次成功，第二次返回 429。这里没有安装 real-IP 信任配置，因此地址 key 仍来自套接字对端。这证明在本次设置中，仅发送不同转发头不会改变配置身份；它并没有认证某个原始互联网用户，也不能被解释为任意代理链的客户端地址恢复已经正确。

dry-run location 对原本会拒绝的请求仍返回 200，但决定头是 REJECTED_DRY_RUN。计数依然发生，只是在该处关闭执行拒绝。仅观察成功响应会隐藏这一区别。评估候选策略时，应读取 dry-run 决定变量，而不是只统计客户端可见的拒绝数，否则容易把“正在记录超额但未执行”误当成“没有超额”。

对于新的共享 key，第一次请求成功，后续从两个已观察 worker 进程 ID 返回的请求都得到 429。随后 nginx 用同一区域配置执行平滑 reload，新 worker 仍拒绝该 key，证明预算状态被保留，没有重置。测试先等待新 worker 身份出现，再把结果归因于重载，避免实际仍由旧 worker 处理却声称已验证新进程行为。

一起定义身份、范围和观测方式

先决定预算应属于地址、已认证账户、路由还是它们的组合，并验证输入在限流阶段已经存在且可信。跨 location 共享区域可以有意建立一份服务预算，分开区域则产生不同计数。不要以为 location 名称会自动成为 key 的一部分；如果表达式没有包含那个维度，就不能期待它提供对应隔离。

区域内存需要按 key 基数规划，不能只看到请求量。文档针对二进制地址示例说明：状态在六十四位平台占一百二十八字节，在三十二位平台占六十四字节；这里的位数指平台架构，不是 key 的位数。不能将这组示例大小直接当成任意可变长度身份 key 的精确容量保证。存储耗尽可能淘汰旧状态，如果仍无法分配，则可能拒绝请求。这个实验验证执行语义，没有测量最大 key 容量，也没有把文档中的近似容量当成本机压测结果。

变更之后还要检查有效配置与决定遥测，区分空 key 不计数、dry run 放行、真正拒绝和 reload 保留状态。单实例限制正常工作，并不能证明全局租户配额已经实现；一个请求返回 429，也不能独自说明究竟消耗了哪个预期用户或路由预算。限流效果需要与身份语义一起解释，才有实际约束价值。

来源

nginx request limit module，共享 key 状态、空 key、dry run、内存大小与决定变量，已核验 2026-10-15。
nginx real IP module，从代理信息推导客户端地址时的信任边界，已核验 2026-10-15。
RFC 6585 additional HTTP status codes，429 与受限主体识别，已核验 2026-10-15。
nginx 1.28.0 request-limit source，兼容 reload 过程中共享区域状态的复用，已核验 2026-10-15。

反向代理需要明确的请求头信任边界

Fri, 27 Aug 2027 00:00:00 +0000

反向代理接受客户端连接，再单独请求上游应用。因此，应用套接字看到的对端是代理，较早客户端的信息则可能通过请求头传入。这些头部只有在部署明确谁可以设置、如何验证时才有可信含义。请求经过代理，不会自动让所有转发身份或协议声明变得可靠；需要把网络连接事实与请求携带的文本声明区分开。

坏掉的样子

客户端到达代理前就可以提供 X-Forwarded-For。普通转发可能保留它，$proxy_add_x_forwarded_for 也只是追加当前对端地址，不会移除不可信前缀。如果应用盲信第一个地址，就可能把请求归属到客户端自行选择的值。正确解释取决于真实可信代理链，不能因为字段名包含 Forwarded 就赋予整条列表相同信任。

Host 处理是独立决策。nginx 默认上游 Host 基于代理目标，不会自动采用客户端访问的公共 Host。因此，构造绝对跳转或选择虚拟主机的应用，在代理后可能表现不同。应只转发预期主机上下文，并应用服务自己的可接受主机名策略；复制头部不等于验证其中名字，也不能替代虚拟服务器入口限制。

代理也不保证后端细节完全不暴露。响应头、跳转、正文、诊断信息或其他公开配置，都可能披露源站信息。限制直接访问和控制特定响应字段很有价值，但这不同于声称一条 proxy_pass 就能隐藏全部上游身份，或提供所需的所有传输保护。地址隐藏、访问控制和加密需要分别依据真实部署判断。

直接客户端实验区分套接字观察与客户端文本。替换选定字段不验证所有代理链、Host 值或传输安全。

快速验证

使用宿主 Python、Docker，以及固定 nginx 和 Python 镜像运行脚本。实测为 Linux arm64 上的 nginx 1.28.0、Python 3.11.16、Docker 29.3.1。它创建私有 Docker 网络与真实回显后端，只把代理发布到宿主回环，验证配置并尝试清理自己的资源，不涉及生产端点或凭据。实验中的伪造值使用文档专用地址：

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True);target.write_text(content)
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'

backend=r'''from http.server import BaseHTTPRequestHandler,HTTPServer
import json
class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 body=self.rfile.read(int(self.headers.get('Content-Length','0')))
 document={'path':self.path,'method':self.command,'body':body.decode(),'headers':{key:self.headers.get(key) for key in ['Host','X-Forwarded-For','X-Real-IP','X-Forwarded-Proto','X-Forwarded-Host']}}
 data=json.dumps(document).encode()
 self.send_response(200);self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(data)));self.send_header('X-Backend-Info','fixture-node');self.end_headers();self.wfile.write(data)
 do_POST=do_GET
 def log_message(self,*args):pass
HTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''

locations=r'''
location /default { proxy_pass http://backend:8081; }
location /append { proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_pass http://backend:8081; }
location /edge {
 proxy_set_header Host $host;
 proxy_set_header X-Forwarded-For $remote_addr;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_set_header X-Forwarded-Host $host;
 proxy_hide_header X-Backend-Info;
 proxy_pass http://backend:8081;
}
'''
with lab(config(locations,'server_tokens off;'),backend=backend) as (container,request):
 forged={'Host':'public.example','X-Forwarded-For':'198.51.100.77','X-Forwarded-Proto':'forged-scheme','X-Real-IP':'198.51.100.88'}
 status,headers,body=request('/default',headers=forged);plain=json.loads(body)
 assert status==200 and plain['headers']['Host']=='backend:8081'
 assert plain['headers']['X-Forwarded-For']=='198.51.100.77' and plain['headers']['X-Forwarded-Proto']=='forged-scheme'
 assert headers['x-backend-info']=='fixture-node'
 status,headers,body=request('/append',headers=forged);appended=json.loads(body)['headers']['X-Forwarded-For'].split(', ')
 assert status==200 and len(appended)==2 and appended[0]=='198.51.100.77'
 status,headers,body=request('/edge',headers=forged);edge=json.loads(body)['headers']
 assert status==200 and edge['Host']==edge['X-Forwarded-Host']=='public.example'
 assert edge['X-Forwarded-For']==edge['X-Real-IP']==appended[-1]
 assert edge['X-Forwarded-For'] not in ['198.51.100.77','198.51.100.88'] and edge['X-Forwarded-Proto']=='http'
 assert 'x-backend-info' not in headers and headers['server']=='nginx'
 print('ordinary forwarding preserves forged forwarding headers and defaults Host to the upstream authority')
 print('append retains the untrusted prefix; the direct-client edge configuration replaces it with the actual socket peer and scheme')
 print('explicit response-header suppression removes one backend field, while server_tokens off still exposes the nginx product name')

每个请求都把 Host 设为 public.example，并携带特意伪造的转发值。默认路由向后端发送 Host: backend:8081，同时保留伪造的 X-Forwarded-For 和 X-Forwarded-Proto。这直接证明普通代理转发不是身份清洗步骤，也不会自动保留公共主机名。后端回显让这些差异可见，不需要仅凭配置推理。

追加路由使用 $proxy_add_x_forwarded_for，后端收到两个逗号分隔地址：客户端提供的地址在前，nginx 观察到的套接字对端在后。原本不可信的前缀仍在。追加有用连接上下文，不会让整个结果列表同样可信；在这个直接面对客户端的结构中，盲信最左地址就会破坏预期边界。

入口路由用 $remote_addr 替换 X-Forwarded-For 和 X-Real-IP，用 $scheme 设置转发协议，并显式传入选择的主机上下文。后端收到真实观察到的对端值，不是两个伪造地址之一；本实验有意使用普通 HTTP，所以协议为 http。测试跨请求比较这些值，不假定 Docker 网桥一定分配某个固定地址。

套接字对端可能反映 Docker 网络路径，这不表示能穿过所有 NAT 或更早代理，恢复任意互联网用户地址。如果入口本身位于可信负载均衡器之后，部署需要有意定义如何接受该跳的信息。本例验证的是直接客户端信任边界，不覆盖所有代理链；应用不能把示例中正确的取值规则无条件搬到不同拓扑。

后端还返回 X-Backend-Info: fixture-node。默认路由会暴露它，入口路由通过明确的 proxy_hide_header 删除它。关闭 server_tokens 后，响应仍包含 Server: nginx。这把隐藏一个后端字段，与隐藏代理产品名或证明其他响应内容没有实现细节区分开。一个字段消失，不等于所有信息泄露渠道都消失。

连接网络访问规则与头部解释

后端依赖代理建立的上下文时，应限制哪些调用者可以直接访问它。如果使用 real IP 模块，可信代理地址范围应准确，并确保最终地址解释与应用自身信任设置一致。过宽信任范围可能让非预期调用者提供看似权威的转发信息，因此不能把网络可达与可信来源简单画等号。

明确 TLS 在哪里终止，以及上游连接是否也需要加密和证书验证。nginx 在当前一跳观察到的协议，不会自动描述更早一跳。跳转、安全 Cookie 和生成 URL 如果依赖转发协议或主机名，就应通过实际部署链路测试。只验证内部 HTTP 回显，不能宣布外部 HTTPS 行为也正确。

最后，同时检查应用收到的请求和客户端收到的响应。头部配置、网络隔离和信息披露控制，分别回答不同问题。两侧证据可以让组合行为可审阅，而不是假定代理会默默补上每个缺失保证。明确事实来源，才能让应用正确使用代理提供的上下文。

来源

nginx HTTP proxy module，默认 Host 处理、转发头与响应头隐藏，已核验 2026-10-15。
nginx real IP module，显式信任的地址来源与代理链，已核验 2026-10-15。
nginx core server_tokens and variables，套接字对端地址、请求协议与服务器版本披露，已核验 2026-10-15。

nginx 匹配规范化路径，并可能再次选择 location

Thu, 26 Aug 2027 00:00:00 +0000

nginx location 匹配使用规范化后的 URI 路径，而不是完全未经处理的请求目标文本。百分号编码字符会被解码，相对路径组件会被消解，相邻斜杠也可能按配置合并。之后的处理还能再次改变当前 URI，并触发新的 location 搜索。当请求似乎进入了与原始拼写不同的处理器时，需要同时理解这两类转换，而不是只比较配置中的字面前缀。

坏掉的样子

只根据原始请求文本判断的路径过滤器，可能与 nginx 路由视图不一致。编码斜杠可以变成路径分隔符，点段可以移除前面的组件，后端还可能采用自己的解码规则。因此，安全与路由决策需要在每个边界约定解释方式，不能假定所有组件看到完全相同的路径字符串。否则同一请求可能在检查时属于一个家族，处理时却属于另一个。

只记录 $uri 也可能掩盖实际输入。它表示当前规范化 URI，并可能在请求处理期间改变；$request_uri 则保留完整原始 URI，包括原始查询字符串。两者不能互相完全替代：前者解释当前路由，后者帮助重建客户端实际请求。诊断时应按问题选择字段，而不是把一个名字相近的变量当成全部路径信息。

index 和 try_files 还会引入另一类转换。目录请求可以内部变成索引文件请求，文件查找失败可以内部跳到回退 URI，使不同 location 和参数生效。所以，最初的前缀匹配不一定就是产生最终响应的配置。若只验证入口匹配，而忽略后续内容处理，就可能漏掉访问控制、缓存或响应状态发生变化的位置。

内部重选可改变当前路径与参数，request_uri 保留输入 URI。本次绘图审阅未执行断言。

快速验证

使用宿主 Python、Docker 和固定 nginx 镜像运行脚本。历史文章报告的环境为 Linux arm64 上的 nginx 1.28.0、Docker 29.3.1。它构建并检查临时配置，只发布宿主回环端口，发送客户端未预先规范化的请求目标，最后尝试删除自身镜像、容器和网络。这样可以观察 nginx 收到明确文本之后的处理，而不被浏览器自动整理路径干扰：

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True);target.write_text(content)
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'

locations=r'''
location / { return 200 "$uri|$request_uri|$args"; }
location /protected/ { return 403 "blocked"; }
location /docs/ { try_files $uri $uri/ /fallback?reason=missing; }
location = /docs/index.html { return 200 "$uri|$request_uri|$args"; }
location = /fallback { return 200 "$uri|$request_uri|$args"; }
'''
with lab(config(locations),{'docs/index.html':'stored-index'}) as (container,request):
 cases={
 '/a//b/../c?x=1':'/a/c|/a//b/../c?x=1|x=1',
 '/a%2Fb/%2e%2e/c?x=1':'/a/c|/a%2Fb/%2e%2e/c?x=1|x=1',
 '/Protected/item':'/Protected/item|/Protected/item|',
 '/docs/':'/docs/index.html|/docs/|',
 '/docs/missing?x=1':'/fallback|/docs/missing?x=1|reason=missing'}
 for path,expected in cases.items():
 status,headers,body=request(path);assert status==200 and body.decode()==expected,(path,status,body)
 for path in ['/protected/item','/protected%2Fitem','/a/../protected/item']:assert request(path)[0]==403,path
 assert request('/bad%ZZ')[0]==400
 print('matching uses normalized paths: percent-decoding, dot segments, and merged slashes differ from the original request URI')
 print('index and try_files internal redirects choose another location; request_uri remains original while uri and args can change')

请求 /a//b/../c?x=1 得到当前 URI /a/c，原始请求 URI 仍为 /a//b/../c?x=1，参数仍为 x=1。这在实测默认配置下展示斜杠合并和点段消解。响应同时包含三个字段，能够直接比较含义，不需要从最终页面内容反向猜测路径到底经过哪些转换。

编码请求 /a%2Fb/%2e%2e/c?x=1 到达同样的当前路径 /a/c，但 request_uri 仍保留原始编码拼写。它说明百分号解码参与路由前的规范化。测试没有依赖浏览器地址栏，因为浏览器可能在发送前已经改写路径。只有知道线上真正收到的请求目标，才能正确解释服务器行为。

受保护前缀对 /protected/item、/protected%2Fitem 和 /a/../protected/item 都返回 403，因为规范化后都属于该路径家族。在这个 Linux 环境中，/Protected/item 因大小写不同而进入普通默认处理。无效百分号编码 %ZZ 则得到 HTTP 400，而不是被当成成功通向任意内容的路径。这些是不同边界，不能混成一个通用字符串比较。

实验放置了真实 /srv/docs/index.html。请求 /docs/ 经 index 处理后进入精确的 /docs/index.html location，该块返回诊断标记，而不是存储文件本身的正文。原始 request_uri 仍是 /docs/。这让内部 location 变化变得可见，虽然客户端没有收到跳转状态，也没有自行发起第二次请求。

对于 /docs/missing?x=1，try_files 找不到文件或目录，会内部选择 /fallback?reason=missing。响应报告当前 URI 为 /fallback，原始请求 URI 为 /docs/missing?x=1，当前参数为 reason=missing。本例回退中显式查询替换了早先参数；如果希望保留原参数，需要明确配置，不能认为所有内部跳转都会自动保持它们。

沿完整请求链验证路径契约

修改路由时，测试有代表性的编码形式、重复斜杠、点段、缺失文件和目录请求。如果客户端、代理与应用的规范化方式不同，集成验证应包含真实组件。这个小实验建立的是所选配置下的 nginx 行为，不证明所有上游框架或安全过滤器都以相同方式解释相同字节。跨组件一致性需要另外的实际请求证据。

诊断中有意选择原始和当前 URI 字段，同时认识到查询字符串可能包含敏感信息，只记录运维任务真正需要的内容。内部跳转可能改变最终处理器和日志上下文，所以除了首次匹配，也要验证事件最终记录在哪里。否则日志缺失或字段变化可能被误判成请求没有到达。

回退行为应明确。缺失资源不应意外变成成功的应用页面，从而掩盖部署错误；受保护路径也不应在重写后落入无关回退。语法检查能够发现配置格式问题，带有明确状态、字段和正文断言的请求，才能验证用户最终实际收到的行为。这两种证据需要一起使用。

来源

nginx core location, try_files, and variables，URI 规范化、内部跳转以及原始与当前 URI，已核验 2026-10-15。
How nginx processes a request，index 处理与后续 location 选择，已核验 2026-10-15。
nginx 1.28.0 core implementation，实测版本的 location 搜索与内部跳转行为，已核验 2026-10-15。

404 页面诚实地作答

Sat, 03 Jul 2027 00:00:00 +0000

404 响应有两类读者：软件需要准确的状态码，访客需要一条能继续前进的路径。错误页即使设计精美，也不能用正文弥补错误的 200；状态码正确，也不代表页面可以难以阅读或没有导航。应当同时保证协议和内容诚实，而不是把一个缺失地址误写成成功，或者把正常的缺失当成整个业务故障。

在渲染正文前确定状态

RFC 9110 对 404 的定义是：源站没有找到目标资源的当前表示，或者不愿透露它确实存在。这并不说明缺失是暂时还是永久。如果服务端知道资源很可能已永久删除，可以使用 410；如果地址确实迁移，就把它重定向到对应的新资源。不要把所有未知地址都送往首页，因为这样既掩盖坏链，也会把访客带到与原意无关的地方。

依赖故障和资源缺失不是一回事。数据库连接失败，导致应用无法判断记录是否存在时，应保留对应的服务端错误语义，不能把所有异常统一变成 404。另一方面，权限策略有时会故意用 404 隐藏资源存在性；这种策略要在契约中说明，而不能在错误正文里泄露对象编号、账号归属或权限细节。相同状态码的选择，必须能由业务事实和安全策略解释。

Google 可能把带错误内容的成功响应识别为 soft 404。返回 200 不保证页面被收录，返回 404 也不保证搜索结果立刻消失。工程上可以承诺的是准确状态、明确内容和正确链接，不能把搜索引擎的后续抓取与索引处理说成即时、确定的操作。修复坏链以后，还需要观察实际抓取和访问结果，而不是仅凭模板名称宣布问题消失。

让错误正文独立且安全

页面用一句简短说明、一个真实首页或目录链接帮助读者恢复方向即可。静态站没有必要为了错误页新增搜索表单、第三方组件或数据库查询；本地静态资源和简单模板更容易在故障时继续工作。API 则应返回已经约定的机器可读错误格式，并保留 404，不能返回一份状态为成功的 HTML 让调用方误判。

状态必须先于正文写入。在 Go 中，如果还没有调用 WriteHeader，第一次写正文会隐式选择 200，后面再试图设置 404 就已经太晚。HEAD 应保持与 GET 相同的状态和适用的表示元数据，但不能传输正文。直接打开某个错误模板文件，只证明那个文件能显示，并不证明真实的缺失请求会进入正确处理器。

坏掉的样子

把所有路径重写到首页，会让缺失文章、脚本和样式表都得到假成功；反向代理也可能把源站的 404 改成自己的 200 错误页。另一个常见问题是处理器先输出页面框架，随后才发现文件不存在。排查时应在实际入口请求一个确定不存在的地址，先禁止自动跟随重定向，再对照正常地址的第一份响应，而不是只看浏览器最终显示了什么。

404 还可能进入缓存。标准允许它在合适条件下进行启发式缓存，过长的负缓存寿命会让刚创建或恢复的页面继续显示不存在。应该明确选择缓存策略；no-store 可以阻止新的存储，却不会主动清除之前已经存入缓存的响应。正文不要未经转义回显查询串，日志也不要记录可能携带认证信息的完整地址。按规范化路径统计缺失请求，避免把每一个随机 URL 都变成新的指标标签。

一份响应，两类读者。依据原文与明确限制静态绘制；未为本图重跑原文夹具。

快速验证

把下面程序保存到临时工作目录的 not_found_probe.go，运行 go run not_found_probe.go。它只启动一个回环 HTTP/1.1 服务，不自动跟随跳转，恢复动作仅改变内存标志。/soft-miss 是故意留下的反例，用于证明“正文像错误页”不足以验证状态，不能把该路由当成推荐实现。

package main

import (
 "fmt"
 "io"
 "net/http"
 "net/http/httptest"
 "runtime"
 "strconv"
 "strings"
 "sync/atomic"
 "time"
)

func must(err error) {
 if err != nil {
 panic(err)
 }
}

func check(ok bool, message string) {
 if !ok {
 panic(message)
 }
}

func main() {
 const missing = `<!doctype html><title>Not found</title><h1>Page not found</h1><a href="/">Home</a>`
 var restored atomic.Bool
 server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 status, body, media := 404, missing, "text/html; charset=utf-8"
 switch r.URL.Path {
 case "/":
 status, body = 200, "<!doctype html><title>Home</title><h1>Home</h1>"
 case "/gone":
 status = 410
 case "/moved":
 status = 308
 w.Header().Set("Location", "/")
 case "/offline":
 status, body = 503, "Service temporarily unavailable"
 case "/soft-miss":
 status = 200 // Deliberate bug: the body alone cannot identify success.
 case "/restored":
 if restored.Load() {
 status, body = 200, "Restored resource"
 }
 default:
 if strings.HasPrefix(r.URL.Path, "/api/") {
 media, body = "application/json", `{"error":"not_found"}`
 }
 }
 if r.Method != "GET" && r.Method != "HEAD" {
 status, body = 405, "Method not allowed"
 w.Header().Set("Allow", "GET, HEAD")
 if media == "application/json" {
 body = `{"error":"method_not_allowed"}`
 }
 }
 w.Header().Set("Content-Type", media)
 w.Header().Set("Cache-Control", "no-store")
 w.Header().Set("Content-Length", strconv.Itoa(len(body)))
 w.WriteHeader(status) // Status must be committed before writing the body.
 if r.Method != "HEAD" {
 _, err := io.WriteString(w, body)
 must(err)
 }
 }))
 defer server.Close()
 transport := &http.Transport{}
 defer transport.CloseIdleConnections()
 client := &http.Client{Transport: transport, Timeout: 2 * time.Second,
 CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse },
 }
 probe := func(method, route string, status int, media string) (*http.Response, string) {
 request, err := http.NewRequest(method, server.URL+route, nil)
 must(err)
 response, err := client.Do(request)
 must(err)
 body, readError := io.ReadAll(response.Body)
 closeError := response.Body.Close()
 must(readError)
 must(closeError)
 check(response.StatusCode == status && response.Proto == "HTTP/1.1", "wrong status or protocol")
 check(response.Header.Get("Content-Type") == media, "wrong media type")
 check(response.Header.Get("Cache-Control") == "no-store", "fixture must not reuse negative responses")
 check(!strings.Contains(string(body), "do-not-echo"), "request query leaked into error page")
 fmt.Printf("%s %s: %d, body=%d bytes\n", method, request.URL.Path, status, len(body))
 return response, string(body)
 }
 const html = "text/html; charset=utf-8"
 probe("GET", "/", 200, html)
 get, body := probe("GET", "/missing?hint=do-not-echo", 404, html)
 check(body == missing && strings.Contains(body, `href="/"`), "missing page must offer a real home link")
 head, empty := probe("HEAD", "/missing", 404, html)
 check(empty == "" && head.ContentLength == get.ContentLength, "HEAD must preserve status and length without a body")
 probe("GET", "/assets/missing.css", 404, html)
 _, api := probe("GET", "/api/missing", 404, "application/json")
 check(api == `{"error":"not_found"}`, "API must not receive an HTML success page")
 probe("GET", "/gone", 410, html)
 move, _ := probe("GET", "/moved", 308, html)
 check(move.Header.Get("Location") == "/", "known move must name its target")
 probe("GET", "/offline", 503, html)
 soft, softBody := probe("GET", "/soft-miss", 200, html)
 check(softBody == missing && soft.StatusCode != get.StatusCode, "negative control must expose a soft 404")
 probe("GET", "/restored", 404, html)
 restored.Store(true)
 _, recovered := probe("GET", "/restored", 200, html)
 check(recovered == "Restored resource", "restored resource must no longer return 404")
 rejected, _ := probe("POST", "/missing", 405, html)
 check(rejected.Header.Get("Allow") == "GET, HEAD", "method rejection must describe allowed methods")
 apiRejected, apiError := probe("POST", "/api/missing", 405, "application/json")
 check(apiRejected.Header.Get("Allow") == "GET, HEAD" && apiError == `{"error":"method_not_allowed"}`, "API method errors must retain JSON")
 fmt.Println("PASS: thirteen requests; missing, moved, unavailable, and restored remain distinct")
 fmt.Println(runtime.Version())
}

十三次请求覆盖正常首页、HTML 缺失、API 缺失、丢失的静态文件、已删除资源、已知迁移和暂时不可用。GET 与 HEAD 对缺失资源返回相同状态和声明长度，但 HEAD 没有正文；查询参数标记不会出现在页面中。soft-miss 的正文和真实 404 完全一致，错误的 200 才揭示它的问题。随后同一个恢复地址从 404 变为 200，说明资源重新出现后不应继续返回缺失；POST 则独立返回 405 和 Allow，避免把方法错误混为不存在，API 的方法错误也保持 JSON 格式。

这些断言已在 macOS、Go 1.27.0 下运行通过。实验使用 no-store 声明，并不实现真实浏览器或 CDN 缓存，因此不能据此证明负缓存已经失效，也没有验证搜索引擎索引和线上代理配置。发布前还需要在网站真实服务链路上分别检查中英文正常路径和虚构路径，确认服务器没有因为美化错误页而改变协议语义。

来源

RFC 9110：HTTP 语义，404、410、HEAD 和表示语义，已核验 2026-09-09。
RFC 9111：HTTP 缓存，负响应存储和缓存控制，已核验 2026-09-09。
MDN：404 Not Found，资源缺失和自定义错误页，已核验 2026-09-09。
Google Search：HTTP 与网络错误，soft 404 和索引行为，已核验 2026-09-09。
Go net/http，响应状态提交和重定向控制，已核验 2026-09-09。

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。

Canonical URL 标识首选表示

Sat, 26 Jun 2027 00:00:00 +0000

同一文档可能由多个地址提供：跟踪参数、别名主机或末尾斜杠变化，都可能不改变有意义的内容。canonical 链接用于指出合适重复表示中的首选版本，帮助接收方理解它们的关系，但不会自动重定向 HTTP 请求，也不能强制搜索引擎采用声明的网址。只有目标与周围信号符合真实内容关系，这份声明才有价值；标签存在本身并不等于规范化已经完成。

先确定身份，再写标签

先决定哪个公开网址代表这份文档，再让站内链接和相关 sitemap 条目与这个选择一致。不能机械删除所有查询参数：跟踪参数可能多余，语言、页码或商品选择却可能实质改变表示。如果没有比较含义就把它们全部折叠到一个地址，会把不同文档指向错误的首选页面。规范化应当反映资源关系，而不是只让网址看起来更短。

HTML 中应把带有 rel="canonical" 的 link 元素放入有效 head，并提供清晰目标。对于 PDF 等其他表示，也可以用 HTTP Link 响应头表达这一关系。优先采用完整公开网址，减少 base 地址或部署前缀造成的歧义。生成时应依据站点预期的公开配置，而不是意外把代理内部主机名写进页面。实际发布结果需要再次检查，不能仅查看模板参数。

canonical 链接关系本身不要求目标必须位于同一个源站。跨域声明需要仔细审查内容与控制关系，声明一个值并不能证明拥有目标。对翻译页面，如果同语言的合适规范页面存在，通常应选择该语言目标。语言替代与内容重复是不同关系，把所有中文页面都指向英文首页，会抹掉有意义的文档区别，不能称为准确的去重处理。

坏掉的样子

声明目标可能报错、继续重定向，或者又指向另一个 canonical。模板、插件和响应头各自生成声明，也可能产生相互冲突的值。应检查完整响应，而不是只搜索有没有一个标签。首选目标需要能够使用，声明也要与实际表示一致。多个位置各自维护相同事实时，更应明确权威来源，避免一次修改只更新了其中一处。

普通链接关系不会改变原始地址的可访问性，除非路由另外配置了行为。如果旧路径需要对所有客户端迁移，就应设置合适的 HTTP 重定向，并验证它对方法的影响；如果变体仍有用途，也可以继续成功响应并提供 canonical。不能把元数据提示等同于跳转、访问授权，或者爬虫必须执行的命令。用户与搜索系统可能观察到不同层面的结果。

搜索引擎会综合多种信号，也可能选择另一份规范网址。因此，标签正确不等于收录已经收敛。应区分源站实际提供的声明与搜索服务报告的选择，排查站内链接、sitemap、跳转或语言元数据是否互相矛盾。发生分歧时，不应只是在更多位置重复添加同一个标签，而应先确认它表达的内容关系是否真实且一致。

重复表示汇合，语言保持区分。依据原文与明确限制静态绘制；未为本图重跑原文夹具。

快速验证

保存为 canonical.py 并执行 python3 canonical.py。脚本创建临时回环 HTTP 源站，用 Python HTML 解析器读取实际响应，提供英文文档、跟踪参数变体、中文文档和两个故意不一致的元数据案例。本地网址只是演示身份，并不会提交给搜索引擎，也没有检查任何真实搜索账号或收录记录。

from html.parser import HTMLParser
from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread
import json


class Canonical(HTMLParser):
 def __init__(self):
 super().__init__()
 self.urls = []

 def handle_starttag(self, tag, attrs):
 values = dict(attrs)
 if tag == 'link' and 'canonical' in values.get('rel', '').split():
 self.urls.append(values.get('href'))


class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 origin = f'http://127.0.0.1:{self.server.server_port}'
 chinese = self.path.startswith('/zh/')
 target = '/zh/article' if chinese else '/article'
 if self.path == '/zh/wrong':
 target = '/article'
 link = f'<link rel="canonical" href="{origin}{target}">'
 if self.path == '/conflict':
 link += f'<link rel="canonical" href="{origin}/another">'
 title = '中文文章' if chinese else 'English article'
 data = f'<!doctype html><html lang="{"zh" if chinese else "en"}"><head><meta charset="utf-8"><title>{title}</title>{link}</head><body><h1>{title}</h1></body></html>'.encode()
 self.send_response(200)
 self.send_header('Content-Type', 'text/html; 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()
 text = response.read().decode()
 parsed = Canonical()
 parsed.feed(text)
 return response.status, response.getheader('Location'), text, parsed.urls
 finally:
 connection.close()

 variant = fetch('/article?utm_source=example')
 primary = fetch('/article')
 translated = fetch('/zh/article')
 assert variant[:2] == (200, None) and variant[2] == primary[2]
 assert variant[3] == [origin + '/article']
 assert translated[3] == [origin + '/zh/article']
 wrong = fetch('/zh/wrong')
 conflict = fetch('/conflict')
 assert wrong[3] != [origin + '/zh/article']
 assert len(conflict[3]) == 2
 print(json.dumps({'variant_status': variant[0], 'variant_redirect': variant[1],
 'same_representation': variant[2] == primary[2],
 'english_target': variant[3], 'chinese_target': translated[3],
 'wrong_language_detected': True, 'conflicting_targets': len(conflict[3]),
 'search_engine_selection_tested': False}))
finally:
 server.shutdown()
 thread.join()
 server.server_close()

跟踪参数变体返回二百，没有 Location 响应头；其字节与英文主页面一致，canonical 指向 /article。中文页面则指向 /zh/article。这同时验证了示例里的重复关系，以及两种语言表示之间的区别。仅提供 canonical 不会让这次 HTTP 请求变成跳转，因此客户端取得的仍是所请求地址的成功响应。

错误语言案例把中文响应指向英文目标；冲突案例则输出两个不同的规范目标。两者都仍然返回二百，所以只看状态的检查会漏掉问题。断言通过读取元数据并比较预期语言映射，识别了这两种具体不一致，并没有猜测搜索引擎面对错误声明时必定采用哪一种处理方式。

这里没有爬虫参与，小解析器也不是完整规范化验证器。实验说明服务器提供了什么声明、怎样响应，不代表 Google 选择了哪个 canonical，更不代表排名结果。调整生产身份之前，应把等价内容、公开目标、已有入口和语言关系一起审阅，并保留原地址或有意设置的重定向，避免元数据整理悄悄破坏用户已经保存的链接。

来源

RFC 6596: canonical link relation，首选表示及 canonical 链接关系的范围，已核验 2026-09-13。
Google: consolidate duplicate URLs，规范网址信号、目标一致性与语言处理，已核验 2026-09-13。

Well-known 路径提供的是发现约定

Tue, 22 Jun 2027 00:00:00 +0000

Well-known URI 为软件发现某个源站的信息提供约定位置。保留的 /.well-known/ 前缀，减少了不同协议各自设计路径时发生名称冲突的机会；注册后缀则指向定义它的具体规范。这个前缀是一种命名机制，不是自动实现，更不是内容可信的保证。服务器仍需正确路由所支持的端点，客户端也必须按照该端点自己的契约解释响应。

按具体后缀的规范实现

RFC 8615 为支持的 URI 方案保留这一命名空间，不要求每个网站发布所有已注册资源，也没有给所有后缀定义统一响应格式。确定媒体类型、认证、跳转处理、缓存或传输条件之前，应查看 IANA 注册及其引用规范。路径看起来熟悉，不能替代协议规则；不同自动化客户端也不会因为共用前缀，就自然采用相同的读取和验证方式。

对于通过网站发布漏洞联系信息，RFC 9116 规定 security.txt 位于 /.well-known/security.txt，并要求通过 HTTPS 获取。旧位置 /security.txt 可以重定向到标准位置。文档使用 UTF-8 纯文本和规定字段，包括至少一个 Contact 以及唯一的 Expires 字段。Contact 提供报告渠道，不代表邮箱一定有人值守，更不能证明某份报告已经被接收或处理。

文档中的 Expires 字段用时间戳限制信息的新鲜度，它与 HTTP 响应中的 Expires 头不是同一个东西。传输层返回二百，不会让已经过期的联系信息重新变得有效。地址和政策需要持续维护，并在内容过时之前更新。使用 Canonical、Policy 等可选字段时，也应遵守各自规则，不能把文档里任意一个网址都当成已经验证的可信声明。

坏掉的样子

宽泛的应用回退路由可能对任何未知地址都返回首页或登录页，并统一使用二百状态。浅层健康检查认为路径可达，真正的协议客户端却得不到可用文档。因此要保留准确路由，同时检查媒体类型与内容。意外跳转到另一个源站，还可能改变信任上下文，而不只是移动一个文件。仅检查最终状态成功，可能遗漏这些协议层面的错误。

命名空间本身不会认证内容。HTTPS 校验帮助建立到目标主机的连接，文档验证及协议要求的其他检查，才进一步判断内容是否可用。存在安全联系信息，不等于授权外部人员扫描或攻击服务。部署也不能因为一个标准资源计划公开，就不加区分地暴露整个目录。应围绕实际支持的资源配置路由和权限，而不是把前缀当成自动开放所有内容的规则。

对没有实现的后缀返回四零四，与悄悄生成一份通用成功文档，是不同选择。每个受支持端点都应有维护者和适合其协议的检查。注册表描述的是约定，既不能证明某个源站已经实现，也不能证明当前响应已经验收。协议发现减少的是查找位置的不确定性，并没有取消维护、格式检查与可信性判断这些后续工作。

Well-known 发现约定：机制与证据边界。

快速验证

保存为 well-known.py，使用 Python 3.14 执行 python3 well-known.py。实验仅提供回环 HTTP 服务，联系地址使用明确虚构的 example.invalid。它验证路由及选定文档字段；由于没有使用 HTTPS，不能把它视为完整 RFC 9116 部署或传输安全测试。代码不会发送邮件，也不会连接真实的漏洞接收系统。

验证记录（2026-10-17）：保留的 macOS arm64、Python 3.14.4 记录匹配两份完整代码载荷，报告在断言开启和回环限制下通过。本次源码审阅没有重跑。不得使用 -O 或 PYTHONOPTIMIZE，因为未实现路由的请求写在断言内。守卫记录的是连接尝试，不是抓包统计的请求数，不能混淆二者。

from datetime import datetime, timedelta, timezone
from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread
import json

now = datetime.now(timezone.utc)
future = (now + timedelta(days=30)).isoformat().replace('+00:00', 'Z')
past = (now - timedelta(days=1)).isoformat().replace('+00:00', 'Z')
content = {'text': f'Contact: mailto:security@example.invalid\nExpires: {future}\n'}


class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 status = 200 if self.path == '/.well-known/security.txt' else 301 if self.path == '/security.txt' else 404
 data = content['text'].encode() if status == 200 else b''
 self.send_response(status)
 if status == 301:
 self.send_header('Location', '/.well-known/security.txt')
 self.send_header('Content-Type', 'text/plain; charset=utf-8')
 self.send_header('Cache-Control', 'no-store')
 self.send_header('Content-Length', str(len(data)))
 self.end_headers()
 self.wfile.write(data)

 def log_message(self, *args):
 pass


def check_contact_and_expiry(text):
 fields = dict(line.split(': ', 1) for line in text.splitlines())
 if not fields.get('Contact', '').startswith('mailto:'):
 raise ValueError('missing demonstration contact')
 expires = datetime.fromisoformat(fields['Expires'])
 if expires <= now:
 raise ValueError('expired metadata')


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 {'status': response.status, 'body': response.read().decode(),
 'location': response.getheader('Location'),
 'content_type': response.getheader('Content-Type')}
 finally:
 connection.close()

 valid = fetch('/.well-known/security.txt')
 assert valid['status'] == 200 and valid['content_type'] == 'text/plain; charset=utf-8'
 check_contact_and_expiry(valid['body'])
 legacy = fetch('/security.txt')
 assert legacy['status'] == 301 and legacy['location'] == '/.well-known/security.txt'
 assert fetch('/.well-known/unimplemented')['status'] == 404
 rejected = []
 for text in (content['text'].replace(future, past), f'Expires: {future}\n'):
 content['text'] = text
 response = fetch('/.well-known/security.txt')
 assert response['status'] == 200
 try:
 check_contact_and_expiry(response['body'])
 except ValueError as error:
 rejected.append(str(error))
 assert rejected == ['expired metadata', 'missing demonstration contact']
 print(json.dumps({'valid_status': valid['status'], 'legacy_status': legacy['status'],
 'unimplemented_status': 404, 'rejected_200_documents': rejected,
 'https_transport_tested': False}))
finally:
 server.shutdown()
 thread.join()
 server.server_close()

标准路径第一次返回二百、预期纯文本类型、联系字段，以及三十天后的到期时间。旧路径返回三零一，指向标准位置；未实现的后缀返回四零四。随后脚本在同一成功路由上提供两份无效文档：一份已经过期，另一份缺少联系字段。它们的 HTTP 状态仍然是二百，却都被字段检查拒绝。这说明地址可达与元数据可用必须分别验证。

解析器只处理演示格式：字典会合并重复字段，并且只接受 mailto 联系方式；它比较的是启动时刻，而不是每次刷新的观察时间。它没有完整实现重复字段、签名、Canonical 地址、跳转或 URI 语法。因此这些只是明确受限的字段测试，不等于整份文档符合 RFC，也没有验证联系渠道真实可用。发布真实端点前，仍需分别验证实际传输、内容与新鲜度。

来源

RFC 8615: Well-Known URIs，保留命名空间与注册模型，已核验 2026-09-13。
RFC 9116: security.txt，规定路径、HTTPS 传输、联系字段与到期规则，已核验 2026-09-13。
IANA: Well-Known URIs registry，已注册后缀及其定义规范，已核验 2026-09-13。
Python assert 语句，优化模式会移除断言及其表达式，已核验 2026-10-18。

字符集告诉阅读者这段字节该如何解码成字符

Fri, 05 Mar 2027 00:00:00 +0000

字符编码规定字节与字符之间的对应关系。在 text/plain; charset=utf-8 中，字符集参数声明了这层关系，但修改参数不会改变正文。可靠的文本交付要求生产者实际使用的编码与消费者采用的解码规则相符，不能只检查配置文件里是否出现了 UTF-8 这个名称。标签、字节和格式规则需要共同成立。

先由格式确定规则

应用通常先把内存中的字符序列编码成字节，再发送响应；接收方则在处理文本之前把字节解码回来。如果响应还经过压缩，需要先解除 gzip 这样的内容编码，再进行字符解码。这是两次不同的转换，不能因为名称里都有“编码”就当成同一层。数据库连接、模板引擎和响应生成器都可能引入不一致，因此最后一个 HTTP 响应头写对了，并不能证明之前的转换过程正确。

HTML 遇到声明冲突时并不是任意猜测，而是有明确的编码探测算法。对于没有用户手动覆盖的普通网络解析，能够识别的字节顺序标记先于受支持的传输层编码声明被考虑，正文里的声明则在后面。因此，页面中的 meta 一般不能覆盖明确且受支持的 HTTP 字符集。应让两处都准确，并把 HTML 编码声明完整放在前一千零二十四个字节之内，而不是依赖冲突优先级去挽救错误输出。

各种文本格式没有一个统一的“缺失字符集时默认如何解码”规则。RFC 8259 要求非封闭生态系统之间交换的 JSON 使用 UTF-8，它的媒体类型注册没有定义 charset 参数，而且网络发送方不得在 JSON 前添加字节顺序标记。不能因为 JSON 和 HTML 都能看成文字，就把 HTML 的探测规则搬到 JSON 上。应先确定内容格式，再执行这个格式规定的编码契约。

坏掉的样子

仅包含 ASCII 的测试很容易掩盖错误，因为这些字符在 UTF-8 和常见旧编码中的字节相同。测试样本应包含重音字符、货币符号，或产品真实支持语言中的代表性文字。一份 Windows-1252 正文如果误标 UTF-8，严格解码可能直接报错；反过来，本实验的 UTF-8 字节被当成 Windows-1252 时却能成功解码，只是字符已经变了。因此，“没有异常”不是文字正确的证据，必须与已知原文比较。

替换式解码会让损坏的数据看起来仍然可读，却可能同时丢掉诊断证据。把替换字符重新编码，通常无法恢复原先那些不合法的字节。同样，先错误解码，再把得到的乱码编码成合法 UTF-8，最终标签和字节语法可能完全一致，原始含义却已经丢失。任何批量修复之前都应保留受保护的原始样本，不要把“统一转成 UTF-8”当作可以无条件覆盖存储数据的理由。

把解码字符与已知原文比较。解码成功仍可能出错；只改标签不是转码。

快速验证

使用 Python 3.11 或更新版本运行以下程序，不需要网络或额外依赖。它用标准头字段解析器提取 charset，然后显式调用 Python 解码器。本实验消费者要求参数存在，并拒绝未知编码名称；这些是它自己的契约，不代表所有 HTTP 文本必须携带该参数，也没有模拟浏览器的完整 HTML 编码探测过程。

from email.message import Message

text = "caf\u00e9 \u20ac"
utf8 = text.encode("utf-8")
legacy = text.encode("windows-1252")


def decode(header, payload):
 message = Message()
 message["Content-Type"] = header
 charset = message.get_content_charset()
 if charset is None:
 raise ValueError("missing charset")
 return payload.decode(charset, errors="strict")


cases = [
 ("utf8", "text/plain; charset=utf-8", utf8),
 ("legacy", "text/plain; charset=windows-1252", legacy),
 ("wrong-label", "text/plain; charset=utf-8", legacy),
 ("mojibake", "text/plain; charset=windows-1252", utf8),
 ("missing", "text/plain", utf8),
 ("unknown", "text/plain; charset=x-not-a-codec", utf8),
]
print("UTF-8 bytes:", utf8.hex(" "))
print("Windows-1252 bytes:", legacy.hex(" "))
outcomes = {}
for name, header, payload in cases:
 try:
 decoded = decode(header, payload)
 except (UnicodeDecodeError, LookupError, ValueError) as error:
 outcome = type(error).__name__
 print(name, outcome)
 else:
 outcome = "same" if decoded == text else "different"
 print(name, outcome, ascii(decoded))
 outcomes[name] = outcome

assert outcomes == {
 "utf8": "same", "legacy": "same", "wrong-label": "UnicodeDecodeError",
 "mojibake": "different", "missing": "ValueError", "unknown": "LookupError",
}
converted = legacy.decode("windows-1252").encode("utf-8")
assert converted == utf8
print("transcoded equals UTF-8:", converted == utf8)
replaced = legacy.decode("utf-8", errors="replace")
assert replaced == "caf\ufffd \ufffd"
print("replacement:", ascii(replaced))
assert b"\x80".decode("latin-1") == "\u0080"
assert b"\x80".decode("windows-1252") == "\u20ac"
print("Python Latin-1:", ascii(b"\x80".decode("latin-1")))

前两种情况都输出 same，说明不同字节序列可以经各自正确的编码规则得到同一段文字。误标的旧编码正文产生 UnicodeDecodeError，反向误标则输出 different，展示了不报错的乱码。缺少参数和未知名称分别产生 ValueError 与 LookupError。输出通过 ascii() 显示字符转义，避免终端字体和编码再次干扰观察。程序还验证了真正的转码：先按原始编码解出字符，再按目标编码生成字节，最终结果才与最初的 UTF-8 字节一致。

替换解码的结果含有两个 U+FFFD，证明确实丢失了原始字符信息。最后两个断言说明，Python 的 Latin-1 把字节 0x80 映射到 U+0080，而 Windows-1252 会得到欧元符号。符合 WHATWG 规则的浏览器却把 iso-8859-1、latin1 等标签当成 Windows-1252。因此不能用 Python 的同名 codec 输出，直接推导浏览器会怎样解释该标签；浏览器标签映射的依据是标准，前面的本地实验只证明它自己执行的规则。

生产诊断时，在修改存储之前，先对照原始正文字节、实际响应头、可能存在的字节顺序标记和 HTML 声明，定位第一次错误编码或解码发生在哪里。让一段已知文本通过那个边界，比较转换前后的字符，而不只看页面是否还有方块。如果码点本身正确、只是字形缺失，应单独检查字体覆盖范围。修复生产者后，再用非 ASCII 样本走完整响应路径复测；仅改标签或接受替换输出，都不算已经验证的修复。

来源

WHATWG 编码标准，编码标签、Windows-1252 别名与解码错误模式，已核验 2026-09-07。
HTML 编码探测，字节顺序标记、传输元数据与文档声明的处理顺序，已核验 2026-09-07。
RFC 8259：JSON，UTF-8、字节顺序标记限制与媒体类型注册，已核验 2026-09-07。

CORS 预检取决于请求形态

Fri, 22 Jan 2027 00:00:00 +0000

CORS 预检用于询问浏览器能否发送某种具体形态的跨源请求。它是一条 OPTIONS 请求，携带计划采用的方法及相关请求头名称，浏览器检查服务端答复后才决定是否发送实际请求。这与实际响应到达之后，检查应用脚本能否读取响应，是两个不同阶段。它们都可能失败，但对服务端是否执行过业务操作的影响不同，诊断时必须先确定错误发生在哪个边界。

触发预检的条件并不是简单的“带有凭据”或“会产生副作用”。在其他条件同时满足时，安全列表中的 GET、HEAD 或 POST 可以不预检。PUT、应用自己设置的 Authorization 等请求头通常需要预检，JSON 内容类型也不属于安全列表里的内容类型。因此，即使目标地址和业务操作没变，只改变请求形态，也可能新增一次 OPTIONS 交互。不能把这种变化误认为服务端突然多执行了一次业务请求。

将服务端收到请求的证据，与脚本能否读取响应分开核对。“允许来源”指 Access-Control-Allow-Origin，“凭据许可”指 Access-Control-Allow-Credentials: true。五个案例均使用本地合成响应，不设置 Cookie，也不实现账号认证。

把每项权限放到对应阶段理解

预检携带计划使用的方法，并在需要时携带计划设置的请求头名称。对于下面的 PUT 和 X-Lab 请求，预检响应必须同时允许该方法和自定义请求头。这个阶段成功之后，实际响应仍然要满足自己的 CORS 暴露条件。当获准的前端需要读取错误状态和正文时，错误响应也可能需要恰当的暴露头。后端处理函数可以被普通客户端成功调用，并不足以证明浏览器中的真实前端能够访问它。

凭据模式又增加了独立约束。使用 include 时，响应暴露需要匹配的明确来源，以及值为 true 的允许凭据头；即使本次测试根本没有 Cookie 可发送，允许来源通配符仍然不成立。浏览器对 Cookie 的其他限制也独立存在。允许凭据头不能替代 Cookie 配置、用户认证或来源允许列表，也不应为了回答浏览器的预检元数据查询，就要求预检先携带会话 Cookie。

坏掉的样子

应用路由可能允许 PUT，但预检响应遗漏了 PUT 或所需自定义请求头。浏览器此时只发送 OPTIONS，根本不会派发实际 PUT。重试业务处理器或修改数据库代码，并不能修复这个协议边界。反过来，一个采用凭据模式的简单 GET 可以在没有 OPTIONS 的情况下到达处理器，然后因为服务端返回通配符而无法向脚本暴露响应。仅凭前端的失败提示，无法确定哪一种情况发生了。

预检缓存还会让配置变更难以观察。最大缓存时长控制的是浏览器专门维护的许可缓存，并且受到浏览器自身限制；它不是业务接口正文缓存。判断修改是否生效之前，应查看真实请求交互及缓存影响。如果响应会根据请求来源选择不同的允许值，还要设置恰当的缓存变化规则，避免共享缓存把某个来源对应的许可响应直接复用于其他请求。不能靠反复修改接口正文来排查权限缓存。

快速验证

保存代码为 cors-preflight.py，执行 python3 cors-preflight.py --serve，打开打印出的页面地址，结束后按控制键加 C 关闭两个本地服务。两个来源位于不同的本机回环端口，所有响应内容均为合成数据。实验有意在不设置 Cookie、不实现账号认证的条件下检查凭据模式，所以它证明的是浏览器协议规则，而不是一套完整的凭据传输方案。

核验记录，2026 年 10 月 17 日：修订后的回环夹具使用 Python 3.14.4 通过了受监控的启动检查，并在使用全新私有配置的无头 Chrome 156.0.8078.36 中通过了五个顺序浏览器案例。通配符配合 include 时不可读，通配符配合 omit、明确来源配合 include 时可读。被拒绝的 PUT 停在预检阶段，获准的 PUT 到达了服务器。观察到的 204 响应均无 Content-Length。私有 Python opener 只处理启动阶段的 OPTIONS；连接对端检查由额外监控器提供，文章辅助函数不包含这些检查。浏览器正常执行 CORS。这些合成结果不证明真实认证或生产环境行为。针对字节完全相同的 API 处理器，另行进行的原始响应检查确认 204 无响应体，也没有 Content-Length 或 Transfer-Encoding；六类离线畸形响应控制均被拒绝。

import json
import sys
from http.server import BaseHTTPRequestHandler, HTTPServer
from threading import Event, Thread
from urllib.request import HTTPRedirectHandler, ProxyHandler, Request, build_opener

events = []


class NoRedirect(HTTPRedirectHandler):
 def redirect_request(self, *args, **kwargs):
 raise ValueError("This fixture does not follow redirects")


def open_owned_preflight(request):
 endpoint = api.socket.getsockname()
 if (endpoint != ("127.0.0.1", api.server_port)
 or type(endpoint[1]) is not int or not 1024 <= endpoint[1] <= 65535
 or request.full_url not in {f"http://127.0.0.1:{endpoint[1]}/{p}" for p in ("deny", "permit")}
 or request.get_method() != "OPTIONS" or request.data is not None
 or request.has_proxy()):
 raise ValueError("Only this fixture's owned loopback preflights are allowed")
 return direct_opener.open(request, timeout=5)


class API(BaseHTTPRequestHandler):
 def log_message(self, *args):
 pass

 def reply(self, preflight=False):
 events.append({"method": self.command, "path": self.path,
 "requested_method": self.headers.get("Access-Control-Request-Method"),
 "requested_headers": self.headers.get("Access-Control-Request-Headers")})
 body = b"" if preflight else b"readable result"
 self.send_response(204 if preflight else 200)
 if not preflight:
 self.send_header("Content-Length", str(len(body)))
 self.send_header("Access-Control-Allow-Origin", "*" if self.path == "/wildcard" else app_origin)
 self.send_header("Access-Control-Allow-Credentials", "true")
 self.send_header("Vary", "Origin")
 if preflight and self.path == "/permit":
 self.send_header("Access-Control-Allow-Methods", "PUT")
 self.send_header("Access-Control-Allow-Headers", "X-Lab")
 self.send_header("Access-Control-Max-Age", "0")
 self.end_headers()
 self.wfile.write(body)

 def do_OPTIONS(self):
 self.reply(preflight=True)

 def do_GET(self):
 self.reply()

 def do_PUT(self):
 self.rfile.read(int(self.headers.get("Content-Length", "0")))
 self.reply()


class App(BaseHTTPRequestHandler):
 def log_message(self, *args):
 pass

 def do_GET(self):
 if self.path == "/events":
 body = json.dumps(events).encode()
 kind = "application/json"
 else:
 body = ("""<!doctype html><meta charset="utf-8"><title>CORS preflight lab</title>
<h1>Credentials mode and preflight</h1><pre id="result">Running...</pre><script>
const api=""" + json.dumps(api_origin) + """;
async function run() {
 const cases=[
 ['wildcardInclude','/wildcard',{credentials:'include'}],
 ['wildcardOmit','/wildcard',{credentials:'omit'}],
 ['exactInclude','/exact',{credentials:'include'}],
 ['deniedPut','/deny',{method:'PUT',headers:{'X-Lab':'demo'},body:'synthetic'}],
 ['allowedPut','/permit',{method:'PUT',headers:{'X-Lab':'demo'},body:'synthetic'}]
 ];
 const results={};
 for(const [name,path,options] of cases) {
 try {const response=await fetch(api+path,options);results[name]={readable:true,status:response.status,body:await response.text()};}
 catch(error) {results[name]={readable:false,error:error.name};}
 }
 results.serverEvents=await (await fetch('/events')).json();
 window.labResult=results;
 document.getElementById('result').textContent=JSON.stringify(results,null,2);
}
run().catch(error=>{window.labError=String(error);});
</script>""").encode()
 kind = "text/html; charset=utf-8"
 self.send_response(200)
 self.send_header("Content-Type", kind)
 self.send_header("Content-Length", str(len(body)))
 self.send_header("Cache-Control", "no-store")
 self.end_headers()
 self.wfile.write(body)


api = HTTPServer(("127.0.0.1", 0), API)
app = HTTPServer(("127.0.0.1", 0), App)
api_origin = f"http://127.0.0.1:{api.server_port}"
app_origin = f"http://127.0.0.1:{app.server_port}"
# A process-local client for these two owned loopback requests only.
# It changes no system settings or global urllib opener.
direct_opener = build_opener(ProxyHandler({}), NoRedirect())
threads = [Thread(target=server.serve_forever, daemon=True) for server in (api, app)]
for thread in threads:
 thread.start()
try:
 headers = {"Origin": app_origin, "Access-Control-Request-Method": "PUT",
 "Access-Control-Request-Headers": "x-lab"}
 for path in ("deny", "permit"):
 with open_owned_preflight(Request(api_origin + "/" + path, method="OPTIONS", headers=headers)) as response:
 assert response.status == 204
 assert response.headers.get("Content-Length") is None
 assert response.headers.get("Access-Control-Allow-Methods") == ("PUT" if path == "permit" else None)
 assert response.headers.get("Access-Control-Allow-Headers") == ("X-Lab" if path == "permit" else None)
 events.clear()
 print(json.dumps({"app_url": app_origin, "wire_preflight_checks": "PASS",
 "real_authentication_or_cookies": False}), flush=True)
 if "--serve" in sys.argv:
 Event().wait()
except KeyboardInterrupt:
 pass
finally:
 for server in (api, app):
 server.shutdown()
 server.server_close()
 for thread in threads:
 thread.join(timeout=5)

页面依次执行五种 fetch：通配符配合 include 时不可读，相同通配符配合 omit 时可读，明确来源配合 include 时也可读。缺少许可信息的 PUT 无法通过预检，而明确允许方法与 X-Lab 请求头的 PUT 成功。页面同时展示服务端记录的事件，避免只根据脚本成功或失败标志来猜测实际请求有没有执行。每项观察都可以与浏览器网络面板里的具体交互对应起来。

预期服务端记录三个 GET、两个 OPTIONS，以及恰好一个发往 permit 路径的 PUT。两个预检都声明 PUT 方法和小写的 x-lab 请求头，deny 路径则没有收到 PUT。允许响应把预检缓存时长设为零，避免实验依赖之前缓存的许可。不带服务参数的 Python 执行只检查响应头，浏览器执行才验证真正的派发与暴露行为。用于实际前端时，应保留这两类证据，并测试真实采用的方法、内容类型、自定义头、凭据模式和响应路径。

来源

MDN CORS，预检条件与携带凭据模式的请求交互，已核验 2026-09-13。
MDN Access-Control-Allow-Credentials，暴露凭据模式响应所需的条件，已核验 2026-09-13。
WHATWG Fetch Standard，方法、请求头权限检查及预检缓存，已核验 2026-09-13。

Caddy 自动管理 HTTPS 证书的签发与续期

Thu, 21 Jan 2027 00:00:00 +0000

Caddy 可以自动获取并续签受管理的证书，不需要运维人员手工实现 ACME 协议。自动化省去了重复操作，却没有取消签发前提，也不能代替对失败的监控。今天证书有效，不证明下次续期仍能完成，更不证明整条链路中的每一跳都使用同一张证书。应先明确服务名称、验证路径、持久存储和 TLS 终止位置，再判断自动化覆盖到哪里。

先让自动 HTTPS 知道服务名称

当配置让 Caddy 知道符合条件的主机名或地址时，自动 HTTPS 才会按规则启用，同时还要考虑文档列出的例外与显式覆盖。Caddyfile 中的站点地址包含主机名，是常见触发方式。file_server 指令负责提供文件，本身并不等于为某个尚未指定的域名申请公开证书，不能把文件服务功能与证书管理的启用条件混在一起。

命令行区别很明确：不带参数的 caddy file-server 默认监听八十端口；提供 --domain 后，才会尝试为指定主机名启用 HTTPS，并将默认监听端口改为四百四十三。无论命令怎样拼写，都不能单独证明 DNS、端口转发或证书授权已经正确。显式 HTTP 配置、手动加载的证书等条件，也可能改变自动行为，应该检查实际生效配置。

本地开发还有不同的信任边界。对于内部名称，Caddy 可以使用自己的本地证书机构。客户端需要通过适当流程信任该机构；某台机器能够正常访问，不代表这张证书已经获得公网客户端的普遍信任。更不能为了修复客户端信任问题，把私有 CA 的签名密钥发给所有客户端。信任根分发与私钥保管是两项不同工作。

让挑战方式与真实路径匹配

Caddy 默认同时启用 HTTP-01 与 TLS-ALPN-01。前者通过公网八十端口验证，后者通过四百四十三端口上的特殊 TLS 握手验证；Caddy 可以在可用方式之间选择。某次 HTTP 挑战失败，并不说明 DNS 验证就是唯一替代方案。应先从日志确认实际失败的是哪种挑战，再检查该方式的入口、转发和防火墙规则。

代理或 CDN 可能干扰这些路径，但它们的存在不会自动使签发变得不可能。即使普通 HTTPS 在 CDN 终止，HTTP 挑战请求也可能被正确转发。DNS-01 则通过 TXT 记录证明控制权，不要求申请证书的服务器接收入站验证流量，但需要受支持的服务商集成和范围适当的 DNS 凭据。选择方式应依据真实路由和权限，而不是凭拓扑名称猜测。

坏掉的样子

陈旧的 A 或 AAAA 记录、端口阻断、错误转发或 CDN 规则变化，都可能让首次签发成功之后的验证失败。应同时检查两个地址族，并读取日志中的具体挑战错误。反复清空存储再重试，不是有效诊断：这样会丢掉本可复用的证书状态，还可能增加不必要的签发尝试，消耗正常业务需要的配额。

实例替换时应保留 Caddy 的数据存储，并保护其中的敏感密钥材料。多个实例需要符合 Caddy 协调语义的存储安排；几台机器上恰好有同名目录，并不表示它们共享了状态。应验证这套配置如何恢复，同时避免把私钥打印到日志、复制进报告或提交到版本库。自动管理证书并不会免除持久化与访问控制责任。

现有证书仍然可用时，续期自动化就可能已经失败。应监控续期错误，以及客户端实际收到的证书到期时间，为处置留下足够提前量。源站续签成功，不能证明 CDN 对外证书已经更新；CDN 对访客启用 TLS，也不会取消对另一条 HTTPS 源站连接的安全和身份检查。这两个终止位置需要分别验收。

签发实验应使用预发签发者，避免把不受公开信任的测试证书带到生产。DNS 凭据轮换后，也需要受控的验证检查。告警提前量应按响应能力与证书寿命选择，不能把一个固定三十天的算术示例当成 Caddy 的续期调度规范，更不能因脚本输出正常就断言真实证书一定会自动更新。

Caddy 证书生命周期：机制与证据边界。

快速验证

保存为 expiry_alert.py 并运行 python3 expiry_alert.py，须启用断言，不使用 -O 或 PYTHONOPTIMIZE；只需要 Python 标准库。程序使用固定 UTC 观察时刻，三十天阈值是本例运维告警的自主选择，不是 Caddy 内部策略。它不会联系域名或证书机构，不启动监听器，不创建密钥，也不修改系统信任设置，适合单独验证日期边界。

from datetime import datetime, timedelta, timezone

# An operator-chosen alert threshold, not Caddy's renewal scheduler.
ALERT_BEFORE = timedelta(days=30)
NOW = datetime(2026, 10, 15, 12, tzinfo=timezone.utc)


def expiry_alert(not_after, now):
 for value in (not_after, now):
 if value.tzinfo is None or value.utcoffset() is None:
 raise ValueError("timezone-aware timestamps required")
 remaining = not_after - now
 if remaining <= timedelta(0):
 return "expired"
 if remaining <= ALERT_BEFORE:
 return "warning"
 return "ok"


for name, days, expected in [
 ("fresh", 80, "ok"), ("due", 20, "warning"),
 ("boundary", 30, "warning"), ("expired", -1, "expired"),
]:
 not_after = NOW + timedelta(days=days)
 actual = expiry_alert(not_after, NOW)
 assert actual == expected
 print(f"{name}: remaining={days}d alert={actual}")
assert expiry_alert(NOW, NOW) == "expired"
try:
 expiry_alert(NOW.replace(tzinfo=None), NOW)
except ValueError:
 print("naive timestamp rejected")
else:
 raise AssertionError("missing timezone accepted")
print("PASS: expiry alert boundaries; no certificate issuance tested")

四个打印案例依次得到正常、警告、警告和过期。恰好剩余三十天也进入警告范围，到期瞬间则单独归为过期。负例传入的是缺少时区的到期时间；函数也检查观察时刻，但本例没有单独测试第二个参数缺少时区的分支。断言验证的是这套明确的告警规则，不依赖执行当天，也不假设所有证书都拥有相同总寿命。

保留的精确记录覆盖这份未变的算术夹具；本轮源码复核没有重跑。该实验没有运行 Caddy、获取证书或观察真实续期。部署验收仍需要检查客户端实际收到的证书、已经配置的挑战路径，并在预期持久存储条件下观察续期成功。应把这些运行证据与这份可重复的小型日期算术检查分开记录，才能知道哪一部分已经证明，哪一部分仍需要实际环境验证。

来源

Python assert statement，优化模式省略断言及其内部调用，已核验 2026-10-18。
Caddy 自动 HTTPS，启用条件、本地信任、挑战选择及存储，已核验 2026-10-15。
Caddy file-server 命令，默认监听端口与 domain 参数，已核验 2026-10-15。
Let’s Encrypt 挑战类型，验证端口、DNS 自动化及受限凭据，已核验 2026-10-15。
Let’s Encrypt 速率限制，实验使用预发环境与签发失败，已核验 2026-10-15。

Link 头把相邻的资源关联起来

Fri, 04 Dec 2026 00:00:00 +0000

Link 响应头描述当前资源与其他资源之间的关系。一个返回 JSON 的接口可以用它给出下一页，让客户端不必解析 HTML，也不必猜测分页参数。这个字段提供目标地址和关系类型，是否访问仍由客户端决定。它是可供理解的元数据，不是强制浏览器下载资源、要求爬虫收录页面或授予访问权限的指令。

相对于有效请求地址解析返回的目标。保留关系语法，并分别处理目标策略与浏览器暴露规则。

链接包含上下文与目标

例如 </items?cursor=b>; rel="next"，表示从当前上下文资源指向指定目标。没有显式的 anchor 参数时，上下文通常是被请求的资源。相对目标应根据重定向之后的有效请求地址解析，不能根据程序工作目录或想象中的接口根路径拼接。只包含查询串的目标会替换查询参数而保留路径，这与以斜杠开头、从站点根部解析的地址不同。

rel 指出关系类型，注册关系包括 next、prev、alternate 和 canonical，扩展关系还可以使用 URI 标识。type="application/json" 等参数描述的是目标资源，不会改写当前响应实际的内容类型，也不保证目标可信。如果一个链接通过 anchor 改变了上下文，无法处理这种上下文的客户端就不应擅自把它解释成当前页面的关系，否则链接含义已经改变。

不同关系还对应不同消费者。爬虫可能参考 canonical 选择优先收录地址，支持相应机制的浏览器可能根据 preload 提示提前获取资源，但这两种关系都不会把当前请求变成重定向。需要将字段语法验证与目标消费者的行为验证分开：普通 HTTP 库完全可以正确返回这个头，却不主动跟随或下载任何目标。

分页沿服务端契约前进

分页接口由服务器判断是否存在后续结果，并给出下一次应当请求的完整目标。游标可能编码排序、筛选条件和快照位置，应当作为不透明值使用。客户端自己递增页码、解码后改写游标或丢掉返回链接上的查询条件，都可能跳过数据、重复读取或使请求失效。跟随服务器提供的目标，才能让客户端适应接口内部分页方式的调整。

在具体接口的分页契约下，没有 next 通常意味着本次遍历结束，但不能据此推断整个集合从此不再变化。若没有快照语义，并发插入与删除依然可能改变两次请求之间的成员。采集程序应设置请求上限，并识别反复出现的续页目标，以免服务端错误导致无限循环。遇到限流或失败也不能直接当成最后一页，否则得到的是被误标为完整的残缺集合。

坏掉的样子

一个响应可以用多条 Link 字段，也可以在同一字段中用逗号分隔多个链接。直接按每个逗号切分会出错，因为带引号的参数值、甚至 URI 引用本身都可能包含逗号。应使用符合 Web Linking 语法的解析器，保留重复字段并正确处理关系标记。如果代理把多条字段覆盖成最后一条，正文虽然仍然有效，下一页信息却可能已经丢失。此时应比较源站和代理后的原始头部。

另一类故障是盲目跟随绝对地址。携带身份信息的接口客户端必须先检查目标是否符合访问策略，再决定是否发起请求以及能否转发凭据。一个链接并没有授权程序把令牌发送到其他源。浏览器还有额外边界：跨源请求能够读取正文，不代表脚本能读取 Link；服务器需要在 Access-Control-Expose-Headers 中明确暴露它。只用命令行看见字段，无法验证浏览器里的读取权限。

快速验证

此前的源码复核只检查了此示例，没有重新运行本地监听或浏览器 CORS 检查。在 2026-10-17 的独立运行中，完整原始英文和中文 Python 代码块分别执行一次，环境为 macOS 26.5.1 arm64、Python 3.14.4，使用 -I -B、关闭优化，并保留全部四处原始 assert 语句。两次运行均输出完整且完全匹配的确认行、以零状态退出、标准错误为空；套接字、线程和各自拥有的临时工作目录均已清理。

每种语言的运行各记录两次成功的回环连接和两条应用层 GET／状态事件：依次为 /items?cursor=a 与 /items?cursor=b，状态均为 200，并与同一个自有监听器代次匹配。这些记录不是抓包，也不是独立的线上状态测量。第二个目标仍是硬编码的 ?cursor=b；本次没有测试通用 Link 解析器、替代资源获取、重定向或凭据策略、分页循环处理或浏览器 CORS 行为。

以下 Python 3 实验启动一个两页的回环接口。第一页分别返回 next 和 alternate 两条字段，末页不返回链接。客户端检查原始字段，并用标准 URL 库解析实验里已知的相对目标；这段代码不是通用链接解析器，不能照搬其中的固定字符串假定来解析任意接口。

from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread
from urllib.parse import urljoin, urlsplit

class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 self.send_response(200)
 self.send_header("Content-Length", "2")
 if self.path == "/items?cursor=a":
 self.send_header("Link", '<?cursor=b>; rel="next"')
 self.send_header("Link", '</items.csv>; rel="alternate"')
 self.end_headers()
 self.wfile.write(b"[]")

 def log_message(self, *args):
 pass

with ThreadingHTTPServer(("127.0.0.1", 0), Handler) as server:
 worker = Thread(target=server.serve_forever, daemon=True)
 worker.start()
 client = HTTPConnection(*server.server_address, timeout=3)
 try:
 client.request("GET", "/items?cursor=a")
 response = client.getresponse()
 links = response.headers.get_all("Link")
 assert response.read() == b"[]"
 assert links == ['<?cursor=b>; rel="next"',
 '</items.csv>; rel="alternate"']
 base = f"http://127.0.0.1:{server.server_port}/items?cursor=a"
 target = urlsplit(urljoin(base, "?cursor=b"))
 client.request("GET", target.path + "?" + target.query)
 response = client.getresponse()
 assert response.read() == b"[]"
 assert response.headers.get_all("Link") is None
 print("two fields preserved; terminal page has no next link")
 finally:
 client.close()
 server.shutdown()
 worker.join()

预期没有断言失败，并打印最后一行确认信息。查询目标应解析成 /items?cursor=b，第一页的两条字段都应保留。实验验证了响应构造、重复字段读取和相对地址解析，没有证明完整分页客户端已经正确。真实解析器还要覆盖引号内逗号、重定向、多关系、跨源目标和循环链接；浏览器暴露字段的效果，则需要从实际调用页面的源进行验证。

来源

RFC 8288：Web 链接，链接上下文、关系类型和字段语法，已核验 2026-09-06。
MDN：Link 头，字段语法和相对地址解析，已核验 2026-09-06。
MDN：Access-Control-Expose-Headers，向跨源浏览器脚本暴露响应元数据，已核验 2026-09-06。

结合传输与业务结果读取状态码

Thu, 03 Dec 2026 00:00:00 +0000

调用方需要的不只是三位数字，还要知道是否收到 HTTP 响应、正文是否完整到达，以及应用结果是否满足预期操作。这是三个不同的问题。二百响应可以按既定契约携带应用层失败，也可能在响应头之后发生传输中断；没有收到响应之前就连接失败，则根本没有 HTTP 状态。诊断和指标应保留这些区别，不能把它们压成一个过于简单的成功标志。

按实际取得的证据分类

HTTP 错误响应仍然是一份响应，其中可能包含有用的表示、认证挑战、请求标识或 Retry-After 字段。有些客户端库会为四开头和五开头状态抛出异常，但仍允许读取这些信息。处理时应先捕获具体 HTTP 异常，再处理更宽泛的传输异常；否则，一个带明确限流提示的四二九，就可能被归成和连接失败完全相同的通用网络错误，丢失下一步判断依据。

HTTP 交换成功也可能只代表业务信封成功传递。例如批处理或 RPC 契约可以返回二百，同时在正文里说明某个子操作失败。应读取文档定义的结构，而不是默认这种响应里的业务全部成功，也不能断言所有此类接口都违反 HTTP。监控需要验证自己承诺监控的结果；如果业务契约要求检查正文，那么只读状态码就没有完成相应检查。

坏掉的样子

在收到响应头时记录状态，可能掩盖随后出现的正文截断。Content-Length、流结束、解压与解析，都影响最后是否得到可用表示。应把已经收到的状态与未完成的传输分别报告，不能因为状态指标已经计入二百，就把只有半份内容的响应视为应用成功。收到响应头，是比完整收到并理解业务结果更早的一个验证点。

是否重试也不能只看第一位数字。四二九表示请求受到限流，可以附带 Retry-After；五零三也可能建议等待。该字段可以使用延迟秒数或 HTTP 日期，但两种形式都没有保证服务器到时一定恢复。客户端应结合服务器提示、有界重试策略、退避和操作语义，避免一遇到错误就立即重放。等待提示不是无限重试的授权，也不是恢复成功的证据。

非幂等请求的响应丢失，可能让业务效果处于未知状态：客户端失去联系之前，服务器也许已经提交。没有合适的幂等契约就重复操作，可能产生重复工作。另一方面，有些四开头错误会随着身份、状态或限流条件改变而变得可恢复。按照整个类别制定“总是重试”或“绝不重试”，会抹掉真正需要用于决策的信息，而不是简化正确的处理逻辑。

状态码本身也不能说明究竟是哪一个组件生成了响应。源站、网关和中间层都可能返回错误，归因时应结合请求标识与相应日志。curl 的 000 一类诊断值，不是注册的 HTTP 响应状态，通常表示没有取得可用的 HTTP 状态。把它当成某种服务器错误，会把连接阶段的问题错误地归到已经收到响应之后的处理阶段。

HTTP：分别判断三类结果。保留的 Mac 试验范围见下文；绘图与本次采纳审阅均未重跑示例。

快速验证

将脚本保存为 status-client.py，使用保留断言的 Python 3.14。五种回环响应和第六个已绑定但未监听的端点，用于检查分类。私有 urllib opener 只为实验关闭代理发现，不更改系统代理。第六个键为 no-response，只检查没有返回 HTTP 状态，不要求特定的拒绝连接错误。保留的 Mac 试验中，该端点始终由实验持有、没有监听，实际观察到的是超时。具体执行设置和证据限制见下文。

from http.client import IncompleteRead
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread
from urllib.error import HTTPError
from urllib.request import ProxyHandler, build_opener
import json
import socket


class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 if self.path == '/application-error':
 status, data, retry = 200, b'{"ok":false,"error":"demo"}', None
 elif self.path == '/busy':
 status, data, retry = 503, b'{"error":"unavailable"}', '3'
 elif self.path == '/limit':
 status, data, retry = 429, b'{"error":"limited"}', '2'
 else:
 status, data, retry = 404, b'{"error":"missing"}', None
 if self.path == '/truncated':
 self.send_response(200)
 self.send_header('Content-Length', '100')
 self.end_headers()
 self.wfile.write(b'partial')
 return
 self.send_response(status)
 self.send_header('Content-Type', 'application/json')
 self.send_header('Content-Length', str(len(data)))
 if retry:
 self.send_header('Retry-After', retry)
 self.end_headers()
 self.wfile.write(data)

 def log_message(self, *args):
 pass


opener = build_opener(ProxyHandler({}))


def inspect(url):
 try:
 response = opener.open(url, timeout=3)
 except HTTPError as error:
 response = error
 except OSError: # Includes URLError and socket timeout/connection errors.
 return {'http_status': None, 'transport_failure': True}
 with response:
 result = {'http_status': response.code, 'retry_after': response.headers.get('Retry-After')}
 try:
 body = response.read()
 except (IncompleteRead, OSError):
 return {**result, 'complete_body': False}
 return {**result, 'complete_body': True, 'payload': json.loads(body)}


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}'
 results = {path: inspect(origin + path) for path in
 ('/application-error', '/busy', '/limit', '/missing', '/truncated')}
 with socket.socket() as reserved:
 reserved.bind(('127.0.0.1', 0)) # Still owned, never listening: no HTTP response expected.
 results['no-response'] = inspect(f'http://127.0.0.1:{reserved.getsockname()[1]}/')
 assert results['/application-error']['http_status'] == 200
 assert results['/application-error']['payload']['ok'] is False
 assert results['/busy']['http_status'] == 503 and results['/busy']['retry_after'] == '3'
 assert results['/limit']['http_status'] == 429 and results['/limit']['retry_after'] == '2'
 assert results['/missing']['http_status'] == 404
 assert all(results[path]['complete_body'] is True for path in
 ('/application-error', '/busy', '/limit', '/missing'))
 assert results['/truncated'] == {'http_status': 200, 'retry_after': None, 'complete_body': False}
 assert results['no-response'] == {'http_status': None, 'transport_failure': True}
 print(json.dumps(results))
finally:
 server.shutdown()
 thread.join()
 server.server_close()

预期应用信封返回 HTTP 二百与 ok: false。繁忙和限流端点分别返回五零三、四二九，并保留 Retry-After 的三秒和两秒文本值。缺失端点仍记录为 HTTP 四零四。这四种情况只有完成读取并成功解析 JSON，才能正常返回相应对象；脚本没有实际等待提示时长、进行重试，也没有宣称等待后一定成功。

截断端点声明一百字节，却只发送 partial。结果在 IncompleteRead 之后保留二百状态，并标记正文不完整。分类器在打开阶段先处理 HTTPError，再处理其他 OSError，从而保留已收到的错误响应。读取正文时遇到 IncompleteRead 或 OSError（包括 TimeoutError），则保留已经收到的状态和 Retry-After，同时设置 complete_body: false。JSON 解析不在这一捕获范围内；其他协议或解析失败仍可能向外抛出。这是小型分类示例，不能当成通用异常处理。

保留的 2026-10-18 试验在 macOS 26.5.1 arm64 上使用 Python 3.14.4，由外部监督器运行，启用 -I -B 并保留断言。上方中英文完整代码正文逐字节相同，分别作为 A-en、A-zh 各执行一次，均返回六种预期结果。另一个单请求的 B-positive 改编使用同一 inspect 函数，让 HTTP 四二九响应的正文保持未完成，直到读取阶段发生 TimeoutError；结果保留状态四二九、Retry-After 的 2，以及 complete_body: false。正文超时属于 B 的独立证据，不是上方六情况脚本新增的端点。四个精确负向变体分别在预期断言处被拒绝：丢弃正文超时后的元数据、把已收到响应当成没有响应、丢弃 HTTPError 元数据，以及把截断正文标为完整。

这是一次包含七个情况的批次，观察到三十二次 inspect 调用，在 19.1647 秒内完成；带观测工具的耗时不是性能基准。监督器继承了未修改的环境，但使用隔离解释器参数，因此不能据此证明默认环境或启动定制链的行为。记录只显示这一次运行的子进程自然退出和清理，没有抓包，也不证明生产行为。文章里的三秒套接字超时、shutdown() 和没有期限的 thread.join() 仍然不是整个进程的截止时间。分类不能验证服务器恢复或写操作重放安全。此前未修正代码、仅编译记录及既有诊断失败均保留为历史证据；本次修正版试验不能倒推证明那些旧可执行字节已经通过。

来源

RFC 9110: HTTP Semantics，状态解释、重试及 Retry-After 语义，已核验 2026-09-13。
RFC 6585: additional HTTP status codes，429 Too Many Requests 的含义，已核验 2026-09-13。
Python 3.14: urllib.request，HTTP 响应对象与错误处理，已核验 2026-09-13。
Python 3.14: urllib.error，HTTPError 响应访问与 URLError 继承关系，已核验 2026-10-18。
Python 3.14: http.client，响应读取与 IncompleteRead，已核验 2026-10-18。
Python 3.14: assert statements，优化模式会移除断言检查，已核验 2026-10-18。
Python 3.14: socket，TimeoutError/OSError 与依赖平台的超时行为，已核验 2026-10-19。

字节边界与解码规则一致，UTF-8 才能完整保留文本

Wed, 02 Dec 2026 00:00:00 +0000

UTF-8 用一到四字节编码 Unicode 标量值。ASCII 字符保持熟悉的单字节表示，许多其他字符则需要更长序列。它适合文本交换，却不会让任意字节自动成为有效文本，也不会让每个字节偏移都成为字符边界。正确处理需要编码约定、符合契约的有效性检查，以及对原始字节和已经解码文本的明确区分。

一次读取可能切开字符。保留未完成字节，严格结束校验，并明确计数单位。

坏掉的样子

文件或网络读取可以停在多字节序列中间。每块独立解码，会拒绝原本完整且有效的整个字节流；如果每块都立即替换错误，还可能破坏本应与下一块组成字符的字节。流式解码器需要保留未完成输入，等后续数据到来再处理，并在流结束时检查是否仍有残缺序列。分块边界是传输细节，不是文本天然边界。

UTF-8 的起始与续字节具有可识别模式，但这不使任意切片安全。直接截断编码后的字节串，可能把一个序列切成两半。使用另一种编码成功解码，也不能证明解释正确。Latin-1 能映射每个字节，因此把 UTF-8 误解为 Latin-1，仍会得到合法 Unicode 字符串，却可能已经成为乱码。有效字符串和正确文本不是同一结论。

编码有效性还不同于文本等价与显示宽度。一个看起来带重音的字母，可以由单个码点表示，也可以由基础字母和组合标记表示。规范化能够让选定形式便于比较，但 UTF-8 解码不会自动完成规范化。同样，字节顺序标记可能成为字符串开头的实际字符，除非选定编解码器明确消费它。不能把这些处理都笼统称为“转换编码”。

快速验证

将脚本保存为 check-utf8.py，准备 Docker 后执行 python3 check-utf8.py。固定 Python 3.11.16 容器在无网络环境下运行标准库编码与 Unicode 操作，输入都是内存中明确给出的字节和字符串。实验不迁移数据库，也不转换现有文件；断言依赖字节和码点，不要求终端能够正确绘制某个表情图形：

import json,subprocess,uuid
image="python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84"
program=r"""
import codecs,json,unicodedata

text='A中🙂';encoded=text.encode('utf-8');assert len(text)==3 and len(encoded)==8
assert encoded.hex()=='41e4b8adf09f9982' and encoded.decode('utf-8')==text
pieces=[encoded[:2],encoded[2:5],encoded[5:]]
split_errors=0
for piece in pieces:
 try:piece.decode('utf-8')
 except UnicodeDecodeError:split_errors+=1
assert split_errors==3
decoder=codecs.getincrementaldecoder('utf-8')(errors='strict');decoded=[]
for piece in pieces:decoded.append(decoder.decode(piece,final=False))
decoded.append(decoder.decode(b'',final=True));assert ''.join(decoded)==text
rejected={}
for label,raw in {'overlong':bytes.fromhex('c0af'),'surrogate':bytes.fromhex('eda080'),
 'too_large':bytes.fromhex('f4908080'),'truncated':bytes.fromhex('e4b8')}.items():
 try:raw.decode('utf-8');raise AssertionError('invalid UTF-8 accepted')
 except UnicodeDecodeError as error:rejected[label]=error.reason
bad_tail=codecs.getincrementaldecoder('utf-8')();assert bad_tail.decode(bytes.fromhex('e4b8'),final=False)==''
try:bad_tail.decode(b'',final=True);raise AssertionError('incomplete final sequence accepted')
except UnicodeDecodeError:final_rejected=True
mojibake=encoded.decode('latin-1');assert mojibake!=text and mojibake.encode('latin-1')==encoded
decomposed='e\u0301';composed='é';assert decomposed!=composed and unicodedata.normalize('NFC',decomposed)==composed
bom=b'\xef\xbb\xbf'+encoded;assert bom.decode('utf-8').startswith('\ufeff') and bom.decode('utf-8-sig')==text
replacement=bytes.fromhex('ff41').decode('utf-8',errors='replace');assert replacement=='\ufffdA'
print(json.dumps({'text':text,'code_points':len(text),'bytes':len(encoded),'hex':encoded.hex(),
 'chunk_hex':[x.hex() for x in pieces],'independent_chunk_failures':split_errors,'incremental_output':decoded,
 'invalid_rejections':rejected,'final_incomplete_rejected':final_rejected,'latin1_code_points':[hex(ord(c)) for c in mojibake],
 'normalization_lengths':[len(decomposed),len(composed)],'bom_utf8_first':hex(ord(bom.decode('utf-8')[0])),
 'utf8_sig_strips_bom':bom.decode('utf-8-sig')==text,'replacement':replacement},ensure_ascii=False))
"""
name='xbcatm-socket-'+uuid.uuid4().hex[:10]
try:
 result=subprocess.run(['docker','run','--rm','-i','--name',name,'--network','none',
 '--memory','128m','--pids-limit','64',image,'python3','-'],input=program,
 capture_output=True,text=True,timeout=60)
 assert result.returncode==0,result.stderr
 print(json.dumps(json.loads(result.stdout),ensure_ascii=False,sort_keys=True))
finally:
 subprocess.run(['docker','rm','-f',name],capture_output=True,text=True,timeout=10)

字符串 A中🙂 在 Python 中具有三个对应码点的元素，编码后为八字节，十六进制是 41e4b8adf09f9982。ASCII 占一字节，汉字占三字节，表情占四字节；重新解码返回原文。编码字节数和这些码点数量回答不同问题，也都不能自动等同于屏幕列宽。限制字段长度前，必须先明确限制使用哪种单位。

程序把字节拆为 41e4、b8adf0、9f9982，每块当作完整 UTF-8 独立解码都会失败。增量解码器却依次输出 A、中、🙂，在调用之间保留部分序列，最后以 final=True 的空输入完成验证。另一个只持有 e4b8 的解码器，在结束时拒绝残缺序列，没有悄悄丢掉最后一段内容。

四个负向案例分别拒绝过长编码、代理码点、超出 Unicode 上限的值和不完整序列。即使部分字节看起来符合续字节模式，这些形式仍不属于有效 UTF-8。程序明确捕获 UnicodeDecodeError，不把无关异常当成校验成功，也没有使用允许代理码点的宽松模式。验证对象是标准编码规则，而不只是某个函数是否发生错误。

把有效 UTF-8 字节按 Latin-1 解码会成功，却产生不同码点。这个受控案例中，再按 Latin-1 编码错误字符串，可以恢复原字节，但它不是通用乱码修复算法。此前若经过替换、规范化或有损转换，信息可能已经消失。诊断编码不一致时，应先保留原始字节，再决定是否有证据支持某个逆向转换。

脚本还比较分解形式的字母与组合重音，以及组合形式 é。两者初始不相等，长度分别为二和一，NFC 规范化后相等。另外，普通 UTF-8 解码保留开头 BOM 为 U+FEFF，utf-8-sig 则消费它。这是两种独立转换，不能仅因文本看起来奇怪就同时应用。是否允许规范化或删除标记，需要依据字段和格式契约。

明确每个边界的字节契约

HTTP charset 声明或文件格式规范告诉消费者怎样解释字节，修改声明本身不会转码正文。生产端编码器、传输元信息、解析器和存储接口需要一致。应让包含多字节字符的样本经过真实边界，特别检查截断、分块缓冲和按字节计量的限制。只在程序入口看到 UTF-8 字样，并不能说明中途每一步都正确处理了内容。

按数据契约选择错误策略。实验展示 errors=‘replace’ 将非法输入变成 U+FFFD，结果是合法但有损的文本。这可能适合诊断显示，却不能证明标识符或签名数据得到保留。拒绝、替换、移除 BOM 和规范化，应作为具有不同可观察效果的独立决定，避免一个宽松解码动作掩盖本来需要向调用方报告的数据损坏。

限制已解码文本时，使用符合字符需求的操作；限制编码消息时，使用明确消息边界。增量解码解决被切开的字节序列，不定义字素簇、换行布局或数据库比较语义。应验证应用实际要求的属性，而不是把“统一使用 UTF-8”当成所有文本边界都正确的证明。编码一致只是完整文本处理契约的一部分。

来源

RFC 3629 UTF-8，有效字节序列、标量范围及非法编码，已核验 2026-09-12。
Unicode UTF and BOM FAQ，编码边界与字节顺序标记行为，已核验 2026-09-12。
Python 3.11 codecs，增量解码、结束校验与错误处理策略，已核验 2026-09-12。
Python 3.11 unicodedata，作为独立操作的 Unicode 规范化，已核验 2026-09-12。

SNI 根据请求主机名选择 TLS 证书

Sun, 08 Nov 2026 00:00:00 +0000

服务器名称指示 SNI 在 TLS 服务器选择握手参数和证书时，提供客户端希望访问的主机名。本文讨论的是证书认证且没有 early data 的路径，因此选择发生在普通 HTTP 字节发送之前，不是网络上任何字节都还没出现的时候。SNI 只是帮助选择，客户端仍然必须验证返回的证书身份。

同一个地址上的不同决策

客户端把 server_name 放在 ClientHello 中，托管多个名称的服务器可以据此选择证书或安全配置。TLS 1.3 在 ServerHello 之后加密证书消息，所以“选证书和传证书都在加密开始之前完成”不是准确描述。应区分先收到选择提示，和随后如何保护证书及其他握手消息。

SNI 中的 DNS 主机名不等于建立连接时使用的目标 IP，填写名称也不要求实验域名真的经过公共 DNS 解析。RFC 6066 不允许在 HostName 字段直接放入 IPv4、IPv6 字面地址，并规定 DNS 主机名比较不区分大小写。客户端直接按 IP 访问时，可以不发送 DNS SNI，转而验证对应的 IP 身份。

多个站点也不一定要使用多张证书。一张证书可以覆盖多个 SAN，服务器没有收到 SNI 时也可以选择默认证书。客户端是否接受，取决于预期访问名称和信任规则；并不是缺少 SNI 就绝对无法建立安全连接。SNI 的作用是帮助选择，不是凭空建立信任，更不证明请求方拥有该主机名。

坏掉的样子

客户端即使连到了正确 IP，仍可能因为没有传递正确名称而拿到其他站点的默认证书。关闭主机名验证只会隐藏这类问题。应分别检查目标地址、预期 TLS 名称、返回证书的 SAN、信任链和有效期，不能把“地址没错”当成身份已经正确的证据。

HTTP Host 或 HTTP/2 的 authority 属于应用层，修改它们不会重新进行 TLS 握手或替换证书。ALPN 则单独协商 HTTP/2 等应用协议，不验证主机名，也不授权租户。证书选择、客户端对服务端身份的验证、协议协商与应用路由，需要分别检查；不能因为其中一项成功，就宣布其他边界也已经正确。

未知 SNI 可能被服务器拒绝，也可能获得默认证书，具体取决于配置；缺少 SNI 并不总会失败。未使用 ECH 时，普通 ClientHello 中的 SNI 在网络上可见，单纯采用 TLS 1.3 不会把它隐藏。ECH 需要额外的部署支持，也不能消除全部流量特征，因此不能把名称隐私当成无需验证就存在的能力。

SNI 证书选择：机制与证据边界。

快速验证

保存为 sni_probe.go，用 Go 1.23 或更新版本运行 go run sni_probe.go。程序在内存中生成一个短期测试 CA 和两张叶证书，只有本地测试客户端信任这个 CA。所有请求都连接同一个回环 IP，通过 ServerName 提供预期 TLS 名称，无需让测试域名经过公共 DNS；实验不复用 TLS 会话或 HTTP 连接。

测试 CA 与叶证书一小时后过期，这是隔离实验的选择，不是生产证书续期策略。生成了证书，不代表其他客户端就会信任它；本例明确配置的信任根池，才为这些请求建立了验证基础。需要把证书生成、服务端选择和客户端信任分开检查，不能把它们合并成一个含糊的“证书可用”。

package main

import (
 "crypto/ed25519"
 "crypto/rand"
 "crypto/tls"
 "crypto/x509"
 "errors"
 "fmt"
 "io"
 "log"
 "math/big"
 "net/http"
 "net/http/httptest"
 "runtime"
 "strings"
 "sync/atomic"
 "time"
)

func must(err error) {
 if err != nil {
 panic(err)
 }
}

func check(ok bool, message string) {
 if !ok {
 panic(message)
 }
}

func leaf(name string, serial int64, ca *x509.Certificate, signer ed25519.PrivateKey) tls.Certificate {
 public, private, err := ed25519.GenerateKey(rand.Reader)
 must(err)
 now := time.Now()
 template := &x509.Certificate{
 SerialNumber: big.NewInt(serial), DNSNames: []string{name},
 NotBefore: now.Add(-time.Minute), NotAfter: now.Add(time.Hour),
 KeyUsage: x509.KeyUsageDigitalSignature,
 ExtKeyUsage: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
 }
 der, err := x509.CreateCertificate(rand.Reader, template, ca, public, signer)
 must(err)
 certificate, err := x509.ParseCertificate(der)
 must(err)
 return tls.Certificate{Certificate: [][]byte{der}, PrivateKey: private, Leaf: certificate}
}

func main() {
 public, private, err := ed25519.GenerateKey(rand.Reader)
 must(err)
 now := time.Now()
 template := &x509.Certificate{
 SerialNumber: big.NewInt(1), IsCA: true, BasicConstraintsValid: true,
 NotBefore: now.Add(-time.Minute), NotAfter: now.Add(time.Hour),
 KeyUsage: x509.KeyUsageCertSign,
 }
 der, err := x509.CreateCertificate(rand.Reader, template, template, public, private)
 must(err)
 ca, err := x509.ParseCertificate(der)
 must(err)
 roots := x509.NewCertPool()
 roots.AddCert(ca)
 alpha := leaf("alpha.example.test", 2, ca, private)
 beta := leaf("beta.example.test", 3, ca, private)
 certificates := map[string]*tls.Certificate{
 "alpha.example.test": &alpha, "beta.example.test": &beta,
 }

 var handled, rejected atomic.Int64
 server := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 handled.Add(1)
 fmt.Fprintf(w, "%s|%s", r.TLS.ServerName, r.Host)
 }))
 server.Config.ErrorLog = log.New(io.Discard, "", 0)
 server.TLS = &tls.Config{
 MinVersion: tls.VersionTLS13, MaxVersion: tls.VersionTLS13,
 Certificates: []tls.Certificate{alpha}, SessionTicketsDisabled: true,
 GetCertificate: func(hello *tls.ClientHelloInfo) (*tls.Certificate, error) {
 certificate, ok := certificates[strings.ToLower(hello.ServerName)]
 if !ok {
 rejected.Add(1)
 return nil, fmt.Errorf("unknown fixture SNI")
 }
 return certificate, nil
 },
 }
 server.StartTLS()
 defer server.Close()

 request := func(name, host string) (string, error) {
 config := &tls.Config{RootCAs: roots, ServerName: name, MinVersion: tls.VersionTLS13}
 transport := &http.Transport{TLSClientConfig: config, DisableKeepAlives: true}
 defer transport.CloseIdleConnections()
 client := &http.Client{Transport: transport, Timeout: 2 * time.Second}
 request, err := http.NewRequest(http.MethodGet, server.URL, nil)
 must(err)
 request.Host = host
 response, err := client.Do(request)
 if err != nil {
 return "", err
 }
 defer response.Body.Close()
 body, err := io.ReadAll(response.Body)
 if err != nil {
 return "", err
 }
 check(response.StatusCode == 200, "unexpected HTTP status")
 check(response.TLS.Version == tls.VersionTLS13 && len(response.TLS.VerifiedChains) > 0, "verified TLS 1.3 required")
 check(string(body) == name+"|"+host, "handler must observe separate SNI and Host")
 certificate := response.TLS.PeerCertificates[0]
 must(certificate.VerifyHostname(name))
 return certificate.DNSNames[0], nil
 }

 for _, name := range []string{"alpha.example.test", "beta.example.test"} {
 selected, err := request(name, name)
 must(err)
 check(selected == name, "SNI must select its matching certificate")
 fmt.Println("SNI", name, "selected", selected)
 }
 selected, err := request("ALPHA.EXAMPLE.TEST", "alpha.example.test")
 must(err)
 check(selected == "alpha.example.test", "DNS name selection must be case-insensitive")
 selected, err = request("alpha.example.test", "beta.example.test")
 must(err)
 check(selected == "alpha.example.test", "HTTP Host must not change the TLS certificate")
 _, err = request("missing.example.test", "missing.example.test")
 check(err != nil && rejected.Load() == 1, "unknown SNI must be rejected by fixture policy")
 _, err = request("", "alpha.example.test")
 var nameError x509.HostnameError
 check(errors.As(err, &nameError), "without DNS SNI, default certificate must fail IP identity")
 check(handled.Load() == 4, "only four verified requests may reach the handler")
 fmt.Println("uppercase name selects alpha; Host override keeps alpha; unknown SNI and IP-name mismatch rejected")
 fmt.Println(runtime.Version())
}

alpha 和 beta 分别选中自己的证书，大写的 alpha 名称也应选中同一张 alpha 证书。客户端保持标准信任链和主机名验证，实验还额外检查了实际返回的证书。四个通过验证的请求进入回显 handler，其中一个刻意使用 alpha SNI 和 beta Host；它认证的仍然是 alpha，证明两个字段是不同输入，并不表示可以据此访问另一个租户的数据。

未知 SNI 被这个测试服务的固定名称策略拒绝。当 ServerName 为空时，请求地址中的 IP 不产生 DNS SNI，服务器选择的默认 alpha 证书又没有对应的 IP 身份，因此主机名验证失败。即使 HTTP Host 填写 alpha，也不能提前改变这个 TLS 验证结果。两个反向测试都没有进入 HTTP handler。

这里的 handler 有意回显两种名称，方便观察它们的差别，不是可直接投入生产的虚拟主机路由器。真实入口仍应按照既定策略解释 HTTP authority 和租户访问权限，不能根据 TLS 握手成功就忽略后续路由与授权检查，也不能把实验中允许的字段差异扩大成任意跨租户请求都可以处理。

保留证据能够确认 Go 1.24.4 编译通过，而握手执行仍被阻断；旧文的 macOS、Go 1.27.0 成功说法，在这里没有对应的留存运行记录。本次源码审阅没有执行 TLS 实验。源码表明私钥只用于样本，不安装到全局信任库；ECH、ALPN 协商、通配符、国际化名称、HTTP/2 合并、会话恢复与真实入口，仍需分别测试。

来源

RFC 6066：TLS 扩展，server_name、名称格式与服务端选择，已核验 2026-09-09。
RFC 8446：TLS 1.3，ServerHello 之后的加密握手消息，已核验 2026-09-09。
Go crypto/tls，ServerName、GetCertificate 与显式 ECH 配置，已核验 2026-09-09。
Go crypto/x509，测试证书生成与基于 SAN 的名称验证，已核验 2026-09-09。
Go net/http/httptest，临时回环 TLS 服务，已核验 2026-09-09。
RFC 7301：ALPN，应用协议选择不同于服务端名称指示，已核验 2026-10-18。

Server-Timing 向浏览器暴露具名测量结果

Sat, 07 Nov 2026 00:00:00 +0000

Server-Timing 响应头允许服务端给响应附加具名测量结果，浏览器开发者工具和性能接口随后可以把这些结果与对应资源请求关联起来。当网络瀑布图只能显示等待很久，却无法说明后端是否在查询数据库、渲染页面或执行其他操作时，这类信息很有帮助。但它提供的是服务端选择上报的观测结果，并不是浏览器独立测得这些内部操作的耗时，因此仍然需要理解测量范围和产生位置。

正确的时长语法是 db;dur=42, render;dur=81，建议使用毫秒作为单位。浏览器解析数值，但无法验证发送方实际采用的单位。直接写 db=42，并不是这项协议表达时长的方式。每个指标有名称，也可以带时长和描述参数。生产环境应采用含义稳定的名称，从实际插桩中得到数值。描述可以解释测量对象，但不应包含响应本来不该披露的原始查询、身份编号或内部细节。浏览器能够展示字段，不代表所有调试内容都适合跟随响应对外发送。

让数值对应明确的时间区间

服务端的多个测量值不一定能加成浏览器看到的请求总耗时。它们可能覆盖嵌套操作、相互重叠的工作，也可能只覆盖处理路径的一部分。只有数据库时间与渲染时间的定义允许相加时，加总才有意义。网络传输、测量区间之外的排队、缓存和客户端处理，都可能解释两侧数字的差异，并不一定说明某个时钟有错误。应先弄清每个数值从哪里开始、在哪里结束。

这个响应头也不会自动生成分布式链路。它在单个响应上命名测量结果，并没有自动提供父子关系、跨服务传播或采集器存储。可以用它展示少量对请求有帮助的测量，再通过日志或链路关联获取更深的解释。当响应经过缓存和代理时，还应检查最终交付的响应头，确定这些数字由哪个组件产生。读取一个字段与证明当前源站执行了相应工作，是不同层次的证据。

坏掉的样子

跨源资源存在两个容易混淆的权限边界。CORS 允许脚本读取响应，而 Access-Control-Expose-Headers 可以让 response.headers 暴露 Server-Timing 字段。Timing-Allow-Origin 则控制相应的详细资源计时信息是否可见。安全上下文与浏览器隐私规则还可能进一步限制计时暴露。因此，脚本成功读取响应头，并不能证明 PerformanceResourceTiming.serverTiming 数组一定包含同样的数据。排查时需要分别验证，不能只用其中一个接口有值就推断另一项能力已经成立。

另一个错误，是把解析演示当成真实性能测量。服务端发送固定时长，只能证明浏览器怎样解析这个数字，不能说明处理器实际运行了那么久。同样，计时数组为空，也不能证明服务端没有做任何工作。应先核对来源授权与真实线上响应头，再检查测量代码放置的位置。公开名称与说明还要符合接收对象的范围，避免为了排障而把不该公开的后端结构随响应一起暴露出去。

相同的合成 Server-Timing 可作为响应头读取，却不出现在浏览器性能条目中。原文历史 Chrome 152 对照检查两种暴露权限，不是后端性能测量。

快速验证

将代码保存为 server-timing.py，执行 python3 server-timing.py --serve；此前记录使用 Python 3.14.4；本轮没有重跑套接字或浏览器测试。脚本在两个不同的临时端口上启动本机回环 HTTP 服务，因此它们是不同来源，然后输出待打开的页面地址。页面会请求两份资源，把响应头内容与浏览器解析出的性能条目同时显示出来。结束后按控制键加 C 关闭两个服务；不带服务参数执行时，只检查响应头并退出，不会自动运行浏览器。

import json
import sys
from http.server import BaseHTTPRequestHandler, HTTPServer
from threading import Event, Thread
from urllib.request import Request, urlopen

timing = "db;dur=42, render;dur=81"


class API(BaseHTTPRequestHandler):
 def log_message(self, *args):
 pass

 def do_GET(self):
 body = b"synthetic timing fixture\n"
 self.send_response(200)
 self.send_header("Content-Type", "text/plain; charset=utf-8")
 self.send_header("Content-Length", str(len(body)))
 self.send_header("Cache-Control", "no-store")
 self.send_header("Access-Control-Allow-Origin", app_origin)
 self.send_header("Access-Control-Expose-Headers", "Server-Timing")
 self.send_header("Server-Timing", timing)
 if self.path.split("?", 1)[0] == "/allow":
 self.send_header("Timing-Allow-Origin", app_origin)
 self.end_headers()
 self.wfile.write(body)


class App(BaseHTTPRequestHandler):
 def log_message(self, *args):
 pass

 def do_GET(self):
 body = ("""<!doctype html><meta charset="utf-8"><title>Server-Timing lab</title>
<h1>Cross-origin Server-Timing</h1><pre id="result">Running...</pre>
<script>
const api = """ + json.dumps(api_origin) + """;
async function run() {
 performance.clearResourceTimings();
 const results = {};
 for (const path of ['deny', 'allow']) {
 const url = api + '/' + path;
 const response = await fetch(url, {cache:'no-store'});
 await response.text();
 await new Promise(resolve => requestAnimationFrame(resolve));
 const entry = performance.getEntriesByName(url).at(-1);
 results[path] = {header:response.headers.get('Server-Timing'),
 timing:entry.serverTiming.map(item => ({name:item.name, duration:item.duration}))};
 }
 window.labResult = results;
 document.getElementById('result').textContent = JSON.stringify(results, null, 2);
}
run().catch(error => {window.labError=String(error); document.getElementById('result').textContent=String(error);});
</script>""").encode()
 self.send_response(200)
 self.send_header("Content-Type", "text/html; charset=utf-8")
 self.send_header("Content-Length", str(len(body)))
 self.end_headers()
 self.wfile.write(body)


api = HTTPServer(("127.0.0.1", 0), API)
app = HTTPServer(("127.0.0.1", 0), App)
api_origin = f"http://127.0.0.1:{api.server_port}"
app_origin = f"http://127.0.0.1:{app.server_port}"
threads = [Thread(target=server.serve_forever, daemon=True) for server in (api, app)]
for thread in threads:
 thread.start()
try:
 for path in ("deny", "allow"):
 with urlopen(Request(api_origin + "/" + path, headers={"Origin": app_origin}), timeout=5) as response:
 assert response.headers["Server-Timing"] == timing
 assert response.headers["Access-Control-Allow-Origin"] == app_origin
 assert response.headers["Access-Control-Expose-Headers"] == "Server-Timing"
 assert response.headers.get("Timing-Allow-Origin") == (app_origin if path == "allow" else None)
 response.read()
 print(json.dumps({"app_url": app_origin, "api_url": api_origin,
 "wire_checks": "PASS", "durations_are_synthetic": True}), flush=True)
 if "--serve" in sys.argv:
 Event().wait()
except KeyboardInterrupt:
 pass
finally:
 for server in (api, app):
 server.shutdown()
 server.server_close()
 for thread in threads:
 thread.join(timeout=5)

两份响应都通过 CORS 允许页面来源，都显式暴露 Server-Timing，也都携带同样的合成数据库与渲染时长。只有 allow 路径额外提供 Timing-Allow-Origin。在此前 Chrome 152 的观察记录中，两侧脚本都读到 db;dur=42, render;dur=81，但未授权的计时数组为空，已授权数组则包含名为 db、时长四十二，以及名为 render、时长八十一的两项结果。这份浏览器证据与 Python 的线上响应头断言分别检查，避免用非浏览器客户端代替实际可见性验证。

这里的固定数字有意只用于验证语法和暴露范围，不是数据库真正执行的时间。本地实验没有检查其他浏览器、生产代理、缓存响应或真实数据库插桩。实际接入时，应测量定义清楚的区间，在响应头已经提交之前写入字段，并让同类检查经过完整交付路径。还需要说明各名称的含义以及测量是否重叠，使阅读者不必自行想象一个服务端从未承诺过的可加总耗时分解。

来源

W3C Server Timing Working Draft，响应头参数及性能条目的暴露规则，已核验 2026-10-15。
MDN Server-Timing，时长语法、浏览器使用方式与信息披露边界，已核验 2026-09-13。
MDN Timing-Allow-Origin，跨源资源详细计时数据的授权方式，已核验 2026-09-13。
WHATWG Fetch，区分响应头暴露、计时授权与安全上下文处理，已核验 2026-10-15。

Web · XB 现场笔记

nginx 选择第一个匹配正则，不会计算通用具体程度分数

坏掉的样子

快速验证

让重叠在审阅中可见

来源

框架策略明确谁可以嵌入当前页面

把限制放到正确的响应上

坏掉的样子

快速验证

延伸阅读

来源

SSRF 让服务器替你去开门

先看清委托了什么权限

解析、解析域名，并保留已检查的目标

坏掉的样子

快速验证

来源

CSRF 检查请求到底来自哪里

Cookie 无意识地跟随请求

令牌把动作与来源绑定

SameSite 是浏览器护栏

把 Origin 当作来源信号

坏掉的样子

快速验证

延伸阅读

来源

显式启用 gzip，再验证协商与解码后的字节

坏掉的样子

快速验证

用有代表性的响应调整策略

延伸阅读

来源

请求限流保护的是 key 所命名的预算

坏掉的样子

快速验证

一起定义身份、范围和观测方式

来源

反向代理需要明确的请求头信任边界

坏掉的样子

快速验证

连接网络访问规则与头部解释

延伸阅读

来源

nginx 匹配规范化路径，并可能再次选择 location

坏掉的样子

快速验证

沿完整请求链验证路径契约

来源

404 页面诚实地作答

在渲染正文前确定状态

让错误正文独立且安全

坏掉的样子

快速验证

延伸阅读

来源

Sitemap 帮助爬虫发现页面

从发布清单生成

坏掉的样子

快速验证

来源

Canonical URL 标识首选表示

先确定身份，再写标签

坏掉的样子

快速验证

延伸阅读

来源

Well-known 路径提供的是发现约定

按具体后缀的规范实现

坏掉的样子

快速验证

来源

字符集告诉阅读者这段字节该如何解码成字符

先由格式确定规则

坏掉的样子

快速验证

延伸阅读

来源

CORS 预检取决于请求形态

把每项权限放到对应阶段理解