网站优化记录:存储后端本地化与 Markdown 编辑器统一

liulinhai 2026.10.29 15:31 17 0
Django技术 Django 七牛云 存储后端 Markdown编辑器

收录于《把博客搬回家》第 12 篇

这次趁迁移到本机、把站点彻底跑在纯 IPv6 + 七牛云存储之上,顺手把两处"历史包袱"清掉了:一是停更多年的七牛存储后端依赖,二是前台后台各写一套、长期对不齐的 Markdown 编辑器。下面记录做法与踩过的坑。

一、存储后端本地化

问题

站点一直用 django-qiniu-storage 把图片传到七牛。但这个包停更在 2.3.1,带来几个隐患:

  • 依赖 six,而新版 Django 早就不需要它;
  • 代码里用 force_text(Django 4.x 已改名 force_str),运行期抛 DeprecationWarning;
  • 长期不更新,Django 再升一个小版本就有不兼容风险。

之前只能在 Dockerfile.web 里用 sed 把 force_text 临时改成 force_str 来凑合,属于打补丁式 workaround,镜像每次构建都靠这段文本替换兜着。

做法

直接在项目内落地一个本地化的 siteqiniu 后端,逐字节复刻原包的上传/签名/URL 逻辑,只做三处清理:

  1. 去掉 six 依赖;
  2. force_text → force_str;
  3. 清掉 DeprecationWarning。

requirements.txt 里移除 django-qiniu-storage,Dockerfile.web 也不再需要那条 sed 补丁——构建干净了。

关键修正:location 必须固定为 media

原包默认读 settings.MEDIA_ROOT(容器里是 /app/media)拼上传 key,结果新文件会落到 app/media/uploads/...,和历史上 media/uploads/... 的形态不一致,导致同一篇文章里新老图片 URL 对不齐。

本地化后端把 QiniuMediaStorage.location 显式固定为 'media',不再读 MEDIA_ROOT。这样新上传的 key 形态是 media/uploads/<年月>/<随机>_文件名,URL 为 http://cdn.siliu.online/media/uploads/...,与 CKEditor 历史上传、与 MEDIA_URL 完全一致,历史链接一个都不用改。

# siteqiniu/backends.py 要点
class QiniuMediaStorage(Storage):
    location = 'media'   # 固定,不读 MEDIA_ROOT,保证 key 形态与历史一致

顺带:django-contrib-comments 在 pip 源里最高只有 2.2.0,但本站只把它当底层库 import,Django 4.2 下 check 0 issues、评论正常,无需强制升级。

二、Markdown 编辑器统一

改造前:两套实现,处处对不齐

  • 前台评论/回复:md-editor.js,按钮 mdce-*,11 个按钮;
  • 后台文章:admin-md-hints.js,按钮 md-*,14 个按钮。

按钮集、插入逻辑、速查表、状态栏全是两套,加个功能要改两个文件,两边都还不一样(后台有标题/表格/分隔线,前台没有)。

统一到 md-core.js

现在把"控件本身"收敛成一份实现(mdc-*),前后台只负责"装配"——容器不同、预览接口不同、显示时机不同,但按钮、插入、速查、状态栏、撤销/重做只有一份代码。

// md-core.js 暴露的公共控件
window.MdCore = {
  ACTIONS, buildActionBar, buildCheatsheet, buildStatusBar,
  createHistory, insert, checkIssues,
  openImageUpload, wirePasteUpload, uploadImageFile, showToast
};

后台 admin-markdown.js 和前台 md-editor.js 只调用这些装配函数,不再各自实现一遍。

撤销/重做为什么自己写

浏览器的原生 undo(Ctrl+Z)无法由按钮触发,document.execCommand('undo') 早已废弃且各浏览器行为不一。所以 md-core.js 里自建了一个快照栈:

  • 输入停顿 400ms 打一个快照(不是每敲一个字符一打,否则一步一撤太碎);
  • 撤销时若当前内容还没入栈,先补一个再回退,保证最新编辑不丢;
  • 恢复时挂 suppress 标志,避免恢复动作自己又触发快照把重做栈冲掉;
  • Ctrl+Z / Ctrl+Shift+Z / Ctrl+Y 与按钮走同一条路径。

快照上限 200 步,超了丢最早的。

图片上传前后台共用

"选本地图上传"对话框和"粘贴图片自动上传"都搬到 md-core.js,后台写文章和登录用户的评论框共用同一套:

  • 点 ☁ 按钮弹对话框(选文件 + 本地预览 + alt 说明 + 上传进度);
  • Ctrl+V 粘贴截图,从 clipboardData.items 取 image/* 直传(参考 CKEditor 的做法);
  • 上传走同一个 MD_IMAGE_UPLOAD_URL 接口,存七牛,返回 media/uploads/... 直链后插入正文;
  • 粘贴上传用唯一 token 占位,上传成功精确替换、失败自动还原。

去掉分屏,预览改为可折叠

后台原来有一套分屏布局,和评论框的预览交互对不齐,维护成本高。统一后后台也去掉分屏,预览改成可折叠:默认收起,首次输入自动展开,手动收起后本页不再自动——与评论框行为完全一致。

权限与样式收口

  • 上传接口 ImageUploadView 从 @staff_member_required 放宽到 @login_required:评论也是登录用户才能用,需要这个接口;两个预览接口仍限 staff。
  • 上传路由不挂 admin_view(那会强制 staff),否则非 staff 的注册用户上传会被 302 拦掉。
  • 上传对话框 / toast 的 CSS 从 admin-markdown.css 迁到 md-core.css:前台评论页只加载 md-core.css,不加载 admin-markdown.css,迁过去前后台弹窗样式才一致;按钮样式用 .md-upload-modal .md-btn 作用域收口,不污染后台预览按钮。

三、配套改动

  • 纯云存储:移除本地 media 挂载、nginx 的 location /media 与 urls.py 的 serve 路由,全站媒体引用 100% 走 cdn.siliu.online,服务器零本地媒体文件。
  • 评论与文章渲染分离:文章可信、渲染层不净化;评论走 bleach 白名单(已放开 img 的 src/alt/title 且允许 https),上传得到的图片链接在评论里能正常渲染。

小结

两处优化的共同思路都是"收口到单一实现":存储后端收口到项目内的 siteqiniu,编辑器控件收口到 md-core.js。后续再加按钮或换存储,都只动一处。

待办提醒:主站和 cdn.siliu.online 目前都还是 HTTP,要上 HTTPS 时两者必须同步开启(七牛免费证书),否则图片会被浏览器拦截。

Last Modified·2026年10月29日 15:31

暂无评论

您尚未登录,请先才能评论。