网站开发里程碑小结: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 三条约束
- 只引用、不复制正文:篇目只存一个指向
Post的外键。文章改了书里跟着改,文章撤回(status≠p)就自动从书里消失,改回已发布自动回归。绝不复存一份正文,否则两处必然分叉。 - 序号不落库:后台只填排序号,页面上的"第 N 篇"由视图按最终顺序连续编号。中间插一篇不会让后面全乱。
- 卷是排序的自然产物:排序号相邻且同卷的篇目自动聚成一卷、生成卷标题,不需要再建一层"卷"模型。
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
您尚未登录,请先登录才能评论。