跳到正文
零到全栈 · 卷 7 · 上线与运维

日志、埋点与流量

本合集目录
本章目录

单册说明:本文件是卷 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 可以伪造,误封真实用户成本很高。合理的顺序是:

  1. 先观察一周,把可疑 UA 和路径列出来;
  2. 对敏感路径(/.env、/.git)直接返回 404,不给探测反馈;
  3. 对高频 IP 做限流(limit_req),而不是封禁;
  4. 只有在确认是恶意且持续的情况下才封,并设过期时间。

顺带说一句:/.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 这类指标数据库里根本没有,只能从日志算,允许有误差。判断标准是:这个数字需不需要精确到个位——需要就查库,只需要趋势就看日志。

下一步

站点能访问、有证书、日志可读。最后一章补上"出事时能救回来"的能力:备份、健康检查、一条命令回滚。

→ 卷7-08-备份监控与回滚.md