From 09d78f57a5a0170f78cc350c5a6736c6806487b0 Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Tue, 31 Mar 2026 22:41:08 +0800 Subject: [PATCH] update readme --- readme.md | 281 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 173 insertions(+), 108 deletions(-) diff --git a/readme.md b/readme.md index 61044eb..db6585c 100644 --- a/readme.md +++ b/readme.md @@ -1,124 +1,189 @@ -# 二次元风格博客技术文档 -打算自己写个博客博客项目练练手，并把原来博客的东西都搬过去，先把仓库和前端写了 +# ACG Blog - 二次元风格博客系统 -### 项目基本信息 +

+ Python + FastAPI + Vue + TypeScript + Docker +

-- **项目名称**：ACG Blog（二次元风格博客） -- **项目简介**：基于 **FastAPI** 与 **Vue 3** 的前后端分离博客系统，主打二次元视觉体验与高性能响应。支持 Markdown 文章发布、动态看板娘、访问量统计、热搜排行、深色模式切换等特色功能。 -- **技术栈概览**： - - 后端：Python + FastAPI + SupaBase + Tortoise‑ORM + Redis + JWT - - 前端：Vue 3 (Vite) + Pinia + Naive UI + Tailwind CSS + GSAP -- **系统架构**：**B/S 架构**（Browser/Server，浏览器/服务器架构） - - 前端：单页应用（SPA）运行于浏览器 - - 后端：RESTful API 服务器 - - 通信协议：HTTP/HTTPS + JSON -- **后端架构模式**：**类 MVC 模式** - - **Model（模型层）**：`models/` 目录，Tortoise-ORM 数据模型定义 - - **View（视图层）**：`api/endpoints/` 目录，FastAPI 路由返回 JSON 响应 - - **Controller（控制器层）**：`api/endpoints/` 中的路由处理函数，协调业务逻辑 - - **Service（服务层）**：`services/` 目录，封装核心业务（如看板娘互动、统计逻辑） - - **Schema（数据传输层）**：`schemas/` 目录，Pydantic 模型校验请求与响应 - - **CRUD（数据操作层）**：`crud/` 目录，封装数据库增删改查逻辑，辅助 Model 层 - - **Core（核心配置）**：`core/` 目录，管理环境变量、日志、JWT 安全等基础设施 -- **开发状态**：规划中 +基于 **FastAPI** 与 **Vue 3** 的前后端分离博客系统，主打二次元视觉体验与高性能响应。支持 Markdown 文章发布、访问量统计、分类标签管理、深色模式切换等功能。 -> 详细技术选型及项目结构请参见下文。 +## 技术栈 -### 后端技术栈 +### 后端 +| 技术 | 说明 | +|------|------| +| FastAPI | 高性能异步 Web 框架 | +| Tortoise-ORM | 异步 ORM，支持 PostgreSQL | +| PostgreSQL | 关系型数据库 | +| Redis | 缓存与会话存储 | +| JWT | 无状态身份认证 | +| Pydantic | 数据验证 | +| Loguru | 日志处理 | -| **模块** | **技术选型** | **说明** | -| -------------- | --------------------- | ------------------------------------------------------------ | -| **核心框架** | **FastAPI** | 高性能、原生异步（Async），满足二次元素材（图片/视频）的高并发加载需求。 | -| **数据库** | **SupaBace** | **内置 Auth**，支持第三方登录 (Github/Google) | -| **ORM (异步)** | **Tortoise-ORM** | 语法类似 Django，且原生支持异步操作。 | -| **缓存/任务** | **Redis** | 用于文章点击量统计、热搜排行以及 Session 存储。 | -| **认证** | **JWT (python-jose)** | 无状态认证，方便前后端分离部署。 | -| **数据校验** | **Pydantic v2** | 确保前端传来的数据不会让后端“炸掉”。 | -| **日志** | **Loguru** | 极简且强大的异步日志处理，便于排错 | +### 前端 +| 技术 | 说明 | +|------|------| +| Vue 3 | 组合式 API (Script Setup) | +| Vite | 快速构建工具 | +| TypeScript | 类型安全 | +| Pinia | 状态管理 | +| Naive UI | UI 组件库 | +| Tailwind CSS | 样式引擎 | +| Axios | HTTP 客户端 | -### 前端技术栈 (The Visuals) +## 项目结构 -| **模块** | **技术选型** | **说明** | -| ------------- | ---------------- | ------------------------------------------------------------ | -| **框架** | **Vue 3 (Vite)** | 组合式 API (Script Setup) 开发体验极佳，构建速度快。 | -| **状态管理** | **Pinia** | 轻量、简洁，存储用户偏好（如：深色/浅色模式、看板娘状态）。 | -| **UI 组件库** | **Naive UI** | 设计感极强，配置主题非常自由，适合定制二次元配色。 | -| **样式引擎** | **Tailwind CSS** | 极其方便编写自定义 UI。你可以轻松实现“毛玻璃”、“卡片悬浮”等特效。 | -| **编辑器** | **V-MD-Editor** | 基于 Vue 3 的 Markdown 编辑器，支持预览、代码高亮和 LaTeX 公式。 | -| **动画库** | **GSAP** | 强大的动效库。二次元风格需要细腻的入场和交互动画。 | - -### 预计项目结构 - -```bash -acg-blog/ -├── backend/ # FastAPI 后端项目 +``` +├── backend/ # FastAPI 后端 │ ├── app/ -│ │ ├── api/ # 接口层 (v1, v2...) -│ │ │ ├── endpoints/ # 具体业务接口 (posts.py, users.py, etc.) -│ │ │ └── api.py # 路由汇总 -│ │ ├── core/ # 核心配置 -│ │ │ ├── config.py # 环境变量与全局配置 -│ │ │ ├── logger.py # 日志拦截与配置 -│ │ │ └── security.py # JWT 与权限相关 -│ │ ├── crud/ # 数据库增删改查逻辑 -│ │ ├── db/ # 数据库连接与初始化 -│ │ ├── models/ # Tortoise-ORM 数据库模型 -│ │ ├── schemas/ # Pydantic 数据验证模型 -│ │ ├── services/ # 业务服务逻辑 (如：看板娘互动 API) -│ │ └── main.py # 后端入口 -│ ├── logs/ # 日志存储目录 (自动生成 .log 文件) -│ ├── static/ # 静态资源 (用户上传的插图、头像) -│ ├── tests/ # 测试用例 -│ ├── .env # 敏感配置文件 -│ ├── pyproject.toml # Poetry 配置或使用 requirements -│ └── requirements.txt # 依赖清单 -├── frontend/ # Vue 3 前端项目 (Vite) -│ ├── public/ # 公共静态资源 (Live2D 模型、Favicon) +│ │ ├── api/endpoints/ # API 端点 (auth, posts, comments, users) +│ │ ├── core/ # 核心配置 (config, security, database, logger) +│ │ ├── crud/ # 数据库增删改查 +│ │ ├── models/ # Tortoise-ORM 数据模型 +│ │ ├── schemas/ # Pydantic 数据验证模型 +│ │ └── main.py # 应用入口 +│ ├── Dockerfile # 后端容器配置 +│ ├── schema.sql # 数据库建表脚本 +│ └── requirements.txt # Python 依赖 +│ +├── frontend/ # Vue 3 前端 │ ├── src/ -│ │ ├── api/ # Axios 接口封装 -│ │ ├── assets/ # 样式、二次元字体、插画 -│ │ ├── components/ # 组件 (看板娘、播放器、卡片) -│ │ ├── router/ # 路由配置 -│ │ ├── store/ # Pinia 状态管理 -│ │ ├── views/ # 页面布局 (首页、文章页、归档) -│ │ ├── App.vue # 根组件 -│ │ └── main.ts # 前端入口 -│ ├── tailwind.config.js # Tailwind CSS 配置 -│ └── package.json # 前端依赖 -├── docker-compose.yml # 全栈 Docker 编排 -└── README.md +│ │ ├── api/ # Axios 接口封装 +│ │ ├── components/ # 公共组件 +│ │ ├── views/ # 页面视图 +│ │ ├── store/ # Pinia 状态管理 +│ │ ├── router/ # 路由配置 +│ │ └── types/ # TypeScript 类型定义 +│ ├── Dockerfile # 前端容器配置 +│ └── nginx.conf # Nginx 配置 +│ +├── docker-compose.yml # Docker 编排 +├── schema.sql # 数据库建表脚本 +└── docker-deploy.md # 部署文档 ``` -### 后端requirements +## 快速开始 + +### 环境要求 +- Python 3.11+ +- Node.js 18+ +- PostgreSQL 14+ +- Redis 7+ (可选) + +### 本地开发 + +**1. 克隆项目** +```bash +git clone +cd acg-blog +``` + +**2. 启动后端** +```bash +cd backend + +# 创建虚拟环境 +python -m venv venv +source venv/bin/activate # Linux/Mac +# 或 venv\Scripts\activate # Windows + +# 安装依赖 +pip install -r requirements.txt + +# 配置环境变量 +cp .env.example .env # 修改数据库连接信息 + +# 初始化数据库 (确保 PostgreSQL 运行中) +psql -U postgres -c "CREATE DATABASE acg_blog;" +psql -U postgres -d acg_blog -f schema.sql + +# 启动服务 +uvicorn main:app --reload --port 8000 +``` + +**3. 启动前端** +```bash +cd frontend + +# 安装依赖 +npm install + +# 启动开发服务器 +npm run dev +``` + +**4. 访问应用** +- 前端: http://localhost:5173 +- 后端 API: http://localhost:8000 +- API 文档: http://localhost:8000/docs + +### Docker 部署 ```bash -# Web 框架 -fastapi==0.110.0 -uvicorn[standard]==0.27.1 +# 启动所有服务 +docker-compose up -d -# 数据库与异步 ORM -tortoise-orm==0.20.0 -aerich==0.7.2 # 数据库迁移工具 -asyncpg==0.29.0 # PostgreSQL 驱动 -aioredis==2.0.1 # Redis 驱动 - -# 日志系统 -loguru==0.7.2 # 极简且强大的异步日志处理 - -# 配置与安全 -pydantic[email]==2.6.3 # 包含 Email 校验 -pydantic-settings==2.2.1 # 处理 .env 环境变量 -python-jose[cryptography]==3.3.0 # JWT -passlib[bcrypt]==1.7.4 # 密码哈希 - -# 业务 -python-multipart==0.0.9 # 处理表单与文件上传 -mistune==3.0.2 # 快速 Markdown 解析 -pillow==10.2.0 # 处理图片 -httpx==0.27.0 # 异步 HTTP 请求 - -# 开发与部署 -python-dotenv==1.0.1 -gunicorn==21.2.0 # 生产环境容器部署使用 +# 查看服务状态 +docker-compose ps ``` +访问 http://localhost 即可使用。 + +## API 接口 + +| 方法 | 路径 | 说明 | +|------|------|------| +| POST | /api/v1/auth/register | 用户注册 | +| POST | /api/v1/auth/login | 用户登录 | +| POST | /api/v1/auth/refresh | 刷新 Token | +| GET | /api/v1/auth/me | 获取当前用户 | +| GET | /api/v1/posts | 获取文章列表 | +| GET | /api/v1/posts/{id} | 获取文章详情 | +| POST | /api/v1/posts | 创建文章 | +| PUT | /api/v1/posts/{id} | 更新文章 | +| DELETE | /api/v1/posts/{id} | 删除文章 | +| GET | /api/v1/categories | 获取分类列表 | +| GET | /api/v1/tags | 获取标签列表 | +| GET | /api/v1/comments/post/{id} | 获取文章评论 | + +## 默认账户 + +- 用户名: `admin` +- 邮箱: `admin@acgblog.com` +- 密码: `admin123` + +**请在部署后立即修改管理员密码！** + +## 功能特性 + +- [x] 用户认证 (JWT) +- [x] 文章管理 (CRUD) +- [x] 分类与标签 +- [x] Markdown 编辑器 +- [x] 评论系统 +- [x] 浏览量统计 +- [x] 深色/浅色模式 +- [x] 响应式设计 +- [x] Docker 部署 + +## 开发说明 + +### 前端组件 +- `Navbar.vue` - 顶部导航栏 +- `Hero.vue` - 首页横幅 +- `PostCard.vue` - 文章卡片 +- `Sidebar.vue` - 侧边栏 +- `Footer.vue` - 页脚 + +### 管理后台 +- `/admin/dashboard` - 仪表盘 +- `/admin/posts` - 文章管理 +- `/admin/categories` - 分类管理 +- `/admin/tags` - 标签管理 + +## License + +MIT License