1.1 技术栈#

2.1 安装依赖#

项目使用 pnpm 作为包管理工具，首先确保已安装 pnpm：

1
npm install -g pnpm

然后安装项目依赖：

1
cd ai-fire-admin
2
pnpm install

2.2 配置文件#

项目包含两个主要的环境配置文件：

• .env.development：开发环境配置
• .env.production：生产环境配置

配置文件中定义了 API 基础路径等关键信息，可根据实际情况修改：

1
# 开发环境示例
2
VITE_API_BASE_URL = '/api'

2.3 启动开发服务器#

1
pnpm dev

开发服务器默认会在 http://localhost:5173 启动。

3.1 核心目录说明#

1
import request from '@/utils/http'
2

3
export const getSiteInfoList = () => {
4
  return request.get('/api/website/info/list')
5
}
6

7
export const createSiteInfo = (data: any) => {
8
  return request.post('/api/website/info/create', data)
9
}

1
import { createRouter, createWebHistory } from 'vue-router'
2
import DefaultLayout from '@/layouts/default-layout.vue'
3

4
const router = createRouter({
5
  history: createWebHistory(import.meta.env.BASE_URL),
6
  routes: [
7
    {
8
      path: '/',
9
      name: 'home',
10
      component: DefaultLayout,
11
      children: [
12
        {
13
          path: '',
14
          name: 'dashboard',
15
          component: () => import('../views/dashboard/index.vue')
16
        }
17
        // 其他路由...
18
      ]
19
    },
20
    {
21
      path: '/login',
22
      name: 'login',
23
      component: () => import('../views/login/index.vue')
24
    }
25
  ]
26
})

1
import { defineStore } from 'pinia'
2
import * as websiteInfoApi from '@/apis/website-info'
3

4
export const useWebsiteInfoStore = defineStore('websiteInfo', {
5
  state: () => ({
6
    websiteInfoList: []
7
  }),
8
  actions: {
9
    async getSiteInfoListAction() {
10
      const res = await websiteInfoApi.getSiteInfoList()
11
      this.websiteInfoList = res.data
12
      return res.data
13
    }
14
  }
15
})

4.1 登录与权限管理#

系统实现了基于 JWT 的登录认证机制：

1. 用户输入账号密码登录
2. 后端验证通过后返回 JWT token
3. 前端将 token 存储到 localStorage
4. 后续请求通过 Authorization 头携带 token

登录逻辑实现：

1
const handleLogin = async () => {
2
  try {
3
    const res = await userApi.login(formData.value)
4
    localStorage.setItem('token', res.data.token)
5
    router.push('/')
6
    message.success('登录成功')
7
  } catch (error) {
8
    message.error('登录失败')
9
  }
10
}

4.2 网站信息管理#

网站信息管理模块用于配置博客系统的基本信息，如标题、标语、封面、版权信息等。

主要功能：

• 查看网站信息列表
• 选择并查看详情
• 编辑网站信息
• 创建新的网站信息

实现细节：

1
<Table
2
  :data-source="dataSource"
3
  :columns="columns"
4
  ref="table"
5
  @edit="edit"
6
  @change="handleTableChange"
7
>
8
  <!-- 表格内容 -->
9
</Table>
10

11
<a-descriptions bordered style="margin-top: 20px;">
12
  <a-descriptions-item label="网站标题">{{ websiteInfo.title }}</a-descriptions-item>
13
  <!-- 其他信息项 -->
14
</a-descriptions>

4.3 博客管理#

博客管理模块用于管理博客文章，支持以下功能：

• 博客列表展示与分页
• 博客文章的创建、编辑、删除
• 富文本编辑
• 分类与标签管理
• 状态管理（已发布/草稿）

4.4 分类管理#

分类管理模块用于管理博客文章的分类，支持：

• 分类列表展示
• 分类的创建、编辑、删除
• 分类排序
• 分类状态管理

4.5 仪表盘#

仪表盘模块提供系统概览，包括：

• 博客文章统计
• 分类统计
• 访问量统计
• 最新动态

5.1 添加新页面#

1. 在 src/views/ 目录下创建新的页面组件
2. 在 src/router/ 中配置路由
3. 在侧边栏菜单中添加新的菜单项

示例：添加新页面

1
<template>
2
  <div class="new-page">
3
    <h1>新页面</h1>
4
  </div>
5
</template>
6

7
<script setup lang="ts">
8
// 页面逻辑
9
</script>

1
const router = createRouter({
2
  // ...
3
  routes: [
4
    {
5
      path: '/',
6
      component: DefaultLayout,
7
      children: [
8
        // ...
9
        {
10
          path: '/new-page',
11
          name: 'newPage',
12
          component: () => import('../views/new-page/index.vue')
13
        }
14
      ]
15
    }
16
  ]
17
})

5.2 添加新组件#

1. 在 src/components/ 目录下创建新的组件
2. 在需要使用的地方导入并使用

示例：创建新组件

1
<template>
2
  <div class="my-component">
3
    <slot></slot>
4
  </div>
5
</template>
6

7
<script setup lang="ts">
8
// 组件逻辑
9
</script>

5.3 扩展 API#

1. 在 src/apis/ 目录下创建新的 API 文件
2. 定义 API 函数
3. 在组件或 store 中使用

示例：添加新 API

1
import request from '@/utils/http'
2

3
export const getNewData = () => {
4
  return request.get('/api/new-data')
5
}

5.4 自定义主题#

系统使用 Ant Design Vue 的主题定制功能，可以通过修改 src/assets/css/variables.less 文件来自定义主题颜色：

1
// 自定义主题色
2
@primary-color: #1890ff;
3
@success-color: #52c41a;
4
@warning-color: #faad14;
5
@error-color: #f5222d;

6.1 构建生产版本#

1
pnpm build

构建后的文件会输出到 dist/ 目录。

6.2 Nginx 配置#

项目提供了 Nginx 配置文件 nginx/nginx.conf，可根据实际情况修改：

1
# 全局配置
2
user nginx;
3
worker_processes auto;
4

5
# http 配置
6
http {
7
    include       mime.types;
8
    default_type  application/octet-stream;
9

10
    # 服务器配置
11
    server {
12
        listen       8080;
13
        server_name  localhost;
14

15
        # 前端静态资源
16
        location / {
17
            root   /usr/share/nginx/html;
18
            index  index.html index.htm;
19
            try_files $uri $uri/ /index.html;
20
        }
21

22
        # API 代理
23
        location /api {
24
            proxy_pass http://127.0.0.1:29090;
25
            proxy_set_header Host $host;
26
            proxy_set_header X-Real-IP $remote_addr;
27
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
28
            proxy_set_header X-Forwarded-Proto $scheme;
29
        }
30
    }
31
}

6.3 部署步骤#

1. 将构建后的 dist/ 目录上传到服务器的 /usr/share/nginx/html/ 目录
2. 将 Nginx 配置文件复制到服务器的 /etc/nginx/conf.d/ 目录
3. 重新加载 Nginx 配置：

   1
   nginx -s reload

7.1 代码风格#

项目使用 ESLint 和 Prettier 来保证代码风格的一致性，提交代码前会自动进行检查。

7.2 命名规范#

• 组件名：大驼峰命名，如 WebsiteInfo
• 文件/目录名：小写字母加短横线，如 website-info.vue
• 变量名：小驼峰命名，如 websiteInfoList
• 常量名：全大写加下划线，如 API_BASE_URL

7.3 注释规范#

• 组件和函数使用 JSDoc 注释
• 复杂逻辑添加必要的单行注释
• 代码变更添加提交注释

8.1 跨域问题#

开发环境中，Vite 配置了代理解决跨域问题：

1
export default defineConfig({
2
  // ...
3
  server: {
4
    proxy: {
5
      '/api': {
6
        target: 'http://localhost:29090',
7
        changeOrigin: true
8
      }
9
    }
10
  }
11
})

生产环境中，通过 Nginx 代理解决跨域问题。

8.2 构建失败#

• 检查依赖是否正确安装
• 检查 TypeScript 类型是否正确
• 检查语法错误

8.3 页面空白#

• 检查路由配置是否正确
• 检查组件是否正确导入
• 检查网络请求是否正常