初始化文档

2025-12-24 11:30:51 +08:00 · 2025-02-23 10:17:57 +08:00
parent 59671091b6
commit 3bd555f363
18 changed files with 899 additions and 0 deletions
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,66 @@
+# 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程
+#
+name: Deploy VitePress site to Pages
+
+on:
+  # 在针对 `main` 分支的推送上运行。如果你
+  # 使用 `master` 分支作为默认分支，请将其更改为 `master`
+  push:
+    branches: [docs]
+
+  # 允许你从 Actions 选项卡手动运行此工作流程
+  workflow_dispatch:
+
+# 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列
+# 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # 构建工作
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
+      # - uses: pnpm/action-setup@v3 # 如果使用 pnpm，请取消此区域注释
+      #   with:
+      #     version: 9
+      # - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm # 或 pnpm / yarn
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Install dependencies
+        run: npm ci # 或 pnpm install / yarn install / bun install
+      - name: Build with VitePress
+        run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  # 部署工作
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,9 @@
 # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.

+# docs
+docs/docs/.vitepress/cache
+docs/docs/.vitepress/dist
+
 # dependencies
 /node_modules
 /.pnp
--- a/docs/docs/.vitepress/config.mts
+++ b/docs/docs/.vitepress/config.mts
@@ -0,0 +1,73 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "MoeMail",
+  description: "一个基于 NextJS + Cloudflare 技术栈构建的可爱临时邮箱服务🎉",
+  head: [
+    ['link', { rel: 'icon', href: '/favicon.ico' }]
+  ],
+  ignoreDeadLinks: true,
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: '首页', link: '/' },
+      { text: '快速开始', link: '/start' },
+      { text: '开发', link: '/LocalDevelopment' },
+      { text: 'API', link: '/api' },
+      { text: '其他', link: '/FAQ' }
+    ],
+    outlineTitle: "本页目录",
+    logo: "/moemail.png",
+    search: {
+      provider: 'local'
+    },
+    sidebar: [
+      {
+        text: '使用',
+        items: [
+          { 
+            text: '快速开始',
+            link: '/start',
+            items: [
+              { text: '准备', link: '/start#准备' },
+              { text: 'Github Actions', link: '/start#github-actions-部署' },
+              { text: '环境变量', link: '/start#环境变量' },
+              { text: '邮件路由配置', link: '/start#cloudflare-邮件路由配置' }
+            ] 
+          },
+          { text: '权限系统', link: '/AuthoritySystem' }
+        ]
+      },
+      {
+        text: '开发',
+        items: [
+          { text: '本地开发', link: '/LocalDevelopment' },
+          { 
+            text: 'API', 
+            link: '/api',
+            items: [
+              { text: 'WebHook', link: '/api#webhook-集成' },
+              { text: 'OpenAPI', link: '/api#openapi' }
+            ] 
+          }
+        ]
+      },
+      {
+        text: '其他',
+        items: [
+          { text: 'FAQ', link: '/FAQ' },
+          { text: '捐赠', link: '/Donate' }
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/beilunyang/moemail' }
+    ],
+    footer: {
+      message: "Released under the MIT License",
+      copyright: "Copyright © 2024-2025 MoeMail",
+    }
+  }
+})
--- a/docs/docs/.vitepress/theme/index.ts
+++ b/docs/docs/.vitepress/theme/index.ts
@@ -0,0 +1,17 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import './style.css'
+
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // https://vitepress.dev/guide/extending-default-theme#layout-slots
+    })
+  },
+  enhanceApp({ app, router, siteData }) {
+    // ...
+  }
+} satisfies Theme
--- a/docs/docs/.vitepress/theme/style.css
+++ b/docs/docs/.vitepress/theme/style.css
@@ -0,0 +1,139 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Colors
+ *
+ * Each colors have exact same color scale system with 3 levels of solid
+ * colors with different brightness, and 1 soft color.
+ *
+ * - `XXX-1`: The most solid color used mainly for colored text. It must
+ *   satisfy the contrast ratio against when used on top of `XXX-soft`.
+ *
+ * - `XXX-2`: The color used mainly for hover state of the button.
+ *
+ * - `XXX-3`: The color for solid background, such as bg color of the button.
+ *   It must satisfy the contrast ratio with pure white (#ffffff) text on
+ *   top of it.
+ *
+ * - `XXX-soft`: The color used for subtle background such as custom container
+ *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
+ *   on top of it.
+ *
+ *   The soft color must be semi transparent alpha channel. This is crucial
+ *   because it allows adding multiple "soft" colors on top of each other
+ *   to create a accent, such as when having inline code block inside
+ *   custom containers.
+ *
+ * - `default`: The color used purely for subtle indication without any
+ *   special meanings attached to it such as bg color for menu hover state.
+ *
+ * - `brand`: Used for primary brand colors, such as link text, button with
+ *   brand theme, etc.
+ *
+ * - `tip`: Used to indicate useful information. The default theme uses the
+ *   brand color for this by default.
+ *
+ * - `warning`: Used to indicate warning to the users. Used in custom
+ *   container, badges, etc.
+ *
+ * - `danger`: Used to show error, or dangerous message to the users. Used
+ *   in custom container, badges, etc.
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-c-default-1: var(--vp-c-gray-1);
+  --vp-c-default-2: var(--vp-c-gray-2);
+  --vp-c-default-3: var(--vp-c-gray-3);
+  --vp-c-default-soft: var(--vp-c-gray-soft);
+
+  --vp-c-brand-1: var(--vp-c-indigo-1);
+  --vp-c-brand-2: var(--vp-c-indigo-2);
+  --vp-c-brand-3: var(--vp-c-indigo-3);
+  --vp-c-brand-soft: var(--vp-c-indigo-soft);
+
+  --vp-c-tip-1: var(--vp-c-brand-1);
+  --vp-c-tip-2: var(--vp-c-brand-2);
+  --vp-c-tip-3: var(--vp-c-brand-3);
+  --vp-c-tip-soft: var(--vp-c-brand-soft);
+
+  --vp-c-warning-1: var(--vp-c-yellow-1);
+  --vp-c-warning-2: var(--vp-c-yellow-2);
+  --vp-c-warning-3: var(--vp-c-yellow-3);
+  --vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+  --vp-c-danger-1: var(--vp-c-red-1);
+  --vp-c-danger-2: var(--vp-c-red-2);
+  --vp-c-danger-3: var(--vp-c-red-3);
+  --vp-c-danger-soft: var(--vp-c-red-soft);
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-text: var(--vp-c-white);
+  --vp-button-brand-bg: var(--vp-c-brand-3);
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-hover-text: var(--vp-c-white);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+  --vp-button-brand-active-border: transparent;
+  --vp-button-brand-active-text: var(--vp-c-white);
+  --vp-button-brand-active-bg: var(--vp-c-brand-1);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    #bd34fe 30%,
+    #41d1ff
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    #bd34fe 50%,
+    #47caff 50%
+  );
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-custom-block-tip-border: transparent;
+  --vp-custom-block-tip-text: var(--vp-c-text-1);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
+  --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
+}
+
+/**
+ * Component: Algolia
+ * -------------------------------------------------------------------------- */
+
+.DocSearch {
+  --docsearch-primary-color: var(--vp-c-brand-1) !important;
+}
+
--- a/docs/docs/AuthoritySystem.md
+++ b/docs/docs/AuthoritySystem.md
@@ -0,0 +1,54 @@
+::: tip
+本项目采用基于角色的权限控制系统（RBAC），用户分为皇帝、公爵、骑士和平民四种角色，每个角色具有不同的权限。
+:::
+
+## 角色配置
+
+新用户默认角色由皇帝在个人中心的网站设置中配置：
+- 公爵：新用户将获得临时邮箱、Webhook 配置权限以及 API Key 管理权限
+- 骑士：新用户将获得临时邮箱和 Webhook 配置权限
+- 平民：新用户无任何权限，需要等待皇帝册封为骑士或公爵
+
+## 角色等级
+
+系统包含四个角色等级：
+
+1. **皇帝（Emperor）**
+   - 网站所有者
+   - 拥有所有权限
+   - 每个站点只能有一个皇帝
+
+2. **公爵（Duke）**  
+   - 超级用户
+   - 可以使用临时邮箱功能
+   - 可以配置 Webhook
+   - 可以使用创建 API Key 调用 OpenAPI
+   - 可以被皇帝贬为骑士或平民
+
+3. **骑士（Knight）**
+   - 高级用户
+   - 可以使用临时邮箱功能
+   - 可以配置 Webhook
+   - 可以被皇帝贬为平民或册封为公爵
+
+3. **平民（Civilian）**
+   - 普通用户
+   - 无任何权限
+   - 可以被皇帝册封为骑士或者公爵
+
+## 角色升级
+
+1. **成为皇帝**
+   - 第一个访问 `/api/roles/init-emperor` 接口的用户将成为皇帝，即网站所有者
+   - 站点已有皇帝后，无法再提升其他用户为皇帝
+
+2. **角色变更**
+   - 皇帝可以在个人中心页面将其他用户设为公爵、骑士或平民
+
+## 权限说明
+
+- **邮箱管理**：创建和管理临时邮箱
+- **Webhook 管理**：配置邮件通知的 Webhook
+- **API Key 管理**：创建和管理 API 访问密钥
+- **用户管理**：升降用户角色
+- **系统配置**：管理系统全局设置
--- a/docs/docs/Donate.md
+++ b/docs/docs/Donate.md
@@ -0,0 +1,10 @@
+# 支持
+
+如果你喜欢这个项目，欢迎给它一个 Star ⭐️
+或者进行赞助
+<br />
+<br />
+<img src="https://pic.otaku.ren/20240212/AQADPrgxGwoIWFZ-.jpg" style="width: 400px;"/>
+<br />
+<br />
+<a href="https://www.buymeacoffee.com/beilunyang" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-blue.png" alt="Buy Me A Coffee" style="width: 400px;" ></a>
--- a/docs/docs/FAQ.md
+++ b/docs/docs/FAQ.md
@@ -0,0 +1,12 @@
+# 贡献
+
+欢迎提交 Pull Request 或者 Issue来帮助改进这个项目
+
+# 交流群
+<img src="https://pic.otaku.ren/20250221/AQAD8b8xG9vVwFV-.jpg" style="width: 400px;"/>
+<br />
+如二维码失效，请添加我的个人微信（hansenones），并备注 "MoeMail" 加入微信交流群
+
+# 许可证
+
+本项目采用 [MIT](LICENSE) 许可证
--- a/docs/docs/LocalDevelopment.md
+++ b/docs/docs/LocalDevelopment.md
@@ -0,0 +1,62 @@
+### 前置要求
+
+- Node.js 18+
+- Pnpm
+- Wrangler CLI
+- Cloudflare 账号
+
+### 安装
+
+1. 克隆仓库：
+```bash
+git clone https://github.com/beilunyang/moemail.git
+cd moemail
+```
+
+2. 安装依赖：
+```bash
+pnpm install
+```
+
+3. 设置 wrangler：
+```bash
+cp wrangler.example.toml wrangler.toml
+cp wrangler.email.example.toml wrangler.email.toml
+cp wrangler.cleanup.example.toml wrangler.cleanup.toml
+```
+设置 Cloudflare D1 数据库名以及数据库 ID
+
+4. 设置环境变量：
+```bash
+cp .env.example .env.local
+```
+设置 AUTH_GITHUB_ID, AUTH_GITHUB_SECRET, AUTH_SECRET
+
+5. 创建本地数据库表结构
+```bash
+pnpm db:migrate-local
+```
+
+### 开发
+
+1. 启动开发服务器：
+```bash
+pnpm dev
+```
+
+2. 测试邮件 worker：
+目前无法本地运行并测试，请使用 wrangler 部署邮件 worker 并测试
+```bash
+pnpm deploy:email
+```
+
+3. 测试清理 worker：
+```bash
+pnpm dev:cleanup
+pnpm test:cleanup
+```
+
+4. 生成 Mock 数据（邮箱以及邮件消息）
+```bash
+pnpm generate-test-data
+```
--- a/docs/docs/api-examples.md
+++ b/docs/docs/api-examples.md
@@ -0,0 +1,49 @@
+---
+outline: deep
+---
+
+# Runtime API Examples
+
+This page demonstrates usage of some of the runtime APIs provided by VitePress.
+
+The main `useData()` API can be used to access site, theme, and page data for the current page. It works in both `.md` and `.vue` files:
+
+```md
+<script setup>
+import { useData } from 'vitepress'
+
+const { theme, page, frontmatter } = useData()
+</script>
+
+## Results
+
+### Theme Data
+<pre>{{ theme }}</pre>
+
+### Page Data
+<pre>{{ page }}</pre>
+
+### Page Frontmatter
+<pre>{{ frontmatter }}</pre>
+```
+
+<script setup>
+import { useData } from 'vitepress'
+
+const { site, theme, page, frontmatter } = useData()
+</script>
+
+## Results
+
+### Theme Data
+<pre>{{ theme }}</pre>
+
+### Page Data
+<pre>{{ page }}</pre>
+
+### Page Frontmatter
+<pre>{{ frontmatter }}</pre>
+
+## More
+
+Check out the documentation for the [full list of runtime APIs](https://vitepress.dev/reference/runtime-api#usedata).
--- a/docs/docs/api.md
+++ b/docs/docs/api.md
@@ -0,0 +1,129 @@
+## Webhook 集成
+
+当收到新邮件时，系统会向用户配置并且已启用的 Webhook URL 发送 POST 请求。
+
+### 请求头
+
+```http
+Content-Type: application/json
+X-Webhook-Event: new_message
+```
+
+### 请求体
+
+```json
+{
+  "emailId": "email-uuid",
+  "messageId": "message-uuid",
+  "fromAddress": "sender@example.com",
+  "subject": "邮件主题",
+  "content": "邮件文本内容",
+  "html": "邮件HTML内容",
+  "receivedAt": "2024-01-01T12:00:00.000Z",
+  "toAddress": "your-email@moemail.app"
+}
+```
+
+### 配置说明
+
+1. 点击个人头像，进入个人中心
+2. 在个人中心启用 Webhook
+3. 设置接收通知的 URL
+4. 点击测试按钮验证配置
+5. 保存配置后即可接收新邮件通知
+
+### 测试
+
+项目提供了一个简单的测试服务器, 可以通过如下命令运行:
+
+```bash
+pnpm webhook-test-server
+```
+
+测试服务器会在本地启动一个 HTTP 服务器，监听 3001 端口（http://localhost:3001）, 并打印收到的 Webhook 消息详情。
+
+如果需要进行外网测试，可以通过 Cloudflare Tunnel 将服务暴露到外网：
+```bash
+pnpx cloudflared tunnel --url http://localhost:3001
+```
+
+### 注意事项
+- Webhook 接口应在 10 秒内响应
+- 非 2xx 响应码会触发重试
+
+## OpenAPI
+
+本项目提供了 OpenAPI 接口，支持通过 API Key 进行访问。API Key 可以在个人中心页面创建（需要是公爵或皇帝角色）。
+
+### 使用 API Key
+
+在请求头中添加 API Key：
+```http
+X-API-Key: YOUR_API_KEY
+```
+
+### API 接口
+
+#### 创建临时邮箱
+```http
+POST /api/emails/generate
+Content-Type: application/json
+
+{
+  "name": "test",
+  "expiryTime": 3600000,
+  "domain": "moemail.app"
+}
+```
+参数说明：
+- `name`: 邮箱前缀，可选
+- `expiryTime`: 有效期（毫秒），可选值：3600000（1小时）、86400000（1天）、604800000（7天）、0（永久）
+- `domain`: 邮箱域名，可通过 `/api/emails/domains` 获取可用域名列表
+
+#### 获取邮箱列表
+```http
+GET /api/emails?cursor=xxx
+```
+参数说明：
+- `cursor`: 分页游标，可选
+
+#### 获取指定邮箱邮件列表
+```http
+GET /api/emails/{emailId}?cursor=xxx
+```
+参数说明：
+- `cursor`: 分页游标，可选
+
+#### 删除邮箱
+```http
+DELETE /api/emails/{emailId}
+```
+
+#### 获取单封邮件内容
+```http
+GET /api/emails/{emailId}/{messageId}
+```
+
+### 使用示例
+
+使用 curl 创建临时邮箱：
+```bash
+curl -X POST https://your-domain.com/api/emails/generate \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "test",
+    "expiryTime": 3600000,
+    "domain": "moemail.app"
+  }'
+```
+
+使用 JavaScript 获取邮件列表：
+```javascript
+const res = await fetch('https://your-domain.com/api/emails/your-email-id', {
+  headers: {
+    'X-API-Key': 'YOUR_API_KEY'
+  }
+});
+const data = await res.json();
+```
--- a/docs/docs/index.md
+++ b/docs/docs/index.md
@@ -0,0 +1,46 @@
+---
+layout: home
+
+hero:
+  name: "MoeMail"
+  text: "萌萌哒临时邮箱服务"
+  tagline: 一个基于NextJS+Cloudflare技术栈构建的可爱临时邮箱服务🎉
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /start
+    - theme: alt
+      text: GitHub
+      link: https://github.com/beilunyang/moemail
+    - theme: alt
+      text: 在线演示
+      link: https://moemail.app
+  image:
+    src: /moemail.png
+    alt: MoeMail
+
+features:
+  - title: 🔒 隐私保护
+    details: 保护您的真实邮箱地址，远离垃圾邮件和不必要的订阅
+  - title: ⚡ 实时收件
+    details: 自动轮询，即时接收邮件通知
+  - title: 🎨 主题切换
+    details: 支持亮色和暗色模式
+  - title: 📱 响应式设计
+    details: 完美适配桌面和移动设备
+  - title: 🔄 自动清理
+    details: 自动清理过期的邮箱和邮件
+  - title: 📱 PWA 支持
+    details: 支持 PWA 安装
+  - title: 💸 免费自部署
+    details: 基于 Cloudflare 构建, 可实现免费自部署，无需任何费用
+  - title: 🎉 可爱的 UI
+    details: 简洁可爱萌萌哒 UI 界面
+  - title: 🔔 Webhook 通知
+    details: 支持通过 webhook 接收新邮件通知
+  - title: 🛡️ 权限系统
+    details: 支持基于角色的权限控制系统
+  - title: 🔑 OpenAPI
+    details: 支持通过 API Key 访问 OpenAPI
+---
+
--- a/docs/docs/markdown-examples.md
+++ b/docs/docs/markdown-examples.md
@@ -0,0 +1,85 @@
+# Markdown Extension Examples
+
+This page demonstrates some of the built-in markdown extensions provided by VitePress.
+
+## Syntax Highlighting
+
+VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:
+
+**Input**
+
+````md
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+````
+
+**Output**
+
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+
+## Custom Containers
+
+**Input**
+
+```md
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+```
+
+**Output**
+
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+
+## More
+
+Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).
--- a/docs/docs/moemail.png
+++ b/docs/docs/moemail.png
--- a/docs/docs/public/favicon.ico
+++ b/docs/docs/public/favicon.ico
--- a/docs/docs/start.md
+++ b/docs/docs/start.md
@@ -0,0 +1,145 @@
+### 视频版部署教程
+https://www.bilibili.com/video/BV19wrXY2ESM/
+
+## 准备
+
+在开始部署之前，需要在 Cloudflare 控制台完成以下准备工作：
+
+1. **创建 D1 数据库**
+   - 登录 [Cloudflare 控制台](https://dash.cloudflare.com/)
+   - 选择 “存储与数据库” -> “D1 SQL 数据库”
+   - 创建一个数据库（例如：moemail）
+   - 记录下数据库名称和数据库 ID，后续配置需要用到
+
+2. **创建 KV 命名空间**
+   - 登录 [Cloudflare 控制台](https://dash.cloudflare.com/)
+   - 选择 “存储与数据库” -> “KV”
+   - 创建一个 KV 命名空间（例如：moemail）
+   - 记录下命名空间 ID，后续配置需要用到
+
+3. **创建 Pages 项目**
+   - 登录 [Cloudflare 控制台](https://dash.cloudflare.com/)
+   - 选择 “Workers 和 Pages”
+   - 点击 “创建” 并选择 “Pages” 标签
+   - 选择 “使用直接上传创建”
+   - 点击 “上传资产”
+   - 输入项目名称
+      ::: warning
+      注意：项目名称必须为 moemail，否则无法正常部署
+      :::
+   - 输入项目名称后，点击 “创建项目” 即可，不需要上传任何文件以及点击“部署站点”，之后我们会通过 本地运行Wrangler 或者通过 Github Actions 自动部署
+4. **为 Pages 项目添加 AUTH 认证相关的 SECRETS**
+   - 在 Overview 中选择刚刚创建的 Pages 项目
+   - 在 Settings 中选择变量和机密
+   - 添加 AUTH_GITHUB_ID, AUTH_GITHUB_SECRET, AUTH_SECRET
+
+## Github Actions 部署
+
+本项目可使用 GitHub Actions 实现自动化部署。支持以下触发方式：
+
+1. **自动触发**：推送新的 tag 时自动触发部署流程
+2. **手动触发**：在 GitHub Actions 页面手动触发，可选择以下部署选项：
+   - Run database migrations：执行数据库迁移
+   - Deploy email Worker：重新部署邮件 Worker
+   - Deploy cleanup Worker：重新部署清理 Worker
+
+#### 部署步骤
+
+1. 在 GitHub 仓库设置中添加以下 Secrets：
+
+| 环境变量 | 说明 |
+|----------|------|
+| `CLOUDFLARE_API_TOKEN` | Cloudflare API 令牌 |
+| `CLOUDFLARE_ACCOUNT_ID` | Cloudflare 账户 ID |
+| `DATABASE_NAME` | D1 数据库名称 |
+| `DATABASE_ID` | D1 数据库 ID |
+| `KV_NAMESPACE_ID` | Cloudflare KV namespace ID，用于存储网站配置 |
+
+2. 选择触发方式：
+
+   **方式一：推送 tag 触发**
+   ```bash
+   # 创建新的 tag
+   git tag v1.0.0
+   ```
+
+   ```bash
+   # 推送 tag 到远程仓库
+   git push origin v1.0.0
+   ```
+
+   **方式二：手动触发**
+   - 进入仓库的 Actions 页面
+   - 选择 "Deploy" workflow
+   - 点击 "Run workflow"
+   - 选择需要执行的部署选项
+   - 点击 "Run workflow" 开始部署
+
+3. GitHub Actions 会自动执行以下任务：
+   - 构建并部署主应用到 Cloudflare Pages
+   - 根据选项或文件变更执行数据库迁移
+   - 根据选项或文件变更部署 Email Worker
+   - 根据选项或文件变更部署 Cleanup Worker
+
+4. 部署进度可以在仓库的 Actions 标签页查看
+
+::: warning
+- 使用 tag 触发时，tag 必须以 `v` 开头（例如：v1.0.0）
+- 使用 tag 触发时，只有文件发生变更的部分会被部署
+- 手动触发时，可以选择性地执行特定的部署任务
+- 每次部署都会重新部署主应用
+:::
+
+## 环境变量
+
+本项目使用以下环境变量：
+
+### 认证相关
+
+| 环境变量 | 说明 |
+|----------|------|
+| `AUTH_GITHUB_ID` | GitHub OAuth App ID |
+| `AUTH_GITHUB_SECRET` | GitHub OAuth App Secret |
+| `AUTH_SECRET` | NextAuth Secret，用来加密 session，请设置一个随机字符串 |
+
+### Cloudflare 配置
+
+| 环境变量 | 说明 |
+|----------|------|
+| `CLOUDFLARE_API_TOKEN` | Cloudflare API Token |
+| `CLOUDFLARE_ACCOUNT_ID` | Cloudflare Account ID |
+| `DATABASE_NAME` | D1 数据库名称 |
+| `DATABASE_ID` | D1 数据库 ID |
+| `KV_NAMESPACE_ID` | Cloudflare KV namespace ID，用于存储网站配置 |
+
+
+## Github OAuth App 配置
+
+- 登录 [Github Developer](https://github.com/settings/developers) 创建一个新的 OAuth App
+- 生成一个新的 `Client ID` 和 `Client Secret`
+- 设置 `Application name` 为 `<your-app-name>`
+- 设置 `Homepage URL` 为 `https://<your-domain>`
+- 设置 `Authorization callback URL` 为 `https://<your-domain>/api/auth/callback/github`
+
+[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/beilunyang/moemail)
+
+## Cloudflare 邮件路由配置
+
+为了使邮箱域名生效，还需要在 Cloudflare 控制台配置邮件路由，将收到的邮件转发给 Email Worker 处理。
+
+1. 登录 [Cloudflare 控制台](https://dash.cloudflare.com/)
+2. 选择您的域名
+3. 点击左侧菜单的 "电子邮件" -> "电子邮件路由"
+4. 如果显示 “电子邮件路由当前被禁用，没有在路由电子邮件”，请点击 "启用电子邮件路由"
+![启用电子邮件路由](https://pic.otaku.ren/20241223/AQADNcQxG_K0SVd-.jpg "启用电子邮件路由")
+5. 点击后，会提示你添加电子邮件路由 DNS 记录，点击 “添加记录并启用” 即可
+![添加电子邮件路由 DNS 记录](https://pic.otaku.ren/20241223/AQADN8QxG_K0SVd-.jpg "添加电子邮件路由 DNS 记录")
+6. 配置路由规则：
+
+   ![配置路由规则](https://pic.otaku.ren/20241223/AQADNsQxG_K0SVd-.jpg "配置路由规则")
+   - Catch-all 地址: 启用 "Catch-all"
+   ::: warning
+   如果Catch-All 状态不可用，请在点击`路由规则`旁边的`目标地址`进去绑定一个邮箱
+   :::
+   - 编辑 Catch-all 地址,选择 "发送到 Worker"
+   - 目标位置: 选择刚刚部署的 "email-receiver-worker"
--- a/docs/package.json
+++ b/docs/package.json
@@ -0,0 +1,7 @@
+{
+  "scripts": {
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  }
+}
--- a/package.json
+++ b/package.json
@@ -66,6 +66,7 @@
    "tailwindcss": "^3.4.1",
    "typescript": "^5",
    "vercel": "39.1.1",
+    "vitepress": "^1.6.3",
    "wrangler": "^3.91.0"
  }
 }