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

开发环境设置

安装依赖

pnpm install

启动开发服务器

pnpm dev

构建生产版本

pnpm build

预览生产构建

pnpm preview

Gitea Runner NPM 缓存配置

问题背景

在容器化环境中，Gitea Runner 每次构建都需要重新下载 npm 包，导致构建时间过长。通过配置持久化缓存可以显著提升构建效率。

缓存策略

1. pnpm 缓存: 缓存 pnpm 全局缓存目录
2. node_modules 缓存: 缓存项目依赖
3. 构建产物缓存: 缓存构建输出

配置步骤

1. 配置 Gitea Runner 容器

在运行 Gitea Runner 容器时，需要挂载缓存目录：

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 中配置缓存步骤：

- 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静态文件服务目录

设置缓存目录

运行以下命令设置宿主机缓存目录：

# 给脚本执行权限
chmod +x scripts/setup-cache-directory.sh

# 设置缓存目录
sudo ./scripts/setup-cache-directory.sh

修复Runner挂载问题

如果遇到Runner容器挂载问题，运行以下命令：

# 检查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             # 项目文档

构建和部署

本地构建

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 进行代码格式化和检查：

# 格式化代码
pnpm biome format

# 检查代码
pnpm biome check

Git 提交规范

• feat: 新功能
• fix: 修复问题
• docs: 文档更新
• style: 代码格式调整
• refactor: 代码重构
• test: 测试相关
• chore: 构建过程或辅助工具的变动

故障排除

常见问题

1. 缓存不生效: 检查挂载目录权限和路径配置
2. 构建失败: 检查 Node.js 版本和依赖完整性
3. 依赖安装慢: 确认镜像源配置正确

日志查看

# 查看 Runner 日志
docker logs gitea-runner

# 查看构建日志
# 在 Gitea Web 界面中查看 Actions 日志

更新日志

v1.0.0

• 初始项目搭建
• 配置 Gitea Runner 缓存
• 实现基础 CI/CD 流程