Files

anghunk 2e177f58f5 feat(邮件通知): 重构邮件通知系统并增加配置选项

- 移除 Cloudflare Email 绑定，改为支持外部邮件网关
- 新增邮件通知全局开关及管理员/用户通知独立配置
- 在管理后台添加邮件通知配置界面
- 优化邮件发送逻辑，增加错误处理和日志记录
- 更新相关文档说明

2026-01-20 11:23:52 +08:00

6.1 KiB

Raw Blame History

后端配置

部署条件

拥有一个 Cloudflare 账号（使用邮箱即可注册，官网地址）
拥有一个 Node.js 运行环境，版本 >= 22（本地部署需要）
拥有一个域名并托管在 Cloudflare 上（这个不是必须项，但可以提高国内访问速度，也更方便）

后端项目目录为 /cwd-comments-api/，基于 Cloudflare Workers + D1 + KV 实现。

部署

以下部署指令均在该目录下执行，不在根目录下

cd cwd-comments-api

本地部署

1. 下载代码，安装依赖

可以直接克隆仓库代码

npm install

2. 配置 Cloudflare Workers

对于 D1 和 KV 配置，有两种方法，第一种是直接使用命令行配置，第二种是使用网页面板创建后填写配置文件，这里推荐使用第一种方法。如果想要使用之前 Cloudflare 上面已经创建的数据库，可以选择自行配置 wrangler.jsonc 文件。

下面介绍第一种方法。

登录到 Cloudflare
```
npx wrangler login
```

创建数据库和数据库表，如果遇到提示，请按回车继续

npx wrangler d1 create CWD_DB
npx wrangler d1 execute CWD_DB --remote --file=./schemas/comment.sql

运行完成后可以确认一下 wrangler.jsonc 中是否有如下配置

"d1_databases": [
  {
    "binding": "CWD_DB",
    "database_name": "CWD_DB",
    "database_id": "xxxxxx" // D1 数据库 ID
  }
]

如果binding字段不是CWD_DB，请修改为CWD_DB

创建 KV 存储，如果遇到提示，按回车继续

npx wrangler kv namespace create CWD_AUTH_KV

运行完成后可以确认一下 wrangler.jsonc 中是否有如下配置

"kv_namespaces": [
  {
    "binding": "CWD_AUTH_KV",
    "id": "xxxxxxx" // KV 存储 ID
  }
]

部署上线
```
npm run deploy
```

没有异常报错后，可以进入 Cloudflare Workers 面板查看是否部署成功，若显示存在一个名称为 cwd-comments-api 的项目即推送成功。

3. 配置环境变量

登录 Worker 面板，点击项目右侧的 Settings (设置) 选项卡，选择查看设置
点击变量和机密右侧的添加按钮，给项目添加环境变量，环境变量参考
部署生效：点击底部的 Save and deploy (保存并部署)。

4. 检测部署情况

部署成功后回得到一个域名，即为后端的域名（格式一般为https://cwd-comments-api.xxx.workers.dev。访问该域名，如果显示部署成功页面，说明 API 部署成功，可以到管理后台进行登录。

当然也可以使用自定义域名。

服务启动与运行参数

本地开发

在本地开发阶段，可以通过 wrangler dev 启动本地 Worker：

npm run dev
# 等价于
wrangler dev

常用参数：

--port <number>：指定本地开发端口，例如：
```
wrangler dev --port 8788
```
如果你使用评论组件开发页面（widget/）进行联调，可以将前端中的 apiBaseUrl 配置为：
```
http://localhost:8788
```
--env <name>：指定 wrangler 环境（如有配置多环境）。

注意：线上环境的运行参数完全由 Cloudflare Workers 控制，一般无需额外手动配置，只需在控制台或 wrangler.jsonc 中正确配置绑定和变量。

数据库与 KV 连接配置

后端使用 Cloudflare D1 作为数据库，使用 KV 作为会话存储。

D1 数据库

创建数据库和表结构：

npx wrangler d1 create CWD_DB
npx wrangler d1 execute CWD_DB --remote --file=./schemas/comment.sql

在 wrangler.jsonc 中确保存在如下配置：
```
"d1_databases": [
  {
    "binding": "CWD_DB",
    "database_name": "CWD_DB",
    "database_id": "xxxxxx"
  }
]
```
其中：
- binding 必须为 CWD_DB，与代码中的 env.CWD_DB 一致。
- database_name 和 database_id 根据 Cloudflare 实际创建结果填写。

数据库结构定义见 schemas/comment.sql。

KV 存储

创建 KV 命名空间：

npx wrangler kv namespace create CWD_AUTH_KV

在 wrangler.jsonc 中添加：
```
"kv_namespaces": [
  {
    "binding": "CWD_AUTH_KV",
    "id": "xxxxxxx"
  }
]
```
其中：
- binding 必须为 CWD_AUTH_KV，与代码中的 env.CWD_AUTH_KV 一致。

KV 主要用于：

管理员登录 Token 存储与校验
登录失败次数和封禁状态记录

环境变量与绑定

后端通过 Cloudflare Worker 的绑定和环境变量控制行为，类型定义见 cwd-comments-api/src/bindings.ts。

所需环境变量如下表所示。

名称	类型	描述
`CWD_DB`	D1 绑定	评论数据存储数据库
`CWD_AUTH_KV`	KV 绑定	管理员登录 Token、登录尝试计数等
`ALLOW_ORIGIN`	string	预留的允许跨域来源配置，目前实现中仍使用 `*`
`MAIL_GATEWAY_URL`	string	外部邮件网关 HTTP 地址，由此网关转发到 QQ SMTP 或其他邮箱服务（可选）
`MAIL_GATEWAY_TOKEN`	string	调用外部邮件网关使用的鉴权 Token（可选）
`ADMIN_NAME`	string	管理员登录名称
`ADMIN_PASSWORD`	string	管理员登录密码

在 Cloudflare 控制台中配置方式：

打开 Worker 项目 -> Settings -> Variables
在 Environment Variables 中添加 ADMIN_NAME、ADMIN_PASSWORD 等变量
在 D1 Databases 中绑定 CWD_DB
在 KV Namespaces 中绑定 CWD_AUTH_KV

6.1 KiB Raw Blame History Unescape Escape