YN Blog - 现代化博客平台

一个基于 Next.js 16 和 Supabase 构建的功能完整、开箱即用的现代化博客系统。具备完整的前后台功能、嵌套评论系统、SEO 优化、深色模式、响应式设计，以及企业级安全防护（RLS 行级安全、Rate Limiting、XSS 防护、审计日志）。

无需编写一行代码，即可拥有一个功能完整的个人博客。

📚 目录

• 项目介绍
• 功能特性
• 技术栈
• 架构总览
• 快速开始（5 分钟上手）
• 环境要求
• 详细部署指南
• Supabase 存储配置
• Cloudflare R2 音频存储配置
• Supabase RLS 策略详解
• 环境变量说明
• 开发指南
• 常见问题与排障
• 贡献指南
• 许可证

🌟 项目介绍

YN Blog 是一个面向个人博主、技术写作者和小型内容团队的博客系统。它将 Next.js 的服务端渲染能力与 Supabase 的后端服务（PostgreSQL 数据库、Auth 认证、Storage 文件存储）相结合，提供从内容创作、发布到读者互动的完整闭环。

适合人群

• 想搭建个人博客的技术爱好者
• 想学习 Next.js App Router 与 Supabase 全栈开发的开发者
• 需要一个轻量级、可自托管 CMS 的内容创作者

核心亮点

• 全栈一体化：前端、后端、数据库、存储、认证一站式集成
• 服务端渲染：基于 Next.js App Router，首屏快、SEO 友好
• 行级安全：Supabase RLS 策略保证数据隔离，权限细化到行
• 渐进增强：Redis 缺失时自动降级到内存限流，开发零配置
• 安全加固：CSP 安全头、XSS 过滤、文件魔数校验、IP 限流、审计日志

✨ 功能特性

🏠 前台功能（访客使用）

🎛️ 后台管理（管理员 / 作者使用）

👥 用户与权限系统

🔒 安全特性

🛠️ 技术栈

前端

后端服务

🏗️ 架构总览

项目采用分层架构，职责清晰：

请求 → middleware.ts（鉴权/重定向）
         ↓
   App Router 页面（Server Components）
         ↓
   Server Actions（@/actions） ← 表单提交 / 数据变更
         ↓
   Services 业务层（@/services） ← 业务逻辑
         ↓
   Repositories 数据层（@/repositories） ← 数据访问
         ↓
   Supabase Client（admin / browser）

分层说明：

• src/app：Next.js App Router 页面与路由
  • src/app/profiles/[id]/：统一用户/作者主页（替代旧的 /authors/[id]）
• src/actions：Server Actions，处理表单提交与数据变更
• src/services：业务逻辑层，所有文件含 import "server-only"
• src/repositories：数据访问层，封装 Supabase 查询
• src/lib：通用工具（鉴权、缓存、限流、日志、验证等）
• src/components：React 组件（按 admin/、ui/、music/、layout/ 等分类）
  • src/components/music/：音乐播放器组件（PersistentMusicPlayer、MiniMusicPlayer 等）

🚀 快速开始（5 分钟上手）

环境要求

关于 Redis：生产环境必需（支持多实例部署的限流）；本地开发可不配置，自动降级为内存限流。

第一步：获取代码

git clone https://github.com/你的用户名/yn-blog.git
cd yn-blog

或访问 GitHub 仓库 → 「Code」→「Download ZIP」→ 解压后进入目录。

第二步：安装依赖

npm install

国内网络较慢时使用镜像：

npm install --registry=https://registry.npmmirror.com

第三步：配置 Supabase

3.1 注册并创建项目

1. 访问 supabase.com，注册登录
2. 点击「New Project」创建新项目
3. 填写：项目名称、数据库密码、选择离你最近的区域
4. 等待约 2 分钟项目初始化完成

3.2 获取项目凭据

进入项目 → 左侧「Project Settings」→「API」，记录：

• Project URL（形如 https://xxxxxx.supabase.co）
• anon public 密钥
• service_role secret 密钥（切勿泄露）

3.3 配置环境变量

复制 .env.example 为 .env.local，填入凭据：

NEXT_PUBLIC_SUPABASE_URL=https://你的项目ID.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=你的anon密钥
SUPABASE_SERVICE_ROLE_KEY=你的service密钥
NEXT_PUBLIC_SITE_URL=http://localhost:3000

第四步：初始化数据库

1. 在 Supabase 项目中点击左侧「SQL Editor」→「New query」
2. 打开项目目录下的 supabase/init.sql，复制全部内容粘贴到编辑器
3. 点击「Run」执行
4. 看到输出 Database initialization complete! 即成功

该脚本会创建所有表、索引、触发器、RPC 函数、RLS 策略、存储桶，并初始化默认设置和白名单域名。

第五步：启动项目

npm run dev

打开浏览器访问 http://localhost:3000 即可看到博客首页。

第六步：创建管理员账号

1. 访问 http://localhost:3000/register 注册账号并登录
2. 回到 Supabase →「Table Editor」→ 找到 profiles 表
3. 找到你刚注册的用户，将 role 字段值改为 admin
4. 退出博客并重新登录（让 JWT 更新角色）
5. 访问 http://localhost:3000/admin 进入后台

📦 详细部署指南

推荐部署平台：Vercel（免费）

准备工作

1. 代码已推送到 GitHub
2. 注册 Vercel 账号

部署步骤

1. 访问 Vercel Dashboard →「Add New」→「Project」
2. 选择你的 GitHub 仓库 →「Import」
3. 在配置页面填写：
   • Framework Preset：自动识别为 Next.js
   • Root Directory：保持默认
   • Environment Variables：依次添加
     • NEXT_PUBLIC_SUPABASE_URL
     • NEXT_PUBLIC_SUPABASE_ANON_KEY
     • SUPABASE_SERVICE_ROLE_KEY
     • NEXT_PUBLIC_SITE_URL（例如 https://your-blog.vercel.app）
     • REDIS_URL（推荐配置，格式 redis://:password@host:port，可使用 Upstash、Redis Cloud 等托管服务）
4. 点击「Deploy」，等待 2-3 分钟构建完成

部署后更新 Supabase 配置

1. 回到 Supabase →「Authentication」→「URL Configuration」
2. 将「Site URL」更新为你的 Vercel 域名
3. 在「Redirect URLs」中添加：
   • https://你的域名/auth/callback
   • http://localhost:3000/auth/callback（保留本地开发）

可选：配置 Sentry 错误监控

1. 注册 Sentry 账号并创建 Next.js 项目
2. 在 Vercel 环境变量中添加：
   • NEXT_PUBLIC_SENTRY_DSN
   • SENTRY_ORG
   • SENTRY_PROJECT
   • SENTRY_AUTH_TOKEN
3. 重新部署，Sentry 自动接管错误上报

未配置 NEXT_PUBLIC_SENTRY_DSN 时，Sentry 完全 no-op，不影响应用功能。

其他部署方式

项目也支持部署到任何支持 Next.js 的平台（如自托管 Node.js 服务器、Docker 等）。部署时需确保：

• Node.js ≥ 18.17 运行环境
• 所有环境变量已正确注入
• Redis 实例可访问（生产环境）
• Supabase 项目的「Redirect URLs」已包含你的域名回调路径

🗄️ Supabase 存储配置

本项目使用单个 media 存储桶管理所有用户上传的文件（文章封面、图片、PDF 等）。

存储桶配置

supabase/init.sql 已自动创建 media 存储桶：

存储桶策略

关于 Storage 安全警告

在 Supabase Dashboard 的 Storage 页面，可能看到警告：

"Clients can list all files in this bucket"

此警告可安全忽略，原因：

• 本项目不直接从 Storage 桶读取文件列表
• 文件元数据存储在 media_files 数据库表中
• 通过 media_files 表的 RLS 策略控制访问
• Storage 桶仅用于文件存储与公开读取

建议点击警告右侧「Remove policy」移除该策略以提升安全性。

上传处理流程

1. 前端提交文件到 handleUploadFile Server Action
2. 校验文件大小、MIME 类型、文件头魔数（防伪装攻击）
3. 图片使用 sharp 自动压缩并转换为 WebP / PNG 格式
4. PDF 校验文件头 %PDF-
5. 通过 service role 上传到 media 桶
6. 文件元数据写入 media_files 表

☁️ Cloudflare R2 音频存储配置

本项目使用 Cloudflare R2 存储音频文件，通过 Cloudflare Worker 实现客户端直传和代理播放。

架构说明

客户端 → Cloudflare Worker（上传/删除/播放代理）
         ↓
   Cloudflare R2 Bucket（音频文件存储）

配置步骤

1. 创建 R2 Bucket

1. 登录 Cloudflare Dashboard
2. 进入「R2」→「Create Bucket」
3. 填写 Bucket 名称（如 yn-blog-audio）
4. 记录 Bucket 名称

2. 创建 Worker 脚本

1. 进入「Workers & Pages」→「Create Application」→「Worker」
2. 从项目目录 cloudflare/worker.js 复制全部内容
3. 粘贴到 Worker 编辑器中
4. 绑定 R2 Bucket：在 Worker Settings → Bindings → R2 Bucket Bindings 中添加
   • Variable name: AUDIO_BUCKET
   • Bucket name: 你的 R2 Bucket 名称
5. 设置 Secret：
   • Variable name: AUDIO_UPLOAD_KEY
   • Value: 运行 openssl rand -base64 48 生成的随机密钥

3. 配置环境变量

在项目 .env.local 中添加：

NEXT_PUBLIC_AUDIO_CDN_URL=https://你的-worker-name.your-subdomain.workers.dev
NEXT_PUBLIC_AUDIO_UPLOAD_KEY=与Worker中AUDIO_UPLOAD_KEY相同的密钥
AUDIO_UPLOAD_KEY=同上（服务端删除文件用）

安全说明

• Worker 通过 AUDIO_UPLOAD_KEY 验证上传/删除请求
• 播放请求直接返回 R2 预签名 URL，不经过 Worker 代理
• 前端通过 navigator.onLine 检测离线状态，离线时隐藏播放器

🔐 Supabase RLS 策略详解

为什么需要 RLS 策略

RLS（Row Level Security）是 Supabase 提供的行级安全功能，确保：

• 用户只能访问和修改自己的数据
• 不同角色拥有不同权限
• 防止未授权的数据访问

本项目所有表均已启用 RLS，策略已包含在 supabase/init.sql 中，执行脚本即可自动创建。

JWT 角色检查机制

本项目采用基于 JWT 的角色检查（app_meta_role() 函数），替代传统的 profiles 表子查询：

• sync_role_to_jwt() 触发器在 profiles.role 变更时，自动将新角色写入 auth.users.raw_app_meta_data.role
• 同时撤销该用户的所有会话，强制重新登录获取含新角色的 JWT
• RLS 策略通过 app_meta_role() 直接读取 JWT，零 IO，性能更优

策略清单（主要表）

profiles 表（用户资料）

posts 表（文章）

tracks 表（音乐曲目）

comments 表（评论）

其他表策略

categories、tags、media_files、site_settings、favorites、audit_logs、email_whitelist、user_cleanup_logs、role_applications、messages、announcements、links、link_applications、subscribers、tracks 等表均已配置对应 RLS 策略，详见 supabase/init.sql 文件。

验证策略是否生效

方法 1：Supabase Dashboard

进入「Table Editor」→ 选择表 →「Policies」标签 → 查看策略列表。

方法 2：SQL 查询

SELECT 
  schemaname, tablename, policyname, permissive, roles, cmd, qual, with_check
FROM pg_policies
WHERE schemaname = 'public'
ORDER BY tablename, policyname;

方法 3：实际测试

使用普通用户登录，尝试访问其他用户数据，确认被正确阻止。

角色权限矩阵

⚙️ 环境变量说明

必需变量

Redis 配置（生产环境必需）

Redis 用于：订阅限流、登录限流、上传限流、删除限流、链接申请限流等。未配置时自动降级为内存限流（仅适用于单实例部署）。

音乐音频配置（可选）

音乐功能使用 Cloudflare R2 存储音频文件，通过 Worker 实现客户端直传和代理播放。未配置时音乐播放器仍可显示但不支持上传新曲目。

可选变量

Sentry 配置（可选）

未配置 NEXT_PUBLIC_SENTRY_DSN 时，Sentry 完全 no-op，不影响应用功能。

👨‍💻 开发指南

可用命令

项目结构

yn-blog/
├── public/                  # 静态资源（favicon、OG 图、赞助码等）
├── cloudflare/              # Cloudflare Worker 脚本（音频上传/删除代理）
├── src/
│   ├── actions/             # Server Actions（服务端操作）
│   │   └── __tests__/       # Action 单元测试
│   ├── app/                 # Next.js App Router（页面路由）
│   │   ├── admin/           # 后台管理页面
│   │   │   └── tracks/      # 曲目管理页面
│   │   ├── api/             # API 路由（健康检查、统计等）
│   │   ├── auth/            # 认证页面（登录、注册、回调）
│   │   ├── profiles/        # 统一用户/作者主页
│   │   ├── posts/           # 文章页面
│   │   └── ...              # 其他页面
│   ├── components/          # React 组件
│   │   ├── admin/           # 后台管理组件
│   │   ├── hero/            # 首页横幅组件
│   │   ├── layout/          # 布局组件（Header / Footer）
│   │   ├── music/           # 音乐播放器组件
│   │   ├── ui/              # 基础 UI 组件
│   │   └── ...              # 功能组件
│   ├── constants/           # 常量定义
│   ├── contexts/            # React Context
│   ├── hooks/               # 自定义 Hooks
│   │   └── admin/           # 后台管理 Hooks
│   ├── lib/                 # 工具库
│   │   ├── supabase/        # Supabase 客户端
│   │   └── ...              # 鉴权、缓存、限流、日志等
│   ├── repositories/        # 数据访问层
│   │   └── __tests__/       # Repository 单元测试
│   ├── services/            # 业务逻辑层
│   ├── test/                # 测试基础设施
│   │   ├── mocks/           # 测试 Mock
│   │   ├── security/        # 安全测试
│   │   └── seo/             # SEO 测试
│   ├── types/               # TypeScript 类型定义
│   ├── utils/               # 工具函数
│   │   └── validators/      # 验证器
│   └── middleware.ts        # 路由鉴权中间件
├── supabase/
│   ├── init.sql             # 数据库初始化脚本（含表、索引、RLS、存储桶、tracks 表）
│   └── migrations/          # 增量迁移脚本（用于已部署库的版本追踪）
├── instrumentation.ts       # Next.js Instrumentation（Sentry 集成）
├── sentry.*.config.ts       # Sentry 多运行时配置（client / server / edge）
├── next.config.mjs          # Next.js 配置（图片优化、安全头、缓存）
├── tailwind.config.ts       # Tailwind 配置
├── vitest.config.ts         # Vitest 测试配置
└── tsconfig.json            # TypeScript 配置

开发约定

• Server Actions 必须使用 Zod schema 校验所有输入
• Service 层文件必须包含 import "server-only" 防止客户端导入
• 后台页面统一使用 AutoRefreshServer 包装实现 1 分钟自动刷新
• 加载状态统一使用 LoadingSpinner 显示「加载中...」
• 返回按钮使用 router.back() 返回上一页
• 评论回复占位符动态显示「回复：{username}：{评论内容}」
• 草稿预览token 有效期 7 天，存储于 preview_token_expires_at 字段
• 文章阅读时间预计算并存储在 posts.reading_time 列
• 根布局不调用 getAuthState() 或 cookies()，认证状态在客户端水合后获取
• 用户主页统一使用 /profiles/[id] 路由（替代旧的 /authors/[id]）
• 新标签页链接不触发全屏加载动画（通过 Ctrl/Shift/Meta 键或中键检测）
• 加载状态在页面可见性变为 hidden 时自动停止（防止后台标签页无限加载）

❓ 常见问题与排障

1. npm install 失败

现象：安装依赖时卡住或报错

排查步骤：

1. 检查 Node.js 版本：node -v，需 ≥ 18.17
2. 删除 node_modules 和 package-lock.json
3. 重新运行 npm install
4. 网络慢时使用镜像：npm install --registry=https://registry.npmmirror.com
5. 清除 npm 缓存：npm cache clean --force

2. 数据库连接失败

现象：Failed to connect to Supabase 或类似错误

排查步骤：

1. 检查 .env.local 中 NEXT_PUBLIC_SUPABASE_URL 和密钥是否正确
2. 确认值两端没有多余空格或引号
3. 确认 Supabase 项目未暂停（免费项目闲置一周会自动暂停）
4. 检查网络能否访问 Supabase 域名
5. 确认 SUPABASE_SERVICE_ROLE_KEY 与 NEXT_PUBLIC_SUPABASE_ANON_KEY 未填反

3. 图片上传失败

现象：上传图片后显示不出来或报错

排查步骤：

1. 确认 Storage 中存在 media 桶（执行 init.sql 会自动创建）
2. 确认桶为「Public」属性
3. 检查 SUPABASE_SERVICE_ROLE_KEY 是否正确
4. 检查文件大小是否超过 10 MB 限制
5. 检查文件 MIME 类型是否在允许列表中
6. 查看浏览器控制台与服务端日志的具体错误

4. 评论无法提交

现象：点击提交评论没反应或报错

排查步骤：

1. 确认用户已登录
2. 检查 comments 表是否创建成功（执行 init.sql）
3. 检查 RLS 策略是否正确配置
4. 查看浏览器控制台错误信息
5. 确认评论内容非空且未触发限流

5. 后台管理页面无权限

现象：访问 /admin 被重定向或提示无权限

排查步骤：

1. 确认已登录
2. 在 Supabase「Table Editor」中查看 profiles 表，确认你的 role 为 admin
3. 退出并重新登录（让 JWT 包含新角色；sync_role_to_jwt() 会撤销旧会话）
4. 清除浏览器 cookie 后重新登录
5. 检查中间件日志是否有异常

6. 部署后图片无法加载

现象：Vercel 部署后图片显示裂图

排查步骤：

1. 检查 next.config.mjs 中 images.remotePatterns 是否包含你的图片域名
2. 确认 Supabase Storage 的 CORS 设置包含你的域名
3. 检查图片 URL 是否正确
4. 确认图片未过期或被删除

7. 登录后跳回 localhost

现象：生产环境登录后重定向到 localhost

排查步骤：

1. 确认 NEXT_PUBLIC_SITE_URL 环境变量已设为生产域名
2. 在 Supabase「Authentication」→「URL Configuration」中更新「Site URL」为生产域名
3. 在「Redirect URLs」中添加 https://你的域名/auth/callback

8. OAuth 社交登录 404

现象：GitHub / Google 登录回调返回 404

排查步骤：

1. 在 Supabase「Authentication」→「URL Configuration」的「Redirect URLs」中添加 https://你的域名/auth/callback
2. 确认 OAuth Provider 已在 Supabase 中启用并配置了 Client ID / Secret
3. 检查 OAuth 应用的回调 URL 是否指向 Supabase（非应用域名）

9. 限流未生效或误报

现象：接口频率限制异常

排查步骤：

1. 生产环境：确认 REDIS_URL 已配置且 Redis 实例可达
2. 开发环境：未配置 Redis 时自动降级为内存限流（仅单实例有效）
3. 检查 Vercel 函数日志中是否有 Redis 连接错误
4. 确认限流 key 的维度（IP / 用户 ID）符合预期

10. 构建失败：Turbopack 相关错误

现象：npm run build 报错

排查步骤：

1. 确认 Node.js 版本 ≥ 18.17
2. 删除 .next 目录后重新构建
3. 检查是否有 Server Component 中误用了 <script> 标签（Next.js 16 + Turbopack 不允许）
4. 运行 npm run lint 检查代码问题
5. 检查环境变量是否完整配置

11. 角色变更后权限未更新

现象：升级用户角色后，用户仍无对应权限

原因：sync_role_to_jwt() 触发器会撤销旧会话，需重新登录获取新 JWT

解决：让用户退出并重新登录即可。

12. 后台数据不更新

现象：编辑文章后列表未刷新

排查步骤：

1. 后台页面使用 1 分钟自动刷新，等待或手动刷新页面
2. 检查 Server Action 是否调用了 revalidatePath
3. 开发环境重启 dev server
4. 检查浏览器是否缓存了旧数据（强制刷新 Ctrl+F5）

13. 音乐播放器无法播放音频

现象：点击播放无声音或报错

排查步骤：

1. 检查 NEXT_PUBLIC_AUDIO_CDN_URL 环境变量是否正确配置
2. 确认 Cloudflare Worker 已部署且正常运行
3. 检查 R2 Bucket 中是否有对应的音频文件
4. 查看浏览器控制台是否有 CORS 错误
5. 确认 next.config.mjs 中 CSP 的 media-src 和 connect-src 已包含音频域名
6. 检查 navigator.onLine 状态，离线模式下播放器会自动隐藏

14. 曲目管理页面 403 无权限

现象：访问 /admin/tracks 提示无权限

排查步骤：

1. 确认当前用户角色为 admin 或 editor
2. 在 Supabase「Table Editor」中查看 profiles 表，确认 role 字段正确
3. 退出并重新登录（让 JWT 包含新角色）

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

贡献流程

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/awesome-feature
3. 提交更改：git commit -m 'Add some awesome feature'
4. 推送分支：git push origin feature/awesome-feature
5. 创建 Pull Request

开发规范

• 提交前运行 npm run lint 和 npm run test 确保通过
• 遵循现有代码风格（TypeScript + 函数式组件）
• 新增功能需附带单元测试
• 新增 Server Action 必须使用 Zod 校验输入
• 新增 Service 文件必须包含 import "server-only"
• 数据库变更需同步更新 supabase/init.sql
• 曲目管理变更需同步更新 supabase/migrations/ 中的迁移脚本
• Cloudflare Worker 脚本位于 cloudflare/worker.js，修改后需同步部署到 Cloudflare

📄 许可证

MIT License - 详见 LICENSE 文件。

💬 获取帮助

如果遇到问题：

1. 查看上方「常见问题与排障」部分
2. 检查浏览器控制台与服务端日志
3. 提交 GitHub Issue，附上错误信息与复现步骤

🙏 致谢

感谢以下优秀的开源项目：

• Next.js
• Supabase
• Tailwind CSS
• Framer Motion
• Lucide

❤️ 支持与赞助

如果这个项目对你有帮助，欢迎请作者喝杯咖啡，支持持续维护与开发。

(上) 支付宝 / (下) 微信

如果这个项目对你有帮助，请给个 Star ⭐ 支持一下！

Built with ❤️