mirror of
https://git.bjxgj.com/xgj/xgj-actions.git
synced 2025-10-14 13:53:36 +08:00
feat: 添加 Web 项目发布构建的 GitHub Action，包括版本发布、Docker 镜像构建和推送，支持灵活的输入参数和环境变量配置，优化 CI/CD 流程。
This commit is contained in:
Lyda
349
release-web/README.md
Normal file
349
release-web/README.md
Normal file
@@ -0,0 +1,349 @@
|
||||
# Web 项目发布构建 Action
|
||||
|
||||
[](https://github.com/features/actions)
|
||||
|
||||
自动化 Web 项目发布流程的 GitHub Action，包括版本发布、Docker 镜像构建和推送等完整的 CI/CD 流程。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- 🚀 **自动化发布**: 支持 `release-it` 工具进行版本管理和发布
|
||||
- 🐳 **Docker 集成**: 自动构建和推送 Docker 镜像到私有仓库
|
||||
- 🏷️ **灵活标签**: 支持自定义 Docker 标签，自动生成版本标签
|
||||
- 📊 **Sentry 集成**: 可选的 Sentry 错误监控集成
|
||||
- 🔧 **高度可配置**: 丰富的输入参数满足不同项目需求
|
||||
- ✅ **参数验证**: 自动验证必需参数和文件存在性
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 基础用法
|
||||
|
||||
```yaml
|
||||
- name: 发布Web项目
|
||||
uses: actions/xgj/release-web@main
|
||||
with:
|
||||
gitea-token: ${{ secrets.GITEA_TOKEN }}
|
||||
```
|
||||
|
||||
### 使用环境变量
|
||||
|
||||
```yaml
|
||||
- name: 发布Web项目
|
||||
uses: actions/xgj/release-web@main
|
||||
with:
|
||||
gitea-token: ${{ secrets.GITEA_TOKEN }}
|
||||
env:
|
||||
# 🌍 可以传递任意数量的环境变量给发布命令
|
||||
APP_ENV: production
|
||||
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
|
||||
SENTRY_DSN: ${{ vars.SENTRY_DSN }}
|
||||
SENTRY_VITE: true
|
||||
BUILD_NUMBER: ${{ github.run_number }}
|
||||
CUSTOM_CONFIG: "your-value"
|
||||
FEATURE_FLAG: ${{ github.ref == 'refs/heads/main' }}
|
||||
# ... 更多任意环境变量
|
||||
```
|
||||
|
||||
### 完整示例
|
||||
|
||||
```yaml
|
||||
- name: 发布Web项目
|
||||
uses: actions/xgj/release-web@main
|
||||
with:
|
||||
gitea-token: ${{ secrets.GITEA_TOKEN }}
|
||||
app-env: "production"
|
||||
sentry-auth-token: ${{ secrets.SENTRY_AUTH_TOKEN }}
|
||||
sentry-dsn: ${{ vars.SENTRY_DSN }}
|
||||
enable-sentry: "true"
|
||||
docker-registry: "docker-registry.bjxgj.com"
|
||||
dockerfile-path: "./container/prod/Dockerfile"
|
||||
docker-tags: |
|
||||
stable
|
||||
v2024
|
||||
```
|
||||
|
||||
## 输入参数
|
||||
|
||||
| 参数名 | 描述 | 必需 | 默认值 |
|
||||
| --------------------- | ------------------------- | ---- | --------------------------------- |
|
||||
| `gitea-token` | Gitea 访问令牌 | ✅ | - |
|
||||
| `app-env` | 应用环境 | ❌ | `production` |
|
||||
| `sentry-auth-token` | Sentry 认证令牌 | ❌ | - |
|
||||
| `sentry-dsn` | Sentry DSN 配置 | ❌ | - |
|
||||
| `enable-sentry` | 是否启用 Sentry | ❌ | `false` |
|
||||
| `release-command` | 发布命令 | ❌ | `npm run release -- --release -V` |
|
||||
| `docker-registry` | Docker 仓库地址 | ❌ | `docker-registry.bjxgj.com` |
|
||||
| `docker-context` | Docker 构建上下文路径 | ❌ | `.` |
|
||||
| `dockerfile-path` | Dockerfile 路径 | ❌ | `./container/dev/Dockerfile` |
|
||||
| `docker-tags` | 额外的 Docker 标签 | ❌ | - |
|
||||
| `enable-docker-build` | 是否执行 Docker 构建 | ❌ | `true` |
|
||||
| `node-debug` | 是否启用 Node.js 调试模式 | ❌ | `false` |
|
||||
|
||||
## 环境变量支持
|
||||
|
||||
Action 支持通过 `env` 传递**任意数量**的环境变量给发布命令，这些环境变量会自动传递给 `npm run release` 或其他发布命令：
|
||||
|
||||
```yaml
|
||||
- uses: actions/xgj/release-web@main
|
||||
with:
|
||||
gitea-token: ${{ secrets.GITEA_TOKEN }}
|
||||
env:
|
||||
# 🌍 任意环境变量都会自动传递给发布命令
|
||||
APP_ENV: production
|
||||
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_TOKEN }}
|
||||
CUSTOM_VAR: "your-value"
|
||||
BUILD_NUMBER: ${{ github.run_number }}
|
||||
FEATURE_FLAG: ${{ github.ref == 'refs/heads/main' }}
|
||||
# ... 更多任意变量
|
||||
```
|
||||
|
||||
### 常用环境变量示例
|
||||
|
||||
| 环境变量名 | 描述 | 示例值 |
|
||||
| ------------------- | ---------------- | ----------------------------- |
|
||||
| `APP_ENV` | 应用环境 | `production` |
|
||||
| `SENTRY_AUTH_TOKEN` | Sentry 认证令牌 | `${{ secrets.SENTRY_TOKEN }}` |
|
||||
| `SENTRY_DSN` | Sentry DSN 配置 | `${{ vars.SENTRY_DSN }}` |
|
||||
| `SENTRY_VITE` | 是否启用 Sentry | `true` |
|
||||
| `NODE_DEBUG` | Node.js 调试模式 | `release-it:*` |
|
||||
| `BUILD_NUMBER` | 构建编号 | `${{ github.run_number }}` |
|
||||
|
||||
## 输出参数
|
||||
|
||||
| 参数名 | 描述 |
|
||||
| --------------------- | ------------------------ |
|
||||
| `version` | 发布的版本号 |
|
||||
| `version-with-dash` | 版本号（点号替换为横线） |
|
||||
| `docker-image-digest` | Docker 镜像摘要 |
|
||||
| `docker-image-tags` | Docker 镜像标签列表 |
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 1. 基础发布流程
|
||||
|
||||
适用于简单的 Web 项目发布：
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: 设置环境
|
||||
uses: actions/xgj/setup-env@main
|
||||
with:
|
||||
docker-password: ${{ secrets.DOCKER_PASSWORD }}
|
||||
|
||||
- name: 安装依赖
|
||||
uses: actions/xgj/npm-install@main
|
||||
|
||||
- name: 发布项目
|
||||
uses: actions/xgj/release-web@main
|
||||
with:
|
||||
gitea-token: ${{ secrets.GITEA_TOKEN }}
|
||||
```
|
||||
|
||||
### 2. 完整 CI/CD 流程
|
||||
|
||||
包含完整的构建、测试、发布流程：
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: 设置构建环境
|
||||
uses: actions/xgj/setup-env@main
|
||||
with:
|
||||
docker-password: ${{ secrets.DOCKER_PASSWORD }}
|
||||
kube-config: ${{ secrets.KUBE_CONFIG }}
|
||||
|
||||
- name: 安装依赖
|
||||
uses: actions/xgj/npm-install@main
|
||||
with:
|
||||
package-manager: "pnpm"
|
||||
|
||||
- name: 运行测试
|
||||
run: npm run test
|
||||
|
||||
- name: 发布构建
|
||||
id: release
|
||||
uses: actions/xgj/release-web@main
|
||||
with:
|
||||
gitea-token: ${{ secrets.GITEA_TOKEN }}
|
||||
app-env: ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}
|
||||
sentry-auth-token: ${{ secrets.SENTRY_AUTH_TOKEN }}
|
||||
sentry-dsn: ${{ vars.SENTRY_DSN }}
|
||||
enable-sentry: "true"
|
||||
dockerfile-path: "./Dockerfile"
|
||||
docker-tags: |
|
||||
${{ github.sha }}
|
||||
${{ github.ref_name }}
|
||||
|
||||
- name: 部署到Kubernetes
|
||||
run: |
|
||||
kubectl set image deployment/web-app web-app=docker-registry.bjxgj.com/${{ github.event.repository.name }}:${{ steps.release.outputs.version }}
|
||||
```
|
||||
|
||||
### 3. 多环境发布
|
||||
|
||||
支持不同环境的差异化配置：
|
||||
|
||||
```yaml
|
||||
strategy:
|
||||
matrix:
|
||||
environment: [staging, production]
|
||||
include:
|
||||
- environment: staging
|
||||
dockerfile: "./container/dev/Dockerfile"
|
||||
app-env: "staging"
|
||||
- environment: production
|
||||
dockerfile: "./container/prod/Dockerfile"
|
||||
app-env: "production"
|
||||
|
||||
steps:
|
||||
- name: 发布到 ${{ matrix.environment }}
|
||||
uses: actions/xgj/release-web@main
|
||||
with:
|
||||
gitea-token: ${{ secrets.GITEA_TOKEN }}
|
||||
app-env: ${{ matrix.app-env }}
|
||||
dockerfile-path: ${{ matrix.dockerfile }}
|
||||
docker-tags: ${{ matrix.environment }}
|
||||
```
|
||||
|
||||
## 工作流程
|
||||
|
||||
1. **参数验证**: 检查必需参数和文件是否存在
|
||||
2. **发布构建**: 执行 `release-it` 命令进行版本发布
|
||||
3. **获取版本**: 从 `/tmp/last-version` 读取新版本号
|
||||
4. **准备标签**: 生成 Docker 镜像标签列表
|
||||
5. **Docker 构建**: 构建并推送 Docker 镜像（可选）
|
||||
6. **发布总结**: 输出发布信息和结果
|
||||
|
||||
## 依赖要求
|
||||
|
||||
### 项目要求
|
||||
|
||||
- 包含 `package.json` 文件
|
||||
- 配置了 `release-it` 工具
|
||||
- 包含发布脚本（如 `npm run release`）
|
||||
- Docker 构建需要有效的 `Dockerfile`
|
||||
|
||||
### 环境依赖
|
||||
|
||||
- Node.js 环境
|
||||
- npm/pnpm/yarn 包管理器
|
||||
- Docker（如果启用 Docker 构建）
|
||||
- 配置好的 Docker 仓库访问权限
|
||||
|
||||
## 配置示例
|
||||
|
||||
### release-it 配置
|
||||
|
||||
确保项目中有类似的 `.release-it.js` 配置：
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
hooks: {
|
||||
"before:release": [
|
||||
"echo '${version}' > /tmp/last-version",
|
||||
"npm run build",
|
||||
],
|
||||
},
|
||||
git: {
|
||||
tagName: "v${version}",
|
||||
commitMessage: "chore: released version v${version} [no ci]",
|
||||
},
|
||||
npm: {
|
||||
publish: false,
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### Docker 多阶段构建
|
||||
|
||||
推荐使用多阶段构建优化镜像大小：
|
||||
|
||||
```dockerfile
|
||||
# 构建阶段
|
||||
FROM node:18-alpine AS builder
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci --only=production
|
||||
|
||||
# 运行阶段
|
||||
FROM node:18-alpine
|
||||
WORKDIR /app
|
||||
COPY --from=builder /app/node_modules ./node_modules
|
||||
COPY dist ./dist
|
||||
EXPOSE 3000
|
||||
CMD ["npm", "start"]
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
Action 会在以下情况报错并退出：
|
||||
|
||||
- 缺少必需的 `gitea-token` 参数
|
||||
- 指定的 `Dockerfile` 不存在
|
||||
- `/tmp/last-version` 文件不存在（发布命令未正确执行）
|
||||
- Docker 构建失败
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
- 🔒 始终通过 `secrets` 传递敏感令牌
|
||||
- 🔍 定期检查和轮换访问令牌
|
||||
- 📋 限制 Docker 仓库访问权限
|
||||
- 🚫 避免在日志中暴露敏感信息
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
**Q: 版本文件不存在错误**
|
||||
|
||||
```
|
||||
❌ 错误: 版本文件 /tmp/last-version 不存在
|
||||
```
|
||||
|
||||
A: 检查 `release-it` 配置是否包含创建版本文件的 hook：
|
||||
|
||||
```javascript
|
||||
hooks: {
|
||||
'before:release': ['echo \'${version}\' > /tmp/last-version']
|
||||
}
|
||||
```
|
||||
|
||||
**Q: Docker 构建失败**
|
||||
|
||||
A: 检查：
|
||||
|
||||
1. Dockerfile 路径是否正确
|
||||
2. Docker 仓库是否已登录（使用 `actions/xgj/setup-env` action）
|
||||
3. 构建上下文是否包含必需文件
|
||||
|
||||
**Q: Gitea Token 权限不足**
|
||||
|
||||
A: 确保 token 具有以下权限：
|
||||
|
||||
- Repository 写权限
|
||||
- Releases 创建权限
|
||||
|
||||
### 调试模式
|
||||
|
||||
启用详细调试信息：
|
||||
|
||||
```yaml
|
||||
- uses: actions/xgj/release-web@main
|
||||
with:
|
||||
gitea-token: ${{ secrets.GITEA_TOKEN }}
|
||||
node-debug: "true"
|
||||
```
|
||||
|
||||
## 更新日志
|
||||
|
||||
查看 [Releases](https://github.com/your-org/actions/releases) 获取详细的更新历史。
|
||||
|
||||
## 贡献
|
||||
|
||||
欢迎提交 Issue 和 Pull Request 来改进这个 Action！
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT License - 详见 [LICENSE](../LICENSE) 文件。
|
||||
Reference in New Issue
Block a user