Mizuki Admin 后台管理系统#

Mizuki Admin 是为博客量身打造的全功能可视化后台管理系统。通过 GitHub API 直接读写仓库文件，无需服务器，所有操作都在浏览器中完成。

核心特性#

零服务器：纯前端实现，通过 GitHub API 操作仓库
可视化编辑：所见即所得的表单编辑，告别繁琐的代码编辑
批量提交：多个操作累积后一次性推送 GitHub，减少 API 调用
预览确认：所有写入操作前可预览内容，确认无误后才提交
本地草稿：文章编辑自动保存到 localStorage，避免意外丢失
多模块覆盖：文章、相册、日记、配置等 12+ 模块全量管理
响应式设计：支持深色/浅色主题切换，适配桌面与移动端

快速开始#

1. 配置 GitHub 凭据#

访问 /admin，点击右上角 ⚙ 按钮，填写：

GitHub 用户名：你的 GitHub 用户名
仓库名：博客仓库（如 mizuki-1-new）
分支：master
Personal Access Token：在 GitHub Settings → Tokens 创建，需要 repo 权限

凭据仅存储在浏览器 localStorage，不会上传到任何服务器。

2. 开始管理#

配置完成后即可开始使用各项管理功能。

功能模块#

内容管理#

📝 文章管理#

列表视图：显示所有文章，支持搜索、新建、删除
编辑器：
- Front Matter 可视化表单（标题、日期、分类、标签、加密、置顶等）
- Markdown 编辑器 + 实时预览（分屏模式）
- Markdown 工具栏（H1-3、粗体、斜体、代码、引用、表格等）
- 📚 代码片段库（40+ 片段，支持点击插入与拖拽）
  - Front Matter 预设（基本/加密/置顶/草稿）
  - 基础 Markdown（标题/列表/引用/代码/表格等）
  - 扩展功能（GitHub 卡片/Note/Tip/Warning/Caution/Spoiler/公式）
  - Mermaid 图表（流程/时序/甘特/类/饼/状态图）
  - 视频嵌入（YouTube/Bilibili）
  - 文章模板（标准/加密/置顶公告/技术教程）
- 图片管理器（上传/插入/复制/删除）
- 文件夹模式支持（重命名、递归删除）
- 本地草稿自动保存（Ctrl+S）
- Tab 缩进

📔 日记#

列表展示日记条目
支持缩略图首图
图片选择器弹窗（上传/选择已有图片到日记）

🖼 相册#

卡片网格布局展示所有相册
缩略图预览
子路由 #/albums/{name} 进入相册详情
图片管理器（拖拽上传、网格预览、插入/复制/删除）
支持递归删除整个相册

📄 特殊页面#

编辑 about.md、friends.md 等特殊页面
Markdown 编辑器 + 预览

数据管理#

🔗 友情链接#

列表展示所有友链
表单编辑（标题、站点 URL、头像 URL、描述）
支持搜索过滤

📦 项目#

列表展示所有项目
表单编辑（标题、描述、图片、分类、技术栈、状态等）
推荐项目标记

🧠 技能#

列表展示所有技能
表单编辑（名称、图标、分类、等级、经验、相关项目、证书）
自定义主题色

⏱ 时间线#

列表展示时间线条目
表单编辑（标题、类型、起止日期、描述、图标、主题色）

配置管理#

⚙ 站点配置#

站点基本信息（标题、副标题、URL、运行日期）
时区与语言
主题色（色相、是否固定）
特色页面开关（番剧/日记/友链/项目/技能/时间线/相册/设备）
顶栏标题（图标 + 文本 / Logo 模式）
页面自动缩放配置

🧭 导航栏#

可视化管理导航菜单
支持多级子菜单
拖拽排序

👤 个人资料#

头像、昵称、简介
打字机效果（启用、速度）
社交链接列表

🎨 横幅与外观#

横幅位置（顶部/居中/底部）
轮播配置（启用、间隔）
波浪效果（启用、性能模式、移动端禁用）
导栏透明模式
首页文字（标题、副标题、打字机效果）

🧩 小部件配置#

12 个小部件的可视化编辑，通过 Tab 切换：

模块	说明
🎵 音乐播放器	Meting API / 本地音频、歌单 ID、音乐源、类型
🌸 樱花特效	数量、尺寸、不透明度、速度（水平/垂直/旋转/消失）、层级
🐱 Pio 看板娘	模型列表、触摸提示、换装提示、对话框文案、位置/尺寸/模式
🦶 页脚	自定义 HTML
🖼 全屏壁纸	桌面/移动端壁纸列表、轮播、位置、层级、透明度、模糊
📐 侧边栏布局	左/右/抽屉栏组件排序、响应式断点、默认动画
💬 评论	Twikoo envId、语言
🔗 分享	启用/禁用
📢 公告	标题、内容、可关闭、链接配置
📜 许可证	名称、URL、CC 协议快速选择
🔗 固定链接	格式模板、占位符提示
💻 代码主题	14 个预设主题、主题切换时隐藏代码块

批量提交机制#

为减少 GitHub API 调用次数，所有写入操作默认进入待提交队列：

工作流程#

入队：图片上传、文件保存、删除等操作进入待提交队列
预览：保存前弹出预览模态框，显示 JSON 配置或 Markdown 渲染
确认：用户确认后将操作加入队列（不立即推送 GitHub）
统一提交：点击右上角 📦 按钮打开待提交面板
执行：点击「全部提交」按顺序写入 GitHub 仓库

队列管理#

顶部 📦 按钮显示待提交数量徽章
点击打开待提交面板，可查看所有操作列表
支持撤销单个操作
支持清空整个队列
关闭页面前提示未提交操作

智能合并#

同路径文件的多次保存自动合并为最后一次
删除操作时如果是队列中新增的文件，直接撤销新增
图片上传后立即可用 data URL 预览，提交后才真正上传到 GitHub

预览功能#

文章预览#

保存文章前弹出预览模态框：

Front Matter 摘要：表格形式展示所有元数据
正文预览：Markdown 渲染后的 HTML
源码预览：可折叠的 Markdown 源码

配置预览#

保存配置前弹出 JSON 预览：

格式化的 JSON 显示
提示文字说明操作不会立即推送
确认后加入待提交队列

技术实现#

架构#

前端：原生 JavaScript + Astro 静态页面
数据存储：GitHub Contents API（读写仓库文件）
凭据存储：浏览器 localStorage
路由：Hash 路由（#/dashboard、#/posts 等）

TS 数据解析#

使用括号匹配算法正确处理嵌套的 TS 字面量：

提取 export const xxx = {...} 或 [...]
跳过字符串、模板字面量、行注释、块注释
通过 scope 注入处理 SITE_LANG、SITE_TIMEZONE 等变量引用
对 LinkPreset 等导入枚举使用 Proxy 占位

图片处理#

上传：FileReader 读取为 base64，入队后用 data URL 预览
删除：入队删除操作，前端立即移除
显示：优先使用队列中的 data URL，否则用 raw.githubusercontent.com

安全说明#

Token 仅存储在浏览器 localStorage，不上传任何服务器
所有 API 调用直接发往 api.github.com
建议使用细粒度 Token，仅授予目标仓库的 contents:write 权限
Token 可随时在 GitHub Settings 中撤销

快捷操作#

操作	快捷键
保存文章	Ctrl+S
Tab 缩进	Tab
插入代码片段	点击 📚 按钮
撤销队列操作	待提交面板 → 撤销
全部提交	待提交面板 → 全部提交

路由总览#

路由	说明
`#/dashboard`	仪表盘
`#/posts`	文章管理
`#/posts/{path}`	文章编辑器
`#/diary`	日记
`#/albums`	相册列表
`#/albums/{name}`	相册详情
`#/spec`	特殊页面
`#/friends`	友情链接
`#/projects`	项目
`#/skills`	技能
`#/timeline`	时间线
`#/site`	站点配置
`#/navbar`	导航栏
`#/profile`	个人资料
`#/banner`	横幅与外观
`#/widgets`	小部件配置
`#/widgets/{key}`	特定小部件（如 `#/widgets/music`）

访问 /admin 即可开始使用。如遇问题，可在 GitHub Issues 反馈。