# blog

**Repository Path**: mindsynt/blog

## Basic Information

- **Project Name**: blog
- **Description**: 简单博客
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-22
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Blog

全栈个人博客系统，支持文章管理、电子书、留言板、说说、友链、统计分析等功能。

## 技术栈

| 层 | 技术 | 版本 |
|---|---|---|
| 前端框架 | Next.js (App Router) | 16.2 |
| UI 语言 | React | 19 |
| 样式 | Tailwind CSS | 4 |
| 类型系统 | TypeScript | 5 |
| 后端框架 | Django REST Framework | 6.0 |
| 数据库 | SQLite (WAL 模式) | — |
| 认证 | SimpleJWT (Access + Refresh Token) | — |

## 项目结构

```
blog/
├── frontend/                    # Next.js 前端
│   └── src/
│       ├── app/                 # App Router 页面
│       │   ├── about/           # 关于页面
│       │   ├── admin/           # 管理后台
│       │   ├── archive/         # 归档
│       │   ├── books/           # 电子书
│       │   ├── guestbook/       # 留言板
│       │   ├── links/           # 友链
│       │   ├── login/           # 登录
│       │   ├── portfolio/       # 作品集
│       │   ├── posts/           # 文章详情
│       │   ├── register/        # 注册
│       │   ├── search/          # 搜索
│       │   └── timeline/        # 时间线
│       ├── components/          # 共享组件
│       ├── lib/                 # 工具函数（API 客户端、认证工具）
│       └── types/               # TypeScript 类型定义
├── backend/                     # Django 后端
│   ├── api/                     # API 视图层（路由 + 视图）
│   │   ├── admin/               # 管理后台 API
│   │   ├── audit/               # 审计日志
│   │   ├── author/              # 作者信息
│   │   ├── book/                # 电子书
│   │   ├── community/           # 社区（友链、时间线、作品集）
│   │   ├── content/             # 内容（文章、分类、标签）
│   │   ├── cover/               # 封面
│   │   ├── discussion/          # 评论
│   │   ├── guestbook/           # 留言板
│   │   ├── health/              # 健康检查
│   │   ├── identity/            # 认证
│   │   ├── interaction/         # 交互（点赞、收藏）
│   │   ├── media/               # 媒体上传
│   │   ├── monitor/             # 监控统计
│   │   ├── notification/        # 通知
│   │   ├── page/                # 独立页面
│   │   ├── settings/            # 站点设置
│   │   └── shuoshuo/            # 说说
│   ├── application/             # 应用层（序列化器、用例）
│   ├── config/                  # Django 配置（settings, urls, wsgi, asgi）
│   ├── domains/                 # 领域层（实体、仓库接口）
│   └── infrastructure/          # 基础设施（数据库模型、中间件、存储）
├── deploy/                      # 部署脚本
│   ├── deploy.sh                # 主部署脚本
│   ├── systemd/                 # systemd 服务单元文件
│   └── logrotate/               # 日志轮转配置
└── README.md
```

## 快速开始（开发环境）

### 后端

```bash
cd backend

# 创建虚拟环境（如已存在则跳过）
python -m venv venv

# 激活虚拟环境
# Linux/macOS:
source venv/bin/activate
# Windows:
.\venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 数据库迁移
python manage.py migrate

# 启动开发服务器（默认 http://localhost:8000）
python manage.py runserver
```

### 前端

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器（默认 http://localhost:3000，API 代理到 :8000）
npm run dev
```

开发环境下，前端通过 Next.js `rewrites` 将 `/api/*` 请求代理到 `http://localhost:8000`，无需额外配置。

首次运行 `migrate` 后自动创建默认管理员账号：

| 用户名 | 密码 |
|--------|------|
| `admin` | `admin123` |

> ⚠️ 生产环境部署后请立即修改密码或删除默认账号。

## API 概述

所有 API 端点以 `/api/` 为前缀。需要认证的端点需在请求头携带 JWT Token：

```
Authorization: Bearer <access_token>
```

### 认证

| 方法 | 端点 | 说明 |
|------|------|------|
| POST | `/api/auth/login/` | 登录，返回 access + refresh token |
| POST | `/api/auth/register/` | 注册 |
| POST | `/api/auth/refresh/` | 刷新 access token |
| GET | `/api/auth/me/` | 获取当前用户信息 🔐 |
| POST | `/api/auth/change-password/` | 修改密码 🔐 |

### 内容

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/api/posts/` | 文章列表（分页，每页 10 篇） |
| GET | `/api/posts/<id>/` | 文章详情 |
| GET | `/api/categories/` | 分类列表 |
| GET | `/api/tags/` | 标签列表 |
| GET | `/api/search/?q=<keyword>` | 搜索文章 |

### 评论

| 方法 | 端点 | 说明 |
|------|------|------|
| GET/POST | `/api/posts/<post_id>/comments/` | 文章评论列表 / 发表评论 |

### 交互

| 方法 | 端点 | 说明 |
|------|------|------|
| POST | `/api/posts/<post_id>/like/` | 点赞/取消点赞 🔐 |
| POST | `/api/posts/<post_id>/favorite/` | 收藏/取消收藏 🔐 |
| GET | `/api/my/favorites/` | 我的收藏列表 🔐 |

### 媒体

| 方法 | 端点 | 说明 |
|------|------|------|
| POST | `/api/upload/` | 上传文件 🔐 |
| GET | `/api/uploads/` | 文件列表 🔐 |
| GET | `/api/covers/` | 封面列表 |

### 电子书

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/api/books/` | 电子书列表 |
| GET | `/api/books/<id>/` | 电子书详情 |
| GET | `/api/books/<book_id>/chapters/` | 章节列表 |

### 监控

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/api/monitor/stats/` | 站点统计 |
| GET | `/api/monitor/daily/` | 每日统计 |
| GET | `/api/monitor/server/` | 服务器状态 |
| GET | `/api/health/` | 健康检查 |

完整 API 端点列表见 `backend/api/urls.py`。

### SEO 端点

| 端点 | 说明 |
|------|------|
| `/robots.txt` | 爬虫规则 |
| `/sitemap.xml` | 站点地图 |
| `/feed.xml` | RSS 订阅 |

## 部署

项目内置部署脚本，支持 **Linux + systemd** 环境。

### 先决条件

- Python ≥ 3.13
- Node.js ≥ 20
- npm
- systemd（用于进程管理）

### 首次部署

在服务器上克隆代码后运行：

```bash
sudo ./deploy/deploy.sh install
```

部署脚本会自动完成以下步骤：

1. 检查前置依赖
2. 创建系统用户 `blog`
3. 创建目录 `/opt/blog`、`/var/log/blog`
4. 创建 Python 虚拟环境并安装依赖
5. 安装前端依赖并构建
6. 生成 `.env` 配置文件（自动生成 Django Secret Key）
7. 执行数据库迁移、收集静态文件
8. 设置目录权限
9. 安装 systemd 服务单元并启动
10. 健康检查验证

部署后请编辑 `/opt/blog/.env`，将 `DJANGO_ALLOWED_HOSTS` 和 `DJANGO_CORS_ORIGINS` 改为你的实际域名。

### 更新部署

```bash
sudo ./deploy/deploy.sh update
```

更新流程：
1. `git pull` 拉取最新代码
2. 通过 `git diff` 检测前后端变更
3. 仅对变更部分执行重建
4. 数据库迁移（幂等安全）
5. 仅重启有变更的服务
6. 健康检查验证

### 其他命令

```bash
./deploy/deploy.sh status          # 查看服务状态
./deploy/deploy.sh restart         # 重启所有服务
./deploy/deploy.sh logs backend    # 查看后端日志
./deploy/deploy.sh logs frontend   # 查看前端日志
./deploy/deploy.sh setup-systemd   # 安装/刷新 systemd 单元
```

### systemd 服务架构

| 服务 | 监听地址 | 说明 |
|------|----------|------|
| `blog-backend.service` | `127.0.0.1:8000` | Gunicorn + Uvicorn (ASGI, 4 workers) |
| `blog-frontend.service` | `0.0.0.0:3000` | Next.js 生产服务器 |

前端作为唯一入口，通过 Next.js `rewrites` 将 `/api/*` 反向代理到后端。

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DJANGO_SECRET_KEY` | — | Django 秘钥（首次部署自动生成） |
| `DJANGO_DEBUG` | `false` | 调试模式 |
| `DJANGO_ALLOWED_HOSTS` | `localhost` | 允许的主机名（逗号分隔） |
| `DJANGO_CORS_ORIGINS` | `http://localhost:3000` | 允许的跨域来源（逗号分隔） |
| `DB_PATH` | `backend/db.sqlite3` | 数据库文件路径 |
| `MEDIA_ROOT` | `backend/media` | 媒体文件存储路径 |
| `STATIC_ROOT` | `backend/staticfiles` | 静态文件收集路径 |

## 开发规范

- **代码标识符**：遵循项目既有命名约定，文档和注释使用简体中文
- **风格**：Django REST Framework 最佳实践，前后端分离
- **数据库**：SQLite WAL 模式（个人博客场景足够），后续可按需迁移 PostgreSQL

## License

MIT