# MyBlog

**Repository Path**: adminruan/my-blog

## Basic Information

- **Project Name**: MyBlog
- **Description**: 轻量个人博客（Vue 3 + FastAPI + SQLite）：前台笔记/留言/搜索，后台仪表盘/富文本编辑/内容审核，零外部服务依赖，一键部署。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-16
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Vue, Python, Sqlite, blog

## README

# 随笔记 · Dev Notes

一个前后端分离的个人技术博客系统,记录日常工作与编程过程中的随笔记,包含博客前台与创作管理工作台。

![Vue 3](https://img.shields.io/badge/Vue-3-42b883?logo=vuedotjs)
![Vite](https://img.shields.io/badge/Vite-6-646cff?logo=vite)
![Tailwind CSS](https://img.shields.io/badge/Tailwind%20CSS-4-38bdf8?logo=tailwindcss)
![FastAPI](https://img.shields.io/badge/FastAPI-0.143-009688?logo=fastapi)
![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-2-red?logo=sqlalchemy)
![SQLite](https://img.shields.io/badge/SQLite-3-003b57?logo=sqlite)
![License](https://img.shields.io/badge/license-MIT-blue)
![Python](https://img.shields.io/badge/Python-3.10%2B-3776ab?logo=python)

---

## 页面预览

<table>
  <tr>
    <td><b>首页</b></td>
    <td><b>笔记详情</b></td>
  </tr>
  <tr>
    <td><img src="docs/screenshots/01-home.png" alt="首页" width="420"/></td>
    <td><img src="docs/screenshots/02-post-detail.png" alt="笔记详情" width="420"/></td>
  </tr>
  <tr>
    <td><b>留言板</b></td>
    <td><b>后台登录</b></td>
  </tr>
  <tr>
    <td><img src="docs/screenshots/03-guestbook.png" alt="留言板" width="420"/></td>
    <td><img src="docs/screenshots/04-admin-login.png" alt="后台登录" width="420"/></td>
  </tr>
  <tr>
    <td><b>后台仪表盘</b></td>
    <td><b>写新文章(TipTap)</b></td>
  </tr>
  <tr>
    <td><img src="docs/screenshots/05-admin-dashboard.png" alt="后台仪表盘" width="420"/></td>
    <td><img src="docs/screenshots/06-admin-post-editor.png" alt="写新文章" width="420"/></td>
  </tr>
</table>

---

## 目录

- [技术栈](#技术栈)
- [功能](#功能)
- [本地运行](#本地运行)
- [生产部署](#生产部署单进程)
- [目录结构](#目录结构)
- [环境变量](#环境变量)

---

## 技术栈

| 端 | 技术 |
| --- | --- |
| 前端 | Vue 3 + Vite + Tailwind CSS 4 + Vue Router + TipTap 富文本 + Axios |
| 后端 | FastAPI + SQLAlchemy 2 + SQLite + PyJWT |

## 功能

**博客前台**
- 首页:作者介绍、笔记列表、分类筛选(后端开发 / 前端开发 / 工程效率)、加载更多
- 笔记详情:正文排版(含代码块)、阅读时长、标签、喜欢、侧边目录(自动生成)、留言与博主回复
- 留言:游客提交留言(昵称 + 邮箱 + 内容)、回复已有留言

**创作管理工作台**(需登录,演示账号 `admin` / `admin123`)
- 仪表盘:文章 / 浏览 / 留言 / 今日访问统计卡片,近 7 天浏览量柱状图,最受欢迎笔记,最新留言快捷回复与隐藏
- 文章管理:按状态与关键词筛选、分页、编辑、删除
- 账号设置:修改登录账号与显示名称、修改登录密码
- 写新文章 / 编辑:TipTap 富文本(标题、加粗、列表、引用、图片上传、链接)、分类(可在「管理分类」里增删)、标签(可在「管理标签」里增删，编辑页直接点选)、封面(内置插画、上传图片或从媒体库复用)、草稿与发布
- 媒体库:按内容哈希落盘,同一张图多次上传只保留一份;封面与正文配图都可以直接点选已有图片复用
- 留言管理:按状态筛选、搜索、回复、显示 / 隐藏、删除

**内容安全(留言检测)**
- 本地词库:`sensitive_words.txt` 可随时增删,用 `[block]` / `[review]` 分档;`imported_words.txt` 为导入的开源大词库(色情 / 涉枪涉爆暴恐 / 广告)
- 归一化匹配:全角转半角、剔除干扰符号、统一小写,「敏 感 词」「敏-感-词」这类拆词绕过同样能识别;**改词库文件自动热更新,无需重启服务**
- 垃圾特征规则:多个外链、联系方式(手机 / QQ / 微信 / 邮箱)、连续重复字符(刷屏)、异常昵称 → 一律转人工审核
- 第三方语义检测(**可选**):配置 `UAPI_KEY` 后调用 uapis.cn 做语义级判定;留空则只走本地规则
- 三档判定:`clean` 直接展示 / `review` 转人工审核 / `block` 直接拒绝;第三方不可用(超时 / 限流 / 鉴权失败)时按 fail-closed 降级,默认全部转人工审核,不放行违规内容

## 本地运行

```powershell
# 1. 后端(端口 8000)
cd backend
py -3 -m venv .venv
.venv\Scripts\pip install -r requirements.txt
.venv\Scripts\python run.py

# 2. 前端(端口 5173,已配置 /api、/uploads 代理)
cd frontend
npm install
npm run dev
```

打开 http://localhost:5173 即可访问博客,后台入口在页脚「后台管理」或直接访问 http://localhost:5173/admin。

## 生产部署(单进程)

```powershell
cd frontend
npm run build
cd ..\backend
.venv\Scripts\python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```

后端检测到 `frontend/dist` 后会自动托管前端静态资源,直接访问 http://localhost:8000 即可,无需单独部署前端。

## 目录结构

```
backend/
  app/
    main.py        # 应用入口、CORS、静态资源托管
    models.py      # User / Post / Comment / VisitStat
    schemas.py     # Pydantic 请求响应模型
    security.py    # PBKDF2 密码哈希 + JWT
    seed.py        # 首次启动的演示数据
    moderation.py  # 内容安全:本地词库 + 垃圾特征规则 + 第三方语义检测
    data/          # 敏感词库(sensitive_words.txt / imported_words.txt)
    routers/       # auth / posts / comments / admin / uploads
  data/            # SQLite 数据库(自动创建,已在 .gitignore)
  uploads/         # 上传的图片(已在 .gitignore)

frontend/
  src/
    api/           # 接口封装与 axios 客户端
    components/    # 插画、编辑器、布局等公共组件
    views/         # 前台页面与后台页面
    stores/        # 登录状态

docs/
  screenshots/    # README 页面预览截图(6 张 PNG,随版本库分发)
```

## 环境变量

后端启动时从 `backend/.env`(已加入 `.gitignore`)或系统环境读取。**正式部署前请复制 `backend/.env.example` 为 `backend/.env` 并填写实际值。**

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `BLOG_SECRET_KEY` | **是** | `city-notes-dev-secret-change-me` | JWT 签名密钥;生产环境务必改为高熵随机串 |
| `UAPI_KEY` | 否 | (空) | uapis.cn 第三方敏感词 API 密钥;**留空 = 跳过第三方检测,仅走本地词库**;不提交到任何代码仓库 |
| `UAPI_SENSITIVE_ENABLED` | 否 | `1` | 是否启用第三方检测(`1`/`0`) |
| `UAPI_FAIL_CLOSED` | 否 | `1` | 第三方不可用时的策略:`1`=全部转人工审核 / `0`=保持首轮判定 |