Manjusaka

优化日志：给自建图床 PicImpact 做一次大范围性能优化

2026-05-31T16:30:00.000Z

和 Debug 日志、SRE 日志一个系列，优化日志用来复盘一些可以公开的折腾经历。

这一篇的主角是 PicImpact——我自己在用的那个开源图床，跑在 photos.manjusaka.me 上，托管着我这几年拍的猫猫狗狗。去年年终总结里我写过一句「把自建图床项目的代码拾掇了很多」，这篇就算是那句话的注脚。前后断断续续修了一轮，修复点其实都不大，但中间冒出来的几个回归是真的有意思，尤其是最后那个 WebGL 的坑，我愿称之为本年度最佳。

开篇：五个硌牙的地方

日常用下来，对着隔壁 afilmory 抄作业，我把 PicImpact 的毛病列成了五条：

动画卡；
滚动在不同平台上各种抽风；
移动端会崩，而且是崩完自动刷新、刷新完接着崩的那种无限循环；
交互普遍卡顿；
二十多兆的原图直接把整个页面拖死。

看着像五个独立的问题，真顺着查下去会发现，根子其实是同一个：这个图床在「该喂给浏览器什么」这件事上，从一开始就喂错了。

下面不按 PR 的顺序讲，按「病灶」讲。顺带一提，整个过程是拆成一堆子任务、各走各的 feature branch + PR 推进的，PR 都提给了上游 besscroft/PicImpact。

⑤ 才是万恶之源

先说第五条，因为它是杠杆最长的一根撬棍——把它撬动了，③④ 也跟着松了大半。

原来的逻辑朴素得感人：缩略图走一张 preview，点开看大图，直接怼原图。问题是我那台 Z8 出的片子动辄 8256×5504、十几兆一张，首页一铺二三十张……移动端内存那点家底，就这么被噎死了。

正经做法是预处理出响应式变体：上传的时候把每张图压成一梯队不同宽度的 AVIF（[320, 480, 640, …, 2560]），前端按 sizes 取对应那一档。这里有两个我觉得值得贴一下的细节。

第一，一张原图只解码一次。十几兆的图解码本身就不便宜，要是每个档位都从头解一遍，那预处理能慢到姥姥家：

// server/lib/image-variants.ts —— 解码 + EXIF 纠正只做一次，8 个档位都从 clone 出来
const base = sharp(input, { limitInputPixels: MAX_INPUT_PIXELS, failOn: 'none' }).rotate()
for (const width of tierWidthsForSource(sourceWidth)) {
  const resized = base.clone().resize({ width, withoutEnlargement: true })
  const [avif, webp] = await Promise.all([
    resized.clone().avif({ quality: avifQuality, effort: avifEffort }).toBuffer(), // effort=2，比默认的 4 快了约 2.6×
    resized.clone().webp({ quality: webpQuality }).toBuffer(),
  ])
}

AVIF 的 effort 我从默认的 4 压到了 2，编码快了两倍多（约 2.6 倍），体积基本没差别，属于白捡的。

第二，变体的 key 用原图的 sha256 来做内容寻址。这样内容一变 key 就变，配上 Cache-Control: immutable 就能永久缓存，压根不用操心失效这事：

1 2	const digest = createHash('sha256').update(input).digest('hex').slice(0, 32) return `variants/${digest}` // 最终变体就是 variants/{digest}_{width}.avif

剩下就是让前端真的去吃这些变体。这里有个一定要注意的坑：next/image 默认会把图片全绕回 Node 服务器去做优化（/_next/image），那我 CDN 不就白搭了么。所以得写个自定义 loader 直接拼 CDN 上的 URL：

// lib/image/loader.ts
export function makeVariantLoader(opts) {
  return ({ width }) => {
    const tier = Math.min(ceilToTier(width), opts.readyMaxWidth) // 取 ≤ 就绪水位的最近一档
    return joinUrl(opts.base, buildVariantKey(opts.imageKey, tier, opts.format))
  }
}

存量那一千来张（实测 1091 张）用一个基于 PG 的任务队列慢慢 backfill 补齐。期间还踩了个小坑：有几张 11008×16512、182MP 的全景，把我们自己设的 100MP 解压上限给顶爆了——那个上限当初是为了防解压炸弹，比 sharp 默认的约 268MP 还严，于是单独给放宽到了 500MP。

效果是相当离谱的。同一张图（DSC_7956，原图 18.08MB）：

原图 JPG：18.08 MB
旧的 preview（webp）：164 KB
网格用的 AVIF 640：5.19 KB，约 3480 倍
灯箱用的 AVIF 2560：24.1 KB

一个首页 24 张图，从「原图加起来 400 多兆」变成「一百多 KB」。后面做 trace 的时候我看到首屏那张 LCP 图的下载耗时是 89 微秒——微秒。⑤ 和大半个 ④ 就这么没了。

这里有条原则我从头贯彻到尾：网格和默认详情页永远不碰原图，原图只有一个地方会加载，就是用户主动点开全屏缩放的时候。记住这个「例外」，它后面要出大事。

顺手收拾掉的 ① ② ③ ④

字节数搞定，剩下是「怎么把它们画出来」。

瀑布流原来是 CSS 多列（columns-*），这玩意有个阴间的地方：每翻一页追加新图，整个累积的 DOM 会重新挂载、重排，把前面所有图的位置全打乱重来一遍。换成 masonic 做窗口化虚拟瀑布流之后，item 只测一次、绝对定位、只挂视口里那些，滚动顺了不止一个档次。

移动端那个无限崩溃循环（③）最唬人，根子在无限滚动的 IntersectionObserver——回调闭包把过期的 state 给捕获了，于是某些时序下它会发了疯一样地「加载下一页」，移动端就这么被拖崩、刷新、再崩。把状态收敛进 ref、再把预加载的 rootMargin 拉到约 1.5 个视口（变体那么小，预加载激进点完全不亏），滚到底再也不用干等接口了。

动画那块（①）就是常规操作：合理用 will-change、blurhash 占位 + 宽高比盒子防止图片加载时的布局回流。后者顺手把 CLS 摁到了 0.01。

benchmark 一轮

在途的 PR 合完，我对线上做了一轮 trace + Lighthouse。头号发现是 LCP 4.69s，差评。

但拆开一看就很有意思：那张 LCP 图自己 89 微秒就下完了，慢全慢在「发现」上——2.77s 的 load delay。三项 LCP discovery 检查全军覆没：没 fetchpriority=high、用了 loading=lazy、而且压根不在初始 HTML 里。

最后这条是命门：画廊是 dynamic(ssr: false) 的纯客户端组件，首图根本不在服务端吐的 HTML 里，浏览器的 preload scanner 自然发现不了，得等 hydration + 动态 import 跑完才开始发请求。

修法就是把首图捞回初始 HTML：首屏头几张标 priority，再在服务端往里塞一条响应式的 AVIF preload-link。imagesrcset 直接复用前面那套档梯常量生成、并且复刻了 next/image 自己的 getWidths 选档逻辑，保证 scanner 和真正的选到的是同一个候选——不会重复下两次。

TTFB 那 700 来毫秒也没放过。页面是每次请求都打 DB 的动态渲染，在公开只读的那些数据函数上包一层 unstable_cache + tag 失效（只缓存全局公开数据，鉴权的一概不碰，写操作触发失效避免上传后长期 stale），TTFB 降了约 38%（/lotus 实测从 ~0.65s 到 ~0.40s）。

再把瀑布流容器那个 role="grid" 改成 role="list"（grid 要求子节点是 row/gridcell，我这一堆链接挂在 grid 底下本来就是 ARIA 契约违例），移动端 a11y 从 90 干到了 100。

一轮下来：LCP 4.69s → 2.46s，CLS 0.01，a11y 满分，TTFB 砍掉小四成。本以为可以收工了——然后就开始还债了。

还债环节：三个回归

性能优化这事最迷人的地方就在于，你每堵上一个窟窿，新的窟窿就从你没盯着的地方冒出来。

第一个，详情页退出来之后，整个相册从 AVIF 退化回了原图/webp。查下来是变体的 CDN base（variantBaseUrl）走的是客户端 SWR 拿的配置，软导航（详情→返回）让画廊重新挂载的那一瞬间，配置还没回来、base 是空的，整个变体阶梯就失效了。给那个 SWR hook 加一层模块级的 fallbackData 兜住上次的值就好。先记住这个「配置异步到达的缝隙」，它马上还要再咬我一口。

第二个，移动端崩溃循环——它回来了。现象是加载相册时 network 里会请求一大堆「明明已经优化掉的」preview。devtools 一抓，硬刷一次 /dog：40 张 AVIF + 24 张 preview，64 个请求，而且这个数字 7.5 秒内纹丝不动，说明不是死循环，是一次性的双重加载。

根子还是那条缝隙。冷加载第一帧 variantBaseUrl 是空的，于是：

// masonry-photo-item.tsx：base 为空 → hasReadyVariants 为 false → 回落去拉 preview
const variantReady = !variantFailed && hasReadyVariants(photo.image_key, photo.ready_max_width, variantBaseUrl)
const imageProps = variantReady
  ? { src: photo.image_key, loader: makeVariantLoader({ base: variantBaseUrl, /* … */ }) }
  : previewSrc ? { src: previewSrc, unoptimized: true } : null
// 等配置到了、variantReady 从 false 翻 true，key 一变 React 就卸了 preview 的  再挂 avif 的 
<Image {...imageProps} key={variantReady ? 'variant' : 'preview'} />

先 preview 后 AVIF，白下一轮。桌面顶多浪费点流量，移动端是 24 张 preview 的解码内存峰值直接把页面顶 OOM，崩了刷、刷了崩。修法是釜底抽薪：页面本来就是 server component，服务端 resolve 出 variantBaseUrl 之后当 prop 直接透传给画廊，第一帧就有 base，焊死这条缝。

第三个最精彩，是个 React 和 WebGL 凑一块儿才能凑出来的坑。现象很具体：详情页点图进缩放（一个 WebGL viewer），第一次好好的，关掉之前再点第二次，整个页面当场去世，图也没了。

老规矩，先 devtools 复现，给 WebGL context 的创建/丢失打点：

第一次开：context 活着 ✓
关闭：context lost = 1
第二次开：没有新建 context，而且 isContextLost() = true

顺着这条线索捋，根因是这么一串：

这个 viewer 是用 React 的来显隐的。有个很要命的语义——隐藏的时候它会跑子组件的 effect cleanup，但保留 DOM（同一个）和 state。而我之前为了修「相册→详情→缩放反复进出会泄漏 WebGL context」（浏览器活跃 context 大概 16 个就到顶了），在 viewer 的 cleanup 里加了一刀 destroy：

// WebGLImageViewer.tsx —— 这个 cleanup，在 Activity 隐藏时也会跑
useEffect(() => {
  setUpWebGLEngine()
  return () => { viewerRef.current?.destroy(); viewerRef.current = null }
}, [])

// 而 engine.destroy() 末尾为了立刻把 context 还给浏览器，调了这么一句：
this.gl.getExtension('WEBGL_lose_context')?.loseContext()

于是关闭 modal（Activity 隐藏）的时候，这个 cleanup 跑了，loseContext() 把那块被 Activity 留着复用的 canvas 的 context 永久弄丢了。等第二次打开，effect 重新跑，可 isInitialized 这个 state 又被 Activity 原样保留着——初始化函数里那句 if (isInitialized) return 的守卫，要么短路（不重建引擎，于是留你对着一块死 canvas 发呆，图不显示），要么没短路（试图在死 context 上重建，createProgram() 返回 null，下一行 attachShader(null, …) 直接抛异常，整页带走）。同一个 bug 两种死法，全看那个守卫这次短没短路，挺哲学的。

说白了就是：我把 destroy 绑错了地方，绑在了「关闭缩放」上，可它本该只在「离开详情页」的时候触发。

第一版修法（#509）图省事，直接把 viewer 从显隐改成条件挂载/卸载。崩是不崩了，可很快就回过味来——这版 UX 反而退化了：每次开都重建引擎、重新解码原图，缩放和平移的状态也全丢了。原来那套设计是能在 modal 里复用同一个 context、把缩放状态留着的，这才是好体验。

最终版（#510）想明白了：viewer 首次打开之后就一直挂着别卸，开关只用 CSS visibility 切：

{hasOpenedFullScreen && (
  <div style={{ visibility: showFullScreenViewer ? 'visible' : 'hidden',
                pointerEvents: showFullScreenViewer ? 'auto' : 'none' }}>
    <WebGLImageViewer ref={webglViewerRef} src={highResImageUrl} /* … */ />
  div>
)}

不卸载就不跑 cleanup，同一个 context 跨开关复用，缩放状态稳稳留着，也不崩；而 destroy 只在 ProgressiveImage 真正卸载（离开详情页）的时候才触发，防泄漏那一刀的收益原样保留。

这里还有个细节：用 visibility:hidden 而不是 display:none。后者会把 canvas 尺寸变成 0×0，引擎算 fit-to-screen 的 scale 时会被 clamp 成 1，重新显示的时候就把你的缩放给重置了。visibility:hidden 保住尺寸，绕开这条路。

React 那套「隐藏 == 卸 effect，但 state 和 DOM 都留着」的语义，碰上「持有原生资源」的组件，是真的隐蔽。

收工

回头看，⑤ 那一刀（原图体积）是性价比最高的——图床这东西，先把「喂给浏览器什么」搞对，一多半的毛病会自己消停。剩下的，与其说是优化，不如说是在「修好主问题之后，挨个去还它牵出来的债」：退化、双载、Activity 的生命周期，没一个是一开始就看得见的。

要说有什么方法论，大概就一条：能 devtools / curl / Lighthouse 量出来的，就别猜。尤其 debug，先稳定复现、揪到根因再动手，比「改改这个看看？」要快得多。

图床现在用着是真舒服了。下次再翻小熊和小狗的照片，至少不用再等那一下卡顿。

一万年太长，我们只优化今朝（

收工。

Pydantic 不是免费的——聊聊数据校验的边界

2026-03-23T14:30:00.000Z

最近给一个后端服务做 perf，跑了一发 py-spy 出来火焰图，盯着看了一会儿，发现 pydantic.main.__init__ 这一条在主热路径上占了一个让人挺难绷的比例。做了几轮调整之后顺手把这件事记一下——核心想说的是：对一个 web 服务来说，数据校验从来不是免费的，pydantic 也一样。它有它的边界，越界使用就要付出对应的代价。

起因：火焰图里看到的东西

某个内部业务服务，写法上挺标准——FastAPI + uvicorn + pydantic + psycopg，业务里所有”长得像数据”的东西，从 DB 行、内部传递的中间态、到 API response，全部都用 BaseModel 表达。看起来一致、规整，review 起来也舒服。

直到我们因为 P95 不太好看，跑了一发 py-spy：

1	py-spy record --duration 60 --rate 100 --output flame.svg --pid

火焰图大约 8,700 个采样点，里面让我多看了一眼的是：

pydantic/main.py:250 也就是 BaseModel.__init__，单条最厚的火焰柱占了 22.65%（约 1,982 samples）
顺着主链路再往上扒，另一条 __init__ 路径又占了 6.81%
加加减减，光是”实例化 pydantic 模型”这一件事，在这个服务上吃掉了 不止 25% 的 CPU 时间

最骚的是，这些 __init__ 大部分根本不是用户请求的入口校验，而是从我们自己的 PostgreSQL 里 SELECT 出来的行，被 psycopg.rows.class_row(SomeModel) 一行一行喂给 BaseModel.__init__ 的——也就是说，我们在拿”自己写进去的、Schema 完全可控的数据”，反复跑一套带 schema validation 的实例化流程。

那一刻就一个念头：这事真不值得。

这件事意味着什么

Pydantic v2 已经把 validator 内核换成 Rust 写的 pydantic-core 了，比 v1 快了一个数量级。所以很多人下意识会觉得 “v2 的开销可以忽略”。这个印象大致没错——但只要你的 QPS 再高一点、单次请求里要构造的对象再多一点，”忽略不计的开销” × N 之后，它会非常明确地出现在你的 flame graph 上。

更重要的是，pydantic v2 快的是 校验本身。但你每实例化一次 BaseModel，整条链路是这样的：

__init__ 入口
  ├── 查 schema cache
  ├── pydantic-core validator dispatch（rust 侧）
  │     ├── field-by-field 类型校验
  │     ├── model_validator(mode="before")
  │     ├── 默认值填充
  │     └── strict / coerce 分支
  ├── 写回 __dict__ / __pydantic_fields_set__
  └── model_validator(mode="after")

哪怕你的 model 没有任何 validator、没有任何 Field(...)，进 rust 转一圈再回来这件事本身就有不可压缩的成本——函数调用、字典构造、属性写入，每一项都要钱。

而把这套机制用在 从可信源反序列化 的场景上，大部分钱花得没意义——你这一行就是你刚才 INSERT 进去的，schema 对不上的概率约等于”你的 migration 没跑过”，那已经是另一类问题了。

Pydantic 在一个 web 服务里到底干啥

把日常项目里 BaseModel 出现的地方分一下类，差不多是这五种：

API 边界：FastAPI route 的 request body / query / path param —— 输入来自外部，必须严格校验
响应序列化：FastAPI 的 response model —— 决定对外契约的 shape，并且要做 JSON 序列化
应用配置：pydantic-settings 读 YAML / env，启动时一次性校验
业务规则校验：带 field_validator / model_validator 的领域对象，比如 “金额必须是正数、组合字段必须满足某个不变式”
内部数据容器：DB 行映射、内部函数之间传递的中间态、纯粹为了”有类型、有字段名”而存在的小结构体

前四个有明确收益——schema 是契约，validation 就是这份契约的执行机制，它的运行时开销换的是 类型/不变式上的安全保证。

第五个，几乎全是白送的开销。这一类对象是在你自己写的代码里产生、在你自己写的代码里消费的，schema 已经被静态类型检查器（mypy / ty）和 beartype 之类工具覆盖到了；运行时再跑一次 pydantic 的校验，校验的对象要么是你 5 行前刚 query 出来的，要么是你 3 行前刚自己 Item(...) 构造的。换句话说，你是在校验你自己。

怎么替代：dataclass + slots

那第五类该用什么？答案非常无聊——标准库的 @dataclass，加 slots=True：

from dataclasses import dataclass

@dataclass(slots=True)
class RowEntry:
    id: str
    value: float
    position: int
    category: str

slots=True 让实例不再有 __dict__，每次构造省一份哈希表分配，访问字段也直接走 C 层 slot。配合 beartype 的运行时类型检查（如果你像我们一样在 __init__.py 里 beartype_this_package()），整体的”类型安全度”和你用 pydantic 是同一个量级的，但开销低得多。

更顺的一点是：psycopg 的 class_row 原生支持 dataclass，几乎是无缝替换：

from psycopg.rows import class_row

# 之前：BaseModel
class RowEntry(BaseModel):
    id: str
    value: float
    position: int
    category: str

# 之后：dataclass，调用方一行不用改
@dataclass(slots=True)
class RowEntry:
    id: str
    value: float
    position: int
    category: str

async def fetch_entries(conn, n: int) -> list[RowEntry]:
    async with conn.cursor(row_factory=class_row(RowEntry)) as cur:
        await cur.execute(
            "SELECT id, value, position, category FROM entries ORDER BY position LIMIT %s",
            (n,),
        )
        return await cur.fetchall()

调用侧的体感和原来一模一样——你照样有 .id、.value、.position，照样能被 ty / mypy 检查类型，照样能 for item in items: ...。差别只是火焰图里那条粗柱子掉下去了。

一个完整的”边界感”示例

把上面的话翻成代码。假设我们要做一个 /items 接口，从 DB 取数据、做点轻量计算、然后返给调用方：

from dataclasses import dataclass
from fastapi import APIRouter, Depends
from pydantic import BaseModel, Field
from psycopg.rows import class_row

# ---- API 边界：必须 pydantic ----

class ListItemsRequest(BaseModel):
    """Request 来自外部，schema 必须严格校验。"""
    user_id: str = Field(min_length=1, max_length=64)
    limit: int = Field(default=20, ge=1, le=100)
    category: str | None = None

class ItemView(BaseModel):
    """Response 决定对外契约和 JSON 序列化方式。"""
    id: str
    value: float
    position: int

class ListItemsResponse(BaseModel):
    items: list[ItemView]
    total: int

# ---- 内部数据容器：dataclass 就够 ----

@dataclass(slots=True)
class RowEntry:
    """从 DB 读出来的一行，schema 完全可控，不需要再校验一次。"""
    id: str
    value: float
    position: int
    category: str
    raw_value: float

@dataclass(slots=True)
class ProcessedEntry:
    """中间计算态，只在内部函数之间传。"""
    id: str
    final_value: float
    position: int

# ---- 业务实现 ----

async def fetch_entries(conn, category: str | None, n: int) -> list[RowEntry]:
    sql = "SELECT id, value, position, category, raw_value FROM entries"
    params: tuple = ()
    if category is not None:
        sql += " WHERE category = %s"
        params = (category,)
    sql += " ORDER BY position LIMIT %s"
    params = (*params, n)

    async with conn.cursor(row_factory=class_row(RowEntry)) as cur:
        await cur.execute(sql, params)
        return await cur.fetchall()

def process_entries(rows: list[RowEntry], user_id: str) -> list[ProcessedEntry]:
    # 纯内部计算，所有输入输出都来自我们自己
    return [
        ProcessedEntry(
            id=r.id,
            final_value=r.value * _compute_factor(user_id, r.category),
            position=i,
        )
        for i, r in enumerate(rows)
    ]

router = APIRouter()

@router.post("/items")
async def list_items(
    req: ListItemsRequest,                    # pydantic 校验入参
    conn = Depends(get_conn),
) -> ListItemsResponse:                       # pydantic 决定出参 shape
    rows = await fetch_entries(conn, req.category, req.limit)    # dataclass
    processed = process_entries(rows, req.user_id)                # dataclass
    return ListItemsResponse(
        items=[ItemView(id=p.id, value=p.final_value, position=p.position)
               for p in processed],
        total=len(processed),
    )

整段代码里 pydantic 只活在两个位置：进来的请求 和 出去的响应。中间所有”只在我们自己代码里活动”的对象，全是 dataclass。这是一种很朴素的边界感——pydantic 守门，dataclass 干活。

什么时候必须保留 pydantic

不是所有看起来”内部”的 model 都该被改成 dataclass。下面这些情况，老老实实留着 pydantic：

用了 validator（field_validator / model_validator）—— 这些校验本身就是业务规则的载体
用了 model_dump() / model_dump_json() 做序列化 —— pydantic 的 dump 比手写转换更稳
用了 model_validate() / TypeAdapter 做反序列化 —— 输入来源不可信
用了 ConfigDict 配字段别名、from_attributes 之类的特性
继承链上有 BaseModel 且子类依赖父类的 schema 推导
配置类（pydantic-settings）—— 启动时一次性校验，是非常划算的开销
被外部库以 pydantic 协议消费（比如 LangChain 这种把 pydantic schema 当 tool 描述用的库）

辨认起来其实很机械——把这个 model 类的整个引用图扫一遍，看它有没有上面这些特性或这些用法。没有任何一条命中的，那它就是一个伪装成 model 的 NamedTuple，可以下放到 dataclass。

一个可以照抄的判断 checklist

每次新加一个数据结构时，先按下面这串问题走一遍：

要加一个新的 data class
  │
  ├─ 这个数据来自外部（HTTP 请求 / 用户输入 / 第三方 API）？
  │     └─ 是 → pydantic BaseModel
  │
  ├─ 这个数据要序列化到外部（HTTP 响应 / 写消息队列）？
  │     └─ 是 → pydantic BaseModel
  │
  ├─ 这个数据需要业务规则校验（字段间不变式 / 自定义 validator）？
  │     └─ 是 → pydantic BaseModel
  │
  ├─ 这是配置（从 YAML / env 读的）？
  │     └─ 是 → pydantic-settings
  │
  ├─ 这个 model 会被 model_dump / model_validate / TypeAdapter 用？
  │     └─ 是 → pydantic BaseModel
  │
  └─ 否则
        └─ @dataclass(slots=True)

这套规则不是要”消灭 pydantic”，而是把它放回它该在的地方——校验和序列化。其他位置上，标准库 + 类型检查器已经能给你足够的安全感，没必要额外缴一份运行时校验税。

收尾

回到那个火焰图。把”纯数据容器”那一类换成 @dataclass(slots=True) 之后，再跑了一次同等压力的 profile，主热路径上 pydantic.main.__init__ 的占比从 20%+ 掉到了零点几个百分点，相同 QPS 下 P95 也跟着下来一截。代码量倒没什么变化，受影响的也就是十来个类——但收益挺真实。

写到这里其实想说的话已经讲完了：

数据校验这件事，从来不是越多越好。它有明确的边界——边界之内是契约和安全，边界之外是无谓的开销。Pydantic 是非常好的工具，但用它的人也得知道自己什么时候用、为什么用。

下次起新项目，先想清楚这条边界画在哪。等到 flame graph 上 pydantic.main.__init__ 已经长成一根粗柱子才回过头来想，其实就晚了一步——好在还来得及。

差不多就这样。

当我们在维护模型 API 服务时我们在维护什么

2026-03-15T14:00:00.000Z

过去这一年我们团队陆陆续续做了几个 AI Service——大多是拿 FastAPI 包一个模型，再对外出 API。做到第三四个的时候我意识到一个尴尬的事实：每个项目长得都差不多，但每次起新项目还是在从零开始复制粘贴，而且不同的人写出来的目录结构、配置方式、metrics 命名都不太一样。一个新人接手第二个服务的时候，几乎要把第一个服务的认知全部重学一遍。

这篇文章想聊的不是某个具体框架，而是把这几个项目踩过的坑、迭代下来的设计、留下来的规范集中讲一遍——也算是给”维护一个模型 API 服务”这件事做一次复盘。

正文

把”维护一个模型 API 服务”拆开看，其实是几个相互独立但又互相影响的小问题：项目长什么样、配置怎么分层、模型版本怎么迭代、可观测性怎么做、日常开发流程怎么走、CI 和镜像怎么发。下面按这几个维度逐个聊。

一个 AI Service 该长什么样

先看目录结构。我们最终收敛到的样子是：

src//
├── __init__.py          # __version__ + beartype_this_package()
├── app.py               # create_app() factory, registries, lifespan, health mount
├── cli.py               # typer CLI: serve with --api-version list
├── config.py            # pydantic-settings BaseSettings + @cache singleton
├── handler.py           # BaseHandler ABC + shared request/response schemas
├── metrics.py           # Prometheus MetricsRegistry (version-aware)
├── v1/
│   ├── handler.py       # V1 Handler + get_handler
│   └── router.py        # register_router(app) with v1 routes
└── v2/                  # added when model evolves
    ├── handler.py       # V2 Handler + get_handler
    └── router.py        # register_router(app) with v2 routes
test/
├── test_app.py          # API integration tests
pyproject.toml           # hatchling build backend, uv managed
Makefile                 # install, format, lint, test, dev, clean
Dockerfile               # multi-stage with uv
entrypoint.sh            # calls CLI serve command

跟我们最早的版本比，最大的变化是引入了版本子目录。顶层的 handler.py 退化成了抽象基类，每个版本（v1、v2……）有自己的 handler 和 router。这是某个项目从 v1 演进到 v2 的时候被迫定型下来的——你不可能在原地修改老接口，又要让两个模型同时在线，唯一可行的就是物理隔离。

下面挑几个真正影响维护体验的点展开聊。

beartype：把类型检查塞进运行时

每个包的 __init__.py 第一行：

from beartype.claw import beartype_this_package
beartype_this_package()

__version__ = "0.1.0"

beartype_this_package() 会给整个包的所有函数挂上运行时类型检查，开销接近零。它能抓住静态检查器搞不定的那一类 bug——你函数签名写的是 str，但运行时传进来一个 None；或者 tensor shape 不对；或者某个第三方库返回值的类型和文档不一致。

在 AI Service 这种场景里，模型推理链路上的类型错误特别常见——预处理、tokenize、forward、后处理，每一步都可能有数据形状或类型上的微妙差异。能在 import 时就把网撒开，越早暴露越好。

配置分三层：Secret / App / CLI

这是看起来朴素但实战非常关键的一个设计——我们把配置严格分成三类：

Secret：HF token、API key、数据库密码——只从环境变量或 Vault 读，永远不进 YAML，不进 git
App config：model id、torch.compile 开关、各种业务阈值——主要从 YAML 读，环境变量可以覆盖
运行时参数：host、port、启用哪些版本——走 CLI

代码层面 Secret 和 App 是两个独立的 pydantic-settings 类：

class SecretSettings(BaseSettings):
    """Secrets only — always from env vars or Vault. Never put these in YAML."""
    model_config = SettingsConfigDict(env_prefix="_")
    hf_token: str | None = None

class AppSettings(BaseSettings):
    """General service config — from YAML, overridable by env vars."""
    model_config = SettingsConfigDict(
        yaml_file="config.yaml",
        env_prefix="_",
    )
    model_id: str = "default-model-name"
    torch_compile: bool = True

    @classmethod
    def settings_customise_sources(
        cls,
        settings_cls: type[BaseSettings],
        init_settings: PydanticBaseSettingsSource,
        env_settings: PydanticBaseSettingsSource,
        dotenv_settings: PydanticBaseSettingsSource,
        file_secret_settings: PydanticBaseSettingsSource,
    ) -> tuple[PydanticBaseSettingsSource, ...]:
        return (
            init_settings,
            env_settings,
            YamlConfigSettingsSource(settings_cls),
            file_secret_settings,
        )

这种分层一开始看起来啰嗦，但维护几个项目下来你会发现：每次出”配置爆炸”问题、每次部署混乱，几乎都来自把这三类东西混在一起处理。强制分层之后，K8s 的 Secret、ConfigMap、Deployment args 各管各的，review 起来一目了然。

Registry-Based App Factory：让 app.py 永远不用动

整个项目最值得说的一个设计决策——用注册表 + 动态导入来管理多版本，让 app.py 在加新版本时一行不用改。

app.py 里有两个 registry dict：

ROUTER_REGISTRY: dict[str, str] = {
    "v1": ".v1.router",
    "v2": ".v2.router",
}

# (handler module, handler class, app.state attr, settings model_id attr)
HANDLER_REGISTRY: dict[str, tuple[str, str, str, str]] = {
    "v1": (".v1.handler", "Handler", "handler", "v1_model_id"),
    "v2": (".v2.handler", "Handler", "v2_handler", "v2_model_id"),
}

create_app 接受一个版本列表，支持同时跑多个版本：

def create_app(api_versions: list[str] | None = None) -> FastAPI:
    if api_versions is None:
        api_versions = ["v1"]

    app = FastAPI(title="", version=__version__, lifespan=lifespan)
    app.state.api_versions = api_versions
    mount_health_routes(app)

    for version in api_versions:
        module = importlib.import_module(ROUTER_REGISTRY[version])
        module.register_router(app)

    return app

lifespan 遍历版本列表，动态加载每个版本的 Handler，存到不同的 app.state 属性上：

@asynccontextmanager
async def lifespan(app: FastAPI):
    settings = get_settings()
    for version in app.state.api_versions:
        module_path, class_name, attr_name, model_id_attr = HANDLER_REGISTRY[version]
        model_id = getattr(settings, model_id_attr)
        module = importlib.import_module(module_path)
        handler_cls = getattr(module, class_name)
        handler = await asyncio.to_thread(handler_cls, model_id, settings.hf_token)
        setattr(app.state, attr_name, handler)
    yield

这个设计的好处是：app.py 不需要 import 任何具体版本的模块，加新版本就是加文件 + 加 registry 条目。换句话说，核心入口对版本扩展是封闭的，对版本添加是开放的——OCP 在这种场景下特别好用。

Handler 和 Router 的分版本组织

顶层 handler.py 定义 BaseHandler ABC 和共享的 schema：

class BaseHandler(ABC):
    @abstractmethod
    def _load_tokenizer_and_model(self, model_id: str, hf_token: str) -> tuple: ...

    def predict(self, request: BasePredictRequest) -> list[PredictResponse]:
        # 共享的推理逻辑
        ...

每个版本的 handler.py 实现具体的模型加载，并提供一个 get_handler 读取自己那个 app.state 属性：

# v1/handler.py
def get_handler(request: Request) -> Handler:
    return request.app.state.handler       # v1

# v2/handler.py
def get_handler(request: Request) -> Handler:
    return request.app.state.v2_handler    # v2

每个版本的 router.py 用 register_router(app) 闭包模式定义路由：

# v1/router.py — v1 没有前缀（默认版本）
def register_router(app: FastAPI) -> None:
    router = APIRouter()
    @router.post("/predict")
    async def predict(...) -> list[PredictResponse]:
        ...
    app.include_router(router)

# v2/router.py — v2 带版本前缀
def register_router(app: FastAPI) -> None:
    router = APIRouter(prefix="/v2")
    @router.post("/predict")
    async def predict(...) -> list[PredictResponse]:
        ...
    app.include_router(router)

注意 v1 的路由没有前缀（路径就是 /predict），v2 才开始加 /v2 前缀。这是对历史的一种妥协——v1 是最早的版本，改路径会破坏已有消费者，所以新增版本的代价由新版本自己承担。

所有 CPU 密集的推理操作都用 asyncio.to_thread 包起来。路由函数的返回值类型注解就是响应模型——不用 response_model= 参数，直接写 -> list[PredictResponse]，FastAPI 会自动推断。

模型版本怎么演进：一条铁律

讲完结构，最容易踩坑的部分是模型版本迭代。我们给自己立了一条铁律：

NEVER modify or rename an existing API route when adding a new model version.

听起来是废话，但真做的时候很多人会犯错。以下这些操作我们都见过、踩过、或者在 review 时拦下来过：

把 /api/v1/encode 改名成 /api/v1/encode-legacy，让它”看起来像被废弃了”
修改已有接口的 request/response schema（哪怕只是加一个可选字段）
在已有的 request 里加一个 model_version 字段来复用同一个路由
直接替换已有路由背后的模型（行为变了但版本号没变——这是 bug，不是 feature）

正确的做法只有一种，不管 API shape 变不变，流程都一样：

加 v2/handler.py + v2/router.py
在 app.py 的 ROUTER_REGISTRY 和 HANDLER_REGISTRY 里加两行
完事

新模型来了？
├── 加 v2/ 子目录（handler + router）
├── 在 app.py 的两个 REGISTRY 里加条目
├── 通过 --api-version 控制启用哪些版本
│   ├── 只跑 v2: --api-version v2
│   └── 同时跑: --api-version v1 --api-version v2
└── 老模型要下线？
    ├── 先在老路由里加 deprecation log warning
    ├── 看版本隔离的 metrics 确认零流量
    └── 确认后删除 v1/ 目录和 registry 条目

CLI 的 --api-version 是一个 list 参数，天然支持多版本同时运行：

@cli.command()
def serve(
    host: Annotated[str, typer.Option(help="Host to bind to")] = "0.0.0.0",
    port: Annotated[int, typer.Option(help="Port to bind to")] = 8000,
    api_version: Annotated[
        list[str], typer.Option("--api-version", help="API versions to enable")
    ] = ["v1"],
) -> None:
    app = create_app(api_versions=api_version)
    uvicorn.run(app, host=host, port=port)

如果新模型的 API shape 变了（比如 request 多了字段），v2 的 handler 里直接 subclass BasePredictRequest 加字段就行。v2 的 router 带 /v2 前缀，v1 的路由完全不受影响。

可观测性：版本感知的 metrics

模型迭代过程中真正让人头疼的不是”加版本”，而是”下版本”——你怎么确认 v1 真的没人用了，可以放心删？这就要求 metrics 必须按版本天然分开。

我们的做法是：每个 API 版本拥有自己的 MetricsRegistry 实例，通过 Prometheus 的 subsystem 命名来隔离。

_METRIC_NAMESPACE = ""

class MetricsRegistry(BaseModel):
    model_config = ConfigDict(arbitrary_types_allowed=True)
    predict_time: Histogram
    result_count: Counter

_registries: dict[str, MetricsRegistry] = {}

def get_metrics_registry(version: str) -> MetricsRegistry:
    if version in _registries:
        return _registries[version]
    subsystem = "api" if version == "v1" else f"api_{version}"
    registry = MetricsRegistry(
        predict_time=Histogram(
            name="predict_time",
            documentation="Time taken to run a prediction",
            namespace=_METRIC_NAMESPACE,
            subsystem=subsystem,
            buckets=tuple(2**i * 1e-3 for i in range(13)),  # 1ms ~ 4s
        ),
        result_count=Counter(
            name="predict_result_total",
            documentation="Number of results",
            namespace=_METRIC_NAMESPACE,
            subsystem=subsystem,
            labelnames=["label"],
        ),
    )
    _registries[version] = registry
    return registry

v1 的指标叫 _api_predict_time，v2 的叫 _api_v2_predict_time。在 Grafana 里天然隔离，不需要额外加 label。

为什么不用 label 区分版本？因为 Histogram 的 time() context manager 不支持直接传 label，你得先 .labels(version=...) 再 .time()，每个调用点都要记得传，容易漏。而 subsystem 方案是在注册时就确定了，调用侧完全无感。

在每个版本的 router.py 的 register_router 里通过一个小 wrapper 注入：

# v1/router.py
def _get_v1_metrics() -> MetricsRegistry:
    return get_metrics_registry("v1")

def register_router(app: FastAPI) -> None:
    router = APIRouter()

    @router.post("/predict")
    async def predict(
        request: PredictRequest,
        handler: Handler = Depends(get_handler),
        metrics_registry: MetricsRegistry = Depends(_get_v1_metrics),
    ) -> list[PredictResponse]:
        with metrics_registry.predict_time.time():
            results = await asyncio.to_thread(handler.predict, request)
            if results:
                metrics_registry.result_count.labels(label=results[0].label).inc()
        return results

    app.include_router(router)

除了自定义 metrics，还有一层全局的 HTTP 自动打点——用 prometheus-fastapi-instrumentator，它自带 handler label 可以按路径过滤，不需要按版本拆：

def mount_health_routes(app: FastAPI) -> None:
    Instrumentator(
        should_instrument_requests_inprogress=True,
        inprogress_name="requests_in_progress",
        inprogress_labels=True,
    ).instrument(
        app,
        metric_namespace="",
    ).expose(app)
    app.add_api_route("/health", health([]))

最终一个同时跑 v1 和 v2 的服务，/metrics 端点会输出：

指标名	类型	来源
`_api_predict_time`	Histogram	v1 自定义
`_api_predict_result_total`	Counter	v1 自定义
`_api_v2_predict_time`	Histogram	v2 自定义
`_api_v2_predict_result_total`	Counter	v2 自定义
`_http_requests_total`	Counter	Instrumentator
`_http_request_duration_seconds`	Histogram	Instrumentator
`_requests_in_progress`	Gauge	Instrumentator

自定义指标按版本隔离，HTTP 指标全局共享。下线 v1 的时候，看一眼 rate(_api_predict_time_count[5m]) 是不是零，决策成本几乎为零。

日常开发的规矩

几个项目下来攒出来的几条不成文规定，后来都被强制写进了项目模板。

分支策略

一条规则，没有例外：

NEVER commit directly to main. All changes go through feature branches and PRs.

分支命名：feat/ 或 fix/，通过 gh pr create 或 GitHub Web UI 创建 PR，CI 过了再合。不管是新功能、bug fix 还是改个配置文件，都走这个流程。这条规则的意义不在 code review 本身，而是它强制了每一次变更都要走 CI——而 CI 是这套体系里所有约束的最终防线。

提交前检查

每次 commit 前跑这三条：

1
2
3

uv run ruff check src/ scripts/ --fix
uv run ruff format src/ scripts/
uv run ty check

ruff 负责 lint 和格式化，ty（Astral 出的新一代 type checker）负责类型检查。这三条同时也会出现在 pre-commit hook 和 CI 里——本地、commit、CI 三道关口跑同一组命令，保证不会出现”本地通过 CI 挂”或者”CI 通过本地挂”的尴尬。

测试实践

改了 app.py、handler.py、config.py、metrics.py 这些核心文件之后，必须跑测试：

1	uv run pytest test/ -v

测试用 scope="session" fixture 避免每个 test case 都重新加载模型（加载一个 transformer 模型可能要几十秒）：

@pytest.fixture(scope="session")
def client():
    with TestClient(app) as c:
        yield c

GPU 相关的测试通过环境变量控制，在 import 之前就设好：

1 2	import os os.environ["_TORCH_COMPILE"] = "false" # 测试时跳过 torch.compile

每个 endpoint 至少要覆盖：happy path、默认参数、参数变体、422 校验、结果唯一性。

发版流程

版本号维护在 src//__init__.py 里，hatchling 自动读取。整个发版流程被刻意做得很无聊：

更新 __version__
合并到 main
在 GitHub 上创建 Release（不要手动打 tag）
GitHub Release 自动创建 tag，触发 docker-release CI 构建生产镜像

无聊就是稳定。人为干预越少，事故面就越小。

工具链与镜像

工具链

我们的标准工具链：

包管理：uv + pyproject.toml + uv.lock，构建后端用 hatchling
Lint：ruff（check + format 一把梭）
类型检查：ty
测试：pytest
Pre-commit：prek（pre-commit 的高性能替代）

pyproject.toml 里的工具配置：

[dependency-groups]
dev = [
    "pytest>=8.0.0",
    "ruff>=0.4.0",
    "ty>=0.0.19",
]

[tool.ruff]
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "W", "A", "PLC", "PLE", "PLW", "I", "C"]

[tool.pytest.ini_options]
testpaths = ["test"]

每个项目有一个标准 Makefile（注意 Makefile 的缩进必须是 tab）：

install:
    uv sync --frozen --no-install-project

format:
    uv run ruff format .
    uv run ruff check --fix .
    uv run ruff check --select I --fix .

lint:
    uv run ty check

test:
    uv run pytest

dev:
    $(MAKE) install
    uv run fastapi dev src//app.py

make format && make lint && make test，三板斧走完就可以提交。

Dockerfile

GPU 服务和 CPU 服务的 Dockerfile 不太一样，但有几个共同原则：

两阶段依赖安装：先 uv sync --frozen --no-install-project（只装依赖，利用 Docker 层缓存），再 ADD . /app && uv sync --frozen（装项目本身）
挂载 uv 缓存：--mount=type=cache,target=/root/.cache/uv
构建时健全检查：python -c "import ; print(.__version__)"，在 build 阶段就发现 import 错误
entrypoint 调 CLI：不直接调 uvicorn，而是调 entrypoint.sh → CLI serve 命令——这样 host/port/api-version 这些运行时参数就不会散在 Dockerfile / k8s manifest / shell 多个地方

GPU 服务基于 nvidia/cuda 镜像：

FROM nvidia/cuda:-cudnn-runtime-ubuntu24.04 AS base

COPY --from=ghcr.io/astral-sh/uv: /uv /uvx /bin/

WORKDIR /app

# Stage 1: deps only
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --frozen --no-install-project

# Stage 2: project
ADD . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen

EXPOSE 8000
CMD ["/app/entrypoint.sh"]

# Sanity check
RUN python -c "import ; print(.__version__)"

CPU 服务用多阶段构建，运行时镜像不带 uv 和构建工具，还跑非 root 用户：

# Build stage
FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_NO_DEV=1

# ... install deps and project ...

# Runtime stage
FROM python:3.12-slim-bookworm

RUN groupadd --system --gid 999 nonroot \
    && useradd --system --gid 999 --uid 999 --create-home nonroot

COPY --from=builder --chown=nonroot:nonroot /app /app
USER nonroot

CMD ["/app/entrypoint.sh"]

GitHub Actions

三条流水线分工明确：

# lint-and-test：push to main 和 PR 时触发
on:
  push:
    branches: [main]
  pull_request:

# docker-build：PR 时触发，验证 Docker 构建是否通过
on:
  pull_request:
    branches: ["main"]

# docker-release：v* tag 时触发，构建并推送生产镜像
on:
  push:
    tags: ["v*"]

PR push 触发构建验证，GitHub Release 创建 tag 触发生产镜像发布。整个链路自动化，人只需要点一下 Release 按钮。

怎么把这些经验落到下一个项目里

写到这其实想讲的核心都讲完了——那一串配置分层、registry 工厂、版本铁律、版本感知 metrics、CI/Docker 模板，每条背后都是某次具体的踩坑或者某次”诶我们上个服务好像也这样写过”的瞬间。

但写到第四第五个项目我们意识到：经验如果只活在某个人的脑子里，或者只在 wiki 上以”请参考某某规范”的形式存在，那它就只是一种”祝愿”——祝愿下一个起项目的同学读过、记得、并且在赶进度的时候还愿意按规矩来。这个祝愿命中率不高。

所以最近我们把这些经验沉淀成了一组 Claude Code Skill，按”项目脚手架 / 模型演进 / 日常维护 / CI 与镜像”四块拆开，写成了 AI 可以直接执行的指令。下次再起一个新的 AI Service，”帮我加一个 v2 的接口”这种话就直接对应到一组按规范操作的步骤——加新 router、加新 handler、加版本感知的 metrics、不碰已有接口。比起在 wiki 上写规范然后祈祷大家都读了，这种方式靠谱得多。

不过 skill 只是这套经验的一种载体——核心其实还是上面那些设计。哪怕你完全不用 Claude Code，把这些规则当成项目模板或者 cookiecutter 来用，也是一样的效果。

差不多就这样，希望对有类似需求的团队有点参考价值。

怎么样 tracing 你的 SQL？

2026-02-22T10:49:00.000Z

过年是个好时候，可以猛猛干活或者看论文。不过上了几天磨，看了几天论文后觉得还是需要整点活

所以这篇文章来聊聊一个经典话题，How to trace your SQL？

正文

在 OpenTelementry 这一套开始铺展开来后，我们对于代码整个生命周期的 tracing 有了一个较为成熟的方案。包括各类 auto-instrumentation 的库，能够让我们在不修改代码的情况下就能对整个调用链进行 tracing。

但是始终有一朵乌云盘绕着 Tracing 世界的大厦上，我们怎么样将 SQL 的执行如同业务代码一样从黑盒中拆出来

在现阶段，我们对于整个 Tracing 的引入都是在做加法，我们选择构建一个 context，注入一些 metadata，让代码中不同的环节都可以获取到上下文。但是还是有一个问题，怎么样在 SQL 中做加法呢？

最直观的想法是，我们可以尝试一个类似机制

begin;
set saka.tracing_id = '1234567890';
select * from users where id = 1;
commit;

我们可以在 SQL 中设置一些 tracing_id 之类的东西，这样我们就可以在明确一个事务的上下文了。但是这个方案有一个问题，这会改变我们使用 SQL 的 pattern，我们需要在每个 SQL 语句前面都加上 set saka.tracing_id = ‘1234567890’ 这样的东西，这样就会导致我们在代码中需要修改大量的 SQL 语句，这显然是不可行的。

那么另外一种方式实现的我们可以将 tracing 注入到 SQL 中，something like this:

1	select * from users where id = 1 /* tracing_id: 1234567890 */;

那么怎么做？

Google 提出了一个通用的方案 or 叫一个事实上的的标准吧，叫作 SQLCommenter，它的核心思想就是通过 Hook ORM 等手段，让我们尽可能简单的在 SQL 中注入一些 comment，这些 comment 中包含了 tracing/Custom Tag 的信息，这样我们可以将元数据注入的成本降到最低。

那么我们来根据 SQLCommenter 的方案来看看我们怎么样在 Python 中实现这个功能，

以 pymysql 为例，我们需要实现这个非常简单

from pymysql.cursors import SSCursor, SSDictCursor
from flask import g

from main.utils.context import INJECT_SQL_COMMENT, TRACE_ID
from main.utils.ip_utils import local_ip

try:
    CURRENT_IP = local_ip()
except:
    CURRENT_IP = "127.0.0.1"


def inject_meta_info(query: str) -> str:
    if INJECT_SQL_COMMENT.get():
        if TRACE_ID.get() != "None":
            trace_id = getattr(g, "TRACE_ID")
            sql_comment = f"/*X-Amzn-Trace-Id={trace_id}*/"
            query = f"{sql_comment} {query}"
    query = f"/*source_ip={CURRENT_IP}*/ {query}"
    return query


class CustomSSCursor(SSCursor):
    def execute(self, query: str, args: Any = None) -> int:
        return super(CustomSSCursor, self).execute(inject_meta_info(query), args)


class CustomSSDictCursor(SSDictCursor):
    def execute(self, query: str, args: Any = None) -> int:
        return super(CustomSSDictCursor, self).execute(inject_meta_info(query), args)

然后我们在使用时，注入自定义的 Cursor 就好了

Python 的生态还是幸福，但是很可惜，我现在是被迫在写 Node.js 的代码了，Node.js 的生态就没有那么幸福了。由于历史原因，我们现在用的是极为美味的 Prisma 作为 ORM。那么我们需要在 Prisma 来看一下怎么样注入 SQL Comment。

首先在 Prisma 最新的 v7.x 版本中，Prisma 本身实现了 SQLCommenter 的功能，something like this:

import { queryTags, withQueryTags } from "@prisma/sqlcommenter-query-tags";
import { PrismaClient } from "../prisma/generated/client";
const prisma = new PrismaClient({
  adapter,
  comments: [queryTags()],
});
// Wrap your queries to add tags
const users = await withQueryTags({ route: "/api/users", requestId: "abc-123" }, () =>
  prisma.user.findMany(),
);

最终会生成类似这样的 SQL

1	SELECT ... FROM "User" /requestId='abc-123',route='/api/users'/

OK，很不错，是预期内行为

但是问题在于 Prisma V7 是一个极为屎一样的版本，我们完全无法如品鉴母鸡卡一样品鉴这个功能。因为性能问题（v7 比 v6 慢了 30%-40%），我们完全无法在生产环境中使用 v7 的版本，所以我们只能在 v6 中实现这个功能了。

在 Prisma v6 中，Prisma 数据映射部分和核心的 Query Engine 是完全分开，他们通过走 NAPI-RS 进行通信，而他们自定义了一套 json based 的传输协议，协议样例如下

{
  "modelName": "User",                    // 可选，raw query 不需要
  "action": "findMany",                   // 操作类型
  "query": {                              // 查询详情
    "arguments": {                        // where/orderBy/take 等
      "where": { "email": { "contains": "prisma.io" } }
    },
    "selection": {                        // 字段选择
      "$scalars": true,
      "$composites": true,
      "posts": {                          // 关联查询嵌套
        "arguments": {},
        "selection": { "$scalars": true }
      }
    }
  }
}

而在这一次，我想实现类似官方的语义

return this.prisma.post.findMany({
  take: 100,
  sqlComments: getSqlComments(req),
});

OK，那么我们直接用一个流程图来输出一下对应的实现流程

flowchart TD    subgraph TS["TypeScript (prisma repo)"]        A["用户代码
prisma.user.findMany({sqlComments: {...}, where: {...}})"]        B["getPrismaClient.ts :: _executeRequest()
调用 serializeJsonQuery()"]        C["serializeJsonQuery.ts :: serializeJsonQuery() [改动1]
提取 sqlComments 放入 JsonQuery 顶层
输出: {modelName, action, query, sqlComments}"]        D["RequestHandler.ts :: singleLoader / batchLoader
调用 _engine.request(protocolQuery, {traceparent})"]        E["LibraryEngine.ts :: request()
JSON.stringify(query) + JSON.stringify({traceparent})
engine.query(queryStr, headerStr, txId)"]    end    subgraph FFI["C ABI / NAPI FFI 边界"]        F(("FFI"))    end    subgraph Rust["Rust (prisma-engines repo)"]        G["QueryEngine::query()
解析 body_str → RequestBody
从 header 提取 traceparent"]        H["RequestHandler::handle() [改动2]
body.into_doc() → (QueryDocument, SqlCommentsVec)
组装 QueryContext {traceparent, sql_comments}"]        I["Single 查询
QueryContext::new(traceparent, sql_comments#0)"]        J["Batch 查询
每个 operation 独立 QueryContext
共享 traceparent，各自 sql_comments"]        K["JsonBody::into_doc() [改动3]
JsonSingleQuery 新增 sql_comments 字段
extract_sql_comments() → Vec<(String,String)>"]        L["QueryExecutor::execute() [改动4]
traceparent → query_context: QueryContext
管道传递: execute_operation → interpreter → read/write"]        M["interpreter :: read.rs / write.rs [改动5]
query_context.sql_trace() → SqlTrace {traceparent, sql_comments}"]        N["ReadOperations / WriteOperations [改动6]
traceparent: Option<TraceParent> → trace: SqlTrace"]        O["sql-query-connector :: connection.rs [改动7]
Context::new(&connection_info, trace)"]        P["sql-query-builder :: read/write/select [改动8]
构建 Quaint AST
调用 .add_trace_id(ctx)"]        Q["sql_trace.rs :: add_trace_id() [改动9]
build_trace_comment(sql_comments, traceparent)
1. sql_comments 按 key 字母排序
2. key/value URL 编码, 格式: key='value'
3.traceparent sampled 则追加
4. 逗号拼接, 调用 .comment(result)"]        R["Quaint AST :: .comment(...)
渲染时在 SQL 末尾追加 /* ... */"]    end    S["最终 SQL
SELECT ... FROM "User" WHERE ...
/* controller='UserController',route='%2Fapi%2Fusers' */"]    A --> B --> C --> D --> E    E --> F --> G --> H    H --> I --> L    H --> J --> L    H -.->|内部调用| K    L --> M --> N --> O --> P --> Q --> R --> S

OK，在调整完 FFI ，扩展完 Query Engine 后，我们再调整一下 Prisma 代码生成相关的部分即可

然后我们可以在业务代码中这样使用

function getSqlComments(req: Request): Record<string, string> {
  const comments: Record<string, string> = {};

  // Request info
  comments.route = req.path;
  comments.method = req.method;
  if (req.route?.path) {
    comments["route_pattern"] = req.route.path;
  }

  // OpenTelemetry trace context
  const span = trace.getSpan(context.active());
  if (span) {
    const ctx = span.spanContext();
    comments.traceparent = `00-${ctx.traceId}-${ctx.spanId}-0${ctx.traceFlags}`;
  }

  return comments;
}

@Controller()
export class AppController {
  constructor(private readonly prisma: PrismaService) {}

  @Get()
  getHello(): string {
    return `Hello World!`;
  }

  @Get("posts")
  getPosts(@Req() req: Request) {
    return this.prisma.post.findMany({
      take: 100,
      sqlComments: getSqlComments(req),
    });
  }

  @Get("posts/:id")
  getPostsById(@Param("id") id: string, @Req() req: Request) {
    return this.prisma.post.findUnique({
      where: { id },
      sqlComments: getSqlComments(req),
    });
  }

  @Get("posts-with-comments")
  getPostsWithComments(@Req() req: Request) {
    return this.prisma.post.findMany({
      take: 100,
      include: {
        comments: true,
      },
      sqlComments: getSqlComments(req),
    });
  }

  @Get("posts-with-comments/:id")
  getPostWithCommentsById(@Param("id") id: string, @Req() req: Request) {
    return this.prisma.post.findUnique({
      where: { id },
      include: {
        comments: true,
      },
      sqlComments: getSqlComments(req),
    });
  }

  @Post("posts")
  createPost(@Body() body: { title: string; body: string }, @Req() req: Request) {
    return this.prisma.post.create({
      data: {
        title: body.title,
        body: body.body,
      },
      sqlComments: getSqlComments(req),
    });
  }
}

然后我们可以得到这样的 SQL

2026-02-22 07:56:38.681 GMT [190] LOG:  execute s412381: SELECT "public"."Post"."id", "public"."Post"."title", "public"."Post"."body", "public"."Post"."createdAt", "public"."Post"."modifiedAt" FROM "public"."Post" WHERE ("public"."Post"."id" = $1 AND 1=1) LIMIT $2 OFFSET $3 /* method='GET',route='%2Fposts%2Fff4ccd6d-2c15-4979-a5f3-0c27e4e2f169',route_pattern='%2Fposts%2F:id',traceparent='00-e984180b391935fbdf2b1e1f6f3b2b12-1286ff6754fbbc57-01' */
2026-02-22 07:56:38.681 GMT [190] DETAIL:  parameters: $1 = 'ff4ccd6d-2c15-4979-a5f3-0c27e4e2f169', $2 = '1', $3 = '0'
2026-02-22 07:56:38.681 GMT [190] LOG:  execute s412382: SELECT "public"."Post"."id", "public"."Post"."title", "public"."Post"."body", "public"."Post"."createdAt", "public"."Post"."modifiedAt" FROM "public"."Post" WHERE ("public"."Post"."id" = $1 AND 1=1) LIMIT $2 OFFSET $3 /* method='GET',route='%2Fposts%2Fff4ccd6d-2c15-4979-a5f3-0c27e4e2f169',route_pattern='%2Fposts%2F:id',traceparent='00-fa7f8686b25c2efe8942718207c28079-bbeb59140c47895c-01' */
2026-02-22 07:56:38.681 GMT [190] DETAIL:  parameters

通常来说，这样的语句已经能在我们常见的数据库调试流程中已经起到很大的帮助了，可以查到某一条慢 SQL 的来源，上下文等信息

但是这就够了吗？我们能不能把数据库也接入到 OpenTelemetry 的 tracing 体系中来呢？我们能不能在数据库的层面上看到整个调用链的 tracing 信息呢？

那没有问题的，这里以我现在更熟悉一点的 PostgreSQL 生态举个例子

Datadog 之前有一个工作，他们在 PostgreSQL 上实现了一个扩展叫作 pg_tracing https://github.com/DataDog/pg_tracing

通过使用 PostgreSQL 的一些扩展点

post_parse_analyze_hook
planner_hook
ExecutorStart_hook
ExecutorRun_hook
ExecutorFinish_hook
ExecutorEnd_hook
ProcessUtility_hook
xact_callback

然后配合一些环形缓冲区和共享内存，就可以在数据库层面上实现一个 tracing 的功能了，这样我们就可以将 PostgreSQL 接入到 OTEL 生态中了。当然这个库的实现里面有不少小技巧，改天可以单独写个文章来聊聊

MySQL 虽然内部的实现是一坨，但是我想如果要在 MySQL 上实现类似的功能应该工作量也不会太大，

最终的效果如下所示

差不多就这样

总结

大家都在写各种 AI/Agent 的文章的时候，我还在搞点这种 old school 的东西。恍惚间看到我的前方有一个巨大的风车。But anyway，我喜欢这些东西，这就够了

祝大家看的开心。

笑ってほしくて

2026-01-01T15:00:00.000Z

每年都会选一句话作为年终总结的标题，去年是“本当の僕らをありがとう”，今年我选择“笑ってほしくて”。

这句话出自《葬送的芙莉莲》的片尾曲《Anytime anywhere》。

愿你露出笑容

可能是我想对逝去之人，逝去的猫说的，可能也是他们想对我说的

也是我想对所有看到这篇文章的人说的

开篇

实际上一度想放弃写这篇文章，因为总是会害怕。今年在生死边缘搏战了许久。但终究是没有挽留住。每次想起点点滴滴时，总会不免破防

但是就如同歌词所说

こんなに胸が痛いのは/胸口传来的痛楚
あなたといた証かな/是与你同在的证明

那么所以还是要写点什么来纪念这特殊的2025, 也是 saka 的2025

生活

今年生活中最大的事件就是猫咪的过世。小熊是我们在2023年从小区收养的猫咪。一最开始就给上了强度，重度口炎+肾衰。然后后续情况稳定后带回家进行日常的治疗。

而在24年经过一整年的折腾（开腹两次，病危三次），25年年初医生终于说可以两月复查后，我们以为小熊还能陪伴我们很长时间

但是事与愿违，在6月份过完到家纪念日后，小熊的状态就时好时坏。在8月份最后一次住进医院后，虽然期间还是有好转的时候，但是整体情况还是急转直下。最终我们选择放他离开

很难说，小熊的离去对我的打击是怎么样的。我同事说感觉我从中恢复过来还蛮快的。不过中个泪流时分也只有自己知道（其实写这篇文章的时候也是在默默流泪）

今年也是我好友离开我的第五个年头。恍惚间，我已经比他大了

君埋泉下泥销骨，我寄人间雪满头

不得不说古人是真的会写啊。

聊点开心的，今年我的日常生活比去年又丰富了很多。史无前例的，saka 获取了，他的，第一个全成就游戏！所以 2025 saka 严选最佳游戏的是？

是《空之轨迹 1st 重制版》

对不起 P5R，我也很爱你的（

今年也还在继续的拍照，买了 Z135 F1.8S 圆神，Z105 F2.8 百微，Z35 F1.2S 三个头，在摄影器材的路上越走越远，整体的快门数快 10w 了，整体以猫狗为主。某种意义上来说，我很庆幸用相机记录下了小熊这几年最精彩的时光

今年对于我来说另一个在最大的改变就是，我去了出来能去的最远的地方——日本

我精神图腾中的几大支柱（奥特曼，摇曳露营）都发源自日本，而我第一次出国便是去日本（某种意义上算冥冥之中的一种巧合）

在日本出差的这两周里，解锁了很多新奇的体验。去秋叶原爆米，去抚子的故乡爆米，在出租车上和司机一起唱奥特曼主题曲，和好友一起逛街爆米，和同事一起去热海合宿，见了好看的海边，去了沼津，吃了好吃的海鲜饭等等等。

某种意义上今年开启了我过去很多人生中未曾想过的体验。也让我坚定的了一个想法、

人与人的欢乐实际上是可以相通的

感情

感情进入了第七个年头。如果要为今年的感情沉淀一个主题的话，那可能就是四个字，生死相依

小熊走前的一个月，我们在医院陪护。仪器的滴鸣声，时而奔走的医护。时而逝去的生命。那种氛围真的很压抑

这种时候，两个人的相互的守望，可能是枯燥且祈祷着奇迹发生的日子里，已然发生少数的奇迹。

小熊离去后，我们两也久违的带着小狗出远门去散心，去一起给小狗拍了很多好看的照片，一起救助了其余的小猫，一起给医院捐献了设备。

能在人群中遇到彼此守望的伴侣，本身已然是奇迹

工作&技术

今年年初在朋友邀请下，我加入了一家 AIGC 创业公司，负责一些 infra 上的工作。这算是我职业生涯一个全新的转折点。

如果说这里面最大的感受是什么，那就是我可能在之前聊过的，身份转变所带来的更多的责任与事情。

先聊聊务虚的部分，往常我只需要 focus 在具体的事情的落地，可能其余的东西都会有人帮我兜底。而我今年开始成为一个试图去帮助其余同事能够更好落地事情的人。说实话这种身份上的转变实际上会让你有很多想法转变。就如同我和团队成员 1:1 沟通时我一直在问的一个问题一样“你觉得我还能做什么，能帮助你落地现在的事情？”。很多时候我去思考事情的时候，我不能仅考虑这个事情本身，而是我需要去思考这个事情怎么样才能够帮助团队/同事实现更好的价值。

与此同时，我的职责以及角色会变得更多元化。这一点也是需要走出舒适区。比如今年我在公司做了很多涉及到 DBA 和搜索相关的工作。严格来说，这一部分工作其实离我的好球区实际上很远，但是如果一个事情是重要的，同时当下没有人比我更擅长这件事（换句话说让我做不会是最坏的结果），那么我就需要去承担起这份责任。

接着是务实的部分，如果要说今年很有成就感的事情的话，就是在加入公司后，从头开始做稳定性相关的建设，且收获颇丰。无论是在多次互联网 infra 大范围 crash 后我们能在最短的时间内恢复业务，还是给我们的业务带来了实际上的稳定性与性能提升。我所做的工作都能直接的作用在用户价值上。某种意义上来说，这也是人生的一件幸事

以上都是好的 part，坏的 part 也不是没有，那就是

教练，我想写代码

我现在写代码基本上只能靠工作之外写写代码来保持手感和练手，呜呜呜呜呜，我真的好想转岗去写代码啊（

不过这也不算坏事，我现在非常享受业余时间写代码的生活，所以今年在社区的贡献比去年多了不少，包括把自建图床项目的代码拾掇了很多，给 CPython 的 JIT 贡献了不少代码。也让自己名字第一次在官方文档里留下了痕迹。

如果说明年有什么想法的话，简单的说就是在工作上带好团队，能够继续突破我自己的舒适区。以及希望我能给 CPython 下一阶段的 JIT 贡献更多的代码（其实有一些想法，正好趁着元旦假期梳理一下）

啊，突然想起，我26年还得好好学学 GPU 相关的编程的东西，说实话学习新的东西真的是非常开心的一件事！

关于 AI

算是凑个热点，聊聊我对 AI 的看法。

很多人都会陷入一种焦虑，“AI 会不会替代我自己”

我自己的看法愈发的清晰，AI 时代会让人的价值更大，而不是被消泯

这里的逻辑很简单，AI 让一切都变得更为高效，内容的生产更为高效，开发效率更为高效，公司的形态更为灵活，在这种情况下，传统的很多东西在 AI 时代都面临的新的挑战。比如我举几个例子

对于愈发高效的内容生产效率，UGC 等形态的 AI Startup 会面临越来越大的 anti nsfw 的合规的挑战
而对于算力的愈发的渴求，边缘 GPU 算力的管控与接入也愈发成为一个重要的课题

AI 带来的生产力提升其实会让人的价值在这个时代更为凸显，而不是被消解

总结

差不多就是这样吧。过去一年有过不少很多的泪水，也有过很多的难眠之夜，也有过很多的快乐。

坦白来说能挺过这一年，是因为身边有着很多的陪伴，有我女朋友，有一群好朋友，有一群好同事。

每一个人的陪伴加上生活中辛酸苦辣甜汇聚在一起就成为了2025年的 saka，或者是 saka 的2025。

曾经想对于以后试图列出很多的展望，但是死生经历过一轮后，觉得剩下的都不太重要了

如同标题一样，

笑ってほしくて/愿你露出笑容

愿我们每一个人都能以笑容度过2026年的每一天

一万年太长，我们只笑今朝（

新年快乐！

成为榜样，但不要成为偶像

2025-10-02T20:00:00.000Z

最近刚把空轨 1st 打通关。差不多国庆假期也要结束了，要开始准备接下来的学习和工作了。趁着这个机会，写点东西，当个迟到的 PyCon China 2025 的总结吧

正文

其实去年在结束去年的会议后，我就在考虑要不要彻底退出 PyCon China 一段时间。原因其实也很简单，太累了。不过我向来是个很拖延癌的人。恰逢那时候正在职业的变动期，所以想着要不要再看看。

今年来了一家 AIGC 公司做 infra，说实话我干的还蛮开心的。每天都会学习新的东西。状态相比于去年好了不少（除了每天都需要和该死的 Any 做斗争），所以一度准备继续参加今年的 PyCon China

不过到了筹备期后，原本的计划突生变故。陪伴需求的猫咪病危，去世。一直在医院通宵，陪护以及最终要面临的生死别离。对我的精神和体力造成了极大的消耗。是否继续参加今年的 PyCon China 也成为一个问题。

不过最终还是决定参加了。今年突然出版社那边给我加了一个活，我翻译的书要在现场签售。这就又成为我心里一个新的疑问：嘛，真的会有人来买吗？

嘛，其实这也是每年在参加 PyCon 时都会有的自我怀疑，我真的有资格在这里吗？我讲的东西真的会有人听吗？

不过做了最终的决定那么就继续做吧。所以今年还是给了一个白银赞助+一个主题演讲。

时间过得很快，转眼到了会议前一天，临上飞机前我还在被 AWS 的傻叉 OpenSearch 折磨。下飞机后 yihong，piglei，空想家，jay 他们去开 impact 了。好好好开 impact 不带我是吧。我就孤零零的跑去了酒店。有人演讲前12h文件夹都还没建是谁我不说。

在酒店顶了几个小时把 PPT 赶完，工作收个尾。勉强睡了2h，然后就去会场了。

今年比较轻松的是早上的主持不用我了，我只要负责暖场一下。不过临开场前发现 C 会场的 PPT 还没收，然后摇了晚枫帮忙。

暖场还是我每年的保留节目，Saka 三问.jpg:

现在还在写 Python 的举个手
现在还没写 Python 的举个手（拖出去
用 2.7 的举个手

看起来效果还不错。暖场完我就跑出去了。不过卧槽，今年怎么这么多人来单杀我，~~妈耶社恐狂哭了~~。

不过说实话，在经历生死一圈后，和老朋友打打闹闹，认识一下新朋友，还是蛮开心的。特别是很多人过来说我影响了他们，我是他们的偶像，他们从我的博客和分享里学到很多的时候。我一直以来的疑惑也得到了解决。虽然说人的自我认同最理想应该是内源性的，但是大家的认可也真的会让我很开心。

哦对了，还有很多人说他们也很喜欢摇曳露营！

值得一提的是，我司的宝藏同事从日本来一起面基了（是的，我们是 Remote 公司），还给我带了手办

当然有某屑 HR 说要来参会结果早上睡过了，是谁我不点名了

上午的时间其实过去的很快，很快就结束了。然后我就来到了签售地方。出乎意料的，有很多人都来了，有来捧场的老朋友们，有刚刚线下刚对上号的新朋友们。大家一起打打闹闹，我用我的丑字写了很多祝福，也有很多杂话。要说哪一句最真心，那我觉得是“不要用 Next.js”罢。

签售完火急火燎的吃完盒饭，抽烟的时候遇到师父，~~我开始基情的抚摸他的胸肌~~，这可能算是每次我们师徒相聚的仪式感了。问他了一个问题：你现在还需要我帮你收尸么？这个出处源自于我们之前约好他要是自杀我会来帮他处理后事。他想了想说，我们不如想想怎么活到150岁吧。很好，很强大，我很喜欢的回答。那我就当不会了。

后面纯爷也来加入了聊天，我顺便向他倾诉了一下把 PostgreSQL 当 MongoDB 用的痛苦。纯爷也只能用爱莫能助的眼光看看我

下午 C 会场实际上因为我需要抽烟提神迟到了几分钟，yihong 帮我暖场缓解尴尬，不得不给他磕一个，以及 yihong 抱起来手感很好，建议网友有条件的可以去试试

下午到我的时候其实因为控场的原因给我的时间比预期的要短一些，所以我临时调整了一些内容。要上去讲的时候，发现很多人都从其余会场赶了过来，算是非常满足了。在 QA 的时候，我给大家说我现在在一家用着 Node.js 写着 Any，把 PostgreSQL 当 MongoDB 用，以及还用着 GraphQL 的公司工作。大家一片会心一笑。我想我们屑 HR 大概今天在现场招不到人了罢

下午的时候，屑 HR 和我们在上海的另外一位同事也来，带来了我需要~~昏睡红茶~~零度可乐。说实话在一个 Remote 公司大家面基的机会还是很少的。理所当然，我成为公司群内表情包的一部分。该考虑下找屑 HR 要肖像费了

晚上散场后，去和沪爷阿蔡以及几个同事一起组了一个局。不过说实话拉着明天要去霓虹的两位同事去吃日式拉面算不算另一种职场 80？笑死

总结

说实话今年 PyCon 的当天是我这两个月最快乐的一点，也许在很多年后我记不得了今年讲了什么，但是还会记得当天最简单快乐。

嘛，从18年到现在，7年过去了，我也从一个刚出校园的年轻人变成了一个老登。似乎很多东西都在变，但是很多东西又没变。

我还是很菜，但是我好像比之前影响了更多的人，帮到了更多的人？我还有很多东西不会，但是我好像能学的东西也更多了？还是会经历很多痛苦，很多迷茫，很多挣扎。但是生活似乎也还是一如既往的有着无限的希望与美好？

回北京后，一次吃饭时，我给我女朋友说，你知道吗？很多人说我是他们的偶像。我女朋友说：不，你是他们的榜样

是的，成为榜样，但是不要成为偶像。

这篇文章差不多写到这里。要到中秋了，除了祝大家中秋快乐，阖家欢乐以外。也祝大家每个人都能在这个快速迭代的世道里永葆初心。用 Piglei 老师的话说就是“老而不登”

这个世界唯有爱，希望，奥特曼与摇曳露营不可辜负，抚门！

Further Performance Evolution in Python 3.14: Tail Call Interpreter

2025-07-02T15:49:00.000Z

I’ve been overwhelmed by security work lately, so let me switch to something lighter to relax my mind.

Python 3.14 has officially introduced a new mechanism called Tail Call Interpreter (Made by Ken Jin), which is undoubtedly another major milestone that lays the foundation for the future.

Main Content

Before discussing Python 3.14’s Tail Call Interpreter, we need to talk about the most basic syntax in C - switch-case.

switch (x) {
    case 1:
        // do something
        break;
    case 2:
        // do something else
        break;
    default:
        // do default thing
}

What would the final assembly look like for such code? Most people’s first reaction might be to use cmp followed by je, and if it doesn’t match, continue. Let’s compile a version to see.

For this code:

void small_switch(int x) {
    switch(x) {
        case 1: printf("One\n"); break;
        case 2: printf("Two\n"); break;
        case 3: printf("Three\n"); break;
        default: printf("Other\n"); break;
    }
}

The final assembly output would be:

00000000000011f0 :
    11f0:83 ff 02             cmp    $0x2,%edi
    11f3:74 2b                je     1220 
    11f5:83 ff 03             cmp    $0x3,%edi
    11f8:74 16                je     1210 
    11fa:83 ff 01             cmp    $0x1,%edi
    11fd:75 31                jne    1230 
    11ff:48 8d 3d fe 0d 00 00 lea    0xdfe(%rip),%rdi        # 2004 <_IO_stdin_used+0x4>
    1206:e9 25 fe ff ff       jmp    1030 
    120b:0f 1f 44 00 00       nopl   0x0(%rax,%rax,1)
    1210:48 8d 3d f5 0d 00 00 lea    0xdf5(%rip),%rdi        # 200c <_IO_stdin_used+0xc>
    1217:e9 14 fe ff ff       jmp    1030 
    121c:0f 1f 40 00          nopl   0x0(%rax)
    1220:48 8d 3d e1 0d 00 00 lea    0xde1(%rip),%rdi        # 2008 <_IO_stdin_used+0x8>
    1227:e9 04 fe ff ff       jmp    1030 
    122c:0f 1f 40 00          nopl   0x0(%rax)
    1230:48 8d 3d db 0d 00 00 lea    0xddb(%rip),%rdi        # 2012 <_IO_stdin_used+0x12>
    1237:e9 f4 fd ff ff       jmp    1030 
    123c:0f 1f 40 00          nopl   0x0(%rax)

We can see that overall it’s as we expected - continuous cmp followed by continuous je. Now let’s evaluate the complexity here? Oh, time complexity O(n), that’s straightforward.

Damn, for Python with such a huge switch case structure, wouldn’t that be O(n) every time? Wouldn’t that be a performance disaster?

Actually, no. Usually, compilers use different strategies to handle switch case structures based on data type and scale.

Let’s prepare several examples:

void small_switch(int x) {
    switch(x) {
        case 1: printf("One\n"); break;
        case 2: printf("Two\n"); break;
        case 3: printf("Three\n"); break;
        default: printf("Other\n"); break;
    }
}

void dense_switch(int x) {
    switch(x) {
        case 10: printf("Ten\n"); break;
        case 11: printf("Eleven\n"); break;
        case 12: printf("Twelve\n"); break;
        case 13: printf("Thirteen\n"); break;
        case 14: printf("Fourteen\n"); break;
        case 15: printf("Fifteen\n"); break;
        case 16: printf("Sixteen\n"); break;
        case 17: printf("Seventeen\n"); break;
        default: printf("Other\n"); break;
    }
}

void sparse_switch(int x) {
    switch(x) {
        case 1: printf("One\n"); break;
        case 100: printf("Hundred\n"); break;
        case 1000: printf("Thousand\n"); break;
        case 10000: printf("Ten thousand\n"); break;
        default: printf("Other\n"); break;
    }
}

void large_dense_switch(int x) {
    switch(x) {
        case 1: printf("Case 1\n"); break;
        case 2: printf("Case 2\n"); break;
        case 3: printf("Case 3\n"); break;
        case 4: printf("Case 4\n"); break;
        case 5: printf("Case 5\n"); break;
        case 6: printf("Case 6\n"); break;
        case 7: printf("Case 7\n"); break;
        case 8: printf("Case 8\n"); break;
        case 9: printf("Case 9\n"); break;
        case 10: printf("Case 10\n"); break;
        case 11: printf("Case 11\n"); break;
        case 12: printf("Case 12\n"); break;
        case 13: printf("Case 13\n"); break;
        case 14: printf("Case 14\n"); break;
        case 15: printf("Case 15\n"); break;
        case 16: printf("Case 16\n"); break;
        case 17: printf("Case 17\n"); break;
        case 18: printf("Case 18\n"); break;
        case 19: printf("Case 19\n"); break;
        case 20: printf("Case 20\n"); break;
        default: printf("Other\n"); break;
    }
}

void mixed_switch(int x) {
    switch(x) {
        case 1: printf("Case 1\n"); break;
        case 2: printf("Case 2\n"); break;
        case 3: printf("Case 3\n"); break;
        
        case 50: printf("Case 50\n"); break;
        
        case 100: printf("Case 100\n"); break;
        case 101: printf("Case 101\n"); break;
        case 102: printf("Case 102\n"); break;
        
        default: printf("Other\n"); break;
    }
}

void char_switch(char c) {
    switch(c) {
        case 'a': printf("Letter a\n"); break;
        case 'b': printf("Letter b\n"); break;
        case 'c': printf("Letter c\n"); break;
        case 'd': printf("Letter d\n"); break;
        case 'e': printf("Letter e\n"); break;
        default: printf("Other char\n"); break;
    }
}

Then we disassemble and look at the results (I’ll only paste the key parts here):

00000000000011f0 :
    11f0:83 ff 02             cmp    $0x2,%edi      # Compare if it's 2
    11f3:74 2b                je     1220            # Jump to case 2
    11f5:83 ff 03             cmp    $0x3,%edi      # Compare if it's 3
    11f8:74 16                je     1210            # Jump to case 3
    11fa:83 ff 01             cmp    $0x1,%edi      # Compare if it's 1
    11fd:75 31                jne    1230            # If not, jump to default

0000000000001240 :
    1240:83 ef 0a             sub    $0xa,%edi      # Subtract 10 (minimum case value)
    1243:83 ff 07             cmp    $0x7,%edi      # Compare range (17-10=7)
    1246:0f 87 90 00 00 00    ja     12dc           # Out of range, jump to default
    124c:48 8d 15 15 0f 00 00 lea    0xf15(%rip),%rdx # Load jump table address
    1253:48 63 04 ba          movslq (%rdx,%rdi,4),%rax # Get offset
    1257:48 01 d0             add    %rdx,%rax      # Calculate target address
    125a:ff e0                jmp    *%rax          # Indirect jump

00000000000012f0 :
    12f0:81 ff e8 03 00 00    cmp    $0x3e8,%edi    # Compare 1000
    12f6:74 40                je     1338           # If equal, jump
    12f8:7f 16                jg     1310           # If greater than 1000, continue checking
    12fa:83 ff 01             cmp    $0x1,%edi      # Less than 1000, check 1
    12fd:74 49                je     1348           
    12ff:83 ff 64             cmp    $0x64,%edi     # Check 100
    1302:75 24                jne    1328           # If none match, default
    ...
    1310:81 ff 10 27 00 00    cmp    $0x2710,%edi   # Check 10000

0000000000001360 :
    1360:83 ff 14             cmp    $0x14,%edi     # Check if ≤20
    1363:0f 87 53 01 00 00    ja     14bc           # Out of range
    1369:48 8d 15 18 0e 00 00 lea    0xe18(%rip),%rdx # Jump table address
    1372:48 63 04 ba          movslq (%rdx,%rdi,4),%rax # Direct indexing
    1376:48 01 d0             add    %rdx,%rax
    1379:ff e0                jmp    *%rax

00000000000014d0 :
    14d0:83 ff 32             cmp    $0x32,%edi     # Compare 50
    14d3:74 7b                je     1550
    14d5:7f 29                jg     1500           # >50 case
    14d7:83 ff 02             cmp    $0x2,%edi      # ≤50, check small values
    14da:74 64                je     1540
    14dc:83 ff 03             cmp    $0x3,%edi
    ...
    1500:83 ff 65             cmp    $0x65,%edi     # >50, check 100,101,102
    1503:74 5b                je     1560

0000000000001580 :
    1580:83 ef 61             sub    $0x61,%edi     # Subtract ASCII value of 'a'
    1583:40 80 ff 04          cmp    $0x4,%dil      # Check if ≤4 (a-e)
    1587:77 63                ja     15ec
    1589:48 8d 15 4c 0c 00 00 lea    0xc4c(%rip),%rdx
    1590:40 0f b6 ff          movzbl %dil,%edi      # Zero-extend to 32 bit
    1594:48 63 04 ba          movslq (%rdx,%rdi,4),%rax

Here we can see that the compiler handles switch case structures differently based on different data types. Let me summarize this with a table:

Switch Type	Case Count	Distribution	Compiler Strategy	Time Complexity
small_switch	3	Consecutive(1,2,3)	Linear comparison	O(n)
dense_switch	8	Consecutive(10-17)	Offset jump table	O(1)
sparse_switch	4	Sparse(1,100,1000,10000)	Binary search	O(log n)
large_dense_switch	20	Consecutive(1-20)	Standard jump table	O(1)
mixed_switch	7	Partially consecutive	Nested comparison	O(log n)
char_switch	5	Consecutive(‘a’-‘e’)	Character offset table	O(1)

OK, here we find that the final implementation of switch-case varies depending on data types, leading to unpredictability in our final code. So do we have ways to optimize this problem? The answer is yes.

Let’s look at the following code:

#include 

void basic_computed_goto(int operation) {
    static void* jump_table[] = {
        &&op_add,   
        &&op_sub,   
        &&op_mul,   
        &&op_div,   
        &&op_mod,   
        &&op_default
    };
    
    int a = 10, b = 3;
    int result;
    
    if (operation < 0 || operation > 4) {
        operation = 5;
    }
    
    printf("Operation %d: a=%d, b=%d -> ", operation, a, b);
    
    goto *jump_table[operation];
    
op_add:
    result = a + b;
    printf("ADD: %d\n", result);
    return;
    
op_sub:
    result = a - b;
    printf("SUB: %d\n", result);
    return;
    
op_mul:
    result = a * b;
    printf("MUL: %d\n", result);
    return;
    
op_div:
    if (b != 0) {
        result = a / b;
        printf("DIV: %d\n", result);
    } else {
        printf("DIV: Error (division by zero)\n");
    }
    return;
    
op_mod:
    if (b != 0) {
        result = a % b;
        printf("MOD: %d\n", result);
    } else {
        printf("MOD: Error (division by zero)\n");
    }
    return;
    
op_default:
    printf("Unknown operation\n");
    return;
}

We can see that the core operation here is to turn each case of our switch-case into a label, then we use a jump_table to directly jump to the corresponding label. Let’s look at the assembly of the most critical part:

1 2	11d3:48 8d 05 c6 2b 00 00 lea 0x2bc6(%rip),%rax # 3da0 11da:ff 24 d8 jmp *(%rax,%rbx,8)

Here we can summarize that using Computed Goto compared to traditional switch-case has the following advantages:

Reduces the cost of branch prediction fallback
Better instruction cache locality
Reduces the number and overhead of cmp instructions

So how much faster can it be? You can refer to the test results of Computed Goto introduced in CPython, which showed an overall improvement of about 15%.

So is the Computed Goto approach perfect? Actually, no. Currently, CPython’s interpreter ceval.c, which is also currently the largest switch case, has several typical problems:

Computed Goto as a specialized feature of clang and gcc, other platforms have limited benefits
Currently Computed Goto is not mature, different versions of the same compiler may have different issues
Extremely large switch cases cause compilers to not optimize switch cases well enough
We cannot use perf to precisely perform quantitative analysis of per-opcode overhead in our entire process, which will be a big problem in the context of making Python faster

Points 1, 3, and 4 are easy to understand. Let’s look at an example of point 2 (thanks to Ken Jin for providing the example).

In GCC 11, switch-case would generate normal code in certain parts:

738f: movq%r13, %r15
7392: movzbl%ah, %ebx
7395: movzbl%al, %eax
7398: movq(,%rax,8), %rax
73a0: movl%ebx, -0x248(%rbp)
73a6: jmpq*%rax

While in GCC 13-15Beta, it would generate code like this:

747a: movzbl%ah, %ebx
747d: movzbl%al, %eax
7480: movl%ebx, -0x248(%rbp)
7486: movq(,%rax,8), %rax
748e: jmp0x72a0 <_PyEval_EvalFrameDefault+0x970>

72a0: movq%r15, %xmm0
72a5: movq%r13, %xmm3
72aa: movq%r15, %rbx
72ad: punpcklqdq%xmm3, %xmm0
72b1: movhlps%xmm0, %xmm2
72b4: movq%xmm2, %r10
72b9: movq%r10, %r11
72bc: jmpq*%rax

We can see that additional registers were introduced. Computer Architecture 101: additional registers mean additional overhead. Registers are expensive!

So do we have ways to iterate on the extremely large switch case above? Some students might be thinking, since the switch case above is extremely large, why don’t we split it into multiple small functions so that the compiler can have enough context to optimize, and our perf can also precisely analyze the overhead of each function. Wouldn’t that be great?

But other students object: function calls trigger call instructions, which bring additional overhead of register push and pop operations. Won’t this make it slower again?

So can we optimize this? The answer is yes. Many students might have thought of it - tail call.

Suppose we have this code:

__attribute__((noinline)) void g(int x) {
    printf("Value: %d\n", x);
};
void f(int x) {
    return g(x);
}

We can see this assembly:

0000000000001140 :
    1140:55                   push   %rbp
    1141:48 89 e5             mov    %rsp,%rbp
    1144:48 83 ec 10          sub    $0x10,%rsp
    1148:89 7d fc             mov    %edi,-0x4(%rbp)
    114b:8b 75 fc             mov    -0x4(%rbp),%esi
    114e:48 8d 3d af 0e 00 00 lea    0xeaf(%rip),%rdi        # 2004 <_IO_stdin_used+0x4>
    1155:b0 00                mov    $0x0,%al
    1157:e8 d4 fe ff ff       call   1030 
    115c:48 83 c4 10          add    $0x10,%rsp
    1160:5d                   pop    %rbp
    1161:c3                   ret
    1162:66 66 66 66 66 2e 0f data16 data16 data16 data16 cs nopw 0x0(%rax,%rax,1)
    1169:1f 84 00 00 00 00 00 

0000000000001170 :
    1170:55                   push   %rbp
    1171:48 89 e5             mov    %rsp,%rbp
    1174:48 83 ec 10          sub    $0x10,%rsp
    1178:89 7d fc             mov    %edi,-0x4(%rbp)
    117b:8b 7d fc             mov    -0x4(%rbp),%edi
    117e:e8 bd ff ff ff       call   1140 
    1183:48 83 c4 10          add    $0x10,%rsp
    1187:5d                   pop    %rbp
    1188:c3                   ret
    1189:0f 1f 80 00 00 00 00 nopl   0x0(%rax)

The call 1140 instruction is very prominent. This is also an important source of function call overhead.

In modern compilers, there’s a special optimization called tail recursion, where when the last step of a function is calling another function, the compiler can optimize away the overhead of this call.

Let’s test this:

#include 
__attribute__((preserve_none)) void g(int x);
__attribute__((noinline, preserve_none)) void g(int x){
    printf("Value: %d\n", x);
}

__attribute__((preserve_none)) void f(int x) {
    [[clang::musttail]] return g(x);
}

int main() {
    f(42);
    return 0;
}

Let’s look at the related assembly:

0000000000001140 :
    1140:55                   push   %rbp
    1141:48 89 e5             mov    %rsp,%rbp
    1144:48 83 ec 10          sub    $0x10,%rsp
    1148:44 89 65 fc          mov    %r12d,-0x4(%rbp)
    114c:8b 75 fc             mov    -0x4(%rbp),%esi
    114f:48 8d 3d ae 0e 00 00 lea    0xeae(%rip),%rdi        # 2004 <_IO_stdin_used+0x4>
    1156:31 c0                xor    %eax,%eax
    1158:e8 d3 fe ff ff       call   1030 
    115d:48 83 c4 10          add    $0x10,%rsp
    1161:5d                   pop    %rbp
    1162:c3                   ret
    1163:66 66 66 66 2e 0f 1f data16 data16 data16 cs nopw 0x0(%rax,%rax,1)
    116a:84 00 00 00 00 00 

0000000000001170 :
    1170:55                   push   %rbp
    1171:48 89 e5             mov    %rsp,%rbp
    1174:44 89 65 fc          mov    %r12d,-0x4(%rbp)
    1178:44 8b 65 fc          mov    -0x4(%rbp),%r12d
    117c:5d                   pop    %rbp
    117d:e9 be ff ff ff       jmp    1140 
    1182:66 66 66 66 66 2e 0f data16 data16 data16 data16 cs nopw 0x0(%rax,%rax,1)
    1189:1f 84 00 00 00 00 00

We can see that the last step of function f is jmp 1140 , not call 1140 . This means when we call function g, we won’t have additional overhead like register allocation that traditional call instructions bring.

Some students might have realized that after tail recursion processing, this can completely be viewed as a high-performance Goto.

Bingo, the idea here is similar. A 1977 paper “Debunking the ‘Expensive Procedure Call’ Myth, or, Procedure Call Implementations Considered Harmful, or, Lambda: The Ultimate GOTO” mentioned that efficient procedure calls can have performance close to Goto, while being more concise in implementation.

In Python 3.14, the implementation of Tail Call Interpreter is based on this idea.

We can see that we’ve applied tail recursion processing to the macro that dispatches opcodes:

#   define Py_MUSTTAIL [[clang::musttail]]
#   define Py_PRESERVE_NONE_CC __attribute__((preserve_none))
    Py_PRESERVE_NONE_CC typedef PyObject* (*py_tail_call_funcptr)(TAIL_CALL_PARAMS);

#   define TARGET(op) Py_PRESERVE_NONE_CC PyObject *_TAIL_CALL_##op(TAIL_CALL_PARAMS)
#   define DISPATCH_GOTO() \
        do { \
            Py_MUSTTAIL return (INSTRUCTION_TABLE[opcode])(TAIL_CALL_ARGS); \
        } while (0)
#   define JUMP_TO_LABEL(name) \
        do { \
            Py_MUSTTAIL return (_TAIL_CALL_##name)(TAIL_CALL_ARGS); \
        } while (0)
#   ifdef Py_STATS
#       define JUMP_TO_PREDICTED(name) \
            do { \
                Py_MUSTTAIL return (_TAIL_CALL_##name)(frame, stack_pointer, tstate, this_instr, oparg, lastopcode); \
            } while (0)
#   else
#       define JUMP_TO_PREDICTED(name) \
            do { \
                Py_MUSTTAIL return (_TAIL_CALL_##name)(frame, stack_pointer, tstate, this_instr, oparg); \
            } while (0)
#   endif
#    define LABEL(name) TARGET(name)

So while ensuring our baseline performance is as good as or even better than Computed Goto, we can get the following benefits:

Broader platform support
After splitting cases, compilers are less likely to make mistakes, and overall performance predictability is stronger
Happy perf
And I can do more cool stuff with tools like eBPF

Summary

This article is pretty much it. Although it claims to only introduce Python 3.14’s Tail Call Interpreter, it still completely introduces the entire evolution of thinking.

This also gives me an insight: predictability is really a very important characteristic in many cases.

This, along with remote debug, are the two features I like most in 3.14. Long live observability!

Python 3.14 的进一步性能进化: Tail Call Interpreter

2025-07-02T15:49:00.000Z

最近做安全做的我头晕脑胀，来点轻松的换换脑子，让自己放松下

Python 3.14 正式引入了一个新的机制叫作 Tail Call Interpreter（Made by Ken Jin），这无疑又是一个奠定未来基础的重大工作

正文

在聊 Python 3.14 的 Tail Call Interpreter 之前，我们先要来聊 C 语言中最基本的语法 switch-case

switch (x) {
    case 1:
        // do something
        break;
    case 2:
        // do something else
        break;
    default:
        // do default thing
}

对于这样的代码我们最终的汇编会是什么样的呢？可能大家第一反应是先 cmp 然后 je ，不等式秒了，我们编译一个版本来看看

对于这样一段代码

void small_switch(int x) {
    switch(x) {
        case 1: printf("One\n"); break;
        case 2: printf("Two\n"); break;
        case 3: printf("Three\n"); break;
        default: printf("Other\n"); break;
    }
}

最终汇编的产物会是这样的

00000000000011f0 :
    11f0:83 ff 02             cmp    $0x2,%edi
    11f3:74 2b                je     1220 
    11f5:83 ff 03             cmp    $0x3,%edi
    11f8:74 16                je     1210 
    11fa:83 ff 01             cmp    $0x1,%edi
    11fd:75 31                jne    1230 
    11ff:48 8d 3d fe 0d 00 00 lea    0xdfe(%rip),%rdi        # 2004 <_IO_stdin_used+0x4>
    1206:e9 25 fe ff ff       jmp    1030 
    120b:0f 1f 44 00 00       nopl   0x0(%rax,%rax,1)
    1210:48 8d 3d f5 0d 00 00 lea    0xdf5(%rip),%rdi        # 200c <_IO_stdin_used+0xc>
    1217:e9 14 fe ff ff       jmp    1030 
    121c:0f 1f 40 00          nopl   0x0(%rax)
    1220:48 8d 3d e1 0d 00 00 lea    0xde1(%rip),%rdi        # 2008 <_IO_stdin_used+0x8>
    1227:e9 04 fe ff ff       jmp    1030 
    122c:0f 1f 40 00          nopl   0x0(%rax)
    1230:48 8d 3d db 0d 00 00 lea    0xddb(%rip),%rdi        # 2012 <_IO_stdin_used+0x12>
    1237:e9 f4 fd ff ff       jmp    1030 
    123c:0f 1f 40 00          nopl   0x0(%rax)

我们能看到整体如我们所预期的一样，不断的 cmp 然后不断的 je，然后我们评估一下这里的复杂度呢？哦，时间复杂度 O(n) 秒了。

卧槽，那对于 Python 这样一个超大的 switch case 的结构，岂不是每次都是一个 O(n) ？这不得原地升天？

其实不是，通常来说，编译器会根据数据的类型和规模来用不同的方案处理 switch case 的结构

我们来准备几组例子

void small_switch(int x) {
    switch(x) {
        case 1: printf("One\n"); break;
        case 2: printf("Two\n"); break;
        case 3: printf("Three\n"); break;
        default: printf("Other\n"); break;
    }
}

void dense_switch(int x) {
    switch(x) {
        case 10: printf("Ten\n"); break;
        case 11: printf("Eleven\n"); break;
        case 12: printf("Twelve\n"); break;
        case 13: printf("Thirteen\n"); break;
        case 14: printf("Fourteen\n"); break;
        case 15: printf("Fifteen\n"); break;
        case 16: printf("Sixteen\n"); break;
        case 17: printf("Seventeen\n"); break;
        default: printf("Other\n"); break;
    }
}

void sparse_switch(int x) {
    switch(x) {
        case 1: printf("One\n"); break;
        case 100: printf("Hundred\n"); break;
        case 1000: printf("Thousand\n"); break;
        case 10000: printf("Ten thousand\n"); break;
        default: printf("Other\n"); break;
    }
}

void large_dense_switch(int x) {
    switch(x) {
        case 1: printf("Case 1\n"); break;
        case 2: printf("Case 2\n"); break;
        case 3: printf("Case 3\n"); break;
        case 4: printf("Case 4\n"); break;
        case 5: printf("Case 5\n"); break;
        case 6: printf("Case 6\n"); break;
        case 7: printf("Case 7\n"); break;
        case 8: printf("Case 8\n"); break;
        case 9: printf("Case 9\n"); break;
        case 10: printf("Case 10\n"); break;
        case 11: printf("Case 11\n"); break;
        case 12: printf("Case 12\n"); break;
        case 13: printf("Case 13\n"); break;
        case 14: printf("Case 14\n"); break;
        case 15: printf("Case 15\n"); break;
        case 16: printf("Case 16\n"); break;
        case 17: printf("Case 17\n"); break;
        case 18: printf("Case 18\n"); break;
        case 19: printf("Case 19\n"); break;
        case 20: printf("Case 20\n"); break;
        default: printf("Other\n"); break;
    }
}

void mixed_switch(int x) {
    switch(x) {
        case 1: printf("Case 1\n"); break;
        case 2: printf("Case 2\n"); break;
        case 3: printf("Case 3\n"); break;
        
        case 50: printf("Case 50\n"); break;
        
        case 100: printf("Case 100\n"); break;
        case 101: printf("Case 101\n"); break;
        case 102: printf("Case 102\n"); break;
        
        default: printf("Other\n"); break;
    }
}

void char_switch(char c) {
    switch(c) {
        case 'a': printf("Letter a\n"); break;
        case 'b': printf("Letter b\n"); break;
        case 'c': printf("Letter c\n"); break;
        case 'd': printf("Letter d\n"); break;
        case 'e': printf("Letter e\n"); break;
        default: printf("Other char\n"); break;
    }
}

然后我们反汇编以下，看下结果（这里我只把关键的部分贴出来）

00000000000011f0 :
    11f0:83 ff 02             cmp    $0x2,%edi      # 比较是否为2
    11f3:74 2b                je     1220            # 跳转到case 2
    11f5:83 ff 03             cmp    $0x3,%edi      # 比较是否为3
    11f8:74 16                je     1210            # 跳转到case 3
    11fa:83 ff 01             cmp    $0x1,%edi      # 比较是否为1
    11fd:75 31                jne    1230            # 不是则跳转到default

0000000000001240 :
    1240:83 ef 0a             sub    $0xa,%edi      # 减去10 (最小case值)
    1243:83 ff 07             cmp    $0x7,%edi      # 比较范围 (17-10=7)
    1246:0f 87 90 00 00 00    ja     12dc           # 超出范围跳转default
    124c:48 8d 15 15 0f 00 00 lea    0xf15(%rip),%rdx # 加载跳转表地址
    1253:48 63 04 ba          movslq (%rdx,%rdi,4),%rax # 获取偏移量
    1257:48 01 d0             add    %rdx,%rax      # 计算目标地址
    125a:ff e0                jmp    *%rax          # 间接跳转

00000000000012f0 :
    12f0:81 ff e8 03 00 00    cmp    $0x3e8,%edi    # 比较1000
    12f6:74 40                je     1338           # 等于则跳转
    12f8:7f 16                jg     1310           # 大于1000则继续检查
    12fa:83 ff 01             cmp    $0x1,%edi      # 小于1000，检查1
    12fd:74 49                je     1348           
    12ff:83 ff 64             cmp    $0x64,%edi     # 检查100
    1302:75 24                jne    1328           # 都不是则default
    ...
    1310:81 ff 10 27 00 00    cmp    $0x2710,%edi   # 检查10000

0000000000001360 :
    1360:83 ff 14             cmp    $0x14,%edi     # 检查是否≤20
    1363:0f 87 53 01 00 00    ja     14bc           # 超出范围
    1369:48 8d 15 18 0e 00 00 lea    0xe18(%rip),%rdx # 跳转表地址
    1372:48 63 04 ba          movslq (%rdx,%rdi,4),%rax # 直接索引
    1376:48 01 d0             add    %rdx,%rax
    1379:ff e0                jmp    *%rax

00000000000014d0 :
    14d0:83 ff 32             cmp    $0x32,%edi     # 比较50
    14d3:74 7b                je     1550
    14d5:7f 29                jg     1500           # >50的情况
    14d7:83 ff 02             cmp    $0x2,%edi      # ≤50，检查小值
    14da:74 64                je     1540
    14dc:83 ff 03             cmp    $0x3,%edi
    ...
    1500:83 ff 65             cmp    $0x65,%edi     # >50，检查100,101,102
    1503:74 5b                je     1560

0000000000001580 :
    1580:83 ef 61             sub    $0x61,%edi     # 减去'a'的ASCII值
    1583:40 80 ff 04          cmp    $0x4,%dil      # 检查是否≤4 (a-e)
    1587:77 63                ja     15ec
    1589:48 8d 15 4c 0c 00 00 lea    0xc4c(%rip),%rdx
    1590:40 0f b6 ff          movzbl %dil,%edi      # 零扩展到32位
    1594:48 63 04 ba          movslq (%rdx,%rdi,4),%rax

我们这里能看到编译器根据数据的不同类型来处理了 switch case 的结构，这里我用一个表格总结一下

Switch类型	Case数量	分布特点	编译器策略	时间复杂度
small_switch	3个	连续(1,2,3)	线性比较	O(n)
dense_switch	8个	连续(10-17)	偏移跳转表	O(1)
sparse_switch	4个	稀疏(1,100,1000,10000)	二分查找	O(log n)
large_dense_switch	20个	连续(1-20)	标准跳转表	O(1)
mixed_switch	7个	部分连续	嵌套比较	O(log n)
char_switch	5个	连续(‘a’-‘e’)	字符偏移表	O(1)

OK，这里我们发现，Switch-case 最终的实现因为数据类型的不一样，会导致我们最终的代码存在一个不可预测性。那么我们有没有办法来优化这个问题呢？答案是有的。

我们来看下面一段代码

#include 

void basic_computed_goto(int operation) {
    static void* jump_table[] = {
        &&op_add,   
        &&op_sub,   
        &&op_mul,   
        &&op_div,   
        &&op_mod,   
        &&op_default
    };
    
    int a = 10, b = 3;
    int result;
    
    if (operation < 0 || operation > 4) {
        operation = 5;
    }
    
    printf("Operation %d: a=%d, b=%d -> ", operation, a, b);
    
    goto *jump_table[operation];
    
op_add:
    result = a + b;
    printf("ADD: %d\n", result);
    return;
    
op_sub:
    result = a - b;
    printf("SUB: %d\n", result);
    return;
    
op_mul:
    result = a * b;
    printf("MUL: %d\n", result);
    return;
    
op_div:
    if (b != 0) {
        result = a / b;
        printf("DIV: %d\n", result);
    } else {
        printf("DIV: Error (division by zero)\n");
    }
    return;
    
op_mod:
    if (b != 0) {
        result = a % b;
        printf("MOD: %d\n", result);
    } else {
        printf("MOD: Error (division by zero)\n");
    }
    return;
    
op_default:
    printf("Unknown operation\n");
    return;
}

我们能看到这里核心的一个操作是将我们 Switch-cased 的每个 case 都变成了一个标签，然后我们通过一个 jump_table 来直接跳转到对应的标签上, 我们来看一下最关键位置的汇编

1 2	11d3:48 8d 05 c6 2b 00 00 lea 0x2bc6(%rip),%rax # 3da0 11da:ff 24 d8 jmp *(%rax,%rbx,8)

这里我们可以总结出来使用 Computed Goto 相较于传统的 switch-case 有以下几点优势

减少分支预测 fallback 的代价
指令缓存局部性上更优
减少了 cmp 指令的数量和开销

那么具体能有多快呢？可以参见 CPython 引入的 Computed Goto 的一个测试结果，大概是整体提升了15% 左右

那么 Computed Goto 的方式就是完美的吗？其实也不是，目前 CPython 的解释器 ceval.c 也是目前最大的一个 switch case 中存在几个典型问题

Computed Goto 作为 clang 和 gcc 特化的功能，那么其余平台受益的可能性较小
目前 Computed Goto 其实并不成熟，在同一个编译器不同的版本可能会有不同的问题
超大型的 switch case 会导致编译器对于 switch case 的优化不够好
我们无法使用 perf 精确的去对我们整个过程中 per opcode 的开销进行定量分析，这在于让 Python 变得更快的大背景下将会是一个很大的问题

1，3，4 都很好理解，我们来看一下2的一个例子（感谢 Ken Jin 提供的例子）

在 GCC 11 的时候，switch-case 某个部分会正常的代码

738f: movq%r13, %r15
7392: movzbl%ah, %ebx
7395: movzbl%al, %eax
7398: movq(,%rax,8), %rax
73a0: movl%ebx, -0x248(%rbp)
73a6: jmpq*%rax

而在 GCC 13-15Beta 的时候，则会产生这样的代码

747a: movzbl%ah, %ebx
747d: movzbl%al, %eax
7480: movl%ebx, -0x248(%rbp)
7486: movq(,%rax,8), %rax
748e: jmp0x72a0 <_PyEval_EvalFrameDefault+0x970>

72a0: movq%r15, %xmm0
72a5: movq%r13, %xmm3
72aa: movq%r15, %rbx
72ad: punpcklqdq%xmm3, %xmm0
72b1: movhlps%xmm0, %xmm2
72b4: movq%xmm2, %r10
72b9: movq%r10, %r11
72bc: jmpq*%rax

我们能发现，额外的寄存器被引入了。体系结构 101，额外的寄存器意味着额外的开销。寄存器是很贵的！

那么我们有没有办法来迭代上面的超大的 Switch case 呢？估计有同学在想，既然上面的 switch case 超级大，那么我们将其拆分为多个小的函数
这样编译器可以有足够的上下文来优化，同时我们的 perf 也可以精确的去分析每个函数的开销，岂不美哉？

但是又有同学反对了，函数调用会触发 call 的指令，会带来额外的寄存器入栈和出栈的开销，这样会不会又变慢了呢？

那么能不能优化一下呢？答案是可以的，很多同学可能会想到了，tail call

假设我们有这样一段代码

__attribute__((noinline)) void g(int x) {
    printf("Value: %d\n", x);
};
void f(int x) {
    return g(x);
}

我们能看到这样一段汇编

0000000000001140 :
    1140:55                   push   %rbp
    1141:48 89 e5             mov    %rsp,%rbp
    1144:48 83 ec 10          sub    $0x10,%rsp
    1148:89 7d fc             mov    %edi,-0x4(%rbp)
    114b:8b 75 fc             mov    -0x4(%rbp),%esi
    114e:48 8d 3d af 0e 00 00 lea    0xeaf(%rip),%rdi        # 2004 <_IO_stdin_used+0x4>
    1155:b0 00                mov    $0x0,%al
    1157:e8 d4 fe ff ff       call   1030 
    115c:48 83 c4 10          add    $0x10,%rsp
    1160:5d                   pop    %rbp
    1161:c3                   ret
    1162:66 66 66 66 66 2e 0f data16 data16 data16 data16 cs nopw 0x0(%rax,%rax,1)
    1169:1f 84 00 00 00 00 00 

0000000000001170 :
    1170:55                   push   %rbp
    1171:48 89 e5             mov    %rsp,%rbp
    1174:48 83 ec 10          sub    $0x10,%rsp
    1178:89 7d fc             mov    %edi,-0x4(%rbp)
    117b:8b 7d fc             mov    -0x4(%rbp),%edi
    117e:e8 bd ff ff ff       call   1140 
    1183:48 83 c4 10          add    $0x10,%rsp
    1187:5d                   pop    %rbp
    1188:c3                   ret
    1189:0f 1f 80 00 00 00 00 nopl   0x0(%rax)

其中 call 1140 指令非常显眼。这也是函数调用本身的开销的一个重要来源

在现在编译器中，存在一种特殊的优化叫作尾递归，即当函数的最后一步是调用另一个函数时，编译器可以优化掉这个调用的开销

我们来测试一下

#include 
__attribute__((preserve_none)) void g(int x);
__attribute__((noinline, preserve_none)) void g(int x){
    printf("Value: %d\n", x);
}

__attribute__((preserve_none)) void f(int x) {
    [[clang::musttail]] return g(x);
}

int main() {
    f(42);
    return 0;
}

我们来看下相关汇编

0000000000001140 :
    1140:55                   push   %rbp
    1141:48 89 e5             mov    %rsp,%rbp
    1144:48 83 ec 10          sub    $0x10,%rsp
    1148:44 89 65 fc          mov    %r12d,-0x4(%rbp)
    114c:8b 75 fc             mov    -0x4(%rbp),%esi
    114f:48 8d 3d ae 0e 00 00 lea    0xeae(%rip),%rdi        # 2004 <_IO_stdin_used+0x4>
    1156:31 c0                xor    %eax,%eax
    1158:e8 d3 fe ff ff       call   1030 
    115d:48 83 c4 10          add    $0x10,%rsp
    1161:5d                   pop    %rbp
    1162:c3                   ret
    1163:66 66 66 66 2e 0f 1f data16 data16 data16 cs nopw 0x0(%rax,%rax,1)
    116a:84 00 00 00 00 00 

0000000000001170 :
    1170:55                   push   %rbp
    1171:48 89 e5             mov    %rsp,%rbp
    1174:44 89 65 fc          mov    %r12d,-0x4(%rbp)
    1178:44 8b 65 fc          mov    -0x4(%rbp),%r12d
    117c:5d                   pop    %rbp
    117d:e9 be ff ff ff       jmp    1140 
    1182:66 66 66 66 66 2e 0f data16 data16 data16 data16 cs nopw 0x0(%rax,%rax,1)
    1189:1f 84 00 00 00 00 00

我们能看到，f 函数的最后一步是 jmp 1140 ，而不是 call 1140 ，这就意味着我们在调用 g 函数的时候不会有额外的寄存器分配等传统 call 指令带来的开销。

可能有同学回过味来了，那么这里在做尾递归处理后，感觉完全可以当作一种高性能 Goto 来看嘛。

Bingo，这里其实思路也是差不多这样的，在77年的一篇论文《Debunking the ‘Expensive Procedure Call’ Myth, or, Procedure Call Implementations Considered Harmful, or, Lambda: The Ultimate GOTO》就提到了，高效的过程调用可以和 Goto 性能相近，而在实现上会更简洁。

在 Python 3.14 中，Tail Call Interpreter 的实现就是基于这个思路的。

我们能看到我们对于 opcode 进行 dispatch 的宏进行了尾递归的处理

#   define Py_MUSTTAIL [[clang::musttail]]
#   define Py_PRESERVE_NONE_CC __attribute__((preserve_none))
    Py_PRESERVE_NONE_CC typedef PyObject* (*py_tail_call_funcptr)(TAIL_CALL_PARAMS);

#   define TARGET(op) Py_PRESERVE_NONE_CC PyObject *_TAIL_CALL_##op(TAIL_CALL_PARAMS)
#   define DISPATCH_GOTO() \
        do { \
            Py_MUSTTAIL return (INSTRUCTION_TABLE[opcode])(TAIL_CALL_ARGS); \
        } while (0)
#   define JUMP_TO_LABEL(name) \
        do { \
            Py_MUSTTAIL return (_TAIL_CALL_##name)(TAIL_CALL_ARGS); \
        } while (0)
#   ifdef Py_STATS
#       define JUMP_TO_PREDICTED(name) \
            do { \
                Py_MUSTTAIL return (_TAIL_CALL_##name)(frame, stack_pointer, tstate, this_instr, oparg, lastopcode); \
            } while (0)
#   else
#       define JUMP_TO_PREDICTED(name) \
            do { \
                Py_MUSTTAIL return (_TAIL_CALL_##name)(frame, stack_pointer, tstate, this_instr, oparg); \
            } while (0)
#   endif
#    define LABEL(name) TARGET(name)

那么在保证我们基线性能和 Compute GOTO 甚至更优一点的同时，我们可以得到如下的一些好处

更广泛的平台支持
将 case 拆分后，编译器更不容易犯错，整体的性能的可预测性更强
happy perf
以及我可以用 eBPF 之类的工具做更多的骚操作（

总结

这篇文章差不多就是这样，虽然说是只介绍 Python 3.14 的 Tail Call Interpreter，但是还是完整的介绍了一些整个的一个演进思路

这也带给我一个启发，很多时候，可预测性真的是非常重要的一个特性。

这算是 3.14 中和 remote debug 一起并列为我最喜欢的两个feature，可观测性万岁！

Python 3.14: Python 世界的一大步

2025-04-26T14:49:00.000Z

Python 3.14 目前主要的一些主要的特性其实已经固定了，在我看来，Python 3.14 是一个未来很多年的一个核心版本。因为其确定了是时代的 Python
调试生态的基准，这篇文章将会来聊聊这个 Python 世界中的史诗级改进

正文

在我们日常调试 Python 代码的时候，我们经常会遇到这样一个问题，我们需要采样当前的 Python Runtime 的状态，进而进一步调试我们的 Python 进程

常见的手段莫过于两种

通过 eBPF + UProbe 等手段来触发
通过 process_vm_readv 等 Syscall 来直接整块读取内存

无论这两种方式都有一个核心的问题，我们怎么样来解析内存中的数据？

用 https://github.com/jschwinger233/perf-examples/blob/main/cpython310_backtrace/bpf.c 来做一个例子，在之前的很多年的时候，我们会怎么做

#define PAGE_SIZE (1<<12)
#define KASAN_STACK_ORDER 0
#define THREAD_SIZE_ORDER (2 + KASAN_STACK_ORDER)
#define THREAD_SIZE  ((__u64)(PAGE_SIZE << THREAD_SIZE_ORDER))
#define TOP_OF_KERNEL_STACK_PADDING ((__u64)0)

const static u32 ZERO = 0;

struct PyTypeObject {
    char _[24];
    char *tp_name;
};

struct PyObject {
    char _[8];
    struct PyTypeObject *ob_type;
};

struct PyVarObject {
    struct PyObject ob_base;
    char _[8];
};

struct PyASCIIObject {
__u8 _[16];
__u64 length;
__u8 __[24];
};

struct _PyStr {
    struct PyASCIIObject ascii;
    char buf[100];
};

struct PyCodeObject {
    char _[104];
    struct _PyStr *co_filename;
    struct _PyStr *co_name;
};

struct PyFrameObject {
    struct PyVarObject ob_base;
    struct PyFrameObject *f_back;
    struct PyCodeObject *f_code;
    char _[60];
    int f_lineno;
};

struct event {
__u64 rip;
__u8 user_mode;
__s8 python_stack_depth;
__u64 filename_len[20];
__u64 funcname_len[20];
unsigned char filename[20][100];
unsigned char funcname[20][100];
};

struct {
__uint(type, BPF_MAP_TYPE_PERCPU_ARRAY);
__uint(max_entries, 1);
__type(key, u32);
__type(value, struct event);
} events SEC(".maps");

struct {
__uint(type, BPF_MAP_TYPE_RINGBUF);
__uint(max_entries, 1<<29);
} ringbuf SEC(".maps");

SEC("perf_event/cpython310")
int perf_event_cpython310(struct bpf_perf_event_data *ctx)
{
__u64 rsp;
struct event *event;
struct PyFrameObject *frame;

event = bpf_map_lookup_elem(&events, &ZERO);
if (!event)
return 0;

rsp = ctx->regs.sp;
event->rip = ctx->regs.ip;
event->user_mode = !!(ctx->regs.cs & 3);

if (!event->user_mode) {
struct task_struct *task = (struct task_struct *)bpf_get_current_task();
__u64 __ptr = (__u64)BPF_CORE_READ(task, stack);
__ptr += THREAD_SIZE - TOP_OF_KERNEL_STACK_PADDING;
struct pt_regs *pt_regs = ((struct pt_regs *)__ptr) - 1;

rsp = BPF_CORE_READ(pt_regs, sp);
event->rip = BPF_CORE_READ(pt_regs, ip);
}

char name[5];
bool found = false;

for (int i = 0; i < 200; i++) {
bpf_probe_read_user(&frame, sizeof(frame), (void *)rsp + 8*i);
if (!frame)
continue;

char *tp_name = BPF_PROBE_READ_USER(frame, ob_base.ob_base.ob_type, tp_name);
bpf_probe_read_user(&name, sizeof(name), (void *)tp_name);
if (bpf_strncmp(name, 5, "frame") == 0) {
found = true;
break;
}
}

if (!found) {
event->python_stack_depth = -1;
bpf_ringbuf_output(&ringbuf, event, sizeof(*event), 0);
return 0;
}

for (int i = 0; i < 20; i++) {
event->python_stack_depth = i;
BPF_PROBE_READ_USER_INTO(&event->filename_len[i], frame, f_code, co_filename, ascii.length);
BPF_PROBE_READ_USER_INTO(&event->filename[i], frame, f_code, co_filename, buf);
BPF_PROBE_READ_USER_INTO(&event->funcname_len[i], frame, f_code, co_name, ascii.length);
BPF_PROBE_READ_USER_INTO(&event->funcname[i], frame, f_code, co_name, buf);
frame = BPF_PROBE_READ_USER(frame, f_back);
if (!frame)
break;
}

bpf_ringbuf_output(&ringbuf, event, sizeof(*event), 0);
return 0;
}

char __license[] SEC("license") = "Dual MIT/GPL";

上面的核心代码其实没多少，核心的逻辑就还是我们手动模拟 Python 中关键的 PyFrameObject 结构体，然后我们在内存中不断做一次搜索，暴力匹配到特征一致的内存

其余诸如 PySpy 这样的工具也是类似的思路

这个方式最核心的问题是在于说，Python 每个版本的 ABI 都可能发生变化，所以我们需要不断的根据不同的版本去做兼容（比如 PySpy 维护了从3.7到3.12的不同的 PyFrameObject。

那么我们有没有更好的方法来处理这个问题？或者说我们能不能更好的去定位？

可以的，写 Python 的同学肯定都知道我们 Python 中有一个全局的变量 _PyRuntime，其类型为 pyruntimestate，大致的布局如下

struct pyruntimestate {

    _Py_DebugOffsets debug_offsets;

    int _initialized;

    int preinitializing;

    int preinitialized;

    int core_initialized;

    int initialized;

    PyThreadState *_finalizing;

    unsigned long _finalizing_id;

    struct pyinterpreters {
        PyMutex mutex;
        PyInterpreterState *head;

        PyInterpreterState *main;

        int64_t next_id;
    } interpreters;


    unsigned long main_thread;
    PyThreadState *main_tstate;


    _PyXI_global_state_t xi;

    struct _pymem_allocators allocators;
    struct _obmalloc_global_state obmalloc;
    struct pyhash_runtime_state pyhash_state;
    struct _pythread_runtime_state threads;
    struct _signals_runtime_state signals;

    Py_tss_t autoTSSkey;

    Py_tss_t trashTSSkey;

    PyWideStringList orig_argv;

    struct _parser_runtime_state parser;

    struct _atexit_runtime_state atexit;

    struct _import_runtime_state imports;
    struct _ceval_runtime_state ceval;
    struct _gilstate_runtime_state {

        int check_enabled;

        PyInterpreterState *autoInterpreterState;
    } gilstate;
    struct _getargs_runtime_state {
        struct _PyArg_Parser *static_parsers;
    } getargs;
    struct _fileutils_state fileutils;
    struct _faulthandler_runtime_state faulthandler;
    struct _tracemalloc_runtime_state tracemalloc;
    struct _reftracer_runtime_state ref_tracer;

    _PyRWMutex stoptheworld_mutex;
    struct _stoptheworld_state stoptheworld;

    PyPreConfig preconfig;
    Py_OpenCodeHookFunction open_code_hook;
    void *open_code_userdata;
    struct {
        PyMutex mutex;
        struct _Py_AuditHookEntry *head;
    } audit_hooks;

    struct _py_object_runtime_state object_state;
    struct _Py_float_runtime_state float_state;
    struct _Py_unicode_runtime_state unicode_state;
    struct _types_runtime_state types;
    struct _Py_time_runtime_state time;

#if defined(__EMSCRIPTEN__) && defined(PY_CALL_TRAMPOLINE)

    int (*emscripten_count_args_function)(PyCFunctionWithKeywords func);
#endif
    struct _Py_cached_objects cached_objects;
    struct _Py_static_objects static_objects;

    PyInterpreterState _main_interpreter;

};

眼尖的同学肯定看到了，我们其中有一段核心的代码

struct pyinterpreters {
    PyMutex mutex;
    PyInterpreterState *head;

    PyInterpreterState *main;

    int64_t next_id;
} interpreters;

维护了一个 PyInterpreterState 的链表，我们可以通过 PyInterpreterState 来获取当前的 Frame，PyInterpreterState 中的 TreadState 来获取当前的线程状态

struct pythreads {
    uint64_t next_unique_id;
    /* The linked list of threads, newest first. */
    PyThreadState *head;
    _PyThreadStateImpl *preallocated;
    /* The thread currently executing in the __main__ module, if any. */
    PyThreadState *main;
    /* Used in Modules/_threadmodule.c. */
    Py_ssize_t count;
    /* Support for runtime thread stack size tuning.
       A value of 0 means using the platform's default stack size
       or the size specified by the THREAD_STACK_SIZE macro. */
    /* Used in Python/thread.c. */
    size_t stacksize;
} threads;

而 PyThreadState 中和核心的 struct _PyInterpreterFrame *current_frame 就是我们需要的 frame state，整个流程大概如下

graph TD    PyRuntime["_PyRuntime (pyruntimestate)"] --> Interpreters["interpreters (pyinterpreters)"]    Interpreters -->|head| InterpreterStateHead["PyInterpreterState *head"]    Interpreters -->|main| InterpreterStateMain["PyInterpreterState *main"]        %% Define interpreter state structure    subgraph PyInterpreterState        InterpreterID["int64_t id"]         ThreadsStruct["struct pythreads threads"]        NextInterpreter["PyInterpreterState *next"]    end        InterpreterStateHead --- PyInterpreterState    InterpreterStateMain --- PyInterpreterState        %% Link to threads structure    ThreadsStruct --> ThreadHead["PyThreadState *head"]    ThreadsStruct --> ThreadMain["PyThreadState *main"]        %% Define thread state structure    subgraph PyThreadState        ThreadID["uint64_t thread_id"]        InterpreterPtr["PyInterpreterState *interp"]        CurrentFrame["_PyInterpreterFrame *current_frame"]        NextThread["PyThreadState *next"]    end        ThreadHead --- PyThreadState    ThreadMain --- PyThreadState        %% Frame structure    CurrentFrame --> Frame["_PyInterpreterFrame structure"]        subgraph _PyInterpreterFrame        PreviousFrame["_PyInterpreterFrame *previous"]        CodeObject["PyCodeObject *f_code"]        Locals["PyObject **localsplus"]    end        %% Connected paths in color    PyRuntime ==>|"Main Path"| Interpreters    Interpreters ==>|"Main Path"| InterpreterStateMain    InterpreterStateMain ==>|"Main Path"| ThreadsStruct    ThreadsStruct ==>|"Main Path"| ThreadMain    ThreadMain ==>|"Main Path"| CurrentFrame    CurrentFrame ==>|"Main Path"| Frame        class PyRuntime,InterpreterStateMain,ThreadMain,CurrentFrame,Frame mainPath;    classDef mainPath fill:#f96,stroke:#333,stroke-width:2px;    classDef mainNodes fill:#f9f,stroke:#333,stroke-width:2px;

那么我们现在来解决第一个问题，我们怎么样获取在内存中的 _PyRuntime 的地址呢？

我们把这个问题抽象成下面最简单一个 C 代码

#include 

int abc=3;

int main() {
    printf("abc: %p\n", &abc);
    return 0;
}

我们怎么样获取 abc 的地址呢？这里写过 C 的同学可能反应过来了，我们可以使用 __attribute__((section())) 的语法，来将其放到一个特定的段中

#include 

int abc __attribute__((section(".my_section"))) = 3;

int main() {
    printf("abc: %p\n", &abc);
    return 0;
}

我们编译，并用 readelf 来解析一下二进制

1 2	╰─ readelf -S ./a.out\| grep my_section [25] .my_section PROGBITS 0000000000004018 00003018

我们能看到这里我们得到了一个相对地址。后续我们就可以通过解析 ELF 来遍历寻找到 abc 变量的地址

那么在 Python 中同样如此，在代码中有这样一段代码

#define GENERATE_DEBUG_SECTION(name, declaration)     \
   _GENERATE_DEBUG_SECTION_WINDOWS(name)            \
   _GENERATE_DEBUG_SECTION_APPLE(name)              \
   declaration                                      \
   _GENERATE_DEBUG_SECTION_LINUX(name)

// Please note that section names are truncated to eight bytes
// on Windows!
#if defined(MS_WINDOWS)
#define _GENERATE_DEBUG_SECTION_WINDOWS(name)                       \
   _Pragma(Py_STRINGIFY(section(Py_STRINGIFY(name), read, write))) \
   __declspec(allocate(Py_STRINGIFY(name)))
#else
#define _GENERATE_DEBUG_SECTION_WINDOWS(name)
#endif

#if defined(__APPLE__)
#define _GENERATE_DEBUG_SECTION_APPLE(name) \
   __attribute__((section(SEG_DATA "," Py_STRINGIFY(name))))      \
   __attribute__((used))
#else
#define _GENERATE_DEBUG_SECTION_APPLE(name)
#endif

#if defined(__linux__) && (defined(__GNUC__) || defined(__clang__))
#define _GENERATE_DEBUG_SECTION_LINUX(name) \
   __attribute__((section("." Py_STRINGIFY(name))))               \
   __attribute__((used))
#else
#define _GENERATE_DEBUG_SECTION_LINUX(name)
#endif

GENERATE_DEBUG_SECTION(PyRuntime, _PyRuntimeState _PyRuntime)
= _PyRuntimeState_INIT(_PyRuntime, _Py_Debug_Cookie);
_Py_COMP_DIAG_POP

这样我们就能比较方便的获取到 PyRuntime 在内存中的地址。

那么现在第二个问题是，我们怎么样通过我们前面介绍的调用链获取到地址？

大家可能第一反应还是想通过维护不同版本的数据结构来获取具体的地址。不过这里我们有没有办法可以用更简单的方法来处理呢？答案是有的

眼尖的同学可能看到了我们在 pyruntimestate 中有一个字段叫 debug_offsets，我们来看下我们怎么初始化这个字段的吧

#define _Py_DebugOffsets_INIT(debug_cookie) { \
    .cookie = debug_cookie, \
    .version = PY_VERSION_HEX, \
    .free_threaded = _Py_Debug_Free_Threaded, \
    .runtime_state = { \
        .size = sizeof(_PyRuntimeState), \
        .finalizing = offsetof(_PyRuntimeState, _finalizing), \
        .interpreters_head = offsetof(_PyRuntimeState, interpreters.head), \
    }, \
    .interpreter_state = { \
        .size = sizeof(PyInterpreterState), \
        .id = offsetof(PyInterpreterState, id), \
        .next = offsetof(PyInterpreterState, next), \
        .threads_head = offsetof(PyInterpreterState, threads.head), \
        .threads_main = offsetof(PyInterpreterState, threads.main), \
        .gc = offsetof(PyInterpreterState, gc), \
        .imports_modules = offsetof(PyInterpreterState, imports.modules), \
        .sysdict = offsetof(PyInterpreterState, sysdict), \
        .builtins = offsetof(PyInterpreterState, builtins), \
        .ceval_gil = offsetof(PyInterpreterState, ceval.gil), \
        .gil_runtime_state = offsetof(PyInterpreterState, _gil), \
        .gil_runtime_state_enabled = _Py_Debug_gilruntimestate_enabled, \
        .gil_runtime_state_locked = offsetof(PyInterpreterState, _gil.locked), \
        .gil_runtime_state_holder = offsetof(PyInterpreterState, _gil.last_holder), \
    }, \
    .thread_state = { \
        .size = sizeof(PyThreadState), \
        .prev = offsetof(PyThreadState, prev), \
        .next = offsetof(PyThreadState, next), \
        .interp = offsetof(PyThreadState, interp), \
        .current_frame = offsetof(PyThreadState, current_frame), \
        .thread_id = offsetof(PyThreadState, thread_id), \
        .native_thread_id = offsetof(PyThreadState, native_thread_id), \
        .datastack_chunk = offsetof(PyThreadState, datastack_chunk), \
        .status = offsetof(PyThreadState, _status), \
    }, \
    .interpreter_frame = { \
        .size = sizeof(_PyInterpreterFrame), \
        .previous = offsetof(_PyInterpreterFrame, previous), \
        .executable = offsetof(_PyInterpreterFrame, f_executable), \
        .instr_ptr = offsetof(_PyInterpreterFrame, instr_ptr), \
        .localsplus = offsetof(_PyInterpreterFrame, localsplus), \
        .owner = offsetof(_PyInterpreterFrame, owner), \
        .stackpointer = offsetof(_PyInterpreterFrame, stackpointer), \
    }, \
    .code_object = { \
        .size = sizeof(PyCodeObject), \
        .filename = offsetof(PyCodeObject, co_filename), \
        .name = offsetof(PyCodeObject, co_name), \
        .qualname = offsetof(PyCodeObject, co_qualname), \
        .linetable = offsetof(PyCodeObject, co_linetable), \
        .firstlineno = offsetof(PyCodeObject, co_firstlineno), \
        .argcount = offsetof(PyCodeObject, co_argcount), \
        .localsplusnames = offsetof(PyCodeObject, co_localsplusnames), \
        .localspluskinds = offsetof(PyCodeObject, co_localspluskinds), \
        .co_code_adaptive = offsetof(PyCodeObject, co_code_adaptive), \
    }, \
    .pyobject = { \
        .size = sizeof(PyObject), \
        .ob_type = offsetof(PyObject, ob_type), \
    }, \
    .type_object = { \
        .size = sizeof(PyTypeObject), \
        .tp_name = offsetof(PyTypeObject, tp_name), \
        .tp_repr = offsetof(PyTypeObject, tp_repr), \
        .tp_flags = offsetof(PyTypeObject, tp_flags), \
    }, \
    .tuple_object = { \
        .size = sizeof(PyTupleObject), \
        .ob_item = offsetof(PyTupleObject, ob_item), \
        .ob_size = offsetof(PyTupleObject, ob_base.ob_size), \
    }, \
    .list_object = { \
        .size = sizeof(PyListObject), \
        .ob_item = offsetof(PyListObject, ob_item), \
        .ob_size = offsetof(PyListObject, ob_base.ob_size), \
    }, \
    .set_object = { \
        .size = sizeof(PySetObject), \
        .used = offsetof(PySetObject, used), \
        .table = offsetof(PySetObject, table), \
        .mask = offsetof(PySetObject, mask), \
    }, \
    .dict_object = { \
        .size = sizeof(PyDictObject), \
        .ma_keys = offsetof(PyDictObject, ma_keys), \
        .ma_values = offsetof(PyDictObject, ma_values), \
    }, \
    .float_object = { \
        .size = sizeof(PyFloatObject), \
        .ob_fval = offsetof(PyFloatObject, ob_fval), \
    }, \
    .long_object = { \
        .size = sizeof(PyLongObject), \
        .lv_tag = offsetof(PyLongObject, long_value.lv_tag), \
        .ob_digit = offsetof(PyLongObject, long_value.ob_digit), \
    }, \
    .bytes_object = { \
        .size = sizeof(PyBytesObject), \
        .ob_size = offsetof(PyBytesObject, ob_base.ob_size), \
        .ob_sval = offsetof(PyBytesObject, ob_sval), \
    }, \
    .unicode_object = { \
        .size = sizeof(PyUnicodeObject), \
        .state = offsetof(PyUnicodeObject, _base._base.state), \
        .length = offsetof(PyUnicodeObject, _base._base.length), \
        .asciiobject_size = sizeof(PyASCIIObject), \
    }, \
    .gc = { \
        .size = sizeof(struct _gc_runtime_state), \
        .collecting = offsetof(struct _gc_runtime_state, collecting), \
    }, \
    .gen_object = { \
        .size = sizeof(PyGenObject), \
        .gi_name = offsetof(PyGenObject, gi_name), \
        .gi_iframe = offsetof(PyGenObject, gi_iframe), \
        .gi_frame_state = offsetof(PyGenObject, gi_frame_state), \
    }, \
    .debugger_support = { \
        .eval_breaker = offsetof(PyThreadState, eval_breaker), \
        .remote_debugger_support = offsetof(PyThreadState, remote_debugger_support),  \
        .remote_debugging_enabled = offsetof(PyInterpreterState, config.remote_debug),  \
        .debugger_pending_call = offsetof(_PyRemoteDebuggerSupport, debugger_pending_call),  \
        .debugger_script_path = offsetof(_PyRemoteDebuggerSupport, debugger_script_path),  \
        .debugger_script_path_size = MAX_SCRIPT_PATH_SIZE, \
    }, \
}

我们能看到我们使用了 offsetof 这个非常经典的宏来将一下我们常用的字段相较于结构体的偏移写入到 debug_offsets 中去。而 debug_offsets 将固定存在于 pyruntimestate 的第一个字段，同时起改变频率相对较低，所以我们就可以通过 debugger_support 获取不同地址的偏移量来获取最终我们想要的数据。

通过这样的做法，我们实际上就有很多很好玩的事情可以做了。实际上官方也是基于这样一套机制提出了 PEP 768 – Safe external debugger interface for CPython https://peps.python.org/pep-0768/。可以允许用户远程的为一个 Python 进程注入一段调试代码

我们来看一下这个 PEP 的核心实现

在前面介绍过的 ThreadState 中新增了一组结构

typedef struct _remote_debugger_support {
    int32_t debugger_pending_call;
    char debugger_script_path[MAX_SCRIPT_PATH_SIZE];
} _PyRemoteDebuggerSupport;

在执行过程中，如果 debugger_pending_call 为 1 的时候，我们就会去执行 debugger_script_path 中的脚本

int _PyRunRemoteDebugger(PyThreadState *tstate)
{
    const PyConfig *config = _PyInterpreterState_GetConfig(tstate->interp);
    if (config->remote_debug == 1
         && tstate->remote_debugger_support.debugger_pending_call == 1)
    {
        tstate->remote_debugger_support.debugger_pending_call = 0;

        // Immediately make a copy in case of a race with another debugger
        // process that's trying to write to the buffer. At least this way
        // we'll be internally consistent: what we audit is what we run.
        const size_t pathsz
            = sizeof(tstate->remote_debugger_support.debugger_script_path);

        char *path = PyMem_Malloc(pathsz);
        if (path) {
            // And don't assume the debugger correctly null terminated it.
            memcpy(
                path,
                tstate->remote_debugger_support.debugger_script_path,
                pathsz);
            path[pathsz - 1] = '\0';
            if (*path) {
                run_remote_debugger_script(path);
            }
            PyMem_Free(path);
        }
    }
    return 0;
}

那么问题来了，我们现在怎么样给目标 Python 进程注入对应的值呢？我们来看看 remote_debugging.c 中的实现

首先入口函数为 _PySysRemoteDebug_SendExec

int
_PySysRemoteDebug_SendExec(int pid, int tid, const char *debugger_script_path)
{
#if !defined(Py_SUPPORTS_REMOTE_DEBUG)
    PyErr_SetString(PyExc_RuntimeError, "Remote debugging is not supported on this platform");
    return -1;
#elif !defined(Py_REMOTE_DEBUG)
    PyErr_SetString(PyExc_RuntimeError, "Remote debugging support has not been compiled in");
    return -1;
#else

    PyThreadState *tstate = _PyThreadState_GET();
    const PyConfig *config = _PyInterpreterState_GetConfig(tstate->interp);
    if (config->remote_debug != 1) {
        PyErr_SetString(PyExc_RuntimeError, "Remote debugging is not enabled");
        return -1;
    }

    proc_handle_t handle;
    if (init_proc_handle(&handle, pid) < 0) {
        return -1;
    }

    int rc = send_exec_to_proc_handle(&handle, tid, debugger_script_path);
    cleanup_proc_handle(&handle);
    return rc;
#endif
}

前面都是一些例行的检查，我们来看看 send_exec_to_proc_handle 这个函数

static int
send_exec_to_proc_handle(proc_handle_t *handle, int tid, const char *debugger_script_path)
{
    uintptr_t runtime_start_address;
    struct _Py_DebugOffsets debug_offsets;

    if (read_offsets(handle, &runtime_start_address, &debug_offsets)) {
        return -1;
    }

    uintptr_t interpreter_state_list_head = (uintptr_t)debug_offsets.runtime_state.interpreters_head;

    uintptr_t interpreter_state_addr;
    if (0 != read_memory(
            handle,
            runtime_start_address + interpreter_state_list_head,
            sizeof(void*),
            &interpreter_state_addr))
    {
        return -1;
    }

    if (interpreter_state_addr == 0) {
        PyErr_SetString(PyExc_RuntimeError, "Can't find a running interpreter in the remote process");
        return -1;
    }

    int is_remote_debugging_enabled = 0;
    if (0 != read_memory(
            handle,
            interpreter_state_addr + debug_offsets.debugger_support.remote_debugging_enabled,
            sizeof(int),
            &is_remote_debugging_enabled))
    {
        return -1;
    }

    if (is_remote_debugging_enabled != 1) {
        PyErr_SetString(
            PyExc_RuntimeError,
            "Remote debugging is not enabled in the remote process");
        return -1;
    }

    uintptr_t thread_state_addr;
    unsigned long this_tid = 0;

    if (tid != 0) {
        if (0 != read_memory(
                handle,
                interpreter_state_addr + debug_offsets.interpreter_state.threads_head,
                sizeof(void*),
                &thread_state_addr))
        {
            return -1;
        }
        while (thread_state_addr != 0) {
            if (0 != read_memory(
                    handle,
                    thread_state_addr + debug_offsets.thread_state.native_thread_id,
                    sizeof(this_tid),
                    &this_tid))
            {
                return -1;
            }

            if (this_tid == (unsigned long)tid) {
                break;
            }

            if (0 != read_memory(
                    handle,
                    thread_state_addr + debug_offsets.thread_state.next,
                    sizeof(void*),
                    &thread_state_addr))
            {
                return -1;
            }
        }

        if (thread_state_addr == 0) {
            PyErr_SetString(
                PyExc_RuntimeError,
                "Can't find the specified thread in the remote process");
            return -1;
        }
    } else {
        if (0 != read_memory(
                handle,
                interpreter_state_addr + debug_offsets.interpreter_state.threads_main,
                sizeof(void*),
                &thread_state_addr))
        {
            return -1;
        }

        if (thread_state_addr == 0) {
            PyErr_SetString(
                PyExc_RuntimeError,
                "Can't find the main thread in the remote process");
            return -1;
        }
    }

    // Ensure our path is not too long
    if (debug_offsets.debugger_support.debugger_script_path_size <= strlen(debugger_script_path)) {
        PyErr_SetString(PyExc_ValueError, "Debugger script path is too long");
        return -1;
    }

    uintptr_t debugger_script_path_addr = (uintptr_t)(
        thread_state_addr +
        debug_offsets.debugger_support.remote_debugger_support +
        debug_offsets.debugger_support.debugger_script_path);
    if (0 != write_memory(
            handle,
            debugger_script_path_addr,
            strlen(debugger_script_path) + 1,
            debugger_script_path))
    {
        return -1;
    }

    int pending_call = 1;
    uintptr_t debugger_pending_call_addr = (uintptr_t)(
        thread_state_addr +
        debug_offsets.debugger_support.remote_debugger_support +
        debug_offsets.debugger_support.debugger_pending_call);
    if (0 != write_memory(
            handle,
            debugger_pending_call_addr,
            sizeof(int),
            &pending_call))

    {
        return -1;
    }

    uintptr_t eval_breaker;
    if (0 != read_memory(
            handle,
            thread_state_addr + debug_offsets.debugger_support.eval_breaker,
            sizeof(uintptr_t),
            &eval_breaker))
    {
        return -1;
    }

    eval_breaker |= _PY_EVAL_PLEASE_STOP_BIT;

    if (0 != write_memory(
            handle,
            thread_state_addr + (uintptr_t)debug_offsets.debugger_support.eval_breaker,
            sizeof(uintptr_t),
            &eval_breaker))

    {
        return -1;
    }

    return 0;
}

我们先不考虑具体的细节的话，这段函数的逻辑还是非常明确的，通过 read_offsets 获取目标的地址偏移，通过 read_memory 这个函数读取不同地址，然后做一些处理后，通过 write_memory 来写入到目标进程中去

而 read_offsets 这个函数就是我们前面核心提到过的怎么样使用目前 Python 给出的调试信息的例子，我们来看一下其在 Linux 下的实现

static int
read_offsets(
    proc_handle_t *handle,
    uintptr_t *runtime_start_address,
    _Py_DebugOffsets* debug_offsets
) {
    if (_Py_RemoteDebug_ReadDebugOffsets(handle, runtime_start_address, debug_offsets)) {
        return -1;
    }
    if (ensure_debug_offset_compatibility(debug_offsets)) {
        return -1;
    }
    return 0;
}

这里的核心函数是 _Py_RemoteDebug_ReadDebugOffsets，我们接着来看这个的实现

static int
_Py_RemoteDebug_ReadDebugOffsets(
    proc_handle_t *handle,
    uintptr_t *runtime_start_address,
    _Py_DebugOffsets* debug_offsets
) {
    *runtime_start_address = _Py_RemoteDebug_GetPyRuntimeAddress(handle);
    if (!*runtime_start_address) {
        if (!PyErr_Occurred()) {
            PyErr_SetString(
                PyExc_RuntimeError, "Failed to get PyRuntime address");
        }
        return -1;
    }
    size_t size = sizeof(struct _Py_DebugOffsets);
    if (0 != _Py_RemoteDebug_ReadRemoteMemory(handle, *runtime_start_address, size, debug_offsets)) {
        return -1;
    }
    return 0;
}

我们注意到，这里的核心还是我们先要获取到 PyRuntime 的地址，那么我们来看看 _Py_RemoteDebug_GetPyRuntimeAddress 的实现

static uintptr_t
_Py_RemoteDebug_GetPyRuntimeAddress(proc_handle_t* handle)
{
    uintptr_t address;
    address = search_linux_map_for_section(handle, "PyRuntime", "python");
    if (address == 0) {
        // Error out: 'python' substring covers both executable and DLL
        PyErr_SetString(PyExc_RuntimeError, "Failed to find the PyRuntime section in the process.");
    }
    return address;
}

static uintptr_t
search_linux_map_for_section(proc_handle_t *handle, const char* secname, const char* substr)
{
    char maps_file_path[64];
    sprintf(maps_file_path, "/proc/%d/maps", handle->pid);

    FILE* maps_file = fopen(maps_file_path, "r");
    if (maps_file == NULL) {
        PyErr_SetFromErrno(PyExc_OSError);
        return 0;
    }

    size_t linelen = 0;
    size_t linesz = PATH_MAX;
    char *line = PyMem_Malloc(linesz);
    if (!line) {
        fclose(maps_file);
        PyErr_NoMemory();
        return 0;
    }

    uintptr_t retval = 0;
    while (fgets(line + linelen, linesz - linelen, maps_file) != NULL) {
        linelen = strlen(line);
        if (line[linelen - 1] != '\n') {
            // Read a partial line: realloc and keep reading where we left off.
            // Note that even the last line will be terminated by a newline.
            linesz *= 2;
            char *biggerline = PyMem_Realloc(line, linesz);
            if (!biggerline) {
                PyMem_Free(line);
                fclose(maps_file);
                PyErr_NoMemory();
                return 0;
            }
            line = biggerline;
            continue;
        }

        // Read a full line: strip the newline
        line[linelen - 1] = '\0';
        // and prepare to read the next line into the start of the buffer.
        linelen = 0;

        unsigned long start = 0;
        unsigned long path_pos = 0;
        sscanf(line, "%lx-%*x %*s %*s %*s %*s %ln", &start, &path_pos);

        if (!path_pos) {
            // Line didn't match our format string.  This shouldn't be
            // possible, but let's be defensive and skip the line.
            continue;
        }

        const char *path = line + path_pos;
        const char *filename = strrchr(path, '/');
        if (filename) {
            filename++;  // Move past the '/'
        } else {
            filename = path;  // No directories, or an empty string
        }

        if (strstr(filename, substr)) {
            retval = search_elf_file_for_section(handle, secname, start, path);
            if (retval) {
                break;
            }
        }
    }

    PyMem_Free(line);
    fclose(maps_file);

    return retval;
}

我们这里能看到 _Py_RemoteDebug_GetPyRuntimeAddress 调用了 search_linux_map_for_section 来获取当前的 PyRuntime 的地址，而 search_linux_map_for_section 则是通过 /proc/${pid}/maps ，暴力遍历 maps 中的内存段来获取具体的地址。

我们来看看 search_elf_file_for_section 的实现

search_elf_file_for_section(
        proc_handle_t *handle,
        const char* secname,
        uintptr_t start_address,
        const char *elf_file)
{
    if (start_address == 0) {
        return 0;
    }

    uintptr_t result = 0;
    void* file_memory = NULL;

    int fd = open(elf_file, O_RDONLY);
    if (fd < 0) {
        PyErr_SetFromErrno(PyExc_OSError);
        goto exit;
    }

    struct stat file_stats;
    if (fstat(fd, &file_stats) != 0) {
        PyErr_SetFromErrno(PyExc_OSError);
        goto exit;
    }

    file_memory = mmap(NULL, file_stats.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
    if (file_memory == MAP_FAILED) {
        PyErr_SetFromErrno(PyExc_OSError);
        goto exit;
    }

    Elf_Ehdr* elf_header = (Elf_Ehdr*)file_memory;

    Elf_Shdr* section_header_table = (Elf_Shdr*)(file_memory + elf_header->e_shoff);

    Elf_Shdr* shstrtab_section = §ion_header_table[elf_header->e_shstrndx];
    char* shstrtab = (char*)(file_memory + shstrtab_section->sh_offset);

    Elf_Shdr* section = NULL;
    for (int i = 0; i < elf_header->e_shnum; i++) {
        char* this_sec_name = shstrtab + section_header_table[i].sh_name;
        // Move 1 character to account for the leading "."
        this_sec_name += 1;
        if (strcmp(secname, this_sec_name) == 0) {
            section = §ion_header_table[i];
            break;
        }
    }

    Elf_Phdr* program_header_table = (Elf_Phdr*)(file_memory + elf_header->e_phoff);
    // Find the first PT_LOAD segment
    Elf_Phdr* first_load_segment = NULL;
    for (int i = 0; i < elf_header->e_phnum; i++) {
        if (program_header_table[i].p_type == PT_LOAD) {
            first_load_segment = &program_header_table[i];
            break;
        }
    }

    if (section != NULL && first_load_segment != NULL) {
        uintptr_t elf_load_addr = first_load_segment->p_vaddr
            - (first_load_segment->p_vaddr % first_load_segment->p_align);
        result = start_address + (uintptr_t)section->sh_addr - elf_load_addr;
    }

exit:
    if (file_memory != NULL) {
        munmap(file_memory, file_stats.st_size);
    }
    if (fd >= 0 && close(fd) != 0) {
        PyErr_SetFromErrno(PyExc_OSError);
    }
    return result;
}

这段代码稍微有点复杂，我们来拆分看一下

首先函数的声明

search_elf_file_for_section(
        proc_handle_t *handle,
        const char* secname,
        uintptr_t start_address,
        const char *elf_file)

用于在ELF文件中搜索特定的section。参数包括：进程句柄、要查找的section名称、起始地址（文件在进程空间的映射位置）、ELF文件路径。

int fd = open(elf_file, O_RDONLY);
if (fd < 0) {
    PyErr_SetFromErrno(PyExc_OSError);
    goto exit;
}

以只读方式打开ELF文件，如果失败则设置Python异常并跳转到退出处理。

file_memory = mmap(NULL, file_stats.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
if (file_memory == MAP_FAILED) {
    PyErr_SetFromErrno(PyExc_OSError);
    goto exit;
}

将文件内容映射到内存，以只读和私有方式，从文件头开始。失败则设置异常并退出。

1 2	Elf_Ehdr* elf_header = (Elf_Ehdr)file_memory; Elf_Shdr section_header_table = (Elf_Shdr*)(file_memory + elf_header->e_shoff);

将文件开头 cast 为ELF文件头结构，并找到section header表的位置，它在文件偏移e_shoff处。

Elf_Shdr* shstrtab_section = §ion_header_table[elf_header->e_shstrndx];
char* shstrtab = (char*)(file_memory + shstrtab_section->sh_offset);
Elf_Shdr* section = NULL;
for (int i = 0; i < elf_header->e_shnum; i++) {
    char* this_sec_name = shstrtab + section_header_table[i].sh_name;
    // Move 1 character to account for the leading "."
    this_sec_name += 1;
    if (strcmp(secname, this_sec_name) == 0) {
        section = §ion_header_table[i];
        break;
    }
}

获取section字符串表（包含所有section名称的表），通过e_shstrndx索引定位。同时遍历所有section，查找匹配的section名称。注意需要跳过section名字的”.”前缀。

Elf_Phdr* program_header_table = (Elf_Phdr*)(file_memory + elf_header->e_phoff);
// Find the first PT_LOAD segment
Elf_Phdr* first_load_segment = NULL;
for (int i = 0; i < elf_header->e_phnum; i++) {
    if (program_header_table[i].p_type == PT_LOAD) {
        first_load_segment = &program_header_table[i];
        break;
    }
}

找到program header表，然后搜索第一个PT_LOAD类型的segment，它定义了程序加载时的基地址。

if (section != NULL && first_load_segment != NULL) {
    uintptr_t elf_load_addr = first_load_segment->p_vaddr
        - (first_load_segment->p_vaddr % first_load_segment->p_align);
    result = start_address + (uintptr_t)section->sh_addr - elf_load_addr;
}

如果找到了目标section和第一个LOAD segment，计算目标section的运行时地址：

计算ELF文件的加载基地址（考虑对齐）
目标地址 = 进程中映射的起始地址 + section的虚拟地址 - ELF加载基地址

经过这样一个流程，我们就能最终的获取到 _PyRuntime 中的地址，然后基于此做一些包括 PEP 768 在内很有趣的工作。

总结

Python 3.14 官方其实将进程信息以半正式化的形式形成了一组相对稳定的 ABI，这样可以使我们调试工具能以更好的方式对 Python 进程进行无侵入的调试与观测。PEP 768 其实是这个过程中一个的有效产物。而基于 PEP768 处理的比如 Remote PDB debug，目前也已合入分支。

可以说从 Python 3.14 起，Python 的调试工具和手段将得到极大的丰富与增强。建议大家在出来后的第一时间进行升级（

差不多就这样（

简单聊聊常见的负载均衡算法

2025-03-23T12:00:00.000Z

这篇文章鸽了很久，最终决定还是老老实实写完，来介绍一下常见的一些负载均衡算法实现。本文的代码最终都会放在 load-balancer-algorithm¹ 这个 repo 中

~~我从来没有觉得写博客快乐过~~

正文

先行准备

既然是讲 LoadBalancer 中常用的一些负载均衡算法，我们先来对一些前置准备做一些讨论

我们目前需要两个基础的数据结构

代表着 Backend 节点的结构
代表着请求上下文的结构

那么我们可以得出下面一些基础代码

import dataclasses


@dataclasses.dataclass
class Node:
    host: str = ""
    port: int = 0
    node_available: bool = True

    @property
    def available(self) -> bool:
        return self.node_available

import dataclasses


@dataclasses.dataclass
class RequestContext:
    pass

同时我们在没有后端节点可供选择的时候，我们需要抛出一个异常

1 2	class NoNodesAvailableError(ValueError): pass

好了，我们现在可以进行更进一步的抽象，我们可以将我们的负载均衡算法抽象为策略(Strategy), 那么我们可以得出如下的一些代码

from __future__ import annotations

import typing
from abc import ABC, abstractmethod

if typing.TYPE_CHECKING:
    from load_balancer_algorithm.context import RequestContext
    from load_balancer_algorithm.node import Node


class Strategy(ABC):
    nodes: list[Node] = []

    def __init__(self, nodes:list[Node]) -> None:
        self.nodes = nodes

    @abstractmethod
    def get_node(self, ctx: RequestContext) -> Node:
        pass

    def add_node(self, node: Node) -> None:
        self.nodes.append(node)

    def remove_node(self, node: Node) -> None:
        self.nodes= list(filter(lambda n: n != node, self.nodes))

好了，我们现在可以往下去实现一些负载均衡算法了

随机选择

负载均衡最简单的一个算法是做一个随机的选择，实现非常简单，最简单的伪代码实现差不多这样

1 2	a = [] random.choice(a)

我们来完整实现一下

class RandomStrategy(Strategy):
    def get_node(self, ctx: RequestContext) -> Node:
        nodes = list(filter(lambda node: node.available, self.nodes))
        if not nodes:
            raise NoNodesAvailableError

        return random.choice(nodes)

OK，现在我们增加一个需求，现在我们每个节点都需要有一个权重值，权重值越高的节点被选中的概率越高。我们可以使用 random.choices 来实现这个需求，不过在此之前我们需要对 Node 进行一些修改

import dataclasses


@dataclasses.dataclass
class Node:
    host: str = ""
    port: int = 0
    node_available: bool = True
    weight: int = 0

    @property
    def available(self) -> bool:
        return self.node_available

然后我们来实现一下 WeightedRandomStrategy


class WeightedRandomStrategy(Strategy):
    def get_node(self, ctx: RequestContext) -> Node:
        nodes = list(filter(lambda node: node.available, self.nodes))
        if not nodes:
            raise NoNodesAvailableError

        weights = [node.weight for node in nodes]
        return random.choices(nodes, weights=weights)[0]

Random 确实是我们非常常用的一套负载均衡算法，但是缺点也很明显，其负载均衡的效果有一定的不可预测性，是神是鬼全靠你使用的 Random 函数的质量。运气不好就会出现分布非常密集的情况。那么我们有没有可用的更好的负载均衡算法呢？

轮询算法

我们对于负载均衡算法常见的需求是在逻辑上有一定的可预测性，从这角度上讲，轮询算法是一个非常好的选择。我们可以使用一个 index 来记录当前的节点，然后每次请求的时候都将 index + 1，直到 index 超过节点的数量，然后 index = 0

class RoundRobinStrategy(Strategy):
    def __init__(self, nodes: list[Node]) -> None:
        super().__init__(nodes)
        self.index = 0

    def get_node(self, ctx: RequestContext) -> Node:
        nodes = list(filter(lambda node: node.available, self.nodes))
        if not nodes:
            raise NoNodesAvailableError

        node = nodes[self.index]
        self.index += 1
        if self.index >= len(nodes):
            self.index = 0

        return node

这里我们实现了一个最基础的轮询算法（我们假设不存在节点不可用，节点增删改的情况），所以我们 index 一直可以有规律的变化

这里的结果很明显，如果有一个 [A, B] 的节点列表，那么我们会得到一个 [A, B, A, B, A, B] 的结果

那么现在我们更改一下需求，我们需要实现一个类似 WeightedRandomStrategy 的轮询算法，权重越高的节点被选中的概率越高。

class WeightedRoundRobinStrategy(Strategy):
    def __init__(self, nodes: list[Node]) -> None:
        super().__init__(nodes)
        self.index = 0
    
    def get_node(self, ctx: RequestContext) -> Node:
        nodes = list(filter(lambda node: node.available, self.nodes))
    
        if not nodes:
            raise NoNodesAvailableError
        nodes=[node for node in nodes for _ in range(node.weight)]
        node = nodes[self.index]
        self.index += 1
        if self.index >= len(nodes):
            self.index = 0
        return node

这里的核心算法很简单，我们基于每个节点的权重，得到一个扩展后的节点列表，然后我们就可以使用最基础的轮询算法来实现了

但是这里核心的一个弊端很明显，假设我们有 [A(weight=2),B(weight=1)] 这样一个节点组合，我们会得到 [A, A, B] 这样一个选择结果，这里的节点分布会非常不均匀。那么怎么办呢？我们可以参考一种来自 Nginx 的平滑算法²

我们首先给节点加上一个 current_weight 的熟悉，记录当前节点的权重值

import dataclasses


@dataclasses.dataclass
class Node:
    host: str = ""
    port: int = 0
    node_available: bool = True
    weight = 0
    current_weight: int = 0

    @property
    def available(self) -> bool:
        return self.node_available

    def __post_init__(self):
        self.current_weight = self.weight

然后我们来实现一下 WeightedRoundRobinStrategy

class WeightedRoundRobinStrategy(RoundRobinStrategy):
    def get_node(self, ctx: RequestContext) -> Node:
        nodes = list(filter(lambda node: node.available, self.nodes))
        if not nodes:
            raise NoNodesAvailableError
        best_node = None
        total = 0
        for node in nodes:
            total += node.weight
            node.current_weight = node.weight
            if not best_node or node.current_weight > best_node.current_weight:
                best_node = node
        if not best_node:
            raise NoNodesAvailableError
        best_node.current_weight -= total
        return best_node

这里新增的 current_weight 的作用很简单，

每次选取节点时，遍历可用节点，遍历时把当前节点的 current_weight 的值加上它的 weight
同时累加所有节点的 weight 值为 total 。
如果当前节点的 current_weight 值最大，那么这个节点就是被选中的节点，同时把它的 current_weight 减去 total
没有被选中的节点的 current_weight 不用减少。

这本质上其实很巧妙的将节点打散，同时将 index 的属性利用 current_weight 来处理，经过处理，我们假设有 [A(weight=3),B(weight=2),C(weight=1)] 这样一个节点组合，我们会得到 [A, B, A, C, B, A] 这样一个选择结果，这里的节点分布会相对均匀很多

OK，现在我们轮询函数实现完成了，我们能发现，Random 和轮询算法本质上是两种无状态的算法（最原始的 RoundRobin 有状态，但是我们通过 current_weight 的方式将其变成了无状态），但是我们通常在业务上会有一些根据状态来选择节点的需求，常见的场景有

我们需要请求去往目前负载最低的节点
某一类请求我们需要去往同一个节点

因此下面我们会来介绍两种算法

最小链接/加权最小链接
一致性 Hash 算法

最小链接算法

最小链接算法是一个非常简单的算法，我们需要在每次请求的时候，遍历所有的节点，找到当前连接数最少的节点，然后将请求转发到这个节点上。我们可以使用一个连接数的属性来记录当前节点的连接数

class LeastConnectionStrategy(Strategy):
    def get_node(self, ctx: RequestContext) -> Node:
        best = None
        for node in self.nodes:
            if not node.available:
                continue
            if not best or node.connections < best.connections:
                best = node
        if not best:
            raise NoNodesAvailableError
        best.connections += 1
        return best

OK，那么我们接下来老规矩需要考虑加权的 LeastConnection 算法，这里稍晚有一点绕

假设用 C 表示连接数、W 表示权重、S 表示被选中的节点、Sn 表示未被选中的节点
那么 S 必须满足 C(S) / W(S) < C(Sn) / W(Sn) ，这个条件也可以表示为 C(S) x W(Sn) < C(Sn) x W(S)

那么我们来实现一下

class WeightedLeastConnectionStrategy(LeastConnectionStrategy):
    def get_node(self, ctx: RequestContext) -> Node:
        best = None
        for node in self.nodes:
            if not node.available:
                continue
            if not best or (node.connections / node.weight) < (best.connections / best.weight):
                best = node
        if not best:
            raise NoNodesAvailableError
        best.connections += 1
        return best

当然我们这里实际上有一点问题是，这里的选择可能会连续选择到同一个节点上（因为权重的不均匀），这里可以考虑把符合条件的节点放到一个列表中，然后使用我们前面提到过的 RoundRobin/Random 来选择一个节点来进行请求转发

这里我就不实现了，大家可以自己实现一下

一致性 Hash 算法

我们在业务中经常有这样一种需求，我们需要将同一类请求转发到同一个节点上，这个时候我们就需要使用一致性 Hash 算法来实现了

最基础的一致性 Hash 算法是将请求的 key 和节点的 key 进行 hash 计算，然后将请求转发到 hash 值最接近的节点上。我们可以使用一个 ring 来表示所有的节点，然后在 ring 上找到离请求最近的节点。

但是这样存在比较大的问题是，如果有节点的增删改，这个时候我们已经分配好的逻辑会存在 rebalance 的问题。所以我们需要将这个变动变得最小。

目前主流的几种一致性 Hash 算法的核心思路都是通过虚拟节点来解决这个问题。我们可以将每个节点映射到多个虚拟节点上，然后在 ring 上找到离请求最近的虚拟节点，然后将请求转发到对应的真实节点上。

这样我们就可以将节点的增删改对请求的影响降到最低。

我们将以 Google 的 Maglev 算法为基础来实现一致性 Hash 算法

首先我们更改一下 Node 的代码

import dataclasses


@dataclasses.dataclass
class Node:
    host: str = ""
    port: int = 0
    node_available: bool = True
    weight: int = 0
    current_weight: int = 0
    connections: int = 0

    @property
    def available(self) -> bool:
        return self.node_available

    def __str__(self) -> str:
        return f"{self.host}:{self.port}"

这里我们可以用 str(node) 来获取 nodekey

然后我们来介绍一下 Maglev 算法的核心思路（这里只介绍最简化版本的细节，详情可以参考 Maglev: A Fast and Reliable Software Network Load Balancer³）这篇论文

首先，我们要确定经过预处理后的产物 lookup table 的长度 M。所有 Key 都会被 hash 到这个 lookup table 中去，而 lookup table 中的每个元素都会被映射到一个 Node 上

而计算 lookup table 的计算分为两步

计算每一个 node 对于每一个 lookup table 项的一个取值（也就是原文中提到的 permutation）；
根据这个值，去计算每一个 lookup table 项所映射到的 node（放在 entry 中，此处 entry 用原文的话来讲就是叫做 the final lookup table）。

permutation 是一个 NM 的矩阵，列对应 *lookup table，行对应 node。为了计算 permutation，需要挑选两个 hash 算法，分别计算两个值 offset 与 skip 。最后根据 offset 和 skip 的值来填充 permutation，计算方式描述如下：

offset = hash1(name[i]) mod M
skip = hash2(name[i]) mod (M − 1)+ 1
permutation[i][j] = (offset+ j × skip) mod M

其中 hash1 和 hash2 是两个不同的 hash 函数，我们后续会使用 xxhash 和 mmh3 这两种 hash 函数来实现

然后我们可以给出 lookup table 的计算方式

def calculate_lookup_table(n: int, m: int, permutation: list[list[int]]) -> list[int]:
    # result 是最终记录分布的 Hash 表
    result: list[int] = [-1] * m
    # next 是用来解决冲突的，在遍历过程中突然想要填入的 entry 表已经被占用，
    # 则通过 next 找到下一行。一直进行该过程直到找到一个空位。
    # 因为每一列都包含有 0~M-1 的每一个值，所以最终肯定能遍历完每一行。
    # 计算复杂度为 O(M logM) ~ O(M^2)
    next: list[int] = [0] * n
    flag = 0
    while True:
        for i in range(n):
            x = permutation[i][next[i]]
            while True:
                # 找到空位，退出查找
                if result[x] == -1:
                    break
                next[i] += 1
                x = permutation[i][next[i]]
            result[x] = i
            next[i] += 1
            flag += 1
            # 表已经填满，退出计算
            if flag == m:
                return result

在这里我们能看到，这段循环代码必然结束，而最坏情况下，复杂度会非常高，最坏的情况可能会到 O(M^2)。原文中建议找一个远大于 N 的 M （To avoid this happening we always choose M such that M ≫ N.）可以使平均复杂度维持在 O(MlogM)

我们可以用论文中的图来评估下如果节点存在移除的情况，整体的 rebalance 的效果

我们现在来完整实现一下 Maglev 算法，我们先确定用请求中的 url 来作为 hash key，所以我们需要对 RequestContext 进行一些修改

import dataclasses


@dataclasses.dataclass
class RequestContext:
    url: str = ""

好了，来把剩下的部分实现了

M = 65537


class MaglevStrategy(Strategy):
    @staticmethod
    def calculate_lookup_table(n: int, m: int, permutations: list[list[int]]) -> list[int]:
        # result 是最终记录分布的 Hash 表
        result: list[int] = [-1] * m
        # next 是用来解决冲突的，在遍历过程中突然想要填入的 entry 表已经被占用，
        # 则通过 next 找到下一行。一直进行该过程直到找到一个空位。
        # 因为每一列都包含有 0~M-1 的每一个值，所以最终肯定能遍历完每一行。
        # 计算复杂度为 O(M logM) ~ O(M^2)
        next: list[int] = [0] * n
        flag = 0
        while True:
            for i in range(n):
                x = permutations[i][next[i]]
                while True:
                    # 找到空位，退出查找
                    if result[x] == -1:
                        break
                    next[i] += 1
                    x = permutations[i][next[i]]
                result[x] = i
                next[i] += 1
                flag += 1
                # 表已经填满，退出计算
                if flag == m:
                    return result

    def __init__(self, nodes: list[Node]) -> None:
        super().__init__(nodes)
        permutations = []
        for i in range(len(nodes)):
            permutation = [0] * M
            offset = mmh3.hash(str(nodes[i])) % M
            skip = (xxhash.xxh32(str(nodes[i])).intdigest() % (M - 1)) + 1
            for j in range(M):
                permutation[j] = (offset + j * skip) % M
            permutations.append(permutation)
        self.tables = self.calculate_lookup_table(len(nodes), M, permutations)

    def get_node(self, ctx: RequestContext) -> Node:
        hash_value = mmh3.hash(str(ctx))
        index = hash_value % M
        node_index = self.tables[index]
        return self.nodes[node_index]

如果大家对 Google 整个 Maglev 系统感兴趣，可以去参考一篇我之前写博客，简单聊聊 Maglev ，来自 Google 的软负载均衡实践⁴

总结

好了，这次负载均衡算法告一段落，其实工作中还有一些更组合的场景，比如 sharding 轮询之类的，不过整体思路都不会发生太大变化。希望大家看的开心

Reference

https://github.com/Zheaoli/load-balancer-algorithm

https://github.com/nginx/nginx/commit/52327e0627f49dbda1e8db695e63a4b0af4448b1

https://research.google/pubs/maglev-a-fast-and-reliable-software-network-load-balancer/

https://www.manjusaka.blog/posts/2020/05/22/a-simple-introduction-about-maglev

简单吐槽一下摇曳露营的台配

2025-02-03T18:00:00.000Z

看了一下台配摇曳露营的 PV 放松，有些地方很想吐槽，写个短文聊一下

正文

先放出两版本对比

下面是原版

下面是台配

现在我们来聊一聊我觉得这个配音出现了什么样的问题

首先这是出自摇曳露营 S1E1 的最开始的部分。实际上是一个倒序的模式，将五人组的富士山露营在最开始进行展现，然后在季末进行收尾。

这个做法的效果和意图都很明确，其核心在于

让声优用声音将角色本身的性格立住

在这里面我认为问题最大的两个人，

大垣千明
齐藤惠那

其实犬山葵的问题也挺大的，但是出于方言角色确实不太好把握，这里就不多说了。

这两个角色的其实问题都很一致，配音者对于角色的性格把握不准。大垣千明是一个很干脆利落的角色，在四人组中是一个类似数码宝贝中太一一样 Leader 的角色，喜欢开玩笑，有一点假小子的感觉。而齐藤惠那性格和大垣千明有一些类似，不过齐藤会有更多一些少女味，所以她也成为四人组与凛之间的融合剂。

在原配中，大垣千明全程以很干脆利落的声线立住了人设。而齐藤惠那主要的两句台词“犬山同学，这样可以吗？”和“欸？真的吗？”声优很巧妙的换了不同的发声方式，让角色瞬间立体了起来。

在台配中，两者的声质都显得非常黏，或者用更不客气的观感来说，五个人的声质完全很难立住人设，属于是教科书里应该出现的声音，而不是动画里应该出现的声音。

而且台配还有一个比较明显的问题，声优对于情绪的把握出现了问题，比如还是经典的齐藤惠那的“欸？真的吗？”（背景是犬山提醒烤棉花糖不要离火太近，否则会烤焦）这句台词，原配中是一个带着学到新东西的惊讶的语气，而在台配中却在声音中显出了一些焦急。我觉得这是合格的声优不应该出现的意料外的问题。

另外一点其实被很多人忽略了，日语和中文的发音节奏和习惯是不一样的。在引入过程中，台词可能需要做一些适当的调整。比如在原配中，大垣千明的“欸！来芝麻凛的可可”(ほいしまりんココア一丁) ，这里 “一丁” 是日语中一个很口语的用法，声优选择在这里加了一个重音，来体现一个服务生的感觉，从而表现出大垣千明的古灵精怪。而在台配中，直接处理为“来，志摩凛的可可”，这里就没有很好的本土化。如果是我的话，我可能会选择更符合中文语境的 “来，志摩凛，你可可来咯！”这种口语化表达

这点在曾经上海电影译制厂译制的各种作品中体现的非常不错。我举个例子，在爱迪奥特曼第44话，激ファイト！ 80vsウルトラセブン/激斗，爱迪对战奥特赛文。中，不良暴走族在被假冒赛文狂追的时候，说“まだついてきやがるチクショウ”，直译为“该死，他还在跟着我。”，上译的老前辈们处理为“赛文还在追我，TMD”。而且用了非常痞子的声线，我觉得这就是展现了一个非常好的本土化的正面例子

放一个片段大家感受下

总结

差不多就吐槽这么多吧，翻译是一个累活苦活，希望大家也能多包容。希望不同地方的译者也能给我们带来不同的文化碰撞带来的惊喜。

差不多这样，祝大家新年快乐

Saka 馬鹿

2025-01-04T18:30:00.000Z

这篇博客是我在刷题群内的 2025 年的第一次分享整理的演讲稿。主要是完整复盘了过去几年里我犯下的两个比较典型的低级错误。

希望大家能看的开心

正文

首先来看一下我们抽象后的架构

很平平常规的一个架构。而我犯的两次相对低级的错误分别是在数据的入口和数据落点上。OK 那么我们分别来看一下我犯下的错误

首先要分享的是我搞出的一个核心数据库删除的事故。在介绍事故现场之前，我将先介绍下下当时我们整体资源管理的结构

我们基于 Terraform 管理资源
熟悉 Terraform 的同学都知道，Terraform 很重要的一点就是需要一个介质来存储当前 infra 的 state，这样能让后续的操作基于状态来实现 diff
我们当时的 state 是存储在 local fs ，state 文件跟随着 Git Repo 一起变更
我们基于目录划分不同业务需要的 AWS Infra 所对应的 Terraform 描述
关键设施没有开启删除保护

OK，我们继续往前讲，我们来激活一下事故现场的回忆

事故当天，需要给一个新的业务需要一个 AWS Aurora 实例
我直接复制了一个目录，然后重命名为新业务名
删除一些不必要的 TF 声明后，我就直接开始 terraform apply 了
因为将之前的 TF State 文件迁移到了新目录，同时修改了 TF 声明。Terraform 会判定需要删除以往的资源。在 apply 阶段的 destory 提示被我忽略
于是数据库没了.jpg

让我们先快进到事故的处理

在接到报警发现异常后，先第一时间中断 Terraform 执行并同步所有关联同事。
将所有关联服务流量 cutoff 并同步客服团队
基于已有快照重建数据库
大约事发1.5h后，恢复业务流量

非常刺激的一次经历。反思的部分我们放在后面。我们快进到第二次事故。CDN 变更事故。还是和之前一样先介绍一下大致的背景

我们的 CDN 因为处于成本，和架构统一的考虑，使用的是 AWS 的 Cloudflare
CDN 前面套了一层基础的 WAF 来处理一些恶意流量
会有一些业务脚本调用 AWS API 来触发 CDN 的 invalid 操作
我们当时在处理反爬虫的一些事情，需要额外更新一些 WAF Rule

那么梅开二度，让我们继续激活一下事故现场的回忆

给 WAF 直接上了官方推荐的 Anti Bot Rule
因为当时 WAF Rule 不支持灰度功能，所以没有做灰度
由于 AWS Anti Bot rule 会将 Android/iOS 的 UA 识别为 Bot，导致客户端流量跌0

继续快进到事故现场的处理

立刻进入熔断流程，切断相关流量并同步客服团队
由于业务调用 AWS 触发了 AWS 账号的 rate limit，所以无法第一时间解除对应的 WAF 规则
先停止业务脚本调用
大约在事发40min后，AWS rate limit 解除，我们将 WAF 规则回滚到之前的版本，恢复业务流量

痛苦的回忆先告一段落。我们来复盘一下我们这两个事故中的共性问题。首先务虚的说核心还是对生产抱有侥幸。那么从技术上来说存在哪些问题呢？

核心基础设施保护设置不到位
核心基础设施变更 Review 缺乏
缺少关键变更的灰度机制
对于业务方使用基础设施的手段缺乏监控和治理（在事故2中，如果不存在 rate limit 的时间，那么整个故障时间可以缩短在 10 min 以内）

所以围绕这样几个点，在事故发生后的一段时间内我在逐步推进一些改进

我们统一将 terraform state 从 local fs + git 的组合中解放出来，迁移到了 S3 存储，这样为后续 Terraform workflow 改造打下基础
我们引入 Atlantis 来管理 Terraform 的 PR Review。对于核心基础设施的变更需要 double review
巡检其余 Redis/MySQL/Kafka 等基础设施，统一开启删除保护/二次验证
对于 CDN 这类变更引入如下流程（实际上分为 AWS 支持灰度前后）
1. 支持灰度前
  1. 我们会从我们自建的网关中提取出一部分镜像 Query 流量
  2. 新建一个 CDN 实例
  3. 将新规则完整应用在新实例上后，进行流量重放，验证规则的有效性
2. 大约在2023年中后，AWS 对于 WAF 之类的规则新增了灰度的一些支持
  1. 我们会在 AWS WAF 中新建一个规则，action 仅为统计
  2. 在确认规则不会存在误伤后，我们会将 action 修改为目标需求
我们在事后统一盘点了业务侧对于基础设施 API 的一些使用情况，将相关问题统一治理

实际上在事故1和2中，我自己还有一些其余的建议给看到这篇文章的同学

在事故发生后，如果预计恢复时间比较长，请第一时间将服务降级/切断入口流量。避免在恢复阶段流量不断进来同时存在缓存雪崩等情况下连锁反应导致恢复时间急剧增加
对于数据库等数据关键数据落地点，一定要存在下面这样一些 action
1. 备份一定需要做
  1. 基于业务的重要性以及备份成本选择备份周期
  2. PITR 增量和全量备份都需要做
2. 一定需要定时对备份进行重建测试，目的主要有以下一些
  1. 验证备份的有效性（对于使用云厂商的数据库备份可靠性相对还好，自研工具做 fs snapshot 的需要特别注意）
  2. 验证不同规模下数据恢复的时间，在事故发生后对于恢复周期有个预期（在事故1中，因为我们之前没做过类似的演练，所以完全没法给出个时间点）（这里我们得到的一个参考时间经验公式是 9分钟/GB 的恢复时间）

总结

差不多就这样，希望大家能从我的分享中得到一些启发。最后，希望大家在新的一年里都能够顺利，事事顺心。

本当の僕らをありがとう

2024-12-31T15:00:00.000Z

每年都会选择一句话来总结自己这一年，前年是“但行好事，莫问前程”，去年是 “Per aspera, Ad astra”。那么今年我选择是 “本当の僕らをありがとう”。

这句出自《Angel Beats!》的片尾曲《My Song》。含义为“向最真实的我们致谢”

开篇

今年其实某种意义上是去年的延续，去年年中的我尝试从18楼一跃而下。而双相以及自己的不自信以及在职业上的焦虑让躯体化的症状持续到了今年。某种意义上来说今年是混沌的一年。

不过今年也是挺值得思考的一年，可能今年所积累的东西可能会在未来以某种特殊的形式回馈回来。

生活

双相的治疗进入了深水区，今年状态一直起伏不定，药物性肝损伤，双相波动带来的躯体化症状如影随行。今年虽然没有如同去年一样试图从18楼上来一次刺客信条。但是对我来说，艰险程度还超过去年。

一如既往的噩梦，各种生活里的反复一如既往的围绕着我。在调整治疗方案后，虽然情绪有所改善，但是所带来的副作用又成为新的问题。

不过日子还得过，生活也还得继续。爱和希望也还围绕着我。

你们可能还记得去年家里新增了一只名为小熊的猫。出身流浪，最让人担心。今年病危三次，挺过来三次，指标在年底进入稳定状态。主治医生评价“这命真硬啊”。某种意义上小熊算是成今年家里生命力的模板。

的今年对于我来说，另外一个最大的变化是买了一直心心念的相机，Z8 + 尼康 2.8 大三元，然后 11月份买了 Z9。看了下快门数差不多接近4w了，带着狗子出门拍照。也自己出去拍了好看的荷花。在经常遛狗的小公园帮很多家庭留下了美好的瞬间。某种意义上来说在按下快门以及和很多人分享照片的时候，是我今年这一年难得心灵上能放松的时候。Hhhhhh

剩下的就是一些碎碎念了，今年看了不少好看的番剧，86不存在的战区，青之箱，Angel Beat，胆大党 etc…. 某种意义上这些番剧成为我精神的一处安心之所。可能这就是二次元的意义吧.jpg

感情

感情进入了第六个年头，相伴真的是一件既幸福，又考验人的事

如果说去年荆澈同学将我从18楼飞出的瞬间抓了回来让这份感情添加了不少生死交错的厚重感。那么今年则是在这份厚重感上尝试去淡化生死的伤痕。

今年由于我状态波动非常大，荆澈同学相较于去年承担了更多宠物和生活上的琐事。比如带着猫咪周期性复查等等。

说实话陪伴一个心理病人稳定的走下去真的是一件非常辛苦的事。首当其冲的挑战是承受伴侣的情绪真的是很有挑战的一件事。所以希望在25年，我的情绪能更加的受控，让荆澈同学能有更多精力去做她所想做的事情

以及 25 年一定要和荆澈同学出去玩！

技术

如果说去年是“改革，啊不，学习进入了深水区”，那么今年我觉得可以是“学习进入了马里亚纳海沟”

今年我要要面临的更具有挑战性的事是我对于自身的怀疑。“我是否适合做技术？我是否能成为一个优秀的工程师？我是否能继续在这条路上稳定的走下去？”这成为我从业八年以来第一次对自己产生了自我的怀疑。

在这种怀疑之下，导致我很多时候会在焦虑驱动下去做一些事情。这样的结果无疑会很坏。我今年一直在尝试与自己和解。尝试去更无功利心，更无目标性的去放松的学习一些东西。这种做法有利有弊，有利的地方是我在一些间接性的兴趣驱使下，机缘巧合下扩展了自己的技术宽度（做一些 AI 以及前端的东西），但是也暴露出了我固有的一些缺点

在8年的职业生涯过去后，我似乎进入了一种思维的舒适区。我会依赖自己相对较强的快速学习和 landing 的能力去啃下不少东西。但是这也会导致我在不少问题的思考深度上有很明显的不足。我在过去这一年通过一些方式在调整自己的这样一些习惯。但是这一点在25年我也更希望能有所改进

不过往好处看，24年算是我积累的一年，这一年我在帮社区修了不少 Bug 之余，在 CPU 指令集/汇编/体系结构/编译原理等基础技能上也有了不小的提升。虽然短期内这些东西不太可能会有很高的收益。但是我感觉未来某一天这些东西会以某种形式回馈回来。

最后用一张图来总结下我的 2024 吧

总结

2024 虽然相较于之前有所摸鱼，不过也算是我自己必须要经历的一个过度年份吧。展望2025，最核心的目标还是和自己和解，希望能在年底的时候能对自己说“saka 你是个不错的人”

如果要说一些具体的小目标的话，那么我希望

和荆澈同学出远门旅游一次
新进入一个 Top 项目的 Org，成为 member/maintainer
继续保持每天刷题的节奏
尽可能保证每两周一篇博客（技术/生活/随笔）
能够去在完成一到两个前端应用（在 AI 辅助下）并在刷题群内分享
重新恢复刷题群的公益活动（刷题捐款，跑步捐款，以及公开分享（作为起始，这周五我先在刷题群内自己公开复盘一下自己过去几年犯过的低级的技术错误以及后续改进的 action （自我鞭尸（
自己能基于 Dify 等 AI Agent 框架做一些好玩的应用（自己目前有一些 idea Hhhh
保持每周一次的摄影活动

差不多就这样吧。

感谢大家 2024 的陪伴，saka 永远爱着你们（

OpenDAL 0.51 版本代号 “本当の僕らをありがとう。” 背后的故事

2024-12-14T18:30:00.000Z

Apache OpenDAL v0.51.0 第一个 RC 版本发布了，这个大版本有些特殊，是我第三个负责 Release 的版本，也是第一个带有 Subtitle 的版本

这个版本的副标题为 “本当の僕らをありがとう” ，意为 “向真实的我们致谢”

聊聊这个版本背后的一些故事吧

正文

在筹备 v0.51.0 的发版的时候，我本来是想想一个标题，来庆祝摇曳露营 S4 制作确定的。所以在 @xuanwo 和 @frostming 的支持和建议下。我发起了一个提案 [VOTE] Proposal: Adding Cultural References to Release Titles¹

提案 #5303 通过后，我本来想用志摩凛的一句我很喜欢的台词“ソロキャンは寂しさも楽しむものなんだって”来作为摇曳露营 S4 制作决定的庆祝。但是不知道怎么回事，我耳边突然想起了《My Song》这首歌

苛立ちをどこにぶつけるか，【焦躁地在哪里寻找的时候】，
探してる间に终わる日，【一天已经结束了】，
空は灰色をして，【天空一片灰暗】，
その先は何も见えない，【前方什么都看不见】，
常识ぶってる奴が笑ってる，【故作明了的家伙在笑】，
次はどんな嘘を言う？【接着又会说出怎样的谎言？】，
それで得られたもの，【由此所得之物】，
大事に饰っておけるの？【又怎会好好珍重呢？】，
でも明日へと进まなきゃならない，【但是我们必须向着明天前进】，
だからこう歌うよ，【因此放声高歌】，
泣いてる君こそ孤独な君こそ，【哭泣的你孤独的你反而】，
正しいよ人间らしいよ，【是更合理的更有人情味的】，
落とした涙がこう言うよ，【落下的泪水仿佛在说】，
こんなにも美しい嘘じゃない，【如此美丽毫不虚假的】，
本当の僕らをありがとう，【向真实的我们致谢啊】，
叶えたい梦や，【希望能够实现的梦想】，
届かない梦がある事，【及遥不可及的梦想】，
それ自体が梦になり希望になり，【其本身就是一种梦想化作了希望】，
人は生きてゆけるんだろ，【人才能活下去吧】，
扉はあるそこで待っている，【有一扇门在那里一直等待着】，
だから手を伸ばすよ，【所以伸出双手吧】，
挫けた君にはもう一度戦える，【为了让受挫折的你能再度奋战】，
强さと自信とこの歌を，【送上这首坚强的自信的歌】，
落とした涙がこう言うよ，【落下的泪水仿佛在说】，
こんなにも汚れて丑い世界で，【向在如此肮脏丑陋的世界中】，
出会えた奇迹にありがとう，【相遇的奇迹致谢吧】。

先附上歌的链接

国内读者²
国外读者³

可能熟悉二次元的同学已经反应过来了，这是来自于《Angel Beats!》第三话的插曲《My Song》的歌词。在现实生活中，由歌手中村真里奈演唱。收藏在专辑《Crow Song》中

Angel Beats! 是一部由 Key 制作的动画，讲述了一群都有着生前特殊的遗憾的人们聚集在一个名为“死后世界”的地方，通过与“天使”对抗，寻找自己的遗憾，最终解决自己的遗憾，从而得以超度的故事。而《My Song》的剧中主唱，岩泽雅美（岩沢まさみ）便是其中的一员。

Angel Beat 每个人的故事都很特殊，男主音无结弦，从小和重病的妹妹相依为命，为了治愈更多的人而立志投生于医学。但是在前往医学院的考场路上遇上土石塌方。在黑暗中音无利用自己的医学知识帮助其余人使其活到了救援到来的时候。而在救援队挖开落石的那一刻因为伤势过重而死亡。在死前选择将器官全部捐献出去。

而女主仲村由理的故事更为惨痛，生前住在生活得很快乐的富裕家庭，有三个弟弟妹妹。一天下午，四名强盗趁双亲不在家时入室抢劫。她被强迫在家中找出值钱的东西，不然就每10分钟杀死她的一个弟弟妹妹，结果警察于30分钟后赶到——这时由理已经眼睁睁地看着弟妹三人依次被杀。 “そんな人生なんて、許せないじゃない”/“怎么能原谅这种人生”是她发出的怒吼

和音无类似于圣徒，由理从地狱归来的人设不太一样。雅美的生前的故事也很惨，但是她同样也没有放弃，生活在家暴与吵架中的贫苦家庭。被音乐所拯救，靠着一把在雨中的垃圾堆捡来的一把吉他在音乐的路上奔驰着，一心用音乐帮助更多的人。但是因为被一酒瓶子砸在脑袋上，脑出血导致脑梗塞，在失语症中度过残生。

雅美的故事可能会更让人在生活中找到一丝真切感，我们见到的很多乐队的主唱都有类似的成长环境。如果说音无和由理的故事离我们太远，那么雅美的故事可能会是我们所见证过的故事。而雅美在逆境中的坚持以及利用音乐给他人点亮的希望之火，也更容易让我们为之动容。

之前有人问过我“你真的觉得这个世界上有奥特曼存在吗”，我的回答是“是的，在我心里”

所以在这个版本中，我想用她所演唱的一首歌的歌词来让我们一起铭记住她。如果平行世界的雅美真的知道了这件事，我相信她也会很开心的

最后

用这首歌的另外一句歌词来作为本文的结尾吧

こんなにも汚れて丑い世界で, 出会えた奇迹にありがとう/向在如此肮脏丑陋的世界中, 相遇的奇迹致谢吧

Reference

[1]. https://github.com/apache/opendal/discussions/5303

[2]. https://www.bilibili.com/video/BV13x411a79f

[3]. https://www.youtube.com/watch?v=mlUCxND9EU8

好了，现在你的知识也是我的了.jpg

2024-12-06T18:00:00.000Z

最近给朋友介绍了一下我对于一些外部资料的吸收的经验。我想了想整理了下聊天记录，将我整个思路以博客的形式展现出来。希望能帮到看这篇博客的人。

正文

首先说明，我自己看过关于知识体系方法论的资料很少。本文描述的是我自己在这些年经过不断改良后觉得目前最适合我的一套方法，可能不适合所有人，仅供参考

我自己的宗旨是 “有些时候我不一定需要成为知识的生产者，而是成为知识的搬运者”

或者套用鸭子类型的一个描述就是“如果一个项目，你知道原理，理解细节，能完整的给别人分享其中的细节，那么这就是你做过的项目”

成为一个合格的知识搬运者，那么意味着你需要擅长或者说能较好的吸收一些外部资料。我自己将原则归纳为两点

摆正心态
知识迁移

这里我先要着重强调心态上的重要性，再开始去描述我们怎么样去做知识的迁移

我自己对于心态是这样的观点：很多人对于去内化别人的资料有一种潜在的耻辱性心态，大家在面对一些资料的时候，会下意识的有“这不是我做的”，“我好菜啊”，“好难懂”心态，而不是抱着“原来我可以这么做”，“原来我之前这么做是对的”，这个心态将决定了你知识吸收的效率。

在我们聊完心态的重要性后，我将以之前看到的一篇 Mooncake 分离式推理架构创新与实践的文章为例子，大致的描述我怎么样将一篇资料消化的

这篇文章比较清晰的介绍了 Mooncake 在一些场景下的面临的挑战和解决思路。我们现在来逐行拆分一些我消化过程中觉得关键的点

在继续之前，我将这个过程总结为

知识验证
平行迁移
知识增强
新领域启发

这四部曲，以及如果你在面对一些可能是你看来比较 naive 的资料，可能还会有一部分我称之为对抗性思路的过程，即你需要去思考，如果是你，你会怎么样做的比他好？

首先我们聊一下第一部分知识验证的过程

比如以上文提到的资料中这样一段资料

第一段

除了性能挑战，我们还需要在大规模推理时采用一些自动运维手段，以减少人力投入，专注于解决更重要的问题。为此，我们采取了以下措施:首先，我们实现了推理实例的快速切换和快速拉齐方法。由于显卡是容易损坏的硬件，我们有硬件巡检手段，能够在机器出现问题时快速隔离，并在一定时间内如果无法恢复则人工介入。其次，在深夜时段，推理压力不大时，我们会释放一部分空闲资源来执行一些长时间或离线的任务，这些任务对延迟不敏感，可以异步进行。或者将这些机器用于一些轻量级的训练任务，以避免资源闲置。

第二段

首先，针对 Prefill Cache Miss 的问题，关键在于机器 B 没有热请求的 KV Cache。我们的解决方案是采用 Prefil 到 Prefill 的 Cache Transfer。当机器 B 发现没有 KV Cache时，我们不选择重新计算，因为这会消耗大量时间，而是让机器 A 直接将 KV Cache 传输给机器 B。这样，机器 B 就可以打破恶性循环，减少 TTFT 压力，提高并行度。
其次，我们需要处理 Prefil 到 Decode 的传输，这使得我们的 RDMA 网络带宽使用非常频繁。因此，我们需要一个更优的 RDMA 传输方案。许多开源工具的实现可以达到 80GE的水平，但离理论上限还有一定距离。我们对 RDMA 传输进行了精细调整，使得传输速率可以达到 180GB 每秒，非常接近 200GB 的理论上限。

这两部分资料提到的有两个东西

自动化巡检
对于缓存系统的 Prefetch 预热

这一部分实际上是对于我已有知识的验证，我会去思考过去做过的自动化巡检系统中的一些细节（包括怎么样提升准确性，减少误报等关键点），以及验证我自己之前做过的一些缓存预热的手段。

当然实际上在看这一部分的时候还包含了一些知识的增强。比如在这个过程中我会去查询目前 RDMA 开源方案的一些瓶颈，同时去查阅一些调优的文章。这样确保即便我没做过 RDMA 相关的部分，我也能对这样一个知识领域有一些最基本的了解

OK，我们来看第二步，知识的平行迁移

我们总结了几个关键公式:
更低的推理成本 =更省的模型结构 + 更便宜的硬件
更便宜的 Long Context= 更快的 Attention 计算 + 更小的 KVCache
更便宜的 Generation =更大的 Batch Size+更 Decode 友好的并行方式
这里所说的更节省的模型结构，指的是在时间和显存上的优化。如果我们进一步拆分推理成本，会发现两个关键点:一是长上下文的 Prefil(预填充)，二是 Generation(生成)的成本。对于长上下文的预填充，我们知道 Attention(注意力机制)具有平方级的时间复杂度。随着上下文长度的增加，比如达到 64K或一兆，所需的时间也会呈平方级增长，这成为我们系统中非常关键的一部分。因此，我们需要对这种场景进行专门的优化。优化长上下文预填充后，我们发现从整体上看，生成的成本才是推理系统的主要成本。因为用户在对话过程中需要模型输出的字数越来越长，而生成是一个 Memory Bound 的过程。

这里是文章开头中介绍 Mooncake 这一套系统的背景。在我看来，这一段可能技术上可以吸收的点并不多。但是这一段包含了很不错的演讲分享技巧。

用简单清晰的公式去吸引观众的注意
用 “比如达到 64K或一兆，所需的时间也会呈平方级增长” 这样精炼而吸睛的描述去做一个关键点的突出

这一样一组技巧，我会直接吸收下来作为我自己后续演讲准备中的一些素材。我自己也会在脑海中构建一个场景，如果时间回到21年，我在阿里晋升答辩的时候，如果让我用现在的技巧去概括我过去一年在网关中做的一些关键工作，我会怎么样去概述。

OK，现在我们来看第三步，知识的增强

我们的优化工作带来了显著的收益，这些收益体现在几个关键指标上。首先，我们实现了TTFT 的 10 倍提升，这主要得益于 Cache Miss 的显著降低，目前我们能做到小于 10%的 Cache Miss 水平，大量的计算可以被重复利用。
其次，我们在 TBT 上获得了大约5 倍的提升。这主要归功于 decode 节点能够将 batchsize 增大两倍以上。如果我们采用 Prefi 和 Decode 混合部署的方式，Decode 节点的TVT(Time to Value)压力会比较大，因为需要在 Decode 之间插入 Prefil 的计算。但如果我们将 Prefi 和 Decode 分离， Decode 节点就不需要为 prefil 预留任何显存，从而可以增大 batch size。尽管如此，batch size 的增加也会导致 TBT 相应下降，因此在SLO 的限制下，我们最终只能达到两倍多的水平。
在总体吞吐量上 RPM 上，我们平均获得了 1.7 倍的提升，对于一些较简单的业务，提升甚至超过了 5 倍。这些成绩的取得，是因为我们挖掘了当前许多框架可能没有充分利用的硬件资源，例如基础架构的 RDMA 通信带宽、内存的容量和带宽，以及 OSS 或 SSD 等多级缓存工具。

我是一个做 infra 出身的 SRE，那么对于可观测性的渴望我是吸纳在骨子里的，在看到这一段 Mooncake 关键结果的描述的时候，我会去思考这样一些问题

他们的监控规模有多大？时序数据规模有多大？采用的什么方案？Prometheus 等开源结构能否满足这一套需求？
他们这种对于 cache 的访问场景是不是延时敏感的？如果是的话，要去监控 cache miss 等指标的 overhead 会有多大？

我会在我脑海中根据我已经有的信息，对我自己给自己提出的问题进行一次或者多次推演（通常我工作累了，会做一些类似的推演或者思考来换个脑子休息一下）。而其有机会的时候，我也会去请教作者我思考过程中的一些问题（比如之前看一些论文或者内核 Patch 我有些思考都会直接去邮件沟通作者）。而不断的推演以及和同行不断的交流，实际上是对于知识的一个正向的反馈过程。能够帮助你对你自己做过的东西理解的更深。

OK，现在我们来聊新领域的启发

以前面的例子为例，整篇文章中反复提到了他们利用 RDMA 所做的一些事情。而这一块其实是我知识的盲区所在。所以我会去做以下这一样一些探索

明确 RDMA 目前的发展的一些状况
找一到两篇关于 RDMA 的论文进行粗读
找一到两篇公开的分享来了解 RDMA 在业界的一些落地概况

我自己日常的场景离 RDMA 可能有不少的 GAP。但是这样一些新领域的探索不仅能让我对 RDMA 有一些最基本的认知。也能让我去对行业头部的发展有一些理性的认识。

在我看来，知识消化其实就是不断的从你觉得有用的资料中重复这四部曲的过程。你需要基于你已有的知识框架去做一些推演，做一些思考。最终，别人的知识也可以成为你的知识.jpg

“我们不是知识的生产者，我们是知识的搬运工.jpg”

总结

差不多就这样吧，希望这篇文章能帮到大家

如何使用 WASMTIME 来运行 CPython for WASI，然后利用 Python 实现的 HostFunction 来扩展它？

2024-10-02T13:00:00.000Z

国庆节搞了一个活，利用 wasmtime 来执行编译成 WASM/WASI 字节码的 CPython 虚拟机，并在宿主机一侧利用 Python 实现的 Host Function 来扩展它。

再次声明一下，这个只是我个人想搞的活，没有再任何生产环境中得到验证，just for fun（XDDD

正文

首先我们简单介绍一下 WASM/WASI，这里我直接引用一下 AI 生成的 brief summary

WebAssembly (WASM) 是一种低级编程语言,可在现代网页浏览器中运行。它提供接近原生的性能。
WebAssembly System Interface (WASI) 是 WASM 的一个标准扩展,允许 WASM 程序在浏览器外运行,访问系统资源。
这两项技术旨在提高 Web 应用性能,并使 WASM 在更多环境中可用。

而 WASM/WASI 技术路线核心的优势在于

跨平台的兼容性
多语言通过静态编译的支持
Native Sandbox 带来的安全性

所以 WASM/WASI 不仅在浏览器得到了广泛的应用，现在其应用也逐渐扩展到了服务端。Serverless Compute，Database UDF， Gateway Plugin 等场景都在逐渐的铺开。

在最近在梳理 CPython 代码的时候，我突然有了一个想法，就是如果我用 WASM/WASI Runtime 来运行 CPython，然后在宿主机一侧利用 Python 实现的 Host Function 来扩展它，这样似乎能对一些比如允许用户上传自定义代码的数据 PaaS 这样的场景有所帮助。当然更主要的原因是这个 idea 貌似很好玩。

在我们继续往下走之前，我们感谢一个人，Brett Cannon，他几乎以一己之力，完成了 CPython WASM/WASI 的支持。快跟我说谢谢 Brett Cannon ！

CPython 整体的 WASM/WASI 演进路线如下

最早于21年11月，通过 emscripten 支持了 WASM，参见 BPO-40280¹
在2023年6月成为官方支持的 Tier3 平台（或者更早?）
在2024年3月，成为官方支持的 Tier2 平台，参见 GH-116314²
从 Python 3.13 开始，传统的 emscripten 方式的 WASM/WASI 支持将被放弃

OK，那么我们先来将 CPython 编译为 WASM/WASI 字节码，这里需要提前 setup 你的环境，确保安装 WASI-SDK。这里我为了省事，直接使用官方提供的 devcontainer 来进行所有的操作

我们使用 vscode setup 好 devcontainer 后，我们执行 python3 Tools/wasm/wasi.py build -- --config-cache --with-pydebug 便可以编译了，这里为了省事，我将原本 wasi.py 设定的先提前预编译一遍 CPython 的部分给去除了


def build_all(context):
    """Build everything."""
    steps = [
            #configure_build_python,
            #make_build_python,
            configure_wasi_python,
            make_wasi_python
        ]

在编译完成后，我们使用 cross-build/wasm32-wasi/python.sh 就可以运行我们的 CPython 了，这里实际上是 wrap 了一下 WASMTIME 的命令

1
2

#!/bin/sh
exec /usr/local/bin/wasmtime run --wasm max-wasm-stack=16777216 --wasi preview2 --dir /workspaces/cpython-wasi::/ --env PYTHONPATH=/cross-build/wasm32-wasi/build/lib.wasi-wasm32-3.14-pydebug /workspaces/cpython-wasi/cross-build/wasm32-wasi/python.wasm "$@"

这里我们可以看到，官方的推荐的 WASM/WASI Runtime 是 wasmtime，那么我们用 wasmtime 进行接下来的工作

由于我们后续想用 Host Function 来扩展这一套流程，所以我们将 bash 的部分重写一下，最开始我使用的是 wasmtime 的 Python binding，大致的代码如下

from wasmtime import Linker, Engine, Store, WasiConfig, Module, FuncType, ValType, _bindings, Config
import sys

def test_wasi():
    linker = Linker(Engine())
    linker.define_wasi()
    with open("/workspaces/cpython-wasi/cross-build/wasm32-wasi/python.wasm", "rb") as file:
        module = Module(linker.engine, file.read())
    def foor_bar(a, b):
        return a + b
    linker.define_func("demo", "demo", FuncType([ValType.i32(),ValType.i32()],[ValType.i32()]), foor_bar)
    store = Store(linker.engine)
    config = Config()
    _bindings.wasmtime_config_max_wasm_stack_set(config.ptr(), 16777216)
    wasi_config = WasiConfig()
    # wasi_config.stdin_file = sys.stdin.fileno()
    # wasi_config.stdout_file = sys.stdout.fileno()
    # wasi_config.stderr_file = sys.stderr.fileno()
    wasi_config.env = [["PYTHONPATH", "/cross-build/wasm32-wasi/build/lib.wasi-wasm32-3.14-pydebug"]]
    wasi_config.inherit_stdout()
    wasi_config.inherit_stderr()
    wasi_config.inherit_stdin()
    wasi_config.preopen_dir("/workspaces/cpython-wasi","/")
    store.set_wasi(wasi_config)

    instance=linker.instantiate(store, module)
    instance.exports(store)["_start"](store)

test_wasi()

由于 wasmtime 的 Python binding 是直接走 ctype 的一套封装，很多 config 选项没有在对外暴露的 API 里（比如代码里使用的 wasmtime_config_max_wasm_stack_set 来处理 WASM 的 stack），导致很多操作需要使用没暴露的私有 API，太过于 tricky，所以我选择重新用 Rust 来实现这一套操作

use wasmtime::*;
use wasmtime_wasi::preview1::{self};
use wasmtime_wasi::WasiCtxBuilder;
fn main() {
    let mut config = Config::new();
    config.max_wasm_stack(16777216);
    match Engine::new(&config) {
        Ok(engine) => {
            let mut linker = Linker::new(&engine);
            preview1::add_to_linker_sync(&mut linker, |t| t).unwrap();
            linker.allow_unknown_exports(true);
            let mut builder = WasiCtxBuilder::new();
            builder.inherit_stdio();
            builder.env(
                "PYTHONPATH",
                "/cross-build/wasm32-wasi/build/lib.wasi-wasm32-3.14-pydebug",
            );
            builder
                .preopened_dir(
                    "/workspaces/cpython-wasi",
                    "/",
                    wasmtime_wasi::DirPerms::all(),
                    wasmtime_wasi::FilePerms::all(),
                )
                .unwrap();
            builder.args(&["--", "--version"]);
            let wasi_ctx = builder.build_p1();
            let mut store = Store::new(&engine, wasi_ctx);
            let module = Module::from_file(
                &engine,
                "/workspaces/cpython-wasi/cross-build/wasm32-wasi/python.wasm",
            )
            .unwrap();
            let instance = linker.instantiate(&mut store, &module).unwrap();
            let run = instance
                .get_typed_func::<(), ()>(&mut store, "_start")
                .unwrap();
            run.call(&mut store, ()).unwrap();
            return;
        }
        Err(e) => {
            println!("Error creating engine: {:?}", e);
            return;
        }
    }
}

然后我们执行代码，成功！

[root@267e91be24fd wasmtime-demo]# cargo run --release
   Compiling wasmtime-demo v0.1.0 (/workspaces/wasmtime-demo)
    Finished `release` profile [optimized] target(s) in 1.81s
     Running `target/release/wasmtime-demo`
Python 3.14.0a0

现在我们来扩展我们的 CPython。首先声明，由于 dlopen 在 WASM/WASI for CPython 中没有得到支持，所以我们需要更改 Python 的本体部分

首先，我们在 Python 的 Modules 目录下面新增一个文件，命名为 demo.c，内容如下

#include 

extern int demo(int a, int b) {
return a + b;
}
static PyObject *
foo_bar(PyObject *self, PyObject *args)
{
Py_INCREF(PyExc_TypeError);
return PyLong_FromLong((long) demo(1, 2));
}

static PyMethodDef foomethods[] = {
{"bar", foo_bar, METH_VARARGS, ""},
{NULL, NULL, 0, NULL},
};

static PyModuleDef foomodule = {
PyModuleDef_HEAD_INIT,
.m_name = "demo",
.m_doc = "foo test module",
.m_size = -1,
.m_methods = foomethods,
};

PyMODINIT_FUNC
PyInit_demo(void)
{
return PyModule_Create(&foomodule);
}

然后我们在 Modules/Setup.bootstrap.in 中加入一行

1	demo demo.c

接着重新执行命令 python3 Tools/wasm/wasi.py build -- --config-cache --with-pydebug，生成新的 WASM/WASI 字节码。接着我们将前面的 Rust 代码中，args 的部分改为 ["--", "-c", "import demo; print(demo.bar())"]，然后重新执行代码，成功！

[root@267e91be24fd wasmtime-demo]# cargo run --release
   Compiling wasmtime-demo v0.1.0 (/workspaces/wasmtime-demo)
    Finished `release` profile [optimized] target(s) in 1.73s
     Running `target/release/wasmtime-demo`
3

现在，我们有了一个扩展模块，demo.c，但是问题是，我们现在的 demo.c 中核心的 demo 函数是 hardcode 在代码中。那么我们需要处理一下这里

通常来说，在常规的经验下，我们可以将函数的实现和定义分离开，这样方便动态链接。WASM/WASI 的也是类似，不过需要额外的处理

extern int demo(int a, int b) __attribute__((
    __import_module__("demo"),
    __import_name__("demo"),
));

这里我们是通过扩展的宏定义，在编译期的时候告诉编译器，demo 函数是从 demo 模块中导入的。这样我们就可以在后续的 Host Function 中，根据约定进行扩展了

然后我们需要修改一下 CPython 的编译脚本，给编译参数添加上 -Wextra -Wl,--allow-undefined

接着重新执行 python3 Tools/wasm/wasi.py build -- --config-cache --with-pydebug，生成新的 WASM/WASI 字节码。这个时候我们可以先执行 python.sh 一下，我们会得到报错

Error: failed to run main module `/workspaces/cpython-wasi/cross-build/wasm32-wasi/python.wasm`

Caused by:
    0: failed to instantiate "/workspaces/cpython-wasi/cross-build/wasm32-wasi/python.wasm"
    1: unknown import: `demo::demo` has not been defined

符合预期。

那么我们现在来重新处理下我们的 Rust 代码

use wasmtime::*;
use wasmtime_wasi::preview1::{self};
use wasmtime_wasi::WasiCtxBuilder;
fn main() {
    let mut config = Config::new();
    config.max_wasm_stack(16777216);
    match Engine::new(&config) {
        Ok(engine) => {
            let mut linker = Linker::new(&engine);
            preview1::add_to_linker_sync(&mut linker, |t| t).unwrap();
            linker
                .func_wrap("demo", "demo", |a: i32, b: i32| {
                    (a+b)*10
                })
                .unwrap();
            linker.allow_unknown_exports(true);
            let mut builder = WasiCtxBuilder::new();
            builder.inherit_stdio();
            builder.env(
                "PYTHONPATH",
                "/cross-build/wasm32-wasi/build/lib.wasi-wasm32-3.14-pydebug",
            );
            builder
                .preopened_dir(
                    "/workspaces/cpython-wasi",
                    "/",
                    wasmtime_wasi::DirPerms::all(),
                    wasmtime_wasi::FilePerms::all(),
                )
                .unwrap();
            builder.args(&["--", "-c", "import demo; print(demo.bar())"]);
            let wasi_ctx = builder.build_p1();
            let mut store = Store::new(&engine, wasi_ctx);
            let module = Module::from_file(
                &engine,
                "/workspaces/cpython-wasi/cross-build/wasm32-wasi/python.wasm",
            )
            .unwrap();
            let instance = linker.instantiate(&mut store, &module).unwrap();
            let run = instance
                .get_typed_func::<(), ()>(&mut store, "_start")
                .unwrap();
            run.call(&mut store, ()).unwrap();
            return;
        }
        Err(e) => {
            println!("Error creating engine: {:?}", e);
            return;
        }
    }
}

执行一下，得到结果

[root@267e91be24fd wasmtime-demo]# cargo run --release
   Compiling wasmtime-demo v0.1.0 (/workspaces/wasmtime-demo)
    Finished `release` profile [optimized] target(s) in 1.79s
     Running `target/release/wasmtime-demo`
30

符合预期。

好了，现在我们支持了 Host Fucntion，我们可以在遵守函数签名的情况下，任意修改我们的逻辑。但是你还记得本文的标题吗？我们想执行 Python 实现的 Host Function。emmmm 虽然有一点绕，但也不是不可以，我们直接祭出 PyO3，更改 Rust 代码如下

use pyo3::prelude::*;
use pyo3::types::PyTuple;
use wasmtime::*;
use wasmtime_wasi::preview1::{self};
use wasmtime_wasi::WasiCtxBuilder;
fn main() {
    let mut config = Config::new();
    config.max_wasm_stack(16777216);
    match Engine::new(&config) {
        Ok(engine) => {
            let mut linker = Linker::new(&engine);
            preview1::add_to_linker_sync(&mut linker, |t| t).unwrap();
            linker
                .func_wrap("demo", "demo", |a: i32, b: i32| {
                    Python::with_gil(|py| {
                        let fun: Py = PyModule::from_code_bound(
                            py,
                            "def example(*args, **kwargs):
                                return (args[0] + args[1])*11",
                            "",
                            "",
                        )
                        .unwrap()
                        .getattr("example")
                        .unwrap()
                        .into();
                        let args = PyTuple::new_bound(py, &[a, b]);
                        // cast following to int

                        fun.call1(py, args).unwrap().extract::<i32>(py).unwrap()
                    })
                })
                .unwrap();
            linker.allow_unknown_exports(true);
            let mut builder = WasiCtxBuilder::new();
            builder.inherit_stdio();
            builder.env(
                "PYTHONPATH",
                "/cross-build/wasm32-wasi/build/lib.wasi-wasm32-3.14-pydebug",
            );
            builder
                .preopened_dir(
                    "/workspaces/cpython-wasi",
                    "/",
                    wasmtime_wasi::DirPerms::all(),
                    wasmtime_wasi::FilePerms::all(),
                )
                .unwrap();
            builder.args(&["--", "-c", "import demo; print(demo.bar())"]);
            let wasi_ctx = builder.build_p1();
            let mut store = Store::new(&engine, wasi_ctx);
            let module = Module::from_file(
                &engine,
                "/workspaces/cpython-wasi/cross-build/wasm32-wasi/python.wasm",
            )
            .unwrap();
            let instance = linker.instantiate(&mut store, &module).unwrap();
            let run = instance
                .get_typed_func::<(), ()>(&mut store, "_start")
                .unwrap();
            run.call(&mut store, ()).unwrap();
            return;
        }
        Err(e) => {
            println!("Error creating engine: {:?}", e);
            return;
        }
    }
}

然后执行一下，得到结果

[root@267e91be24fd wasmtime-demo]# cargo run --release
   Compiling wasmtime-demo v0.1.0 (/workspaces/wasmtime-demo)
    Finished `release` profile [optimized] target(s) in 1.75s
     Running `target/release/wasmtime-demo`
33

OK，我们成功了！

总结

本文实际上是一个技术路线的 PoC，验证了特定情况下，将 Python 和 WASI 结合的可能性，但是目前也暴露出一些问题

dlopen 支持的缺乏导致需要魔改 CPython runtime 本身的代码，不过根据 Brett Cannon 博客中提供的信息，有人 hack 了这一块代码提供了支持。感觉后续可以 follow up 一下
wasmtime Python binding 实在是太难用了，其实可以考虑直接基于 PyO3 进行一次封装
利用 Rust 来处理 wasmtime ，PyO3 调用 Python 代码目前存在的问题是 Python VM 对象没法跨线程共享，可能需要自己基于 Rust 封装一套类似 Golang 这样的 channel 的思路来复用虚拟机和传递数据

不过总体来说，这个 PoC 还是很有意思的，希朋友们也能玩的开心

参考

[1]. https://bugs.python.org/issue40280

[2]. https://github.com/python/cpython/issues/116314

How to Run CPython for WASI Using WASMTIME and Extend It with Python-Implemented Host Functions?

2024-10-02T13:00:00.000Z

During the National Day holiday, I worked on a project to use wasmtime to execute CPython virtual machine compiled into WASM/WASI bytecode, and extend it with Host Functions implemented in Python on the host side.

I’d like to clarify again that this is just a personal project I wanted to work on, without any validation in production environments, just for fun (XDDD

Main Content

First, let’s briefly introduce WASM/WASI. Here, I’ll directly quote an AI-generated brief summary:

WebAssembly (WASM) is a low-level programming language that can run in modern web browsers. It provides near-native performance.
WebAssembly System Interface (WASI) is a standard extension of WASM that allows WASM programs to run outside the browser and access system resources.
These two technologies aim to improve Web application performance and make WASM available in more environments.

The core advantages of the WASM/WASI technology route are:

Cross-platform compatibility
Multi-language support through static compilation
Security brought by Native Sandbox

Therefore, WASM/WASI is not only widely used in browsers but is also gradually expanding to the server-side. Scenarios such as Serverless Compute, Database UDF, and Gateway Plugin are gradually being rolled out.

While reviewing CPython code recently, I suddenly had an idea: what if I use WASM/WASI Runtime to run CPython, and then extend it with Host Functions implemented in Python on the host side? This seems to be helpful for scenarios like data PaaS that allows users to upload custom code. Of course, the main reason is that this idea seems quite interesting.

Before we continue, let’s thank one person, Brett Cannon, who almost single-handedly completed the support for CPython WASM/WASI. Say thank you to Brett Cannon with me!

The overall WASM/WASI evolution route of CPython is as follows:

As early as November 2021, WASM was supported through emscripten, see BPO-40280¹
It became an officially supported Tier3 platform in June 2023 (or earlier?)
It became an officially supported Tier2 platform in March 2024, see GH-116314²
Starting from Python 3.13, the traditional emscripten method of WASM/WASI support will be abandoned

OK, let’s start by compiling CPython into WASM/WASI bytecode. You need to set up your environment in advance and make sure WASI-SDK is installed. To save time, I directly use the official devcontainer for all operations.

After setting up the devcontainer with vscode, we can compile by executing python3 Tools/wasm/wasi.py build -- --config-cache --with-pydebug. To save time, I removed the part in wasi.py that pre-compiles CPython:

def build_all(context):
    """Build everything."""
    steps = [
            #configure_build_python,
            #make_build_python,
            configure_wasi_python,
            make_wasi_python
        ]

After compilation, we can run our CPython using cross-build/wasm32-wasi/python.sh. This is actually a wrapper for the WASMTIME command:

1
2

#!/bin/sh
exec /usr/local/bin/wasmtime run --wasm max-wasm-stack=16777216 --wasi preview2 --dir /workspaces/cpython-wasi::/ --env PYTHONPATH=/cross-build/wasm32-wasi/build/lib.wasi-wasm32-3.14-pydebug /workspaces/cpython-wasi/cross-build/wasm32-wasi/python.wasm "$@"

We can see that the officially recommended WASM/WASI Runtime is wasmtime, so we’ll use wasmtime for our next steps.

Since we want to use Host Functions to extend this process later, we’ll rewrite the bash part. Initially, I used wasmtime’s Python binding, and the code looked roughly like this:

from wasmtime import Linker, Engine, Store, WasiConfig, Module, FuncType, ValType, _bindings, Config
import sys

def test_wasi():
    linker = Linker(Engine())
    linker.define_wasi()
    with open("/workspaces/cpython-wasi/cross-build/wasm32-wasi/python.wasm", "rb") as file:
        module = Module(linker.engine, file.read())
    def foor_bar(a, b):
        return a + b
    linker.define_func("demo", "demo", FuncType([ValType.i32(),ValType.i32()],[ValType.i32()]), foor_bar)
    store = Store(linker.engine)
    config = Config()
    _bindings.wasmtime_config_max_wasm_stack_set(config.ptr(), 16777216)
    wasi_config = WasiConfig()
    # wasi_config.stdin_file = sys.stdin.fileno()
    # wasi_config.stdout_file = sys.stdout.fileno()
    # wasi_config.stderr_file = sys.stderr.fileno()
    wasi_config.env = [["PYTHONPATH", "/cross-build/wasm32-wasi/build/lib.wasi-wasm32-3.14-pydebug"]]
    wasi_config.inherit_stdout()
    wasi_config.inherit_stderr()
    wasi_config.inherit_stdin()
    wasi_config.preopen_dir("/workspaces/cpython-wasi","/")
    store.set_wasi(wasi_config)

    instance=linker.instantiate(store, module)
    instance.exports(store)["_start"](store)

test_wasi()

Since wasmtime’s Python binding is a direct ctype wrapper, many config options are not exposed in the public API (such as using wasmtime_config_max_wasm_stack_set to handle WASM’s stack), which leads to many operations requiring the use of unexposed private APIs. This is too tricky, so I chose to reimplement this set of operations using Rust:

use wasmtime::*;
use wasmtime_wasi::preview1::{self};
use wasmtime_wasi::WasiCtxBuilder;
fn main() {
    let mut config = Config::new();
    config.max_wasm_stack(16777216);
    match Engine::new(&config) {
        Ok(engine) => {
            let mut linker = Linker::new(&engine);
            preview1::add_to_linker_sync(&mut linker, |t| t).unwrap();
            linker.allow_unknown_exports(true);
            let mut builder = WasiCtxBuilder::new();
            builder.inherit_stdio();
            builder.env(
                "PYTHONPATH",
                "/cross-build/wasm32-wasi/build/lib.wasi-wasm32-3.14-pydebug",
            );
            builder
                .preopened_dir(
                    "/workspaces/cpython-wasi",
                    "/",
                    wasmtime_wasi::DirPerms::all(),
                    wasmtime_wasi::FilePerms::all(),
                )
                .unwrap();
            builder.args(&["--", "--version"]);
            let wasi_ctx = builder.build_p1();
            let mut store = Store::new(&engine, wasi_ctx);
            let module = Module::from_file(
                &engine,
                "/workspaces/cpython-wasi/cross-build/wasm32-wasi/python.wasm",
            )
            .unwrap();
            let instance = linker.instantiate(&mut store, &module).unwrap();
            let run = instance
                .get_typed_func::<(), ()>(&mut store, "_start")
                .unwrap();
            run.call(&mut store, ()).unwrap();
            return;
        }
        Err(e) => {
            println!("Error creating engine: {:?}", e);
            return;
        }
    }
}

Then we execute the code, success!

[root@267e91be24fd wasmtime-demo]# cargo run --release
   Compiling wasmtime-demo v0.1.0 (/workspaces/wasmtime-demo)
    Finished `release` profile [optimized] target(s) in 1.81s
     Running `target/release/wasmtime-demo`
Python 3.14.0a0

Now let’s extend our CPython. First, note that since dlopen is not supported in WASM/WASI for CPython, we need to modify the Python core itself.

First, we add a new file in Python’s Modules directory, named demo.c, with the following content:

#include 

extern int demo(int a, int b) {
return a + b;
}
static PyObject *
foo_bar(PyObject *self, PyObject *args)
{
Py_INCREF(PyExc_TypeError);
return PyLong_FromLong((long) demo(1, 2));
}

static PyMethodDef foomethods[] = {
{"bar", foo_bar, METH_VARARGS, ""},
{NULL, NULL, 0, NULL},
};

static PyModuleDef foomodule = {
PyModuleDef_HEAD_INIT,
.m_name = "demo",
.m_doc = "foo test module",
.m_size = -1,
.m_methods = foomethods,
};

PyMODINIT_FUNC
PyInit_demo(void)
{
return PyModule_Create(&foomodule);
}

Then we add a line in Modules/Setup.bootstrap.in:

1	demo demo.c

Next, we re-execute the command python3 Tools/wasm/wasi.py build -- --config-cache --with-pydebug to generate new WASM/WASI bytecode. Then we change the args part in our previous Rust code to ["--", "-c", "import demo; print(demo.bar())"], and re-execute the code, success!

[root@267e91be24fd wasmtime-demo]# cargo run --release
   Compiling wasmtime-demo v0.1.0 (/workspaces/wasmtime-demo)
    Finished `release` profile [optimized] target(s) in 1.73s
     Running `target/release/wasmtime-demo`
3

Now, we have an extension module, demo.c, but the problem is that the core demo function in our current demo.c is hardcoded. So we need to handle this.

Typically, in regular practice, we can separate the implementation and definition of functions to facilitate dynamic linking. WASM/WASI is similar, but requires additional handling:

extern int demo(int a, int b) __attribute__((
    __import_module__("demo"),
    __import_name__("demo"),
));

Here, we use extended macro definitions to tell the compiler at compile time that the demo function is imported from the demo module. This way, we can extend it in subsequent Host Functions according to the convention.

Then we need to modify CPython’s compilation script, adding -Wextra -Wl,--allow-undefined to the compilation parameters.

Next, re-execute python3 Tools/wasm/wasi.py build -- --config-cache --with-pydebug to generate new WASM/WASI bytecode. At this point, we can first execute python.sh, and we’ll get an error:

Error: failed to run main module `/workspaces/cpython-wasi/cross-build/wasm32-wasi/python.wasm`

Caused by:
    0: failed to instantiate "/workspaces/cpython-wasi/cross-build/wasm32-wasi/python.wasm"
    1: unknown import: `demo::demo` has not been defined

This is as expected.

So now let’s reprocess our Rust code:

use wasmtime::*;
use wasmtime_wasi::preview1::{self};
use wasmtime_wasi::WasiCtxBuilder;
fn main() {
    let mut config = Config::new();
    config.max_wasm_stack(16777216);
    match Engine::new(&config) {
        Ok(engine) => {
            let mut linker = Linker::new(&engine);
            preview1::add_to_linker_sync(&mut linker, |t| t).unwrap();
            linker
                .func_wrap("demo", "demo", |a: i32, b: i32| {
                    (a+b)*10
                })
                .unwrap();
            linker.allow_unknown_exports(true);
            let mut builder = WasiCtxBuilder::new();
            builder.inherit_stdio();
            builder.env(
                "PYTHONPATH",
                "/cross-build/wasm32-wasi/build/lib.wasi-wasm32-3.14-pydebug",
            );
            builder
                .preopened_dir(
                    "/workspaces/cpython-wasi",
                    "/",
                    wasmtime_wasi::DirPerms::all(),
                    wasmtime_wasi::FilePerms::all(),
                )
                .unwrap();
            builder.args(&["--", "-c", "import demo; print(demo.bar())"]);
            let wasi_ctx = builder.build_p1();
            let mut store = Store::new(&engine, wasi_ctx);
            let module = Module::from_file(
                &engine,
                "/workspaces/cpython-wasi/cross-build/wasm32-wasi/python.wasm",
            )
            .unwrap();
            let instance = linker.instantiate(&mut store, &module).unwrap();
            let run = instance
                .get_typed_func::<(), ()>(&mut store, "_start")
                .unwrap();
            run.call(&mut store, ()).unwrap();
            return;
        }
        Err(e) => {
            println!("Error creating engine: {:?}", e);
            return;
        }
    }
}

Execute it, and we get the result:

[root@267e91be24fd wasmtime-demo]# cargo run --release
   Compiling wasmtime-demo v0.1.0 (/workspaces/wasmtime-demo)
    Finished `release` profile [optimized] target(s) in 1.79s
     Running `target/release/wasmtime-demo`
30

As expected.

Alright, now we support Host Functions, and we can modify our logic arbitrarily while adhering to the function signature. But do you remember the title of this article? We want to execute Python-implemented Host Functions. Hmm, although it’s a bit roundabout, it’s not impossible. Let’s directly bring out PyO3 and modify our Rust code as follows:

use pyo3::prelude::*;
use pyo3::types::PyTuple;
use wasmtime::*;
use wasmtime_wasi::preview1::{self};
use wasmtime_wasi::WasiCtxBuilder;
fn main() {
    let mut config = Config::new();
    config.max_wasm_stack(16777216);
    match Engine::new(&config) {
        Ok(engine) => {
            let mut linker = Linker::new(&engine);
            preview1::add_to_linker_sync(&mut linker, |t| t).unwrap();
            linker
                .func_wrap("demo", "demo", |a: i32, b: i32| {
                    Python::with_gil(|py| {
                        let fun: Py = PyModule::from_code_bound(
                            py,
                            "def example(*args, **kwargs):
                                return (args[0] + args[1])*11",
                            "",
                            "",
                        )
                        .unwrap()
                        .getattr("example")
                        .unwrap()
                        .into();
                        let args = PyTuple::new_bound(py, &[a, b]);
                        // cast following to int

                        fun.call1(py, args).unwrap().extract::<i32>(py).unwrap()
                    })
                })
                .unwrap();
            linker.allow_unknown_exports(true);
            let mut builder = WasiCtxBuilder::new();
            builder.inherit_stdio();
            builder.env(
                "PYTHONPATH",
                "/cross-build/wasm32-wasi/build/lib.wasi-wasm32-3.14-pydebug",
            );
            builder
                .preopened_dir(
                    "/workspaces/cpython-wasi",
                    "/",
                    wasmtime_wasi::DirPerms::all(),
                    wasmtime_wasi::FilePerms::all(),
                )
                .unwrap();
            builder.args(&["--", "-c", "import demo; print(demo.bar())"]);
            let wasi_ctx = builder.build_p1();
            let mut store = Store::new(&engine, wasi_ctx);
            let module = Module::from_file(
                &engine,
                "/workspaces/cpython-wasi/cross-build/wasm32-wasi/python.wasm",
            )
            .unwrap();
            let instance = linker.instantiate(&mut store, &module).unwrap();
            let run = instance
                .get_typed_func::<(), ()>(&mut store, "_start")
                .unwrap();
            run.call(&mut store, ()).unwrap();
            return;
        }
        Err(e) => {
            println!("Error creating engine: {:?}", e);
            return;
        }
    }
}

Then execute it, and we get the result:

[root@267e91be24fd wasmtime-demo]# cargo run --release
   Compiling wasmtime-demo v0.1.0 (/workspaces/wasmtime-demo)
    Finished `release` profile [optimized] target(s) in 1.75s
     Running `target/release/wasmtime-demo`
33

OK, we succeeded!

Summary

This article is actually a Proof of Concept (PoC) for a technical route, verifying the possibility of combining Python and WASI in specific situations. However, it also exposes some problems:

The lack of dlopen support requires modifying the CPython runtime code itself. However, according to information provided in Brett Cannon’s blog, someone has hacked this part of the code to provide support. It feels like we can follow up on this later.
The wasmtime Python binding is really difficult to use. We could consider wrapping it once based on PyO3.
Using Rust to handle wasmtime and PyO3 to call Python code currently has the problem that Python VM objects cannot be shared across threads. We might need to encapsulate a set of channels similar to Golang based on Rust to reuse the virtual machine and pass data.

However, overall, this PoC is still very interesting. I hope friends can also have fun playing with it.

References

[1]. https://bugs.python.org/issue40280

[2]. https://github.com/python/cpython/issues/116314

Debug 日志：eCapture GH-604

2024-09-18T14:00:00.000Z

Debug 日志系列第二篇，eCapture 的 GH-604，一个和 Go， Glibc，静态编译相关的问题

太长不看版：在 eCapture 中，由于在静态链接时 glibc 版本的差异，导致在 Ubuntu 下编译的二进制会在特定发行版上 Segment fault

开篇

首先介绍下 eCapture，这个项目是基于 eBPF 做的一套安全工具，核心的能力是可以提供在旁路对于 TLS 流量解密的能力

在8月25日的时候，社区反馈了一个 bug，编号 GH-604，其核心行为如下

下载在 GitHub Release 中发布的二进制，在 Arch Linux 下会 Segment Fault，报错大致如下

2024-09-18T21:10:47+08:00 INF BTF bytecode mode: CORE. btfMode=0
2024-09-18T21:10:47+08:00 INF module initialization. isReload=false moduleName=EBPFProbeOPENSSL
2024-09-18T21:10:47+08:00 INF Module.Run()
SIGSEGV: segmentation violation
PC=0x7f29ee844696 m=5 sigcode=1 addr=0x1e83c0
signal arrived during cgo execution

goroutine 19 gp=0xc0005b81c0 m=5 mp=0xc000100008 [syscall]:
runtime.cgocall(0x10990e0, 0xc0000bca90)
        /root/.go/src/runtime/cgocall.go:167 +0x4b fp=0xc0000bca58 sp=0xc0000bca20 pc=0x4739ab
net._C2func_getaddrinfo(0xc00058e3c0, 0x0, 0xc0005886f0, 0xc00058a0a0)
        _cgo_gotypes.go:108 +0x55 fp=0xc0000bca90 sp=0xc0000bca58 pc=0x84a7f5
net._C_getaddrinfo.func1(0xc00058e3c0, 0x0, 0xc0005886f0, 0xc00058a0a0)
        /root/.go/src/net/cgo_unix_cgo.go:78 +0xeb fp=0xc0000bcb48 sp=0xc0000bca90 pc=0x84af4b
net._C_getaddrinfo(0xc00058e3c0, 0x0, 0xc0005886f0, 0xc00058a0a0)
        /root/.go/src/net/cgo_unix_cgo.go:78 +0x6c fp=0xc0000bcbd0 sp=0xc0000bcb48 pc=0x84adac
net.cgoLookupHostIP({0x1351556, 0x3}, {0x13727d2, 0x9})
        /root/.go/src/net/cgo_unix.go:181 +0x3f9 fp=0xc0000bce38 sp=0xc0000bcbd0 pc=0x7f65b9
net.cgoLookupIP.func1()
        /root/.go/src/net/cgo_unix.go:226 +0x85 fp=0xc0000bcf00 sp=0xc0000bce38 pc=0x7f7145
net.doBlockingWithCtx[...].func1()
        /root/.go/src/net/cgo_unix.go:70 +0x8f fp=0xc0000bcfe0 sp=0xc0000bcf00 pc=0x84de4f
runtime.goexit({})
        /root/.go/src/runtime/asm_amd64.s:1700 +0x1 fp=0xc0000bcfe8 sp=0xc0000bcfe0 pc=0x482301
created by net.doBlockingWithCtx[...] in goroutine 18
        /root/.go/src/net/cgo_unix.go:67 +0x3c5

我在 Garuda 下能复现同样的问题，由于作者没有 Arch Linux 的环境，那么就由我来接手了

最开始的排查方向是先利用容器环境进行启动，发现执行正常。那么目前可以初步判断是依赖的二进制版本不同导致的问题，但是 eCapture 依赖的二进制有点多，那么怎么办呢？

这个时候 issue 的提出者提供了一个关键点，这个问题是 v0.8.1 之后出现的，那么很好办，祭出我们的 git bisect 大法

最后确定是 938fcffb95e23015af8643ae046c0e912de0a438 带来的问题，我们来看一下代码，这个代码核心的的变更在于

重构了一部分 Module 的注册逻辑
引入 Gin 框架来作为 HTTP Configuration 变更的框架

那么这里我们来调试一下，因为原本的二进制是 strip 了符号信息，我们先关闭符号信息，然后上 gdb ，获取崩溃时的栈信息，能得到如下信息

[Switching to LWP 1772723]
0x00007fffabe44696 in __ctype_init () from /usr/lib/libc.so.6
(gdb) bt
#0  0x00007fffabe44696 in __ctype_init () from /usr/lib/libc.so.6
#1  0x00007fffabf785d1 in __libc_early_init () from /usr/lib/libc.so.6
#2  0x000000000118729f in dl_open_worker_begin ()
#3  0x000000000113a7b8 in _dl_catch_exception ()
#4  0x0000000001186469 in dl_open_worker ()
#5  0x000000000113a7b8 in _dl_catch_exception ()
#6  0x000000000118681b in _dl_open ()
#7  0x000000000113a8f6 in do_dlopen ()
#8  0x000000000113a7b8 in _dl_catch_exception ()
#9  0x000000000113a883 in _dl_catch_error ()
#10 0x000000000113aa74 in __libc_dlopen_mode ()
#11 0x0000000001128eb5 in module_load ()
#12 0x0000000001129315 in __nss_module_get_function ()
#13 0x0000000001118fec in getaddrinfo ()
#14 0x0000000001099119 in _cgo_04fbb8f65a5f_C2func_getaddrinfo (v=0xc00013ca90) at cgo-gcc-prolog:60
#15 0x0000000000481f84 in runtime.asmcgocall () at /root/.go/src/runtime/asm_amd64.s:923
#16 0x000000c0001048c0 in ?? ()
#17 0x000000000048045a in runtime.morestack () at /root/.go/src/runtime/asm_amd64.s:621
#18 0x47681163f543b200 in ?? ()
#19 0x0100000000000016 in ?? ()
#20 0x0000000000800000 in net.(*sysDialer).dialSerial (sd=0x0, ctx=..., ras=..., ~r0=..., ~r1=...) at /root/.go/src/net/dial.go:630
#21 0x0000000000000000 in ?? ()

我们能看到 net.(*sysDialer).dialSerial 非常显眼，这个函数通常是在使用 net.Dialer ，进行 TCP 的监听时处理的，我们根据这一个信息，对比 code diff，便能确定，这一点是我们所引入 Gin 框架，执行 TCP 监听流程时遇到问题。

我们再往下看，我们能看到 getaddrinfo 这个函数，这个是执行 DNS Lookup 的痕迹。我们将代码中的 localhost:xx 更改为 IP 地址的形式，如同我们所预料的一样，问题消失了

那么我们可以判定，这个问题是 Golang 走 CGO 调用 getaddrinfo 时变量导致的问题

我们可以在开源社区的 Issue 中，查到之前的 Report，参见 https://github.com/golang/go/issues/30310，解决方法是可以避免使用 glibc 提供的 DNS lookup 而使用 Go 内置实现的 DNS 来处理。

在将项目代码构建参数新增 -tags 'netgo' 后，问题解决。

那么这个问题就到词结束了吗？并不是，我们的问题依然存在，到底是什么原因导致我们会出现使用 glibc 的时候有 Segment fault 的发生？

我们先把我们复现代码最小化

package main

import (
    "fmt"
    "net"
)

func main() {
    address := "localhost:8080"

    listener, err := net.Listen("tcp", address)
    if err != nil {
        fmt.Println("Error creating listener:", err)
        return
    }
    defer listener.Close()

    fmt.Printf("Listening on %s\n", address)

    for {
        conn, err := listener.Accept()
        if err != nil {
            fmt.Println("Error accepting connection:", err)
            continue
        }

        go handleConnection(conn)
    }
}

func handleConnection(conn net.Conn) {
    defer conn.Close()

    buffer := make([]byte, 1024)
    n, err := conn.Read(buffer)
    if err != nil {
        fmt.Println("Error reading from connection:", err)
        return
    }

    fmt.Printf("Received: %s\n", string(buffer[:n]))

    response := "Hello, client!"
    _, err = conn.Write([]byte(response))
    if err != nil {
        fmt.Println("Error writing to connection:", err)
        return
    }
}

我们先使用，CGO_ENABLED=1 go build 来构建复现代码，然后发现，可以在不同环境下运行。而当我们使用 CGO_ENABLED=1 go build -ldflags "-linkmode=external -extldflags -static" 的参数构建的产物则不可以。为什么呢？我们来对比下汇编

我们能发现在第一种参数构建的代码，其 getaddrinfo 的部分如下

00000000004022a0 :
  4022a0:ff 25 aa 3e 1e 00    jmp    *0x1e3eaa(%rip)        # 5e6150 
  4022a6:68 27 00 00 00       push   $0x27
  4022ab:e9 70 fd ff ff       jmp    402020 <_init+0x20>

哦，熟悉的 PLT 的部分，这一部分是纯动态链接，直接在加载时由链接器来处理。而第二种方式构建的的产物却不一样

0000000000528fd0 :
  528fd0:f3 0f 1e fa          endbr64
  528fd4:55                   push   %rbp
  528fd5:48 89 e5             mov    %rsp,%rbp
  528fd8:41 57                push   %r15
  528fda:49 89 d7             mov    %rdx,%r15
  528fdd:41 56                push   %r14
  528fdf:41 55                push   %r13
  528fe1:41 54                push   %r12
  528fe3:49 89 f4             mov    %rsi,%r12
  528fe6:53                   push   %rbx
  528fe7:48 81 ec 38 07 00 00 sub    $0x738,%rsp
  528fee:48 89 bd 18 f9 ff ff mov    %rdi,-0x6e8(%rbp)
  528ff5:48 89 8d b0 f8 ff ff mov    %rcx,-0x750(%rbp)
  528ffc:64 48 8b 04 25 28 00 mov    %fs:0x28,%rax
  529003:00 00 
  529005:48 89 45 c8          mov    %rax,-0x38(%rbp)
  529009:31 c0                xor    %eax,%eax
  52900b:48 c7 85 30 f9 ff ff movq   $0x0,-0x6d0(%rbp)
  529012:00 00 00 00 
  529016:48 85 ff             test   %rdi,%rdi
  529019:0f 84 3a 08 00 00    je     529859 
  52901f:80 3f 2a             cmpb   $0x2a,(%rdi)
  529022:0f 84 27 08 00 00    je     52984f 
  529028:4d 85 e4             test   %r12,%r12
  52902b:74 0b                je     529038 
  52902d:41 80 3c 24 2a       cmpb   $0x2a,(%r12)
  529032:0f 84 7c 0b 00 00    je     529bb4 
  529038:4d 85 ff             test   %r15,%r15
  52903b:0f 84 4f 08 00 00    je     529890 
  529041:41 8b 07             mov    (%r15),%eax
  529044:a9 00 f8 ff ff       test   $0xfffff800,%eax
  529049:0f 85 6d 19 00 00    jne    52a9bc 
  52904f:48 83 bd 18 f9 ff ff cmpq   $0x0,-0x6e8(%rbp)

这里省略了很多的汇编，我们可以结合 GDB 的调试来看一下关键信息

#0  0x00007fffb0044696 in __GI___ctype_init () at ctype-info.c:31
#1  0x00007fffb01785d1 in __libc_early_init (initial=false) at libc_early_init.c:35
#2  0x000000000059549f in dl_open_worker_begin ()
#3  0x000000000054a5e8 in _dl_catch_exception ()
#4  0x0000000000594669 in dl_open_worker ()
#5  0x000000000054a5e8 in _dl_catch_exception ()
#6  0x0000000000594a1b in _dl_open ()
#7  0x000000000054a726 in do_dlopen ()
#8  0x000000000054a5e8 in _dl_catch_exception ()
#9  0x000000000054a6b3 in _dl_catch_error ()
#10 0x000000000054a8a4 in __libc_dlopen_mode ()
#11 0x0000000000538ce5 in module_load ()
#12 0x0000000000539145 in __nss_module_get_function ()
#13 0x000000000052aa3c in getaddrinfo ()
#14 0x00000000004da549 in _cgo_04fbb8f65a5f_C2func_getaddrinfo (v=0xc0001acdd0) at /tmp/go-build/cgo-gcc-prolog:60
#15 0x0000000000471204 in runtime.asmcgocall () at /root/.go/src/runtime/asm_amd64.s:923
#16 0x000000c0001868c0 in ?? ()

我们能看到第二种方式（即使用外部链接器，以静态链接方式进行链接）的背后是会用 dl_open 去处理 glibc 的链接

我们直接跳转到 __ctype_init 看下源码以及汇编，这里第一段汇编是在 Glibc 2.35 下编译产物，第二段是在 Arch Linux 下的 Glibc 2.40 下编译的产物

void
__ctype_init (void)
{
  const uint16_t **bp = __libc_tsd_address (const uint16_t *, CTYPE_B);
  *bp = (const uint16_t *) _NL_CURRENT (LC_CTYPE, _NL_CTYPE_CLASS) + 128;
  const int32_t **up = __libc_tsd_address (const int32_t *, CTYPE_TOUPPER);
  *up = ((int32_t *) _NL_CURRENT (LC_CTYPE, _NL_CTYPE_TOUPPER) + 128);
  const int32_t **lp = __libc_tsd_address (const int32_t *, CTYPE_TOLOWER);
  *lp = ((int32_t *) _NL_CURRENT (LC_CTYPE, _NL_CTYPE_TOLOWER) + 128);
}

000000000055aee0 <__ctype_init>:
  55aee0:f3 0f 1e fa          endbr64
  55aee4:48 c7 c0 80 ff ff ff mov    $0xffffffffffffff80,%rax
  55aeeb:48 c7 c1 f0 ff ff ff mov    $0xfffffffffffffff0,%rcx
  55aef2:64 48 8b 00          mov    %fs:(%rax),%rax
  55aef6:48 8b 00             mov    (%rax),%rax
  55aef9:48 8b 70 40          mov    0x40(%rax),%rsi
  55aefd:48 8d 96 00 01 00 00 lea    0x100(%rsi),%rdx
  55af04:64 48 89 11          mov    %rdx,%fs:(%rcx)
  55af08:48 8b 78 48          mov    0x48(%rax),%rdi
  55af0c:48 c7 c1 e8 ff ff ff mov    $0xffffffffffffffe8,%rcx
  55af13:48 8d 97 00 02 00 00 lea    0x200(%rdi),%rdx
  55af1a:64 48 89 11          mov    %rdx,%fs:(%rcx)
  55af1e:48 8b 40 58          mov    0x58(%rax),%rax
  55af22:48 c7 c2 e0 ff ff ff mov    $0xffffffffffffffe0,%rdx
  55af29:48 05 00 02 00 00    add    $0x200,%rax
  55af2f:64 48 89 02          mov    %rax,%fs:(%rdx)
  55af33:c3                   ret
  55af34:66 2e 0f 1f 84 00 00 cs nopw 0x0(%rax,%rax,1)
  55af3b:00 00 00 
  55af3e:66 90                xchg   %ax,%ax

第二段

000000000111c270 <__ctype_init>:
 111c270:f3 0f 1e fa          endbr64
 111c274:48 c7 c0 90 ff ff ff mov    $0xffffffffffffff90,%rax
 111c27b:48 c7 c1 e8 ff ff ff mov    $0xffffffffffffffe8,%rcx
 111c282:64 48 8b 00          mov    %fs:(%rax),%rax
 111c286:48 8b 00             mov    (%rax),%rax
 111c289:48 8b 70 38          mov    0x38(%rax),%rsi
 111c28d:48 8d 96 00 01 00 00 lea    0x100(%rsi),%rdx
 111c294:64 48 89 11          mov    %rdx,%fs:(%rcx)
 111c298:48 8b 78 40          mov    0x40(%rax),%rdi
 111c29c:48 c7 c1 e0 ff ff ff mov    $0xffffffffffffffe0,%rcx
 111c2a3:48 8d 97 00 02 00 00 lea    0x200(%rdi),%rdx
 111c2aa:64 48 89 11          mov    %rdx,%fs:(%rcx)
 111c2ae:48 8b 40 50          mov    0x50(%rax),%rax
 111c2b2:48 c7 c2 d8 ff ff ff mov    $0xffffffffffffffd8,%rdx
 111c2b9:48 05 00 02 00 00    add    $0x200,%rax
 111c2bf:64 48 89 02          mov    %rax,%fs:(%rdx)
 111c2c3:c3                   ret
 111c2c4:66 2e 0f 1f 84 00 00 cs nopw 0x0(%rax,%rax,1)
 111c2cb:00 00 00 
 111c2ce:66 90                xchg   %ax,%ax

我们能看到两段代码行为基本一致，但是 offset 存在明显差异。这个时候我们对比一下 Glibc 两个版本的代码的差异

我们能发现，由于 __locale_data 结构的变化，导致 _NL_CTYPE_CLASS 的 offset 在不同版本下存在偏移

//v2.35

struct __locale_data
{
  const char *name;
  const char *filedata;/* Region mapping the file data.  */
  off_t filesize;/* Size of the file (and the region).  */
  enum/* Flavor of storage used for those.  */
  {
    ld_malloced,/* Both are malloc'd.  */
    ld_mapped,/* name is malloc'd, filedata mmap'd */
    ld_archive/* Both point into mmap'd archive regions.  */
  } alloc;

  /* This provides a slot for category-specific code to cache data computed
     about this locale.  That code can set a cleanup function to deallocate
     the data.  */
  struct
  {
    void (*cleanup) (struct __locale_data *);
    union
    {
      void *data;
      struct lc_time_data *time;
      const struct gconv_fcts *ctype;
    };
  } private;

  unsigned int usage_count;/* Counter for users.  */

  int use_translit;/* Nonzero if the mb*towv*() and wc*tomb()
   functions should use transliteration.  */

  unsigned int nstrings;/* Number of strings below.  */
  union locale_data_value
  {
    const uint32_t *wstr;
    const char *string;
    unsigned int word;/* Note endian issues vs 64-bit pointers.  */
  }
  values __flexarr;/* Items, usually pointers into `filedata'.  */
};

//v2.40

struct __locale_data
{
  const char *name;
  const char *filedata;/* Region mapping the file data.  */
  off_t filesize;/* Size of the file (and the region).  */
  enum/* Flavor of storage used for those.  */
  {
    ld_malloced,/* Both are malloc'd.  */
    ld_mapped,/* name is malloc'd, filedata mmap'd */
    ld_archive/* Both point into mmap'd archive regions.  */
  } alloc;

  /* This provides a slot for category-specific code to cache data
     computed about this locale.  Type of the data pointed to:

     LC_CTYPE   struct lc_ctype_data (_nl_intern_locale_data)
     LC_TIME    struct lc_time_data (_nl_init_alt_digit, _nl_init_era_entries)

     This data deallocated at the start of _nl_unload_locale.  */
  void *private;

  unsigned int usage_count;/* Counter for users.  */

  int use_translit;/* Nonzero if the mb*towv*() and wc*tomb()
   functions should use transliteration.  */

  unsigned int nstrings;/* Number of strings below.  */
  union locale_data_value
  {
    const uint32_t *wstr;
    const char *string;
    unsigned int word;/* Note endian issues vs 64-bit pointers.  */
  }
  values __flexarr;/* Items, usually pointers into `filedata'.  */
};

那么我们问题的 Root cause 也就得到了确定，整个问题的因果链如下

我们项目使用引入 Gin，来作为 HTTP Server
我们使用 localhost 来作为默认的监听地址
localhost 在服务端启动监听的时候触发了 DNS Lookup 行为
CGO_ENABLED=1 的情况下，Golang 默认使用 glibc 中的 getaddrinfo 进行 DNS lookup
我们项目开启了 -ldflags "-linkmode=external -extldflags -static"，即使用外部链接器，以静态链接方式进行链接），将会使用 dl_open 来处理 glibc，而且这种情况下，__ctype_init 这类方法将会被静态编译至二进制中
Glibc 中特定字段不同版本的 offset 不一致
结合 4&5&6, 我们在 Glibc 2.35 （即文中默认的构建机）静态编译后的产物，因为 offset 不一致，在 Glibc 2.40 （即 Arch Linux）下使用时，会出现 segment fault

问题得证

总结

这个问题变更只有一行，但是查了我很久的时间，反复在 Go 和 Glibc 的源码中横跳。顺便还去复习了 Linker 的很多知识

这某种意义上是我很喜欢这个行业的原因，因为我们所遇到的每个问题背后的风景，都很值得一看。

2024 年了，是 Gevent 还是选择 asyncio Part 1？

2024-08-19T17:00:00.000Z

Gevent 还是 asyncio 这一直是个经典的问题，在这里我们直接用数据来帮助大家做一下决策

开篇

Lin Wei 老师珠玉在前

给出了 asyncio 和 Gevnet 的极限性能。在这里我们看到了 asyncio 配合 uvloop 基本上是 Gevent 的 double 了

那么在在 Web 框架下是否如此呢？

我们来做一下实验吧

首先说一下负载机器的配置，这里我选用了 Azure 上 D8as_v5 的机器，该机器配置如下：

8Core32G 的配置
底座硬件基于 EPYC 7763 系列处理器
共计4个节点，分配给 Django/Flast/FastAPI/Starlette 四个不同的框架

我们压测框架选择 locust，同样基于 Kuberntes 集群，因为我账户的 D8as_v5 机器的 Quota 不太够，所以压测框架我们选了不同机器的混合部署

4个 D8as_v5，共计 32 Core 算力
4个 D8as_v3，共计 32 Core 算力
4个 D4as_v2，共计 16 Core 算力

我们测试的主要目的是模拟在生产环境下的吞吐，所以我选择的测试方式如下

准备一台 16Core 64G 的 MySQL 实例，用于存储数据
创建一张表，随机写入100万数据
在框架代码中进行 SQL 查询，返回查询结果

MySQL 表结构如下

create table  if not exists  `demo_data`
(
    `id`          bigint(20)   not null auto_increment,
    `name`        varchar(255) not null,
    `create_time` timestamp default CURRENT_TIMESTAMP,
    `update_time` timestamp default CURRENT_TIMESTAMP,
    primary key (`id`),
    index (`name`)
) charset = utf8mb4
  engine = innodb;

Django 代码如下

import random

from django.core import serializers
from django.shortcuts import HttpResponse

from .models import DemoData

TEMP = "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()_+=-"


# Create your views here.
def demo_views(request):
    result = DemoData.objects.filter(
        name="".join(random.choices(TEMP, k=random.randrange(1, 254)))
    )
    # x = json.dumps(request.body)
    return HttpResponse(
        serializers.serialize("json", result if result else []),
        content_type="application/json",
    )

Flask 代码如下

import json
import random

import os
import dataset
from flask import Flask, Response

app = Flask(__name__)

DATABASE_URL = f"mysql://{os.getenv('DATABASE_USER')}:{os.getenv('DATABASE_PASSWORD')}@{os.getenv('DATABASE_HOST')}:3306/demo"
db = dataset.connect(DATABASE_URL, engine_kwargs={"pool_size": 10000})

TEMP = "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()_+=-"


@app.route("/demo", methods=["GET"])
def demo_code():
    return Response(
        response=json.dumps(
            list(
                db.query(
                    f"select * from demo_data where name='{''.join(random.choices(TEMP, k=random.randrange(1, 254)))}'"
                )
            ),
            default=str
        ),
        status=200,
        content_type="application/json",
    )


if __name__ == "__main__":
    app.run(debug=True)

FastAPI 代码如下

import random
import os
from typing import List

import databases
import pymysql
import sqlalchemy
import json
from fastapi import FastAPI
from fastapi.responses import Response
from pydantic import BaseModel

pymysql.install_as_MySQLdb()

AYSNC_DATABASE_URL = f"mysql+aiomysql://{os.getenv('DATABASE_USER')}:{os.getenv('DATABASE_PASSWORD')}@{os.getenv('DATABASE_HOST')}:3306/demo"
SYNC_DATABASE_URL = f"mysql+mysqldb://{os.getenv('DATABASE_USER')}:{os.getenv('DATABASE_PASSWORD')}@{os.getenv('DATABASE_HOST')}:3306/demo"

database = databases.Database(AYSNC_DATABASE_URL, max_size=10000)

metadata = sqlalchemy.MetaData()

demo_data = sqlalchemy.Table(
    "demo_data",
    metadata,
    sqlalchemy.Column("id", sqlalchemy.Integer, primary_key=True),
    sqlalchemy.Column("name", sqlalchemy.String),
    sqlalchemy.Column("create_time", sqlalchemy.DATETIME),
    sqlalchemy.Column("update_time", sqlalchemy.DATETIME),
)
engine = sqlalchemy.create_engine(SYNC_DATABASE_URL)
metadata.create_all(engine)
TEMP = "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()_+=-"


class DemoData(BaseModel):
    id: int
    name: str


app = FastAPI()

init = False


@app.get("/demo", response_model=List[DemoData])
async def demo_code():
    global init
    if not init:
        await database.connect()
        init = True

    query = demo_data.select().where(
        demo_data.c.name == "".join(random.choices(TEMP, k=random.randrange(1, 254)))
    )
    data = await database.fetch_all(query)
    response = json.dumps(data, default=str)
    return Response(content=response, status_code=200, media_type="application/json")

Starlette 代码如下

import random
import os
from typing import List

import databases
import pymysql
import json
import sqlalchemy
from starlette.applications import Starlette
from starlette.responses import Response
from starlette.routing import Route
from pydantic import BaseModel

pymysql.install_as_MySQLdb()

AYSNC_DATABASE_URL = f"mysql+aiomysql://{os.getenv('DATABASE_USER')}:{os.getenv('DATABASE_PASSWORD')}@{os.getenv('DATABASE_HOST')}:3306/demo"
SYNC_DATABASE_URL = f"mysql+mysqldb://{os.getenv('DATABASE_USER')}:{os.getenv('DATABASE_PASSWORD')}@{os.getenv('DATABASE_HOST')}:3306/demo"

database = databases.Database(AYSNC_DATABASE_URL, max_size=10000)

metadata = sqlalchemy.MetaData()

demo_data = sqlalchemy.Table(
    "demo_data",
    metadata,
    sqlalchemy.Column("id", sqlalchemy.Integer, primary_key=True),
    sqlalchemy.Column("name", sqlalchemy.String),
    sqlalchemy.Column("create_time", sqlalchemy.DATETIME),
    sqlalchemy.Column("update_time", sqlalchemy.DATETIME),
)
engine = sqlalchemy.create_engine(SYNC_DATABASE_URL)
metadata.create_all(engine)
TEMP = "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()_+=-"


class DemoData(BaseModel):
    id: int
    name: str


init = False


async def demo_code(request):
    global init
    if not init:
        await database.connect()
        init = True

    query = demo_data.select().where(
        demo_data.c.name == "".join(random.choices(TEMP, k=random.randrange(1, 254)))
    )
    data = await database.fetch_all(query)
    return Response(content=json.dumps(data, default=str), status_code=200, media_type="application/json")

routes = [
    Route("/demo", demo_code, methods=["GET"]),
]

app = Starlette(debug=False, routes=routes)

然后部署方式如下

各服务都部署在 K8S 上，POD 类型为 Guaranteed
所有镜像都基于 3.12 构建
服务限制 6Core 的 CPU
Django 和 Flask 基于 Gevent + Gunicorn 进行部署，利用 Greenify 对二进制进行 Patch
FastAPI 和 Starlette 基于 uvicorn 进行部署，使用 uvloop 作为 event loop

OK，我们现在来公布测试结果

标准操作下的测试结果

Django:

FastAPI

Flask

Starlette

Django 毫无疑问的最后，其余三者的性能是 Flask + Gevent > Starlette > FastAPI，后三个框架 CPU 占用率均 > 90%

空转测试

为了保险起见，我们将后续三个框架进行空转测试

Flask

FastAPI

Starlette

Starlette > FastAPI > Flask + Gevent

总结

目前来看，整体结论是这样

在空转情况下，asyncio 的性能要搞出 Gevent 不少，加上框架因素后，也有百分之10-20% 的提升
在 ORM + MySQL Driver 的情况下，Gevent 的生态要好于 asyncio 的生态

如果换成 ORM + PGSQL 的生态结论会不会更好一些呢？有点期待下一轮测试的结果

In 2024, Gevent or asyncio? Part 1

2024-08-19T17:00:00.000Z

The choice between Gevent and asyncio has always been a classic question. Here, we’ll use data to help you make a decision.

Introduction

Professor Lin Wei has set a high standard:

This graph shows the extreme performance of asyncio and Gevent. We can see that asyncio with uvloop is basically double the performance of Gevent.

But is this the case under web frameworks?

Let’s conduct an experiment.

First, let’s talk about the configuration of the load machine. I chose a D8as_v5 machine on Azure with the following configuration:

8 Core 32GB configuration
The underlying hardware is based on the EPYC 7763 series processor
A total of 4 nodes, allocated to Django/Flask/FastAPI/Starlette, four different frameworks

We chose locust as our load testing framework, also based on a Kubernetes cluster. Because the quota for D8as_v5 machines in my account wasn’t sufficient, we chose a mixed deployment of different machines for the load testing framework:

4 D8as_v5, totaling 32 Core computing power
4 D8as_v3, totaling 32 Core computing power
4 D4as_v2, totaling 16 Core computing power

Our main purpose for testing is to simulate throughput in a production environment, so I chose the following test method:

Prepare a 16 Core 64GB MySQL instance for data storage
Create a table and randomly write 1 million data entries
Perform SQL queries in the framework code and return the query results

The MySQL table structure is as follows:

create table if not exists `demo_data`
(
    `id`          bigint(20)   not null auto_increment,
    `name`        varchar(255) not null,
    `create_time` timestamp default CURRENT_TIMESTAMP,
    `update_time` timestamp default CURRENT_TIMESTAMP,
    primary key (`id`),
    index (`name`)
) charset = utf8mb4
  engine = innodb;

Django code is as follows:

import random

from django.core import serializers
from django.shortcuts import HttpResponse

from .models import DemoData

TEMP = "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()_+=-"


# Create your views here.
def demo_views(request):
    result = DemoData.objects.filter(
        name="".join(random.choices(TEMP, k=random.randrange(1, 254)))
    )
    # x = json.dumps(request.body)
    return HttpResponse(
        serializers.serialize("json", result if result else []),
        content_type="application/json",
    )

Flask code is as follows:

import json
import random

import os
import dataset
from flask import Flask, Response

app = Flask(__name__)

DATABASE_URL = f"mysql://{os.getenv('DATABASE_USER')}:{os.getenv('DATABASE_PASSWORD')}@{os.getenv('DATABASE_HOST')}:3306/demo"
db = dataset.connect(DATABASE_URL, engine_kwargs={"pool_size": 10000})

TEMP = "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()_+=-"


@app.route("/demo", methods=["GET"])
def demo_code():
    return Response(
        response=json.dumps(
            list(
                db.query(
                    f"select * from demo_data where name='{''.join(random.choices(TEMP, k=random.randrange(1, 254)))}'"
                )
            ),
            default=str
        ),
        status=200,
        content_type="application/json",
    )


if __name__ == "__main__":
    app.run(debug=True)

FastAPI code is as follows:

import random
import os
from typing import List

import databases
import pymysql
import sqlalchemy
import json
from fastapi import FastAPI
from fastapi.responses import Response
from pydantic import BaseModel

pymysql.install_as_MySQLdb()

AYSNC_DATABASE_URL = f"mysql+aiomysql://{os.getenv('DATABASE_USER')}:{os.getenv('DATABASE_PASSWORD')}@{os.getenv('DATABASE_HOST')}:3306/demo"
SYNC_DATABASE_URL = f"mysql+mysqldb://{os.getenv('DATABASE_USER')}:{os.getenv('DATABASE_PASSWORD')}@{os.getenv('DATABASE_HOST')}:3306/demo"

database = databases.Database(AYSNC_DATABASE_URL, max_size=10000)

metadata = sqlalchemy.MetaData()

demo_data = sqlalchemy.Table(
    "demo_data",
    metadata,
    sqlalchemy.Column("id", sqlalchemy.Integer, primary_key=True),
    sqlalchemy.Column("name", sqlalchemy.String),
    sqlalchemy.Column("create_time", sqlalchemy.DATETIME),
    sqlalchemy.Column("update_time", sqlalchemy.DATETIME),
)
engine = sqlalchemy.create_engine(SYNC_DATABASE_URL)
metadata.create_all(engine)
TEMP = "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()_+=-"


class DemoData(BaseModel):
    id: int
    name: str


app = FastAPI()

init = False


@app.get("/demo", response_model=List[DemoData])
async def demo_code():
    global init
    if not init:
        await database.connect()
        init = True

    query = demo_data.select().where(
        demo_data.c.name == "".join(random.choices(TEMP, k=random.randrange(1, 254)))
    )
    data = await database.fetch_all(query)
    response = json.dumps(data, default=str)
    return Response(content=response, status_code=200, media_type="application/json")

Starlette code is as follows:

import random
import os
from typing import List

import databases
import pymysql
import json
import sqlalchemy
from starlette.applications import Starlette
from starlette.responses import Response
from starlette.routing import Route
from pydantic import BaseModel

pymysql.install_as_MySQLdb()

AYSNC_DATABASE_URL = f"mysql+aiomysql://{os.getenv('DATABASE_USER')}:{os.getenv('DATABASE_PASSWORD')}@{os.getenv('DATABASE_HOST')}:3306/demo"
SYNC_DATABASE_URL = f"mysql+mysqldb://{os.getenv('DATABASE_USER')}:{os.getenv('DATABASE_PASSWORD')}@{os.getenv('DATABASE_HOST')}:3306/demo"

database = databases.Database(AYSNC_DATABASE_URL, max_size=10000)

metadata = sqlalchemy.MetaData()

demo_data = sqlalchemy.Table(
    "demo_data",
    metadata,
    sqlalchemy.Column("id", sqlalchemy.Integer, primary_key=True),
    sqlalchemy.Column("name", sqlalchemy.String),
    sqlalchemy.Column("create_time", sqlalchemy.DATETIME),
    sqlalchemy.Column("update_time", sqlalchemy.DATETIME),
)
engine = sqlalchemy.create_engine(SYNC_DATABASE_URL)
metadata.create_all(engine)
TEMP = "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()_+=-"


class DemoData(BaseModel):
    id: int
    name: str


init = False


async def demo_code(request):
    global init
    if not init:
        await database.connect()
        init = True

    query = demo_data.select().where(
        demo_data.c.name == "".join(random.choices(TEMP, k=random.randrange(1, 254)))
    )
    data = await database.fetch_all(query)
    return Response(content=json.dumps(data, default=str), status_code=200, media_type="application/json")

routes = [
    Route("/demo", demo_code, methods=["GET"]),
]

app = Starlette(debug=False, routes=routes)

The deployment method is as follows:

All services are deployed on K8S, with POD type as Guaranteed
All image is built base on the Python 3.12
Services are limited to 6 Core CPU
Django and Flask are deployed based on Gevent + Gunicorn, using Greenify to patch the binary
FastAPI and Starlette are deployed based on uvicorn, using uvloop as the event loop

OK, now let’s reveal the test results.

Test Results Under Standard Operations

Django:

FastAPI:

Flask:

Starlette:

Django is undoubtedly the last, while the performance of the other three is Flask + Gevent > Starlette > FastAPI. The CPU usage of the latter three frameworks is all > 90%.

Idle Test

To be on the safe side, we conducted an idle test on the latter three frameworks.

Flask:

FastAPI:

Starlette:

Starlette > FastAPI > Flask + Gevent

Conclusion

Currently, the overall conclusions are as follows:

In idle situations, the performance of asyncio is significantly better than Gevent. Even with the framework factor, there is still a 10-20% improvement.
In the case of ORM + MySQL Driver, Gevent’s ecosystem is better than asyncio’s ecosystem.

If we switch to ORM + PGSQL ecosystem, will the conclusion be even better? Looking forward to the results of the next round of tests.