# 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 根据项目源码自动生成。*