Debian 上使用 Composer 的 CI/CD 实战指南
一 核心原则与准备
- 在 Debian 构建机或 Runner 上安装并验证工具链:PHP CLI、Composer、Git,以及项目所需的 PHP 扩展(如 php-mysql、php-curl、php-mbstring、php-xml、php-zip、php-bcmath 等)。示例:
- sudo apt update && sudo apt install -y php php-cli php-fpm php-mysql php-curl php-mbstring php-xml php-zip php-bcmath unzip git composer
- 代码与依赖管理:
- 始终将 composer.lock 纳入版本控制,CI 中使用 composer install 而非 update,确保环境一致性。
- 生产构建使用 –no-dev --optimize-autoloader;必要时加上 –prefer-dist 加速安装。
- 启用缓存:优先缓存 ~/.composer/cache(跨项目复用下载产物),谨慎缓存 vendor/(建议以 composer.lock 哈希为缓存键,命中才复用)。
- 安全与合规:在 CI 中加入 composer validate 与 composer audit(Composer 2.5+ 内置)以阻断不安全依赖;如需拉取私有包,使用 auth.json 或平台密钥,避免明文存放凭据。
二 流水线示例
- GitHub Actions(检出 → 安装 → 测试 → 部署)
- 在仓库 Settings → Secrets 配置:SERVER_HOST、SERVER_USER、SERVER_SSH_KEY、DEPLOY_PATH。
- 工作流示例(.github/workflows/ci-cd.yml):
- name: CI/CD
on:
push:
branches: [ main ]
jobs:
build-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: ‘8.2’
extensions: mbstring, xml, curl, zip, bcmath, mysql
- name: Composer cache
uses: actions/cache@v3
with:
path: |
~/.composer/cache
vendor
key: ${{ runner.os }}-composer-${{ hashFiles(‘**/composer.lock’) }}
restore-keys: ${{ runner.os }}-composer-
- name: Install dependencies
run: composer install --no-interaction --prefer-dist --optimize-autoloader
- name: Validate & Security Audit
run: |
composer validate --strict
composer audit --no-dev
- name: Run tests
run: vendor/bin/phpunit --configuration phpunit.xml
deploy:
needs: build-test
runs-on: ubuntu-latest
if: github.ref == ‘refs/heads/main’
steps:
- uses: actions/checkout@v4
- name: Deploy via SSH
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.SERVER_HOST }}
username: ${{ secrets.SERVER_USER }}
key: ${{ secrets.SERVER_SSH_KEY }}
script: |
set -e
cd ${{ secrets.DEPLOY_PATH }}
git pull origin main
composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan migrate --force
# 可选:重启 FPM 或重载 Nginx
# sudo systemctl reload php8.2-fpm || true
# sudo systemctl reload nginx || true
- GitLab CI(Runner 在 Debian 上的通用做法)
- 在仓库 Settings → CI/CD → Variables 配置:DEPLOY_USER、DEPLOY_HOST、SSH_PRIVATE_KEY、DEPLOY_PATH。
- .gitlab-ci.yml 示例:
- stages:
- test
- deploy
variables:
APP_ENV: production
before_script:
- apt-get update -yqq
- apt-get install -yqq unzip git
- php -r “copy(‘.env.example’, ‘.env’);”
- php artisan key:generate --force
- which ssh-agent || ( apt-get update -y && apt-get install -y openssh-client )
- eval $(ssh-agent -s)
- echo “$SSH_PRIVATE_KEY” | tr -d ‘\r’ | ssh-add - > /dev/null
- mkdir -p ~/.ssh
- chmod 700 ~/.ssh
- ssh-keyscan -H “$DEPLOY_HOST” >> ~/.ssh/known_hosts
cache:
paths:
- vendor/
- ~/.composer/cache/files/
key: ${CI_COMMIT_REF_SLUG}
test:
stage: test
script:
- composer install --no-interaction --prefer-dist
- php artisan config:cache
- php artisan route:cache
- php artisan view:cache
- php artisan migrate --seed --force
- vendor/bin/phpunit --configuration phpunit.xml
deploy_prod:
stage: deploy
only:
- main
script:
- ssh $DEPLOY_USER@$DEPLOY_HOST “cd $DEPLOY_PATH && git pull origin main”
- ssh $DEPLOY_USER@$DEPLOY_HOST “composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev”
- ssh $DEPLOY_USER@$DEPLOY_HOST “php artisan config:cache && php artisan route:cache && php artisan view:cache”
- ssh $DEPLOY_USER@$DEPLOY_HOST “php artisan migrate --force”
- Jenkins(在 Debian 上自建 Runner)
- 安装 Runner 并注册到 Jenkins;在 Job 或 Pipeline 中:
- 拉取代码 → 设置 COMPOSER_NO_INTERACTION=1、缓存 ~/.composer/cache → 执行 composer install --no-dev --optimize-autoloader → 运行测试 → 通过 SSH/SCP 部署并在远端执行 composer install 与 migrate。
- 如需拉取私有包,使用 Jenkins 凭据将 auth.json 写入 ~/.composer/auth.json,避免硬编码令牌。
三 部署与安全要点
- 使用 SSH 密钥或平台托管的部署密钥进行服务器访问;在 CI 中预先启动 ssh-agent、添加私钥、写入 known_hosts,避免交互与中间人风险。
- 数据库迁移策略:预发布环境可带 –seed 便于联调;生产环境建议使用 –force 且配合蓝绿/金丝雀发布或维护模式,降低变更风险。
- 缓存策略:优先缓存 ~/.composer/cache;缓存 vendor/ 时以 composer.lock 哈希为键,命中才复用,避免脏缓存导致构建不一致。
- 私有依赖:通过 auth.json 或 GitHub/GitLab 令牌安全注入凭据;切勿将令牌写入仓库或脚本。
- 安全审计:在 CI 中加入 composer validate 与 composer audit,发现高危漏洞即阻断发布。
- 原子化发布:先拉取新版本、执行 composer install、再切换软链接或原子移动发布目录,最后执行 cache:clear/migrate,减少服务中断窗口。
四 性能优化与常见问题
- 提速手段:
- 使用 –prefer-dist、关闭进度条(如 –no-progress)、开启 Composer 缓存与构建缓存,显著缩短依赖安装时间。
- 生产构建使用 –no-dev --optimize-autoloader;必要时使用 classmap-authoritative 进一步优化自动加载。
- 常见问题与修复:
- 构建不一致:未提交 composer.lock 或在 CI 中误用 composer update → 改为提交 lock 并使用 install。
- 权限或连接失败:SSH 未正确配置密钥/known_hosts → 在 CI 中显式添加并校验。
- 迁移失败或数据不一致:生产环境误用 –seed → 移除 –seed 并使用 –force 配合灰度/维护策略。
- 缓存命中异常:缓存键未基于 composer.lock → 以 lock 哈希为键,命中才复用 vendor。
- 私有包拉取失败:缺少 auth.json → 通过 CI 凭据安全注入。