企业官网建设流程全解析

• DevOps
• CI/CD
• CLI
• 开发工具
• 运维

本指南讲解如何在 Deployer 中引入codeigniter4recipe，将 CodeIgniter 4 应用以零停机、可回滚的方式部署到服务器，并自动完成依赖安装、.env配置、目录权限、生产优化与数据库迁移。读完本文你将掌握 CodeIgniter 4 部署所需的全部配置项、内置 spark 任务链、自定义 spark 命令的调用方式，以及底层源码级的工作原理。

CodeIgniter 4 部署的核心特性

Deployer 是一个用 PHP 编写的免费开源部署工具，recipe/codeigniter4.php是官方为 CodeIgniter 4 应用定制的部署配方（recipe）。使用该配方，只需一行require即可获得完整的部署能力：

require 'recipe/codeigniter4.php';

该配方为 CodeIgniter 4 应用带来三大核心能力：

• Provisioning（服务器供给）：可直接对服务器进行初始化配置（需配合 provision recipe 使用）；
• Zero downtime deployment（零停机部署）：通过"新版本发布目录 + 原子切换 symlink"的方式切换流量，部署期间服务不中断；
• Rollbacks（回滚）：若发布出错，可一键回滚到上一个可用版本。

除此之外，Deployer 本身还具备：简单直观的 DSL 语法、基于并行 SSH 连接的高执行速度、全程通过 SSH 的安全通道，以及对主流 PHP 框架的开箱即用支持。

部署前建议先阅读 Getting Started 完成 Deployer 的安装与项目初始化（dep init），并参考 installation.md 确认运行环境要求。

快速开始：初始化 CodeIgniter 4 部署

在 CodeIgniter 4 项目根目录执行dep init并按提示选择codeigniter4recipe 后，deploy.php的核心结构如下：

<?php namespace Deployer; require 'recipe/codeigniter4.php'; // 主机定义 host('example.org') ->set('remote_user', 'deployer') // SSH 用户名 ->set('deploy_path', '~/example'); // 服务器上的部署根目录（必填） // 代码仓库 set('repository', 'git@github.com:you/codeigniter4-app.git'); // 部署 task('deploy', [ 'deploy:prepare', 'deploy:vendors', 'spark:optimize', 'spark:migrate', 'deploy:publish', ]);

其中deploy_path是必填项，未设置时会在部署时抛出ConfigurationException（见 recipe/common.php 中set('deploy_path', ...)的默认抛错逻辑）。随后执行：

dep deploy

即可一键部署。若需要从某个环节继续，可配合--start-from选项，例如dep deploy --start-from deploy:migrate。

deploy 主任务：完整流程拆解

recipe/codeigniter4.php中的deploy任务（源码见 recipe/codeigniter4.php）是一个组任务（group task），按顺序包含五个阶段：

deploy:prepare → deploy:vendors → spark:optimize → spark:migrate → deploy:publish

各阶段职责如下：

阶段一：deploy:prepare（准备新版本）

来自 common recipe，本身也是组任务，展开后包含 8 个子任务：

1. deploy:info—— 展示本次部署相关信息（主机、仓库、分支等），见 docs/recipe/deploy/info.md；
2. deploy:setup—— 在服务器上创建deploy_path目录骨架，见 docs/recipe/deploy/setup.md；
3. deploy:lock—— 获取部署锁，防止并发部署互相覆盖，见 docs/recipe/deploy/lock.md；
4. deploy:release—— 生成新的 release 编号并创建发布目录，见 docs/recipe/deploy/release.md；
5. deploy:update_code—— 通过 git 拉取指定分支/提交到 release 目录，见 docs/recipe/deploy/update_code.md；
6. deploy:env—— 配置.env文件：若 release 目录中不存在.env而存在{{dotenv_example}}（默认.env.example），则复制一份（实现见 recipe/deploy/env.php）；
7. deploy:shared—— 为共享目录/文件创建符号链接（见下文"共享与权限配置"）；
8. deploy:writable—— 设置可写目录权限（见下文）。

阶段二：deploy:vendors（安装依赖）

执行 Composer 安装依赖。默认动作为install，默认选项为--verbose --prefer-dist --no-progress --no-interaction --no-dev --optimize-autoloader（见 recipe/deploy/vendors.php），即生产环境安装、跳过 dev 依赖并优化自动加载。若服务器上找不到 Composer，Deployer 会自动将 Composer 安装到{{deploy_path}}/.dep/composer.phar。

阶段三：spark:optimize（生产优化）

执行 CodeIgniter 4 的spark optimize命令，对应用进行生产环境优化（配置缓存、路由缓存等），仅在 CodeIgniter 4.5.0 及以上版本可用（源码中通过'min' => '4.5.0'限制）。

阶段四：spark:migrate（数据库迁移）

执行spark migrate --all运行所有未执行过的数据库迁移，并带有skipIfNoEnv保护：若.env文件缺失或为空，则跳过并给出警告而非中断部署。

阶段五：deploy:publish（发布版本）

来自 common recipe，展开后包含 4 个子任务：

1. deploy:symlink—— 将current符号链接原子切换到新 release，实现零停机切换，见 docs/recipe/deploy/symlink.md；
2. deploy:unlock—— 释放部署锁，见 docs/recipe/deploy/lock.md；
3. deploy:cleanup—— 按keep_releases（默认 10）清理过期 release，见 docs/recipe/deploy/cleanup.md；
4. deploy:success—— 输出成功信息。

配置项详解

codeigniter4recipe 定义（或覆盖）了以下配置参数，全部可在deploy.php中用set()二次覆盖。

public_path

Web 服务器文档根目录（相对于 release 目录），覆盖自 provision/website 配方：

set('public_path', 'public');

CodeIgniter 4 的入口文件位于public/目录，部署后 Web 服务器（如 Nginx）应将root指向current/public：

root /home/deployer/example/current/public; index index.php; location / { try_files $uri $uri/ /index.php?$query_string; }

shared_dirs（共享目录）

set('shared_dirs', ['writable']);

writable/目录存放 CodeIgniter 4 的运行时文件（缓存、日志、会话、上传等），必须在各 release 之间共享，否则每次发布都会丢失运行数据。deploy:shared任务的处理逻辑（见 recipe/deploy/shared.php）：

1. 若{{deploy_path}}/shared/writable不存在，则创建它，并把 release 中已有的writable目录内容拷贝进去；
2. 删除 release 中的原目录；
3. 在 release 中创建指向shared/writable的符号链接。

shared_files（共享文件）

set('shared_files', ['.env']);

.env存放数据库凭据、encryption key 等环境敏感配置，同样以符号链接形式在 release 间共享：首次部署时把 release 内的.env（若存在）复制到shared/.env，此后所有 release 统一通过 symlink 引用同一份文件。这也解释了spark系列任务中skipIfNoEnv/failIfNoEnv选项的意义——.env是独立于代码仓库的共享资产。

writable_dirs（可写目录）

set('writable_dirs', [ 'writable/cache', 'writable/debugbar', 'writable/logs', 'writable/session', 'writable/uploads', ]);

列出需要 Web 服务器可写的子目录。deploy:writable任务会先mkdir -p确保目录存在，再按writable_mode设置权限（默认acl，其他可选值见 recipe/deploy/writable.php：chown、chgrp、chmod、acl、sticky、skip）。http_user/http_group会在进程列表中自动探测 Apache/Nginx 用户，探测失败时可在deploy.php中显式指定。

log_files（日志文件）

set('log_files', 'writable/logs/*.log');

指定应用日志文件路径（支持通配符），供 common recipe 中的logs:app任务使用——运行dep logs:app可通过tail -f实时跟踪 CodeIgniter 4 的日志输出。

codeigniter4_version（版本自动检测）

set('codeigniter4_version', function () { $result = run('{{bin/php}} {{release_or_current_path}}/spark'); preg_match_all('/(\d+\.?)+/', $result, $matches); return $matches[0][0] ?? 5.5; });

在远程执行php spark解析输出中的第一个版本号，用于判断当前 CodeIgniter 4 版本，从而决定带min/max版本限制的 spark 任务是否执行；解析失败时回退到默认值5.5。bin/php来自 common recipe，默认为which php，也可通过主机级php_version配置指定特定版本。

spark() 辅助函数：版本门控与环境保护

codeigniter4recipe 通过源码中的辅助函数spark($command, $options)（见 recipe/codeigniter4.php）统一封装了对 CodeIgniter 4 CLI 命令php spark ...的调用，支持以下选项：

版本比较通过codeigniter4_version_compare(string $version, string $comparator)实现（recipe/codeigniter4.php），底层使用 PHP 的version_compare。.env的存在性检测使用test('[ -s .../.env ]')（-s表示文件存在且非空）。

内置任务速查

所有任务均可在命令行直接运行，例如dep spark:routes、dep spark:migrate:status。按源码注释（recipe/codeigniter4.php）分为五类：

Discover & Checks（诊断与检查）

Actions（执行类操作）

Database and migrations（数据库与迁移）

Housekeeping（日常维护）

spark:custom（自定义 spark 命令）

task('spark:custom', spark('', ['showOutput']));

用于执行 CodeIgniter 4 中没有被内置任务覆盖的自定义 spark 命令（例如 shield、settings 等第三方包的 CLI 命令），运行时会回显输出。使用方式示例：

dep spark:custom -- 'shield:user create'

部署后的服务器目录结构

一次成功部署后，服务器上的deploy_path目录结构如下（与 getting-started.md 中描述的通用结构一致）：

~/example // deploy_path ├─ current -> releases/2 // 指向当前版本的符号链接 ├─ releases/ │ ├─ 1 // 旧版本（cleanup 保留，默认 10 个） │ └─ 2 // 最新版本 │ ├─ ... │ ├─ writable -> ../../shared/writable // 共享目录 symlink │ └─ .env -> ../../shared/.env // 共享文件 symlink ├─ shared/ │ ├─ writable/ // 共享运行数据（缓存/日志/会话/上传） │ └─ .env // 共享环境配置 └─ .dep/ // Deployer 内部数据（锁、composer.phar 等）

current是 Web 服务器实际服务的目录。由于切换current是原子 symlink 操作，因此发布过程零停机；若新版本异常，可执行dep rollback回滚到上一 release（见 docs/recipe/deploy/rollback.md）。

总结与扩展阅读

codeigniter4recipe 将 CodeIgniter 4 的框架约定（public/入口、writable/运行时目录、.env环境配置、sparkCLI）与 Deployer 的通用部署模型（release 目录 + symlink 切换）有机结合：deploy:prepare负责准备与共享资产，deploy:vendors安装 Composer 依赖，spark:optimize与spark:migrate完成生产优化与数据库升级，deploy:publish原子发布并清理旧版本。整个流程以 common recipe 为基底，可进一步按需扩展自定义任务。

可继续阅读：

• common recipe 完整参考
• deploy 子任务系列、shared 共享配置、writable 权限配置、vendors 依赖安装
• recipe 源码实现

• DevOps
• CI/CD
• CLI
• 开发工具
• 运维