核心是三步：配置 Runner、写好 .gitlab-ci.yml、确保服务器环境就绪；需安装 PHP 7.4+、Swoole 扩展、Composer 等依赖，用 Shell 执行器注册 Runner，通过 rsync 部署并 daemon 启动服务。
用 GitLab CI 在 Linux 上快速自动化部署 Hyperf，核心是三步：配置 Runner、写好 .gitlab-ci.yml、确保服务器环境就绪。Hyperf 是基于 Swoole 的高性能 PHP 框架，部署时需注意扩展依赖、服务常驻（如用 Supervisor 或 systemd）、以及构建产物的正确分发。
一、Linux 服务器基础准备
Hyperf 运行依赖 PHP 7.4+、Swoole 扩展、Composer 及常用系统工具。建议在干净的 CentOS 7/8 或 Ubuntu 20.04+ 环境操作：
- 安装 PHP 及关键扩展：
php-cli、php-mbstring、php-xml、php-opcache、php-swoole（务必确认版本兼容，Hyperf v3.x 推荐 Swoole ≥ 5.0） - 安装 Composer：
curl -sS https://getcomposer.org/installer | php && sudo mv composer.phar /usr/local/bin/composer - 安装 Git、unzip、rsync（用于部署同步）：
yum install -y git unzip rsync或apt install -y git unzip rsync - 创建部署目录并赋权，例如：
sudo mkdir -p /var/www/hyperf-app && sudo chown -R $USER:$USER /var/www/hyperf-app
二、注册并配置 GitLab Runner（Shell 执行器）
推荐使用 Shell 执行器（轻量、调试方便），不依赖 Docker。Runner 需以普通用户身份运行，避免权限问题：
- 下载并安装 Runner：
sudo curl -L --output /usr/local/bin/gitlab-runner "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64" && sudo chmod +x /usr/local/bin/gitlab-runner - 创建专用用户：
sudo useradd --comment 'Hyperf CI Runner' --create-home --shell /bin/bash gitlab-runner - 安装服务并启动：
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner && sudo gitlab-runner start - 注册 Runner：
sudo -u gitlab-runner gitlab-runner register，按提示填入项目 Settings → CI/CD → Runners 页面提供的 URL 和 Registration Token；Tag 建议设为hyperf-shell；执行器选shell - 确保该用户对部署目录有读写权限，必要时加组：
sudo usermod -aG www-data gitlab-runner（Ubuntu）或sudo usermod -aG nginx gitlab-runner（CentOS）
三、编写高效可靠的 .gitlab-ci.yml
针对 Hyperf 项目，典型流程是：拉代码 → 安装依赖 → 构建（可选优化）→ 复制到目标目录 → 重启服务。以下为精简实用模板：
stages: - install - build - deploy <p>variables: COMPOSER_CACHE_DIR: "$CI_PROJECT_DIR/.composer-cache" DEPLOY_PATH: "/var/www/hyperf-app"</p><p>cache: key: "$CI_COMMIT_REF_SLUG" paths:</p><ul><li>vendor/</li><li>.composer-cache/</li></ul><p>install-job: stage: install tags:</p><ul><li>hyperf-shell only:</li><li>main script:</li><li>composer install --no-dev --optimize-autoloader -n</li></ul><p>build-job: stage: build tags:</p><ul><li>hyperf-shell only:</li><li>main script:</li><li>php bin/hyperf.php gen:publish</li><li>php bin/hyperf.php di:compile</li></ul><p>deploy-job: stage: deploy tags:</p><ul><li>hyperf-shell only:</li><li>main script:</li><li>rsync -av --delete --exclude=".git" --exclude="tests" --exclude="docker" --exclude=".gitlab-ci.yml" ./ $DEPLOY_PATH/</li><li>cd $DEPLOY_PATH</li><li>composer dump-autoload -o</li><li>php bin/hyperf.php start --daemon</li><li>echo "✅ Hyperf deployed and restarted"
说明：
• 使用 rsync 替代 cp 更安全可控；
• --daemon 启动 Swoole 服务，生产环境建议配合 Supervisor 管理进程；
• 若用 Supervisor，请在服务器预装并配置好 /etc/supervisor/conf.d/hyperf.conf，CI 中只需执行 supervisorctl reread && supervisorctl update && supervisorctl restart hyperf。
四、补充：安全与可观测性建议
上线前建议加固关键环节：
- GitLab 项目中设置 CI/CD 变量（Settings → CI/CD → Variables）：如
DB_HOST、REDIS_HOST等敏感配置，避免硬编码 - 在
.gitlab-ci.yml中添加简单健康检查：curl -f http://localhost:9501/ping || exit 1（假设监听 9501 端口） - 日志统一收集：将 Hyperf 日志输出到
/var/log/hyperf/，并配置 logrotate - 启用 GitLab Pipeline 调试模式：在作业开头加
set -x，便于排查失败步骤
不复杂但容易忽略
