PHP Composer 私有源搭建

wen PHP项目 2026-08-11 187

本文目录导读：

PHP Composer 私有源搭建

方案选择总览
Satis 搭建方案（推荐）
私有包发布技巧
缓存代理方案（高级）
Private Packagist（付费方案）
安全与最佳实践
故障排查
总结建议

搭建PHP Composer私有源是很多团队在开发中需要面对的问题，这里我将为你详细介绍几种主流的搭建方案，从简单到复杂，你可以根据团队规模和需求选择。

方案选择总览

方案	优点	缺点	适用场景
Satis	简单、轻量、官方出品	需要手动更新	小型团队、个人
Private Packagist	功能强大、自动更新	付费（收费）	中型及以上团队
Toran Proxy	功能完整、含代理	已停止维护	不推荐新项目
自建 Composer 仓库	完全掌控	开发成本高	有特殊需求

Satis 搭建方案（推荐）

安装 Satis

# 全局安装
composer global require composer/satis

创建配置文件 `satis.json`

{
    "name": "My Private Repository",
    "homepage": "http://repo.example.com",
    "repositories": [
        {"type": "vcs", "url": "https://github.com/your-company/package-a.git"},
        {"type": "vcs", "url": "https://github.com/your-company/package-b.git"},
        {"type": "package", "package": {
            "name": "private/package-c",
            "version": "1.0.0",
            "dist": {
                "url": "http://repo.example.com/packages/package-c.zip",
                "type": "zip"
            }
        }},
        // 可以使用通配符匹配
        {"type": "vcs", "url": {"git@github.com:your-company/*.git"}}
    ],
    "require": {
        // 可选，只包含指定包
        "your-company/package-a": "*",
        "your-company/package-b": "~1.2"
    },
    // 可选：依赖的公共包也缓存进来
    "require-dependencies": true,
    "require-dev-dependencies": true,
    "archive": {
        "directory": "dist",
        "format": "zip",
        "skip-dev": true
    }
}

生成静态仓库

# 生成配置文件指定的仓库
php satis build satis.json public/
# 如果有多个版本的配置，可以分别构建
php satis build satis.json public/ --no-interaction

配置 Web 服务器

Nginx 配置示例：

server {
    listen 80;
    server_name repo.example.com;
    root /var/www/repo/public;
    location / {
        try_files $uri $uri/ =404;
    }
    # 可选：启用压缩
    gzip on;
    gzip_types application/json text/html;
}

客户端使用配置

在 composer.json 中配置：

{
    "repositories": [
        {"type": "composer", "url": "http://repo.example.com"},
        {"packagist.org": false}
    ],
    "require": {
        "your-company/package-a": "^1.0"
    }
}

私有包发布技巧

使用 Git 标签控制版本

# 发布 1.0.0 版本
git tag -a v1.0.0 -m "Release 1.0.0"
git push origin v1.0.0

通过 GitHub Actions 自动更新 Satis

创建 .github/workflows/update-satis.yml：

name: Update Satis
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
      - name: Install Composer
        run: composer global require composer/satis
      - name: Build Satis
        run: php ~/.composer/vendor/bin/satis build
      - name: Deploy to Server
        uses: easingthemes/ssh-deploy@v2
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USER }}
          key: ${{ secrets.SSH_KEY }}
          source: "public/"
          target: "/var/www/repo/"

缓存代理方案（高级）

如果需要同时代理 Packagist 并缓存公共包：

修改 satis.json

{
    "name": "Combined Repository",
    "homepage": "http://repo.example.com",
    "repositories": [
        {"type": "composer", "url": "https://repo.packagist.org"},
        {"type": "vcs", "url": "https://github.com/your-company/private-package.git"}
    ],
    "require-all": true,
    "require-dependencies": true,
    "providers": true,
    "config": {
        "cache-dir": "./cache"
    },
    "archive": {
        "directory": "dist",
        "format": "zip",
        "skip-dev": true,
        "prefix-url": "http://repo.example.com"
    }
}

定时更新脚本 `update.sh`

#!/bin/bash
cd /path/to/satis
# 更新主仓库
php satis build satis.json public/ --no-interaction
# 清理过期缓存
find public -name "*.zip" -mtime +30 -delete

使用 crontab 定时执行：

# 每天凌晨 3 点更新
0 3 * * * /path/to/satis/update.sh

Private Packagist（付费方案）

对于商业团队,更推荐使用 Private Packagist，它提供：

自动更新：当 Git 仓库有新的 tag 时自动更新
Webhook 支持：集成 GitHub/GitLab/Bitbucket
团队管理：多用户权限控制
审计日志：完整的使用记录
API 支持：编程式管理包

# 安装私有包
composer config repositories.private-packagist composer https://repo.packagist.com/your-company/
composer require vendor/package --no-update

安全与最佳实践

访问控制（Nginx + 基本认证）

server {
    listen 80;
    server_name repo.example.com;
    auth_basic "Restricted Access";
    auth_basic_user_file /etc/nginx/.htpasswd;
    root /var/www/repo/public;
}

生成密码：

htpasswd -c /etc/nginx/.htpasswd composer

客户端认证

{
    "repositories": [
        {
            "type": "composer",
            "url": "http://repo.example.com",
            "username": "your-username",
            "password": "your-password"
        }
    ]
}

或使用环境变量：

export COMPOSER_AUTH='{"http-basic":{"repo.example.com":{"username":"user","password":"pass"}}}'

避免泄露公司域名

{
    "repositories": [
        {"packagist.org": false}
    ]
}

故障排查

常见问题及解决：

包版本找不到
- 检查 satis.json 中的版本限制
- 确认 Git 标签是否推送完整
下载超时
- 增加 dist 服务器配置
- 检查网络防火墙设置
认证失败
- 检查 COMPOSER_AUTH 环境变量
- 测试 curl -u user:pass http://repo.example.com
缓存问题
```
composer clear-cache
```