Ubuntu
288 lines
12 KiB
Markdown
288 lines
12 KiB
Markdown
# 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. 环境配置
|
|
|
|
### 后端
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
### 前端
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
# 开发模式
|
|
npm run dev
|
|
# 生产构建
|
|
npm run build
|
|
```
|
|
|
|
### 默认管理员账号
|
|
|
|
- 用户名：`admin`
|
|
- 密码：`admin123`（部署后应立即修改）
|
|
|
|
---
|
|
|
|
*本文档由 nanobot 根据项目源码自动生成。*
|