# 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-store/`: pnpm 全局缓存
  - `build-cache/`: 构建产物缓存

### 设置缓存目录

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

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

# 设置缓存目录
sudo ./scripts/setup-cache-directory.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. 部署到目标服务器

### 构建产物

构建完成后，产物位于 `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 流程