后端【免费下载链接】passengerA fast and robust web server and application server for Ruby, Python and Node.js项目地址https://gitcode.com/gh_mirrors/pa/passenger点击查看免费下载本指南以 Passenger 仓库中的 src/agent/README.md 为骨架系统讲解 Passenger Agent 的整体架构它并非单一进程而是由一个可执行文件承载的多个协作部件组成。文中将逐一剖析 Watchdog守护进程、Core核心引擎、SpawnEnvSetupper、SystemMetrics、TempDirToucher 等组成部分的职责与内部机制并结合源码如 AgentMain.cpp、WatchdogMain.cpp、CoreMain.cpp给出可验证的实现细节。读完本文你将理解 Passenger Agent 的进程模型、崩溃恢复机制、应用进程孵化流程以及各部件之间通过实例目录与套接字进行的协作方式。Passenger Agent 是什么Passenger 是一个面向 Ruby、Python 与 Node.js 的 Web 服务器与应用服务器。它的核心运行时被称为Passenger Agent——一个单一的二进制可执行文件内部却由多个逻辑上独立的部分组成。src/agent/目录下每个子目录都对应其中一个部件的源码Watchdog守护进程Passenger 的主进程负责启动与监督 Core并在 Core 崩溃时重启它退出时执行全局清理Core核心承担绝大多数重活——解析请求、孵化应用进程、把请求转发给正确的进程、再把应用响应回传给 Web 服务器SpawnEnvSetupper被Core/SpawningKit/内部使用的工具用于在孵化应用进程前准备运行环境SystemMetrics展示 CPU、内存等系统指标的工具主要用于开发与调试SystemMetricsCollector.hTempDirToucher被 Passenger Standalone 内部使用通过持续刷新临时目录的时间戳防止临时目录被/tmp清理守护进程删除另有 ExecHelper、FileReadHelper 等辅助部件见 MainFunctions.h 中的入口声明。单一入口与子命令分发尽管 Agent 包含多个部件对外却只有一个入口。在 AgentMain.cpp 中main()函数先处理help/--help/-h再通过dispatchSubcommand()根据第一个参数分发给不同部件的入口函数PassengerAgent SUBCOMMAND [options...] Daemon subcommands: core, watchdog Utility subcommands: system-metrics, exec-helper, file-read-helper分发映射如下对应 AgentMain.cpp子命令入口函数职责watchdogwatchdogMain启动 Watchdog 守护进程corecoreMain启动 Core 核心引擎system-metricssystemMetricsMain输出系统指标temp-dir-touchertempDirToucherMain保持临时目录时间戳新鲜spawn-env-setupperspawnEnvSetupperMain设置孵化环境exec-helperexecHelperMain以指定用户执行程序file-read-helperfileReadHelperMain以受限权限读取文件此外还内置了test-binary子命令用于快速自检输出PASS。WatchdogPassenger 的主进程根据 src/agent/README.mdWatchdog 是 Passenger 的主进程main Passenger process。它的核心职责有三启动 Passenger Core监督 Core崩溃时自动重启退出时清理所有相关资源。生命周期从启动到退出watchdogMain()WatchdogMain.cpp的执行顺序完整展示了 Watchdog 的启动流程initializeBareEssentials()初始化日志、配置ConfigKit::Store、包装器注册表等基础设施并将PASSENGER_USE_FEEDBACK_FDtrue注入环境变量以便所有子 Agent 使用反馈管道maybeSetsid()/maybeDaemonize()成为会话领导进程防止 Web 服务器用killpg()误杀 Watchdog同时保证能用一次killpg()杀掉所有子进程必要时守护化到后台createPidFile()把自身 PID 写入--pid-file指定的文件默认退出时自动删除lowerPrivilege()若以 root 运行且指定了--user则通过initgroups()/setgid()/setuid()降权并同步更新USER/HOME/UID环境变量initializeWorkingObjects()创建实例目录instance directory、生成随机的管理员密码文件、设置核心与 API 服务器的监听地址initializeAgentWatchers()创建监督器当前只有CoreWatcher见 initializeAgentWatchersinitializeApiServer()启动自身的 API 服务器监听实例目录下的agents.s/watchdog_apiUnix 域套接字startAgents()→beginWatchingAgents()启动 Core 并开始监督reportStartupResult()通过反馈文件描述符FEEDBACK_FD或--report-file把实例信息JSON 格式汇报给 Web 服务器finalizeInstanceDir()对实例目录加锁并完成创建收尾进入waitForStarterProcessOrWatchers()阻塞等待 Web 服务器退出或某个被监督进程出错。崩溃恢复机制Watchdog 对子进程的监督由AgentWatcherAgentWatcher.h实现。每个被监督的 Agent 对应一个 watcher 线程其核心逻辑是一个waitpid()循环子进程以非零退出码退出或被信号杀死时记录警告并自动重启子进程以退出码 0退出时说明是 Web 服务器优雅关闭触发的Watchdog 也随之优雅退出若waitpid()返回ECHILD例如 Agent 正被 gdb 附着调试则回退到kill()轮询方式探测存活状态。关闭与清理Watchdog 收到SIGINT/SIGTERM或 Web 服务器通过反馈管道发送c字符后会执行以下清理逻辑优雅退出时cleanupAgentsInBackground()会fork()一个子进程在后台向所有 Agent 发送SIGTERM最多等待 30 秒超时则升级为SIGKILL随后销毁实例目录、向--cleanup-pidfile指定的 PID 发送SIGTERM、删除 PID 文件非优雅退出watcher 出错时forceAllAgentsShutdown()先发SIGTERM等待 1 秒后强制SIGKILL。OOM 保护Watchdog 本身内存占用极小但若被系统 OOM Killer 杀死整个 Passenger 实例将不可用。因此在 Linux 上initializeBareEssentials()会调用setOomScoreNeverKill()WatchdogMain.cpp以 root 运行时将自身 OOM score 写入/proc/self/oom_score_adj值为-1000或旧式/proc/self/oom_adj值为-17并记录旧值通过extraConfigToPassToSubAgents[oom_score]传递给子进程OOM score 会被子进程继承故需在各次fork()后恢复。Watchdog 命令行参数usage()WatchdogMain.cpp列出了完整参数。核心参数如下参数说明--passenger-root PATHPassenger 源码目录位置必需参数标记[A]自动传递给所有被监督的 Agent--BC/--begin-core-args、--EC/--end-core-args标记传给 Core 的参数段起止--BU/--begin-ust-router-args、--EU/--end-ust-router-args标记传给 UstRouter 的参数段起止该组件已不存在仅保留兼容--api-listen ADDRESSAPI 服务器监听地址tcp://IP:PORT或unix:PATH可多次指定上限SERVER_KIT_MAX_SERVER_ENDPOINTS - 1次--authorize [LEVEL:]USERNAME:PASSWORDFILE为 API 服务器配置认证账号LEVEL为readonly只读或full完整默认--instance-registry-dir实例注册目录默认系统临时目录--spawn-dir孵化握手目录默认系统临时目录--no-user-switching禁用用户切换支持[A]--default-user NAME用户切换开启时的默认应用用户默认DEFAULT_WEB_APP_USER--default-group NAME用户切换关闭时的默认应用组默认取默认用户主组--daemonize后台守护化--user NAME降权到指定用户--pid-file PATH写入 Watchdog PID退出时删除可用--no-delete-pid-file关闭--log-file PATH日志输出到文件--log-level LEVEL日志级别[A]--disable-log-prefix关闭应用日志的 App PID 前缀--report-file PATH初始化成功后以 JSON 格式向指定文件汇报实例信息--cleanup-pidfile PATH关闭时杀掉指定 PID 文件对应的进程--ctl NAMEVALUE设置自定义内部选项标记[A]的参数会自动传给所有被监督的 Agent除非在--BC ... --EC段内显式覆盖。例如passenger watchdog --passenger-root /opt/passenger \ --BC --listen tcp://127.0.0.1:4000 /webapps/foo实例目录与进程间通信Watchdog 在启动时通过InstanceDirectory创建实例目录其中存放lock实例目录锁文件flock排他锁防止多实例冲突watchdog.pid、core.pid各进程 PIDread_only_admin_password.txt、full_admin_password.txt随机生成的 API 管理员密码readonly/full两个权限级别见 initializeWorkingObjectsagents.s/core、agents.s/core_api、agents.s/watchdog_apiCore 控制器、Core API、Watchdog API 的 Unix 域套接字。Watchdog 通过fdPassingPassword随机 24 字符实现与子进程之间的文件描述符传递这是 Agent 之间传递监听套接字的关键机制。Core承担重活的请求处理引擎根据 src/agent/README.mdCore 承担了绝大多数重活解析请求parse requests孵化应用进程spawn application processes把请求转发给正确的进程forwards requests to the correct process把应用响应回传给 Web 服务器forwards application responses back to the web server。Core 的组成结构从 CoreMain.cpp 的WorkingObjects结构可以看到 Core 的核心依赖CoreMain.cppSpawningKit::Context应用进程孵化子系统ApplicationPool2::Context与Pool应用进程池负责进程复用与生命周期管理ServerKit::AcceptLoadBalancerController请求接入负载均衡器Controller继承自ServerKit::HttpServerController, Client见 Controller.h是 HTTP 请求处理的核心每个工作线程对应一个ThreadWorkingObjects含独立的BackgroundEventLoop、ServerKit::Context与ControllerSecurityUpdateChecker与TelemetryCollector安全更新检查与遥测收集。单应用模式Single App ModeCore 支持多应用模式与单应用模式两种运行方式CoreMain.cpp。在单应用模式下Core 可借助AppTypeDetector::Detector自动检测应用类型如 Rack、WSGI 等或由用户通过--app-type、--startup-file、--app-start-command显式指定--app-type与--app-start-command不允许同时设置。Core 与请求路径Controller使用ServerKit的 HTTP 服务器框架通过 libev/libuv 事件循环处理接入请求AcceptLoadBalancer负责在多个工作线程间分配连接。每个请求经解析后Core 会从ApplicationPool中取出或孵化一个应用进程通过预建立的套接字转发请求并把响应流回 Web 服务器。SpawningKit可靠的应用进程孵化子系统src/agent/Core/SpawningKit/目录是 Core 内部负责孵化 Web 应用进程的子系统其设计文档 SpawningKit/README.md 非常详尽。它要处理大量失败场景但对外提供简单可靠的接口调用方提供应用位置、语言、环境变量等参数SpawningKit 孵化进程、校验是否成功成功后返回描述进程的对象失败则抛出描述原因的异常。通用应用与 SpawningKit 增强应用通用应用generic applicationgenericApp true没有显式 SpawningKit 支持。调用方须提供启动命令SpawningKit 寻找空闲 TCP 端口并执行该命令然后通过端口 ping等待应用就绪失败时报告应用的 stdout/stderr 输出。SpawningKit 增强应用genericApp false应用通过wrapper包装器或手工改造获得 SpawningKit 支持可以使用 Unix 域套接字而非 TCP并提供 HTML 格式的失败反馈。例如 Ruby 应用通常通过 Passenger 自带的 Ruby wrapper 孵化wrapper 激活 Gemfile、加载应用、在 Unix 域套接字上启动轻量服务器并把套接字地址回报给 SpawningKit。Preloader 与预派生Pre-forking支持 fork 的语言C、MRI Ruby、CPython可以使用预派生技术先启动一个 preloader 进程再让 preloader fork 出实际处理请求的 worker 进程。利用操作系统写时复制CoW机制所有 worker 共享 preloader 已加载的库与应用代码既能显著降低内存占用又能把启动耗时从秒级降到毫秒级。Node.js、JRuby、Go 等不支持 fork 的语言则无法使用该技术。孵化旅程Spawning JourneySpawningKit 把一次孵化称为一次journey旅程其中HandshakePrepareHandshake/Prepare.h负责 fork 前的准备工作创建握手用的临时工作目录work directory、为通用应用寻找空闲端口、把孵化参数spawn arguments写入工作目录、在 fork 前预先计算好exec()所需的完整参数fork 后只能调用 async-signal-safe 代码。HandshakePerform负责 fork 后等待子进程就绪、并在失败时从工作目录与 stdout/stderr 推断原因。孵化分三条路线不带 preloader 直接孵化 workerSpawningKit 内执行 Preparation → Fork 子进程 → Handshake → Finish子进程侧依次执行 SpawnEnvSetupper--before→ 加载 OS shell → SpawnEnvSetupper--after→ 执行 wrapper → 加载应用 → 开始监听 → Finish启动 preloader与上面类似但最终以 preloader 模式加载应用并开始监听命令通过 preloader 孵化 workerSpawningKit 通过 Unix 域套接字向 preloader 发送一行 JSON 命令{ command: spawn, work_dir: /path-to-work-dir }preloader fork 出子进程后立即回复{ result: ok, pid: 1234 }或{ result: error, message: ... }随后双方继续握手。工作目录Work Directory工作目录通过PASSENGER_SPAWN_WORK_DIR环境变量传递给子进程其结构如下标记[P]的条目由 SpawningKit 准备阶段创建Work directory -- args.json [P] 孵化参数JSON -- args/ [P] 孵化参数每个参数一个文件方便无 JSON 解析器的进程如 Bash 读取 -- stdin [P] 仅经 preloader 孵化时worker 的标准输入 FIFO -- stdout_and_err [P] 仅经 preloader 孵化时worker 的标准输出/错误 FIFO -- response/ [P] | -- finish [P] wrapper 或增强应用写入 1成功/ 0失败告知就绪 | -- properties.json 应用回传的套接字信息 | -- error/ [P] category / summary / problem_description.txt|html / | | advanced_problem_details / solution_description.txt|html | -- steps/ [P] 旅程步骤状态state / begin_time|begin_time_monotonic / end_time|end_time_monotonic -- envdump/ [P] 环境信息envvars / ulimits / user_info / annotations/应用响应属性Application Response Propertieswrapper 或增强应用可在response/properties.json中回传监听套接字信息仅允许以下键字段说明sockets套接字数组每项含addresstcp://IP:PORT或unix:PATHUnix 套接字文件属主必须与应用进程一致、protocolhttp/sessionRuby/Python wrapper 与 Passenger 之间的类 SCGI 协议/preloader/ 其他自定义值、concurrency并发请求数0表示无限、accept_http_requests可选默认false为true的套接字必须使用http或session协议、description可选worker 进程至少需要一个accept_http_requests true的套接字Passenger 才会向它转发 HTTP 流量——这与套接字是否说 HTTP 协议无关例如 Passenger 用session协议向 Ruby/Python wrapper 转发流量。等待应用就绪的双重机制SpawningKit 同时启用两种等待机制任一成功即完成等待response/finishFIFO 被写入1表示成功0表示失败对通用应用或指定了空闲端口的应用等待端口可连通。错误报告Error Reporting孵化失败时生成SpawnException错误报告包含错误category内部错误 / 系统调用错误 / 文件系统错误 / I/O 错误、单行summary、HTML 格式的问题描述含面向初学者的高层描述与advanced problem details调试细节、HTML 格式的解决方案描述、辅助细节stdout/stderr 输出、ulimits、环境变量、UID/GID、CPU/RAM 系统指标以及旅程描述各步骤状态与耗时。SpawnException::what()提供终端/日志使用的纯文本形式stdout/stderr 较大时仅截取前 4KB 与后 4KB上限 8KB并在 HTML 页面中保留完整输出。子进程可通过response/error/与envdump/目录提供自己的问题/解决方案描述纯文本或 HTML 二选一来辅助生成报告。辅助部件逐一解析SpawnEnvSetupper孵化环境设置器SpawnEnvSetupperMain.cpp 实现了 README 中描述的工具。它是子进程孵化后执行的第一个程序主要工作包括切换当前工作目录到应用目录设置环境变量、ulimits 等切换进程 UID/GID。它从工作目录读取参数执行这些操作。之所以必须独立成程序是因为这些工作在fork()之后、exec()之前的进程内执行不安全该阶段只允许 async-signal-safe 代码不能分配内存或调用setenv()。它会在 OS shell 之前--before和之后--after各执行一次shell 可能任意修改环境因此--after阶段负责恢复调用方要求的环境环境变量、ulimits并把完整环境转储到工作目录以便故障排查。SystemMetrics系统指标查看工具SystemMetricsMain.cpp 用于展示 CPU、内存等系统指标主要功能实现在 src/cxx_supportlib/SystemTools/SystemMetricsCollector.h。该工具主要服务于开发与调试SystemMetricsCollector.h。其命令行选项包括选项说明--xml以 XML 格式输出--no-general/--no-cpu/--no-memory不显示对应类别指标--force-colors即使 stdout 不是 TTY 也输出彩色-w/--watch INTERVAL每隔 INTERVAL 秒重新输出--stdin每收到一行输入就重新输出直到 EOF与--watch互斥--no-exit-on-unexpected-error遇到意外错误时不退出SystemMetricsCollector.h按平台分派实现Linux 使用sys/sysinfo.h与/proc文件系统macOS 使用mach/mach.h与sysctlFreeBSD 使用sysctl与vm/vm_param.h。TempDirToucher临时目录保鲜器TempDirToucherMain.cpp 的职责是每 30 分钟刷新目录内所有条目的时间戳防止/tmp清理守护进程删除 Passenger Standalone 的临时目录。当 Standalone 以--daemonize模式启动时会向该工具传递--cleanup参数使其代为负责清理临时目录因为守护化后 Standalone 主进程尽快退出以节省内存无法再承担清理工作。ExecHelper 与 FileReadHelperExecHelperExecHelperMain.cpp以指定用户身份执行程序用于权限切换场景FileReadHelperFileReadHelperMain.cpp以受限权限读取文件。SharedAgent 专属共享代码与src/cxx_supportlib面向 Passenger 之外也可复用的通用库不同src/agent/Shared/下的代码是Passenger 专属的供各 Agent 部件共享。其结构包括Fundamentals/AbortHandler异常中止处理、InitializationAgent 初始化流程、Utils等基础设施ApiAccountUtils.hAPI 账号解析工具ApiServerUtils.hAPI 服务器公共工具ApplicationPoolApiKey.h应用进程池 API 密钥。例如 Watchdog 与 Core 都依赖Shared/Fundamentals/Initialization.h中的initializeAgent()来完成日志、配置与信号处理的统一初始化。整体协作关系一览一次完整的 Passenger 运行可以概括为以下协作链路Web 服务器Apache/nginx或 Standalone 启动PassengerAgent watchdogWatchdog 创建实例目录与 API 服务器启动PassengerAgent core并持续监督Core 启动事件循环与 Controller通过agents.s/core等套接字等待 Web 服务器接入Web 服务器把请求通过套接字交给 CoreCore 的 Controller 解析请求由 ApplicationPool 复用或经由 SpawningKit 孵化应用进程必要时使用 preloader 预派生SpawningKit 通过工作目录与 SpawnEnvSetupper 完成环境准备与握手确认应用就绪Core 把请求转发给应用进程并把响应回传给 Web 服务器任一部件的崩溃都由 Watchdog 捕获并自动重启Web 服务器退出时Watchdog 统一清理所有进程与临时资源。总结Passenger Agent 的设计核心是**“单一可执行文件 多进程协作 强监督”**Watchdog 作为主进程保证整个系统的存活与清理Core 专注请求处理与进程孵化SpawningKit 提供可靠、可诊断的孵化流程各辅助工具则各自解决权限、指标、临时目录等横切问题。理解这套进程模型与协作机制是深入调试 Passenger 运行问题、扩展其能力的起点。相关测试如 test/cxx 下的 Core 与 SpawningKit 测试可帮助你进一步验证本文描述的行为。赞分享后端【免费下载链接】passengerA fast and robust web server and application server for Ruby, Python and Node.js项目地址https://gitcode.com/gh_mirrors/pa/passenger点击查看免费下载相关推荐Woodpecker架构深度解析理解Server、Agent与CLI的协作机制Woodpecker架构深度解析理解Server、Agent与CLI的协作机制 Woodpecker是一个简单而强大的CI引擎具有出色的可扩展性。在这篇 WCI/CDDevOpsApache Mesos架构深度解析理解Master、Agent与Framework的高效协作机制Apache Mesos架构深度解析理解Master、Agent与Framework的高效协作机制 Apache Mesos是一个开源的集群管理平台能够将整云原生ik_llama.cpp 命令行推理工具 llama-cli 完全指南从快速上手到采样与性能调优ik_llama.cpp 命令行推理工具 llama cli 完全指南从快速上手到采样与性能调优 导读 本文以 examples/main/README.md网络安全应用安全云原生漏洞扫描上一篇Neovide macOS 打包指南使用 macos-builder 脚本一键生成 .app 与 .dmg 分发镜像下一篇komorebi 空工作区循环切换命令 cycle-empty-workspace 详解用法、判定逻辑与源码实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考