Ubuntu
12 KiB
12 KiB
Personal Blog - 架构总览
文档生成时间：2026-04-28
项目路径：/home/ubuntu/nanocode/personal-blog
1. 项目定位
一个面向个人使用的全栈博客系统，具备以下核心能力：
- 内容管理：文章 CRUD、分类/标签体系、草稿与发布状态
- 内容采集：支持通用网页采集和微信公众号文章采集
- 访客端展示：基于 Markdown 的文章渲染、SEO 友好的 URL
- 管理后台：完整的后台管理界面，支持文章编辑、分类标签管理、系统设置
- 图片管理：本地上传与远程图片下载统一管理
2. 技术栈
2.1 后端
| 技术 | 版本 | 用途 |
|---|---|---|
| Python | 3.11 | 运行环境 |
| FastAPI | 0.115.0 | Web 框架 |
| Uvicorn | 0.32.0 | ASGI 服务器 |
| SQLAlchemy | 2.0.36 | ORM |
| Pydantic | 2.9.2 | 数据校验 |
| python-jose | 3.3.0 | JWT 签名/验证 |
| passlib[bcrypt] | 1.7.4 | 密码哈希 |
| python-multipart | 0.0.17 | 文件上传解析 |
| Pillow | 11.0.0 | 图片处理 |
| Playwright | (系统安装) | 浏览器自动化采集 |
2.2 前端
| 技术 | 版本 | 用途 |
|---|---|---|
| React | 18.3.1 | UI 框架 |
| Vite | 6.0.0 | 构建工具 |
| React Router | 7.0.0 | 客户端路由 |
| Axios | 1.7.9 | HTTP 客户端 |
| Tailwind CSS | 3.4.16 | 样式框架 |
| Preline UI | 2.7.0 | 管理后台组件库 |
| react-markdown | 9.0.1 | Markdown 渲染（管理端预览） |
| markdownify | (系统安装) | HTML 转 Markdown |
3. 系统架构
┌─────────────────────────────────────────────────────────────┐
│ 用户浏览器 │
└─────────────────────────┬───────────────────────────────────┘
│
┌───────────────┴───────────────┐
│ │
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ 访客端 (Port 8888) │ │ 管理后台 (同端口) │
│ Neobrutalism 主题 │ │ Preline Admin 主题 │
│ - 首页文章列表 │ │ - 文章管理 │
│ - 文章详情页 │ │ - 分类/标签管理 │
│ - 分类/标签筛选 │ │ - 系统设置 │
│ - 关于页面 │ │ - 图片管理 │
└─────────┬───────────┘ └──────────┬──────────┘
│ │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ 前端 Dev Server (Vite) │
│ http://localhost:8888 │
└──────────────┬───────────────┘
│
│ API 请求
▼
┌──────────────────────────────┐
│ FastAPI 后端 (Port 8889) │
│ /api/* 路由 + /uploads 静态文件 │
│ │
│ ┌────────────────────────┐ │
│ │ 路由模块 (routers/) │ │
│ │ auth, posts, categories│ │
│ │ tags, images, settings │ │
│ │ crawl, wechat_crawl │ │
│ └────────────────────────┘ │
│ │
│ ┌────────────────────────┐ │
│ │ SQLAlchemy ORM │ │
│ │ SQLite 数据库 │ │
│ │ app.db │ │
│ └────────────────────────┘ │
│ │
│ ┌────────────────────────┐ │
│ │ 静态文件服务 │ │
│ │ uploads/ (图片上传) │ │
│ └────────────────────────┘ │
└──────────────────────────────┘
4. 部署架构
服务器 (Ubuntu 22.04)
│
├── Nginx (反向代理，可选)
│ └── 80/443 → 前端:8888 / 后端:8889
│
├── systemd 服务
│ ├── personal-blog-frontend.service (Vite dev server)
│ └── personal-blog-backend.service (Uvicorn + FastAPI)
│
└── 项目目录
└── /home/ubuntu/nanocode/personal-blog/
├── backend/ FastAPI 后端
│ ├── app.py 应用入口
│ ├── models.py 数据库模型
│ ├── schemas.py Pydantic 模型
│ ├── database.py DB 连接与 Session
│ └── routers/ 路由模块
├── frontend/ React 前端
│ ├── src/
│ │ ├── pages/ 页面组件
│ │ ├── components/ 访客端组件
│ │ ├── components-preline/ 管理端组件
│ │ └── api/ API 封装
│ └── index.html
└── docs/ 项目文档
5. 数据流
5.1 正常发布流程
管理员 → 管理后台 → 编辑文章 → 保存草稿 / 发布
│
▼
FastAPI /api/posts
│
▼
SQLite (Post, Category, Tag)
│
▼
访客端读取 /api/posts → 渲染
5.2 采集流程
管理员 → 采集页面 → 输入 URL → Playwright 抓取
│
┌──────────────┴──────────────┐
│ │
▼ ▼
通用网页采集 公众号采集
(crawl.py) (wechat_crawl.py)
- Readability-lxml - BeautifulSoup
- markdownify - 图片下载到本地
- 图片下载到本地 - 微信图片修复
│ │
└──────────────┬──────────────┘
│
▼
前端预览 → 编辑 → 保存/发布
6. 安全设计
| 层面 | 措施 |
|---|---|
| 认证 | JWT (HS256)，支持 Bearer Header 和 Cookie 两种方式 |
| 密码 | bcrypt 哈希存储 |
| 后台路由 | 全路由 get_current_admin 鉴权 |
| 访客路由 | 公开访问，无鉴权 |
| 文件上传 | 白名单扩展名 (jpg, jpeg, png, gif, webp)，重命名防冲突 |
| CORS | 开发环境允许跨域，生产环境按需配置 |
7. 关键目录结构
personal-blog/
├── backend/
│ ├── app.py # FastAPI 应用入口
│ ├── models.py # SQLAlchemy 数据模型
│ ├── schemas.py # Pydantic 请求/响应模型
│ ├── database.py # 数据库引擎与 Session
│ ├── app.db # SQLite 数据库文件
│ ├── requirements.txt # Python 依赖
│ ├── routers/
│ │ ├── auth.py # 认证/登录/Token
│ │ ├── posts.py # 文章 CRUD + 搜索
│ │ ├── categories.py # 分类管理
│ │ ├── tags.py # 标签管理
│ │ ├── images.py # 图片上传/删除
│ │ ├── settings.py # 系统设置/自定义页面
│ │ ├── crawl.py # 通用网页采集
│ │ └── wechat_crawl.py # 公众号文章采集
│ └── uploads/ # 图片上传目录
│ └── wechat_*/ # 公众号文章图片
├── frontend/
│ ├── index.html # HTML 入口
│ ├── vite.config.js # Vite 配置
│ ├── package.json # Node 依赖
│ ├── tailwind.config.js # Tailwind 配置
│ └── src/
│ ├── main.jsx # React 入口
│ ├── App.jsx # 根路由
│ ├── index.css # 全局样式 (双主题)
│ ├── api/
│ │ ├── config.js # Axios 实例
│ │ ├── posts.js # 文章 API
│ │ └── categories.js # 分类 API
│ ├── pages/
│ │ ├── Home.jsx # 访客端首页
│ │ ├── PostDetail.jsx # 访客端文章详情
│ │ ├── PostEdit.jsx # 文章编辑/新建
│ │ ├── Posts.jsx # 文章管理列表
│ │ ├── CrawlEdit.jsx # 通用采集编辑
│ │ ├── WechatCrawlEdit.jsx # 公众号采集
│ │ ├── Categories.jsx # 分类管理
│ │ ├── Tags.jsx # 标签管理
│ │ ├── Images.jsx # 图片管理
│ │ ├── Settings.jsx # 系统设置
│ │ ├── Login.jsx # 登录页
│ │ └── About.jsx # 关于页面
│ ├── components/
│ │ ├── Layout.jsx # 访客端布局
│ │ └── PostCard.jsx # 文章卡片
│ └── components-preline/
│ ├── Sidebar.jsx # 管理后台侧边栏
│ ├── Card.jsx # 卡片组件
│ ├── Button.jsx # 按钮组件
│ └── Input.jsx # 表单组件
└── docs/ # 本文档目录
8. 环境配置
后端
cd backend
# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate
# 安装依赖
pip install -r requirements.txt
# 安装 Playwright 浏览器
playwright install chromium
# 启动
uvicorn app:app --host 0.0.0.0 --port 8889 --reload
前端
cd frontend
npm install
# 开发模式
npm run dev
# 生产构建
npm run build
默认管理员账号
- 用户名：
admin - 密码：
admin123（部署后应立即修改）
本文档由 nanobot 根据项目源码自动生成。