# laravelcms

**Repository Path**: jiangfeng2019/laravelcms

## Basic Information

- **Project Name**: laravelcms
- **Description**: laravelcms
- **Primary Language**: PHP
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-21
- **Last Updated**: 2025-12-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Laravel

## README

# Laravel + Vue 3 CMS 系统

一个基于 Laravel 和 Vue 3 开发的现代化 CMS 管理系统，提供了完整的用户管理、权限控制、内容管理等功能。

## 技术栈

### 后端
- **框架**: Laravel 10.x
- **认证**: Sanctum
- **权限管理**: Spatie Laravel Permission
- **API 文档**: Swagger (L5-Swagger)
- **数据库**: MySQL/SQLite
- **缓存**: Redis/File

### 前端
- **框架**: Vue 3
- **构建工具**: Vite
- **路由**: Vue Router
- **状态管理**: Pinia
- **UI 组件**: 原生 CSS (可扩展)
- **HTTP 客户端**: Axios

## 环境要求

### 后端
- PHP >= 8.1
- Composer >= 2.0
- MySQL >= 5.7 或 SQLite
- Node.js >= 16 (用于 Vite)

### 前端
- Node.js >= 16
- npm >= 8 或 yarn >= 1.22

## 安装步骤

### 1. 克隆项目

```bash
git clone <repository-url>
cd laravelcms
```

### 2. 后端安装

#### 2.1 配置环境变量

```bash
cd backend
cp .env.example .env
```

编辑 `.env` 文件，配置数据库和其他必要信息：

```env
# 数据库配置
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravelcms
DB_USERNAME=root
DB_PASSWORD=

# 应用配置
APP_URL=http://localhost:8000

# CORS 配置
SANCTUM_STATEFUL_DOMAINS=localhost:5173
```

#### 2.2 安装依赖

```bash
composer install
```

#### 2.3 生成应用密钥

```bash
php artisan key:generate
```

#### 2.4 运行数据库迁移

```bash
php artisan migrate
```

#### 2.5 运行数据种子

```bash
php artisan db:seed
```

#### 2.6 启动后端服务

```bash
php artisan serve
# 或使用 Laravel Octane (推荐用于生产环境)
# php artisan octane:start
```

后端服务将在 `http://localhost:8000` 启动。

### 3. 前端安装

#### 3.1 安装依赖

```bash
cd ../frontend
npm install
```

#### 3.2 配置环境变量

复制 `.env.example` 文件（如果存在）：

```bash
cp .env.example .env # 如果文件不存在，可跳过此步骤
```

编辑 `vite.config.js` 或创建 `.env` 文件，配置后端 API 地址：

```javascript
// vite.config.js
export default defineConfig({
  // ...
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8000',
        changeOrigin: true,
      },
    },
  },
})
```

#### 3.3 启动前端开发服务器

```bash
npm run dev
```

前端服务将在 `http://localhost:5173` 启动。

### 4. 访问系统

- 前端地址: http://localhost:5173
- 后端 API 地址: http://localhost:8000/api
- Swagger API 文档: http://localhost:8000/api/documentation

## 项目结构

### 后端结构

```
backend/
├── app/
│   ├── Http/
│   │   └── Controllers/       # 控制器目录
│   ├── Models/                # 模型目录
│   └── Providers/             # 服务提供者
├── bootstrap/                 # 引导目录
├── config/                    # 配置文件
├── database/                  # 数据库相关
│   ├── factories/             # 模型工厂
│   ├── migrations/            # 迁移文件
│   └── seeders/               # 种子文件
├── public/                    # 公共资源
├── resources/                 # 资源文件
├── routes/                    # 路由定义
│   ├── api.php                # API 路由
│   └── web.php                # Web 路由
├── storage/                   # 存储目录
└── tests/                     # 测试文件
```

### 前端结构

```
frontend/
├── public/                    # 公共资源
├── src/
│   ├── assets/                # 静态资源
│   ├── components/            # Vue 组件
│   ├── composables/           # 组合式函数
│   ├── layouts/               # 布局组件
│   ├── router/                # 路由配置
│   ├── stores/                # Pinia 状态管理
│   ├── views/                 # 页面组件
│   ├── App.vue                # 根组件
│   ├── main.js                # 入口文件
│   └── style.css              # 全局样式
└── vite.config.js             # Vite 配置
```

## 功能模块

### 1. 用户管理
- 用户列表展示
- 用户创建、编辑、删除
- 密码重置
- 用户角色分配

### 2. 角色与权限管理
- 角色列表展示
- 角色创建、编辑、删除
- 权限列表展示
- 权限分配（角色-权限关系）

### 3. 内容管理
- 文章列表展示
- 文章创建、编辑、删除
- 文章分类管理
- 富文本编辑器支持（可扩展）

### 4. 系统设置
- 网站基本信息配置
- 系统参数设置

### 5. 捐赠管理
- 捐赠列表展示
- 捐赠记录管理

### 6. 安装向导
- 数据库连接配置
- 管理员账户创建
- 系统初始化

## API 文档

系统提供了完整的 Swagger API 文档，访问地址：

```
http://localhost:8000/api/documentation
```

### 生成 API 文档

```bash
cd backend
php artisan l5-swagger:generate
```

## 开发指南

### 后端开发

1. **创建新模型**：
   ```bash
   php artisan make:model ModelName -mcr
   ```

2. **创建新控制器**：
   ```bash
   php artisan make:controller Api/ControllerName --api
   ```

3. **创建新迁移**：
   ```bash
   php artisan make:migration create_table_name
   ```

4. **创建新种子**：
   ```bash
   php artisan make:seeder SeederName
   ```

### 前端开发

1. **创建新页面**：
   ```bash
   # 在 src/views/ 目录下创建新的 Vue 组件
   ```

2. **添加路由**：
   ```javascript
   // 在 src/router/index.js 中添加路由
   ```

3. **创建新 Store**：
   ```bash
   npm run pinia:create store-name
   ```

## 测试

### 后端测试

```bash
cd backend
php artisan test
```

### 前端测试

```bash
cd frontend
npm run test
```

## 部署

### 后端部署

1. **优化自动加载**：
   ```bash
   composer install --optimize-autoloader --no-dev
   ```

2. **缓存配置**：
   ```bash
   php artisan config:cache
   php artisan route:cache
   php artisan view:cache
   ```

3. **设置存储目录权限**：
   ```bash
   chmod -R 775 storage bootstrap/cache
   ```

### 前端部署

1. **构建生产版本**：
   ```bash
   cd frontend
   npm run build
   ```

2. **部署构建产物**：
   - 将 `dist/` 目录下的文件部署到 web 服务器根目录
   - 或配置 web 服务器指向 `dist/` 目录

## 常见问题

### 1. 跨域问题

确保在 `.env` 文件中正确配置了 CORS 和 Sanctum 相关参数：

```env
SANCTUM_STATEFUL_DOMAINS=your-domain.com
SESSION_DOMAIN=.your-domain.com
```

### 2. 数据库连接问题

确保 `.env` 文件中的数据库配置正确，且数据库服务正在运行：

```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your-database
DB_USERNAME=your-username
DB_PASSWORD=your-password
```

### 3. API 认证问题

确保在请求头中包含正确的认证令牌：

```
Authorization: Bearer {your-token}
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### v1.0.0
- 初始版本发布
- 实现了基本的用户管理、角色权限管理、内容管理等功能
- 提供了完整的 API 文档
- 支持安装向导