Sanic Worker Manager 深入解析:多进程架构、共享上下文与自定义进程管理

原创2026-09-20 16:08:381,873 阅读
文章标签:后端Web框架

Sanic Worker Manager 深入解析:多进程架构、共享上下文与自定义进程管理

Worker Manager(工作进程管理器)是 Sanic 自 22.9 版本引入的核心多进程编排组件:它负责在单个主进程内创建、监控、重启和终止一个或多个工作进程,让开发环境(带自动重载)与生产环境(多工作进程)拥有一致的使用体验。读完本文,你将掌握 Sanic 的进程启动模型与 ack 确认机制、如何借助 shared_ctx 在 worker 之间共享 multiprocessing 对象、如何通过 app.m(multiplexer)与 Manager 交互,以及如何注册和管理自定义后台进程、启用 Inspector 与零停机重启。

本文面向进阶使用者,普通入门开发可先跳过。文档完整版见 manager.md。

总览:主进程、Manager 与 Worker 进程

当你运行 Sanic 时,主进程会实例化一个 WorkerManager,由它负责运行一个或多个 WorkerProcess。进程大体分为两类:

  • server 进程:真正对外提供 HTTP 服务的进程;
  • non-server 进程:例如自动重载器(auto-reloader)、Inspector 等辅助进程。

为了表述简洁,本指南统一用 "worker / worker process" 指代 server 进程,用 "Manager" 指代主进程中的 Worker Manager 实例。

从源码看,WorkerManager 维护两组 worker 字典:self.transient 与 self.durable,manage() 方法根据 transient 参数决定进程归入哪一组;构造函数还会为每个 server 进程调用 create_server() 预创建 worker,并注册 SIGINT / SIGTERM 信号处理(manager.py)。整个 Manager 的生命周期在 run() 中依次执行 start() → monitor() → join() → terminate() → cleanup()。

Sanic 如何启动进程

spawn 启动方式与 __main__ 保护

Sanic 默认使用 Python multiprocessing 的 spawn 启动方式创建进程。这意味着每个进程/worker 都会在各自的解释器里重新执行应用模块的全局作用域。实际影响是:如果不通过 CLI 运行 Sanic,就必须把执行代码嵌套在 __main__ 保护块内:

if __name__ == "__main__":
    app.run()

否则很可能看到如下错误:

sanic.exceptions.ServerError: Sanic server could not start: [Errno 98] Address already in use.

This may have happened if you are running Sanic in the global scope and not inside of a `if __name__ == "__main__"` block.

修复办法通常就是把 app.run() 放进 __name__ == "__main__" 块。如果嵌套之后仍报此错(或是在使用 CLI 时看到),说明端口确实被占用,需要换一个端口。

启动一个 worker:ack 确认机制

所有 worker 进程启动后必须向主进程发送一个 ack(acknowledge)消息,这个动作由框架在底层自动完成,开发者无需干预。但 Manager 在以下两种情况会以退出码 1 结束:

  • 有一个或多个 worker 没有发送 ack;
  • worker 进程在启动期间抛出异常。

如果没有异常,Manager 最多等待 30 秒等待确认。该超时阈值定义在 WorkerProcess.THRESHOLD = 300(单位为 0.1 秒,即 30 秒,见 process.py),WorkerManager.THRESHOLD 直接引用该值(manager.py)。

如果确实需要更长的启动时间,可以猴子补丁(monkeypatch)Manager 的阈值。注意该阈值不包含任何 listener 内的执行时间,只覆盖应用全局作用域的执行时长。若触发此问题,往往暗示应用启动过慢,值得深入排查:

from sanic.worker.manager import WorkerManager

WorkerManager.THRESHOLD = 100  # 单位是 0.1s,即 10 秒

同理,如果希望改用 fork 启动方式(仅 Unix),可以这样设置:

from sanic import Sanic

Sanic.start_method = "fork"

关于 ack 的具体实现:worker 启动完成后由 WorkerMultiplexer.ack() 把自身在共享状态中的 state 置为 ACKED(multiplexer.py);主进程侧的 wait_for_ack() 循环轮询共享状态,直到所有 server 进程都达到 ACKED(_all_workers_ack(),见 manager.py)。若某个 worker 在启动完成前就终止,会发送 __TERMINATE_EARLY__ 消息让 Manager 提前结束。

为什么需要 ack:防止死锁

所有 worker 都在子进程中运行时,潜在风险是死锁:子进程可能已停止工作,但主进程毫无感知。因此 Sanic server 在启动完成后会自动向主进程发送 ack 消息,主进程据此确认每个 worker 都已成功就绪。

  • 在 22.9 版本中,ack 超时较短,只有 5s;
  • 在 22.12 版本中,超时延长到 30s。

如果应用在 30 秒后关闭,可能需要手动调大该阈值。WorkerManager.THRESHOLD 以 0.1s 为增量,若要设置为 1 分钟,应设值为 600:

from sanic.worker.manager import WorkerManager

WorkerManager.THRESHOLD = 600

该值应尽早设置,理想情况下放在全局作用域;主进程启动之后再设置不会生效。

零停机重启(Zero Downtime Restarts)

默认情况下,Sanic 重启 worker 时先销毁现有进程,再启动新进程(对应 RestartOrder.SHUTDOWN_FIRST,见 constants.py)。

如果打算在生产环境使用重启功能,可能希望零停机重载:强制重载器改变顺序——先启动新进程、等待其发送 ack、再销毁旧进程。通过 multiplexer 使用 zero_downtime 参数:

app.m.restart(zero_downtime=True)

在 v22.12 中加入。

从源码看,restart(zero_downtime=True) 会在发送给主进程的消息尾部追加 :STARTUP_FIRST(multiplexer.py);Manager 收到后以 RestartOrder.STARTUP_FIRST 执行重启(manager.py)。对应地,process.py 中 STARTUP_FIRST 分支会先 spawn 并 start 新进程,再用后台线程等待新进程 ACKED 后终止旧进程(_wait_to_terminate)。

在工作进程之间共享上下文(shared_ctx)

Python 的 multiprocessing 与 ctypes 模块提供了多种进程间交换对象、同步与共享状态的方式。如果你熟悉这些对象,Sanic 提供了在工作进程间共享它们的 API:app.shared_ctx。它与应用上下文 app.ctx 类似,但专门用于存放上述进程安全对象。

shared_ctx 的边界非常明确:

  • 不会共享 int、dict、list 之类的普通对象;
  • 不会跨机器共享 Sanic 实例的状态;
  • 不会共享给非 worker 进程;
  • 只会在同一个 Manager 管理的 server worker 之间共享状态。

向 shared_ctx 挂载不合适的对象通常会得到一条警告而非报错。若你因为这类警告被引导到本文,很可能是不小心把不安全对象放进了 shared_ctx。底层实现中,SharedContext.__setattr__ 会检查对象所在模块是否以 multiprocessing 或 ctypes 开头,否则打印 "Unsafe object ... added to shared_ctx" 警告(shared_ctx.py)。

必须在主进程中、main_process_start listener 内创建共享对象并挂载:

from multiprocessing import Queue

@app.main_process_start
async def main_process_start(app):
    app.shared_ctx.queue = Queue()

在主进程启动后、或在其他位置往 shared_ctx 挂载对象,可能触发 RuntimeError(SharedContext 被 lock() 锁定后拒绝再写入)。创建并挂载到 shared_ctx 后,这些对象在所有 worker 中(listener、中间件、请求处理器等能拿到 app 实例的地方)都可用:

from multiprocessing import Queue

@app.get("")
async def handler(request):
    request.app.shared_ctx.queue.put(1)
    ...

正确用法是把耗时的 multiprocessing 原语实例化从全局作用域移到 listener 中:

# 这是 BAD:避免在全局作用域创建
from multiprocessing import Queue

q = Queue()
# 这是 GOOD:在 listener 中创建,并通过 shared_ctx 共享给所有进程
from multiprocessing import Queue

@app.main_process_start
async def main_process_start(app):
    app.shared_ctx.q = Queue()

访问 multiplexer(app.m)

应用实例上挂载了一个与 Manager 及其他 worker 交互的对象,即 app.multiplexer 属性,更常用的别名是 app.m。

例如,可以在请求处理器里获取当前 worker 的状态:

@app.on_request
async def print_state(request: Request):
    print(request.app.m.name)
    print(request.app.m.pid)
    print(request.app.m.state)
Sanic-Server-0-0
99999
{'server': True, 'state': 'ACKED', 'pid': 99999, 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), 'starts': 2, 'restart_at': datetime.datetime(2022, 10, 1, 0, 0, 12, 861332, tzinfo=datetime.timezone.utc)}

multiplexer 还可以终止 Manager 或重启 worker 进程:

# 关闭整个应用及所有进程
app.m.name.terminate()

# 只重启当前 worker
app.m.name.restart()

# 只重启指定 worker(逗号分隔)
app.m.name.restart("Sanic-Server-4-0,Sanic-Server-7-0")

# 重启所有 worker
app.m.name.restart(all_workers=True)  # 自 v22.12 起可用

从实现上看,WorkerMultiplexer 只在 worker 进程内实例化,它通过 monitor_publisher 连接与主进程的 monitor 通信:restart 会把目标进程名(必要时附加 STARTUP_FIRST 后缀)发送给主进程(multiplexer.py),主进程的 _handle_message 解析后交给 Restarter 执行。此外还有 scale()、terminate()、manage() 等方法,且 reload 是 restart 的别名。

Worker 状态(Worker State)

如上所示,multiplexer 能报告当前运行 worker 的状态,并且它包含所有进程的状态:

@app.on_request
async def print_state(request: Request):
    print(request.app.m.workers)
{
    'Sanic-Main': {'pid': 99997},
    'Sanic-Server-0-0': {
        'server': True,
        'state': 'ACKED',
        'pid': 9999,
        'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc),
        'starts': 2,
        'restart_at': datetime.datetime(2022, 10, 1, 0, 0, 12, 861332, tzinfo=datetime.timezone.utc)
    },
    'Sanic-Reloader-0': {
        'server': False,
        'state': 'STARTED',
        'pid': 99998,
        'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc),
        'starts': 1
    }
}

这些状态值定义在 constants.py 的 ProcessState 枚举中:

  • NONE —— worker 已创建,但还没有进程
  • IDLE —— 进程已创建,但尚未运行
  • STARTING —— 进程正在启动
  • STARTED —— 进程已启动
  • ACKED —— 进程已启动并发送确认(通常只针对 server 进程)
  • JOINED —— 进程已退出并 join 到主进程
  • TERMINATED —— 进程已退出并终止
  • RESTARTING —— 进程正在重启
  • FAILED —— 进程遇到异常且不再运行
  • COMPLETED —— 进程已完成工作并成功退出

状态存储在主进程的 sync_manager.dict() 共享字典中,Manager 的 _sync_states() 会周期性同步各进程状态;进程以非零退出码结束时状态被标记为 FAILED,否则为 COMPLETED(manager.py)。通过 WorkerState(state.py)可以按 key 读写当前 worker 的额外状态,其中 health、pid、requests、state 等属于受保护 key,不可覆盖。

内置的非 server 进程

Manager 除了 server 进程,还能运行非 server 进程。Sanic 内置两类,并支持创建自定义进程:

  • 自动重载器(auto-reloader):可选启用,监控文件系统变化并触发重启,详见 development.md;
  • Inspector:可选启用,提供对运行实例状态的外部访问。

在 serve 的组装逻辑里,当满足 should_auto_reload() 时会把 Reloader 注册为 durable 进程,INSPECTOR=True 时把 Inspector 注册为 durable 进程(startup.py)。

Inspector

Sanic 可以把 multiplexer 的状态与功能暴露给 CLI,方便运维时从命令行查看和操控运行中的实例。当前要求 CLI 命令与 Sanic 实例运行在同一台机器上,且 Inspector 默认关闭。

开启方式:把配置值设为 True。

app.config.INSPECTOR = True

之后即可执行以下 CLI 命令:

sanic inspect reload                      Trigger a reload of the server workers
sanic inspect shutdown                    Shutdown the application and all processes
sanic inspect scale N                     Scale the number of workers to N
sanic inspect <custom>                    Run a custom command

其工作原理是在本机暴露一个小型 HTTP 服务,可用配置控制监听位置:

app.config.INSPECTOR_HOST =  "localhost"
app.config.INSPECTOR_PORT =  6457

相关配置的默认值定义在 config.py:INSPECTOR=False、INSPECTOR_HOST="localhost"、INSPECTOR_PORT=6457,另外还有可选的 INSPECTOR_TLS_KEY、INSPECTOR_TLS_CERT 与 INSPECTOR_API_KEY(用于鉴权)。从源码看,Inspector 自身是一个以 single_process=True 运行的小型 Sanic 应用,提供 GET /(信息)与 POST /<action>(操作)两个端点(inspector.py)。更多能力参见 inspector.md。

运行自定义进程

要在 Sanic 中托管自定义进程,必须创建一个 callable。如果该进程是长时间运行的,它应当通过捕获 SIGINT 或 SIGTERM 信号来处理关闭请求。Python 中最简单的做法是用 KeyboardInterrupt 包裹循环:

from time import sleep

def my_process(foo):
    try:
        while True:
            sleep(1)
    except KeyboardInterrupt:
        print("done")

如果你要运行的是其他应用(比如机器人),它多半已经具备信号处理能力,通常无需额外处理。

该 callable 必须在 main_process_ready listener 中注册。特别注意:这与注册 shared_ctx 对象的 main_process_start 不是同一个位置:

@app.main_process_ready
async def ready(app: Sanic, _):
#   app.manager.manage(<name>, <callable>, <kwargs>)
    app.manager.manage("MyProcess", my_process, {"foo": "bar"})

manage() 的完整签名与参数含义见 manager.py:name(进程名)、func(后台进程要执行的函数)、kwargs(传给函数的参数)、transient、restartable、tracked、auto_start、workers(进程数量,默认 1)、ident。同名 worker 重复注册会抛出 ValueError。

临时(transient)与持久(durable)进程

用 manage 托管进程时,可以决定它是 transient 还是 durable:

  • transient 进程会随自动重载器一起重启;
  • durable 进程不会。

默认情况下所有进程都是 durable(transient=False)。

@app.main_process_ready
async def ready(app: Sanic, _):
    app.manager.manage(
        "MyProcess",
        my_process,
        {"foo": "bar"},
        transient=True,
    )

从源码结构看,manage() 会按 transient 把 worker 放入 self.transient 或 self.durable;自动重载触发的全局重启只作用于 transient 进程,而 durable 进程只有显式点名时才会重启(restarter.py)。

被跟踪(tracked)与不被跟踪(untracked)的进程

默认情况下,Sanic 会跟踪所有进程的状态,因此可以从 multiplexer 或 Inspector 查看进程状态,详见 Worker 状态。

有时运行一些非长驻的后台进程很有用:它们运行一次直到完成然后退出,结束后处于 FAILED 或 COMPLETED 状态。对于这类进程,可以在 manage 中设置 tracked=False 来放弃跟踪,进程完成之后会从跟踪列表中移除,你只能在进程运行期间查询其状态:

@app.main_process_ready
async def ready(app: Sanic, _):
    app.manager.manage(
        "OneAndDone",
        do_once,
        {},
        tracked=False,
    )

在 v23.12 中加入。 对应地,Manager 的 _cleanup_non_tracked_workers() 会周期性地把"不被跟踪且没有存活进程"的 worker 从 transient / durable 字典中移除(manager.py)。

可手动重启的自定义进程

transient 自定义进程始终可重启,自动重启因此也能正常工作。但如果你希望进程可以手动重启、却不要被自动重载器重启,可以在 manage 中设置 restartable=True:

@app.main_process_ready
async def ready(app: Sanic, _):
    app.manager.manage(
        "MyProcess",
        my_process,
        {"foo": "bar"},
        restartable=True,
    )

之后即可从 multiplexer 手动重启该进程:

@app.get("/restart")
async def restart_handler(request: Request):
    request.app.m.restart("Sanic-MyProcess-0")
    return json({"foo": request.app.m.name})

在 v23.12 中加入。 注意 manage 的实现里 restartable 默认跟随 transient,且不允许"transient 却不可重启"的组合(会抛 ValueError,见 manager.py);durable 进程要能被点名重启,必须显式设置 restartable=True。

运行中动态添加进程

自定义进程通常在 main_process_ready listener 中添加,但有时需要在应用启动后添加进程(例如从请求处理器中)。multiplexer 提供了相应方法:拿到 multiplexer 引用后调用 manage 即可,用法与 Manager 上的 manage 一致:

@app.post("/start")
async def start_handler(request: Request):
    request.app.m.manage(
        "MyProcess",
        my_process,
        {"foo": "bar"},
        workers=2,
    )
    return json({"foo": request.app.m.name})

在 v23.12 中加入。 其实现是把参数打包成 8 元组发送给主进程,由主进程 _handle_manage 调用真正的 WorkerManager.manage 并启动对应数量的进程(multiplexer.py、manager.py)。

单进程模式

如果希望退出多进程,可以只以单进程运行 Sanic。此时 Manager 不会运行,任何依赖进程的功能(自动重载、Inspector 等)也都不可用:

sanic path.to.server:app --single-process
if __name__ == "__main__":
    app.run(single_process=True)
if __name__ == "__main__":
    app.prepare(single_process=True)
    Sanic.serve_single()

从源码看,serve_single() 会禁用 fast、workers、multiplexer、auto_reload 与 Inspector 等特性(startup.py),CLI 的 --single-process 参数定义在 arguments.py。另外,若 single_process 与 fast / workers>1 / auto_reload 同时使用会抛出 RuntimeError(startup.py)。

Sanic 与 multiprocessing

Sanic 重度依赖标准库 multiprocessing 模块来管理工作进程。一般应避免直接做底层操作(例如自行设置 start method),以免干扰 Sanic 的功能。

Python 的 start methods

先理解 start_method 是什么、为什么重要。Python 一般提供三种进程启动方式:

  • fork
  • spawn
  • forkserver

其中 fork 和 forkserver 仅在 Unix 系统可用,spawn 是 Windows 上唯一的方式。在 Unix 上,fork 通常是系统默认。

关键区别:fork 基本是把父进程的整个内存拷贝给子进程,而 spawn 会创建新进程然后把应用加载进去——这正是不使用 CLI 时必须把 app.run() 嵌套在 __name__ == "__main__" 块内的原因。

Sanic 与 start methods

默认情况下 Sanic 会尝试使用 spawn,因为它是 Windows 上唯一的选择,也是 Unix 上最安全的方式。如果在 Unix 上想改用 fork,可以尽早(理想情况是在导入其他模块之前的全局作用域)设置 Sanic 类上的 start_method:

from sanic import Sanic

Sanic.start_method = "fork"

从源码看,spawn 也是默认的 multiprocessing 上下文来源(cls._get_context() 被传入 WorkerManager,见 startup.py),确保跨平台一致性。

处理 RuntimeError

你可能会遇到这样的 RuntimeError:

RuntimeError: Start method 'spawn' was requested, but 'fork' was already set.

这意味着应用某处设置的 start method 与 Sanic 的目标冲突。有三种解决选项:

选项 1: 告诉 Sanic start method 已设置,不要再尝试设置:

from sanic import Sanic

Sanic.START_METHOD_SET = True

选项 2: 告诉 Sanic 你打算用 fork,不要试图改成 spawn:

from sanic import Sanic

Sanic.start_method = "fork"

选项 3: 直接用 multiprocessing 设置 start method 为 spawn:

import multiprocessing

multiprocessing.set_start_method("spawn")

无论选哪种,都应在应用尽可能早的位置执行;视具体情况可能需要组合多个选项。

一个更省心的建议:让 Sanic 来管理 multiprocessing 通常能直接规避这类问题——也就是利用 main_process_start 与 main_process_ready listener 处理多进程问题。例如,把在全局作用域做大量底层工作的 multiprocessing 原语实例化移进 listener:

# 这是 BAD;避免全局作用域
from multiprocessing import Queue

q = Queue()
# 这是 GOOD;队列在 listener 中创建并通过 shared_ctx 共享
from multiprocessing import Queue

@app.main_process_start
async def main_process_start(app):
    app.shared_ctx.q = Queue()

小结

Sanic 的 Worker Manager 把开发与生产的进程管理统一到了同一套模型之下:spawn 启动 + ack 心跳确认避免死锁、shared_ctx 共享进程安全对象、app.m 提供运行时交互入口、Inspector 提供外部 CLI 访问、manage() 支持托管任意自定义后台进程(transient/durable、tracked/untracked、restartable、动态添加)。理解这些机制后,无论你是要调试多进程下的启动问题、实现零停机发布,还是把后台任务纳入 Sanic 的统一生命周期管理,都能找到对应的正确姿势。相关测试用例(如 test_manager.py、test_inspector.py)也可作为进一步研究底层行为的参考。

登录后查看全文
sanic