Nuclio Python 运行时完全参考:Handler 编写、Dockerfile 构建与部署实战指南

原创2026-10-11 21:46:521,925 阅读
文章标签:云原生后端微服务

Nuclio Python 运行时完全参考:Handler 编写、Dockerfile 构建与部署实战指南

本文是 Nuclio 高性能 Serverless 事件与数据处理平台中 Python 运行时的专项参考指南,系统讲解 Python 函数的 Handler 入口规范、异步(asyncio)支持、自定义 Dockerfile 构建流程、受支持的 Python 版本与 EOL 策略、事件元数据解码行为、函数配置写法、镜像构建与运行命令,以及处理器退出时的终止回调(Termination Callback)机制。读完本文,你将能够独立编写并部署一个生产可用的 Nuclio Python 函数,并理解其背后的处理器(Processor)与 Python Wrapper 协作原理。

本文对应的原始参考文档位于 docs/reference/runtimes/python/python-reference.md,全部实现代码位于 pkg/processor/runtime/python,建议结合源码阅读。


函数与 Handler(Function and Handler)

Nuclio Python 函数的核心是一个普通 Python 函数,通过 nuclio_sdk 提供的类型注解接收上下文(context)与事件(event),并返回处理结果:

import nuclio_sdk

def handler(context: nuclio_sdk.Context, event: nuclio_sdk.Event):
    context.logger.info_with('Invoked', method=event.method)
    return "Hello, from Nuclio :]"

Handler 字段格式

handler 字段的格式为 <package>:<entrypoint>:

  • <package>:以点(.)分隔的模块路径。例如 foo.bar 等价于文件 foo/bar.py(即点号对应目录层级);
  • <entrypoint>:模块内的函数名。

以上面代码为例,若文件命名为 main.py,则 handler 应配置为 main:handler。

这个格式在 Python Wrapper 源码中通过正则表达式严格校验,见 wrapper_common.py:

match = re.match(r'^([\w|-]+(\.[\w|-]+)*):(\w+)$', handler)
if not match:
    raise ValueError('Malformed handler - {!r}'.format(handler))

module_name, entrypoint = match.group(1), match.group(3)
module = __import__(module_name)
for sub in module_name.split('.')[1:]:
    module = getattr(module, sub)
entrypoint_address = getattr(module, entrypoint)

可见模块名支持字母、数字、下划线以及连字符(-),wrapper 会依次逐级 import 并定位最终的入口函数;若找不到该函数,会在日志中输出 Handler not found 并抛出异常。

初始化钩子 init_context

除了 handler,wrapper 还支持模块级可选的 init_context(context) 钩子,用于在首次加载函数时执行一次性初始化(如加载模型、建立数据库连接)。其调用逻辑同样在 wrapper_common.py 中:wrapper 会检查入口模块是否定义了 init_context,若定义则先于事件处理调用它,并且支持异步的 async def init_context(通过 asyncio.iscoroutinefunction 判断后 await 其结果)。仓库测试函数目录 test/_functions/common/context-init 提供了相关示例。

异步函数支持(asyncio)

如需异步支持(例如基于 asyncio 的 I/O 密集型逻辑),函数需定义为 async def,并在需要等待的地方使用 await;同时必须在函数配置中把对应触发器的 spec.triggers.<trigger-name>.mode 设置为 async:

spec:
  triggers:
    myHttpTrigger:
      kind: http
      mode: async

异步 Handler 示例:

import asyncio

import nuclio_sdk

async def handler(context: nuclio_sdk.Context, event: nuclio_sdk.Event):
    await update_db(context, event)
    return 'ok'

async def update_db(context, event):
    context.db.update_record(event.body)

⚠️ 警告:Async 模式当前处于 Technical Preview(技术预览)阶段,请结合自身场景评估后再使用。

异步模式的详细说明请参阅 docs/tasks/async-mode.md。从源码实现看,当触发模式为 async 时,Go 处理器会选择启动异步版 wrapper 脚本 _nuclio_async_wrapper.py(见 runtime.go 中 getWrapperScriptPath() 对 functionconfig.AsyncTriggerWorkMode 的判断),该 wrapper 基于 asyncio + selectors 实现 TCP 多连接服务,每个连接对应一个并发处理任务(实现见 _nuclio_async_wrapper.py),并在启动时校验 Handler 必须是 async def 或异步生成器(async def 带 yield),否则抛出 WrapperFatalException。


使用 Dockerfile 构建 Python 函数镜像

Nuclio 支持完全由用户提供的 Dockerfile 来定义函数镜像的构建过程。以下是为 Python 函数部署编写的 Dockerfile 示例(完整教程见 docs/tasks/deploy-functions-from-dockerfile.md):

注意: 请务必将示例中的 my-function-code 和 my-function.yaml 替换为你自己的函数源码目录与函数配置文件名称。

ARG NUCLIO_LABEL=1.6.0
ARG NUCLIO_ARCH=amd64
ARG NUCLIO_BASE_IMAGE=python:3.8
ARG NUCLIO_ONBUILD_IMAGE=quay.io/nuclio/handler-builder-python-onbuild:${NUCLIO_LABEL}-${NUCLIO_ARCH}

# Supplies processor uhttpc, used for healthcheck
FROM nuclio/uhttpc:0.0.3-amd64 as uhttpc

# Supplies processor binary, wrapper
FROM ${NUCLIO_ONBUILD_IMAGE} as processor

# From the base image
FROM ${NUCLIO_BASE_IMAGE}

# Copy required objects from the suppliers
COPY --from=processor /home/nuclio/bin/processor /usr/local/bin/processor
COPY --from=processor /home/nuclio/bin/py /opt/nuclio/
COPY --from=processor /home/nuclio/bin/py*-whl/* /opt/nuclio/whl/
COPY --from=uhttpc /home/nuclio/bin/uhttpc /usr/local/bin/uhttpc

# Install pip (if missing) + nuclio python sdk and its dependencies
# Using "python -m" to ensure the given interpreter has all dependencies installed in cases
# .. where there is more than one python interpreter and global pip is attached to the other interpreter
RUN python /opt/nuclio/whl/$(basename /opt/nuclio/whl/pip-*.whl)/pip install pip --no-index --find-links /opt/nuclio/whl \
 && python -m pip install nuclio-sdk msgpack --no-index --find-links /opt/nuclio/whl

# Readiness probe
HEALTHCHECK --interval=1s --timeout=3s CMD /usr/local/bin/uhttpc --url http://127.0.0.1:8082/ready || exit 1

# Copy the function code, including the handler directory to /opt/nuclio
COPY . /opt/nuclio

# Run processor with configuration and platform configuration
CMD [ "processor" ]

各构建阶段说明

该 Dockerfile 采用多阶段构建,共使用三个 FROM:

  1. FROM nuclio/uhttpc:0.0.3-amd64 as uhttpc:提供健康检查所用的 uhttpc 二进制(一个自包含的 HTTP 探测工具)。它被复制到 /usr/local/bin/uhttpc,并配合 HEALTHCHECK 命令定时探测 http://127.0.0.1:8082/ready 判断处理器是否就绪。如果只运行在 Kubernetes 平台,该阶段与 HEALTHCHECK 指令可以省略;
  2. FROM ${NUCLIO_ONBUILD_IMAGE} as processor:即 handler-builder-python-onbuild 镜像,它通过 ONBUILD 指令提供两样关键产物——处理器二进制 processor(Go 编译的进程,负责触发接入、事件分发与结果回传)与 Python 侧 shim 层(wrapper 脚本及其依赖 wheel 包)。对于 Python 这类解释型运行时,不需要像 Go/Java 那样预编译用户代码,只需把 shim 层与用户代码一起放进最终镜像;
  3. FROM ${NUCLIO_BASE_IMAGE}:最终运行镜像的基础镜像(默认 python:3.8),其上叠加处理器、wrapper、SDK 与用户代码。

依赖安装与 SDK 版本

RUN 指令中的 pip install nuclio-sdk msgpack 是函数运行所必需的两个 Python 依赖。当前仓库中 Python runtime 的依赖清单(requirements)位于 pkg/processor/runtime/python/py/requirements/common.txt,固定版本为 nuclio-sdk==0.6.3、msgpack==1.2.1,另有 pip 与 mock;各受支持 Python 版本的 python3_10.txt、python3_11.txt、python3_12.txt 均通过 -r common.txt 引用同一份公共清单。

关于基础镜像版本: 示例 Dockerfile 中 NUCLIO_BASE_IMAGE 默认取 python:3.8,但 Python 3.8 已进入 EOL 名单(详见下文),官方推荐迁移到 3.10 及以上版本,请根据自身函数实际部署的 Python 版本调整该参数与函数配置中的 runtime 字段。


受支持的 Python 版本与 EOL 版本

Nuclio Python 运行时当前支持以下版本:

  • Python 3.10
  • Python 3.11
  • Python 3.12

集成测试同样按这三个版本逐一执行,见 pkg/processor/runtime/python/test/python_test.go:测试套件以 python:3.10、python:3.11、python:3.12 三种 runtime 名循环运行。

不再支持的版本(EOL)

以下 Python 版本因官方生命周期结束(End Of Life)而不再受 Nuclio 支持:

版本 EOL 时间
Python 2.7 2020 年 1 月
Python 3.6 2021 年 12 月
Python 3.7 2023 年 6 月
Python 3.8 2024 年 10 月
Python 3.9 2025 年 10 月

官方强烈建议将代码迁移到 Python 3.12 或更高版本,以获得更好的性能与消息吞吐。需要注意的是,虽然 EOL 版本已不再受支持,运行时源码仍对旧版本做了兼容性提示:见 runtime.go,当检测到 runtime 版本为 3.7 或 3.8(或未指定版本)时,会打印弃用警告,提示迁移到 python:3.11 或更高版本。

Python 3.10+ 的事件元数据解码行为

在 Python 3.10+ 运行时中,事件的元数据(如 headers、path、method 等字段)在反序列化时可能以 byte-string(字节串) 形式呈现,这会导致旧代码(例如在 Python 2.7 / 3.6 时代编写的、直接比较 event.path 字符串的代码)行为发生变化。

若想禁用 UTF-8 解码,可在函数环境变量中设置:

NUCLIO_PYTHON_DECODE_EVENT_STRINGS=disabled

禁用后,事件元数据字段不再被解码,而是以 byte-string 形式提供,代码需要相应调整。例如,原先这样写:

def handler(context, event):
    if event.path == "/do_something":
        return "I'm doing something..."

在禁用解码后应改为:

def handler(context, event):
    if event.path == b"/do_something":
        return "I'm doing something..."

环境变量的底层实现

这一行为由 Go 处理器的 resolveDecodeEvents() 决定,见 runtime.go:环境变量取值为 no、false、disable、disabled(不区分大小写)之一时返回 false,即不向 wrapper 传递 --decode-event-strings 参数;其余取值(包括空值、未设置以及 true)均视为启用 UTF-8 解码。随后该参数会作为命令行参数传给 wrapper(runtime.go),并进一步决定 msgpack 解包器使用 raw=False(解码)还是 raw=True(保留原始字节),以及事件反序列化器的选择,见 wrapper_common.py。

注意: 若不禁用事件字符串解码,当事件元数据包含非 UTF-8 内容时,Nuclio Python wrapper 的 msgpack 解码可能抛错(wrapper 捕获 UnicodeDecodeError 后会重置解包器并返回错误响应,见 _nuclio_wrapper.py)。请结合你的实际事件内容决定是否禁用解码。


函数配置(Function Configuration)

函数配置文件(例如与上述 Dockerfile 配套的 my-function.yaml)必须声明 Handler 名称与 Python runtime。完整的配置项说明参见 函数配置参考。示例:

meta:
  name: "my-function"
spec:
  handler: main:handler
  runtime: python:3.8
  triggers:
    myHttpTrigger:
      numWorkers: 1
      kind: "http"

各字段要点:

  • meta.name:函数名称,需与部署时的函数名一致;
  • spec.handler:即上文所述的 <package>:<entrypoint> 格式,这里对应文件 main.py 中的 handler 函数;
  • spec.runtime:声明 Python 运行时。示例中的 python:3.8 对应旧版镜像约定,新部署请使用 python:3.10 / python:3.11 / python:3.12;
  • spec.triggers.<name>:声明触发器。myHttpTrigger 定义了一个 HTTP 触发器,kind: "http" 表示类型,numWorkers: 1 表示该触发器使用 1 个 worker 进程(在 async 模式下,并发上限还受 maxConnectionsNumber 等参数影响,详见 async-mode.md)。

仓库中的函数示例配置可参考 hack/examples/python 下的各 function.yaml(例如 helloworld、encrypt、sentiments 等),测试用函数配置位于 test/_function_configs。


构建与执行(Build and Execution)

以下命令演示如何构建并运行最新版本的 my-function 函数,使其监听在 8090 端口。可根据需要替换函数名与对外发布端口:

docker build --tag my-function:latest .

docker run \
  --rm \
  --detach \
  --volume /path/to/function.yaml:/etc/nuclio/config/processor/processor.yaml \
  --name my-function \
  --publish 8090:8080 \
  my-function:latest

命令要点:

  • docker build 在包含 Dockerfile 与函数源码的目录中构建镜像;
  • docker run 启动容器,其中 --volume 把宿主机上的函数配置 function.yaml 挂载到容器内处理器的默认配置路径 /etc/nuclio/config/processor/processor.yaml(处理器启动时会读取该文件获取 handler、runtime、triggers 等设置);
  • --publish 8090:8080 将容器内处理器的 8080 端口映射到宿主机的 8090 端口,之后即可通过 http://localhost:8090 调用该函数。

可移植执行(Portable Execution)

如果已经把函数配置(即 function.yaml)烘焙进函数容器镜像,则运行时无需再挂载配置文件,只需在容器启动命令中显式覆盖函数配置路径即可,例如:

docker run \
  --rm \
  --detach \
  --name my-function \
  --publish 8090:8080 \
  my-function:latest \
  processor --config /opt/nuclio/function.yaml

如上所示,把镜像的默认命令 processor 替换为带 --config /opt/nuclio/function.yaml 参数的形式,处理器就会从镜像内部的该路径读取函数配置。这样一来,可以一次构建、任意多次部署,无需在每次部署时都挂载函数配置,显著提升了镜像的移植性与部署的可重复性。


终止回调(Termination Callback)

终止回调(Termination Callback)目前是 Python 运行时独有的特性,它允许用户代码注册一个在处理器即将退出时被调用的回调函数,从而实现优雅停机(graceful shutdown)。注册方式如下:

context.platform.set_termination_callback(callback)  # 其中 'callback' 是用户自定义的函数

底层实现机制

从源码看,终止流程由 Go 处理器通过向 wrapper 进程发送 SIGUSR1 信号触发,见 runtime.go 的 Terminate() 方法;wrapper 侧在 wrapper_common.py 中定义了信号常量(termination_signal = signal.SIGUSR1),并在事件循环中注册信号处理器(_register_to_signal)。收到 SIGUSR1 后,wrapper 会:

  1. 置位终止标记并停止接收新事件(_discard_events = True),见 _on_termination_signal;
  2. 在事件处理循环的 finally 块中调用用户注册的终止回调(_call_termination_handler),且同步与异步回调(返回 coroutine)均被支持,见 _nuclio_wrapper.py 与 wrapper_common.py。

终止回调通常注册在 init_context 中。仓库的 Kubernetes 平台集成测试 function_test.go(TestProcessorShutdown)完整验证了这一流程:测试函数在 init_context 中通过 context.platform.set_termination_callback(callback) 注册回调,回调内 time.sleep(3) 模拟耗时清理;随后测试持续向函数发送请求,并删除 Pod 触发处理器退出,最终断言日志中出现 "Stopping HTTP trigger" 与 "All triggers are terminated",证明退出过程中事件处理被有序终止、回调被正确执行。

流触发器的 Drain 回调

此外,对于流式触发器(stream triggers),还提供了 drain callback 选项:在消费者组重平衡(rebalance)等场景中,可通过以下方式注册一个无参回调,在 worker 被 drain(排空)之前执行清理动作(例如提交正在处理的事件偏移量):

context.platform.set_drain_callback(callback)

该机制用于防止同一消息被重复处理,详细说明(含可配置超时 WaitExplicitAckDuringRebalanceTimeout 及注解 nuclio.io/wait-explicit-ack-during-rebalance-timeout)请参阅 Kafka 触发器参考文档。与之配套的信号是 SIGUSR2(drain)与 SIGCONT(恢复处理),实现见 runtime.go 与 wrapper_common.py,wrapper 在 drain 完成后会通过控制 socket 向处理器发送 drain-complete 确认消息,使处理器无需等待固定超时即可继续重平衡流程。


小结

Nuclio 的 Python 运行时由 Go 处理器进程与 Python wrapper(shim)协作构成:处理器负责触发器接入与事件分发,wrapper 负责加载用户 Handler、反序列化事件(msgpack)、调用入口函数并把结果编码回传。围绕这一架构,本文覆盖了从 Handler 编写(<package>:<entrypoint> 规范、async def 异步模式、init_context 钩子)、镜像构建(多阶段 Dockerfile、依赖安装、健康检查)、版本选型(3.10/3.11/3.12 与 EOL 迁移策略)、事件解码行为(NUCLIO_PYTHON_DECODE_EVENT_STRINGS)、函数配置(YAML 字段)到构建运行与可移植执行(--config 覆盖配置路径),以及终止回调与 drain 回调等生命周期钩子的完整实践路径。你可以以此为基础,在 docs/reference/runtimes/python 与 pkg/processor/runtime/python 中继续深入探索各触发器的专属配置与 wrapper 实现细节。

登录后查看全文
nuclio