Debian Composer如何进行持续集成与持续部署

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 凭据安全注入。