基于 Vue3、Express、MongoDB、TypeScript 实现的个人主页前后端分离完整系统
         [](https://choosealicense.com/licenses/mit/)
**QF-page** 是一款免费开源的个人主页系统，项目代码简洁，注释丰富，上手容易；同时还提供了一系列功能丰富的组件和工具，帮助开发者搭建个人主页简历网站和开发管理后台应用。 ## 项目结构 ``` PersonalSite/ ├── admin/ # 管理后台 (Vue 3 + Vite + Ant Design Vue) │ ├── public/ │ │ └── config.js # 构建时不需要，仅本地开发参考 │ └── src/ ├── client/ # 前台展示 (Vue 3 + Vite + GSAP) ├── server/ # 后端服务 (Express + TypeScript + MongoDB) │ ├── src/ │ │ ├── controllers/ # 控制器 │ │ ├── middlewares/ # 中间件（鉴权、上传、日志等） │ │ ├── models/ # Mongoose 数据模型 │ │ ├── routes/ # 路由（自动挂载） │ │ ├── db/ # 数据库初始化脚本 │ │ ├── utils/ # 工具函数 │ │ └── config/ # 配置文件 │ ├── .env.development # 本地开发环境变量（裸机运行时生效） │ └── .env.production # 生产环境变量（Docker 中被 .env 覆盖） ├── deploy/ # 部署脚本 │ ├── docker-deploy.sh # Docker 一键部署（源码构建） │ ├── docker-export.sh # Docker 构建 + 冒烟验证 + 导出镜像包 │ ├── ubuntu-deploy.sh # Ubuntu 裸机部署脚本 │ └── update.sh # 裸机增量更新脚本 ├── .env # Docker 运行时环境变量（改完重启容器即可） ├── config.js # 前端运行时配置（同域留空，分机器填 API 地址） ├── docker-compose.yml # 容器编排（mongo + server + nginx） ├── Dockerfile # 多阶段构建（server → admin → client → nginx） └── .dockerignore # 构建排除清单 ``` ## 项目功能特色 - [x] 使用 Vue 3、TypeScript 和 Vite 构建，具备高效的开发体验和优秀的性能表现 - [x] 集成模块：用户登录注册、主题更换、博客管理、系统管理、大屏数据可视化、资源管理、图标地图渲染等 - [x] 文件、视频、音频、图片上传下载预览、Markdown 文件内容解析 HTML、解析 Markdown 文件内容自动一键填写博文内容 - [x] 代码生成器，可一键生成 Express 后端代码的 CRUD 接口和前端的增删改查页面 - [x] 博文内容发表支持视频、文件、音频、链接、图片、表格、各种图表、流程图、管道图等 - [x] 评论模块，发表、回复、点赞、反对等 - [x] 权限模块，路由权限、接口权限、按钮权限各级细粒度的权限设计 - [x] 操作日志、访客记录，提供访客的行为分析 - [x] 服务器状态监控，实时显示 CPU、内存、磁盘使用率 - [x] 站点配置管理，在线编辑主页展示内容 - [x] 文件上传安全防护：MIME 白名单、大小限制、Token 鉴权 + 权限校验 - [x] 丰富的各种组件，上传、图片列表、导入、导出、批量删除等 - [x] 丰富的特效和动画，视差效果具有设计感和 3D 酷炫界面的展示 - [x] 图片懒加载、路由预加载、路由懒加载 - [x] GitHub 开源数据实时同步 - [x] Docker 一键部署，支持导出镜像包离线部署 --- ## 快速部署（Docker，推荐） ### 环境要求 - Docker >= 20.10 - Docker Compose >= 2.0 ### 方式一：源码构建部署 ```bash # 1. 克隆项目 git clone https://gitee.com/Z568_568/PersonalSite.git cd PersonalSite # 2. 一键部署（自动构建镜像 + 启动） sudo bash deploy/docker-deploy.sh ``` ### 方式二：离线部署（导出镜像包） **构建机器上：** ```bash # 构建镜像 + 冒烟验证 + 导出 sudo bash deploy/docker-export.sh ``` 验证通过后，`deploy/export/` 目录包含完整部署包： ``` export/ ├── qf-images.tar.gz # 镜像包 ├── docker-compose.yml # 服务编排 ├── nginx-docker.conf # Nginx 配置 ├── .env # 环境变量（编辑后再部署） ├── config.js # 运行时配置 └── start.sh # 一键启动脚本 ``` **目标机器上：** ```bash # 1. 复制到目标机器 scp -r export ubuntu@目标IP:~/ # 2. 编辑配置 vim .env # 3. 一键启动 sudo bash start.sh ``` > 目标机器只需要 Docker，不需要 Node.js、npm、构建工具。 ### 配置文件说明 部署后需要关注的配置： | 文件 | 用途 | 改完如何生效 | |------|------|-------------| | `.env` | 域名、数据库、邮箱等 | `docker compose restart` | | `config.js` | 前端 API 地址（分机器部署时修改） | `docker compose restart web` | **`.env` 可配置项：** ```env DOMAIN=your-domain.com # 站点域名 DB_NAME=mypage_db # 数据库名 SIGN_KEY=随机生成 # JWT 签名密钥 MAIL_HOST=smtp.qq.com # SMTP 服务器 MAIL_PORT=465 # SMTP 端口 MAIL_USER=your-email@qq.com # 邮箱账号 MAIL_PASS=授权码 # 邮箱授权码 MAIL_FROM=your-email@qq.com # 发件人地址 ``` **`config.js` 运行时配置：** ```js window.__APP_CONFIG__ = { // 同域部署（nginx 反向代理）：留空 apiBaseUrl: '', // 分机器部署：填 API 完整地址 // apiBaseUrl: 'https://api.your-domain.com', } ``` > `config.js` 通过 volume 挂载到 Nginx 容器，浏览器加载后注入 `window.__APP_CONFIG__`，admin 和 client 的 axios 实例读取此值。**改完无需重新构建镜像**。 ### Docker 架构 ``` nginx (:80) server (:3089) mongo (:27017) ├─ /admin/ → admin dist ├─ / → client dist ├─ /v1/* → proxy 转发 └─ /uploads/ → 上传文件 ``` --- ## 本地开发 ### 环境要求 - Node.js >= 18 - MongoDB >= 6.0 - npm ### 1. 克隆项目 ```bash git clone https://gitee.com/Z568_568/PersonalSite.git cd PersonalSite ``` ### 2. 安装依赖 ```bash cd admin && npm install cd ../client && npm install cd ../server && npm install ``` ### 3. 配置环境变量 编辑 `server/.env.development`： ```env NODE_ENV=development URL=http://localhost PORT=3089 DB_URL=localhost DB_PORT=27017 DB_NAME=mypage_db SIGN_KEY=gLR+JUuKR/R5KrA1gr4ukg== ``` ### 4. 启动 MongoDB ```bash # macOS brew services start mongodb-community # Ubuntu sudo systemctl start mongod # Windows net start MongoDB ``` ### 5. 启动项目 ```bash cd server && npm run dev # 后端 :3089 cd admin && npm run dev # 管理后台 :3088 cd client && npm run dev # 前台展示 :3002 ``` ### 6. 访问 - 前台展示：http://localhost:3002 - 管理后台：http://localhost:3088 - API 文档：http://localhost:3089/swagger - 默认管理员：admin / admin123 --- ## 裸机部署（Ubuntu） > Docker 部署请使用上面的快速部署方式。 ```bash chmod +x deploy/ubuntu-deploy.sh sudo bash deploy/ubuntu-deploy.sh ``` 脚本自动完成：系统更新 → Node.js → MongoDB → Nginx → PM2 → 构建代码 → 配置启动。 --- ## 默认账号 | 角色 | 用户名 | 密码 | |------|--------|------| | 超级管理员 | admin | admin123 | 默认拥有所有权限。普通管理员角色需自行在角色管理中分配权限。 ## 技术栈 | 层级 | 技术 | |------|------| | 前台展示 | Vue 3 + Vite + Pinia + GSAP + ECharts + SCSS | | 管理后台 | Vue 3 + Vite + Ant Design Vue + Pinia + ECharts | | 后端服务 | Express + TypeScript + Mongoose + JWT | | 数据库 | MongoDB | | 部署 | Docker + Docker Compose（推荐） / Nginx + PM2 + Certbot | ## 贡献 欢迎对 QF-page 项目的改进和完善，如果您发现任何错误或有任何建议，请随时提交问题和拉取请求。 ## License MIT License ## 联系方式 - 邮箱：1840354092@qq.com