【没事学点啥】TurboBlog个人化轻量博客项目——Turbo Blog 项目学习与上线指南

Turbo Blog 项目学习与上线指南

整理日期：2026-05-06
项目定位：一个轻量个人博客。Django 像发动机，负责数据、接口、登录、评论、上传、RSS 和 sitemap；原生 HTML/CSS/JS 像驾驶舱，负责页面、写作后台和交互。

效果如图所示：

1. 项目总览表

当前本地数据库概况：站点名 Turbo Blog，公网地址仍是 http://localhost:5173，共有 4 篇文章，4 篇已发布文章，1 条评论，0 条待审评论。

2. 架构图

#mermaid-svg-P5hGDFqfISYibOJY{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-P5hGDFqfISYibOJY .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-P5hGDFqfISYibOJY .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-P5hGDFqfISYibOJY .error-icon{fill:#552222;}#mermaid-svg-P5hGDFqfISYibOJY .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-P5hGDFqfISYibOJY .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-P5hGDFqfISYibOJY .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-P5hGDFqfISYibOJY .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-P5hGDFqfISYibOJY .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-P5hGDFqfISYibOJY .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-P5hGDFqfISYibOJY .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-P5hGDFqfISYibOJY .marker{fill:#333333;stroke:#333333;}#mermaid-svg-P5hGDFqfISYibOJY .marker.cross{stroke:#333333;}#mermaid-svg-P5hGDFqfISYibOJY svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-P5hGDFqfISYibOJY p{margin:0;}#mermaid-svg-P5hGDFqfISYibOJY .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-P5hGDFqfISYibOJY .cluster-label text{fill:#333;}#mermaid-svg-P5hGDFqfISYibOJY .cluster-label span{color:#333;}#mermaid-svg-P5hGDFqfISYibOJY .cluster-label span p{background-color:transparent;}#mermaid-svg-P5hGDFqfISYibOJY .label text,#mermaid-svg-P5hGDFqfISYibOJY span{fill:#333;color:#333;}#mermaid-svg-P5hGDFqfISYibOJY .node rect,#mermaid-svg-P5hGDFqfISYibOJY .node circle,#mermaid-svg-P5hGDFqfISYibOJY .node ellipse,#mermaid-svg-P5hGDFqfISYibOJY .node polygon,#mermaid-svg-P5hGDFqfISYibOJY .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-P5hGDFqfISYibOJY .rough-node .label text,#mermaid-svg-P5hGDFqfISYibOJY .node .label text,#mermaid-svg-P5hGDFqfISYibOJY .image-shape .label,#mermaid-svg-P5hGDFqfISYibOJY .icon-shape .label{text-anchor:middle;}#mermaid-svg-P5hGDFqfISYibOJY .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-P5hGDFqfISYibOJY .rough-node .label,#mermaid-svg-P5hGDFqfISYibOJY .node .label,#mermaid-svg-P5hGDFqfISYibOJY .image-shape .label,#mermaid-svg-P5hGDFqfISYibOJY .icon-shape .label{text-align:center;}#mermaid-svg-P5hGDFqfISYibOJY .node.clickable{cursor:pointer;}#mermaid-svg-P5hGDFqfISYibOJY .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-P5hGDFqfISYibOJY .arrowheadPath{fill:#333333;}#mermaid-svg-P5hGDFqfISYibOJY .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-P5hGDFqfISYibOJY .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-P5hGDFqfISYibOJY .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-P5hGDFqfISYibOJY .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-P5hGDFqfISYibOJY .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-P5hGDFqfISYibOJY .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-P5hGDFqfISYibOJY .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-P5hGDFqfISYibOJY .cluster text{fill:#333;}#mermaid-svg-P5hGDFqfISYibOJY .cluster span{color:#333;}#mermaid-svg-P5hGDFqfISYibOJY div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-P5hGDFqfISYibOJY .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-P5hGDFqfISYibOJY rect.text{fill:none;stroke-width:0;}#mermaid-svg-P5hGDFqfISYibOJY .icon-shape,#mermaid-svg-P5hGDFqfISYibOJY .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-P5hGDFqfISYibOJY .icon-shape p,#mermaid-svg-P5hGDFqfISYibOJY .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-P5hGDFqfISYibOJY .icon-shape .label rect,#mermaid-svg-P5hGDFqfISYibOJY .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-P5hGDFqfISYibOJY .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-P5hGDFqfISYibOJY .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-P5hGDFqfISYibOJY :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

浏览器

index.html

config.js

script.js

/api/… 请求

turboblog/urls.py

blog/views.py

blog/models.py

backend/data/turbo-blog-django.sqlite

assets/uploads/

RSS / sitemap / robots

可选 AI 模型 API

这不是 React/Vue 项目，而是“原生前端 + Django 单体后端”。浏览器加载静态文件，script.js 用 fetch() 调 Django API；Django 再读写 SQLite，必要时保存上传图片。

3. 要改内容时去哪里

manage.py 的作用：它是 Django 的“控制开关”。你运行这些命令时都靠它找到项目配置：

python manage.py runserver python manage.py migrate python manage.py
check python manage.py seed_initial_data

它里面最关键的一行是：

os.environ.setdefault(“DJANGO_SETTINGS_MODULE”, “turboblog.settings”)

意思是：告诉 Django，配置文件在 turboblog/settings.py。
注意：站点标题、描述、公网地址已经存进 SQLite 后，改 backend/data/db.json 不会自动覆盖旧库。已有库要改 public_url，可用：

python manage.py shell -c "from blog.models import SiteSetting; s=SiteSetting.objects.get(pk=1); s.public_url='https://你的域名'; s.save()"

4. 数据模型速记

最重要的关系：一篇 Post 可以有多条 Comment；评论默认 pending，管理员通过后才公开展示。

5. API 地图

6. 核心流程

6.1 打开首页

浏览器访问 /，Django 的 frontend() 返回 index.html；script.js 先 loadSite()，再 navigate()，最后 loadPosts() 拉文章并 renderHome() 画出首页。

6.2 写文章

点击“写作”后，前端先调用 /api/auth/me 检查管理员。登录通过后进入 renderEditor()；保存时提交到 /api/posts 或 /api/posts/<id>，Django 写入 Post 表。

6.3 评论

文章详情页先拉 /api/captcha。访客提交评论时，后端检查验证码、敏感词和频率限制；评论进入 pending，管理员在写作后台通过后才展示。

6.4 图片上传

写作后台选择图片，前端转成 base64 发到 /api/uploads；后端校验格式和大小，然后写入 assets/uploads/，返回 Markdown 图片地址。

6.5 AI 问答

问题进入 /api/ai/ask。后端把问题分词，在已发布文章里找相关片段；没有 AI_API_KEY 时用本地检索回答，有 key 时把片段交给 DeepSeek/OpenAI-compatible 模型生成回答。

7. 本地开发命令

Windows 推荐：

start-blog.bat

手动启动：

python -m pip install -r requirements.txt
python manage.py migrate –noinput
python manage.py seed_initial_data
python manage.py runserver [::]:5173

检查：

python manage.py check
python scripts/test_django_backend.py

本地地址：

http://localhost:5173
http://localhost:5173/api/health
http://localhost:5173/sitemap.xml

本地默认管理员令牌/密码：dev-token。上线必须改。

8. 生产环境变量

9. Turbo Blog Django 公网发布指南

当前项目已经切换为 Django 后端：一个 Python 服务同时提供前端页面、博客 API、图片上传、RSS、sitemap 和 robots.txt。

整体发布流程如下：

部署平台 + 持久磁盘 Volume + SQLite

部署成功如图所示：

9.1Railway部署

Railway 是什么
Railway 是一个“云上自动机房”。你不用买服务器、装 Nginx、配 HTTPS，它会从 GitHub 拉代码，自动构建，运行你的 Django，并给你一个公网网址。

你的链路会变成：

GitHub 仓库
-> Railway 自动拉代码
-> 安装 requirements.txt
-> 执行启动命令
-> Gunicorn 跑 Django
-> Railway 给公网域名和 HTTPS

Volume 是什么
Volume 不是“音量”，是“持久硬盘”。

普通 Railway 容器像临时酒店房间：你可以在里面写文件，但重新部署/重启后，房间可能被打扫干净。
Volume 像你租的储物柜：挂到服务里以后，文件会长期保留。

你的博客长期写文章，最重要的是数据库不能丢，所以要让 SQLite 住进 Volume：

/app/data/turbo-blog-django.sqlite

Railway 官方说明：Volumes 用来给服务保存持久数据，挂载路径会变成服务里可读写的目录；Volume 在服务启动时挂载，不在 build/pre-deploy 阶段挂载。参考：

python manage.py migrate –noinput && python manage.py seed_initial_data && gunicorn turboblog.wsgi:application –bind 0.0.0.0:$PORT

项目也带了 Procfile，支持会读取 Procfile 的平台自动部署。

9.2新建项目

New Project
-> Deploy from GitHub repo
-> 选择你的博客仓库
Railway 会生成一个项目，里面会有一个服务。这个服务就是你的 Django 博客容器

9.3设置启动命令

进入你的服务：

Service
-> Settings
-> Deploy
-> Start Command

python manage.py migrate –noinput && python manage.py seed_initial_data && gunicorn turboblog.wsgi:application –bind 0.0.0.0:$PORT

9.4必填环境变量

操作如下图所示：

之后直接复制下方代码：

DJANGO_DEBUG=0
DJANGO_SECRET_KEY=一串很长的随机字符
ADMIN_TOKEN=你的后台强令牌
ADMIN_PASSWORD=你的后台强密码
ALLOWED_HOSTS=*
SQLITE_FILE=/app/data/turbo-blog-django.sqlite
UPLOAD_DIR=/app/data/uploads

密钥可以本地生成：

python -c "import secrets; print(secrets.token_urlsafe(50))"

9.5Volume 创建

先ctrl+k
然后在这个搜索框里输入 volume
接下来一直点
最后Mount Path: /app/data
结束

9.6访问

1、开全局才能访问的到网站
2、如图所示，这才是你个人的网站

10. 上线前检查清单

11. 快速学习路线

按这个顺序学，像从地图边缘走到城市中心：

练手建议：