# 项目模板 (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 | 基础系统 |