BACK TO ARCHIVE
pipeline framework kitsu zou email smtp gmail self-hosted devops configuration

在自托管的 Kitsu(Zou)服务器上设置电子邮件

06.24.2026 ADUCG RESEARCH

这是一份使用 Gmail 账户的分步指南,专为第一次配置的人编写。

理解这件事的关键只有一个:Zou 不会运行自己的邮件服务器。它本身不会直接发送邮件。它所做的只是登录到一个现有邮箱,并请求该服务器代为发送。因此,下面每一个 MAIL_ 设置其实都只是在回答一个问题:“我要登录哪个邮箱,以及如何登录?” 一旦你这样理解,剩下的事情就只是把对应的值复制到一个文件里。

开始前

请在实际运行你的 Kitsu 的同一台服务器上打开终端,也就是安装了 Zou、并且存在文件 /etc/zou/zou.env 的那台机器。无论你的主机是哪一台,下面的步骤都是一样的。

Phase 1

获取 Gmail App Password

Gmail 不接受像 Zou 这样的应用直接使用你的普通账户密码。你需要一个专用的 16 位 app password,而这个选项只有在开启 2-Step Verification 之后才会出现。

  1. 前往 myaccount.google.com/security,确认 2-Step Verification 已经处于开启状态。如果还没有开启,现在就打开它。
  2. 前往 myaccount.google.com/apppasswords,系统可能会要求你再次登录。
  3. App name 输入框中填写 Kitsu,然后点击 Create
  4. Google 会显示一串 16 位代码,通常分为四组,例如 abcd efgh ijkl mnop。请复制它,并去掉中间空格,使它变成一个连续字符串:abcdefghijklmnop。在进入下一阶段时你会用到它。

如果 App Passwords 页面提示该选项不可用,说明 2-Step Verification 还没有完全开启,请先完成第 1 步。

Phase 2

编辑配置文件

打开你的服务器终端。然后输入下面这条命令并按 Enter,用 nano 打开配置文件:

sudo nano /etc/zou/zou.env

sudo 的意思是“以管理员身份执行”。如果系统要求输入密码,请输入你的服务器密码。输入时屏幕上不会显示字符,这是正常现象,输入完成后直接按 Enter 即可。

你会看到这个文件当前已有的内容,例如 DB_PASSWORDPREVIEW_FOLDER 等。不要删除其中任何内容。使用方向键移动到文件底部的新空行,然后把下面这段内容粘贴进去:

MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=youraddress@gmail.com
MAIL_PASSWORD=your16charappassword
MAIL_USE_TLS=True
MAIL_USE_SSL=False
MAIL_DEFAULT_SENDER=youraddress@gmail.com
MAIL_DEBUG=0
DOMAIN_NAME=your-kitsu-address
DOMAIN_PROTOCOL=https

现在把下面这四个值改成你自己的:

  • MAIL_USERNAME → 你的完整 Gmail 地址。
  • MAIL_PASSWORD → 你在 Phase 1 中获取的 16 位 app password,不要带空格。
  • MAIL_DEFAULT_SENDER → 再次填写同一个 Gmail 地址。Gmail 不允许你使用一个不属于你的地址作为发件地址,所以这里必须保持一致。
  • DOMAIN_NAME → 你在浏览器里访问 Kitsu 时输入的地址,例如 kitsu.yourstudio.com。如果你是通过一个没有挂锁标志的纯 IP 地址访问 Kitsu,就在这里填写这个 IP,并把最后一行改成 DOMAIN_PROTOCOL=http

保存并退出 nano

  • Ctrl+O 保存。
  • 屏幕底部会显示文件名,按 Enter 确认。
  • Ctrl+X 退出并返回终端。

Phase 3

重启并测试

重启 Kitsu,让它读取新的设置:

sudo systemctl restart zou zou-events

仅仅修改文件本身不会产生任何效果,只有重启之后设置才会生效,这是最常被忽略的一步。

测试方法如下:在浏览器中打开 Kitsu,退出登录,在登录界面点击 Forgot password?,然后输入一个真实存在的 Kitsu 用户邮箱,例如你的管理员邮箱。只有当这个地址对应的是实际存在的用户时,重置邮件才会发送,所以不要用一个随便写的地址来测试。然后检查你的收件箱和垃圾邮件文件夹。

如果什么都没有收到,具体原因通常会被记录到日志里。运行下面这条命令,并查看接近底部的位置,查找任何提到 SMTPauthenticationmail 的行:

sudo tail -n 50 /opt/zou/logs/gunicorn_error.log

最常让人出错的五件事

本文采用 Creative Commons BY-NC-ND 4.0 协议进行授权。

BY-NC-ND: 署名-非商业性使用-禁止演绎

End of Article