跳到正文
零到全栈 · 卷 0 · 学习地图

全景地图:一次请求的旅程

本合集目录
本章目录

单册说明:本文件是卷 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 把图变成工具:三步定位法

以后遇到任何"打不开/不对",按这个顺序走,不要跳步:

  1. 先确认是不是网络层:curl -I https://你的域名 能拿到状态码,说明 1–4 段通;拿不到,回第 1–3 段。
  2. 再看是谁返回的错误:响应头里有 Server: nginx 且状态 502,是 Nginx 的问题;状态 500 且响应体是你的应用格式,是应用的问题。
  3. 最后看应用内部:日志里按时间戳找那条请求,看是校验失败、数据库失败、还是第三方调用超时。

这三步的价值在于它把"我感觉是 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 段的衔接问题。

下一步

图有了,接下来把"机器"准备好:三个系统各自怎么装、要注册哪几个账号、目录怎么放。这一章是全卷唯一必须按顺序做完的部分。

→ 卷0-04-课前准备-机器工具账号.md