onesend 表单收件配置完整教程

网站表单收不到邮件？DNS、验证码、SMTP 任一环出错都会卡住。

onesend 配置要先准备服务器和域名，再设置后台项目、Cloudflare Turnstile、网站表单和 SMTP 邮件。

onesend 是做什么的

onesend 用来接收网站表单。

比如网站上有一个“联系我们”表单，访客填写后：

网站把表单内容提交给 onesend。
onesend 检查是不是机器人提交。
onesend 把内容保存到后台。
onesend 给你发一封邮件通知。

整体流程是：

网站表单 -> onesend -> 后台保存 -> 邮件通知

你需要准备什么

你需要准备这些东西：

一台服务器，用来运行 onesend。
一个 API 域名，例如 api.example.com。
一个网站域名，例如 www.example.com。
一个收件邮箱，用来接收表单通知。
一个发件邮箱，用来发送通知邮件。
一个 Cloudflare 账号，用来配置 DNS 和 Turnstile。

这里的域名只是示例，实际配置时换成你自己的。

域名应该怎么分

建议这样分：

网站域名： https://www.example.com
接口域名： https://api.example.com
后台地址： https://api.example.com/admin
提交地址： https://api.example.com/f/project-slug

project-slug 是项目标识。它不要用中文，建议用小写英文、数字和短横线。

例如：

company
brand-a
contact-site

Cloudflare DNS 配置

进入 Cloudflare 后台，找到你的域名，然后进入 DNS 页面。

添加一条记录：

类型：A
名称：api
内容：服务器公网 IP
代理状态：开启或关闭都可以

如果你的接口域名是 api.example.com，那么 名称 就填：

api

如果你使用的是根域名，比如 example.com，那名称一般填：

配置完成后，等待 DNS 生效。

Cloudflare SSL/TLS 配置

进入：

Cloudflare -> SSL/TLS -> Overview

推荐选择：

Full

如果你的服务器上已经有正常 HTTPS 证书，可以选择：

Full (strict)

不建议使用：

Flexible

因为 Flexible 很容易导致浏览器报错：

ERR_TOO_MANY_REDIRECTS

简单理解：

Full / Full (strict)：比较稳
Flexible：容易循环跳转

部署 onesend

把 onesend 程序放到服务器上运行。

常见运行方式有：

直接运行二进制文件
systemd 服务
宝塔 Go 项目
Docker

无论哪种方式，核心都是让 onesend 在服务器上监听一个端口，例如：

然后用 Nginx、宝塔或反向代理，把：

https://api.example.com

转发到：

http://127.0.0.1:3000

onesend 环境变量配置

onesend 一般会用 .env 文件保存配置。

示例：

PORT=3000

ADMIN_TOKEN=your-admin-password

MAIL_TO=receive@example.com
MAIL_FROM=sender@example.com

TURNSTILE_SECRET=your-turnstile-secret-key

REDIRECT_URL=https://www.example.com/thank-you
ALLOWED_ORIGINS=https://www.example.com

每一项是什么意思：

PORT
onesend 运行端口。

ADMIN_TOKEN
后台登录密码。忘记后台密码时，改这个值再重启 onesend。

MAIL_TO
默认收件邮箱。表单通知会发到这个邮箱。

MAIL_FROM
发件邮箱。收件人看到邮件来自这个地址。

TURNSTILE_SECRET
Cloudflare Turnstile 的 Secret Key，用来防机器人。

REDIRECT_URL
用户提交成功后跳转到哪里。

ALLOWED_ORIGINS
允许哪个网站提交表单。

如果你在后台里按项目单独配置了这些字段，后台项目配置会更重要。

打开 onesend 后台

部署完成后，打开：

https://api.example.com/admin

输入 ADMIN_TOKEN 登录。

如果忘记后台密码：

找到服务器上的 .env。
修改：

ADMIN_TOKEN=新的后台密码

重启 onesend。
用新密码登录后台。

创建项目

进入后台后，创建一个项目。

建议一个网站对应一个项目。

项目里最重要的是这些字段：

Slug
项目标识，会出现在提交地址里。

Mail To
收件邮箱。

Mail From
发件邮箱。

SMTP Host / SMTP Port / SMTP User / SMTP Pass
SMTP 发信配置。建议使用。

Turnstile Secret
Cloudflare Turnstile 的 Secret Key。

Redirect URL
提交成功后跳转的页面。

Allowed Origins
允许提交表单的网站域名。

例如项目 Slug 是：

contact

那么提交地址就是：

https://api.example.com/f/contact

如果一个项目有多个表单，可以继续加一段：

https://api.example.com/f/contact/inquiry
https://api.example.com/f/contact/support

大多数网站只用第一种就够了：

https://api.example.com/f/contact

Cloudflare Turnstile 是什么

Turnstile 是 Cloudflare 的人机验证工具。

它类似验证码，但通常不会让用户手动点图片。

它有两个 key：

Site Key
放在网站前端，可以公开。

Secret Key
放在 onesend 后台或 .env，不能公开。

网站负责生成 token。

onesend 负责拿 token 去 Cloudflare 验证。

所以一定要注意：

网站用 Site Key
onesend 用 Secret Key

不要填反。

创建 Turnstile

进入 Cloudflare 后台：

Turnstile -> Add widget

然后填写：

Widget name
随便起一个名字，自己能看懂就行。

Domains
填写你的网站域名。

例如：

example.com
www.example.com

如果你本地测试，也可以加：

localhost

创建完成后，复制：

Site Key
Secret Key

把 Secret Key 填到 onesend 项目的 Turnstile Secret 里。

把 Site Key 放到网站表单代码里。

网站表单怎么写

在网页里先加入 Turnstile 脚本：

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

然后写表单：

<form action="https://api.example.com/f/project-slug" method="POST">
  <input name="name" placeholder="Name" required>
  <input name="email" type="email" placeholder="Email" required>
  <textarea name="message" placeholder="Message"></textarea>

  <div class="cf-turnstile" data-sitekey="your-turnstile-site-key"></div>

  <button type="submit">Submit</button>
</form>

你需要替换两处：

https://api.example.com/f/project-slug

换成你的 onesend 提交地址。

your-turnstile-site-key

换成 Cloudflare Turnstile 的 Site Key。

Turnstile token 不需要显示在邮件里

Turnstile 会生成一个字段：

cf-turnstile-response

有些网站或转发逻辑也可能叫：

turnstile_token
turnstileToken
cfTurnstileResponse

这些字段只是给 onesend 做验证用的。

它们不需要出现在通知邮件里，也不需要显示在后台表单内容里。

简单理解：

验证时要用
展示时不需要

如果用 JavaScript 提交

如果你不是普通 HTML 表单，而是用 JavaScript 提交，也可以。

推荐用 FormData，这样 Turnstile token 会自动一起带上：

const form = document.querySelector("form");
const body = new FormData(form);

fetch("https://api.example.com/f/project-slug", {
  method: "POST",
  body
});

如果你自己组装 JSON，就要手动带上 token：

const token = document.querySelector('[name="cf-turnstile-response"]')?.value;

fetch("https://api.example.com/f/project-slug", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "Name",
    email: "email@example.com",
    message: "Message",
    cfTurnstileResponse: token
  })
});

邮件发送建议

onesend 可以用服务器本机的 sendmail 发邮件。

但更推荐使用 SMTP。

原因是：VPS 本机直接发邮件，经常会遇到这些问题：

日志显示发送成功，但邮箱收不到
邮件进入垃圾箱
邮件被对方服务器隔离
邮件被直接拒收

最稳的方式是使用真实邮箱服务商的 SMTP。

例如项目里配置：

Mail From
发件邮箱地址。

SMTP Host
邮箱服务商提供的 SMTP 地址。

SMTP Port
一般是 465 或 587。

SMTP User
邮箱账号。

SMTP Pass
邮箱授权码。注意，很多时候不是登录密码。

发件邮箱要注意什么

如果你用某个域名邮箱作为发件人，例如：

notice@example.com

最好使用这个邮箱服务商自己的 SMTP 发信。

不建议让 VPS 本机 sendmail 直接冒用这个地址发信。

因为很多域名有邮件安全记录：

SPF
DKIM
DMARC

如果你的 VPS 不在 SPF 允许列表里，收件方可能会认为这封邮件不可信。

结果就是：

onesend 显示邮件发送成功
但是邮箱收不到

所以，遇到这种情况，优先换成 SMTP。

常见问题

后台没有提交记录

检查：

表单 action 是否写对
项目 slug 是否写对
网站是否真的提交到了 onesend
Allowed Origins 是否包含网站域名
Turnstile Site Key 是否正确
Turnstile Secret 是否正确

后台有记录，但没有收到邮件

检查：

项目 Mail To 是否填写
Mail To 是否写错
Mail From 是否正确
SMTP 配置是否完整
垃圾箱是否有邮件
服务器邮件日志是否报错

日志显示邮件已发送，但邮箱收不到

这通常不是 onesend 接收问题，而是邮件投递问题。

检查：

垃圾箱
邮箱隔离区
发件域名 SPF
发件域名 DKIM
发件域名 DMARC
是否使用了 VPS 本机 sendmail
是否应该改用 SMTP

打开 API 地址提示重定向太多

如果浏览器提示：

ERR_TOO_MANY_REDIRECTS

通常是 Cloudflare SSL 配置问题。

把 Cloudflare 的 SSL/TLS 模式改成：

Full

或者：

Full (strict)

不要使用：

Flexible

直接打开提交地址没有表单

这是正常的。

例如：

https://api.example.com/f/project-slug

这个地址是给网站表单 POST 用的，不是给人直接打开看的页面。

后台页面是：

https://api.example.com/admin

最推荐的最终配置

推荐这样配置：

Cloudflare DNS 指向服务器
Cloudflare SSL/TLS 使用 Full 或 Full (strict)
onesend 使用独立 API 域名
网站表单使用 HTTPS 提交
每个网站一个 onesend 项目
每个项目配置自己的 Mail To
Turnstile Site Key 放网站前端
Turnstile Secret 填 onesend 后台
邮件发送使用 SMTP
发件域名配置好 SPF / DKIM / DMARC

这样最稳定：

表单能提交
后台能保存
机器人会被拦截
邮件能送达
不容易出现跳转循环

新项目上线前检查清单

上线前逐项检查：

Cloudflare DNS 是否指向服务器。
Cloudflare SSL/TLS 是否是 Full 或 Full (strict)。
onesend 后台能否打开。
项目 Slug 是否正确。
网站表单 action 是否是 /f/project-slug。
Turnstile Site Key 是否放在网站。
Turnstile Secret 是否填在 onesend 项目。
Allowed Origins 是否包含网站域名。
Mail To 是否是正确收件邮箱。
Mail From 是否是正确发件邮箱。
SMTP 是否配置完整。
提交一次测试，后台是否有记录。
邮箱是否收到通知邮件。

只要这张清单都通过，基本就配置好了。