概述

Lumin Admin 是基于 Vue 3 + Element Plus 前端框架和 Node.js Express 后端的博客后台管理系统，用于管理基于 Hugo 的 Lumin Blog 静态站点。本文记录了后台系统从基础框架到功能完善的完整开发过程。

技术栈

一、Dashboard 概览页面升级

1.1 数据统计卡片

从最初的 4 个统计卡片扩展到 10 个，覆盖站点核心指标：

1.2 数据可视化图表

共 7 个 ECharts 图表：

• 月度发文趋势：折线图 + 面积填充，展示近 12 个月发文量
• 内容构成：环形饼图，展示各分类文章占比
• 分类统计：柱状图，每个分类独立配色
• 文章状态：饼图，已发布/草稿/置顶/精选分布
• 发布时段：柱状图，24 小时发文时段分布
• 年度归档：横向柱状图，按年份统计
• 标签云：词云图，标签大小与文章数成正比

1.3 列表模块

• 最近发布：显示 8 篇最新文章，分类显示中文名称
• 热门文章：按字数排序的 Top 8
• 草稿箱：未发布的草稿文章
• 版本更新：从 themeVersion.md 读取版本历史
• 站点信息：11 项站点配置信息

1.4 关键技术问题与解决

标签云不显示：echarts-wordcloud@2.1.0 仅兼容 echarts@5，与 echarts@6 不兼容。降级到 echarts@5.6.0 后，还需将动态 await import('echarts') 改为静态 import * as echarts from 'echarts'，确保 wordcloud 注册到同一个 echarts 实例。

分类显示英文 slug：后端新增 categoryTitle 字段，使用 catTitleMap 将 slug 映射为中文标题。

TOML 字段名大小写：parseHugoConfig 将 baseURL 存为小写 baseurl，Dashboard API 需兼容两种写法。

二、媒体库改造

2.1 从单一目录到全站扫描

原媒体库仅扫描 static/images/uploads/ 目录，改造后递归扫描整个 static/ 目录，自动识别文件类型：

1const MEDIA_EXTENSIONS = {
2  image: ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.svg', '.ico', '.bmp', '.avif'],
3  audio: ['.mp3', '.wav', '.ogg', '.flac', '.aac', '.m4a', '.wma'],
4  video: ['.mp4', '.webm', '.avi', '.mov', '.mkv', '.flv', '.wmv', '.m4v']
5}

2.2 功能特性

• 类型筛选：全部/图片/音频/视频，显示各类型数量
• 来源切换：本地/远程图床（预留接口）
• 智能上传：根据文件类型自动路由到 images/uploads、audios、videos 目录
• 预览弹窗：图片直接预览，音频/视频使用原生播放器
• 文件大小限制：从 20MB 提升到 100MB，支持所有主流媒体格式

2.3 目录结构

Hugo 的 static/ 目录下的文件在构建时直接映射到站点根路径：

1static/
2├── images/          # 图片（含 avatar/banners/icons/reward/uploads 子目录）
3├── audios/          # 音频文件
4├── videos/          # 视频文件
5└── libs/            # 第三方库

三、图床配置系统

3.1 架构设计

采用配置与使用分离的架构：

• 系统设置 → 图床配置：配置各平台的 Key/Secret 等凭据
• 媒体库：查看本地文件 + 已配置的远程图床文件

3.2 支持的图床平台

3.3 API 设计

3.4 配置存储

图床配置存储在 admin/imageHosting.json，包含各平台的凭据信息和默认图床设置。GitHub 测试连接会真实调用 GitHub API 验证仓库访问权限。

四、站点预览

4.1 功能设计

• 本地预览：一键启动/停止 Hugo 本地预览服务器（hugo server -D --bind 0.0.0.0）
• 远程站点：输入远程站点 URL，选择部署方式
• 自动状态检测：每 10 秒轮询服务器运行状态

4.2 部署方式支持

支持 GitHub Pages、Cloudflare Pages、Vercel、Netlify、自定义服务器五种部署方式。

五、备份还原系统

5.1 核心功能

5.2 备份范围

备份包含以下目录和文件：

• content/ — 所有文章内容
• static/ — 静态资源（图片、音频、视频等）
• hugo.toml — 站点配置文件
• config/ — 额外配置目录（如存在）

5.3 安全措施

• 文件路径安全检查：确保备份文件路径在 _backups 目录内
• 恢复确认弹窗：防止误操作覆盖数据
• 备份文件下载：支持离线保存

六、插件系统

6.1 内置插件列表

6.2 插件管理

支持按分类筛选（内容/媒体/SEO/外观/系统），一键安装/卸载。已安装插件列表存储在 admin/plugins/installed.json。

七、应用市场

7.1 应用列表

7.2 功能特性

• 按分类筛选（外观/统计/功能/互动/内容/媒体）
• 关键词搜索（支持名称、描述、标签）
• 显示评分、下载量、版本号、文件大小
• 一键安装

八、版本更新系统

8.1 数据源

版本历史数据存储在项目根目录的 themeVersion.md 文件中，使用 YAML Front Matter 格式：

1---
2versions:
3  - version: "Beta 1.9"
4    date: "2026-05-20"
5    changes:
6      - "新增后台管理系统 Dashboard 概览页面"
7      - "新增文章 Front Matter 参数管理功能"
8---

8.2 解析方式

使用 js-yaml 库解析 YAML Front Matter，支持自定义 versions 数组字段，每条记录包含版本号、日期和更新列表。

九、系统设置增强

9.1 themeVersion 位置调整

将 themeVersion 从 [params.profile] 移到 hugo.toml 顶层基础信息区域，与 theme、languageCode 等字段同级，逻辑更清晰。

9.2 站点信息扩展

站点信息从 6 项扩展到 11 项：

• 站点标题、站点地址、Hugo 版本、主题、主题版本
• 语言、所在地、组织、建站日期
• 内容大小、媒体大小

十、项目文件结构

 1admin/
 2├── frontend/                    # Vue 3 前端
 3│   └── src/
 4│       ├── api/index.js         # API 接口定义
 5│       ├── router/index.js      # 路由配置
 6│       ├── layouts/MainLayout.vue  # 侧边栏布局
 7│       └── views/
 8│           ├── Dashboard/index.vue   # 概览页面
 9│           ├── Media/index.vue       # 媒体库
10│           ├── Storage/Index.vue     # 图床配置
11│           ├── Preview/Index.vue     # 站点预览
12│           ├── Backup/Index.vue      # 备份还原
13│           ├── Plugins/Index.vue     # 插件管理
14│           ├── Marketplace/Index.vue # 应用市场
15│           └── Settings/Index.vue    # 站点设置
16├── backend/
17│   ├── server.js                # Express 后端（所有 API）
18│   └── dist/                    # 前端构建输出
19├── _backups/                    # 备份文件存储
20├── plugins/                     # 插件数据
21├── imageHosting.json            # 图床配置
22└── backupConfig.json            # 备份配置

十一、后续规划

待实现功能

1. 图床文件浏览：在媒体库中查看远程图床文件（需集成各平台 SDK）
2. 图床文件上传：直接上传到远程图床
3. 增量备份：仅备份变更文件
4. 定时自动备份：基于调度器实现
5. 插件实际功能：当前为框架，需实现各插件的具体逻辑
6. 一键部署：Git 推送 + 自动构建

建议新增功能

• 友情链接管理：当前有统计但无管理页面
• 图库管理：照片墙管理功能
• 操作日志：记录后台操作审计
• SEO 设置：全局 meta、robots.txt 管理
• 主题编辑器：在线编辑主题模板
• 系统健康检查：检测 Hugo 版本、磁盘空间等