搭建企业级私有Composer包仓库（Satis + GitHub Pages）完整指南

🏗️ 搭建企业级私有Composer包仓库（Satis + GitHub Pages）完整指南

📋 概述

本文将详细介绍如何为企业搭建一个安全、可扩展、完全免费 的私有Composer包仓库。这个架构基于Satis + GitHub Pages，能够满足团队内部PHP包管理的所有需求。

🎯 架构目标

1. 安全性：私有包代码绝对不泄漏
2. 可扩展性：轻松管理多个私有包
3. 自动化：全流程CI/CD自动化
4. 免费：基于GitHub免费服务
5. 易用性：适合各级开发者使用

🏗️ 架构设计原理

比喻：内部软件图书馆

想象您的公司要建立一个"内部数字图书馆"：

🏛️ 内部数字图书馆架构
├── 📚 图书编目系统（Satis）
│   └── 功能：扫描所有图书，生成目录
│   └── 安全：只记录"书名、作者、简介"
│
├── 🤖 自动编目机器人（GitHub Actions）
│   └── 工作：有新书自动更新目录
│
├── 🎪 公共查询台（GitHub Pages）
│   └── 地址：your-company.github.io/composer-repo
│   └── 内容：只展示目录，不存书
│
├── 🔐 机器人工作证（GitHub Secrets）
│   └── 安全：工作证不离柜
│
└── 👨💻 读者借阅流程
    └── 查询目录 → 出示借书证 → 借阅图书 → 书库取书

🚀 搭建步骤

第一步：准备账号和仓库

1.1 创建GitHub账号

• 个人账号：用于管理所有仓库
• 机器人账号（推荐）：专门用于自动化构建

1.2 创建仓库

1. Satis配置仓库

   • 仓库名：composer-packages
   • 用途：存放Satis配置和生成网站

2. 私有包仓库（示例）

   • 仓库名：internal-package-1
   • 用途：存放私有PHP包代码

第二步：创建配置文件

2.1 创建 satis.json

在composer-packages仓库根目录创建：

{
    "name": "your-company/composer-packages",
    "homepage": "https://your-company.github.io/composer-packages/",
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/your-company/internal-package-1.git"
        },
        {
            "type": "vcs",
            "url": "https://github.com/your-company/internal-package-2.git"
        }
    ],
    "require-all": true,
    "output-dir": "public",
    "archive": {
        "directory": "dist",
        "format": "zip",
        "prefix-url": "https://your-company.github.io/composer-packages/",
        "skip-dev": false
    },
    "config": {
        "github-oauth": {
            "github.com": "GITHUB_TOKEN_PLACEHOLDER"
        }
    }
}

配置说明：

• homepage：您的GitHub Pages地址
• repositories：所有私有包仓库列表
• config.github-oauth：认证配置占位符

2.2 创建GitHub Actions工作流

创建.github/workflows/build.yml：

name: Build and Deploy Private Composer Repository

on:
  push:
    branches: [ "main" ]
  workflow_dispatch:  # 支持手动触发

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          
      - name: Install Satis
        run: composer create-project composer/satis:^2.0 --stability=dev --no-dev
        
      - name: Replace GitHub Token
        run: |
          if [ -z "${{ secrets.SATIS_GITHUB_TOKEN }}" ]; then
            echo "❌ Error: Token not configured"
            exit 1
          fi
          sed -i "s/GITHUB_TOKEN_PLACEHOLDER/${{ secrets.SATIS_GITHUB_TOKEN }}/g" satis.json
        
      - name: Build Satis Repository
        run: php satis/bin/satis build --no-ansi --verbose satis.json public/
        
      - name: Setup Pages
        uses: actions/configure-pages@v4
        
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './public'

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

第三步：安全配置

3.1 生成GitHub访问令牌

1. 访问GitHub设置 → Developer settings → Personal access tokens
2. 创建具有 repo 权限的Token
3. 复制Token值（只显示一次）

3.2 配置GitHub Secrets

1. 进入仓库设置 → Secrets and variables → Actions
2. 添加Secret：
   • 名称：SATIS_GITHUB_TOKEN
   • 值：粘贴您的Token
3. 保存

3.3 设置仓库权限

将机器人账号添加为仓库协作者：

• Satis配置仓库：Write权限
• 私有包仓库：Read权限

第四步：部署

4.1 提交配置

git add .
git commit -m "初始化私有Composer仓库配置"
git push origin main

4.2 观察构建

访问仓库的Actions页面，查看构建状态，等待所有步骤完成。

4.3 验证部署

构建成功后：

1. 访问GitHub Pages设置，确认站点已激活
2. 访问：https://your-company.github.io/composer-packages/
3. 应该看到包列表页面

📱 在项目中使用

5.1 添加私有仓库源

在项目的composer.json中：

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://your-company.github.io/composer-packages/"
        }
    ]
}

5.2 配置个人访问令牌

开发者本地配置：

# 方法一：环境变量
export COMPOSER_AUTH='{"github-oauth": {"github.com": "YOUR_PERSONAL_TOKEN"}}'

# 方法二：全局配置
composer config -g github-oauth.github.com YOUR_PERSONAL_TOKEN

5.3 安装私有包

composer require your-company/internal-package-1
composer require your-company/internal-package-2

🏗️ 架构管理

添加新私有包

1. 在satis.json的repositories数组中添加新仓库
2. 提交并推送，GitHub Actions会自动重建

自动更新触发

在私有包仓库配置Webhook，发布新版本时自动更新Satis仓库。

🔧 故障排除

问题	可能原因	解决方案
404错误	Pages未部署	检查Actions，等待几分钟
认证失败	Token权限不足	重新生成有repo权限的Token
包不存在	包名错误	检查satis.json配置

✅ 架构优势

安全性

• 代码不泄漏：Satis只生成元数据
• 密钥不泄漏：Token通过GitHub Secrets管理
• 权限控制：最小权限原则

可扩展性

• 多包管理：轻松添加新包
• 自动构建：代码更新自动重建
• 团队协作：开发者只需个人Token

易用性

• 标准兼容：与Composer完全兼容
• Web界面：可视化包列表
• 详细文档：适合各级开发者

📁 项目结构

composer-packages/
├── .github/workflows/build.yml
├── satis.json
├── .gitignore
└── public/                    # 自动生成
    ├── index.html
    ├── packages.json
    ├── include/
    └── p/

🎉 成功标志

• ✅ 私有仓库可访问
• ✅ 包管理功能正常
• ✅ 自动化流程运行
• ✅ 团队可协作使用
• ✅ 安全保障到位

📈 总结

这个架构提供了一套完整的企业级私有Composer包管理解决方案：

• 无需额外服务器：基于GitHub免费服务
• 无需复杂配置：开箱即用
• 无需担心安全：多重防护机制
• 无需手动维护：全自动化流程

无论是初创团队还是大型企业，都可以通过这个架构轻松管理内部PHP包，提升开发效率和代码复用率。

---

注意事项：

1. 所有敏感信息（账号、仓库名、Token）已脱敏处理
2. 实际使用时请替换为您的真实信息
3. 建议定期更新访问令牌
4. 监控构建状态，确保服务正常

希望这个指南能帮助您的团队建立高效的私有包管理体系！