Nginx 内嵌 CPython → 升级实录

摘要：我们的 Nginx 不是反向代理，而是进程内嵌入 CPython 跑业务逻辑。Python 时真正卡住的不是语法，而是 Nginx+ CPython+ 硬件加密狗 SDK 在同一进程里对 OpenSSL 的版本拉扯。这篇文章记录三轮踩坑、gdb 排障过程和最终解法。

关键词： Nginx、CPython、嵌入、OpenSSL、加密狗、ERP

一、背景：为什么 Nginx 里跑 Python

团餐 ERP 这类程序大量本地部署到客户内网，交付形态是整机/整包安装。我们的 Nginx 承担的是应用服务器HTTP/HTTPS 进线后主要原因在同一进程里由嵌入的 CPython 执行，而不是反代到 uwsgi/gunicorn。

选 CPython 而不是 OpenResty。原因很朴素：团队资产和技能栈都在 Python，业务脚本、对接方式、排障习惯都长在这条链上。我们用 BOOST_PYTHON_MODULE 把日志、应答、跨进程 FIFO 等能力注册进 Python。换 Lua 等于重写一层 FFI，成本比升级解释器大一个数量级。

客户环境不可控、拷贝成本低，主要脚本不能明文裸奔——所以进程里还叠了一层硬件加密狗 SDK做运行期绑定。其实，这个加密狗是后文 OpenSSL 拉扯的第三方主角。老实说，

痛点：Python 3.5 已在 2020 年停止维护。安全补丁全无，依赖链老化导致线上突发崩溃。其实，迫切需要升级到受支持的 3.8。

二、单进程里谁在做什么

之前先搞清楚当前程序长什么样。跑在线上的 nginx 可以看成一条固定流水线，后文所有改动都是换心脏但不改站位：

flowchart TB
subgraph proc
ngx
py
dog
end
osl
ngx --> osl
py --> osl
dog --> osl

四块积木这方面。

1. TLS对外 HTTPS，底层链 OpenSSL。
2. 硬件授权进程启动前必须就绪，失败直接拒绝启动；说起来，厂商库内部也走 TLS/密码学方法。不过，
3. 嵌入 CPython在 worker 侧用独立业务线程跑。不能让 Nginx 事件线程随便进入解释器。老实说，
4. 链接与运行时上述全部编译进同一个可执行文件或同一套 rpath。运行时只能认一套libcrypto/libssl

启动顺序：先授权 → 再进入主循环 → worker 里起 Python → GIL 边界 → 同一条大链接钉死 OpenSSL

启动这方面，先授权，再进主循环

ngx_use_stderr =;if，= NGX_OK) {
return;}
if {
ngx_single_process_cycle;} else {
ngx_master_process_cycle;话说回来，}

加密狗走在 master 启动方法上。和 worker 里起的 Python 业务线程处于同一地址空间的不同阶段——所以 ABI 不对时崩溃堆栈很难一眼判断是业务脚本的问题还是授权链的问题。

嵌入解释器的观点是，注册桥 → 设置 home → 初始化 → 放开 GIL

PyImport_AppendInittab;Py_SetPythonHome;if，= ) { /* 内部即 Py_InitializeEx */ }
if ) {
PyEval_InitThreads;}
PyObject *sys_path = PySys_GetObject;PyList_Append);py_thread = PyEval_SaveThread;

• PyImport_AppendInittab 必须在 Py_Initialize*之前*调用，否则内置模块注册不上。
• P y_InitializeEx 表示不安装 Python 自己的信号处理器，避免和 Nginx master/worker 的信号逻辑抢钩子。
• P yEval_SaveThread 释放主线程 GIL，把“日常进 Python”交给业务线程里的 P yGILState_Ensure/Release

GIL这方面。只在进 Python 的临界区持锁

Nginx 侧大量 C 代码，任何调用 P y* 的方法都应落在明确临界区内：

GILGuard::GILGuard {
gil_token = PyGILState_Ensure;}
GILGuard::~GILGuard {
PyGILState_Release;}

链接形态

Nginx 官方 .configure. 生成 `objs/Makefile` `build.sh`

./configure --with-http_ssl_module \
--with-http_stub_status_module \
--add-module=../ngx_rpc_module \
--with-openssl=../third_party/openssl-1.1.1w \
--add-module=../ngx_python_embed_module \
--add-module=../nginx-upload-module

C 同步链接命令里必须出现P ython 动态库。硬件授权三件套,OpenSSL 静态库,还有pthread .缺任何环节都会导致“本地能编现场偶崩”。

三、主要难点：三个主角抢一个 OpenSSL

Pain Point: 每个组件都强依赖特定 OpenSSL ABI。一旦版本不一致，就会出现不可预期的 Crash 与 SSL handshake failure。 话说回来，

1. Nginx 的 HTTPS

Cpython 的 _ssl

硬件加密狗厂商库

The root cause is that dynamic linker can only tolerate a single set of `libcrypto` / `libssl`. When three parties bring in different versions。linker may resolve symbols from wrong library at runtime,leading to random crashes.

四 、升级方法与踩坑

CPython ：C API 改动

嵌入式升级并非简单替换 `python3` 可执行文件；说起来，三个大版本后需要修改以下关键 API ：

• 模块初始化 : `Py_InitModule3` → `PyModule_Create` c static struct PyModuleDef erp_bridge_module = { PyModuleDef_HEAD_INIT。"erp_bridge","ERP bridge module",-1,erp_methods };PyMODINIT_FUNC PyInit_erp_bridge { return PyModule_Create;} 漏改表现为 `import erp_bridge` 报 `ModuleNotFoundError`，即使文件已在 `sys.path` 中。
• 字符串函数 : `PyString_FromString` → `PyUnicode_FromString` 全局搜索并替换，否则编译报错。
• 线程初始化 : `PyEval_InitThreads` 已成 no‑op 保留调用不影响运行。
• 热重载陷阱 : 多次调用 `Py_Finalize` 再重建解释器会与仍在运行的业务线程竞争 GIL，引发未定义行为。老实说，仅用于本地排障，不建议生产使用。

Nginx 嵌入层适配

• `python_embed_worker_init` 创建 `PythonWorker` 并启动业务线程。
• `python_embed_worker_exit` 将全局标记设为 false，实现优雅退出。
• `worker_python.cpp` 主循环仅在 “加载业务模块 / 调用 Python 函数” 区段使用 `GILGuard` 包裹。后仅需更新模块初始化签名和字符串 API，其余代码保持不变。

OpenSSL 三方对齐 ： 三轮踩坑历程

第一轮 : 各自链接导致交叉崩溃

现象 :

• HTTPS 握手直接断开。
• Python ssl 模块导入失败。
• 硬件狗初始化报错 `)。

定位过程 :

/ # ldd objs/nginx | grep ssl
libssl.so.. => /lib/x86_64-linux-gnu/libssl.so..
libssl.so. => not found
/ # 

ldd $') | grep ssl

ldd libhkey_runtime.so | grep ssl

三者指向不同版本的动态库，同一个进程只能保有一种符号集合。其实，

修复 :

将 Nginx 编译时静态链接自带源码树中的 OpenSSL。确保 Nginx 本身不再依赖程序 libssl。

第二轮 : 加密狗仍然挂掉  ​​​​​​​ ​​​ ​​​​ ​​​ ​​​ ​​​ ​​​​​​                                

​

bash

Program received signal SIGSEGV…0x00007f3b2c1a8e22 in SSLCTXnew from /opt/erp/thirdparty/libhkeyruntime.so

根因 :

厂商提供的 libhkey_runtime.so 在内部 静态 链接了旧版 OpenSSL，导致其内部读取错误结构体字段而 segfault。联系供应商获取基于相同 OpenSSL 源码树的新版 SDK 动态库。

第三轮 : 定案 – 单宿主、单版本、尽量静态  ​

最终链接行示例：

bash nginx-objs/nginx: -lpython3.8 -lboost_python38 -ljsoncpp -lerp_business \ -lhkey_runtime -lhkey_control -lhkey_auth \ ../third_party/openssl-1.1.1w/libssl.a \ ../third_party/openssl-1.1.1w/libcrypto.a \ -lpcre -lz -ldl -lpthread

说到原则，

• OpenSSL 静态链接 ： 使用 `.a` 库避免运行时加载额外的 `.so`。​
• Python 动态链接 ： 保持灵活，可随小版本升级而无需重新编译 Nginx 主体。​
• 硬件 SDK 动态链接 ： 保持供应商可自行更新而不影响整体二进制。​
•  pthread 必须放在链接行末尾，否则可能出现未解析符号错误。怎么说呢，​

从验证来看。

bash ldd objs/nginx | grep -i ssl

代价OpenSSL 小版本升级需要重新编译整条链路，但比起运行期随机崩溃要可控得多。

Makefile 手术 : build.sh 做了什么

• 去掉 `-Werror` sh sed -i 's/-Werror//' objs/Makefile 防止因自研模块警告导致编译中断。
• 强制使用自带 OpenSSL 头文件方法 sh sed -i 's|-I/usr/include/openssl|-I../third_party/openssl-1.1.1w/include|g' objs/Makefile 避免意外引用程序头文件导致 ABI 不匹配。
• 将 `-lpthread` 移至链接行末尾 sh # 删除原位置： sed -i 's/-lpthread //' objs/Makefile # 在末尾追加： sed -i '$ s/$/ -lpthread/' objs/Makefile 因为 Python 链接需要 pthread，而若 pthread 位于 python 前面会导致未解析符号错误。按理说，
• 补齐 Python 与加密狗库的搜索方法与链接选项 sh sed -i '$ s/$/ -L\/opt\/erp\/python3.8\/lib -lpython3.8 -lboost_python38/' objs/Makefile sed -i '$ s/$/ -L\/opt\/erp\/hkey\/lib -lhkey_runtime -lhkey_control -lhkey_auth/' objs/Makefile 确保所有自研和第三方库均被正确加入最终可执行文件。

每次运行 /configure ... && ./build.sh 即可得到一致且可复现的二进制产出。话说回来，

验收标准 & 回归测试 

 

 

 

 

 


• TLS 验证 :: 使用压测工具覆盖完整握手流程。包括证书链验证、会话复用还有错误证书场景；确保无随机 handshake failure。
  ⚠️ 痛点回顾 – “HTTPS 正常但偶尔业务掉线”，正是因为之前多版本 OpenSSL 共存导致符号冲突所致。
  ，…，….... ... ... ... .... ... ... ...

—–

…

…，

….

—

-

...

————

——————

---

---

——-

---

---

---

---

---

---

--

---

---

---

---

---

---

---

–-

–

–- –

–– – — – – — –

- – —- - – – –

–––––

—-

— -

―

―‐

―――――――――――――――――

---