common-nginx-fpm/GITHUB_ACTION_SETUP.md

GitHub Action 配置说明

概述

已为项目创建了 GitHub Action 工作流，用于自动构建 Docker 镜像并推送到阿里云容器镜像仓库。

配置文件

• 工作流文件: .github/workflows/docker-build-push.yml
• 触发条件:
  • 推送到 main 分支
  • 创建 tag（以 v 开头）
  • Pull Request 到 main 分支
  • 手动触发

必需的 GitHub Secrets

在 GitHub 仓库的 Settings > Secrets and variables > Actions 中添加以下 Secrets：

必需配置

• ALIYUN_REGISTRY - 阿里云镜像仓库地址
  • 示例: registry.cn-hangzhou.aliyuncs.com
• ALIYUN_USERNAME - 阿里云镜像仓库用户名
• ALIYUN_PASSWORD - 阿里云镜像仓库密码

可选配置

• IMAGE_NAME - 镜像名称（可选）
  • 如果不设置，将使用 GitHub 仓库名称
  • 示例: your-namespace/common-nginx-fpm

镜像标签策略

工作流会自动生成以下标签：

分支推送

• main → latest, alpine
• 其他分支 → branch-name

Tag 推送

• v1.2.3 → 1.2.3, 1.2, 1, latest, alpine
• v2.0.0-beta.1 → 2.0.0-beta.1

Pull Request

• PR #123 → pr-123

功能特性

• ✅ 单架构构建 (linux/amd64)
• ✅ 构建缓存优化
• ✅ 自动标签管理
• ✅ 元数据标签
• ✅ 构建状态输出
• ✅ 支持手动触发

使用示例

1. 配置 Secrets

# 在 GitHub 仓库设置中添加以下 Secrets:
ALIYUN_REGISTRY=registry.cn-hangzhou.aliyuncs.com
ALIYUN_USERNAME=your-username
ALIYUN_PASSWORD=your-password
IMAGE_NAME=your-namespace/common-nginx-fpm  # 可选

2. 触发构建

# 方式1: 推送到 main 分支
git push origin main

# 方式2: 创建版本标签
git tag v1.0.0
git push origin v1.0.0

# 方式3: 在 GitHub 网页上手动触发
# Actions > Build and Push Docker Image to Aliyun Registry > Run workflow

3. 使用构建的镜像

# 拉取最新版本
docker pull registry.cn-hangzhou.aliyuncs.com/your-namespace/common-nginx-fpm:latest

# 拉取特定版本
docker pull registry.cn-hangzhou.aliyuncs.com/your-namespace/common-nginx-fpm:v1.0.0

# 运行容器
docker run -d -p 80:80 registry.cn-hangzhou.aliyuncs.com/your-namespace/common-nginx-fpm:latest

故障排除

1. 认证失败

• 检查 ALIYUN_USERNAME 和 ALIYUN_PASSWORD 是否正确
• 确认阿里云账号有推送权限

2. 镜像仓库不存在

• 在阿里云控制台创建对应的镜像仓库
• 确认 ALIYUN_REGISTRY 和 IMAGE_NAME 配置正确

3. 构建失败

• 查看 GitHub Actions 日志
• 检查 Dockerfile 语法
• 确认依赖包可用性

安全建议

1. 使用专用账号: 为 CI/CD 创建专用的阿里云子账号
2. 最小权限: 只授予必要的镜像推送权限
3. 定期轮换: 定期更新密码和访问密钥
4. 监控日志: 定期检查构建和推送日志

扩展功能

如需添加更多功能，可以考虑：

• 多架构构建 (linux/amd64, linux/arm64)
• 安全扫描集成
• 构建通知 (Slack, 钉钉等)
• 自动部署到测试环境
• 镜像签名验证