23bef2484e
- 新增 CI/CD 工作流文件，实现前端项目的自动构建和部署 - 支持 main、master 和 develop 分支的自动构建- 包含代码检出、环境安装、依赖管理、项目构建等步骤 - 实现构建产物的自动部署和 Docker 容器重启
253 lines
5.5 KiB
Markdown
253 lines
5.5 KiB
Markdown
# Epic UI - 现代化前端项目
|
||
|
||
## 项目简介
|
||
|
||
Epic UI 是一个基于 React + TypeScript + Rsbuild 构建的现代化前端项目，采用 Tailwind CSS 作为样式框架，Ant Design 作为 UI 组件库。
|
||
|
||
## 技术栈
|
||
|
||
- **框架**: React 19.1.0 + TypeScript 5.8.2
|
||
- **构建工具**: Rsbuild 1.3.1
|
||
- **包管理器**: pnpm
|
||
- **样式**: Tailwind CSS 4.1.4
|
||
- **UI组件**: Ant Design 5.26.3
|
||
- **路由**: React Router DOM 7.5.0
|
||
- **代码规范**: Biome 1.9.4
|
||
|
||
## 开发环境设置
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
### 启动开发服务器
|
||
|
||
```bash
|
||
pnpm dev
|
||
```
|
||
|
||
### 构建生产版本
|
||
|
||
```bash
|
||
pnpm build
|
||
```
|
||
|
||
### 预览生产构建
|
||
|
||
```bash
|
||
pnpm preview
|
||
```
|
||
|
||
## Gitea Runner NPM 缓存配置
|
||
|
||
### 问题背景
|
||
|
||
在容器化环境中，Gitea Runner 每次构建都需要重新下载 npm 包，导致构建时间过长。通过配置持久化缓存可以显著提升构建效率。
|
||
|
||
### 缓存策略
|
||
|
||
1. **pnpm 缓存**: 缓存 pnpm 全局缓存目录
|
||
2. **node_modules 缓存**: 缓存项目依赖
|
||
3. **构建产物缓存**: 缓存构建输出
|
||
|
||
### 配置步骤
|
||
|
||
#### 1. 配置 Gitea Runner 容器
|
||
|
||
在运行 Gitea Runner 容器时，需要挂载缓存目录：
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name gitea-runner \
|
||
--restart=always \
|
||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||
-v /opt/gitea-runner-cache:/opt/hostedtoolcache \
|
||
-v /opt/gitea-runner-data:/data \
|
||
gitea/act_runner:latest
|
||
```
|
||
|
||
#### 2. 配置 CI 工作流
|
||
|
||
在 `.gitea/workflows/ci.yaml` 中配置缓存步骤：
|
||
|
||
```yaml
|
||
- name: 恢复 pnpm 缓存
|
||
shell: bash
|
||
run: |
|
||
if [ -d "/cache/pnpm-store" ]; then
|
||
echo "恢复 pnpm 缓存..."
|
||
mkdir -p ~/.pnpm-store
|
||
cp -r /cache/pnpm-store/* ~/.pnpm-store/ 2>/dev/null || true
|
||
fi
|
||
|
||
- name: 安装依赖
|
||
shell: bash
|
||
run: |
|
||
pnpm install --frozen-lockfile
|
||
|
||
- name: 保存 pnpm 缓存
|
||
shell: bash
|
||
run: |
|
||
echo "保存 pnpm 缓存..."
|
||
mkdir -p /cache/pnpm-store
|
||
cp -r ~/.pnpm-store/* /cache/pnpm-store/ 2>/dev/null || true
|
||
```
|
||
|
||
### 缓存目录说明
|
||
|
||
- **宿主机路径**: `/opt/gitea-runner-cache`
|
||
- **容器内路径**: `/opt/hostedtoolcache`
|
||
- **缓存内容**:
|
||
- `node_modules_*.tar.gz`: 项目依赖缓存（基于pnpm-lock.yaml哈希）
|
||
- `pnpm-store/`: pnpm 全局缓存
|
||
- `pnpm-cache/`: pnpm 缓存目录
|
||
|
||
### 生产环境目录
|
||
|
||
- **宿主机路径**: `/opt/1panel/apps/openresty/openresty/www/sites/epic7`
|
||
- **容器内路径**: `/opt/prod`
|
||
- **用途**: nginx静态文件服务目录
|
||
|
||
### 设置缓存目录
|
||
|
||
运行以下命令设置宿主机缓存目录：
|
||
|
||
```bash
|
||
# 给脚本执行权限
|
||
chmod +x scripts/setup-cache-directory.sh
|
||
|
||
# 设置缓存目录
|
||
sudo ./scripts/setup-cache-directory.sh
|
||
```
|
||
|
||
### 修复Runner挂载问题
|
||
|
||
如果遇到Runner容器挂载问题，运行以下命令：
|
||
|
||
```bash
|
||
# 检查Runner状态
|
||
chmod +x scripts/check-runner.sh
|
||
./scripts/check-runner.sh
|
||
|
||
# 修复挂载问题
|
||
chmod +x scripts/fix-runner-mount.sh
|
||
sudo ./scripts/fix-runner-mount.sh
|
||
```
|
||
|
||
### 性能优化建议
|
||
|
||
1. **使用国内镜像源**: 配置 `.npmrc` 使用 npmmirror.com
|
||
2. **启用离线模式**: 设置 `prefer-offline=true`
|
||
3. **并行安装**: 使用 `--parallel` 参数
|
||
4. **缓存清理**: 定期清理过期缓存
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
epic-ui/
|
||
├── src/ # 源代码目录
|
||
├── public/ # 静态资源
|
||
├── .gitea/ # Gitea CI/CD 配置
|
||
├── package.json # 项目配置
|
||
├── pnpm-lock.yaml # 依赖锁定文件
|
||
├── tsconfig.json # TypeScript 配置
|
||
├── rsbuild.config.ts # Rsbuild 构建配置
|
||
└── README.md # 项目文档
|
||
```
|
||
|
||
## 构建和部署
|
||
|
||
### 本地构建
|
||
|
||
```bash
|
||
pnpm build
|
||
```
|
||
|
||
### CI/CD 构建
|
||
|
||
项目使用 Gitea Actions 进行自动化构建和部署：
|
||
|
||
1. 代码推送到 main/master 分支触发构建
|
||
2. 自动安装依赖（使用缓存加速）
|
||
3. 构建生产版本
|
||
4. 部署到nginx静态文件目录
|
||
|
||
### 部署配置
|
||
|
||
项目构建产物会自动部署到nginx静态文件目录：
|
||
|
||
- **宿主机路径**: `/opt/1panel/apps/openresty/openresty/www/sites/epic7`
|
||
- **容器内路径**: `/opt/prod`
|
||
- **部署方式**: 直接覆盖nginx静态文件目录
|
||
- **备份策略**: 部署前自动备份当前版本
|
||
|
||
#### 部署流程
|
||
|
||
1. **构建**: 在容器内执行 `pnpm build` 生成 `dist/` 目录
|
||
2. **备份**: 备份当前生产环境文件（如果存在）
|
||
3. **部署**: 清空nginx目录并复制构建产物
|
||
4. **权限设置**: 设置文件权限为755
|
||
|
||
#### 访问方式
|
||
|
||
部署完成后，可以通过nginx访问：
|
||
- 本地访问: `http://localhost`
|
||
- 域名访问: 根据nginx配置的域名
|
||
|
||
### 构建产物
|
||
|
||
构建完成后，产物位于 `dist/` 目录：
|
||
- `index.html`: 主页面
|
||
- `assets/`: 静态资源（JS、CSS、图片等）
|
||
|
||
## 开发规范
|
||
|
||
### 代码风格
|
||
|
||
项目使用 Biome 进行代码格式化和检查：
|
||
|
||
```bash
|
||
# 格式化代码
|
||
pnpm biome format
|
||
|
||
# 检查代码
|
||
pnpm biome check
|
||
```
|
||
|
||
### Git 提交规范
|
||
|
||
- feat: 新功能
|
||
- fix: 修复问题
|
||
- docs: 文档更新
|
||
- style: 代码格式调整
|
||
- refactor: 代码重构
|
||
- test: 测试相关
|
||
- chore: 构建过程或辅助工具的变动
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **缓存不生效**: 检查挂载目录权限和路径配置
|
||
2. **构建失败**: 检查 Node.js 版本和依赖完整性
|
||
3. **依赖安装慢**: 确认镜像源配置正确
|
||
|
||
### 日志查看
|
||
|
||
```bash
|
||
# 查看 Runner 日志
|
||
docker logs gitea-runner
|
||
|
||
# 查看构建日志
|
||
# 在 Gitea Web 界面中查看 Actions 日志
|
||
```
|
||
|
||
## 更新日志
|
||
|
||
### v1.0.0
|
||
- 初始项目搭建
|
||
- 配置 Gitea Runner 缓存
|
||
- 实现基础 CI/CD 流程
|