# myblog

**Repository Path**: lbtooth/myblog

## Basic Information

- **Project Name**: myblog
- **Description**: 一个包含前台展示与后台管理的博客系统，支持一键 Docker 部署。主题配色由后端统一控制，内置 **64 套精美配色**（8色系×8主题），可在后台自由切换。
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 博客系统 (FastAPI + Vue 3 + MySQL)

一个包含前台展示与后台管理的博客系统，支持一键 Docker 部署。主题配色由后端统一控制，内置 **64 套精美配色**（8色系×8主题），可在后台自由切换。

## 技术栈

- **后端**：FastAPI + SQLAlchemy 2.0 + PyMySQL + JWT（PyJWT）+ passlib/bcrypt
- **前端**：Vue 3 + Vite + Vue Router + Pinia + Element Plus + markdown-it
- **数据库**：MySQL 8.0（utf8mb4）
- **部署**：Docker / Docker Compose（MySQL + 后端 + 前端 nginx 三个服务）

## 功能

### 前台
- 首页文章列表（分页、关键词搜索、按分类 / 标签筛选、置顶）
- 顶部分类导航菜单（顺序由后台「分类管理」控制）
- 全局搜索页（`/search`，实时搜索标题 / 摘要 / 正文）
- 文章详情（Markdown 渲染、阅读量统计）
- 文章评论（游客可发表，需管理员审核后公开）
- 侧边栏：标签云、热门文章排行、站点统计
- 站点主题由后台统一设定，全站实时切换（共 64 套配色，8色系×8主题）

### 后台管理（`/admin`）
- JWT 登录鉴权、修改密码
- 仪表盘（文章 / 评论 / 分类 / 标签 / 阅读量统计 + 最新文章）
- 文章管理（增删改查、发布 / 草稿、置顶、封面图上传、正文中插入图片、分类与标签）
- 分类管理（增删改查、拖拽 / 按钮调整菜单左右顺序）
- 标签管理
- 评论管理（审核通过 / 驳回 / 筛选 / 删除）
- 主题设置（从 64 套配色中选择并即时预览）
- 图片上传（封面、正文配图，使用 `/uploads` 静态目录，卷持久化）

## 目录结构

```bash
myblog/
├── backend/                # FastAPI 后端
│   ├── app/
│   │   ├── main.py         # 应用入口 + 启动建表、迁移与种子数据
│   │   ├── config.py       # 配置（环境变量）
│   │   ├── database.py     # 引擎 / 会话 / 基类
│   │   ├── models.py       # ORM 模型（User / Category / Tag / Post / Comment / Setting）
│   │   ├── schemas.py      # Pydantic 模型
│   │   ├── security.py     # 密码哈希 / JWT
│   │   ├── deps.py         # 鉴权依赖
│   │   └── routers/        # 路由（auth / posts / admin）
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/               # Vue 3 前端
│   ├── public/             # 静态资源（构建时原样复制到 dist）
│   │   ├── logo.png        # 站点 Logo 图标
│   │   └── favicon.ico     # 浏览器标签页图标
│   ├── src/
│   │   ├── api/            # axios 封装
│   │   ├── router/         # 路由与守卫
│   │   ├── theme.js        # 64 套主题定义与 applyTheme 应用逻辑
│   │   ├── components/     # 公共组件（SiteHeader 等）
│   │   └── views/          # 前台（Home / PostDetail / Search）与后台页面
│   ├── nginx.conf
│   └── Dockerfile
├── docker-compose.yaml
└── README.md
```

## 主题（64 套配色·8色系×8主题）

| 色系 | 主题 |
| --- | --- |
| 红 | 宝石红、覆盆子红、胭脂红、西瓜红、玫瑰粉、腮红粉、报刊红、唯品会粉 |
| 橙 | 暖阳橙、淘宝橙、搜狐橙、橘红、哈密瓜、珊瑚红、铁锈橙、赤陶土 |
| 黄 | 向阳金、琥珀黄、藏红花、柠檬黄、金丝雀黄、蜂蜜黄、向日葵、橄榄绿 |
| 绿 | 青草绿、翡翠绿、玉石绿、薄荷绿、鼠尾草、青柠绿、森林绿、JumpServer |
| 青 | 海蓝宝石、水鸭青、绿松石、天青色、水色、青色、云杉青、铜绿色 |
| 蓝 | 晴空蓝、海军蓝、皇家蓝、湛蓝、钴蓝、天蓝色、冰蓝、夜空 |
| 紫 | 紫藤、紫罗兰、梅紫、紫水晶、淡紫红、鸢尾蓝紫、薰衣草、暮光紫 |
| 黑 | 极简墨、炭黑、黑曜石、石板灰、炮铜灰、午夜、X.com、极光夜 |

主题由后台「主题设置」统一控制并保存到 `settings` 表；前台 `main.js` 启动时读取 `/api/site/settings` 并调用 `applyTheme` 应用，无需前端手动切换。

## 一键部署

要求本机已安装 **Docker** 与 **Docker Compose**。

```bash
# 在 myblog 目录下
docker compose up -d --build
```

启动完成后：

- 前台博客：<http://localhost:8080>
- 后台管理：<http://localhost:8080/admin>（点击「后台管理」或访问 `/admin/login`）
- 后端 API 文档：<http://localhost:8000/docs>

默认管理员账号（可在 `docker-compose.yaml` 的环境变量中修改）：

- 用户名：`admin`
- 密码：`wang123`

## 环境变量

### 后端（`docker-compose.yaml` → backend.environment）
| 变量 | 说明 | 默认值 |
| --- | --- | --- |
| `DATABASE_URL` | 数据库连接串 | `mysql+pymysql://blog:blog123456@mysql:3306/blog?charset=utf8mb4` |
| `SECRET_KEY` | JWT 签名密钥（请修改） | `please-change-this-secret` |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | Token 有效期（分钟） | `1440` |
| `ADMIN_USERNAME` | 初始管理员用户名 | `admin` |
| `ADMIN_PASSWORD` | 初始管理员密码 | `wang123` |

### MySQL
| 变量 | 默认值 |
| --- | --- |
| `MYSQL_ROOT_PASSWORD` | `wang123` |
| `MYSQL_DATABASE` | `blog` |
| `MYSQL_USER` | `blog` |
| `MYSQL_PASSWORD` | `wang123` |

> 本项目所有默认密码统一为 `wang123`（管理员账号、MySQL root、MySQL 业务账号）。生产环境请务必修改为强密码。

> 容器编排说明：三个服务均配置了 `restart: unless-stopped`，宿主机器开机 / Docker 守护进程启动后会自动拉起容器（开机自启）。MySQL 服务**不暴露宿主端口**（不在 `ports` 中映射 3306），仅允许同一 Docker 网络内的后端容器通过服务名 `mysql` 访问，提升安全性。后端服务 `backend` 当前映射了 `8000` 宿主端口便于本地测试；生产环境建议移除该映射，仅通过前端 nginx（`:8080`）反向代理访问 `/api`、`/uploads`。

## 安全加固

本项目默认已启用以下安全措施：

- **后端端口**：`backend` 接入内部自定义网络（`myblog_net`，子网 `172.31.0.0/16`）；当前为方便测试映射了 `8000` 宿主端口，生产环境应移除该映射，仅由前端 nginx 反代对外。
- **nginx 安全响应头**：`X-Frame-Options: DENY`、`X-Content-Type-Options: nosniff`、`Referrer-Policy`、`X-XSS-Protection`、`Content-Security-Policy`（限制为同源资源）。
- **JWT 密钥（SECRET_KEY）**：当前 `docker-compose.yaml` 中使用默认值 `please-change-this-secret`；**生产环境务必替换为强随机密钥**（可用 `openssl rand -hex 32` 生成）。修改后已签发的旧 Token 会失效，需重新登录。
- **CORS 白名单**：后端跨域仅放行 `FRONTEND_ORIGINS` 显式配置的来源（默认 `http://localhost:8080`、`http://localhost:5173`），不再允许任意来源。
- **上传校验**：`/api/admin/upload` 仅接受图片类型（png/jpg/jpeg/gif/webp/bmp/svg），单文件上限 5MB，防止上传恶意或超大文件。
- **评论审核**：新评论默认进入「待审核」，仅审核通过后前台可见。

> 自定义网络：在 `docker-compose.yaml` 的 `networks.myblog_net.ipam.config` 中配置子网；如需固定容器 IP，可在各服务下增加 `networks: - myblog_net` 并为对应网络指定 `ipv4_address`（需先在 `networks` 中声明 `ipam` 网段）。

## 远程部署（可选）

仓库同级提供部署脚本（如 `deploy.py`），将代码打包后经 SFTP 上传到目标服务器并远程执行 `docker compose up -d --build`；旧目录会自动迁移备份，上传目录通过 Docker 卷持久化。

## 本地开发（不使用 Docker）

### 后端
```bash
cd backend
pip install -r requirements.txt
# 准备一个可用的 MySQL，并设置 DATABASE_URL
export DATABASE_URL="mysql+pymysql://blog:wang123@localhost:3306/blog?charset=utf8mb4"
uvicorn app.main:app --reload --port 8000
```

### 前端
```bash
cd frontend
npm install
npm run dev
# 开发服务器默认 http://localhost:5173，已配置 /api 代理到 8000 端口
```

## 说明

- 首次启动后端会自动建表，并写入管理员账号与示例分类 / 标签 / 文章；若表结构需新增字段（如评论审核 `approved`、分类顺序 `order`），会在启动时自动迁移补齐。
- 评论默认进入「待审核」状态，仅审核通过的评论在前台公开；管理员可在后台评论管理通过 / 驳回。
- 生产部署请务必修改 `SECRET_KEY`（已在 `docker-compose.yaml` 中设置为随机值，可替换为自有密钥）与数据库 / 管理员密码。