summaryrefslogtreecommitdiff
path: root/README-zh
diff options
context:
space:
mode:
authorBertrand Yuan <me@bertyuan.com>2025-12-31 16:43:47 +0800
committerBertrand Yuan <me@bertyuan.com>2025-12-31 16:43:47 +0800
commit828c8eb046096691675838d530d8b49db4d58425 (patch)
tree8a2fb7b12a3ac778216fe6f77ee40a65b256fe63 /README-zh
parent3d25fb9ab9a0565aac3d4362cdbe7a61b5ece2f0 (diff)
docs: add instructions in readme
Diffstat (limited to 'README-zh')
-rw-r--r--README-zh115
1 files changed, 0 insertions, 115 deletions
diff --git a/README-zh b/README-zh
deleted file mode 100644
index ce565f3..0000000
--- a/README-zh
+++ /dev/null
@@ -1,115 +0,0 @@
-Next blog
-=========
-
-基于 Next.js 15 与 Payload CMS 的全栈博客,内置认证、评论、搜索、RSS 和邮件模板。
-
-项目简介
---------
-
-前端使用 Next.js App Router 配合 Tailwind 和 shadcn,并借助 fumadocs 的组件搭建导航、分页与搜索。
-内容由 Payload CMS(payload.config.ts)管理,支持富文本、标签、封面图与发布状态。
-认证使用 better-auth,支持 Google 和 GitHub;会话与评论通过 Drizzle ORM 写入 Postgres。
-评论集成 @fuma-comment,站点同时生成 /rss.xml 订阅源与 /api/search 搜索索引。
-
-主要特性
---------
-
-文章管理:Payload 后台 /admin 可创建草稿或已发布文章,支持封面、标签与定时发布时间。
-博客体验:列表分页、标签聚合页、文章详情富文本渲染、分享按钮、一键复制链接。
-社交与互动:Google 或 GitHub 登录,better-auth 会话管理,Fuma Comment 评论存储在本地数据库。
-增强能力:RSS 输出、站内搜索索引、自动 Open Graph Banner、next-sitemap 生成站点地图。
-邮件模板:emails/newsletter-welcome.tsx 提供 React Email + Tailwind 的欢迎邮件,可接入 Resend。
-运维友好:.env 校验、start-database.sh 一键启动本地 Postgres,统一的 Drizzle 与 Payload 脚本。
-
-技术栈
-------
-
-框架:Next.js 15(App Router),服务端组件,静态与动态混合渲染。
-UI:Tailwind CSS 4、shadcn、fumadocs-ui,用于导航、分页、Section 和主题。
-内容:Payload CMS 管理 Posts、Users、Media,使用 Lexical 富文本。
-数据:PostgreSQL 与 Drizzle ORM,认证与评论表以 blog_* 作为前缀。
-认证:better-auth + OAuth(Google/GitHub),包含会话和额外角色字段。
-邮件:Resend 与 React Email,Tailwind 样式的欢迎模板。
-
-快速开始
---------
-
-1. 安装工具链。推荐 Node 20+,使用 pnpm(已锁定 pnpm-lock.yaml)。
-2. 配置环境变量。复制 .env.example 为 .env,填写 DATABASE_URL、PAYLOAD_SECRET、BETTER_AUTH_SECRET,如需社交登录补齐 OAuth。
-3. 启动 Postgres。运行 ./start-database.sh(依赖 Docker/Podman),或连接自带的 Postgres 实例。
-4. 安装依赖并生成结构。执行 pnpm install;pnpm db:generate && pnpm db:migrate 处理 Drizzle;pnpm payload:migrate 同步 Payload CMS。
-5. 运行开发服务器。pnpm dev(默认 3000,后台 /admin,博客 /)。
-6. 可选步骤。pnpm payload:generate 生成类型;pnpm email:dev -p 3001 预览邮件模板。
-开发模式下,Payload 登录框会预填 admin@example.com / admin123。
-
-核心模块
---------
-
-内容模型位于 payload.config.ts,定义文章、用户、媒体,支持封面上传、标签数组、发布时间与状态。
-数据访问封装在 src/lib/payload-posts.ts,用于文章查询、标签统计、分页与 slug 工具。
-页面与布局在 src/app/(main),_components 内含 Hero、CTA、文章列表等 UI。
-认证与评论位于 src/server/auth(better-auth + Drizzle)和 src/server/comments(写入 blog_comments 表)。
-搜索与订阅在 src/app/(main)/api/search/route.ts(索引)与 src/app/(main)/rss.xml/route.ts(Atom/RSS)。
-邮件模板是 emails/newsletter-welcome.tsx,可接受文章数组渲染卡片。
-
-项目结构(节选)
-----------------
-
-src/
- app/
- (main)/(home)/page.tsx 首页:Hero、最近文章、CTA
- (main)/(home)/posts/[slug]/page.tsx 文章详情、评论、分享
- (main)/(home)/posts/page.tsx 分页文章列表
- (main)/(home)/tags/page.tsx 标签聚合
- (main)/api/search/route.ts 搜索索引接口
- (main)/rss.xml/route.ts Atom/RSS 输出
- (payload)/admin/... Payload CMS 后台
- lib/ 数据与工具(payload-posts、metadata、auth-client)
- server/ better-auth 与 Drizzle schema,评论存储
- emails/ React Email 模板
-
-环境变量
---------
-
-常用或必填项:
- DATABASE_URL:Postgres 连接串,例如 postgresql://user:pass@localhost:5432/blog
- PAYLOAD_SECRET:Payload CMS 的 JWT 密钥
- BETTER_AUTH_SECRET:better-auth 会话密钥
- BETTER_AUTH_URL:认证回调地址,本地可用 http://localhost:3000
- NEXT_PUBLIC_SERVER_URL:生成链接、OG、RSS 的基础地址
- RESEND_API_KEY / RESEND_AUDIENCE_ID / EMAIL_FROM:发送邮件所需
- GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET:启用 Google 登录时必填
- GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET:启用 GitHub 登录时必填
- NEXT_PUBLIC_UMAMI_URL / NEXT_PUBLIC_UMAMI_WEBSITE_ID:可选分析
-
-常用脚本
---------
-
-pnpm dev 启动 Next.js 开发服务器(含 Payload routes)
-pnpm build 构建生产包
-pnpm preview 预览生产构建
-pnpm db:generate 生成 Drizzle 迁移(认证/评论表)
-pnpm db:migrate 执行 Drizzle 迁移
-pnpm payload:migrate 同步 Payload CMS 数据表
-pnpm lint 质量检查(biome)
-pnpm format 代码格式化(biome)
-pnpm email:dev 本地预览 React Email 模板
-
-页面与接口
-----------
-
-/ 首页,Hero、最新文章、CTA
-/posts 文章分页;/posts/[slug] 展示详情、富文本、评论、分享
-/tags 标签云与计数
-/login Google/GitHub 登录入口
-/admin Payload CMS 后台
-/api/search 站内搜索索引接口(fumadocs search)
-/rss.xml Atom/RSS 订阅
-
-开发提示
---------
-
-优先使用 ./start-database.sh 启动本地 Postgres,脚本会提示端口占用。
-认证与评论表使用 blog_ 前缀,保持 drizzle.config.ts 中的 tablesFilter 一致。
-开发模式下 Payload 自动填充 <admin@example.com> / admin123,便于快速登录。
-只想浏览 UI 时可设置 SKIP_ENV_VALIDATION=1,并关闭依赖外部服务的功能;完整环境更可靠。