Petrichor

<div align="center">

<img src="apps/web/public/sidebar-logo.jpg" alt="Petrichor" width="120" height="120" />

# Petrichor

**一个开箱即用的全栈知识库与博客平台 · 基于 Next.js + Supabase + Vercel**

*An open-source full-stack knowledge base & blog platform built with Next.js, Supabase and Vercel.*

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Next.js](https://img.shields.io/badge/Next.js-16-black?logo=next.js)](https://nextjs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Supabase](https://img.shields.io/badge/Supabase-PostgreSQL-3ECF8E?logo=supabase&logoColor=white)](https://supabase.com)
[![Vercel](https://img.shields.io/badge/Deploy-Vercel-black?logo=vercel)](https://vercel.com)

[**🌐 产品官网**](https://petrichor.wl.do) ·
[**📖 在线 Demo（前台）**](https://wl.do)

[**🚀 一键部署到 Vercel**](#-vercel-一键部署傻瓜式教程) ·
[功能特性](#-功能特性) ·
[环境变量](#-环境变量速查表) ·
[本地开发](#-本地开发) ·
[English](#english)

</div>

---

## 📖 简介

**Petrichor**是一个个人/小团队场景下的现代化知识库与博客平台，集成了富文本编辑器、知识库管理、文章发布、AI 写作助手、AI 回顾周报/月报、对象存储上传等能力。

整套系统目标运行环境为 **Vercel + Supabase**，零自建服务器即可上线，仅需配置好环境变量就能拥有一个完整可用的内容平台。

---

## ✨ 功能特性

| 模块 | 能力 |
| --- | --- |
| **📝 富文本编辑器** | 基于 PlateJS，支持 Markdown、代码块、表格、数学公式、白板、思维导图、媒体嵌入等 |
| **📚 知识库** | 多层级目录树、文章标签、文章分享、文章 RSS/Atom Feed |
| **🤖 AI 助手** | AI 续写 / 改写 / 翻译 / 语气调整、AI 文章总结、AI 周报 & 月报回顾 |
| **🔐 认证体系** | Better Auth + httpOnly Cookie，支持邮箱密码、LinuxDo OAuth、二步验证 |
| **🗂️ 对象存储** | S3 兼容上传（封面、附件、头像），支持预签名 URL |
| **📊 仪表盘** | 写作数据统计、活跃度图、知识库分布 |
| **🎨 主题与外观** | 浅色/深色模式、自定义网站标题/图标、Retypeset 主题博客首页 |
| **🌐 公开站点** | 文章公开页、SEO 元数据、RSS、Atom、sitemap.xml |
| **🛠️ Agent 集成** | API Key 管理、Skill 包（兼容 Claude Code / Codex）、调用审计日志、REST 能力层 |

---

## 🚀 Vercel 一键部署（傻瓜式教程）

> 整个过程大约 **5–10 分钟**，无需懂代码，只要会复制粘贴。

### 第 1 步：准备一个 Supabase 数据库（免费）

1. 打开 <https://supabase.com>，注册并登录。
2. 点击 **New Project**，填写项目名（如 `petrichor`），设置一个数据库密码，**密码记下来**。
3. 等待数据库初始化完成（约 1–2 分钟）。
4. 进入 **Project Settings → Database → Connection string**，选择 **Transaction (port 6543)** 模式，复制连接串。它形如：
   ```
   postgresql://postgres.xxxxxxx:你的密码@aws-1-us-west-2.pooler.supabase.com:6543/postgres
   ```
   这串就是后面要填的 **`DATABASE_URL`**。

### 第 2 步：准备一个 S3 兼容的对象存储

任选其一即可，都有免费额度：

| 服务 | 推荐场景 | 链接 |
| --- | --- | --- |
| **缤纷云 Bitiful** | 国内访问快、免费额度大 | <https://www.bitiful.com> |
| **Cloudflare R2** | 海外、零出口费用 | <https://developers.cloudflare.com/r2/> |
| **AWS S3** | 标准方案 | <https://aws.amazon.com/s3/> |
| **MinIO** | 自托管 | <https://min.io> |

创建一个 Bucket（公开读权限），并获取以下信息：

- **S3_ENDPOINT**：S3 API 地址，例如 `https://blog-1.s3.bitiful.net`
- **S3_REGION**：区域，例如 `cn-east-1`、`us-east-1`、`auto`
- **S3_BUCKET**：桶名
- **S3_ACCESS_KEY_ID** / **S3_SECRET_ACCESS_KEY**：访问密钥对

### 第 3 步：生成必要的密钥

随机生成 3 串密钥，本地终端执行（macOS / Linux 通用）：

```bash
# SESSION_SECRET：32 字节 base64
openssl rand -base64 32

# PETRICHOR_ENCRYPT_KEY：32 字节 base64
openssl rand -base64 32

# PETRICHOR_ENCRYPT_SALT：8 字节 hex（16 位十六进制）
openssl rand -hex 8
```

> Windows 用户：可在 <https://www.random.org/bytes/> 上分别生成对应长度的随机串，或用 PowerShell 的 `[Convert]::ToBase64String((1..32 | %{[byte](Get-Random -Min 0 -Max 256)}))`。

把这 3 串结果先保存到记事本，待会儿填到 Vercel。

### 第 4 步：点击下方按钮，一键部署

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FLittleBunVerse%2FDosphere-vercel&project-name=petrichor&repository-name=petrichor&root-directory=apps%2Fweb&env=DATABASE_URL,SESSION_SECRET,PETRICHOR_ENCRYPT_KEY,PETRICHOR_ENCRYPT_SALT,S3_ENDPOINT,S3_REGION,S3_BUCKET,S3_ACCESS_KEY_ID,S3_SECRET_ACCESS_KEY,NEXT_PUBLIC_APP_URL&envDescription=%E5%A1%AB%E5%85%A5%E6%95%B0%E6%8D%AE%E5%BA%93%E3%80%81%E4%BC%9A%E8%AF%9D%E5%AF%86%E9%92%A5%E3%80%81%E5%8A%A0%E5%AF%86%E5%AF%86%E9%92%A5%E5%92%8C%E5%AF%B9%E8%B1%A1%E5%AD%98%E5%82%A8%E7%AD%89%E5%BF%85%E5%A1%AB%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F&envLink=https%3A%2F%2Fgithub.com%2FLittleBunVerse%2FDosphere-vercel%23-%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E9%80%9F%E6%9F%A5%E8%A1%A8)

按钮会自动：

- ✅ 把当前仓库 Fork 到你自己的 GitHub
- ✅ 在 Vercel 创建一个新项目
- ✅ 把 **Root Directory** 自动设为 `apps/web`
- ✅ 弹出表单让你填入所有**必填**环境变量

按照下表把第 1–3 步收集到的值粘贴进去：

| 字段 | 填什么 |
| --- | --- |
| `DATABASE_URL` | 第 1 步 Supabase 的 Transaction Pooler 连接串 |
| `SESSION_SECRET` | 第 3 步生成的 base64（必须 ≥ 32 字符） |
| `PETRICHOR_ENCRYPT_KEY` | 第 3 步生成的 base64 |
| `PETRICHOR_ENCRYPT_SALT` | 第 3 步生成的 16 位 hex |
| `S3_ENDPOINT` | 第 2 步的 S3 接入点 |
| `S3_REGION` | 第 2 步的区域名 |
| `S3_BUCKET` | 第 2 步的桶名 |
| `S3_ACCESS_KEY_ID` | 第 2 步的 Access Key ID |
| `S3_SECRET_ACCESS_KEY` | 第 2 步的 Secret Access Key |
| `NEXT_PUBLIC_APP_URL` | **先随便填 `http://localhost:3000`，部署完成后再来改成你的 Vercel 域名（如 `https://你的项目.vercel.app`）** |

填完点 **Deploy**，等待 2–4 分钟构建完成。

### 第 5 步：初始化数据库表结构（只做一次）

部署完成后，先把数据库表建好，否则页面会报错。

1. 在本地终端把项目克隆下来（用第 4 步 fork 出去的仓库）：
   ```bash
   git clone https://github.com/你的用户名/petrichor.git
   cd petrichor
   pnpm install
   ```
2. 生成初始化 SQL：
   ```bash
   pnpm --silent --filter @petrichor/web db:sql > petricho

... (truncated)