告警邮件：生产服务器根分区用到 81%（30G/40G，超过 80% 红线）。第一反应是查 docker system df——它显示 images 一栏 RECLAIMABLE 100% (7)，看起来删掉镜像就能回血；但这 7 个镜像全在运行，真按提示 docker image prune -a 就是生产事故。

在开发 AI运营 时遇到此问题——基于大语言模型的智能分析平台，自动洞察市场趋势、用户行为与销售数据；出问题的是跑它 Airflow 数据管道的 Docker 服务器。

TL;DR​

磁盘超红线时别信 docker system df 的 RECLAIMABLE——它是「无容器引用空间」的估算口径，active 镜像照样标 100%。正确姿势：sudo du -xh -d1 / 逐层找大头。这次的三大隐形消耗都不在业务数据里：容器可写层里无限累积的 task 日志（Dockerfile 没给日志配卷）、包管理器缓存（npm + pnpm 共 ~4G）、只增不删的备份脚本（每次全量克隆从不清理）。对应清理：缓存直删、可写层 force-recreate 回收、备份脚本加 TTL 剪枝——81% 回落到 64%。

问题现象​

$ df -h /
Filesystem      Size  Used Use% Mounted on
/dev/vda1        40G   30G  81% /

$ docker system df
TYPE        TOTAL   ACTIVE   SIZE     RECLAIMABLE
Images      7       7        4.2GB    100% (7)    ← 全是运行中镜像
Containers  5       5        810MB    0%

按 docker system df 的提示去做文章（清理镜像）无从下手——RECLAIMABLE 100% 但 ACTIVE 也是 7/7。真正的空间去哪了，docker system df 完全没体现：

sudo du -xh -d1 / | sort -rh | head
# 部分输出：
# 2.7G    /root/.npm              ← npm 缓存
# 1.1G    /root/.local/share/pnpm ← pnpm store
# 857M    /root/backups-git       ← 备份工作区，只增不删
# （overlay2 内藏：airflow scheduler 可写层 468M + dag-processor 257M）

根因​

三类消耗在「业务数据」视角里全部隐形。

容器可写层吃日志。 Airflow 的 task 日志写在容器内部、没挂外置卷——scheduler 可写层 468M、dag-processor 257M，约两周累积 780M，随时间单调增长。镜像层不变，变的都是可写层；docker system df 把它归在 Containers 的 SIZE 里，混在 810M 的总数里毫无存在感。

包管理器缓存只进不出。 频繁部署/构建的服务器上，~/.npm（2.7G）和 pnpm store（1.1G）持续累积，没有人会主动去清。

备份脚本只增不删。 备份脚本每次全量克隆仓库工作区推 GitHub，旧的克隆目录从不剪枝——857M 里大部分是历史重复。更隐蔽的是孤本：某些备份目录对应的分支从未推送成功，直接删有风险，需要先核对。

而 docker system df 的 RECLAIMABLE 是按「没有运行容器引用」估算的统计口径，active 镜像也可能显示 100% reclaimable（本次 7/7 全如此）——它是误报来源，不是清理依据。

解决方案​

步骤 1：du 逐层定位，先看再删​

sudo du -xh -d1 / | sort -rh | head        # 根分区逐层
sudo du -xh -d1 /var/lib/docker | sort -rh | head   # Docker 目录下钻
docker ps -as --format "table {{.Names}}\t{{.Size}}"  # 各容器可写层

du -x 不跨文件系统，避开 proc/sys 噪音和 overlay 混淆；docker ps -as 的 SIZE 列直接暴露每个容器的可写层大小——这是定位「日志写进容器」类问题的关键一条。

步骤 2：缓存直删​

npm cache clean --force        # 或直接 rm -rf ~/.npm/_cacache
pnpm store prune               # 只清未引用的包

缓存类共回收 ~5.1G，无风险、可随时重下。

步骤 3：可写层 force-recreate 回收​

docker compose up -d --force-recreate   # 可写层随旧容器删除而回收

本次回收 ~780M。两个前提：选低峰期（服务会重启）；容器内还有用要先捞出来——比如 docker cp 把 task 日志拷出，否则随容器一起没了。

步骤 4：备份脚本加 TTL，防复发​

# 备份目录保留 7 天，超过自动剪
find /root/backups-git -maxdepth 1 -type d -mtime +7 -exec rm -rf {} +

把剪枝加进备份脚本尾部（本例 github-backup-push.sh 已部署）；删除前核对未推送的孤本分支（git ls-remote 对比），确认无独有提交再删——本次 325M 孤本经确认后清理。

清理完成后：81% → 64%，缓存/剪枝/可写层三处合计回收 ~6.7G。

常见问题​

docker system df 的 RECLAIMABLE 显示 100% 能直接删吗？​

不能。RECLAIMABLE 是「当前无容器引用」空间的估算口径，运行中的 active 镜像也可能被标 100% reclaimable——实测 7 个镜像全在用仍显示如此。它回答的是「理论上有多少未被引用」，不回答「能不能删」。动手前用 du -xh -d1 和 docker ps -as 实测定位。

docker ps 的 SIZE 和 docker system df 的 SIZE 有什么区别？​

docker ps -as 的 SIZE 是单个容器可写层的大小；docker system df 是镜像/容器/卷/缓存的分类汇总。容器内日志无限累积只体现在可写层（docker ps -as 能看到），不会体现在任何 image size 上——这就是「镜像看起来不大、磁盘却在涨」的原因。

Docker 服务器磁盘满了怎么清理？​

分三类：包管理缓存直删（npm cache clean --force、pnpm store prune），无风险；容器可写层用 docker compose up -d --force-recreate 回收（会重启服务，日志先备份）；备份、日志、克隆目录这类加 TTL 定期剪枝防复发。任何删除动作前，先用 du -xh -d1 / 确认大头位置。

浏览器扩展的「人群资产」采集功能升级后，客服收到反馈：部分用户月中点开人群资产提示「已是最新」，数据却停留在月初——没升级的旧版扩展不再采集了，要到下个月 1 日才自己恢复。

在开发 电商数据采集工具 时遇到此问题——一站式电商运营解决方案，从数据采集到智能分析；采集判定标志由服务端下发，新旧版本扩展共用同一张服务端表。

TL;DR​

新版本给服务端已有的布尔标志 is_current_month 赋了新语义（当月采集窗口已覆盖），未升级的旧版本按旧含义把它读成「数据已是最新」，幂等判断被短路 → 月中停止采集。这不是要修的 bug，而是 version skew（版本偏差）：同一字段、两种解读。影响有自然自愈边界（次月标志翻 false）；处置 = 提醒升级 + 服务端 upsert 幂等免回滚；预防 = 语义变更必须换新字段。

问题现象​

新版扩展采集：写入当月行，is_current_month = true

旧版扩展续采：读到当月行 → 命中「up-to-date」判定 → 中止采集
用户视角：月中点「人群资产」→ 提示已是最新，数据停在月初
次月 1 日：is_current_month 翻 false → 旧版恢复采集（自愈）

诡异之处在于：服务端数据完全正确、新版扩展工作正常、旧版扩展代码一行没改——出问题的只是「旧版读到新版写的行」。

根因​

经典的 version skew。标志的名字没变，含义变了：新版本的语义是「当月窗口已覆盖」，旧版本按它自己的历史语义把同一行解读成「数据已最新」，于是按设计正确的幂等判断（已最新 → 不重复采集）短路了整个采集。判断逻辑双方都没错，错的是让两种语义共用一个字段。

浏览器扩展（以及一切客户端）的版本分布不受服务端控制：发布新版后，新旧版本并存是以周计的常态。任何「服务端字段含义」的调整，读方都包括所有历史版本——这和 feature flag 的经典教训同构：复用旧 flag 承载新含义，读方按旧含义行动。

解决方案​

当期处置：提醒升级 + 幂等免回滚​

发布含新采集逻辑的版本时，明确提醒用户升级——旧版本在当月内不会自己恢复。服务端与数据无需回滚：采集写入是 upsert 幂等，新旧版本交错写入不产生脏数据，次月标志翻转后自动对齐。

长期预防：语义变更换新字段​

把「窗口语义」从布尔标志迁移到带明确窗口的新字段，旧客户端不认识新字段就不会误读：

// 反例：复用旧标志承载新语义
{ "is_current_month": true }

// 正解：新语义用新字段，窗口显式、可比较
{ "collected_window": "2026-08", "source_version": "2.3.0" }

幂等判断键与业务语义从此解耦：旧版按旧字段判断、新版按新字段判断，互不越界。

设计原则：给每个标志找自愈边界​

标志优先绑定自然时间边界（月、天）而不是「最新」这种绝对语义。本例月翻边界把最坏影响锁定在一个月内；如果没有这种边界，skew 的影响是永久的，只能靠发版修复。

常见问题​

feature flag 的最佳实践有哪些？​

一个标志只承载一种语义；需要新语义时新增字段而不是复用旧标志；标志绑定明确的时间窗口或版本号；改语义前枚举所有读方（尤其未升级的旧客户端），确认它们不会把新值按旧含义解读。本例的停采就是复用旧标志的直接后果。

服务端字段如何做到向后兼容？​

只增不改：已有字段的含义、类型、判定行为保持稳定，新语义用新字段表达，旧客户端读到不认识的字段应当安全忽略。字段名字没变但含义变了，对所有存量读方来说就是一次破坏性变更。

旧版本客户端读到新语义数据怎么办？​

三步：把影响限定在有自愈边界的时间窗口内（如自然月翻转后自动恢复）；发布新版本时主动提醒升级，缩短并存期；服务端写入保持 upsert 幂等，让新旧版本的交错写入可以安全混合，不回滚、不清洗。

生产环境首跑一个 LLM 批量校验任务，日志一片绿、状态成功——但检查输出发现 2449 个待校验对象全部标成了降级标记，实际 LLM 调用次数为零。「语义校验默认开启」的功能，等于一次都没开过。

在开发 AI运营 时遇到此问题——基于大语言模型的智能分析平台，自动洞察市场趋势、用户行为与销售数据；这个校验任务跑在其数据管道的标题优化环节。

TL;DR​

容量门控按「预计量 ≤ 上限」做全有全无判断：试设的 cap 是 400，生产实际是 2449 个词×商品对，超限 → 整批降级、零 LLM 调用，且任务状态照样是成功。教训两条：容量上限必须用生产实测规模校准；超限降级应按单位粒度（分组/排队/截断）进行，并让「fallback 率 100%」这种异常可被观测。

问题现象​

任务的 Layer2 是 LLM 语义校验，入口有一个容量门控：

def semantic_validate(pairs, cap=400):
    if len(pairs) > cap:
        # 超限：整批降级，一次 LLM 都不调
        return [mark_overflow(p) for p in pairs]
    return [llm_validate(p) for p in pairs]

生产首跑结果：

待校验词×商品对：2449/2449 全部 语义校验方式='overflow'
LLM 实际调用：0 次
任务状态：success（无任何报错）

如果只看「跑完没有」，一切正常；只有检查输出列的分布，才发现功能整体失效。

根因​

两层问题叠加。第一层是数值：cap 试设 400，而生产规模是 60 个市场词×同类目商品 + 50 个本店词×商品、共 92 个商品，对数直接到 2449——预估和实测差了一个数量级。第二层是结构：门控是全有全无，超限即整批降级。「这是一个容量约束」的初衷，实际效果是「超限 = 功能整体关闭」，而且降级发生在数据列里、不抛错不打日志，完全静默。

这类「看起来成功、实际没干活」的静默失败和 DeepSeek thinking 吃满输出预算导致空回复静默兜底是同一个家族：错误被兜底逻辑消化，表面上永远 success。

解决方案​

步骤 1：用生产实测规模校准 cap​

上线前先统计真实待处理量，别用拍脑袋的预估值：

# dry-run：只统计规模，不产生 LLM 调用
python -c "from pipeline import build_pairs; print(len(build_pairs(shop='prod')))"

实测 2449 → cap 设 3000（约 1.2~2 倍余量），同时确认超大店铺超出时仍有降级路径，不会撞墙。

步骤 2：把调用粒度从「总量」改为「分组」​

按商品分组调用，让调用次数随商品数线性增长，而不是随 词数×商品数 的乘积暴涨：

def semantic_validate(pairs, cap):
    groups = group_by_product(pairs)          # 92 商品 → ~92 次调用/轮
    results = []
    for g in groups:
        if within_budget(g, cap):             # 按组判断，不整批放弃
            results.extend(llm_validate(g))
        else:
            log.warning("capacity gate: group degraded",
                        extra={"size": len(g), "cap": cap})
            results.extend([mark_overflow(p) for p in g])
    return results

本例校准后第三跑实测 2449/2449 全部走 LLM 校验；更大的店铺超出时按组降级，不再一损俱损。

步骤 3：让降级可观测​

给降级路径埋点，并对异常比例告警（如 fallback 率 > 50%）。降级是安全网，不是掩体——它应该被看见，而不是替你掩盖超限。

常见问题​

LLM 管道里的 fallback 机制应该怎么设计？​

降级粒度尽量小——按条或按组降级，而不是整批放弃；降级动作必须留痕（标记列、日志、指标）并配置告警。全有全无式门控一旦触发等于整个功能关闭，只适合成本硬上限场景，且要显式报警。

LLM 批量任务的容量上限怎么定？​

不能拍脑袋。先在生产规模或等比样本上跑一次 dry-run 统计实际待处理量，上限设为实测值的 1.5~2 倍，并随业务规模增长定期复核。预估与实测差一个数量级，是这类事故的标配。

怎么发现 LLM 任务被静默降级了？​

任务状态往往仍是成功，必须检查输出：统计降级标记列的占比、核对实际 LLM 调用次数是否与预期一致。fallback 率异常（尤其 100%）应配置告警，把静默失败变成显式信号。

在一次前后端同仓的多包项目部署时，部署日志里 npm audit 输出 3 个 high 漏洞，顺着日志把它记到了后端名下——修完才确认这 3 个 high 全在前端包树里，后端从始至终是另一组 moderate。

在开发 AI运营 时遇到此问题——基于大语言模型的智能分析平台，自动洞察市场趋势、用户行为与销售数据；前端在仓库根目录、后端在 server/ 目录，同仓多包分开部署。

TL;DR​

npm audit 的摘要行只有数量、不带路径；部署流顺序执行多个目录的 npm install 时输出串联在一起，摘要无法区分归属。解法：用每棵包树的唯一指纹——audited N packages 的 N——先对号入座，再用 package.json 的 overrides 钉住有漏洞的传递依赖，二次部署两端归零。

问题现象​

部署脚本先后在前端（仓库根）和后端（server/）执行 npm install，日志混在同一股输出里：

# 部署流输出（摘要行不带路径）
added 546 packages in 41s
found 3 high severity vulnerabilities

added 372 packages in 24s
found 4 moderate severity vulnerabilities

交接记录把「3 high」归因到了 server/。按这个方向去查后端依赖链，怎么都对不上——server/ 的 audit 无论在本地还是服务器跑，结果都是 4 moderate，从没出现过 high。「部署日志看得见、归属对不上」是混合部署流的常见病，此前踩过的前端部署后线上未更新也是这一类。

根因​

npm audit 摘要行只有「found X vulnerabilities」，不带目录信息；紧挨着的 audited 546 packages 也很少有人下意识当成归属线索。两棵包树规模差异巨大（546 vs 372），这恰好是唯一稳定的指纹。

前端仓库根装的是 Vite + React + Ant Design Pro 全家桶，包树大；@ant-design/pro-components → @ant-design/pro-layout 引用了旧版 path-to-regexp，这正是 3 个 high 的来源。后端 server/ 是 Express + tsx 的精简依赖树，唯一的问题是 tsx → @esbuild-kit/core-utils → 旧版 esbuild 这条 moderate 链。

「报错位置与真因错位」在部署排查里不止一例：另一次是 .env 密码含 # 被 dotenv 静默截断——鉴权 401 把矛头指向凭据，真因却藏在 dotenv 的解析规则里。

解决方案​

步骤 1：按 audited N 对目录​

在本地各目录分别 npm install（或直接读部署日志的 added N packages），记录包树规模：

cd <repo-root> && npm install 2>&1 | tail -2   # added 546 packages ...
cd server      && npm install 2>&1 | tail -2   # added 372 packages ...

部署日志里 found 3 high 紧跟在 added 546 后面 → 前端；4 moderate 跟在 added 372 后面 → 后端。归属定对了，后面才不用白跑。

步骤 2：展开漏洞链​

npm audit                # 看 Path 字段，完整依赖链
npm ls path-to-regexp    # 或反查某个包被谁依赖

前端输出确认链路：@ant-design/pro-components → @ant-design/pro-layout → path-to-regexp（旧版本，3 high）。

步骤 3：用 overrides 钉住传递依赖​

前端仓库根 package.json：

{
  "overrides": {
    "path-to-regexp": "^8.4.2"
  }
}

后端 server/package.json（顺带把 tsx 升到新版）：

{
  "overrides": {
    "@esbuild-kit/core-utils": {
      "esbuild": "^0.25.12"
    }
  }
}

overrides 支持嵌套写法，只影响指定父依赖之下的子依赖版本——比全局覆盖一个包名更精准。

步骤 4：重装验证​

rm -rf node_modules package-lock.json && npm install && npm audit

两端重跑部署后，audit 均为 0 vulnerabilities。

常见问题​

npm audit fix 跑了为什么漏洞还在？​

npm audit fix 只会升级 semver 允许范围内的版本。漏洞出在传递依赖上、且被上层包的版本范围钉死时，fix 改不动它，需要用 package.json 的 overrides 强制钉版本，然后重新 npm install。

怎么定位 npm audit 报的漏洞在哪条依赖链上？​

看 npm audit 完整输出的 Path 字段，它列出从直接依赖到漏洞包的完整链路；也可以用 npm ls <包名> 反查依赖方。摘要行只有数量，不带任何路径信息。

多包项目的 npm audit 结果怎么对应到具体子项目？​

部署日志的摘要不带目录名，按各目录安装时 added N packages / audited N packages 的包树规模对号入座即可。在本地分别对每个目录 npm install 一次，记录各自的 N，之后就能稳定对应。

核对一次生产任务的决策快照时，发现第 5 个阶段的特征数据落在了数组槽 3，而不是设计文档里写的槽 4——下游和抽屉组件按「段号−1」取值，取到的是上一阶段的输出。

在开发 AI运营 时遇到此问题——基于大语言模型的智能分析平台，自动洞察市场趋势、用户行为与销售数据；快照是管道留给前端展示和事后审计的决策依据。

TL;DR​

管道把各阶段（段）输出按执行顺序 push 进快照数组，而 if rows.empty: skip 会把 0 行段整个丢弃，后续所有段前移一位——「段号−1 = 槽位」的静态映射随时被打破，且哪种段为空取决于运行态，槽位每次都可能不同。解法两条路：消费端按行内键名实时认槽（推荐），或写入端给空段保留占位、维持槽位恒定。

问题现象​

装配逻辑长这样：

snapshot = {"features": [], "rule_output": []}
for seg in segments:                    # 段①…段⑤ 顺序执行
    df = execute_sql(seg.sql)
    if not df.empty:                    # 0 行段在这里被丢弃
        snapshot["features"].append(df.to_dict("records"))

设计假设是「段⑤ → 槽 4」。但生产快照核验发现段⑤的特征落在槽 3：

全段有数据：      段①→0  段②→1  段③→2  段④→3  段⑤→4   ✓ 符合假设
段④ 空表被弃：    段①→0  段②→1  段③→2          段⑤→3   ✗ 前移
段③④ 都空：      段①→0  段②→1                  段⑤→2   ✗ 再前移

同一个代码版本，不同店铺/不同权限下快照槽位完全不同——保护词白名单是空表时段④被弃，权限关闭时段③被弃，槽位跟着运行态漂移。

根因​

位置寻址撞上了稀疏装配。 快照数组是运行时把「有输出的段」压缩拼接的产物，本质是个稀疏集合；而下游按「段号−1」硬编码取值，等价于假设「每个段必然产出至少一行」。这个假设在三种常见情形下都会碎：白名单空表、功能开关关闭、业务数据天然为空——0 行是常态而不是异常。

更深一层，if not df.empty 这个判空本身没写错，错的是契约的隐含前提：设计文档写了「槽位 = 段号−1」，却没人把它声明成显式契约。所有按位置消费的下游都在继承一个未被承认、也无人维护的假设。

解决方案​

方案 A（推荐）：消费端按行键名认槽​

让每行数据自带段标识键，消费方在读取时实时解析位置，不做任何静态映射：

def locate_segment(features: list, seg_key: str) -> dict:
    for row in features:
        if seg_key in row:              # 行内自带段标识，按内容寻址
            return row
    raise KeyError(f"segment '{seg_key}' missing in snapshot")

槽位漂移从此无关紧要——找的是「键名长这样的段」，不是「第 N 个元素」。唯一要求是所有消费方统一走这个解析入口（写进 processor docstring 和消费方契约，明确禁止硬编码槽位）。

方案 B：写入端保留空段占位​

如果下游暂时改不动，可以让装配端维持「槽位 = 段号」恒定：

snapshot["features"].append(
    df.to_dict("records") if not df.empty else {"__empty__": True}
)

代价是快照里出现占位对象，所有消费方都得处理它；作为过渡方案可用，长期仍建议收敛到方案 A。

步骤 3：用多种运行态做契约测试​

把「全段有数据 / 单段空 / 多段空」三种运行态做成快照 fixture，断言消费方在三种形态下解析结果一致。只测全满场景，等于没测。

常见问题​

数据工程里怎么处理 schema drift？​

把位置契约换成键名契约：快照、消息、接口按字段名或段标识寻址，而不是数组下标。上游发生未经约定的结构变化（空段被跳过、字段增删）时，按名寻址的下游最多报「找不到」，不会静默拿到错误数据。

schema drift 和 schema evolution 有什么区别？​

Schema evolution 是显式管理的版本演进（加字段、发版本、迁移消费方）；schema drift 是被动发生的漂移——上游一改、下游不知不觉错位。本例的槽位前移就是典型 drift：没人改契约，是数据形态变了。

怎么检测数据管道里这类槽位错位？​

两层：契约测试覆盖多种运行态（全段有数据/单段空/多段空），断言消费方解析一致；生产侧定期抽检快照，核对槽位内容自带的段标识与预期段是否对应。发现「内容与位置对不上」即是 drift。

排查一个监控漏报：server-monitor 按日志级别 warn 过滤告警，但 logs 表里有 38 行告警级日志的 level 写的是 warning——过滤条件一个字符都对不上，这 38 行在监控眼里不存在。

在开发 AI运营 时遇到此问题——基于大语言模型的智能分析平台，自动洞察市场趋势、用户行为与销售数据；server-monitor 是它的告警模块，消费四个服务共写的一张日志表。

TL;DR​

跨语言日志契约定义的级名是小写 warn/fatal，而 Python stdlib 的 record.levelname 是 WARNING/CRITICAL——直写或简单 .lower() 产出的是 warning/critical，按契约过滤永远匹配不上。修复原则两条：在写出口做单点映射（WARNING→warn、CRITICAL/FATAL→fatal），别让每个消费方兼容多种拼写；契约文档写「应该的实现」而不是复制现状——这次漂移能长期存在，正因为契约文档的 Python 列照抄了错误实现。

问题现象​

四个服务写同一张 logs 表，契约规定 level 取值：debug / info / warn / error / fatal。对账查询：

SELECT service, level, count(*)
FROM logs
GROUP BY service, level ORDER BY 1, 2;

结果里混着契约之外的拼写：

 service    | level    | count
------------+----------+-------
 ai-dag     | warning  |    21   ← 契约里没有
 rag-service| warning  |    17   ← 契约里没有
 ...        | warn     |   ...   ← 这才是契约级名

监控按 level = 'warn' 过滤，这 38 行告警级日志静默蒸发。

根因​

第一层是字面差异：Python stdlib 的级别体系是 DEBUG / INFO / WARNING / ERROR / CRITICAL——没有 WARN（那是个废弃别名），也没有 FATAL。两服务把 record.levelname 直接送进了日志表：一个原样写（大写 WARNING），一个 .lower() 后写（warning）。无论哪种，和契约的 warn 都对不上。

第二层更值得警惕：契约文档本身写着错误实现。跨项目日志契约的字段对照表里，Python 两服务的 level 列写的就是「record.levelname」「record.levelname.lower()」——文档在描述现状，而不是规定应该怎样。于是错误实现拿到了「契约背书」，两个服务各自照做，谁也没怀疑。这和 try/except 吞异常导致的静默失败是同一种危害形态：不出错、只是悄悄少东西，等发现时已经积了几十行漏报。

解决方案​

步骤 1：出口单点映射​

每个服务定义一个归一化函数，所有落库/输出路径统一走它：

_LEVEL_NAME_MAP = {"WARNING": "warn", "CRITICAL": "fatal", "FATAL": "fatal"}

def normalize_level(levelname: str) -> str:
    """WARNING→warn、CRITICAL/FATAL→fatal，其余小写。"""
    return _LEVEL_NAME_MAP.get(levelname.upper(), levelname.lower())

payload = {"level": normalize_level(record.levelname)}   # 永远产出契约级名

关键在「单点」：JSON formatter 和落库 handler 共用同一个函数，映射规则改一处即可，不存在第二个实现。

步骤 2：契约文档改为「应该的实现」​

字段对照表里 Python 两服务的 level 列改为 normalize_level(record.levelname)，并新增一节「level 名映射」：写明映射规则、反模式（禁直写/禁裸 lower）、两个服务的函数入口。契约是规范，不是现状快照。

步骤 3：加对账查询，让漂移可发现​

SELECT level, count(*) FROM logs
WHERE service IN ('ai-dag', 'rag-service')
GROUP BY level ORDER BY 2 DESC;

出现 warn 之外的拼写即漂移。这条查询可以进监控巡检，把「契约 vs 实现」从口头约定变成可断言的检查。

步骤 4：清洗存量（可选）​

修复后新数据不再产生错误级名，存量 38 行按需处理：

UPDATE logs SET level = 'warn' WHERE level = 'warning';

量小可忽略（自然过期），量大或影响历史统计时统一 UPDATE。

常见问题​

Python 的 WARNING 为什么不能直接写进日志表？​

stdlib 级名的字面量是 WARNING/CRITICAL，跨语言契约通常定义为 warn/fatal——直写或 .lower() 得到的 warning/critical 在契约世界里是未知级别，所有按契约级名过滤的消费方（监控、告警）都会漏掉这些行。Python 侧必须在写出口映射成契约级名。

WARNING 和 WARN 是同一个级别吗？​

语义相同、字面不同。Python 的 logging 没有 WARN 级别（WARN 是废弃别名，实际输出永远是 WARNING），也没有 FATAL（对应 CRITICAL）。所以「小写一下」解决不了问题——需要在出口做显式映射：WARNING→warn、CRITICAL→fatal。

怎么发现日志契约和实现已经漂移？​

定期按契约级名做对账查询（GROUP BY level），出现契约外的拼写即为漂移。更重要的是契约文档要写「应该的实现」并注明映射函数入口，而不是复制某个服务的现状——文档照抄实现，错误就有了背书，这是本次漂移存活已久的根源。

在把按天返回的广告数据聚合成周报时，PPC、CPM、ROI 等比率指标暴涨几十倍——PPC 从日粒度实测的 4.70 变成了周报表里的 111.39。

在开发 AI运营 时遇到此问题——基于大语言模型的智能分析，自动洞察市场趋势、用户行为、销售数据，提供精准运营策略。广告数据接口按天返回明细行，入库前要聚合成周粒度供报表消费。聚合上线后首查周报：PPC 111.39（日实测 4.70）、CPM 1585.9（日实测 68.6）、ROI 169.98（日实测 1.82）——13 个比率/均值列全部失真。

TL;DR​

聚合查询里对 CTR、PPC、ROI 这类比率/均值列直接 SUM，得到的是「每天比率的总和」而不是均值，数值按聚合天数成倍放大。两条规则：聚合时只加总可加列（展现、点击、花费等总量），跳过所有比率列；聚合后用总量重算比率（花费÷点击、点击÷展现）。如果手里只有比率没有总量，用分母作权重做加权平均，绝不简单平均。

问题现象​

聚合代码对数值列「全部 SUM」，比率列被静默带进去：

-- 错误写法：所有列都 SUM
SELECT
  campaign_id,
  date_trunc('week', day) AS week,
  SUM(clicks)      AS clicks,
  SUM(impressions) AS impressions,
  SUM(ppc)         AS ppc,   -- 7 天日 PPC 之和！
  SUM(ctr)         AS ctr,   -- 7 天日 CTR 之和！
  SUM(roi)         AS roi    -- 7 天日 ROI 之和！
FROM daily_ad_report
GROUP BY campaign_id, date_trunc('week', day);

实测对比（某计划单周）：

没有任何报错，数据照常入库，报表照常渲染——只有把周报和日明细并排对比，才能发现数值差了一到两个数量级。

根因​

比率与均值是不可加的派生量。 ppc = cost / clicks 的分母每天不同，把 7 天的日 PPC 直接相加，数学上得到的是「7 个相对值的和」，没有任何业务含义。CTR、ROI 同理。

「全部数值列求和」是静默陷阱。 聚合代码通常按列循环统一处理，比率列混在其中不报错、不告警，只是结果悄悄失真。列越多、比率列占比越高，越难肉眼发现。

ROI 放大 93 倍反而更具迷惑性。 它看起来像「投放效果极好」，如果下游直接消费周报做预算决策，错误的数字会一路传到运营动作里。这次事故里，下游还有只读消费方直接读这张周表——表值修对之前，所有消费方都在读错数据。

解决方案​

第一步：聚合只保留可加列​

CREATE VIEW weekly_ad_totals AS
SELECT
  campaign_id,
  date_trunc('week', day) AS week,
  SUM(impressions) AS impressions,
  SUM(clicks)      AS clicks,
  SUM(cost)        AS cost,
  SUM(gmv)         AS gmv
FROM daily_ad_report
GROUP BY campaign_id, date_trunc('week', day);

可加列的特征：它们是「计数/总量」（展现、点击、花费、订单数），跨时间区间相加仍有意义。

第二步：聚合后用总量统一重算比率​

SELECT
  campaign_id,
  week,
  impressions,
  clicks,
  cost,
  CASE WHEN clicks > 0
       THEN cost / NULLIF(clicks, 0)::numeric
       ELSE 0 END AS ppc,
  CASE WHEN impressions > 0
       THEN clicks::numeric / NULLIF(impressions, 0)
       ELSE 0 END AS ctr,
  CASE WHEN cost > 0
       THEN (gmv - cost)::numeric / NULLIF(cost, 0)
       ELSE 0 END AS roi
FROM weekly_ad_totals;

两个细节：PostgreSQL 整数除法会截断，除法前先 ::numeric；分母为 0 统一返回 0，保持与明细层口径一致。

第三步：只有比率、拿不到总量时用加权平均​

-- 用展现量加权聚合日 CTR（展开式：SUM(ctr × impressions) / SUM(impressions)）
SELECT
  date_trunc('week', day) AS week,
  SUM(clicks)::numeric / NULLIF(SUM(impressions), 0) AS ctr_weighted
FROM daily_ad_report
GROUP BY date_trunc('week', day);

加权平均的本质就是「还原分子分母再相除」——只要还拿得到权重列，就永远优先于简单平均。

改完后周报 13 个比率列全部与日明细实测一致，历史脏数据用同一套公式回填，下游只读消费方不改一行代码自动变对。

常见问题​

百分比可以直接 SUM 吗？​

不能。百分比/比率是相对值，各行分母不同，直接 SUM 得到的是 N 个相对值之和，按聚合天数放大且无业务含义。正确做法是聚合时跳过比率列，聚合后用总量重算（点击÷展现、花费÷点击）；只有比率没有总量时，用分母作权重做加权平均。

百分比能加起来求平均吗？​

只有分母相同时才可以。分母不同的百分比直接平均等于不加权平均，结果偏向分母小的项（小流量日的极端比率会被放大）。正确做法是分别加总分子和分母再相除，数学上等价于以分母为权重的加权平均。

排查一个数据看板线索：某广告 offer 在「诊断明细」里被判疑似停投、并附了再投资建议，点进「建议投放」清单却查无此 offer——明细页指着一张清单，清单里没有这行。

在开发 AI运营 时遇到此问题——基于大语言模型的智能分析平台，自动洞察市场趋势、用户行为与销售数据；诊断明细与建议清单分别来自管道里两个相邻查询的产出。

TL;DR​

两个查询对同一个业务谓词（「疑似停投」）用了不同的聚合粒度：明细查询按 计划×offer 粒度判定——任一计划末周无消耗即判疑似；候选清单按 offer 整体粒度判定——挂着的全部计划末周均无消耗才入选。某 offer 在其中一个计划末周仍有消耗，于是「明细判疑似、汇总不入选」，呈现层指向的明细悬空。修法三件套：口径统一收紧到整体粒度、两侧判定 CTE 逐字同源、引用对方行集前校验包含关系。

问题现象​

两个查询各自定义「疑似停投」：

-- 查询④ 诊断明细：pair 粒度（计划 × offer）
WITH consumption_paused_q4 AS (
  SELECT offer_id, campaign_id
  FROM spend_weekly
  GROUP BY offer_id, campaign_id        -- 每个计划单独看
  HAVING SUM(spend) FILTER (WHERE is_last_week) = 0
)

-- 查询⑤ 建议投放候选：offer 粒度（跨全部计划汇总）
WITH suspected_paused_q5 AS (
  SELECT offer_id
  FROM spend_weekly
  GROUP BY offer_id                     -- 整个 offer 一起看
  HAVING SUM(spend) FILTER (WHERE is_last_week) = 0
)

出问题的 offer 挂在多个计划下，其中一个计划末周仍有消耗（3.09）：

查询④（pair 粒度）：  计划A 末周消耗 0     → 判疑似 ✓，并给出建议
查询⑤（offer 粒度）： 跨计划汇总末周消耗 3.09 → 不入选 ✗
呈现层：明细页说「见建议投放表」，建议投放表里没有它

任务不报错、行数对得上大数，悬空只有顺着某条明细点过去才会撞见。

根因​

「同源」契约有覆盖盲区。管道规范要求相邻查询的特征列 CTE 逐字同源——这条契约被严格遵守了；但它只约束特征列，判定集（WHERE 之前的那个业务谓词）不在契约范围内。「疑似停投」在两个查询里被独立实现了两次，粒度不同：pair 级判定对「单个计划内无消耗」敏感，offer 级判定对「所有计划都无消耗」敏感。同一个 offer 两种结论，数学上必然存在交叉带。

跨查询引用把分叉放大成了悬空：呈现层拿查询④的行当明细、查询⑤的表做入口，却没人校验过「④的行集 ⊆ ⑤的行集」。聚合口径不一致是数据仓库最经典的一致性陷阱之一——此前写过的 SUM 比率列导致聚合后指标暴涨是它的另一种形态：聚合发生在了错误的层级上。

解决方案​

步骤 1：先定口径，再写 SQL​

业务问题只有一个答案：「这个 offer 还投不投」是 offer 级决策，判定就该收紧到整体粒度——挂着的全部计划末周均无消耗、且无任何运营标注行，才判疑似。口径变更升 rule_version，可追溯。

步骤 2：判定集 CTE 逐字同源​

把判定 CTE 抽成同一段文本，两个查询直接引用；契约同步升级：逐字同源覆盖判定集（含粒度），不止特征列。从此同一谓词只有一处定义，改口径只改一处。

步骤 3：跨查询引用前，校验行集包含关系​

把「标记集 ⊆ 对方行集」做成固定校验（可入库为测试）：

-- 悬空检测：④ 判了疑似、⑤ 却查无此行
SELECT q4.offer_id
FROM consumption_paused_q4 q4
LEFT JOIN suspected_paused_q5 q5 USING (offer_id)
WHERE q5.offer_id IS NULL;

这条查询返回 0 行，呈现层才有资格把两个产出拼在同一张页面上。

步骤 4：重放验证后上线​

新口径对历史快照重放：逐行核对翻转方向（疑似↔正常）全部正确、零误伤、零悬空，再重跑生产验证通过，才完成收口。

常见问题​

为什么两条 SQL 对同一份数据给出不同结果？​

常见三个差异：聚合粒度（GROUP BY 维度不同——本例的计划×offer 与 offer 整体）、过滤口径（WHERE/HAVING 条件不同）、取数时点（查询时间不同）。粒度分叉最隐蔽：两条 SQL 各自都对，结论却可以相反。

SQL 的 HAVING 和 WHERE 在聚合判定里怎么选？​

WHERE 在分组前过滤行，HAVING 在分组后过滤组。但选对关键字之前先选对粒度——「以什么为一组」决定了判定的灵敏度：粒度越细越容易命中（单组满足即判），越粗越保守（全部满足才判）。两条 SQL 粒度不同，判定结论就可能相反。

如何避免报表之间的数据口径不一致？​

同一业务谓词只在一处定义，判定 CTE 多查询逐字同源；跨查询引用对方行集前跑包含关系校验（A ⊆ B）；口径变更升版本号并对历史数据重放验证。一致性不靠约定俗成，靠契约加校验。

在一次广告数据源从日表切换到周表后，我发现 schema 里还躺着一张只在最早期的 migration 里建过、0 行数据、运行时代码从不引用的空表——还带着过时的字段名和没规范化的中文列。

在开发 AI运营 时遇到此问题——基于大语言模型的智能分析，自动洞察市场趋势、用户行为、销售数据，提供精准运营策略。这次数据源切换后，写入端早已迁到新的周表，旧日表的清理 migration 也补了，唯独一张只在 baseline 里 CREATE 过的月表被遗漏——它既没有对应的新写入，也没有 DROP，就那样潜伏在 schema 里，带着早已废弃的字段定义。

TL;DR​

废弃表的典型特征：只在早期/baseline migration 里 CREATE、当前代码 0 引用、常带旧字段或未规范化的列名。批量迁移时它们不会被自动处理，需要主动用 information_schema.tables 列出 schema 全表，再与代码引用比对，定位 orphan 表后写一条 DROP migration 清理——而不是手动 psql 删完就了事。

问题现象​

一张典型的废弃表长这样：

• 0 行数据——业务早已不再写入它；
• 0 运行时引用——代码里 grep 不到任何 SELECT/INSERT，只剩 migration 文件里的 CREATE；
• 旧字段残留——字段名是上一版命名（如 ad_plan_id/product_id），与当前规范不一致；
• 未规范化的列名——甚至还有中文列名没来得及改。

它不报错、不影响线上运行，所以从「线上没出问题」的视角完全无感。但它的危害是隐性的：误导后来者以为它仍在用、占用 schema 命名空间、在跨表审计时制造噪音，还可能被某个误判的 SELECT * 意外读到脏数据。

根因​

数据库迁移有一个普遍的模式：migration 是「加法」的。

一次数据源切换通常这样演进：

1. 早期 baseline migration CREATE 了一批表（日表、月表）；
2. 业务跑通后，写入端开始依赖这些表；
3. 需求变化，引入新表（周表），写入端逐步迁移过去；
4. 旧表的写入停了，补一条 migration DROP 旧日表；
5. 但月表/其他只在 baseline 建过、从未被写入端直接引用的表，没有对应的 DROP。

问题出在第 5 步：迁移注意力集中在「现在用到的表」上——哪些表在写入、哪些 SQL 在查。而「曾经存在、但从未进入主链路」的表既不在写入端、也不在查询端，自然不会触发任何 DROP，于是成了 orphan。这类残留和 Airflow 删除 DAG 后元数据残留 是同一类问题：「删了入口、忘了清结构」，是迁移类问题的高发区。

解决方案​

核心流程：列全表 → 比对引用 → 确认空表 → 写 migration DROP → 验证。

步骤 1：用 information_schema 列出 schema 下所有基础表​

-- 列出某 schema 下所有基础表（排除视图）
SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'your_schema'
  AND table_type = 'BASE TABLE'
ORDER BY table_name;

information_schema.tables 是 SQL 标准目录视图，跨 PostgreSQL/MySQL/SQL Server 通用，字段稳定，非常适合写进审计脚本。

步骤 2：grep 代码库确认运行时引用​

对每张候选表，在代码库里搜索引用，排除 migration 文件本身：

# 搜索运行时代码引用，排除 migrations 目录
grep -rn "ad_product_monthly_stats" src/ --include="*.py" \
  | grep -v "migrations/"
# 0 行输出 → 运行时无引用，进入候选

0 引用是判定 orphan 的关键证据。注意一定要排除 migration 目录——baseline 里的 CREATE 不算「引用」。

步骤 3：确认是空表​

SELECT count(*) FROM your_schema.ad_product_monthly_stats;
-- 0 → 确认无数据，可安全清理

对有数据的表要格外谨慎：先确认它真的废弃（而非只是近期没写入），有疑问就先做逻辑备份再处理。

步骤 4：写一条 migration DROP（而非手动删）​

-- db-migrations/{project}/027_drop_ad_product_monthly_stats.sql
DROP TABLE IF EXISTS your_schema.ad_product_monthly_stats;

务必走 migration 文件：它会被版本控制、在所有环境（开发/预发/生产）一致重放，留下审计轨迹。手动 psql 删一次，换台机器就又长回来了。

步骤 5：验证已删除​

SELECT to_regclass('your_schema.ad_product_monthly_stats');
-- 返回 NULL 表示表已不存在

to_regclass() 是验证表是否存在的标准手段，返回 NULL 即确认删除成功。

批量审计：按前缀一次性排查同类遗漏​

单张表清掉后，按前缀把同类表全部列出来逐个核对，避免「清了一张、漏了兄弟」：

-- 列出某前缀下所有表，逐个走 步骤2-5
SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'your_schema'
  AND table_name LIKE 'ad_%'
ORDER BY table_name;

常见问题​

怎么列出 PostgreSQL 数据库中的所有表？​

查 information_schema.tables，过滤 table_schema 和 table_type = 'BASE TABLE'，即可列出某 schema 下所有基础表。它比 psql 的 \dt 更适合写进脚本做自动化审计，且是 SQL 标准、跨数据库通用，代码可移植性更好。

PostgreSQL 怎么找出没被使用的废弃表？​

用 information_schema.tables 列出全部表，再与代码库或查询日志的引用做比对，运行时代码 0 引用且无写入的表即为废弃候选；空表可进一步用 SELECT count(*) 确认行数，确认无数据、无外键依赖后再写 migration DROP 清理。

information_schema 和 pg_catalog 有什么区别？​

information_schema 是 SQL 标准定义的目录视图，跨 PostgreSQL/MySQL/SQL Server 通用、字段稳定不易变，适合写可移植的审计脚本；pg_catalog 是 PostgreSQL 专有目录，信息更全更细（如精确行数估算、存储细节），但版本间可能调整。做通用 schema 审计优先用 information_schema。

在用 json.dumps(data, default=str) 把一个含 Python set 的字典持久化、再回读用 in 判断成员时，结果静默出错——没有任何报错，但 in 判断全乱。

在开发 AI运营 时遇到此问题——基于大语言模型的智能分析，自动洞察市场趋势、用户行为、销售数据，提供精准运营策略。某次分析模板的决策重放（replay）功能里，需要把「缺失月份集合」序列化进快照、回放时再读出来判断某月是否缺失。结果重放后，本应判定为「缺失」的月份被误判为「不缺失」，而整个链路没有任何异常抛出。

TL;DR​

default=str 不是万能兜底。它会把 set 交给 str()，在 JSON 里存成 "{1, 2}" 这样的字面量字符串而非数组；回读后类型已不可逆，对它做 in 判断会退化成子串匹配，静默返回错误结果。涉及 set 时，正确做法是序列化前转 list、读取时 set() 重建。

问题现象​

下面这段代码完整复现了静默出错的过程：

import json

# 一个含 set 的字典——比如"需要补数据的缺失月份"
data = {"missing_months": {"3", "5", "12"}}

# 用 default=str 兜底序列化（常见的"别让它报错"写法）
serialized = json.dumps(data, default=str)
print(serialized)
# {"missing_months": "{'3', '5', '12'}"}   ← 变成了字符串，不是数组！

# 回读
back = json.loads(serialized)
value = back["missing_months"]
print(type(value))   # <class 'str'>   ← 已经不是 set 了

# 静默 bug：本想判断某月份是否在"缺失集合"里
print("1" in value)   # True   ← 1 根本不在 {3,5,12}，但 "1" 是 "12" 的子串！
print("3" in value)   # True   ← 碰巧对
print("9" in value)   # False

"1" in value 返回 True，但原集合 {"3", "5", "12"} 根本不含 "1"。没有异常、没有警告，判断结果就这样悄悄错了。这种 bug 在依赖判断结果做分支（如「这个月缺数据吗？缺则补采」）的链路里尤其致命。

根因​

分三层看：

第一层：set 本就不可 JSON 序列化。 JSON 只有 array（对应 list）和 object，没有集合类型。直接 json.dumps({"x": {1, 2}}) 会抛 TypeError: Object of type set is not JSON serializable。

第二层：default=str 把报错变成了静默污染。 json.dumps 的 default 参数在遇到无法序列化的对象时被调用，期望返回一个可序列化的值。str 作为 default 时，会把对象交给 str()——set 就被转成了它的 Python 字面量表示 {'3', '5', '12'}，作为字符串存进 JSON：

>>> json.dumps({"m": {"3", "5", "12"}}, default=str)
'{"m": "{\'3\', \'5\', \'12\'}"}'

报错消失了，代价是类型从 set 变成了 str，且这个过程不会给你任何提示。

第三层：in 对 str 和 set 语义不同。 这是静默 bug 的核心。对 set/list，x in s 是成员判断；对 str，x in s 退化成子串匹配。回读后的值是字符串 "{'3', '5', '12'}"，于是 "1" in "{'3', '5', '12'}" 判断的是字符 "1" 是否作为子串出现——而 "12" 里恰好有 "1"，所以返回 True。

这和 Airflow PostgresHook 多语句 SQL 静默丢结果 是同一类陷阱：最危险的 bug 不是抛异常，而是「静默地给错结果」，因为没有任何信号提醒你去查。

解决方案​

核心原则：JSON 里只存标准类型，集合语义在读取端重建。

方案一：序列化前显式转 list（推荐）​

最直接、最可控——明确知道哪里有 set，就地转成 list：

import json

# 序列化前：set → list（标准 JSON 数组）
data = {"missing_months": list({"3", "5", "12"})}
serialized = json.dumps(data)
print(serialized)
# {"missing_months": ["3", "5", "12"]}   ← 正确的 JSON 数组

# 回读后重建 set
back = json.loads(serialized)
months = set(back["missing_months"])
print("1" in months)   # False ✓
print("3" in months)   # True  ✓

序列化结果是一个干净的 JSON 数组，跨语言、可读、可还原。

方案二：自定义 default 函数（数据来源复杂时）​

如果数据结构较深、不确定哪里混入了 set，用一个专门处理集合类型的 default 函数，既不丢失语义，又能兜底其他非标准类型：

import json

def safe_default(obj):
    # 集合类型 → list，保留为标准 JSON 数组
    if isinstance(obj, (set, frozenset)):
        return sorted(obj)          # 排序让输出稳定可预测
    # 其他无法序列化的类型再退回 str，但要清楚这会丢类型
    return str(obj)

data = {"missing_months": {"3", "5", "12"}, "created_at": some_datetime}
serialized = json.dumps(data, default=safe_default)
# {"missing_months": ["3", "5", "12"], "created_at": "..."}

back = json.loads(serialized)
months = set(back["missing_months"])
print("1" in months)   # False ✓

相比无脑 default=str，这个函数把「需要保真的类型」（集合）单独处理，只有真正无法表示的类型才退回 str，把静默风险控制到最小。

常见问题​

Python set 怎么转 json？​

set 不是 JSON 原生类型，直接 json.dumps 会抛 TypeError。正确做法是序列化前用 list(set) 转成列表，存成标准 JSON 数组；读取时再 set(back["key"]) 重建。这样既不报错，又能完整还原集合语义，跨语言也兼容。

json.dumps 报 Object of type set is not JSON serializable 怎么解决？​

根因是 set 不可 JSON 序列化。最稳妥的解法是序列化前把 set 转成 list；也可以传一个 default 函数，在里面对 isinstance(obj, (set, frozenset)) 返回 list(obj)。要避免用 default=str 兜底——它虽不报错，却把 set 存成了字符串，回读后类型无法还原。

为什么 default=str 序列化 set 后 in 判断结果错了？​

default=str 会把 set 交给 str()，变成字面量字符串 '{1, 2}' 存进 JSON。回读后值类型是 str 而非 set，x in s 就从「成员判断」退化成「子串匹配」——比如 "1" in "{'3','5','12'}" 因 "12" 含字符 "1" 而返回 True，但原集合并不含 "1"。解法是序列化 list、读取时 set() 重建。