全景地图:一次请求的旅程
本合集目录
本章目录
单册说明:本文件是卷 0 的第 3 章,可独立阅读。前置:第 2 章(四层能力)。本章走一遍"输入网址 → 看到页面"的完整链路,给你一张能用来定位故障的图。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 0 · 起点与路线(第 3 / 5 章) |
| 前置章节 | 0.2 全栈到底指什么 |
| 本章产出 | 一张手绘的请求旅程图 + 一张"报错→哪一层"对照表 + 一次真实跑通的请求 |
| 对应代码 | code/serve.py、code/index.html(可直接运行,见 0.3.6) |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 拿到任意一个报错,能说出该去哪个面板/日志里找 |
0.3.1 一句话结论:一次访问 = 六个动作,每个动作都可能失败
你在地址栏敲下 https://dudao.example.com,到看见页面,中间发生了六件事。这六件事的每一件都可能坏,而坏的姿势各不相同——这就是为什么"打不开"这三个字毫无信息量。
下面这张表是全章的地图,后面逐段展开:
| # | 动作 | 谁在做 | 失败时的典型表现 | 去哪查 |
|---|---|---|---|---|
| 1 | 域名解析成 IP | DNS 服务器 | 浏览器转圈后"无法访问此网站",ping 提示找不到主机 |
nslookup / dig |
| 2 | 建立 TCP 连接 | 浏览器 ↔ 服务器 | 连接超时;curl 卡住不动 |
telnet IP 端口 |
| 3 | TLS 握手(https) | 浏览器 ↔ 服务器 | "您的连接不是私密连接"、证书过期 | 浏览器证书面板、curl -v |
| 4 | 请求交给后端应用 | Nginx → 应用进程 | 502 Bad Gateway、504 超时 | Nginx 与后端日志 |
| 5 | 应用处理:查数据 | 应用 ↔ 数据库 | 500,日志里出现连接错误或锁等待 | 应用日志 |
| 6 | 浏览器渲染 | 浏览器 | 页面骨架在,但空白/错位/点了没反应 | F12 的 Console 与 Network |
记住这张表,比记住任何框架 API 都有用。 卷 7 的所有排查,都是在这六行里挑一行。
0.3.2 第 1–3 段:先把话说上
① DNS:把名字翻译成地址
服务器只认 IP(一串数字),人只认域名。DNS 就是中间那个翻译。它是一层层问出来的:
| 顺序 | 问谁 | 干什么 |
|---|---|---|
| 1 | 浏览器缓存 / 系统缓存 | 上次问过的还记着吗 |
| 2 | 你路由器或运营商给的递归服务器 | 帮我一路问到底 |
| 3 | 根 → 顶级域(.com)→ 权威服务器 | 逐级指路 |
这里有个初学者必经的坑:改完 DNS 记录不是立刻生效的。因为第 1、2 步都有缓存,TTL 没过完之前,你本地可能一直解析到旧 IP。所以"我明明改了"和"怎么还是旧的"可以同时为真。
② TCP:确认对方真的在听
DNS 给了你 IP,但一台服务器上可能跑着十几个服务。端口就是门牌号:HTTP 默认 80,HTTPS 默认 443,开发时后端常用 8000 或 3000。
| 现象 | 最可能的层 | 先做什么 |
|---|---|---|
Connection refused |
端口没人监听(服务没起,或监听在 127.0.0.1) | ss -lntp 看有没有在听 |
| 一直卡住直到超时 | 防火墙/安全组没放行 | 云控制台看安全组规则 |
| 本机能连、外面连不上 | 只监听了 127.0.0.1 |
改成 0.0.0.0 |
这三行能省掉大量"玄学问题"。尤其第三条:本机看着一切正常,外面死活连不上,九成是监听地址写成了回环。
③ TLS:加密与身份
https 比 http 多了两步:先确认对面是不是真的它(证书),再约定一把只有双方知道的密钥(握手)。这一步失败的表象非常固定:
| 报错 | 含义 |
|---|---|
NET::ERR_CERT_DATE_INVALID |
证书过期(最常见,多半是自动续期没配) |
NET::ERR_CERT_COMMON_NAME_INVALID |
证书上的域名和你访问的不一致 |
ERR_SSL_PROTOCOL_ERROR |
这个端口上跑的不是 HTTPS 服务,或用了不兼容的协议版本 |
卷 7 会亲手配一次证书并做自动续期。现在只需要知道:证书问题只影响第 3 段,不影响你的代码。
0.3.3 第 4–5 段:请求进到"你自己的地盘"
前面三段是"公共基础设施",你只能配置不能改。从第 4 段开始,全都是你的代码。
现代单机部署的分工基本长这样:
浏览器
│ https://域名/api/notes
▼
Nginx(80/443,负责收证书、转发、托管静态文件)
│ proxy_pass http://127.0.0.1:8000
▼
应用进程(FastAPI,负责业务逻辑与校验)
│ SQL
▼
SQLite / 数据库(负责存住)
这张图解释了三件容易搞混的事:
| 疑问 | 答案 |
|---|---|
| "为什么我后端改完没生效?" | 因为请求可能根本没到后端——Nginx 把静态文件直接返回了 |
| "502 是谁报的?" | Nginx 报的。它连不上后端(后端挂了、端口错了、只监听回环) |
| "500 是谁报的?" | 后端报的。Nginx 只是转达,真正的栈信息在后端日志里 |
502 与 500 的区别,是新手和老手的分界线之一: 502 是"门卫找不到里面的人",500 是"里面的人自己崩了"。
0.3.4 第 6 段:浏览器在做什么
后端把 HTML/JSON 送回来,浏览器要干三件事:解析 HTML 建 DOM、下载 CSS/JS/图片、执行 JS。任何一步失败都可能表现为"页面白屏",但原因完全不同:
| 现象 | 先看哪里 | 典型原因 |
|---|---|---|
| 白屏 + Console 有红字 | Console | JS 语法错误、变量未定义 |
| 白屏 + Network 里 JS 是 404 | Network | 构建产物路径错、部署漏了文件 |
| 有骨架但数据不显示 | Network 里接口请求 | 接口 500 / 401 / CORS 被拦 |
| 样式全乱 | Network 里 CSS 状态码 | MIME 类型不对,或缓存了旧文件 |
到这里,第 2 章说的"边界感"就有具体形状了:F12 的 Console 和 Network 两个面板,能把你从"猜"变成"看"。
0.3.5 把图变成工具:三步定位法
以后遇到任何"打不开/不对",按这个顺序走,不要跳步:
- 先确认是不是网络层:
curl -I https://你的域名能拿到状态码,说明 1–4 段通;拿不到,回第 1–3 段。 - 再看是谁返回的错误:响应头里有
Server: nginx且状态 502,是 Nginx 的问题;状态 500 且响应体是你的应用格式,是应用的问题。 - 最后看应用内部:日志里按时间戳找那条请求,看是校验失败、数据库失败、还是第三方调用超时。
这三步的价值在于它把"我感觉是 bug"变成"我确认是第 5 段的问题"。定位一旦落到某一段,剩下的就是查文档。
0.3.6 动手:把第 4–6 段跑一遍
看再多图,不如亲手发一次请求。卷 0 随书带了一个 30 行的静态服务器(code/serve.py),只用 Python 标准库,不需要装任何包。它能把你刚才读到的东西变成终端里的日志。
在两个终端里分别执行(Windows 用 py,macOS/Linux 用 python3):
# 终端 A:起服务
py code/serve.py
# 终端 B:发请求
curl -I http://127.0.0.1:8000/ # 看响应头
curl http://127.0.0.1:8000/missing # 故意访问不存在的路径
终端 A 会打出这样的三行:
00:57:49 127.0.0.1 GET / 200 2888B 177.0ms curl/8.21.0
00:57:49 127.0.0.1 GET /missing 404 383B 0.5ms curl/8.21.0
再用浏览器打开 http://127.0.0.1:8000/,回到终端 A 看——多了一行 UA 是浏览器的请求。这一行就是你刚才那张六段图的全部证据:
| 你看到的 | 说明哪一段通了 |
|---|---|
| 终端里有这一行 | 第 1–2 段通(DNS + TCP 都成了,否则连接根本到不了) |
| 状态码 200 | 第 4–5 段通(服务器处理完并给出了资源) |
| 字节数 2888B | 响应体真的发出去了,不是空回包 |
| 浏览器里页面出来了 | 第 6 段通(HTML 被解析、CSS 被应用、JS 被执行) |
换成 /missing 得 404 |
第 4 段仍然通——404 是"服务器在正常工作但没这个文件",不是网络故障 |
这里要记住一个反直觉的点:404 不代表"连不上"。连不上是超时或 Connection refused,根本没有状态码。只要你能看到一个三位数状态码,就说明请求已经成功抵达服务器——它在第 4 段之后。
最后试一件事:把地址从 127.0.0.1 换成你电脑的局域网 IP(ipconfig / ifconfig 里查),手机连同一个 WiFi 打开它。打不开是正常的——因为服务器只监听了本机回环地址。这就是第 2 段那张表里"本机能连、外面连不上"的第一种成因,卷 1 第 6 章会让你亲手改成 0.0.0.0。
本章验收
- 能默写出六段链路,以及每段失败时的一个典型报错
- 能说清 502 和 500 的区别,以及各自该看哪里
- 能用
curl -I判断一个网址在 1–4 段是否通畅 - 能说出"白屏"的四种可能原因,以及各自去哪个面板确认
自测
Q1:用户说"网站打不开",你在自己电脑上访问却正常。第一批要收集的三条信息是什么?
看答案
① 他的网络与设备(同一 WiFi 还是手机流量,哪个浏览器);② 他看到的准确报错文字或截图;③ 访问时间点。原因是:你能访问说明服务器基本活着,问题多半落在 DNS 缓存、他的网络劫持、或只有特定路径/特定账号才出错。没有这三条信息,猜十次也不中。Q2:curl -I https://域名 返回 200,但浏览器打开是白屏。问题最可能在哪一段?
看答案
在第 6 段。响应 200 说明 1–5 段全通,服务器把 HTML 正常交付了;白屏说明浏览器在解析或执行阶段出了问题——最常见是 JS 报错或静态资源 404,此时要看 Console 和 Network,而不是继续查服务器。Q3:为什么"本机测试一切正常、线上 502"这种问题,往往和代码无关?
看答案
因为 502 是 Nginx 报的,意思是它连不上后端。本机你直接访问的是应用端口,不经过 Nginx,自然正常。线上出 502 的常见原因是:应用没起来、端口和 Nginx 配置不一致、应用只监听了 127.0.0.1 而 Nginx 在容器/另一网络命名空间,或应用启动时因为缺环境变量直接退出。这些都属于第 4 段的衔接问题。下一步
图有了,接下来把"机器"准备好:三个系统各自怎么装、要注册哪几个账号、目录怎么放。这一章是全卷唯一必须按顺序做完的部分。