历史包袱不会自己消失,它只会在下一次迁移时一起算账。
这次趁迁移到本机、把站点彻底跑在纯 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 逻辑,只做三处清理:
- 去掉
six依赖; force_text→force_str;- 清掉
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 下check0 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 时两者必须同步开启(七牛免费证书),否则图片会被浏览器拦截。
定稿于 2026.10.29
本书目录
- 01 把网站从云服务器搬回家里:Django + Docker + IPv6 DDNS 迁移实录
- 02 评论功能迁移完善:把四处 site-packages 补丁收拢为 sitecomments 自定义 app
- 03 为什么 AAAA 记录指向家里的 IPv6 地址,外网就能直接访问
- 04 外网打不开、本机却正常:一次 IPv6 静默断网三小时的完整复盘
- 05 用 Markdown 写博客:一篇示例,也是本站的格式说明
- 06 给博客加上 Markdown:一个字段、两套渲染层,和一堆必须小心的地方
- 07 把编辑器打磨顺手:去掉多余确认、对齐宽度,让评论也用上 Markdown
- 08 收尾两件事:评论只剩 Markdown,代码高亮只剩一套
- 09 编辑栏合并成一套,顺手补上撤销重做
- 10 博客媒体全面上云:CDN 域名统一与纯云存储改造
- 11 把博客升级到 Django 4.2 LTS:一次低风险、却有意外收获的升级
- 12 网站优化记录:存储后端本地化与 Markdown 编辑器统一
- 13 把文章编成书:给博客加一个「文集」板块
- 14 网站开发里程碑小结:siliu.online 的架构与特点
- 15 小结之后的继续打磨:PDF 导出、悬浮目录与后台收尾
- 16 本站功能与使用指南:siliu.online 一览
- 17 外网也能传:用 Docker SFTP 把静态站点直推到家宽服务器