Download the PHP package kode/process without Composer

Kode Process

PHP 8.3+ 多进程编排内核 · 自研 Native 默认运行时 · Swoole / Workerman 可插拔 · 内置分布式集群能力

简介

Kode Process 是一个「进程编排内核 + 多运行时兼容层」：你只写一套 API，底层运行时由环境自动择优，也可显式切换，业务代码零改动——

• 默认自研 Native 运行时（纯 PHP、零扩展依赖、master-worker 多进程），装好即用，无需任何 C 扩展
• 装了 Swoole → 可显式接入（最快，全 C 实现，原生协程），业务代码一行不改
• 装了 Workerman → 纯 PHP 依赖，已写入 require，开箱即用，Linux 上 ext-event 加速

切换运行时（native / swoole / workerman）只需改一个参数，协议、连接 API、编排原语全部一致。

关于「自研 vs 兼容层」：v5.0.0 起自研 Native 运行时成为默认形态，并补齐分布式协调能力（服务发现、分布式锁、Leader 选举、负载均衡、分布式 ID、限流、集群 RPC）， 同时保留 Swoole / Workerman 作为可插拔的高性能运行时。详见 docs/cluster.md。

最低要求 PHP 8.3。若仍在 PHP 8.1 / 8.2 上运行，请使用旧版 ^2.9。

特性

安装

workerman/workerman 是纯 PHP 依赖、已写入 require，安装后即开箱可用；需要更高吞吐时再装 ext-swoole 即可自动择优到它。

快速开始

HTTP 服务器

WebSocket 服务器

TCP 服务器

Kode::serve() 内部调用 Runtime::auto() 选择最优运行时。若想显式指定：

事件与连接

运行时通过事件回调驱动业务，连接对象统一为 Kode\Process\Runtime\ConnectionInterface：

ConnectionInterface 提供与底层无关的操作：

能力探测

不同运行时的能力不同，请用 supports() 做优雅降级：

能力枚举见 Kode\Process\Runtime\Capability：协程、共享表、Task 工作进程、UDP、Unix Socket、 SSL、平滑重载、SO_REUSEPORT、WebSocket、定时器、异步 I/O。

运行时择优与自检

Kode::diagnose() 返回可用运行时、各自版本与优先级、当前事件循环驱动、共享表后端、并行能力 （是否 ZTS、是否可用、后端类型），以及集群后端（可用协调存储、已加入节点）； 在 Linux 且未安装 ext-event / ext-ev 时会给出安装建议 （Workerman 官方也推荐 Linux 用 event 循环）。

共享数据（零安装兜底）

跨进程共享数据，无需引入 Swoole / Workerman：

若应用已运行在 Swoole / Workerman 之上，可复用其共享表做兼容共存：

选型建议：能上 Swoole / Workerman 就优先用它们的表（成熟稳定、免维护）。 本库 SharedTable::auto() 是「不引入这两者时」的零安装、零依赖兜底。 详见 docs/global-data.md。

并发原语

分布式集群

v5.0.0 内置轻量分布式协调能力，覆盖单主机到多主机场景。所有原语通过统一的协调存储抽象（StoreInterface）驱动， 可零依赖使用包内 GlobalData 后端，或对接 Redis 实现跨主机协调：

集群后端如需跨主机复用 Redis：

详见 docs/cluster.md。

定时器

通过 Kode 门面一行注册定时器，底层复用 Kode\Process\Timer：

也支持 setTimeout / setInterval（JS 风格别名）与 pause / resume / getStatus 等， 详见 docs/timer.md。

多进程定时任务的重复执行问题与选型

⚠️ 关键认知：进程内的 Kode::cron() / Timer::cron() / Crontab 是「每进程一份」的静态注册表。 在 master-worker 多进程（或水平扩展多机）下，每个 worker 都会独立注册并触发同一表达式 —— 每个调度时刻会被 N 个 worker 重复执行 N 次，且某个 worker 崩溃即丢失其定时器。 多进程本身并不能解决这个问题，反而把它放大了：要让定时任务在集群内「至多执行一次」， 必须引入协调权威（分布式锁 / Leader 选举），或把活儿交给持久队列。

解法一：每任务分布式锁（推荐起步，零改造）

Kode::cronCluster() / ClusterCron::create() 用 Cluster::lock() 给每个表达式加一把互斥锁， 只有抢到锁的 worker 才执行 —— 多进程不再重复。存储后端自动择优（同机 file、跨机 redis）， 同机多进程开箱即可协调，无需任何外部依赖；跨主机先 Cluster::make('redis', ...) 即可。

协调存储不可用时守卫 fail-soft 退化为本地执行并告警（极端情况可能重复，与无协调同款行为）。 每次触发多出一次锁往返（file 后端约 0.07ms，见 benchmarks/cluster-cron-bench.php）。

解法二：Leader 选举（长任务 / 强 exactly-once）

任务耗时可能超过锁 TTL、或要求强一致时，用 Kode::tickCronOnLeader() 让整套 cron 只在选举胜出的 Leader 进程推进，天然 exactly-once：

解法三：用 Redis 队列承接「持久 / 可重试」的活儿

若任务是持久、可重试、崩溃不丢、需要背压/限速/失败重放的（发邮件、对账、下发）， 不要依赖进程内 cron/timer —— 它既不持久、崩溃即丢、多进程还重复。正确做法是让 cron 只负责 「产生消息」，真正的执行交给 Kode::queue()（Redis 后端），由队列保证投递语义：

一句话：定时「触发」用集群锁/选举去重；业务「执行」用 Redis 队列保持久。 两者互补，而非替代。

常驻进程运行器 (Daemon)

⚠️ 为什么不直接用 Kode\Process::start($config, $cb) 跑周期任务？ 官方 worker 池（WorkerProcess）的事件循环里 processTasks() 从不调用用户回调—— 回调只在外部 assignTask() 推任务时触发。所以 Process::start($config, fn()=>...) 传入的回调在 worker 里实际是空转，并不适合「每进程周期执行自定义任务」。要可靠地常驻跑任务，请用本运行器。

Kode::daemon() 只依赖两个原语——Process::fork()（多进程）+ Timer（周期/定时调度）—— 自建「监督进程 + N 个 worker 子进程」：worker 在独立事件循环里真正执行你的任务，监督进程负责 信号、回收僵尸、异常退出重生（带上限防 fork bomb）、优雅退出。完全不碰 Master/Worker 池。

daemon 文件（return 一个 Daemon 实例）配合 CLI 子命令管理生命周期：

与「多进程定时任务重复执行」的关系：Daemon 解决的是单机上 N 个 worker 各自可靠地周期跑任务； 若还要跨进程/跨机「同一时刻只跑一次」，仍用 Kode::cronCluster()（集群锁）或 Kode::tickCronOnLeader()（Leader 选举）去重，二者可叠加。详见 docs/daemon.md。

队列系统

队列由 kode/queue 提供，支持内存 / 同步 / Redis / 数据库多后端。详见 docs/queue.md。

信号、监控与进程内事件

信号处理器为单例，详见 docs/signal.md。

SSL/TLS

通过监听选项配置，随宿主运行时生效（需 ext-openssl）：

命令行工具

bin/kode 是便捷启动器，运行你提供的服务脚本（脚本内调用 Kode::serve(...)->start()）：

运行中的服务也可直接用信号控制：

文档

• 安装
• 快速开始
• 运行时兼容层（架构与 API）
• 事件循环（Reactor）
• 协议系统
• HTTP/2
• 共享数据
• 并行（多线程）
• 定时器
• 常驻进程运行器 (Daemon)
• 队列系统
• 信号管理
• 监控（进程 / 心跳 / 文件）
• 生产部署
• 分布式集群
• 压测数据

项目结构

测试

许可证

Apache License 2.0