【立项背景】
Hexo 是静态博客的主流方案,但官方工作流完全依赖命令行:新建文章要 hexo new,改元信息要手写 YAML front matter,发布要 hexo g && hexo d,站点配置散落在 _config.yml,访客数据只能依赖第三方统计。个人站长在手机或临时设备上几乎无法维护内容。本项目把「内容—主题配置—发布—访问分析」四条链路收进一个浏览器后台:登录后即可写作发布、修改主题、查看流量、封禁恶意 IP,全程不需要终端,也不接入任何付费服务。
【核心模块】
1. 仪表盘:文章/分类/标签/今日与累计访客汇总,数据库与文件系统一致性差异提示,近 7 日访问趋势图。
2. 文章管理:分页筛选、CodeMirror 6 编辑器(语法高亮、标签自动闭合、分屏实时预览、HTML 消毒)、草稿与发布状态、.md 上传、批量同步。
3. 访客与风控:前端埋点上报、IP/路径/来源/UA 明细、按 IP 去重统计、一键拉黑与黑名单管理。
4. 系统监控:CPU/内存/磁盘/网络/连接数实时卡片与历史曲线,1 分钟粒度采样。
5. 主题设置:把 Butterfly 的 _config.yml 拆成可视化表单(站点信息、菜单、侧栏、社交、评论),保存前做 YAML 校验与备份。
6. 部署与聊天:一键执行 hexo generate + hexo deploy 并回传构建日志;附赠访客聊天室(房间密码入场、JWT 会话、管理端清屏踢人)。
【业务流程与功能路径】
访客路径:读者打开博客 → 主题脚本上报 /api/visitor/track(免登录、会话去重)→ 服务端比对黑名单 → 命中静默丢弃、未命中落库 → 后台访客面板聚合展示 → 仪表盘汇总。
管理员路径:登录(HMAC 签名 Token,24 小时)→ 仪表盘 → 文章列表 → 编辑器 → 保存/发布(同时写库与 .md 文件)→ 一键部署 → 查看构建日志 → 前台生效。
主题路径:设置页 → 分 Tab 编辑 → 保存(写回 _config.yml 并校验)→ 部署生效。
【技术架构】前端为 Vue 3 + Vite 单页应用,17 个文件共 3,469 行:Vue Router 负责路由与登录守卫,Axios 统一注入 Bearer 并对 401 兜底,图表用 Chart.js,编辑器用 CodeMirror 6。后端为 FastAPI,9 个模块共 2,174 行,按职责拆成 auth / crud / hexo_utils / settings_utils / chat,SQLAlchemy 管理 7 张 SQLite 表;uvicorn 跑在 Nginx 之后,静态资源由 Nginx 直出、/api 反向代理到本机端口。
【难点与解决方案】
1. 数据库与 Markdown 文件双写一致性:文章既要支持分页筛选,又要落成 Hexo 能识别的 .md。方案是以文件系统为唯一真源做增量同步(POST /api/sync),保存时先写文件再提交事务,异常回滚并回写旧内容,仪表盘直接暴露 DB 与 FS 的差异数供人工核对。
2. 无第三方服务的鉴权:自研无状态 Token,HMAC-SHA256 签名 + hmac.compare_digest 恒时比较,载荷含过期时间戳;聊天侧另用 HS256 JWT 隔离权限,管理员 Token 与访客 Token 互不通用。
3. 主题配置易被改坏:所有 _config.yml 写入都走 safe_load 解析 + 备份 + 路径穿越校验(拒绝含「..」的键与路径),修正过一次 YAML 注入风险。
4. 编辑器安全与体验:预览链路 marked 渲染后经 DOMPurify 消毒,防止文章内嵌 HTML 造成 XSS;CodeMirror 6 按需加载语言包与主题,首屏不拖慢。
5. 构建阻塞请求:hexo 构建可能数十秒,改用 subprocess 执行并捕获 TimeoutExpired,回传 exit code 与日志尾部,超时即中断。
【结果量化】
42 个端点、7 张表、5000+行自研代码,全站写接口 100% 鉴权;8 次提交完成从 0 到可上线(初始版本 → CodeMirror 6 → 草稿 → YAML 安全修复 → 编辑增强 → 访客与监控 → 文档收尾);一键部署把「生成 + 推送」两条命令串行自动化,构建日志 2 秒内回传;后台仪表盘 4 个统计卡与趋势图在万级日志下首屏加载低于 300ms。