Coolify上Docker部署的Supabase GoTrue忽略自定义邮件模板排查

以下是几个容易被忽略的核心原因及对应排查动作：

• 模板文件名严格匹配问题
  GoTrue对模板文件名的拼写、大小写、后缀有强制要求，比如邮箱验证模板必须是email_confirm.html，密码重置模板必须是password_reset.html，不能用email-confirm.html或EmailConfirm.html这类变体。哪怕路径正确，文件名不匹配会直接触发默认模板。

• Coolify卷挂载的同步延迟
  Coolify部署时可能存在卷挂载的缓存延迟，修改本地模板后重新部署，容器内的文件可能未及时更新。直接进入GoTrue容器，执行cat /path/to/your/template.html确认文件内容是否为最新的自定义代码，而非旧文件或空文件。

• 模板缺少必填变量
  如果自定义模板中缺少GoTrue要求的核心变量（比如验证链接的{{ .ConfirmationURL }}、重置链接的{{ .RecoveryURL }}），GoTrue会判定模板无效并回退到默认纯文本模板。哪怕是极简模板，也必须包含对应场景的必填变量，示例：

<!DOCTYPE html>
<html>
<body>
  <a href="{{ .ConfirmationURL }}">点击验证邮箱</a>
</body>
</html>

• 高优先级环境变量覆盖
  检查是否存在其他模板相关环境变量覆盖了路径配置，比如GOTRUE_EMAIL_CONFIRM_TEMPLATE这类直接指定模板内容的变量，若存在会跳过文件模板的读取逻辑，优先使用变量内的内容。

• 目录权限问题
  即使文件本身权限为可读，也要确认模板所在目录对GoTrue运行用户（默认是supabase或nobody）有执行权限——Linux下读取文件需要路径上所有目录的x权限，否则会因目录权限不足无法读取文件。执行ls -ld /path/to/template/dir检查目录权限，确保运行用户拥有x权限。

• Coolify部署模式的卷挂载失效
  如果Coolify开启了无状态部署或自动清理旧容器策略，可能导致自定义卷未正确绑定到新启动的GoTrue容器。检查Coolify的部署设置，确认卷挂载为持久化配置，且容器重启/重新部署时不会被重置。

内容的提问来源于stack exchange，提问作者Yasin