网站开发里程碑小结:siliu.online 的架构与特点

liulinhai 2026.10.30 13:34 20 0
Django技术 Django 文集 网站架构 小结 部署

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

网站开发里程碑小结:siliu.online 的架构与特点

从云服务器把站点搬回家里的一台小机器,到 IPv6 直连、纯云存储、Markdown 编辑器、文集板块落地,再到今天——这个站已经走完一段完整的开发旅程。本文把全站的技术架构、数据模型、内容板块和运维机制梳理成一份小结,作为这一阶段的里程碑记录。

数据快照(2026-10-31):230 篇文章(198 篇已发布)、28 个分类、98 个标签、3 本合集(67 条篇目)、60 条评论。

本篇写于 2026-10-30,随后两天里又做了 PDF 导出、悬浮目录等一轮打磨,复盘见续篇《小结之后的继续打磨:PDF 导出、悬浮目录与后台收尾》。


一、技术架构

1.1 整体栈

层 选型
语言 / 框架 Python + Django 4.2 LTS
数据库 SQLite(db.sqlite3,单文件)
应用服务器 gunicorn(单 worker,规避 SQLite 写锁)
反向代理 nginx 1.27-alpine
容器编排 Docker Compose,三容器:web / nginx / acme
静态资源 绑定挂载 + collectstatic 收集
媒体存储 纯云存储:七牛 CDN(cdn.siliu.online),本地零媒体文件

1.2 网络与部署特点

  • 纯 IPv6 直连 + 阿里云 DDNS:家宽没有固定公网 IPv4,外网访问走 IPv6 永久地址(SLAAC),由计划任务每 30 分钟把本机 AAAA 记录同步到阿里云 DNS。缓存早退、登录补跑、静默执行,整套逻辑都为了"变化才同步、不变不动网"。
  • 单点部署:SQLite 不支持跨机共用,所以刻意做成单点 + 每周自动备份,而不是上 PostgreSQL 主从。博客写入频率低,这个取舍是划算的。
  • 纯云存储:所有图片、附件都在七牛,URL 统一为 http://cdn.siliu.online/media/...。容器里没有 media 挂载,nginx 也没有 location /media,GET /media/... 直接返回 404。换机器不再需要拷媒体目录。

复迁只需:装 Docker → 拉代码 → docker compose up -d --build → migrate → (可选)填 AK/SK 开 HTTPS。数据库里的链接已经全是七牛地址。


二、内容模型

2.1 文章(Post)

文章是站点的原子单位,核心字段:

Post
├─ title          标题(唯一)
├─ body           正文原文(html 或 markdown 源码)
├─ content_format 正文格式:html(富文本)| markdown
├─ excerpt        摘要(可空,空则自动截取)
├─ status         状态:d 草稿 | p 已发布 | w 已撤回
├─ category       分类(FK,一对一分类)
├─ tags           标签(M2M)
├─ author         作者(FK→User)
└─ view_num       阅读量(泛型关系 ViewNum)

关键设计:正文只存原文,渲染统一在出口做。 文章有两种格式(历史 219 篇是 html 富文本,新文章用 markdown),但详情页、列表页摘要、RSS 三处都走同一个渲染出口 blog/content.py 的 render_body(),避免 Markdown 文章在列表页露出 ** 和 #。

2.2 渲染层隔离

文章与评论走两套渲染,因为信任级别不同:

文章 blog/content.py 评论 sitecomments/content.py
作者 作者本人(后台 / 本地命令) 读者(外部输入)
渲染后 原样输出,不净化 bleach 白名单净化
缺依赖降级 转义纯文本 全部转义(宁显源码不开口子)

评论层净化放在渲染层而非表单层——存量历史评论在库里躺了多年,只有渲染这道闸门能兜住它们。白名单不放行 style 与任何 on* 事件,链接协议限定 http/https/mailto。

2.3 代码高亮统一

全站代码高亮统一交给前端的 highlight.js(github 主题),Markdown 文章只输出 <pre><code class="language-x">。去掉了服务端的 Pygments 上色——它和 highlight.js 重复着色会导致 HTML 文章与 Markdown 文章配色不一致,而且 RSS 里还会塞一堆内联样式。现在 HTML 文章、Markdown 文章、前台、后台预览四者配色完全一致(代价是 RSS 阅读器里代码块无颜色,但更干净)。


三、文集(书)板块

这是本阶段新增的内容组织方式:把已经发表过的文章按阅读顺序编成一本"书"。

3.1 模型

Collection(书)
├─ title / slug / subtitle / author
├─ cover          封面(留空则由书名自动生成纯 CSS 封面)
├─ intro          简介
├─ epigraph       扉页书摘(一行一条)
├─ status / sort_order
└─ Chapter(篇目)
   ├─ collection  所属书
   ├─ post        指向某篇 Post(只引用,不复制正文)
   ├─ order       排序号(10/20/30…)
   ├─ part        卷 / 部
   ├─ title       篇名(留空用原标题)
   └─ epigraph    本篇题记

3.2 三条约束

  1. 只引用、不复制正文:篇目只存一个指向 Post 的外键。文章改了书里跟着改,文章撤回(status≠p)就自动从书里消失,改回已发布自动回归。绝不复存一份正文,否则两处必然分叉。
  2. 序号不落库:后台只填排序号,页面上的"第 N 篇"由视图按最终顺序连续编号。中间插一篇不会让后面全乱。
  3. 卷是排序的自然产物:排序号相邻且同卷的篇目自动聚成一卷、生成卷标题,不需要再建一层"卷"模型。

3.3 页面

  • /books/ 书库封面墙(无封面时用书名 + 4 套渐变换色生成纯 CSS 封面)
  • /books/<slug>/ 目录页(按卷分组、带序号与书摘)
  • /books/<slug>/<seq>/ 阅读页(URL 用"第几篇"而非文章 id,含进度条、篇首书摘、书内上下篇、可折叠目录)

联动:导航加了"文集",文章详情页会显示"收录于《X》第 N 篇"并链回书内。后台文章列表还加了"已收录于"列、以及"添加到合集"批量动作,勾选文章即可加入已有书或新建一本。

本站目前有三本合集:《把博客搬回家》(本站开发记录,14 篇)、《结构设计笔记》(结构设计与计算,六卷 48 篇)、《小薇薇的成长》(刘霁云的成长故事,5 篇)。


四、写作与编辑体验

4.1 编辑器

后台正文编辑器支持 HTML(CKEditor 4.22.1)与 Markdown 双格式切换:

  • CKEditor 4.22.1 是最后一个开源免费版本,4.23+ 起改为需商业许可证的 ESM/LTS,无 licenseKey 时编辑器拒绝初始化,所以本站冻结在 4.22.1 并用 versionCheck:False 关掉升级告警。
  • 切到 Markdown 时,CKEditor 序列化出的冗余 HTML 会被 html2md 真正转成干净 Markdown 源码再进编辑框,而不是把一堆 <p style=...> 当源码显示。
  • Markdown 模式有分屏预览、快捷插入工具条、语法速查表、状态栏,以及自建的撤销 / 重做快照栈(前后台共用 md-core 公共库)。

4.2 图片浏览分页

CKEditor 的"浏览服务器"原本是递归全量遍历、无分页,文章多了会越来越卡。本站用服务端 marker 分页视图接管了 /ckeditor/browse/,按 12 张一页翻,支持上一页 / 下一页;Markdown 编辑器的图片浏览也改成 8 张一页、尽量一次铺满、不水平滚动。

4.3 命令行发表

publish_post 管理命令支持从 Markdown 文件发表,带 YAML front-matter 或命令行参数传标题 / 分类 / 标签,按标题幂等(相同标题更新不新建)。这是本站大部分技术文章的生产路径。


五、运维与可靠性

  • 单点 SQLite + 每周一 06:30 自动备份:在线热备 db.sqlite3 + 媒体 + 完整性校验,保留最近 12 份快照(约 3 个月)。
  • 备用机一键部署包:package-for-standby.ps1 生成自包含 zip,另一台电脑解压即用、灾备待命(不与主力机抢 DDNS)。
  • 改代码必重建镜像:Python / 模板 / 静态资源都打进镜像,改完必须 docker compose build web && up -d web,再 diff 核对收集产物。
  • 迁移脚本沉淀:IPv6 放行、DDNS、HTTPS(enable-https.ps1 走 DNS-01 签证书,不开放任何入站端口)、WSL2 引擎修复,全部脚本化、幂等、可双击运行。

六、小结与下一步(更新)

这一阶段的成果,是把一个"能跑的博客"逐步打磨成"结构清楚、好写、好读、好运维"的站点:

  • 内容上:双格式渲染统一、评论净化、代码高亮一致;
  • 组织上:用文集把散篇变成有序可读的书;
  • 体验上:编辑器双格式切换、图片分页、后台批量入集;
  • 底座上:纯 IPv6 直连、纯云存储、单点 SQLite + 自动备份。

初稿写到这里时,我留了几个"可选方向,都不急":文章内浮动导航、书籍 RSS、把某卷导出 PDF、为合集每篇补单独书摘。它们没有等太久——在随后的一轮打磨里:

  • 阅读页有了动态悬浮目录:平时右缘只露几条安静的小横线,鼠标靠近时由近及远地荡出全部篇目,卷分组也不落下;
  • 整本合集可以导出 PDF:带纯 CSS 封面同款渐变、图表、Pygments 高亮的代码块,异步生成配进度条,不再担心被下载工具接管;
  • 篇目的篇名与书摘在后台真正可用了,48 行的编辑表也不再横向滚动。

这一段的完整复盘,续篇里有写:《小结之后的继续打磨:PDF 导出、悬浮目录与后台收尾》。清单上还剩书籍 RSS 与按卷导出——继续往下做就是了,先把这份小结收进《把博客搬回家》作为这一程的节点。

Last Modified·2026年10月31日 07:52

暂无评论

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