项目模板 (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 中的镜像：

container:
  image: git.xiaoxiajianji.com/xiaoxia/base/node:22

修改构建命令

修改 package.json 中的 scripts 部分：

{
  "scripts": {
    "build": "your-build-command",
    "lint": "your-lint-command"
  }
}

修改 Dockerfile

根据项目类型（前端/后端/全栈）调整 Dockerfile 中的构建和运行步骤。

镜像仓库地址

git.xiaoxiajianji.com/<用户名>/<仓库名>

拉取镜像：

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	基础系统