feat: add docs (#122)

2026-08-07 22:43:39 +08:00 · 2024-04-14 15:15:09 +08:00
parent fb74504282
commit 209693673d
43 changed files with 3073 additions and 16 deletions
--- a/vitepress-docs/docs/zh/guide/cli/d1.md
+++ b/vitepress-docs/docs/zh/guide/cli/d1.md
@@ -0,0 +1,27 @@
+# 初始化/更新 D1 数据库
+
+第一次执行登录 wrangler 命令时，会提示登录, 按提示操作即可
+
+## 初始化数据库
+
+```bash
+# 创建 D1 并执行 schema.sql
+wrangler d1 create dev
+wrangler d1 execute dev --file=db/schema.sql
+```
+
+创建完成后，我们在 cloudflare 的控制台可以看到 D1 数据库
+
+![D1](/readme_assets/d1.png)
+
+## 更新数据库 schema
+
+`schema` 更新，请确认你之前部署的版本,
+查看 [更新日志](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/CHANGELOG.md)
+
+找到需要执行的 `patch` 文件, 执行, 例如:
+
+```bash
+wrangler d1 execute dev --file=db/2024-01-13-patch.sql
+wrangler d1 execute dev --file=db/2024-04-03-patch.sql
+```
--- a/vitepress-docs/docs/zh/guide/cli/pages.md
+++ b/vitepress-docs/docs/zh/guide/cli/pages.md
@@ -0,0 +1,25 @@
+# Cloudflare Pages 前端
+
+第一次部署会提示创建项目, `production` 分支请填写 `production`
+
+```bash
+cd frontend
+pnpm install
+cp .env.example .env.prod
+```
+
+修改 `.env.prod` 文件
+
+将 `VITE_API_BASE` 修改为上一步创建的 `worker` 的 `url`, 不要在末尾加 `/`
+
+例如: `VITE_API_BASE=https://xxx.xxx.workers.dev`
+
+```bash
+pnpm build --emptyOutDir
+# 根据提示创建 pages
+pnpm run deploy
+```
+
+部署完成之后你可以在 Cloudflare 控制台看到你的项目, 可以为 `pages` 配置自定义域名
+
+![pages](/readme_assets/pages.png)
--- a/vitepress-docs/docs/zh/guide/cli/pre-requisite.md
+++ b/vitepress-docs/docs/zh/guide/cli/pre-requisite.md
@@ -0,0 +1,17 @@
+# 先决条件
+
+## wrangler 的安装
+
+安装 wrangler
+
+```bash
+npm install wrangler -g
+```
+
+## 克隆项目
+
+```bash
+git clone https://github.com/dreamhunter2333/cloudflare_temp_email.git
+# 切换到最新 tag 或者你想部署的分支，你也可以直接使用 main 分支
+# git checkout $(git describe --tags $(git rev-list --tags --max-count=1))
+```
--- a/vitepress-docs/docs/zh/guide/cli/worker.md
+++ b/vitepress-docs/docs/zh/guide/cli/worker.md
@@ -0,0 +1,50 @@
+# Cloudflare workers 后端
+
+## 初始化项目
+
+```bash
+cd worker
+pnpm install
+cp wrangler.toml.template wrangler.toml
+```
+
+## 修改 `wrangler.toml` 配置文件
+
+```bash
+name = "cloudflare_temp_email"
+main = "src/worker.js"
+compatibility_date = "2023-12-01"
+# 如果你想使用自定义域名，你需要添加 routes 配置
+# routes = [
+#  { pattern = "temp-email-api.xxxxx.xyz", custom_domain = true },
+# ]
+node_compat = true
+
+[vars]
+PREFIX = "tmp" # 要处理的邮箱名称前缀，不需要后缀可配置为空字符串
+# 如果你想要你的网站私有，取消下面的注释，并修改密码
+# PASSWORDS = ["123", "456"]
+# admin 控制台密码, 不配置则不允许访问控制台
+# ADMIN_PASSWORDS = ["123", "456"]
+DOMAINS = ["xxx.xxx1" , "xxx.xxx2"] # 你的域名, 支持多个域名
+JWT_SECRET = "xxx" # 用于生成 jwt 的密钥
+BLACK_LIST = "" # 黑名单，用于过滤发件人，逗号分隔
+
+# D1 数据库的名称和 ID 可以在 cloudflare 控制台查看
+[[d1_databases]]
+binding = "DB"
+database_name = "xxx" # D1 数据库名称
+database_id = "xxx" # D1 数据库 ID
+```
+
+## 部署
+
+第一次部署会提示创建项目, `production` 分支请填写 `production`
+
+```bash
+pnpm run deploy
+```
+
+部署成功之后再路由中可以看到 `worker` 的 `url`，控制台也会输出 `worker` 的 `url`
+
+![worker](/readme_assets/worker.png)
--- a/vitepress-docs/docs/zh/guide/config-send-mail.md
+++ b/vitepress-docs/docs/zh/guide/config-send-mail.md
@@ -0,0 +1,12 @@
+
+# 配置发送邮件
+
+1. 找到域名 `DNS` 记录的 `TXT` 的 `SPF` 记录, 增加 `include:relay.mailchannels.net`
+
+    `v=spf1 include:_spf.mx.cloudflare.net include:relay.mailchannels.net ~all`
+
+2. 新建 `_mailchannels` 记录, 类型为 `TXT`, 内容为 `v=mc1 cfid=你的worker域名`
+
+- 此处 worker 域名为后端 api 的域名，比如我部署在 `https://temp-email-api.awsl.uk/`，则填写 `v=mc1 cfid=awsl.uk`
+
+- 如果你的域名是 `https://temp-email-api.xxx.workers.dev`，则填写 `v=mc1 cfid=xxx.workers.dev`
--- a/vitepress-docs/docs/zh/guide/email-routing.md
+++ b/vitepress-docs/docs/zh/guide/email-routing.md
@@ -0,0 +1,9 @@
+# Cloudflare Email Routing
+
+1. 配置对应域名的 `电子邮件 DNS 记录`, 如果是多个域名，需要配置多个域名的 `电子邮件 DNS 记录`
+
+2. 在将电子邮件地址绑定到您的 Worker 之前，您需要启用电子邮件路由并拥有至少一个经过验证的电子邮件地址。
+
+3. 配置每个域名的 `Cloudflare Email Routing` catch-all 发送到 `worker`
+
+![email](/readme_assets/email.png)
--- a/vitepress-docs/docs/zh/guide/quick-start.md
+++ b/vitepress-docs/docs/zh/guide/quick-start.md
@@ -0,0 +1,8 @@
+# 快速开始
+
+- 良好的网络环境
+- cloudflare 账号
+
+打开 [cloudflare控制台](https://dash.cloudflare.com/)
+
+请查看通过 [命令行部署](/zh/guide/cli/pre-requisite) 或者 [用户界面部署](/zh/guide/ui/d1)
--- a/vitepress-docs/docs/zh/guide/star-history.md
+++ b/vitepress-docs/docs/zh/guide/star-history.md
@@ -0,0 +1,7 @@
+# Star History
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=dreamhunter2333/cloudflare_temp_email&type=Date&theme=dark" />
+  <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=dreamhunter2333/cloudflare_temp_email&type=Date" />
+  <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=dreamhunter2333/cloudflare_temp_email&type=Date" />
+</picture>
--- a/vitepress-docs/docs/zh/guide/ui/d1.md
+++ b/vitepress-docs/docs/zh/guide/ui/d1.md
@@ -0,0 +1,25 @@
+# 初始化/更新 D1 数据库
+
+## 初始化数据库
+
+打开 cloudflare 控制台，选择 `Workers & Pages` -> `D1` -> `Create Database`，点击创建数据库
+
+![d1](/ui_install/d1.png)
+
+创建完成后，我们在 cloudflare 的控制台可以看到 D1 数据库
+
+打开 `Console` 标签页，输入 `db/schema.sql` 的内容，点击 `Execute` 执行
+
+![d1](/ui_install/d1-exec.png)
+
+## 更新数据库 schema
+
+`schema` 更新，请确认你之前部署的版本,
+
+查看 [更新日志](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/CHANGELOG.md)
+
+找到需要执行的 `patch` 文件, 执行, 例如:  `db/2024-01-13-patch.sql`
+
+打开 `Console` 标签页，输入 `patch` 文件的内容，点击 `Execute` 执行
+
+![d1](/ui_install/d1-exec.png)
--- a/vitepress-docs/docs/zh/guide/ui/pages.md
+++ b/vitepress-docs/docs/zh/guide/ui/pages.md
@@ -0,0 +1,95 @@
+# Cloudflare Pages 前端
+
+<script setup>
+import { ref } from 'vue'
+import JSZip from 'jszip';
+
+const domain = ref("")
+const downloadUrl = ref("")
+const tip = ref("下载")
+
+const generate = async () => {
+    try {
+        const response = await fetch("/ui_install/frontend.zip");
+        const arrayBuffer = await response.arrayBuffer();
+        var zip = new JSZip();
+        await zip.loadAsync(arrayBuffer);
+        let target_content = ""
+        let target_path = ""
+        const directory = zip.folder("assets");
+        if (directory) {
+            for (const [relativePath, zipEntry] of Object.entries(directory.files)) {
+                console.log(relativePath);
+                if (relativePath.startsWith("assets/index-") && relativePath.endsWith(".js")){
+                    let content = await zipEntry.async("string");
+                    content = content.replace("https://temp-email-api.xxx.xxx", domain.value);
+                    target_path = relativePath;
+                    zip.file(relativePath, content);
+                    break;
+                }
+            }
+        }
+        if (!target_path) {
+            tip.value = "生成失败";
+            downloadUrl.value = '';
+        }
+        const blob = await zip.generateAsync({ type: "blob" });
+        const url = window.URL.createObjectURL(blob);
+        downloadUrl.value = url;
+    } catch (error) {
+        console.error("Error: ", error);
+    }
+}
+</script>
+
+1. 点击 `Workers & Pages` -> `Overview` -> `Create Application`
+
+    ![create pages](/ui_install/worker_home.png)
+
+2. 选择 `Pages`，选择 `Create using direct upload`
+
+    ![pages](/ui_install/pages.png)
+
+3. 输入部署的 worker 的地址, 地址不要带 `/`，点击生成，成功会出现下载按钮，你会得到一个 zip 包
+    - 此处 worker 域名为后端 api 的域名，比如我部署在 `https://temp-email-api.awsl.uk`，则填写 `https://temp-email-api.awsl.uk`
+    - 如果你的域名是 `https://temp-email-api.xxx.workers.dev`，则填写 `https://temp-email-api.xxx.workers.dev`
+
+    <div :class="$style.container">
+        <input :class="$style.input" type="text" v-model="domain" placeholder="请输入地址"></input>
+        <button :class="$style.button" @click="generate">生成</button>
+        <a v-if="downloadUrl" :href="downloadUrl" download="frontend.zip">{{ tip }}</a>
+    </div>
+
+4. 选择 `Pages`，点击 `Create Pages`, 修改名称，上传下载的 zip 包，然后点击 `Deploy`
+
+    ![pages1](/ui_install/pages-1.png)
+
+5. 打开 刚刚部署的 `Pages`，点击 `Custom Domain`  这里可以添加自己的域名，你也可以使用自动生成的 `*.pages.dev` 的域名。能打开域名说明部署成功。
+
+    ![pages domain](/ui_install/pages-domain.png)
+
+<style module>
+.container {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    height: 100%;
+}
+.input {
+    border: 2px solid deepskyblue;
+    margin-right: 10px;
+    width: 75%;
+    border-radius: 5px;
+}
+
+.button {
+    background-color: deepskyblue;
+    padding: 5px 10px;
+    border-radius: 5px;
+    margin-right: 10px;
+}
+
+.button:hover {
+    background-color: green;
+}
+</style>
--- a/vitepress-docs/docs/zh/guide/ui/worker.md
+++ b/vitepress-docs/docs/zh/guide/ui/worker.md
@@ -0,0 +1,27 @@
+# Cloudflare workers 后端
+
+1. 点击 `Workers & Pages` -> `Overview` -> `Create Application`
+
+    ![create worker](/ui_install/worker_home.png)
+
+2. 选择 `Worker`，点击 `Create Worker`, 修改名称然后点击 `Deploy`
+
+    ![worker1](/ui_install/worker-1.png)
+
+3. 下载 [worker.js](https://github.com/dreamhunter2333/cloudflare_temp_email/releases/latest/download/worker.js)
+
+4. 回到 `Overview`，找到刚刚创建的 worker，点击 `Edit Code`, 上传 `worker.js`, 删除 `index.js`，然后重命名 `worker.js` 为 `index.js`, 点击 `Deploy`
+
+    ![worker2](/ui_install/worker-2.png)
+
+5. 点击 `Settings` -> `Trggers`, 这里可以添加自己的域名，你也可以使用自动生成的 `*.workers.dev` 的域名。能打开域名说明部署成功，记录下这个域名，后面部署前端会用到。
+
+    ![worker3](/ui_install/worker-3.png)
+
+6. 点击 `Settings` -> `Variables`, 如图所示添加变量，参考 README.md 中的 `wrangler.toml` 文件的 `vars` 部分
+
+    ![worker-var](/ui_install/worker-var.png)
+
+7. 点击 `Settings` -> `Variables`, 下拉找到 `D1 Database`, 点击 `Add Binding`, 名称如图，选择刚刚创建的 D1 数据库，点击 `Deploy`
+
+    ![worker-d1](/ui_install/worker-d1.png)
--- a/vitepress-docs/docs/zh/guide/what-is-temp-mail.md
+++ b/vitepress-docs/docs/zh/guide/what-is-temp-mail.md
@@ -0,0 +1,7 @@
+# 临时邮箱简介
+
+## 什么是临时邮箱
+
+临时邮箱，也被称为一次性邮箱或临时邮件地址，是一种用于临时接收邮件的虚拟邮箱。与常规邮箱不同，临时邮箱旨在提供一种匿名且临时的邮件接收解决方案。
+
+临时邮箱往往由网站或在线服务提供商提供，用户可以在需要注册或接收验证邮件时使用临时邮箱地址，而无需暴露自己的真实邮箱地址。这样做的好处是可以保护个人隐私