智慧门禁系统 — 部署与使用文档

项目名称: porject_gd（智慧门禁系统）
技术栈: Vue 3 + Vue Router + Vuex + Ant Design Vue + ECharts + Axios
构建工具: Vue CLI 5（基于 Webpack）
Node.js 版本要求: >= 14.x（推荐 16.x 或 18.x LTS）

---

目录

• 1. 项目概述
• 2. 环境要求
• 3. 快速开始（开发环境）
• 4. 生产环境部署
  • 4.1 构建生产包
  • 4.2 Nginx 部署
  • 4.3 IIS 部署
  • 4.4 其他 Web 服务器部署
• 5. 后端 API 对接说明
• 6. 项目功能模块说明
• 7. 路由与权限说明
• 8. 配置文件说明
• 9. 常见问题排查

---

1. 项目概述

本项目是一个智慧门禁管理系统的前端部分，提供以下核心功能：

项目后端地址: https://github.com/hbbc123/AccessControl-java

功能模块	说明
管理员登录	系统入口，支持管理员和普通用户登录
人脸闸机管理	管理人脸识别闸机设备及其进出记录
车辆闸机/停车场管理	管理车辆进出闸机、VIP 车位
访客管理	访客登记、审批、查询
用户管理	内部人员信息管理、人脸录入
内部车辆管理	内部车辆登记与管理
收费管理	停车场收费规则配置与收费记录查询
系统设置	系统参数配置
路由/权限管理	页面路由和用户权限分配
统计报表	人员出入统计、收入统计
移动端	适配移动端的访客登记、人员查询等功能

前端页面通过 Axios 调用后端 RESTful API（默认转发至 http://127.0.0.1:666），实现数据的增删改查操作。

---

2. 环境要求

依赖项	版本要求	说明
Node.js	>= 14.x（推荐 16.x / 18.x LTS）	JavaScript 运行环境
npm	>= 6.x（随 Node.js 自带）	包管理工具
后端 API 服务	Java 后端（监听 666 端口）	需先部署后端服务

⚠️ 重要: 前端项目本身不包含后端代码，部署前请确保后端 API 服务已正常运行。

---

3. 快速开始（开发环境）

3.1 克隆/获取项目

将项目代码放置到目标目录，例如 d:/java/bs/porject_accessControl。

3.2 安装依赖

在项目根目录下打开终端，执行：

npm install

该命令会根据 package.json 和 package-lock.json 安装所有依赖包。

主要依赖包括：

包名	版本	用途
vue	^3.2.13	前端框架
vue-router	^4.0.3	前端路由
vuex	^4.0.0	状态管理
ant-design-vue	^4.2.6	UI 组件库
ant-design-x-vue	^1.1.0	Ant Design X 扩展组件
axios	^1.8.3	HTTP 请求库
echarts	^5.6.0	图表库
echarts-gl	^2.0.9	ECharts 3D 扩展
vue-echarts	^7.0.3	ECharts 的 Vue 封装
docx-preview	^0.3.5	Word 文档预览
reset-css	^5.0.2	CSS 重置样式

3.3 启动开发服务器

npm run serve

启动成功后，终端会显示类似以下信息：

  App running at:
  - Local:   http://localhost:8080/
  - Network: http://192.168.x.x:8080/

在浏览器中打开 http://localhost:8080 即可访问。

3.4 开发代理说明

开发环境下，/api 路径的请求会被代理转发到后端服务。代理配置位于 vue.config.js：

devServer: {
    proxy: {
        "/api": {
            target: "http://127.0.0.1:666",   // 后端服务地址
            changeOrigin: true,
            pathRewrite: {
                "^/api": "/",                   // 将 /api 前缀重写为 /
            },
        },
    },
},

例如前端请求 /api/admin/login 实际会被转发到 http://127.0.0.1:666/admin/login。

如需修改后端地址，编辑 vue.config.js 中的 target 字段后重启开发服务器。

---

4. 生产环境部署

4.1 构建生产包

在项目根目录执行：

npm run build

构建完成后，产物位于 dist/ 目录下，包含：

dist/
├── index.html          # 入口 HTML 文件
├── favicon.ico         # 网站图标
├── css/                # 样式文件（含 hash）
├── js/                 # JavaScript 文件（含 hash）
└── images/             # 图片资源（如有）

注意: 生产构建使用相对路径（publicPath: './'），因此可将 dist/ 部署到任意目录层级。

4.2 Nginx 部署

4.2.1 静态文件部署

将 dist/ 目录的内容复制到 Nginx 的 web 根目录（例如 /usr/share/nginx/html/ 或自定义路径），然后配置 Nginx：

server {
    listen       80;
    server_name  your-domain.com;   # 替换为实际域名或 IP

    # 前端静态资源
    location / {
        root   /path/to/dist;       # 替换为 dist 目录的实际路径
        index  index.html;
        try_files $uri $uri/ /index.html;  # 支持 Vue Router history 模式
    }

    # API 反向代理到后端
    location /api/ {
        proxy_pass http://127.0.0.1:666/;   # 后端服务地址
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

说明: Nginx 配置中的 proxy_pass http://127.0.0.1:666/; 末尾带 /，会自动去除 /api 前缀，与开发代理行为一致。

4.2.2 重载 Nginx

nginx -t                # 检查配置是否正确
nginx -s reload         # 重载配置

4.3 IIS 部署

4.3.1 准备工作

1. 安装 IIS（Internet Information Services）及 URL Rewrite 模块
2. 将 dist/ 目录内容复制到 IIS 站点根目录

4.3.2 配置 web.config

在 dist/ 目录下创建 web.config 文件：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <!-- 支持 Vue Router（history 模式回退到 index.html） -->
                <rule name="Vue Router" stopProcessing="true">
                    <match url=".*" />
                    <conditions logicalGrouping="MatchAll">
                        <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
                        <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
                        <add input="{REQUEST_URI}" pattern="^/api/" negate="true" />
                    </conditions>
                    <action type="Rewrite" url="/index.html" />
                </rule>
            </rules>
        </rewrite>

        <!-- API 反向代理（需要安装 ARR 模块） -->
        <!-- 如果不需要 IIS 代理，可以在前端 Axios 配置中直接指向后端地址 -->
    </system.webServer>
</configuration>

4.3.3 注意

• Vue 项目使用 Hash 路由模式（createWebHashHistory），因此大部分情况下不需要 URL Rewrite 回退配置也能正常工作。
• 如果 IIS 直接部署且后端不在同一台机器，需要修改 Axios 的 baseURL（见 第 5 节），然后重新构建。

4.4 其他 Web 服务器部署

• Apache: 启用 mod_rewrite，配置 .htaccess 将非文件请求重写到 index.html
• Tomcat: 将 dist/ 内容放入 webapps/ROOT/ 目录
• 静态资源托管服务: 如阿里云 OSS、腾讯云 COS、Nginx 等，直接上传 dist/ 目录内容即可

---

5. 后端 API 对接说明

5.1 默认配置

开发环境下，API 请求基地址为 /api，通过 webpack-dev-server 代理转发到 http://127.0.0.1:666。

5.2 修改后端地址

文件中有一行被注释的代码，位于 src/request/request.js 第 4 行：

// axios.defaults.baseURL = "http://139.9.103.141:666";

如果前后端分离部署（不在同一台机器或不同端口），有两种方式配置：

方式一（推荐）: 通过 Nginx 等反向代理统一转发，前端无需修改。

方式二: 修改 src/request/request.js 中的 baseURL 为后端实际地址，然后重新 npm run build：

// 修改 axios 实例的 baseURL
const instance = axios.create({
    baseURL: "http://你的后端IP:666",   // 改为实际后端地址
    withCredentials: true,
});

同时也需要修改 axios.defaults.baseURL（第 3 行）。

5.3 API 端点清单

所有 API 接口定义在 src/request/api.js 中，主要包括：

模块	端点前缀	说明
管理员	/admin/	登录、增删改查
人脸闸机	/gate/	闸机列表、新增、修改
VIP 停车场	/vipParkingLot/	车位管理、车辆审批
人脸记录	/userface/	人脸闸机进出记录
收费记录	/feeRecords/	车辆进出记录
收费规则	/charge/	车场收费规则 CRUD
地址/单位	/unit/	单位信息管理
收费标准	/tariff/	收费列表查询
访客管理	/visitor/	访客登记、审批、删除
用户管理	/user/	用户 CRUD、人脸更新、登录
内部车辆	/userCar/	内部车辆管理
路由权限	/routingRole/	路由角色管理
页面路由	/pageRouter/	页面路由配置
系统设置	/settings/	系统参数
统计	/system/	统计报表
人脸记录	/faceRecord/	人员进出记录

---

6. 项目功能模块说明

6.1 登录模块

• 页面: src/views/LoginView.vue
• 路由: /（根路径）
• 功能: 管理员/用户登录，登录后获取用户权限路由表

6.2 主页/管理后台

• 页面: src/views/Home.vue + 子路由页面
• 路由: /home
• 子模块:

  子路由	页面文件	功能
  gate	GateView.vue	人脸闸机管理
  gate-table	GateTableView.vue	人脸闸机进出记录
  parking	Parking.vue	车辆闸机/停车场管理
  parking-table	ParkingTableView.vue	车辆进出记录
  fees	VehicleFees.vue	车辆收费管理
  unit	Unit.vue	地址/单位管理
  tariff	TariffTable.vue	收费标准查询
  visitor-table	VisitorTableView.vue	访客登记管理
  user	UserView.vue	用户管理
  internal	Internal.vue	内部车辆管理
  admin	Admin.vue	管理员管理
  system	System.vue	系统设置
  strategy	Strategy.vue	策略配置
  statistics	Statistics.vue	统计报表
  personFace	PersonFace.vue	人员进出记录
  pageRouterView	PageRouterView.vue	页面路由查看
  pageRouterRootView	PageRouterRootView.vue	页面路由权重管理
  rootview	RouterView.vue	路由查看

6.3 3D 可视化页面

• 页面: src/views/C.vue
• 路由: /c
• 功能: 使用 Three.js 和 Vanta.js 实现 3D 背景效果的大屏展示页面

6.4 移动端

• 页面: src/views/Mobile.vue + 子路由
• 路由: /mobile
• 子模块:

  子路由	页面文件	功能
  visit-table	VisitView.vue	移动端访客登记
  moveUser	MoveUser.vue	移动端人员操作
  searchVisitor	SearchVisitor.vue	移动端访客查询

---

7. 路由与权限说明

7.1 路由模式

项目使用 Hash 路由模式（createWebHashHistory），URL 格式为：

http://your-domain/#/home/gate

7.2 路由守卫

路由守卫逻辑在 src/router/index.js 的 router.beforeEach 中：

• 白名单路径（无需权限即可访问）:

  • / — 登录页
  • /c — 3D 大屏页面
  • /mobile/moveUser — 移动端人员操作
  • /mobile/searchVisitor — 移动端访客查询
  • /mobile/visit-table — 移动端访客登记
  • /model/* — 模型相关通配路径

• 权限校验: 其他所有路径必须在用户的路由权限列表（store.state.userRouterList）中存在，否则重定向到登录页 /。

7.3 权限数据流

1. 用户登录成功 → 后端返回用户权限路由列表
2. 前端调用 store.commit('SET_USER_ROUTER_LIST', ...) 存储权限
3. 导航守卫检查目标路径是否在权限列表中
4. 有权限则放行，无权限则跳回登录页

---

8. 配置文件说明

8.1 核心配置文件

文件	说明
package.json	项目依赖、脚本命令
vue.config.js	Vue CLI 配置（publicPath、devServer 代理）
babel.config.js	Babel 编译配置
jsconfig.json	VS Code 路径别名配置（@ → src/）
.gitignore	Git 忽略文件配置

8.2 源码目录结构

src/
├── App.vue                     # 根组件（Ant Design 国际化配置）
├── main.js                     # 入口文件（注册插件）
├── assets/                     # 静态资源（图片等）
├── components/                 # 公共组件
│   ├── HelloWorld.vue          # 示例组件
│   ├── SexRatio.vue            # 性别比例统计组件
│   ├── StatisticsCountTheNumberOfPeopleByConstructionSite.vue  # 工地人数统计
│   └── WageStatistics.vue      # 工资统计组件
├── hooks/                      # 组合式函数
│   └── myHooks.js              # 通知提示 Hook
├── request/                    # HTTP 请求封装
│   ├── api.js                  # API 接口定义
│   └── request.js              # Axios 实例与拦截器
├── router/                     # 路由配置
│   └── index.js                # 路由定义与守卫
├── store/                      # 状态管理
│   └── index.js                # Vuex Store（权限列表）
├── util/                       # 工具库
│   ├── three.js                # Three.js 库（3D 渲染）
│   └── vanta.js                # Vanta.js 库（3D 背景动画）
└── views/                      # 页面视图
    ├── C.vue                   # 3D 大屏页面
    ├── Home.vue                # 管理后台主页
    ├── LoginView.vue           # 登录页
    ├── Mobile.vue              # 移动端布局
    ├── mobileView/             # 移动端子页面
    └── newHomeView/            # 管理后台子页面

---

9. 常见问题排查

9.1 npm install 安装依赖失败

症状: 安装过程中报错或卡住。

解决方案:

1. 检查 Node.js 版本是否 >= 14.x：node -v
2. 清除 npm 缓存后重试：

   npm cache clean --force
   npm install

3. 如果网络较慢，可设置国内镜像：

   npm config set registry https://registry.npmmirror.com
   npm install

9.2 开发环境页面空白

症状: npm run serve 启动后浏览器打开页面空白。

排查步骤:

1. 检查浏览器控制台是否有报错（F12 → Console）
2. 检查后端服务 http://127.0.0.1:666 是否正常运行
3. 检查 vue.config.js 中代理配置是否正确
4. 确认没有端口冲突（默认 8080）

9.3 API 请求 404 / 跨域错误

症状: 浏览器控制台显示 API 请求失败。

解决方案:

• 开发环境: 确认 vue.config.js 中的代理目标地址和端口与后端一致
• 生产环境: 确认 Nginx/IIS 的反向代理配置正确，或修改 baseURL 为后端实际地址后重新构建

9.4 生产部署后页面刷新 404

症状: 部署后直接访问子页面（如 /home/gate）出现 404。

原因: Vue Router 使用 Hash 模式（# 分隔），但如果浏览器访问不带 # 的路径，服务器需要配置回退。

解决方案: 配置 Nginx try_files 或 IIS URL Rewrite 将未知路径回退到 index.html（见第 4 节）。

9.5 登录后无法访问某些页面

症状: 登录成功但点击某些菜单被重定向回登录页。

原因: 后端返回的权限路由列表中不包含该页面路径。

解决方案: 联系后端管理员为该用户分配相应的页面权限。

---

附录

A. 浏览器兼容性

根据 package.json 中的 browserslist 配置：

> 1%
last 2 versions
not dead
not ie 11

• 不支持 IE 11
• 支持主流浏览器的最新两个版本
• 覆盖全球使用率 > 1% 的浏览器

B. 相关技术文档链接

技术	文档地址
Vue 3	https://cn.vuejs.org/
Vue Router 4	https://router.vuejs.org/zh/
Vuex 4	https://vuex.vuejs.org/zh/
Ant Design Vue 4	https://www.antdv.com/
ECharts 5	https://echarts.apache.org/zh/
Axios	https://www.axios-http.cn/
Vue CLI 5	https://cli.vuejs.org/zh/