Coolify 架构实践从 app/Actions 到并发锁——Laravel 架构最佳在真实 PaaS 项目中的落地【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify本文以 Coolify 仓库中的 架构最佳实践文档 为主体系统讲解八条 Laravel 架构准则单一职责的 Action 类、构造器依赖注入、面向接口编程、默认降序排序、原子锁防竞态、多字节字符串函数、defer()后置任务与Concurrency::run()并行执行。读完之后你将掌握每条准则的正确/错误写法对照并能在 Coolify 这样体量较大的自托管 PaaSLaravel 12 项目源码中找到与之对应的真实实现作为参照。八条准则总览原文档 architecture.md 给出的八条准则可以概括为三个层次层次准则解决的问题结构单一职责 Action 类、依赖注入、面向接口业务逻辑分散、难以测试数据访问默认降序排序、原子锁结果不确定、并发竞态运行期细节mb_*函数、defer()、Context、Concurrency::run()多字节编码错误、任务调度开销、请求作用域数据传递以下逐条展开并结合 Coolify 源码印证这些准则在真实项目中的形态。准则一单一职责的 Action 类原文档要求把离散的業務操作抽取为可调用invokableAction 类核心示例class CreateOrderAction { public function __construct(private InventoryService $inventory) {} public function execute(array $data): Order { $order Order::create($data); $this-inventory-reserve($order); return $order; } }关键思想是一个类只做一件事——创建订单并锁定库存这一完整业务动作封装进一个类而不是散落在 Controller 的某个方法里。这样该动作可以在 HTTP 请求、队列任务、CLI 命令中被复用且可以独立测试。Coolify 是这一准则的大规模实践者。整个 app/Actions 目录就是按业务域组织的 Action 层包含 70 余个 Action 类例如app/Actions/DatabaseStartRedis、StartPostgresql、StopDatabase、StartDatabaseProxy等 13 个每个负责一类数据库资源的一种操作app/Actions/ServerValidateServer、InstallDocker、StartSentinel、DeleteServer等 16 个覆盖服务器生命周期app/Actions/ServiceStartService、RestartService、DeleteService等管理服务Docker Compose 资源app/Actions/StripeCancelSubscription、RefundSubscription、SyncStripeSubscriptions等订阅操作。以 StartRedis 为例可以看到典型形态类通过handle(StandaloneRedis $database)方法接收单一类型的模型参数第 23 行内部只干一件事——生成启动该 Redis 实例所需的远程命令序列包括创建配置目录、按enable_ssl开关处理 SSL 证书等分支。类里还声明了$commands数组属性最终供外部执行。项目通过 lorisleiva/laravel-actions 包的AsActiontrait 让这类类同时支持app(StartRedis::class)-execute($db)与$db直接调用的两种方式。从源码结构看这种一个操作一个类的命名与分层使得在 app/Http/Controllers 与 app/Jobs 中都能以相同方式调用同一业务动作避免了业务逻辑在多处复制。准则二依赖注入避免在类内app()/resolve()原文档给出的对照错误写法——在方法体内手工解析容器class OrderController extends Controller { public function store(StoreOrderRequest $request) { $service app(OrderService::class); return $service-create($request-validated()); } }正确写法——构造器注入class OrderController extends Controller { public function __construct(private OrderService $service) {} public function store(StoreOrderRequest $request) { return $this-service-create($request-validated()); } }构造器注入的价值在于依赖关系在类的签名上显式可见测试时可以轻松替换为 mock且不存在隐藏的解析时机问题。Coolify 的服务提供者中可以看到容器绑定的真实用法。例如 AppServiceProvider 中$this-app-bind(StripeClient::class, fn () new StripeClient(config(subscription.stripe_api_key)));HorizonServiceProvider 中则将 Horizon 的JobRepository契约绑定到自定义实现$this-app-singleton(JobRepository::class, CustomJobRepository::class); $this-app-singleton(CustomJobRepositoryInterface::class, CustomJobRepository::class);其中 CustomJobRepository 实现了 CustomJobRepositoryInterface——契约app/Contracts接口 app/Repositories实现放在容器边界上正是下一条准则的注脚。准则三面向接口编程系统边界处原文档强调在系统边界支付网关、通知渠道、外部 API依赖契约而非具体类以获得可测试性与可替换性。错误依赖具体类class OrderService { public function __construct(private StripeGateway $gateway) {} }正确依赖接口interface PaymentGateway { public function charge(int $amount, string $customerId): PaymentResult; } class OrderService { public function __construct(private PaymentGateway $gateway) {} }并在 Service Provider 中完成绑定$this-app-bind(PaymentGateway::class, StripeGateway::class);Coolify 的对应实例就是上文提到的JobRepository绑定应用代码面向JobRepository契约编程实现可被 CustomJobRepository 替换而不触及调用方。同理CustomJobRepositoryInterface的存在说明项目把可替换实现这件事显式建模成了契约。这种模式在对接 Stripe、通知渠道app/Notifications/Channels 下有 12 种渠道实现等外部系统时尤其重要——边界处换实现的成本被压缩到一行绑定。准则四未显式指定顺序时默认按 id / created_at 降序原文档没有显式ORDER BY时行顺序是未定义的。错误$posts Post::paginate();正确$posts Post::latest()-paginate();Coolify 源码中大量列表查询遵循了这一习惯例如 Backup Index 页 中的-latest()链式调用第 37 行、Service/Heading 中取最近一次活动Activity::...-latest()-first()第 100 行、ScheduledJobDiagnostics 中诊断命令的-latest()第 84 行。对活动日志、备份执行记录这类时间线 UI而言latest()不仅保证顺序确定性也让最新一条在前成为默认语义无需前端再排序。准则五用原子锁防止竞态条件原文档给出两种手段Cache::lock(order-processing-.$order-id, 10)-block(5, function () use ($order) { $order-process(); }); // Or at query level $product Product::where(id, $id)-lockForUpdate()-first();Cache::lock()是应用层锁适合跨进程Web 进程 队列 worker互斥lockForUpdate()是数据库行锁SELECT ... FOR UPDATE适合事务内的并发更新。Coolify 中Cache::lock有多处真实用例SentinelControllershouldDispatchUpdate()方法里用Cache::lock($lockKey, 10)-block(5, ...)保护读取旧状态哈希 → 比较 → 写入新哈希这段复合操作。哨兵Sentinel状态推送是高频写端点若不加锁两次并发推送会互相覆盖判断结果代码还捕获LockTimeoutException优雅降级第 133 行。SshMultiplexingHelperSSH 连接复用的控制逻辑用Cache::lock防止同一连接被并发建立。AdminDeleteUser管理命令用 10 分钟锁保护删除流程防止重复执行。DeleteScheduledVolumeBackup删除卷备份前锁住对应备份任务防止备份作业与删除动作竞态锁超时设为timeout 300以覆盖任务实际执行时长。注意第 4 例的锁键通过VolumeBackupJob::lockKey($backup-id)生成——锁键的命名约定与任务一一对应是排查谁持锁时的关键。准则六优先使用mb_*多字节字符串函数原文档指出PHP 标准字符串函数按字节计数而mb_*系列按字符计数处理 UTF-8 时必须用后者若 Laravel 提供Str助手则优先用Str底层同样是多字节安全的。错误strlen(José); // 5 (bytes, not characters) strtolower(MÜNCHEN); // mÜnchen — fails on multibyte正确mb_strlen(José); // 4 (characters) mb_strtolower(MÜNCHEN); // münchen // Prefer Laravels Str helpers when available Str::length(José); // 4 Str::lower(MÜNCHEN); // münchenCoolify 源码遵循了这一准则典型场景是用户输入标签名、仓库路径的校验与比较HandlesTagsApimb_strlen($tagName) 2用于标签名长度校验第 88、133、153 行TagsControllermb_strlen($name) 2MatchesManualWebhookApplicationshash_equals(mb_strtolower($fullName), mb_strtolower($repositoryPath))——先做多字节安全的小写化再用hash_equals做时序安全比较两个细节都到位SummarizesDiffText用mb_strlen($value) self::SINGLE_LINE_LIMIT判断摘要行长度。这些位置如果误用strlen/strtolower含非 ASCII 字符的标签或仓库名就会出现校验错误甚至匹配失败。准则七用defer()处理响应后轻量工作原文档区分了两类响应后工作轻量、无需在进程崩溃后幸存的任务日志、统计、清理→ 用defer()回调在 HTTP 响应发出后、同一进程内执行没有队列开销必须跨进程存活、需要重试的工作 → 用队列 Job。错误给琐碎工作派 Jobdispatch(new LogPageView($page));正确同进程、响应后执行defer(fn () PageView::create([page_id $page-id, user_id auth()-id()]));适用前提defer()是 Laravel 11.23 引入的特性要求 PHP 8.3。Coolify 的 composer.json 声明laravel/framework: ^12.65.0满足该前提理论上可直接采用这一准则从当前源码检索结果看defer(尚未在app/中广泛使用——可以推断这类准则更多是作为后续重构与代码评审的基线。准则八Context与Concurrency::run()原文档还给出两项现代 Laravel 能力请求作用域数据用Contextfacade 传递——数据自动贯穿 middleware、controller、job、log且会自动传播到入队任务// In middleware Context::add(tenant_id, $request-header(X-Tenant-ID)); // Anywhere later — controllers, jobs, log context $tenantId Context::get(tenant_id);敏感数据用Context::addHidden()隐藏出日志上下文若数据绝不应离开当前进程则不要放进Context因为它会随 Job 传播。并行执行用Concurrency::run()——每个闭包在独立子进程中运行无需异步库且子进程内拥有完整的 Laravel 访问use Illuminate\Support\Facades\Concurrency; [$users, $orders] Concurrency::run([ fn () User::count(), fn () Order::where(status, pending)-count(), ]);适合彼此独立的数据库查询、API 调用或计算。Coolify 同样声明了 Laravel 12 依赖具备使用条件当前app/源码中尚未检索到这两项的既有用例属于可落地的改进方向而非现有行为。准则九约定优于配置原文档最后一条遵循 Laravel 约定不要无故覆盖默认值。错误冗余覆盖class Customer extends Model { protected $table Customer; protected $primaryKey customer_id; public function roles(): BelongsToMany { return $this-belongsToMany(Role::class, role_customer, customer_id, role_id); } }正确依赖约定class Customer extends Model { public function roles(): BelongsToMany { return $this-belongsToMany(Role::class); } }约定表名复数小写、主键id、关联表按字母序拼接让模型类保持最小化只有数据库 schema 历史包袱与约定不符时才显式声明且声明越少越好——每多一行覆盖就多一处将来迁移 schema 时的遗忘点。小结准则与 Coolify 源码对照准则原文档位置Coolify 中的对应证据单一职责 Action第 3 节app/Actions 全目录 70 类如 StartRedis依赖注入第 22 节AppServiceProvider 的构造器注入与容器绑定面向接口第 52 节CustomJobRepositoryInterface HorizonServiceProvider 的singleton绑定默认降序第 83 节Backup/Index.php 等处的-latest()原子锁第 97 节SentinelController 的Cache::lock(...)-block(5, ...)mb_*函数第 110 节MatchesManualWebhookApplications 的mb_strtolowerdefer()/Context/Concurrency第 130、146、160 节框架版本composer.json 中laravel/framework ^12.65.0已具备使用前提约定优于配置第 175 节app/Models 中大量模型不重写$table/$primaryKey这套准则的核心逻辑是一致的把隐式变显式——依赖显式注入、顺序显式声明、并发显式加锁、编码显式多字节安全——从而让一个 48 个控制器、100 个 Livewire 组件、70 个 Action 的 Laravel 项目如 Coolify在增长过程中保持可测试、可替换、可推理。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Coolify 架构实践：从 app/Actions 到并发锁——Laravel 架构最佳在真实 PaaS 项目中的落地
Coolify 架构实践从 app/Actions 到并发锁——Laravel 架构最佳在真实 PaaS 项目中的落地【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify本文以 Coolify 仓库中的 架构最佳实践文档 为主体系统讲解八条 Laravel 架构准则单一职责的 Action 类、构造器依赖注入、面向接口编程、默认降序排序、原子锁防竞态、多字节字符串函数、defer()后置任务与Concurrency::run()并行执行。读完之后你将掌握每条准则的正确/错误写法对照并能在 Coolify 这样体量较大的自托管 PaaSLaravel 12 项目源码中找到与之对应的真实实现作为参照。八条准则总览原文档 architecture.md 给出的八条准则可以概括为三个层次层次准则解决的问题结构单一职责 Action 类、依赖注入、面向接口业务逻辑分散、难以测试数据访问默认降序排序、原子锁结果不确定、并发竞态运行期细节mb_*函数、defer()、Context、Concurrency::run()多字节编码错误、任务调度开销、请求作用域数据传递以下逐条展开并结合 Coolify 源码印证这些准则在真实项目中的形态。准则一单一职责的 Action 类原文档要求把离散的業務操作抽取为可调用invokableAction 类核心示例class CreateOrderAction { public function __construct(private InventoryService $inventory) {} public function execute(array $data): Order { $order Order::create($data); $this-inventory-reserve($order); return $order; } }关键思想是一个类只做一件事——创建订单并锁定库存这一完整业务动作封装进一个类而不是散落在 Controller 的某个方法里。这样该动作可以在 HTTP 请求、队列任务、CLI 命令中被复用且可以独立测试。Coolify 是这一准则的大规模实践者。整个 app/Actions 目录就是按业务域组织的 Action 层包含 70 余个 Action 类例如app/Actions/DatabaseStartRedis、StartPostgresql、StopDatabase、StartDatabaseProxy等 13 个每个负责一类数据库资源的一种操作app/Actions/ServerValidateServer、InstallDocker、StartSentinel、DeleteServer等 16 个覆盖服务器生命周期app/Actions/ServiceStartService、RestartService、DeleteService等管理服务Docker Compose 资源app/Actions/StripeCancelSubscription、RefundSubscription、SyncStripeSubscriptions等订阅操作。以 StartRedis 为例可以看到典型形态类通过handle(StandaloneRedis $database)方法接收单一类型的模型参数第 23 行内部只干一件事——生成启动该 Redis 实例所需的远程命令序列包括创建配置目录、按enable_ssl开关处理 SSL 证书等分支。类里还声明了$commands数组属性最终供外部执行。项目通过 lorisleiva/laravel-actions 包的AsActiontrait 让这类类同时支持app(StartRedis::class)-execute($db)与$db直接调用的两种方式。从源码结构看这种一个操作一个类的命名与分层使得在 app/Http/Controllers 与 app/Jobs 中都能以相同方式调用同一业务动作避免了业务逻辑在多处复制。准则二依赖注入避免在类内app()/resolve()原文档给出的对照错误写法——在方法体内手工解析容器class OrderController extends Controller { public function store(StoreOrderRequest $request) { $service app(OrderService::class); return $service-create($request-validated()); } }正确写法——构造器注入class OrderController extends Controller { public function __construct(private OrderService $service) {} public function store(StoreOrderRequest $request) { return $this-service-create($request-validated()); } }构造器注入的价值在于依赖关系在类的签名上显式可见测试时可以轻松替换为 mock且不存在隐藏的解析时机问题。Coolify 的服务提供者中可以看到容器绑定的真实用法。例如 AppServiceProvider 中$this-app-bind(StripeClient::class, fn () new StripeClient(config(subscription.stripe_api_key)));HorizonServiceProvider 中则将 Horizon 的JobRepository契约绑定到自定义实现$this-app-singleton(JobRepository::class, CustomJobRepository::class); $this-app-singleton(CustomJobRepositoryInterface::class, CustomJobRepository::class);其中 CustomJobRepository 实现了 CustomJobRepositoryInterface——契约app/Contracts接口 app/Repositories实现放在容器边界上正是下一条准则的注脚。准则三面向接口编程系统边界处原文档强调在系统边界支付网关、通知渠道、外部 API依赖契约而非具体类以获得可测试性与可替换性。错误依赖具体类class OrderService { public function __construct(private StripeGateway $gateway) {} }正确依赖接口interface PaymentGateway { public function charge(int $amount, string $customerId): PaymentResult; } class OrderService { public function __construct(private PaymentGateway $gateway) {} }并在 Service Provider 中完成绑定$this-app-bind(PaymentGateway::class, StripeGateway::class);Coolify 的对应实例就是上文提到的JobRepository绑定应用代码面向JobRepository契约编程实现可被 CustomJobRepository 替换而不触及调用方。同理CustomJobRepositoryInterface的存在说明项目把可替换实现这件事显式建模成了契约。这种模式在对接 Stripe、通知渠道app/Notifications/Channels 下有 12 种渠道实现等外部系统时尤其重要——边界处换实现的成本被压缩到一行绑定。准则四未显式指定顺序时默认按 id / created_at 降序原文档没有显式ORDER BY时行顺序是未定义的。错误$posts Post::paginate();正确$posts Post::latest()-paginate();Coolify 源码中大量列表查询遵循了这一习惯例如 Backup Index 页 中的-latest()链式调用第 37 行、Service/Heading 中取最近一次活动Activity::...-latest()-first()第 100 行、ScheduledJobDiagnostics 中诊断命令的-latest()第 84 行。对活动日志、备份执行记录这类时间线 UI而言latest()不仅保证顺序确定性也让最新一条在前成为默认语义无需前端再排序。准则五用原子锁防止竞态条件原文档给出两种手段Cache::lock(order-processing-.$order-id, 10)-block(5, function () use ($order) { $order-process(); }); // Or at query level $product Product::where(id, $id)-lockForUpdate()-first();Cache::lock()是应用层锁适合跨进程Web 进程 队列 worker互斥lockForUpdate()是数据库行锁SELECT ... FOR UPDATE适合事务内的并发更新。Coolify 中Cache::lock有多处真实用例SentinelControllershouldDispatchUpdate()方法里用Cache::lock($lockKey, 10)-block(5, ...)保护读取旧状态哈希 → 比较 → 写入新哈希这段复合操作。哨兵Sentinel状态推送是高频写端点若不加锁两次并发推送会互相覆盖判断结果代码还捕获LockTimeoutException优雅降级第 133 行。SshMultiplexingHelperSSH 连接复用的控制逻辑用Cache::lock防止同一连接被并发建立。AdminDeleteUser管理命令用 10 分钟锁保护删除流程防止重复执行。DeleteScheduledVolumeBackup删除卷备份前锁住对应备份任务防止备份作业与删除动作竞态锁超时设为timeout 300以覆盖任务实际执行时长。注意第 4 例的锁键通过VolumeBackupJob::lockKey($backup-id)生成——锁键的命名约定与任务一一对应是排查谁持锁时的关键。准则六优先使用mb_*多字节字符串函数原文档指出PHP 标准字符串函数按字节计数而mb_*系列按字符计数处理 UTF-8 时必须用后者若 Laravel 提供Str助手则优先用Str底层同样是多字节安全的。错误strlen(José); // 5 (bytes, not characters) strtolower(MÜNCHEN); // mÜnchen — fails on multibyte正确mb_strlen(José); // 4 (characters) mb_strtolower(MÜNCHEN); // münchen // Prefer Laravels Str helpers when available Str::length(José); // 4 Str::lower(MÜNCHEN); // münchenCoolify 源码遵循了这一准则典型场景是用户输入标签名、仓库路径的校验与比较HandlesTagsApimb_strlen($tagName) 2用于标签名长度校验第 88、133、153 行TagsControllermb_strlen($name) 2MatchesManualWebhookApplicationshash_equals(mb_strtolower($fullName), mb_strtolower($repositoryPath))——先做多字节安全的小写化再用hash_equals做时序安全比较两个细节都到位SummarizesDiffText用mb_strlen($value) self::SINGLE_LINE_LIMIT判断摘要行长度。这些位置如果误用strlen/strtolower含非 ASCII 字符的标签或仓库名就会出现校验错误甚至匹配失败。准则七用defer()处理响应后轻量工作原文档区分了两类响应后工作轻量、无需在进程崩溃后幸存的任务日志、统计、清理→ 用defer()回调在 HTTP 响应发出后、同一进程内执行没有队列开销必须跨进程存活、需要重试的工作 → 用队列 Job。错误给琐碎工作派 Jobdispatch(new LogPageView($page));正确同进程、响应后执行defer(fn () PageView::create([page_id $page-id, user_id auth()-id()]));适用前提defer()是 Laravel 11.23 引入的特性要求 PHP 8.3。Coolify 的 composer.json 声明laravel/framework: ^12.65.0满足该前提理论上可直接采用这一准则从当前源码检索结果看defer(尚未在app/中广泛使用——可以推断这类准则更多是作为后续重构与代码评审的基线。准则八Context与Concurrency::run()原文档还给出两项现代 Laravel 能力请求作用域数据用Contextfacade 传递——数据自动贯穿 middleware、controller、job、log且会自动传播到入队任务// In middleware Context::add(tenant_id, $request-header(X-Tenant-ID)); // Anywhere later — controllers, jobs, log context $tenantId Context::get(tenant_id);敏感数据用Context::addHidden()隐藏出日志上下文若数据绝不应离开当前进程则不要放进Context因为它会随 Job 传播。并行执行用Concurrency::run()——每个闭包在独立子进程中运行无需异步库且子进程内拥有完整的 Laravel 访问use Illuminate\Support\Facades\Concurrency; [$users, $orders] Concurrency::run([ fn () User::count(), fn () Order::where(status, pending)-count(), ]);适合彼此独立的数据库查询、API 调用或计算。Coolify 同样声明了 Laravel 12 依赖具备使用条件当前app/源码中尚未检索到这两项的既有用例属于可落地的改进方向而非现有行为。准则九约定优于配置原文档最后一条遵循 Laravel 约定不要无故覆盖默认值。错误冗余覆盖class Customer extends Model { protected $table Customer; protected $primaryKey customer_id; public function roles(): BelongsToMany { return $this-belongsToMany(Role::class, role_customer, customer_id, role_id); } }正确依赖约定class Customer extends Model { public function roles(): BelongsToMany { return $this-belongsToMany(Role::class); } }约定表名复数小写、主键id、关联表按字母序拼接让模型类保持最小化只有数据库 schema 历史包袱与约定不符时才显式声明且声明越少越好——每多一行覆盖就多一处将来迁移 schema 时的遗忘点。小结准则与 Coolify 源码对照准则原文档位置Coolify 中的对应证据单一职责 Action第 3 节app/Actions 全目录 70 类如 StartRedis依赖注入第 22 节AppServiceProvider 的构造器注入与容器绑定面向接口第 52 节CustomJobRepositoryInterface HorizonServiceProvider 的singleton绑定默认降序第 83 节Backup/Index.php 等处的-latest()原子锁第 97 节SentinelController 的Cache::lock(...)-block(5, ...)mb_*函数第 110 节MatchesManualWebhookApplications 的mb_strtolowerdefer()/Context/Concurrency第 130、146、160 节框架版本composer.json 中laravel/framework ^12.65.0已具备使用前提约定优于配置第 175 节app/Models 中大量模型不重写$table/$primaryKey这套准则的核心逻辑是一致的把隐式变显式——依赖显式注入、顺序显式声明、并发显式加锁、编码显式多字节安全——从而让一个 48 个控制器、100 个 Livewire 组件、70 个 Action 的 Laravel 项目如 Coolify在增长过程中保持可测试、可替换、可推理。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
