# gitea-starter

**Repository Path**: fast-template-org/gitea-starter

## Basic Information

- **Project Name**: gitea-starter
- **Description**: 一些工作流构建示例
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-13
- **Last Updated**: 2025-11-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gitea 工作流示例模板

## 项目介绍

这是一个基于 Gitea Actions 的工作流示例集合，提供了多种常见的 CI/CD 场景的实现方案。本项目旨在帮助开发者快速理解和使用 Gitea Actions 进行自动化构建、测试和部署。

## 快速开始

### 选择适合你的工作流

| 场景 | 推荐工作流 | 文档链接 |
|------|-----------|---------|
| 🎓 **学习 Gitea Actions 基础** | [build.yml](.gitea/workflows/build.yml) | [查看文档](docs/build.md) |
| 🚀 **生产环境 Vue.js 部署 (PNPM)** | [build-with-pnpm-ssh.yaml](.gitea/workflows/build-with-pnpm-ssh.yaml) | [查看文档](docs/build-pnpm-ssh.md) |
| 🐳 **使用 Docker 容器构建 (NPM)** | [build-with-npm-ssh.yaml](.gitea/workflows/build-with-npm-ssh.yaml) | - |
| 🌐 **从 Gitee 克隆项目构建** | [build-gitea-starter-from-gitee.yml](.gitea/workflows/build-gitea-starter-from-gitee.yml) | [查看文档](docs/build-gitea-starter-from-gitee.md) |
| ⚡ **加速工作流 (本地 Actions)** | [build-local-action.yml](.gitea/workflows/build-local-action.yml) | [查看文档](docs/build-local-action.md) |
| 🐛 **调试工作流问题** | [build-manus-clone-debug.yml](.gitea/workflows/build-manus-clone-debug.yml) | [查看文档](docs/build-manus-clone-debug.md) |

## 工作流示例

### 基础示例

#### [Hello World 示例](.gitea/workflows/build.yml)
展示 Gitea Actions 的基本概念和语法，包括：
- 工作流触发方式
- 上下文变量使用
- Runner 标签和 Docker 镜像配置
- 基本步骤（steps）编写

📖 **[详细文档](docs/build.md)**

#### [本地 Action 构建](.gitea/workflows/build-local-action.yml)
展示如何使用本地定义的 Action，实现离线运行和性能优化：
- ⚡ **性能提升 50-70%**：减少 Actions 下载时间
- 🔌 **离线运行**：无需访问 GitHub
- 🎯 **挂载 → 复制 → 使用** 三步走策略
- 🔄 **自动降级**：本地不可用时使用远程 Actions

📖 **[详细文档](docs/build-local-action.md)** - 包含完整的配置步骤和故障排查指南

#### [调试工作流](.gitea/workflows/build-manus-clone-debug.yml)
保持容器运行 10 分钟，允许进入容器调试：
- 🐛 适合调试失败的 CI 环境
- 🔍 手动排查环境差异
- 📦 检查依赖和配置
- ⏱️ 自定义保持时间

📖 **[详细文档](docs/build-manus-clone-debug.md)**

### 前端项目部署

#### PNPM 构建部署系列

##### [标准 PNPM 部署](.gitea/workflows/build-with-pnpm-ssh.yaml) ⭐ 推荐
适用于已有代码仓库的 Vue.js 项目：
- 🐳 使用 `node:22-alpine` 容器环境
- ✅ 自动检查 `pnpm-lock.yaml` 文件
- 🔄 智能部署目录备份（带时间戳）
- 🚀 构建产物自动验证
- 📦 精确的文件路径控制

📖 **[详细文档](docs/build-pnpm-ssh.md)**

##### [从 Gitee 克隆 + PNPM 构建](.gitea/workflows/build-with-pnpm-ssh-from-gitee-clone.yaml)
适用于需要从外部仓库（如 Gitee）获取代码的场景：
- 🌐 支持从任意 Git 仓库克隆
- 📥 手动克隆代码到工作目录
- 🔧 使用 `actions/setup-node@v4` 配置环境
- ⏱️ 首次运行需下载 Node.js 环境

##### [Bookworm 容器 + PNPM](.gitea/workflows/build-with-pnpm-ssh-from-gitee-clone-use-bookworm.yaml)
基于 Debian Bookworm 的稳定构建环境：
- 🎯 使用 `node:22-bookworm` 镜像
- 🛡️ 避免 Alpine 兼容性问题
- 📦 完整的系统工具支持
- 🔧 适合复杂依赖项目

##### [Alpine 容器 + PNPM](.gitea/workflows/build-with-pnpm-ssh-from-gitee-clone-use-alpine.yaml)
轻量级 Alpine 镜像构建方案：
- 🪶 镜像体积小，启动快
- ⚙️ 需手动安装 git、bash、curl 等工具
- 💡 适合简单项目快速构建
- ⚠️ 注意 Alpine 特有的兼容性问题

#### NPM 构建部署

##### [NPM + Docker 容器部署](.gitea/workflows/build-with-npm-ssh.yaml)
基于 Docker 容器的 NPM 构建方案：
- 🐳 使用 `node:22-alpine` Docker 容器环境
- ✅ 自动检查 `package-lock.json` 文件
- 🔄 智能的部署目录备份机制
- 🚀 自动构建产物验证
- 📦 精确的文件部署路径控制 (`strip_components: 3`)

### 从外部仓库构建

#### [从 Gitee 克隆并构建](.gitea/workflows/build-gitea-starter-from-gitee.yml)
演示如何从 Gitee 等外部仓库克隆代码并部署：
- 🌐 手动克隆外部仓库
- 📤 SCP 文件传输
- 🔧 详细的 `strip_components` 使用说明
- 🔄 自动备份机制

📖 **[详细文档](docs/build-gitea-starter-from-gitee.md)** - 包含 `strip_components` 详解和路径控制说明

### SSH 操作工具

#### [SSH 文件传输示例](.gitea/workflows/build-ssh-action.yaml)
演示 SSH 连接和文件系统操作：
- 🔐 SSH 密钥认证
- 📁 测试不同目录的权限
- 💾 磁盘空间检查
- 👤 用户权限验证
  

## 主要特性

- ✨ **多种触发方式**：push、pull request、手动触发（workflow_dispatch）
- 🔒 **安全性**：SSH 密钥和 Secrets 管理
- 📦 **包管理器支持**：PNPM、NPM，支持锁文件验证
- 🚀 **自动化部署**：通过 SSH/SCP 部署到远程服务器
- 🔄 **智能备份**：部署前自动备份，带时间戳
- 🐳 **容器化构建**：支持 Alpine、Bookworm 等多种 Docker 镜像
- 🛠️ **可复用模板**：开箱即用的工作流模板
- ⚡ **性能优化**：本地 Actions 缓存，提升 50-70% 速度
- 🐛 **调试支持**：容器保活调试模式

## 工作流对比选择

### PNPM 工作流对比

| 特性 | 标准 PNPM | Gitee 克隆 | Bookworm 容器 | Alpine 容器 |
|------|----------|-----------|-------------|------------|
| **代码来源** | actions/checkout | 手动克隆 | 手动克隆 | 手动克隆 |
| **Node 环境** | 容器自带 | setup-node | 容器自带 | 容器自带 |
| **镜像大小** | 中等 | 依赖 setup-node | 较大 | 最小 |
| **启动速度** | 快 | 较慢 | 快 | 最快 |
| **兼容性** | 好 | 好 | 最好 | 需注意 |
| **适用场景** | 本仓库项目 | 外部仓库 | 复杂依赖 | 简单项目 |
| **推荐指数** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |

### NPM vs PNPM

| 对比项 | NPM | PNPM |
|-------|-----|------|
| **安装速度** | 较慢 | 快 2-3 倍 |
| **磁盘占用** | 较多 | 节省 50%+ |
| **lockfile** | package-lock.json | pnpm-lock.yaml |
| **适用场景** | 传统项目 | 现代项目 |
| **strip_components** | 3 | 2 |

## 配置要求

### 1. SSH 部署配置

在 Gitea 仓库的 **Settings → Secrets and variables → Actions** 中配置以下变量：

| Secret 名称 | 说明 | 示例 |
|------------|------|------|
| `SSH_HOST` | 服务器 IP 或域名 | `192.168.1.100` 或 `example.com` |
| `SSH_USER` | SSH 用户名 | `deploy` 或 `ubuntu` |
| `SSH_PRIVATE_KEY` | SSH 私钥内容 | 完整的 RSA/ED25519 私钥 |

#### SSH 密钥生成方法

```bash
# 1. 在本地生成 SSH 密钥对
ssh-keygen -t ed25519 -C "gitea-deploy" -f ~/.ssh/gitea_deploy

# 2. 将公钥添加到服务器
ssh-copy-id -i ~/.ssh/gitea_deploy.pub user@your-server

# 3. 复制私钥内容到 Gitea Secrets
cat ~/.ssh/gitea_deploy
# 将输出的完整内容（包括 BEGIN 和 END 行）添加到 SSH_PRIVATE_KEY
```

### 2. 包管理器配置

#### PNPM 配置（推荐 ⭐）

使用最新的 `pnpm/action-setup@v4` 版本：

```yaml
- uses: pnpm/action-setup@v4
  with:
    version: 10  # 或从 package.json 的 packageManager 字段自动读取
```

**v4 相比 v2 的优势**：
- ✅ 支持最新 Node.js 版本
- ✅ 更好的 packageManager 字段支持
- ✅ 改进的缓存机制
- ✅ 支持 standalone 模式

📖 详见 [PNPM Action Setup 说明](docs/pnpm-action-setup.md)

#### NPM 配置

**方式一：Docker 容器环境**（推荐用于简单项目）

```yaml
container:
  image: node:22-alpine
  options: --user root

steps:
  - name: Install bash in Alpine
    run: apk add --no-cache bash curl
  
  - name: Install dependencies
    run: npm ci
```

**方式二：setup-node Action**（推荐用于复杂项目）

```yaml
- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '22'
    cache: 'npm'
    cache-dependency-path: './your-project/package-lock.json'
```

### 3. 本地 Actions 配置（可选，性能优化）

如需离线运行和提速 50-70%，配置本地 Actions：

**Act Runner 配置文件** (`config.yaml`)：

```yaml
container:
  network: "bridge"
  options: "-v /opt/actions:/opt/actions:ro"
  valid_volumes:
    - /opt/actions
```

**宿主机准备**：

```bash
# 创建 actions 目录
sudo mkdir -p /opt/actions
cd /opt/actions

# 克隆常用 actions
sudo git clone https://github.com/actions/checkout.git
cd checkout && sudo git checkout v4 && cd ..

sudo git clone https://github.com/actions/setup-node.git
cd setup-node && sudo git checkout v4 && cd ..

# 设置权限
sudo chmod -R 755 /opt/actions
```

📖 详见 [本地 Actions 完整指南](docs/build-local-action.md)

## 最佳实践

### 1. 文件部署

#### strip_components 配置
根据项目结构选择合适的值：

```yaml
# 部署整个项目（保留项目目录结构）
source: "./gitea-vue-starter/*"
strip_components: 1

# 只部署 dist 内容到 Web 根目录
source: "./gitea-vue-starter/dist/*"
strip_components: 2  # PNPM 项目
strip_components: 3  # NPM 项目（如果工作目录多一层）
```

📖 详细说明请参考 [strip_components 详解](docs/build-gitea-starter-from-gitee.md#strip_components-详解)

#### 部署安全措施
- ✅ **自动备份**：部署前备份现有版本（带时间戳）
- ✅ **构建验证**：检查 dist 目录是否存在
- ✅ **部署验证**：检查目标目录文件完整性
- ✅ **权限控制**：使用专用部署用户，限制权限范围

### 2. 安全性

#### Secrets 管理
- 🔒 所有敏感信息使用 Gitea Secrets 存储
- 🔐 定期轮换 SSH 密钥（建议每 3-6 个月）
- 👤 使用专用部署账户，避免使用 root
- 🚫 不在日志中打印敏感信息

#### SSH 最佳实践
```yaml
# 推荐配置
timeout: 30s          # 设置超时避免挂起
use_insecure_cipher: false  # 使用安全加密
```

### 3. 工作流优化

#### 缓存策略
```yaml
# PNPM 缓存
- uses: actions/setup-node@v4
  with:
    cache: 'pnpm'
    cache-dependency-path: './your-project/pnpm-lock.yaml'

# NPM 缓存
- uses: actions/setup-node@v4
  with:
    cache: 'npm'
```

#### 触发条件优化
```yaml
# 生产环境：仅主分支推送时触发
on:
  push:
    branches: [ main, master ]
    paths-ignore:
      - '**.md'
      - 'docs/**'

# 开发环境：手动触发
on:
  workflow_dispatch:
```

#### 错误处理
```yaml
# 添加失败时的处理
- name: Build project
  run: pnpm run build
  continue-on-error: false

# 部署失败时通知
- name: Notify on failure
  if: failure()
  run: echo "::error::Deployment failed!"
```

### 4. 容器镜像选择

| 场景 | 推荐镜像 | 原因 |
|------|---------|------|
| **生产环境** | `node:22-bookworm` | 稳定、兼容性好 |
| **快速构建** | `node:22-alpine` | 体积小、启动快 |
| **复杂依赖** | `node:22-bookworm` | 完整工具链支持 |
| **调试开发** | `ubuntu:22.04` + setup-node | 工具丰富、易调试 |

## 文档索引

详细的文档和指南可以在 [docs](docs) 目录中找到：

### 基础教程
| 文档 | 说明 | 难度 |
|------|------|------|
| [build.md](docs/build.md) | Gitea Actions 基础概念和语法 | ⭐ |
| [build-gitea-starter-from-gitee.md](docs/build-gitea-starter-from-gitee.md) | 从外部仓库克隆和部署 + `strip_components` 详解 | ⭐⭐ |
| [build-manus-clone-debug.md](docs/build-manus-clone-debug.md) | 容器保活调试技巧 | ⭐⭐ |

### 进阶配置
| 文档 | 说明 | 难度 |
|------|------|------|
| [build-pnpm-ssh.md](docs/build-pnpm-ssh.md) | PNPM 构建与部署完整流程 | ⭐⭐⭐ |
| [build-local-action.md](docs/build-local-action.md) | 本地 Actions 配置完整指南（性能优化必读） | ⭐⭐⭐⭐ |
| [pnpm-action-setup.md](docs/pnpm-action-setup.md) | pnpm/action-setup@v4 vs @v2 对比 | ⭐⭐ |

## 常见问题

### Q1: 如何选择 PNPM 还是 NPM？

**推荐使用 PNPM**，优势明显：
- 安装速度快 2-3 倍
- 磁盘占用节省 50%+
- 更严格的依赖管理

**使用 NPM** 的场景：
- 旧项目已使用 NPM
- 需要特定 NPM 功能

### Q2: strip_components 应该设置为多少？

取决于你的源路径结构：

```bash
# 查看源路径层级
./gitea-vue-starter/dist/*
# 层级 1: gitea-vue-starter
# 层级 2: dist
# 层级 3: index.html, assets/, 等

# 只部署 dist 内容到根目录：strip_components: 2
# 保留 dist 目录：strip_components: 1
```

### Q3: 工作流运行很慢，如何优化？

**优化方法**：
1. ✅ 启用缓存（cache: 'pnpm' 或 'npm'）
2. ✅ 配置本地 Actions（提速 50-70%）
3. ✅ 使用轻量级镜像（alpine）
4. ✅ 合理设置触发条件（避免不必要的运行）

详见 [最佳实践](#最佳实践) 章节

### Q4: SSH 连接失败怎么办？

**排查步骤**：
1. 检查 Secrets 配置是否正确
2. 验证 SSH 密钥格式（需包含完整的 BEGIN/END 行）
3. 确认服务器防火墙允许 SSH 连接
4. 测试密钥是否能在本地连接服务器

```bash
# 本地测试
ssh -i ~/.ssh/gitea_deploy user@your-server
```

### Q5: 部署后文件权限不对？

在 SSH 脚本中添加权限设置：

```yaml
script: |
  TARGET_DIR="/home/user/web/app"
  # 部署后设置权限
  chown -R www-data:www-data $TARGET_DIR
  chmod -R 755 $TARGET_DIR
```

### Q6: 如何回滚到之前的版本？

工作流自动创建带时间戳的备份：

```bash
# SSH 到服务器
cd /home/user/web/

# 查看备份
ls -la | grep backup
# gitea-vue-app_backup_20241027_143000

# 回滚
rm -rf gitea-vue-app
mv gitea-vue-app_backup_20241027_143000 gitea-vue-app
```

## 相关资源

### 官方文档
- 📚 [Gitea Actions 官方文档](https://docs.gitea.com/zh-cn/)
- 🎯 [Act Runner 配置指南](https://docs.gitea.com/usage/actions/act-runner)
- 🔧 [Gitea Actions 市场](https://gitea.com/actions)

### 常用 Actions
- [actions/checkout](https://github.com/actions/checkout) - 代码检出
- [actions/setup-node](https://github.com/actions/setup-node) - Node.js 环境配置
- [pnpm/action-setup](https://github.com/pnpm/action-setup) - PNPM 配置
- [appleboy/ssh-action](https://github.com/appleboy/ssh-action) - SSH 命令执行
- [appleboy/scp-action](https://github.com/appleboy/scp-action) - SCP 文件传输

### 社区资源
- [GitHub Actions 文档](https://docs.github.com/zh/actions)（语法兼容）
- [Act 本地测试工具](https://github.com/nektos/act)

## 故障排查

### 容器启动失败

```yaml
# 错误：镜像拉取失败
Error: pull access denied for node:22-alpine

# 解决：检查镜像名称是否正确，或配置镜像加速
container:
  image: node:22-alpine  # 确认镜像名称
```

### Actions 下载失败

```yaml
# 错误：Unable to resolve action 'actions/checkout@v4'

# 解决方案 1：配置本地 Actions
# 见 docs/build-local-action.md

# 解决方案 2：使用镜像地址
uses: https://gitea.com/actions/checkout@v4
```

### 锁文件检查失败

```bash
# 错误：pnpm-lock.yaml not found

# 解决：确保锁文件存在并提交到仓库
git add pnpm-lock.yaml
git commit -m "Add lockfile"
git push
```

## 贡献指南

欢迎提交 Issue 和 Pull Request 来完善这个模板库！

### 贡献方式

1. **报告问题**
   - 发现 Bug 或文档错误
   - 提出新功能建议
   - 分享使用经验

2. **提交代码**
   - Fork 本仓库
   - 创建特性分支 (`git checkout -b feature/AmazingFeature`)
   - 提交更改 (`git commit -m 'Add some AmazingFeature'`)
   - 推送到分支 (`git push origin feature/AmazingFeature`)
   - 创建 Pull Request

### 贡献准则

- ✅ 保持示例的**简单性和可读性**
- ✅ 提供**详细的文档说明**和注释
- ✅ 遵循**最佳实践和安全准则**
- ✅ 确保工作流能够**正常运行**
- ✅ 更新相关文档（README 和 docs/）

### 文档贡献

特别欢迎以下类型的文档贡献：
- 📝 使用案例和实践经验
- 🐛 故障排查指南
- 🎯 性能优化技巧
- 🌍 多语言翻译

## 更新日志

### 2024-10 (最新)
- ✨ 添加多种 PNPM 构建工作流（Alpine、Bookworm）
- 📚 完善文档，添加详细的配置说明
- 🚀 优化 README 结构，添加快速开始指南
- 🐛 修复部分工作流中的路径问题

### 2024-09
- ✨ 初始版本发布
- 📦 基础工作流示例

## Star 历史

如果这个项目对你有帮助，欢迎点个 ⭐ Star！

## 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

---

<div align="center">

**📚 [文档索引](#文档索引) · 🚀 [快速开始](#快速开始) · 💡 [常见问题](#常见问题) · 🤝 [贡献指南](#贡献指南)**

Made with ❤️ for Gitea Actions Community

</div>