diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..adef045 --- /dev/null +++ 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 \ No newline at end of file diff --git a/.gitignore b/.gitignore index f19465b..ee4c534 100644 --- 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 diff --git a/docs/docs/.vitepress/config.mts b/docs/docs/.vitepress/config.mts new file mode 100644 index 0000000..959fcfe --- /dev/null +++ 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", + } + } +}) diff --git a/docs/docs/.vitepress/theme/index.ts b/docs/docs/.vitepress/theme/index.ts new file mode 100644 index 0000000..def4cfc --- /dev/null +++ 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 diff --git a/docs/docs/.vitepress/theme/style.css b/docs/docs/.vitepress/theme/style.css new file mode 100644 index 0000000..1a61cb1 --- /dev/null +++ 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; +} + diff --git a/docs/docs/AuthoritySystem.md b/docs/docs/AuthoritySystem.md new file mode 100644 index 0000000..729d0b8 --- /dev/null +++ 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 访问密钥 +- **用户管理**：升降用户角色 +- **系统配置**：管理系统全局设置 diff --git a/docs/docs/Donate.md b/docs/docs/Donate.md new file mode 100644 index 0000000..3c558b8 --- /dev/null +++ b/docs/docs/Donate.md @@ -0,0 +1,10 @@ +# 支持 + +如果你喜欢这个项目，欢迎给它一个 Star ⭐️ +或者进行赞助 +
+
+ +
+
+Buy Me A Coffee \ No newline at end of file diff --git a/docs/docs/FAQ.md b/docs/docs/FAQ.md new file mode 100644 index 0000000..7010714 --- /dev/null +++ b/docs/docs/FAQ.md @@ -0,0 +1,12 @@ +# 贡献 + +欢迎提交 Pull Request 或者 Issue来帮助改进这个项目 + +# 交流群 + +
+如二维码失效，请添加我的个人微信（hansenones），并备注 "MoeMail" 加入微信交流群 + +# 许可证 + +本项目采用 [MIT](LICENSE) 许可证 \ No newline at end of file diff --git a/docs/docs/LocalDevelopment.md b/docs/docs/LocalDevelopment.md new file mode 100644 index 0000000..4bd5c3a --- /dev/null +++ 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 +``` \ No newline at end of file diff --git a/docs/docs/api-examples.md b/docs/docs/api-examples.md new file mode 100644 index 0000000..6bd8bb5 --- /dev/null +++ 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 + + +## Results + +### Theme Data +
{{ theme }}
+ +### Page Data +
{{ page }}
+ +### Page Frontmatter +
{{ frontmatter }}
+``` + + + +## Results + +### Theme Data +
{{ theme }}
+ +### Page Data +
{{ page }}
+ +### Page Frontmatter +
{{ frontmatter }}
+ +## More + +Check out the documentation for the [full list of runtime APIs](https://vitepress.dev/reference/runtime-api#usedata). diff --git a/docs/docs/api.md b/docs/docs/api.md new file mode 100644 index 0000000..573bae8 --- /dev/null +++ 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(); +``` \ No newline at end of file diff --git a/docs/docs/index.md b/docs/docs/index.md new file mode 100644 index 0000000..c4258df --- /dev/null +++ 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 +--- + diff --git a/docs/docs/markdown-examples.md b/docs/docs/markdown-examples.md new file mode 100644 index 0000000..f9258a5 --- /dev/null +++ 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). diff --git a/docs/docs/moemail.png b/docs/docs/moemail.png new file mode 100644 index 0000000..4045a5e Binary files /dev/null and b/docs/docs/moemail.png differ diff --git a/docs/docs/public/favicon.ico b/docs/docs/public/favicon.ico new file mode 100644 index 0000000..115e6f5 Binary files /dev/null and b/docs/docs/public/favicon.ico differ diff --git a/docs/docs/start.md b/docs/docs/start.md new file mode 100644 index 0000000..d47e607 --- /dev/null +++ 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` 为 `` +- 设置 `Homepage URL` 为 `https://` +- 设置 `Authorization callback URL` 为 `https:///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" \ No newline at end of file diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 0000000..45e1db2 --- /dev/null +++ b/docs/package.json @@ -0,0 +1,7 @@ +{ + "scripts": { + "docs:dev": "vitepress dev docs", + "docs:build": "vitepress build docs", + "docs:preview": "vitepress preview docs" + } +} \ No newline at end of file diff --git a/package.json b/package.json index a3b37ba..df93b1e 100644 --- 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" } }