138 lines
3.5 KiB
Markdown
138 lines
3.5 KiB
Markdown
# 项目模板 (Project Template)
|
||
|
||
标准的前后端项目模板，内置完整的 CI/CD 流水线配置。
|
||
|
||
## 功能特性
|
||
|
||
- ✅ 代码质量检查 (Lint)
|
||
- ✅ 自动化构建
|
||
- ✅ Docker 镜像构建并推送到 Gitea 私有 Registry
|
||
- ✅ 构建缓存加速
|
||
- ✅ 使用私有基础镜像（无需访问 Docker Hub）
|
||
- ✅ 使用本地 Actions（无需访问 GitHub）
|
||
|
||
## 快速开始
|
||
|
||
### 1. 使用模板创建新项目
|
||
|
||
在 Gitea 界面中：
|
||
1. 点击右上角 **+** → **新建仓库**
|
||
2. 选择 **使用模板创建** → 选择 `project-template`
|
||
3. 填写仓库名称和描述
|
||
4. 点击 **创建仓库**
|
||
|
||
### 2. 配置 Secrets
|
||
|
||
在仓库设置中添加以下 Secrets：
|
||
|
||
| Secret 名称 | 说明 | 示例值 |
|
||
|-----------|------|--------|
|
||
| `GITEA_TOKEN` | 用于推送镜像的访问令牌 | `xxxxxxxxxxxxx` |
|
||
|
||
> **注意**：`GITEA_TOKEN` 需要有 `write:package` 权限。
|
||
|
||
### 3. 项目结构
|
||
|
||
```
|
||
.
|
||
├── .gitea/
|
||
│ └── workflows/
|
||
│ └── ci.yml # CI/CD 流水线配置
|
||
├── src/ # 源代码目录
|
||
├── dist/ # 构建产物（自动生成）
|
||
├── Dockerfile # Docker 镜像构建
|
||
├── .dockerignore # Docker 构建忽略文件
|
||
├── .gitignore # Git 忽略文件
|
||
├── package.json # 项目配置
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
## CI/CD 流水线说明
|
||
|
||
### 触发条件
|
||
|
||
- **Push 到 main / develop 分支**：触发完整流水线
|
||
- **Pull Request 到 main**：触发代码检查和构建（不推送镜像）
|
||
|
||
### 流水线阶段
|
||
|
||
1. **Lint & Build**
|
||
- 检出代码
|
||
- 安装依赖（带缓存）
|
||
- 代码风格检查
|
||
- 类型检查
|
||
- 项目构建
|
||
- 上传构建产物
|
||
|
||
2. **Docker Build & Push**（仅 main 分支）
|
||
- 下载构建产物
|
||
- 构建 Docker 镜像
|
||
- 推送到 Gitea 私有 Registry
|
||
- 镜像标签：`latest` 和 commit SHA
|
||
|
||
### 使用的私有资源
|
||
|
||
**基础镜像**（来自 `git.xiaoxiajianji.com/xiaoxia/base/`）：
|
||
- `node:20` - 构建环境
|
||
- `node:20-alpine` - 生产环境
|
||
|
||
**Actions**（来自 `actions/` 命名空间）：
|
||
- `actions/checkout@v4` - 代码检出
|
||
- `actions/cache@v4` - 依赖缓存
|
||
- `actions/upload-artifact@v4` - 产物上传
|
||
- `actions/download-artifact@v4` - 产物下载
|
||
- `actions/setup-buildx-action@v3` - Docker Buildx
|
||
- `actions/login-action@v3` - Registry 登录
|
||
- `actions/build-push-action@v6` - 镜像构建推送
|
||
|
||
## 自定义配置
|
||
|
||
### 修改 Node.js 版本
|
||
|
||
修改 `.gitea/workflows/ci.yml` 中的镜像：
|
||
```yaml
|
||
container:
|
||
image: git.xiaoxiajianji.com/xiaoxia/base/node:22
|
||
```
|
||
|
||
### 修改构建命令
|
||
|
||
修改 `package.json` 中的 `scripts` 部分：
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"build": "your-build-command",
|
||
"lint": "your-lint-command"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 修改 Dockerfile
|
||
|
||
根据项目类型（前端/后端/全栈）调整 `Dockerfile` 中的构建和运行步骤。
|
||
|
||
## 镜像仓库地址
|
||
|
||
```
|
||
git.xiaoxiajianji.com/<用户名>/<仓库名>
|
||
```
|
||
|
||
拉取镜像：
|
||
```bash
|
||
docker pull git.xiaoxiajianji.com/xiaoxia/my-project:latest
|
||
```
|
||
|
||
## 支持的基础镜像
|
||
|
||
已同步到私有 Registry 的基础镜像：
|
||
|
||
| 镜像 | 标签 | 用途 |
|
||
|-----|------|------|
|
||
| node | 18, 20, 22 | Node.js 应用 |
|
||
| node | 20-alpine | 轻量 Node.js 运行时 |
|
||
| nginx | alpine, latest | Web 服务器 |
|
||
| python | 3.10-slim, 3.11-slim, 3.12-slim | Python 应用 |
|
||
| postgres | 15-alpine, 16-alpine | 数据库 |
|
||
| redis | 7-alpine | 缓存 |
|
||
| alpine | 3.19, 3.20 | 基础系统 |
|