Deployer 升级指南：从 2.x 到 8.x 的完整迁移路径与破坏性变更详解

Deployer 升级指南从 2.x 到 8.x 的完整迁移路径与破坏性变更详解【免费下载链接】deployerThe PHP deployment tool with support for popular frameworks out of the box项目地址: https://gitcode.com/gh_mirrors/de/deployer本篇技术指南以 DeployerPHP 部署工具官方升级文档 docs/UPGRADE.md 为核心骨架系统梳理从 2.x 一路升级到 8.x 过程中每一代主版本的破坏性变更、必改项与新特性并结合当前仓库源码逐一印证底层实现如run()命名参数、quote()ANSI-C 引号、Httpie响应对象化、MAML recipe 解析等。读完本文你将掌握deploy.php配方文件的全部迁移改写要点能够安全、平滑地把存量项目升级到 Deployer 最新主版本。升级总览版本演进主线Deployer 的每一次主版本升级都伴随 API 层面的破坏性变更涉及函数签名、配置命名、Host 定义、任务约束与底层实现四个维度。从本文档给出的演进路径看主线如下版本跨度核心变更主题2.x → 3.x服务器路径配置从-path()迁往-env(deploy_path, ...)3.x → 4.x函数命名空间化、env()更名为set()/get()、异常类移动4.x → 5.xserver()全面改名host()、点号数组语法移除、凭据改由 SSH 配置承载5.x → 6.x分支优先级调整、run()返回string、env_vars更名为env6.x → 7.x阶段stage概念被标签labels 选择器selector取代、inventory()更名为import()、任务定义重写7.x → 8.xrun()/runLocally()参数改为命名参数、Httpie响应对象化、MAML recipe 新格式、自更新功能移除下文按时间倒序从最新的 8.x 开始逐代展开每节均给出“旧写法 → 新写法”的对照与源码依据。从 7.x 升级到 8.x运行环境要求8.x 对运行时与依赖提出了明确门槛这一点与仓库 composer.json 中require段完全一致PHP 8.3 或更高版本php: ^8.3Symfony 7.4 或 8.0 组件symfony/console、symfony/process、symfony/yaml均为^7.4.0 || ^8.0.0。升级前请先确认服务器与本地开发环境满足上述版本否则 Deployer 8.x 无法安装运行。run()与runLocally()$options 数组被移除全面启用命名参数7.x 及更早版本中run()的附加选项通过第二个$options数组传递8.x 将其彻底移除改为 PHP 命名参数named arguments。# Before (v7): run(command, [timeout 5, no_throw true]); # After (v8): run(command, timeout: 5, nothrow: true);同时涉及以下参数重命名no_throw→nothrowreal_time_output→forceOutputidle_timeout→idleTimeout从源码看src/functions.php 中run()的完整签名已经全部命名化function run( string $command, ?string $cwd null, ?array $env null, ?array $secrets null, ?bool $nothrow false, ?bool $forceOutput false, ?int $timeout null, ?int $idleTimeout null, ): string这些参数最终被封装进 src/Ssh/RunParams.php 的只读值对象readonly属性并由 src/ProcessRunner/ProcessRunner.php 消费nothrow决定进程非零退出时是返回输出还是抛出RunExceptionforceOutput决定是否实时打印命令输出idleTimeout则用于长时间无输出即中止的监控。此外run()的timeout默认值取自配置default_timeout默认 300 秒cwd未指定时回退到working_path配置。secret参数被secrets映射取代7.x 的secret只能传入一个命名秘钥8.x 改为secrets一个支持多个命名秘钥的关联数组配合%name%占位符在命令中使用并会被replace_secrets在日志与输出中打码隐藏。# Before (v7): run(echo %secret%, secret: getenv(MY_SECRET)); # After (v8): run(echo %my_secret%, secrets: [my_secret getenv(MY_SECRET)]);secrets同样出现在runLocally()签名中src/functions.php并可在RunParams::with()中与既有的 secrets 合并src/Ssh/RunParams.php。注意run()内部对sudo命令的二次尝试也会注入sudo_pass秘钥这同样是 8.x 秘钥体系的内部使用场景。新增cwd参数直接指定工作目录8.x 的run()新增cwd命名参数可以在调用时直接指定命令执行的工作目录无需先cd()再run()run(ls, cwd: /var/www);源码中run()的cwd默认值取自working_path配置若存在显式传入则优先runLocally()的cwd则默认遵循working_path语义用于本地命令执行。escapeshellarg()→quote()ANSI-C$...引号8.x 将配方中所有 PHP 原生escapeshellarg()的用法替换为 Deployer 自带的quote()函数。其实现位于 src/functions.php采用 ANSI-C$...引号语法对远程 shell 的兼容性更好由安全字符字母数字及/.-:,%组成的字符串会原样返回不加引号遇到 null 字节则直接抛异常。# Before (v7): run(echo . escapeshellarg($arg)); # After (v8): run(echo . quote($arg));quote()是全局函数也常用于拼接其他命令参数例如 src/functions.php 中which()定位二进制时就用quote($name)包装待查找的命令名。此外quote还可以作为模板过滤器在配置模板中使用run(echo {{ message | quote }});模板转义输出字面{{8.x 中若需要在命令中输出字面量{{而不触发配置替换用反斜杠转义即可run(echo \{{not_replaced}}); // outputs: {{not_replaced}}Httpie响应对象化、方法链去克隆、fetch()支持更多 HTTP 方法Httpie是 Deployer 内置的 HTTP 客户端基于 cURL 扩展见 src/Utility/Httpie.php构造时强制校验curl扩展。8.x 对其行为做了三处破坏性调整Httpie::send()现在返回HttpResponse对象而非字符串。响应对象src/Utility/HttpResponse.php提供body()响应体字符串、status()HTTP 状态码、json()解码为数组与info()cURL 元信息。取响应体需显式调用-send()-body()。getJson()已废弃改用sendJson()sendJson()内部等价于send()-json()src/Utility/Httpie.php。Httpie 方法不再克隆对象query()、header()、bearerToken()、body()、jsonBody()、formBody()、timeout()、setopt()、nothrow()等全部改为原地修改并返回$this形成标准的流式接口fluent API且send(?array $info)支持通过引用传出 cURL 信息。同时顶层辅助函数fetch()src/functions.php现在支持put、patch、delete方法内部按方法名分派到对应的Httpie::get()/post()/put()/patch()/delete()静态工厂并透传nothrow、请求头与请求体fetch(https://api.example.com/items/1, method: patch, body: json_encode([name new]));其他破坏性变更自更新功能移除Self-update自更新功能已移除。不再提供内建的自更新命令如需升级 Deployer 本身请通过 Composer 更新依赖composer update deployer/deployer。从 src/Command/MainCommand.php 可以看到8.x 仅在启动时通过 HTTP 检查远端是否有新版本提示。8.x 新特性一览8.x 在破坏性变更之外引入了多项新能力MAML recipes新增deploy.maml配方格式与 PHP、YAML 配方并存。MAML 是 Deployer 引入的声明式配方语言解析实现见 src/Import/MamlRecipe.php通过Maml\Maml库将deploy.maml解析为 hosts、config、tasks 等结构并执行对run/runLocally步骤还支持secrets、nothrow、forceOutput、idleTimeout等 8.x 命名参数的声明式写法src/Import/MamlRecipe.php。配合import(deploy.maml)使用入口函数见 src/functions.php。local_archive策略update_code_strategy新增取值直接从本地机器打包上传代码而不是从远端仓库拉取。该策略实现在 recipe/deploy/update_code.php本地git archive生成archive.tar后upload到远端并解包同时记录本地git rev-list的提交号。策略取值完整枚举为archive默认从远端仓库获取、local_archive本地复制、clone远端克隆保留.git目录三种见 recipe/deploy/update_code.php。composer_version配置在远端主机安装指定版本的 Composer。实现在 recipe/deploy/vendors.php配置为null时跳过版本校验非空时会下载 composer.phar 并校验--version输出是否匹配。set(composer_version, 2.7);Host::setShellPath()按主机定制 shell 路径对应源码 src/Host/Host.phpsetShell()为 170 行处setShellPath()为 181 行处。CI 用户检测自动识别 GitLab、GitHub Actions、CircleCI、Drone CI 环境中的用户名避免在 CI 流水线里手工写死remote_user。ACL 增强deploy:writable任务新增writable_acl_groups默认空数组见 recipe/deploy/writable.php用于指定额外 ACL 组与writable_acl_force两个配置项。从 6.x 升级到 7.x7.x 是概念级重构的一代阶段stage被标签labels 选择器selector取代配方导入、任务定义、Host API 全部重写。升级分两步走。Step 1更新 deploy.php配置项改名hostname→aliasreal_hostname→hostnameuser→remote_userdefault_stage→default_selector值相应调整例如prod改为stageproddefault_selector在 src/Command/SelectCommand.php 中被消费。Host 定义更新所有 setter 加set前缀identityFile→setIdentityFile()或改用set(identity_file, ...)SSH 选项写法变化# before host(...)-addSshOption(UserKnownHostsFile, /dev/null) # after host(...)-setSshArguments([-o UserKnownHostsFile/dev/null]);setSshArguments()对应 src/Host/Host.php阶段 → 标签原来按 stage 区分环境现在用 labelshost(deployer.org) -set(labels, [stage prod]);部署命令从dep deploy prod变为dep deploy stageprod。setLabels()/addLabels()实现见 src/Host/Host.phpalias()方法被删除host()本身就同时设置 alias 与 hostname如需覆盖主机名使用setHostname()src/Host/Host.php。任务定义更新onRoles()→select()task(...) -select(stageprod);字符串式任务定义被移除不能再用task(name, shell command)必须改为回调函数且注意设置正确的工作目录# from task(deploy:npm-install, npm clean-install); # to task(deploy:npm-install, function() { cd({{release_path}}); run(npm clean-install); });移除shallow()任务选项任务改名success→deploy:success、cleanup→deploy:cleanup冗长度函数isDebug()等被删除改用output()-isDebug()local()任务改为once()runLocally()的组合locateBinaryPath()→which()src/functions.phponHosts()/onStage()改为基于 labels selectorssetPrivate()→hidden()。第三方配方并入主仓库7.x 起第三方配方移入 Deployer 主仓库的contrib目录本仓库 contrib/ 下已包含 rsync、slack、telegram、discord、sentry、newrelic、crontab、supervisord-monitor 等 30 个集成配方引用方式require contrib/rsync.php;inventory()→import()import()src/functions.php不仅导入主机还能导入配置与任务支持 PHP、YAML、MAML 三种配方分发逻辑见 src/Import/Import.php。YAML 配方示例tests/spec/recipe/deploy.yaml 有可运行用例import: recipe/common.php config: application: deployer shared_dirs: - uploads - storage/logs/ - storage/db shared_files: - .env - config/test.yaml keep_releases: 3 http_user: false hosts: prod: local: true tasks: deploy: - deploy:prepare - deploy:vendors - deploy:publish deploy:vendors: - run: cd {{release_path}} echo {{bin/composer}} {{composer_options}} 21其余行为变更runLocally()现在相对配方文件所在目录执行命令可通过环境变量覆盖DEPLOYER_ROOT. vendor/bin/dep taskname配置writable_recursive默认改为false如需旧行为显式开启set(writable_recursive, true);.git目录不再出现在 release 目录中恢复旧行为需显式设置set(update_code_strategy, clone);Step 2首次部署需手工指定 release 编号由于 v6 与 v7 的 release 历史编号不兼容第一次升级部署必须手工指定release_name否则会从 release 1 重新开始SSH 登录主机lsreleases 目录找到当前最大的编号示例为42用下一个编号部署dep deploy -o release_name43:::note 若需要回滚手工切换current软链接ln -nfs releases/42 current::::::note 若多台主机的 release 编号不一致需要在每台主机的{{deploy_path}}/.dep/latest_release文件中写入该主机当前的 release 编号。 :::从 5.x 升级到 6.x分支优先级调整主机定义中的branch(...)参数优先级提高命令行--branch不再覆盖它只有主机未定义分支时才取本地当前 git 分支。恢复旧行为的写法host(prod) -set(branch, production)host(prod) -set(branch, function () { return input()-getOption(branch) ?: production; })deploy任务开头新增deploy:info任务展示部署信息。run返回类型变化run()/runLocally()从返回Deployer\Type\Result对象改为直接返回stringrun(command)-toString()→run(command)run(if command; then echo true; fi;)-toBool()→test(command)test()的现代实现见 src/functions.php它在远端执行if $command; then echo true; fi并比对输出testLocally()是本地等价版src/functions.php。env_vars更名为envset(env_vars, FOObar);→set(env, [FOO bar]);Symfony 配方场景set(env, prod);→set(symfony_env, prod);从 4.x 升级到 5.xServers → Hosts核心函数全面改名server($hostname)→host($hostname)server($name, $hostname)→host($name)-hostname($hostname)localServer($name)→localhost()cluster($name, $nodes, $port)→hosts(...$nodes)serverList($file)→inventory($file)同一台服务器部署多套环境可借助 host 别名或同 hostname 多定义host(domain.com/green, domain.com/blue) -set(deploy_path, ~/{{hostname}}) ...host(production) -hostname(domain.com) -set(deploy_path, ~/production) ... host(beta) -hostname(domain.com) -set(deploy_path, ~/beta) ...配置选项{{server.name}}更名为{{hostname}}。点号数组语法移除v5 起get(a.b)不再支持嵌套访问改用扁平配置项set(a, [b 1]); get(a.b); // before set(a_b, 1); get(a_b); // after凭据管理推荐做法是在deploy.php中省略连接凭据改写到~/.ssh/configidentityFile($publicKeyFile, $privateKeyFile, $passPhrase)→identityFile($privateKeyFile)pemFile($pemFile)→identityFile($pemFile)forwardAgent()→forwardAgent(true)任务约束改名onlyOn→onHostsonlyOnStage→onStage。从 3.x 升级到 4.x函数命名空间化在deploy.php开头导入命名空间函数use function Deployer\{server, task, run, set, get, add, before, after};PHP 低于 5.6 时改用namespace Deployer;声明。env()→set()/get()env($name, $value)→set($name, $value)取值env($name)→get($name)server(...)-env(...)→server(...)-set(...)异常类移动Deployer\Task\NonFatalException→Deployer\Exception\NonFatalException。旧 release 清理因 release 管理机制变更新 cleanup 任务会忽略 3.x 部署的旧 release迁移并在 4.x 成功发布后需手工删除旧 release。从 2.x 升级到 3.x服务器路径配置改写server(...) -path(...);改为server(...) -env(deploy_path, ...);升级后的验证与配套文档完成升级后建议按以下路径验证配方可用性并深入学习新 API阅读 docs/basics.md 与 docs/getting-started.md 了解 8.x 的部署流程基本概念标签选择器语法详见 docs/selector.md任务定义与hidden()等 API 详见 docs/tasks.md各框架配方与部署子任务可参考 docs/recipe/ 与 recipe/ 下的实现内置集成配方slack、telegram、rsync 等文档位于 docs/contrib/源码位于 contrib/官方测试用例如 tests/spec/recipe/deploy.yaml、tests/src/FunctionsTest.php可作为理解run()命名参数、quote()、test()等新 API 行为的可执行参考。本文所涉及的函数签名、配置项与行为变更均有当前仓库源码佐证升级过程中如遇具体报错可优先对照 docs/KNOWN_BUGS.md 排查已知问题。【免费下载链接】deployerThe PHP deployment tool with support for popular frameworks out of the box项目地址: https://gitcode.com/gh_mirrors/de/deployer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考