现代化博客系统 - 项目介绍与部署指南

项目简介

这是一个基于 Next.js 16 + PostgreSQL 构建的现代化个人博客系统，具有完整的内容管理功能、高性能优化和优雅的用户界面。

核心特性

🚀 性能优化

• ISR 缓存: 60秒增量静态重生成，大幅提升访问速度
• SSG 预渲染: 前20篇热门文章静态生成
• 图片优化: 自动 WebP/AVIF 转换，响应式加载
• 数据库优化: 8个性能索引，全文搜索支持
• 异步更新: 浏览量异步更新，不阻塞页面渲染

✨ 功能特性

• Markdown 编辑: 富文本编辑器 + 实时预览
• 文章管理: 完整的 CRUD 操作，支持草稿/发布/归档
• 分类标签: 灵活的分类和标签系统
• 图片上传: Vercel Blob 存储，支持外链
• 搜索排序: 全文搜索 + 多字段排序
• 分页功能: 前后台完整分页支持
• n8n 集成: Webhook 支持自动化发布

🎨 用户界面

• 响应式设计: 完美适配桌面端和移动端
• 暗色模式: 自动适配系统主题
• 优雅动画: 流畅的过渡效果和交互
• Poetize 主题: 渐变色彩，现代化视觉

🔒 安全特性

• JWT 认证: 安全的令牌认证机制
• 密码加密: bcrypt 哈希存储
• SQL 注入防护: 参数化查询
• XSS 防护: 内容转义和清理

---

技术栈

前端

• Next.js 16: App Router + Server Components
• React 19: 最新版本的 React
• TypeScript: 类型安全
• Tailwind CSS: 实用优先的 CSS 框架
• AiEditor: 强大的 Markdown 编辑器
• React Markdown: Markdown 渲染

后端

• Next.js API Routes: 服务端 API
• PostgreSQL: 可靠的关系型数据库
• Neon: Serverless PostgreSQL（推荐）
• JWT: 认证令牌
• bcryptjs: 密码加密

部署

• Vercel: 推荐的部署平台
• Vercel Blob: 图片存储
• GitHub Actions: CI/CD（可选）

---

项目结构

my-blog/
├── app/                      # Next.js App Router
│   ├── page.tsx             # 首页
│   ├── blog/                # 博客页面
│   │   ├── [slug]/          # 文章详情
│   │   ├── category/        # 分类页面
│   │   └── tag/             # 标签页面
│   ├── admin/               # 管理后台
│   │   ├── posts/           # 文章管理
│   │   ├── settings/        # 设置管理
│   │   └── login/           # 登录页面
│   └── api/                 # API 路由
│       ├── posts/           # 文章 API
│       ├── auth/            # 认证 API
│       ├── admin/           # 管理 API
│       └── upload/          # 上传 API
├── components/              # React 组件
│   ├── Header.tsx           # 导航栏
│   ├── Footer.tsx           # 页脚
│   ├── BlogCard.tsx         # 文章卡片
│   ├── MarkdownRenderer.tsx # Markdown 渲染器
│   └── admin/               # 后台组件
├── lib/                     # 工具库
│   ├── db.ts                # 数据库连接
│   ├── posts.ts             # 文章数据操作
│   ├── auth.ts              # 认证工具
│   └── utils.ts             # 通用工具
├── sql/                     # SQL 脚本
│   ├── init-postgres.sql    # 数据库初始化
│   └── add-performance-indexes.sql  # 性能索引
├── public/                  # 静态资源
└── scripts/                 # 脚本工具

---

快速开始

环境要求

• Node.js: 18.17 或更高版本
• PostgreSQL: 14 或更高版本（推荐使用 Neon）
• npm/yarn/pnpm: 包管理器

1. 克隆项目

git clone https://github.com/your-username/my-blog.git
cd my-blog

2. 安装依赖

npm install

3. 配置环境变量

创建 .env.local 文件：

# 数据库连接
DATABASE_URL=postgresql://user:password@host:5432/database

# JWT 密钥（生成随机字符串）
JWT_SECRET=your-super-secret-jwt-key-change-this

# Vercel Blob（可选，用于图片上传）
BLOB_READ_WRITE_TOKEN=your-blob-token

# Webhook 密钥（可选，用于 n8n 集成）
WEBHOOK_SECRET=your-webhook-secret

生成 JWT 密钥:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

4. 初始化数据库

# 连接到数据库执行初始化脚本
psql $DATABASE_URL -f sql/init-postgres.sql

# 添加性能索引（推荐）
npm run db:optimize

默认管理员账号:

• 用户名: admin
• 密码: admin123（首次登录后请修改）

5. 启动开发服务器

npm run dev

访问 http://localhost:3000 查看网站 访问 http://localhost:3000/admin 进入后台管理

6. 构建生产版本

npm run build
npm start

---

部署到 Vercel

方法 1: 通过 GitHub（推荐）

1. 推送代码到 GitHub:

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/your-username/my-blog.git
git push -u origin main

2. 连接 Vercel:

   • 访问 Vercel
   • 点击 "Import Project"
   • 选择你的 GitHub 仓库
   • 配置环境变量

3. 设置环境变量: 在 Vercel 项目设置中添加：

   • DATABASE_URL
   • JWT_SECRET
   • BLOB_READ_WRITE_TOKEN
   • WEBHOOK_SECRET

4. 部署:

   • Vercel 会自动构建和部署
   • 每次 push 到 main 分支都会自动重新部署

方法 2: 通过 Vercel CLI

# 安装 Vercel CLI
npm install -g vercel

# 登录
vercel login

# 部署
vercel

# 添加环境变量
vercel env add DATABASE_URL
vercel env add JWT_SECRET

# 部署到生产环境
vercel --prod

部署后配置

1. 初始化数据库 (仅首次):

# 连接到生产数据库
psql $DATABASE_URL -f sql/init-postgres.sql

# 添加性能索引
psql $DATABASE_URL -f sql/add-performance-indexes.sql

2. 配置自定义域名:

   • 在 Vercel 项目设置中添加域名
   • 配置 DNS 解析

3. 修改默认密码:

   • 登录后台: https://your-domain.com/admin/login
   • 进入设置修改密码

---

使用 Neon 数据库

为什么选择 Neon？

• Serverless: 自动扩展，按需付费
• 快速: 极低延迟
• 免费层: 每月 5 GB 免费存储
• 分支功能: 支持数据库分支（开发/预览/生产）

创建 Neon 数据库

1. 访问 Neon
2. 创建新项目
3. 复制连接字符串
4. 添加到 .env.local:

DATABASE_URL=postgresql://user:password@ep-xxx.region.aws.neon.tech/database?sslmode=require

在 Neon 控制台初始化

1. 打开 SQL Editor
2. 复制 sql/init-postgres.sql 内容
3. 执行脚本
4. 复制 sql/add-performance-indexes.sql 内容
5. 执行脚本

---

配置图片上传

使用 Vercel Blob

1. 启用 Vercel Blob:

   • 在 Vercel 项目中启用 Blob 存储
   • 获取 BLOB_READ_WRITE_TOKEN

2. 添加到环境变量:

BLOB_READ_WRITE_TOKEN=vercel_blob_xxx

3. 使用:
   • 后台上传图片时会自动使用 Blob 存储
   • 支持的格式: JPG, PNG, GIF, WebP, SVG
   • 最大文件大小: 5MB

使用外链图片

直接在文章中使用图片 URL：

![图片描述](https://your-image-host.com/image.jpg)

---

n8n 集成

配置 Webhook

1. 设置 Webhook 密钥:

WEBHOOK_SECRET=your-secret-key

2. n8n 工作流配置:
   • 添加 HTTP Request 节点
   • URL: https://your-domain.com/api/webhook/posts
   • Method: POST
   • Headers:
     • Content-Type: application/json
     • X-Webhook-Secret: your-secret-key
   • Body:

{
  "title": "{{ $json.title }}",
  "content": "{{ $json.content }}",
  "author": "{{ $json.author }}",
  "category": "{{ $json.category }}",
  "tags": "{{ $json.tags }}"
}

使用场景

• RSS 订阅自动发布
• 定时任务发布
• 其他系统集成
• 批量导入文章

---

性能优化

已实施的优化

详见 PERFORMANCE.md 文档，包括：

1. ISR 缓存 - 60秒重新验证
2. SSG 预渲染 - 热门文章静态生成
3. 图片优化 - WebP/AVIF 自动转换
4. 数据库索引 - 8个性能索引
5. 连接池优化 - 适配 Serverless 环境
6. 异步更新 - 浏览量不阻塞渲染
7. 压缩 - Gzip/Brotli 启用

性能指标

• 首页 TTFB: ~250ms (优化前 ~800ms)
• 文章页 TTFB: ~200ms (优化前 ~1000ms)
• Lighthouse 分数: 90+
• 搜索速度: ~50ms (优化前 ~500ms)

---

常见问题

1. 数据库连接失败

问题: 无法连接到数据库

解决:

• 检查 DATABASE_URL 是否正确
• 确认数据库服务是否运行
• Neon 数据库需要添加 ?sslmode=require

2. 图片上传失败

问题: 上传失败

解决:

• 检查 BLOB_READ_WRITE_TOKEN 是否设置
• 确认文件大小 < 5MB
• 确认文件格式支持

3. 构建时静态生成警告

问题: 生成静态参数失败

原因: 构建时数据库不可用（正常现象）

解决: 可以忽略，不影响部署

4. 登录失败

问题: 用户名或密码错误

解决:

• 默认账号: admin / admin123
• 检查数据库是否正确初始化
• 查看 admins 表是否有数据

5. 暗色模式不生效

原因: 依赖系统主题

解决: 在操作系统中切换暗色模式

---

维护和更新

数据库备份

# 备份数据库
pg_dump $DATABASE_URL > backup-$(date +%Y%m%d).sql

# 恢复数据库
psql $DATABASE_URL < backup-20240101.sql

更新依赖

# 检查过期依赖
npm outdated

# 更新依赖
npm update

# 更新 Next.js
npm install next@latest react@latest react-dom@latest

监控

建议使用：

• Vercel Analytics: 访问统计
• Sentry: 错误监控
• LogRocket: 用户行为分析

---

开发指南

添加新功能

1. 创建新的 API 路由: app/api/your-feature/route.ts
2. 添加数据库函数: lib/your-feature.ts
3. 创建组件: components/YourFeature.tsx
4. 添加页面: app/your-feature/page.tsx

代码规范

# 格式化代码
npm run lint

# 类型检查
npx tsc --noEmit

Git 提交规范

• feat: 新功能
• fix: 修复bug
• docs: 文档更新
• style: 代码格式
• refactor: 重构
• perf: 性能优化
• test: 测试
• chore: 构建工具

---

安全建议

1. 修改默认密码: 首次登录后立即修改
2. 使用强密码: 至少12位，包含大小写字母、数字、符号
3. 环境变量: 不要提交 .env.local 到 Git
4. HTTPS: 生产环境必须使用 HTTPS
5. 定期更新: 及时更新依赖包
6. 备份: 定期备份数据库
7. 监控: 启用错误日志和异常监控

---

路线图

当前版本 (v1.0.0)

• ✅ 文章 CRUD
• ✅ Markdown 编辑器
• ✅ 图片上传
• ✅ 分类标签
• ✅ 搜索排序
• ✅ 性能优化
• ✅ n8n 集成

计划功能 (v1.1.0)

• ⏳ 评论系统
• ⏳ 文章点赞
• ⏳ RSS 订阅
• ⏳ 站点地图
• ⏳ 多语言支持

未来计划 (v2.0.0)

• 📝 多用户支持
• 📝 权限管理
• 📝 文章版本控制
• 📝 全文搜索引擎
• 📝 AI 写作助手

---

贡献指南

欢迎贡献代码！

1. Fork 项目
2. 创建特性分支: git checkout -b feature/amazing-feature
3. 提交更改: git commit -m 'feat: add amazing feature'
4. 推送分支: git push origin feature/amazing-feature
5. 提交 Pull Request

---

许可证

本项目采用 MIT 许可证。

---

联系方式

• 项目地址: https://github.com/your-username/my-blog
• 在线演示: https://your-demo.vercel.app
• 问题反馈: GitHub Issues
• 邮箱: your-email@example.com

---

鸣谢

感谢以下开源项目：

• Next.js - React 框架
• Tailwind CSS - CSS 框架
• AiEditor - Markdown 编辑器
• PostgreSQL - 数据库
• Neon - Serverless PostgreSQL
• Vercel - 部署平台

---

开始使用: npm install && npm run dev 文档: 查看 PERFORMANCE.md 和 API 文档 部署: 推荐使用 Vercel 版本: v1.0.0 最后更新: 2024-01-01

祝你使用愉快！🎉