ciao1019/petrichor

---

---

📖 简介

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

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

---

✨ 功能特性

---

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

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

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

1. 打开 ，注册并登录。
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 兼容的对象存储

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

创建一个 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 通用）：

# 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 用户：可在 上分别生成对应长度的随机串，或用 PowerShell 的 [Convert]::ToBase64String((1..32 | %{[byte](Get-Random -Min 0 -Max 256)}))。

把这 3 串结果先保存到记事本，待会儿填到部署平台。

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

按钮会自动：

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

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

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

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

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

1. 在本地终端把项目克隆下来（用第 4 步 fork 出去的仓库）：

   git clone https://github.com/你的用户名/petrichor.git
   cd petrichor
   pnpm install
   

2. 生成初始化 SQL：

   pnpm --silent --filter @petrichor/web db:sql > petrichor-init.sql
   

3. 打开 Supabase → SQL Editor → New query，把 petrichor-init.sql 全部内容粘贴进去，点 Run 执行。
4. 看到 “Success. No rows returned” 即代表表结构已就绪。

不想本地装环境？直接打开仓库里的 docs/petrichor-init.sql 复制粘贴也行。该文件随仓库提供，与最新表结构同步。

第 6 步：创建第一个超级管理员账号

⚠️ 初始化 SQL 不会自动创建任何用户。数据库刚跑完上一步时是空的，需要自己造一个超级管理员。

二选一，推荐方法 A（不用写 SQL、不用懂 bcrypt）。

方法 A：临时开放注册 → 注册 → 关闭注册（推荐）

🎯 首位管理员会自动产生：当数据库里还没有任何 SUPER_ADMIN 时，第一个注册成功的账号会自动成为超级管理员，无需再手动配置 PETRICHOR_REGISTER_DEFAULT_SYSTEM_ROLE。之后再注册的账号才按默认角色（USER）创建。

1. 在 Vercel → Settings → Environment Variables 新增一个变量（所有环境勾选 Production / Preview / Development）：

   变量	临时填
   NEXT_PUBLIC_REGISTER_ENABLED	true

2. 进入 Deployments → ⋯ → Redeploy 让新环境变量生效（约 2 分钟）。

3. 打开你的 Vercel 域名 https://你的项目.vercel.app/login，点「注册」，填邮箱和密码，提交。系统里此时还没有管理员，这个账号会自动成为超级管理员。

4. 注册成功后立即返回 Vercel → Environment Variables，把变量改回安全值：

   变量	改回
   NEXT_PUBLIC_REGISTER_ENABLED	false

5. 再点一次 Redeploy，登录页的「注册」入口就消失了，从此只有管理员能从后台手动加用户。

方法 B：直接在 Supabase SQL Editor 插入（需要本地 Node）

1. 在本地仓库目录生成 bcrypt 密码哈希（先 pnpm install 安装依赖）：

   cd apps/web
   node -e "console.log(require('bcryptjs').hashSync('替换成你的明文密码', 10))"
   

   会输出形如 $2a$10$... 的哈希串，复制下来。

2. 打开 Supabase → SQL Editor，粘贴下面 SQL，把 3 个占位符替换后 Run：

   do $$
   declare
       v_email         text := '[email protected]';                    -- 改成你的邮箱
       v_password_hash text := '$2a$10$把上一步的哈希粘贴到这里';        -- 改成上面生成的哈希
       v_nickname      text := 'Admin';                                -- 显示名
       v_auth_user_id  text := gen_random_uuid()::text;
       v_username      text := split_part(v_email, '@', 1);
   begin
       insert into better_auth_user (id, name, email, email_verified, created_at, updated_at)
       values (v_auth_user_id, v_nickname, lower(v_email), true, now(), now())
       on conflict (email) do nothing;
   
       insert into petrichor_user (auth_user_id, email, password_hash, system_role, user_type, username, nickname)
       values (v_auth_user_id, lower(v_email), v_password_hash, 'SUPER_ADMIN', 'LOCAL', v_username, v_nickname)
       on conflict (email) do nothing;
   
       insert into better_auth_account (id, account_id, provider_id, user_id, password, created_at, updated_at)
       values (gen_random_uuid()::text, v_auth_user_id, 'credential', v_auth_user_id, v_password_hash, now(), now())
       on conflict (provider_id, account_id) do nothing;
   end $$;
   

3. 用这个邮箱密码登录即可。

第 7 步：回填 NEXT_PUBLIC_APP_URL 并重新部署

1. 在 Vercel 项目首页找到自己分配到的域名，例如 https://petrichor-abc123.vercel.app。
2. 进入 Settings → Environment Variables，把 NEXT_PUBLIC_APP_URL 改成上面这个域名（不要带斜杠结尾）。
3. 进入 Deployments，对最新一次部署点 ⋯ → Redeploy。

完成！ 🎉 用第 6 步创建的管理员账号登录，开始使用。

---

🔐 环境变量速查表

✅ 必填（缺一不可，否则启动失败）

📦 对象存储（上传相关功能依赖；不配则上传按钮会报错）

用到 S3 的功能： 文章封面上传、附件上传、用户头像上传、知识库文件附件、AI 文章总结配图等。

🌐 应用与公开页

🔗 LinuxDo OAuth（可选第三方登录）

不需要 LinuxDo 登录可以全部留空。

在 注册一个 OAuth 应用即可获得 ID 和 Secret，回调地址填 https://你的域名/api/auth/callback。

---

🛠️ Agent 集成（Skill 包 / REST 能力层）

Petrichor 内置了一套面向外部 Agent（Claude Code、Codex、Cursor、ChatGPT 桌面端等）的开放能力，让 AI 工具能直接读写你的知识库。

能力一览

Skill 包结构

下载后的压缩包是一个顶层 petrichor/ Skill，外部 Agent 工具的侧栏只会出现一个 petrichor。根目录 SKILL.md 内置路由表，按用户意图按需读取下列子文档（不会一次性加载）：

scripts/petrichor（零依赖 Python CLI）、scripts/petrichor-api.sh（curl 兜底）和 references/endpoints.md（完整接口字段说明）整个 skill 共用一份，默认读取同目录的 config.json。

接入步骤

1. 生成 API Key：仪表盘 → Agent 集成 → API Key 管理 → 新建，按需勾选权限（article:write / article:delete / doc:read / qa:read），保存明文。
2. 下载 Skill 包：仪表盘 → Agent 集成 → Skill 包 → 下载包，或直接访问 /api/agent/skill-pack，得到 petrichor-agent-skills.zip。
3. 导入 Agent 工具：解压后将 Skill 目录放入 Claude Code / Codex 对应的 Skills 路径（参考各工具文档）。
4. 编辑配置文件：打开解压后的 petrichor/config.json，确认 baseUrl，并把 apiKey 改成上一步生成的明文 Key。
5. 调用约定：Skill 包内 CLI 会从 config.json 读取 apiKey，并自动携带 Authorization: Bearer 。
6. 审计：每次调用都会自动写入「调用日志」，登录用户可在仪表盘内回看。

公开接口清单：未带鉴权也能访问的 GET /api/agent/manifest 会列出全部可用接口、参数和所需权限，方便 Agent 自动发现能力。详细设计见 docs/agent-integration.md。

🧪 完整模板

参考 apps/web/.env.example 或直接复制：

# 必填
DATABASE_URL="postgres://postgres:[password]@[host]:6543/postgres"
SESSION_SECRET=""
PETRICHOR_ENCRYPT_KEY=""
PETRICHOR_ENCRYPT_SALT=""

# S3 兼容对象存储
S3_ENDPOINT="https://s3.example.com"
S3_REGION="us-east-1"
S3_BUCKET="your-bucket"
S3_ACCESS_KEY_ID="your-access-key-id"
S3_SECRET_ACCESS_KEY="your-secret-access-key"
S3_UPLOAD_EXPIRE_SECONDS="900"
S3_DOWNLOAD_EXPIRE_SECONDS="3600"
S3_USE_SSL="true"

# 应用 URL 与注册策略
NEXT_PUBLIC_APP_URL="https://yourdomain.com"
NEXT_PUBLIC_REGISTER_ENABLED="false"
PETRICHOR_REGISTER_DEFAULT_SYSTEM_ROLE="USER"
PETRICHOR_SESSION_EXPIRE_SECONDS="172800"

# 可选：LinuxDo OAuth
PETRICHOR_LINUXDO_CLIENT_ID=""
PETRICHOR_LINUXDO_CLIENT_SECRET=""
PETRICHOR_LINUXDO_REDIRECT_URI=""

---

💻 本地开发

前置依赖

• Node.js ≥ 22
• pnpm 10.x（推荐 corepack enable && corepack prepare [email protected] --activate）
• 一个可用的 Postgres 数据库（Supabase / 本地 Docker / 远程均可）

启动

git clone https://github.com/Ciao1019/Petrichor.git petrichor
cd petrichor
pnpm install
cp apps/web/.env.example apps/web/.env.local
# 编辑 apps/web/.env.local 填入真实值

# 初始化数据库（生成 SQL 后到 Supabase / psql 执行）
pnpm --silent --filter @petrichor/web db:sql > petrichor-init.sql

pnpm dev

打开 。

常用命令

pnpm dev           # 启动开发服务器
pnpm build         # 生产构建
pnpm test          # 单元测试（Vitest）
pnpm typecheck     # TypeScript 类型检查
pnpm lint          # ESLint

---

📁 项目结构

.
├── apps/
│   └── web/                     # Next.js 全栈应用
│       ├── app/                 # App Router 入口、API route、RSS/sitemap
│       │   └── api/agent/       # 外部 Agent REST 能力层（manifest / skill / skill-pack 等）
│       ├── src/
│       │   ├── client-app.tsx   # 客户端 SPA 入口
│       │   ├── features/pages/  # 业务页面（dashboard / blog / kb / ai / agent / admin ...）
│       │   ├── components/      # 通用组件 + shadcn/ui
│       │   ├── lib/             # 前端工具与 API client
│       │   ├── server/          # 服务端 handler / 业务逻辑 / Drizzle schema
│       │   │   └── agent/       # Agent 接入逻辑：API Key、Skill 生成、审计
│       │   └── config/          # 环境变量解析与服务端配置
│       └── .env.example
├── docs/
│   ├── petrichor-init.sql       # 完整初始化 SQL（与代码同步）
│   ├── create-first-admin.sql   # 创建第一个超级管理员账号的 SQL 模板
│   ├── agent-integration.md     # Agent 集成（Skill 包 / REST）设计说明
│   ├── migrations/              # 历史增量迁移脚本
│   └── assets/                  # 文档资源（logo 等）
├── AGENTS.md                    # 给 AI 协作者的项目级说明
├── LICENSE                      # Apache 2.0
└── README.md

---

🤝 贡献

欢迎 Issue / PR。提交前请确保：

pnpm typecheck
pnpm lint
pnpm test

全部通过。

代码风格、提交约定、UI 复用与目录规范详见 AGENTS.md。

---

🙏 致谢

• 本项目的前台公开站点 UI 与排版设计借鉴自 astro-theme-retypeset —— 一个优雅、克制、专注阅读的 Astro 博客主题。感谢作者 @radishzzz 在中文排版与视觉细节上的精心打磨，为本项目的公开页提供了重要灵感。
• 感谢 LinuxDo 社区的支持。

---

📄 License

Apache License 2.0 © 2026 Petrichor Contributors

---

English

Petrichor (repo codename Dosphere) is a self-hostable knowledge-base & blog platform powered by Next.js 16 + Supabase + Vercel, featuring a PlateJS rich-text editor, multi-level knowledge tree, AI writing assistant (continue / rewrite / translate / tone), AI weekly & monthly reviews, S3-compatible uploads, Better Auth with optional LinuxDo OAuth, and an Agent integration layer (REST + downloadable Skill packs compatible with Claude Code / Codex) with full call auditing.

Links

• 🌐 Product site:
• 📖 Live demo (public site):

Quick deploy

1. Provision Postgres — create a free Supabase project, copy the Transaction Pooler connection string (port 6543) as DATABASE_URL.
2. Provision object storage — any S3-compatible service (Bitiful / AWS S3 / MinIO). Collect endpoint, region, bucket, access key, secret.
3. Generate secrets:

   openssl rand -base64 32   # SESSION_SECRET
   openssl rand -base64 32   # PETRICHOR_ENCRYPT_KEY
   openssl rand -hex 8       # PETRICHOR_ENCRYPT_SALT
   

4. Click the deploy button above and fill the env form.
5. Initialize the database: run pnpm --silent --filter @petrichor/web db:sql (or copy docs/petrichor-init.sql) into Supabase SQL Editor.
6. Create the first super-admin — the init SQL does not seed any user. Two options:
   • Recommended (no SQL): temporarily set NEXT_PUBLIC_REGISTER_ENABLED=true on Vercel → redeploy → register from /login. While no super-admin exists yet, the first registered account automatically becomes SUPER_ADMIN — no need to touch PETRICHOR_REGISTER_DEFAULT_SYSTEM_ROLE. Then revert the var and redeploy.
   • Via SQL: generate a bcrypt hash locally (cd apps/web && node -e "console.log(require('bcryptjs').hashSync('YourPwd', 10))") and run docs/create-first-admin.sql in Supabase with your email + hash filled in.
7. Set NEXT_PUBLIC_APP_URL to your deployed Vercel domain and redeploy.

Required env

Optional env

See the full breakdown in the Chinese section above.

Agent integration

Petrichor exposes a permissioned REST layer at /api/agent/** for external AI agents (Claude Code, Codex, Cursor, ChatGPT Desktop, …), together with a downloadable Skill pack containing a single top-level petrichor Skill that routes by user intent into sub-docs for setup, articles, docs, qa, share and AI generation.

1. Generate an API key in Dashboard → Agent 集成 → API Key 管理 (plaintext shown once; only sha256 is persisted).
2. Download the Skill pack (petrichor-agent-skills.zip) from the dashboard or /api/agent/skill-pack, then import it into your agent tool.
3. Edit petrichor/config.json: confirm baseUrl and paste the generated API key into apiKey.
4. Call convention: the packaged CLI reads config.json and sends Authorization: Bearer .
5. Audit: every call (source, tool, IP, UA, request, response, status, latency) is recorded in Dashboard → Agent 集成 → 调用日志.

Public manifest endpoint (no auth) for capability discovery: GET /api/agent/manifest. Full design notes in docs/agent-integration.md.

Acknowledgements

• The public-facing site’s UI and typography were inspired by astro-theme-retypeset by @radishzzz — an elegant, reading-focused Astro blog theme with carefully crafted CJK typography.
• Thank you to the LinuxDo community for your support.

License

Apache License 2.0