日志、埋点与流量
本合集目录
本章目录
单册说明:本文件是卷 7 的第 7 章,可独立阅读。前置:第 4 章(Nginx)、第 6 章(HTTPS)。本章把"一行看不出信息的日志"改成八个字段的结构化记录,配好轮转,并做一个不依赖第三方的统计接口。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 7 · 上线与运维(第 7 / 8 章) |
| 前置章节 | 7.4 Nginx 反向代理;7.6 HTTPS 与证书 |
| 本章产出 | 一份 JSON 格式的 log_format + 一份 logrotate 配置 + 一个 /api/stats 接口 |
| 对应代码 | /etc/nginx/conf.d/dudao-log.conf、/etc/logrotate.d/dudao、backend/routers/stats.py |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 日志每行是合法 JSON,含八个字段;手动 logrotate -f 之后新请求写进新文件 |
7.7.1 一句话结论:日志的价值不在"记下来",在"能回答一个具体问题"
先看两个现场。
现场一:凌晨三点,磁盘写满。你早上看到的是:
sqlite3.OperationalError: database or disk is full
Nginx 的错误日志里:
2026/11/17 03:12:44 [alert] 1203#1203: *8821 write() failed (28: No space left on device)
/var/log/nginx/access.log 有 6.4 GB,从上线那天起就没轮转过。SQLite 因为写不进 WAL 文件,所有写操作失败,用户存不了摘录。
现场二:你想知道"昨天有多少人访问",打开 access.log:
127.0.0.1 - - [16/Nov/2026:22:10:03 +0800] "GET /api/notes HTTP/1.1" 200 482 "-" "Mozilla/5.0 ..."
127.0.0.1 - - [16/Nov/2026:22:10:04 +0800] "GET /_next/static/chunk.js HTTP/1.1" 200 12044 "-" "Mozilla/5.0 ..."
全是 127.0.0.1。因为这些请求经过 Nginx 转发到后端,后端日志里记的是"上一跳"的地址。真实 IP 早就在 X-Real-IP 里传过来了,只是没人记。
两个现场的共同点是:日志存在,但回答不了问题。 这一章要把它变成能回答问题的东西。
7.7.2 原理与方法
① 一条有用的访问日志,八个字段
| # | 字段 | Nginx 变量 | 用来回答什么 |
|---|---|---|---|
| 1 | 时间(含时区) | $time_iso8601 |
什么时候出的问题,能不能和别的日志对齐 |
| 2 | 真实客户端 IP | $remote_addr(配 realip 后) |
谁在访问,封谁 |
| 3 | 方法 | $request_method |
是读还是写,写操作出问题更严重 |
| 4 | 路径 | $uri |
哪个页面/接口 |
| 5 | 查询串 | $args |
搜索词、分页参数(单独放,便于聚合) |
| 6 | 状态码 | $status |
成功还是失败,谁的错 |
| 7 | 响应字节 | $body_bytes_sent |
是真返回了内容还是空包 |
| 8 | 耗时(秒) | $request_time |
慢在哪 |
| 9 | User-Agent | $http_user_agent |
人还是机器 |
再加两个"有了更好"的:
| 字段 | 变量 | 价值 |
|---|---|---|
| 上游耗时 | $upstream_response_time |
区分"Nginx 慢"还是"应用慢" |
| 请求 ID | $request_id |
把 Nginx 日志和应用日志串起来 |
$request_time 和 $upstream_response_time 的差值是排障的关键:
| 现象 | 含义 |
|---|---|
| 两者都大 | 应用慢(慢查询、死锁、外部调用) |
request_time 大、upstream 小 |
客户端慢,或响应体大、网络慢 |
upstream 是 - |
请求没转发,被 Nginx 自己处理了(静态文件或 404) |
最后一行特别有用:看到 - 就知道这个请求根本没进 Python,不用去翻应用日志。
② 真实 IP:X-Forwarded-For 里该信哪一段
先把一个误解拆掉:X-Forwarded-For 不是一个 IP,是一串,格式是 客户端, 代理1, 代理2。而且最左边那一段是客户端自己写的,可以随便伪造。
X-Forwarded-For: 1.2.3.4, 203.0.113.77
攻击者可以随手发 X-Forwarded-For: 8.8.8.8,你的日志里就出现了一个谷歌的 IP。如果你按日志里的 IP 做封禁,封的是别人。
正确的做法取决于你的部署形态:
| 形态 | $remote_addr 是什么 |
该信什么 |
|---|---|---|
| 客户端 → Nginx → 应用 | 真实客户端 IP | 直接用 $remote_addr,不要看 XFF |
| 客户端 → CDN → Nginx → 应用 | CDN 节点 IP | 用 realip 模块,从 XFF 取 |
| 客户端 → 多层代理 → Nginx | 最后一跳代理 IP | 同上,但要设对信任层级 |
本书是第一种形态:Nginx 直接对外,所以 $remote_addr 就是真实 IP,X-Real-IP 只是传给后端用的。这时候去读 XFF 反而会引入伪造风险。
如果以后加了 CDN,正确写法是:
set_real_ip_from 198.51.100.0/24; # 只信任 CDN 的出口网段
real_ip_header X-Forwarded-For;
real_ip_recursive on;
三行的意思:只有来自这些网段的请求,才允许改写 $remote_addr;改写的依据是 XFF,从右往左找到第一个不在信任列表里的地址。
关键是 set_real_ip_from 必须精确到 CDN 的网段。 写成 0.0.0.0/0 等于告诉 Nginx"任何人说的 XFF 我都信",那就回到了"客户端随便伪造"的状态。
③ logrotate:为什么必须让 Nginx 重新打开文件
轮转的动作是:把 access.log 改名成 access.log.1,再创建一个新的空 access.log。
问题在于:Nginx 进程手里握着的是旧文件的句柄(fd),不是文件名。 改名不影响句柄,它会继续往 access.log.1 里写。于是你看到"新文件一直是空的,旧文件还在长"。
解决办法是给 Nginx 发 USR1 信号,它会重新打开日志文件:
postrotate
[ -f /run/nginx.pid ] && kill -USR1 $(cat /run/nginx.pid)
endscript
postrotate 在轮转完成后执行,sharedscripts 保证多个日志文件只执行一次(不然发好几次信号)。
配置里几个常被忽略的项:
| 指令 | 作用 | 不写的后果 |
|---|---|---|
daily |
每天轮转 | 默认按周,日志可能太大 |
rotate 14 |
保留 14 份 | 无限保留,迟早写满 |
size 50M |
超过 50 MB 也轮转 | 一天写 2 GB 时,等到第二天已经晚了 |
compress |
压缩历史文件 | 磁盘占用大 10 倍 |
delaycompress |
最近一份不压缩 | 有些程序还在写,压了会报错 |
missingok |
文件不存在不报错 | 凌晨报错邮件 |
notifempty |
空文件不轮转 | 一堆空文件 |
create 0640 www-data adm |
新文件的属主和权限 | 新文件属主变成 root,Nginx 写不进去 |
create 那行最容易被漏。轮转后 Nginx 以 www-data 身份重开文件,如果新文件是 root:root 644,它打不开,直接进错误日志:
nginx: [alert] could not open error log file: open() "/var/log/nginx/error.log" failed (13: Permission denied)
④ 磁盘写满的完整事故链
它不是一步到位的,是一串连锁反应:
日志无限增长
→ 磁盘 100%
→ SQLite 无法创建 -wal/-shm 文件
→ sqlite3.OperationalError: database or disk is full
→ 写接口全部 500
→ 应用日志开始报错,日志增长更快
→ Nginx 无法写 access.log
→ systemd 反复重启应用(每次都失败)
→ 你 SSH 上去,连 bash 都提示 "No space left on device"
到了最后一步,连 vim 都存不了文件。所以预防必须在链条的前两环,不能等到报警。
三条命令覆盖日常检查:
df -h /
du -sh /var/log/* 2>/dev/null | sort -h | tail -n 5
journalctl --disk-usage
第二条能立刻指出是谁在吃磁盘。第三条看 journald 占了多少——它默认可能没有上限。
⑤ 最小可用埋点:三个事件就够
不要一上来就上第三方分析平台。个人站需要的只有三类事件:
| 事件 | 记什么 | 回答什么问题 |
|---|---|---|
| 页面访问 | 路径、时间、是否登录 | 哪些内容有人看 |
| 关键动作 | 注册、登录、新建摘录、删除 | 功能有没有人用 |
| 错误 | 状态码、异常类型、请求 ID | 出了什么问题,影响多少人 |
「读到」的做法是:访问日志交给 Nginx,业务动作和错误交给应用,两者都往 stdout 写,由 journald 收。 不引入任何第三方 SDK。
一个必须接受的局限:日志不适合做精确统计。 它会被轮转删掉、会被采样、会在磁盘满时丢失。所以:
| 需求 | 用什么 |
|---|---|
| "今天有多少人访问" | 日志,允许有误差 |
| "一共有多少条摘录" | 数据库,必须精确 |
| "哪个标签最多" | 数据库聚合 |
/api/stats 就建在数据库上,因为那些数字要准;PV/UV 这类用一条 shell 命令从日志里算,不进接口。
⑥ 机器人流量:先识别,别急着封
| 特征 | 例子 | 可信度 |
|---|---|---|
UA 含 bot / spider / crawl |
Googlebot/2.1 |
高,但可能是伪造 |
| UA 是命令行工具 | curl/8.5.0、python-requests/2.32 |
高,正常用户不会这样 |
UA 为空或 - |
— | 高,扫描器常见 |
| 只请求敏感路径 | /.env、/.git/config、/wp-login.php |
极高 |
| 请求频率恒定 | 每秒一次,从不加载 CSS/JS | 高 |
| 从不请求静态资源 | 只打 HTML 和接口 | 中,可能是预加载 |
前四条基本可以确定是机器。但不要根据 UA 直接封 IP:UA 可以伪造,误封真实用户成本很高。合理的顺序是:
- 先观察一周,把可疑 UA 和路径列出来;
- 对敏感路径(
/.env、/.git)直接返回 404,不给探测反馈; - 对高频 IP 做限流(
limit_req),而不是封禁; - 只有在确认是恶意且持续的情况下才封,并设过期时间。
顺带说一句:/.env 和 /.git/config 被扫是常态,几乎每个公网站点每天都会遇到。只要你没把它们放到 web/ 目录里,就没事。 这也是 7.2 坚持"代码和产物分开"的又一个理由。
7.7.3 动手:自定义格式、轮转演练、统计接口
第一步:写 log_format
log_format 只能出现在 http 块里,所以不能写在 sites-available 的 server 块内。Ubuntu 的 Nginx 会自动 include /etc/nginx/conf.d/*.conf,放这里正好:
sudo tee /etc/nginx/conf.d/dudao-log.conf >/dev/null <<'EOF'
log_format dudao_json escape=json
'{"ts":"$time_iso8601",'
'"ip":"$remote_addr",'
'"method":"$request_method",'
'"uri":"$uri",'
'"args":"$args",'
'"status":$status,'
'"bytes":$body_bytes_sent,'
'"rt":$request_time,'
'"urt":"$upstream_response_time",'
'"ua":"$http_user_agent",'
'"rid":"$request_id"}';
EOF
escape=json 是关键:UA 里常有引号和反斜杠,不转义会让整行 JSON 解析失败。加上它之后,所有变量值都会被正确转义。
status 和 bytes、rt 故意不加引号,让它们是 JSON 数字,便于后续用 jq 过滤和求和。
第二步:让站点用这个格式
编辑 /etc/nginx/sites-available/dudao 的 443 段,把 access_log 那行改成:
access_log /var/log/nginx/dudao.access.log dudao_json;
sudo nginx -t && sudo systemctl reload nginx
第三步:验证日志是合法 JSON
curl -s -o /dev/null https://dudao.example.com/
sudo tail -n 1 /var/log/nginx/dudao.access.log
预期:
{"ts":"2026-11-17T04:40:12+08:00","ip":"203.0.113.77","method":"GET","uri":"/","args":"","status":200,"bytes":2888,"rt":0.042,"urt":"0.038","ua":"curl/8.5.0","rid":"a3f1c9d2e4b6478a9c0d1e2f3a4b5c6d"}
用 jq 验一下它真的能解析(没装就先 apt install -y jq):
sudo tail -n 20 /var/log/nginx/dudao.access.log | jq -r 'select(.status >= 500) | "\(.ts) \(.uri) \(.status)"'
能正常输出(或安静地什么都不输出)就说明格式没问题。
第四步:写 logrotate 配置
Ubuntu 自带 /etc/logrotate.d/nginx,管的是系统默认的 access.log。我们的站点日志是单独文件,要单独配:
sudo tee /etc/logrotate.d/dudao >/dev/null <<'EOF'
/var/log/nginx/dudao.*.log {
daily
rotate 14
size 50M
compress
delaycompress
missingok
notifempty
create 0640 www-data adm
sharedscripts
postrotate
[ -f /run/nginx.pid ] && kill -USR1 $(cat /run/nginx.pid)
endscript
}
EOF
注意不要和 /etc/logrotate.d/nginx 里的规则重叠。如果两个文件都匹配同一个路径,logrotate 会报 duplicate log entry。
第五步:演练一次轮转
先看它打算做什么(-d 是 dry-run,不实际执行):
sudo logrotate -d /etc/logrotate.d/dudao
输出里会列出 "rotating pattern"、要执行的动作。确认无误后强制跑一次:
sudo logrotate -f /etc/logrotate.d/dudao
ls -l /var/log/nginx/dudao.*
预期:
-rw-r----- 1 www-data adm 0 Nov 17 04:45 /var/log/nginx/dudao.access.log
-rw-r----- 1 www-data adm 18422 Nov 17 04:45 /var/log/nginx/dudao.access.log.1
新文件是 0 字节、属主 www-data。再发一个请求:
curl -s -o /dev/null https://dudao.example.com/
sudo wc -l /var/log/nginx/dudao.access.log /var/log/nginx/dudao.access.log.1
新文件应该有 1 行,旧文件行数不变。如果新文件还是 0 行、旧文件继续增长,就是 postrotate 没生效——见坑 3。
第六步:写 /api/stats
新建 backend/routers/stats.py:
from fastapi import APIRouter, Depends
from datetime import date
from db import get_conn
router = APIRouter(prefix="/api", tags=["stats"])
@router.get("/stats")
def stats():
with get_conn() as conn:
one = conn.execute(
"SELECT COUNT(*) AS notes, "
" COUNT(DISTINCT user_id) AS authors "
"FROM notes"
).fetchone()
today = conn.execute(
"SELECT COUNT(*) FROM notes WHERE date(created_at) = ?",
(date.today().isoformat(),),
).fetchone()[0]
tags = conn.execute(
"SELECT t.name, COUNT(*) AS n "
"FROM tags t JOIN note_tags nt ON nt.tag_id = t.id "
"GROUP BY t.id ORDER BY n DESC LIMIT 5"
).fetchall()
return {
"notes_total": one["notes"],
"notes_today": today,
"authors_total": one["authors"],
"top_tags": [{"name": r["name"], "count": r["n"]} for r in tags],
}
然后在 main.py 里注册:
from routers import stats as stats_router
app.include_router(stats_router.router)
三个设计取舍:
| 取舍 | 理由 |
|---|---|
| 只做聚合,不返回明细 | 统计接口不该把用户数据带出来 |
date(created_at) 用 SQLite 函数 |
避免在 Python 里遍历全部记录 |
LIMIT 5 |
标签可能有几百个,前端只展示前几名 |
验证:
curl -s https://dudao.example.com/api/stats | jq
预期:
{
"notes_total": 128,
"notes_today": 3,
"authors_total": 4,
"top_tags": [
{ "name": "js", "count": 41 },
{ "name": "css", "count": 27 }
]
}
第七步:用一条命令算 PV/UV
日志在 /var/log/nginx/,属组是 adm。把你自己加进 adm 组就能读,不必每次 sudo:
sudo usermod -aG adm "$USER"
# 重新登录后生效
今天的 PV 和 UV 一次算出来(用 jq 按日期和资源类型过滤,再交给 awk 去重):
TODAY=$(date +%F)
sudo cat /var/log/nginx/dudao.access.log \
| jq -r --arg d "$TODAY" '
select(.ts | startswith($d))
| select(.uri | test("\\.(css|js|png|jpg|svg|woff2)$") | not)
| [.uri, .ip] | @tsv' \
| awk '{pv++; ip[$2]=1} END {printf "PV=%d UV=%d\n", pv, length(ip)}'
预期形如 PV=342 UV=57。过滤静态资源是必须的:一个页面可能带十几个 CSS/JS 请求,不过滤的话 PV 会被放大十倍,数字毫无意义。
这类命令不必写进系统,放进 notes/ 里随用随抄就行。它们的结果只能当趋势看:日志轮转后历史就没了,被机器人打过也会虚高。
第八步:看清一次真实的流量构成
sudo tail -n 500 /var/log/nginx/dudao.access.log \
| jq -r '.ua' | sort | uniq -c | sort -rn | head -n 10
你大概率会看到几类:正常浏览器、curl、各种 bot,以及一堆空 UA。这一步的收获不是"抓到了谁",而是知道自己站点的噪声水平——一个人站点每天被扫几十次是常态,不值得为它加班。
7.7.4 三个坑
坑 1:日志写满磁盘
症状:
sqlite3.OperationalError: database or disk is full
2026/11/17 03:12:44 [alert] 1203#1203: *8821 write() failed (28: No space left on device)
df -h 显示 Use% 100%。
成因:三种,往往同时存在。
| 成因 | 检查 |
|---|---|
| 访问日志没轮转 | ls -lh /var/log/nginx/ 看单个文件大小 |
| journald 没有上限 | journalctl --disk-usage |
| 备份文件堆在同一块盘 | du -sh /srv/dudao/* |
修法:先止血,再治根。
# 1. 立刻腾出空间(清掉最老的压缩日志,不要删正在写的那个)
sudo find /var/log/nginx -name '*.gz' -mtime +7 -delete
# 2. 限制 journald 总量
sudo sed -i 's/^#SystemMaxUse=.*/SystemMaxUse=500M/' /etc/systemd/journald.conf
sudo systemctl restart systemd-journald
# 3. 配置 logrotate(本章第四步)
sudo logrotate -f /etc/logrotate.d/dudao
不要删当前正在写的 access.log:删掉后 Nginx 仍握着那个 inode,磁盘空间不会释放(df 还是 100%),而 du 又找不到这个文件——这种"空间凭空消失"的现象会让人怀疑人生。要清就直接 truncate -s 0,或者用 logrotate 正常轮转。
坑 2:日志里全是 127.0.0.1
症状:access.log 第一列永远是 127.0.0.1,或者应用日志里 client_ip 全是回环地址。
成因:你在看应用的日志,而应用看到的"上一跳"就是 Nginx。真实 IP 在 X-Real-IP 头里,但:
| 原因 | 检查 |
|---|---|
Nginx 没配 proxy_set_header X-Real-IP |
nginx -T | grep X-Real-IP |
| 应用没读这个头 | 看代码里有没有 request.headers["x-real-ip"] |
| 看错了文件 | 应用日志 vs Nginx 日志 |
修法:分两层处理。
Nginx 这一层,确保转发头在(7.4 已配)。应用这一层,让 uvicorn 信任代理头(7.3 的 --proxy-headers --forwarded-allow-ips=127.0.0.1),然后:
def client_ip(request: Request) -> str:
forwarded = request.headers.get("x-real-ip")
if forwarded:
return forwarded.strip()
return request.client.host if request.client else "-"
只信 X-Real-IP,不要去解析 X-Forwarded-For 的第一段。 那个值客户端可以随便写。
加 CDN 之后,记得按 7.7.2 第 ② 节上 realip 模块,并把 set_real_ip_from 限定到 CDN 网段。
坑 3:轮转之后日志还在长旧文件
症状:logrotate -f 执行成功,dudao.access.log 是 0 字节,但 dudao.access.log.1 一直在变大,新请求全写进了旧文件。
成因:postrotate 没执行,或者执行了但没发对信号。Nginx 握着旧 fd,改名对它没影响。
修法:先手工验证信号有效:
sudo kill -USR1 $(cat /run/nginx.pid)
ls -l /proc/$(cat /run/nginx.pid)/fd | grep access
发完信号后,Nginx 会重新打开日志文件,新请求进新文件。
如果手工有效但自动无效,检查三处:
| 检查点 | 常见问题 |
|---|---|
postrotate ... endscript 是否包在规则块内 |
括号位置错,脚本被当成新规则 |
sharedscripts 是否写了 |
没写时每个文件触发一次,可能重复发信号 |
测试用的是 -d 还是 -f |
-d 是 dry-run,根本不执行脚本 |
还有一种更隐蔽的:/run/nginx.pid 不存在(Nginx 用了别的 pid 路径),[ -f ... ] 判断为假,脚本静默跳过。用 nginx -t 的输出或 ps 确认 pid 文件位置。
| 坑 | 关键现象 | 一句话修法 |
|---|---|---|
| 磁盘满 | database or disk is full |
清压缩日志、限 journald、配轮转 |
| IP 全 127.0.0.1 | 日志第一列是回环 | 配 X-Real-IP 并让应用读它 |
| 轮转不生效 | 新文件空、旧文件长 | postrotate 发 USR1,先手工验证 |
本章验收
-
tail -n 1的日志行能被jq解析,且含八个必需字段 - 日志里的
ip是真实公网 IP,不是127.0.0.1 -
logrotate -f后新文件属主是www-data、权限640,新请求写进新文件 -
curl https://你的域名/api/stats返回聚合数据,且不含任何用户隐私字段 - 能用
jq筛出最近 20 条 5xx,并说出它们的uri - 能说出
$request_time和$upstream_response_time差值代表什么
自测
Q1:为什么不能直接用 X-Forwarded-For 的最左边一段作为真实 IP?
看答案
因为 XFF 是客户端可以自己设置的请求头。攻击者发一个 X-Forwarded-For: 8.8.8.8,你的日志里就出现 8.8.8.8,如果据此封禁会误伤无关的人,如果据此做限流会被轻易绕过。正确做法是:单层 Nginx 直接用 $remote_addr;有 CDN 时用 realip 模块,并用 set_real_ip_from 限定只信任 CDN 网段,从右往左找第一个非信任地址。Q2:logrotate 之后为什么必须给 Nginx 发信号?不发会怎样?
看答案
因为进程持有的是打开的文件句柄,不是文件名。改名不会改变句柄指向,Nginx 会继续往已改名的 access.log.1 里写,新建的 access.log 一直是空的。USR1 信号让 Nginx 关闭并重新打开日志文件,之后才写到新文件。这个现象看起来像"日志丢了",实际是写到了另一个文件名下。Q3:为什么统计接口应该查数据库,而不是解析访问日志?
看答案
两者精度不同。日志会被轮转删除、可能被采样、磁盘满时会丢失,用它算"一共多少条摘录"必然不准;数据库是唯一事实来源。反过来,PV/UV 这类指标数据库里根本没有,只能从日志算,允许有误差。判断标准是:这个数字需不需要精确到个位——需要就查库,只需要趋势就看日志。下一步
站点能访问、有证书、日志可读。最后一章补上"出事时能救回来"的能力:备份、健康检查、一条命令回滚。