检查与故障排查

推荐顺序

1. 记录发生时间、账号、页面路径和操作步骤。
2. 用 docker compose ps 确认容器和健康状态。
3. 查看同一时间段对应服务日志，保留第一条错误。
4. 检查宿主机反向代理、网络、磁盘、数据库、Redis 和 DNS。
5. 修复根因后再重启；不要用持续重启掩盖错误。

页面、Logo 或菜单异常

Logo 不显示时检查静态文件是否进入镜像、响应状态与 Content-Type、文件和父目录读取权限，以及 CDN/浏览器缓存。应用位于 /app/，静态资源必须使用正确基础路径。

版本刚更新时，旧标签页可能引用已经删除的 JS 分块，表现为侧边栏个别菜单点击没反应。先强制刷新；路由内置一次分块加载失败刷新。仍失败时查看浏览器网络面板是否有旧资源 404，并清理代理/CDN 的 HTML 缓存。

www 或 mail 的网页若打开成服务器上另一个站点，检查每个主机名是否有明确虚拟主机和默认回退，不能只依赖第一个 server block。

企业域名没有显示组织品牌时，先在组织域名页确认所有权 TXT 与 MX 均已验证；待验证域名即使已添加并启用，也不会用于品牌匹配。再检查全局企业品牌开关、访问 Host、组织状态、企业套餐状态、组织品牌内容和 Logo 响应。组织被暂停或没有生效/宽限期套餐时，公开页面会恢复平台品牌。

登录或注册失败

• 区分普通登录页与带 redirect=/admin 的管理员入口。
• 检查账号启用状态、密码、TOTP 时间和登录限流。
• 管理员账号不会进入普通用户首次引导；已有邮箱的用户也不应重复进入创建邮箱步骤。
• OAuth 检查提供方开关、客户端配置、回调地址、一次性 state 和 Turnstile 证明。
• 注册检查开放注册、邮件验证、来源 IP 限速和 SMTP 认证邮件。

管理员密码采用哈希保存，无法从数据库读取明文。忘记后走受控重置，并立即设置新密码。

Turnstile 没有出现交互

托管模式可能自动完成无感验证。查看组件是否加载、按钮是否等待令牌、请求是否携带 turnstile_token 和 Cloudflare 是否记录统计。

若页面显示 Site Key，但后台显示 Secret 未配置，补齐 Secret 后保存。启用但配置不完整或 Cloudflare 不可达时，系统按故障关闭返回 503。紧急恢复时在服务器环境中显式设置 TURNSTILE_ENABLED=false（也接受 0、no 或 off）并重启后端；它会临时覆盖数据库启用状态，即使数据库设置暂时无法读取也能救援。空值或拼写错误不会覆盖数据库中已经启用的保护，数据库设置查询失败时仍会故障关闭。修复后移除覆盖值并再次重启。

SMTP 认证邮件发送失败

依次核对：

1. 主机名没有 http://、路径或空格。
2. 465 对应 SSL/TLS，587 对应 STARTTLS。
3. 用户名与 SMTP 专用密码/API Key 正确。
4. 系统发件人是服务商已验证并允许的完整地址。
5. 宿主机能连接目标端口，服务商账号没有欠费、冻结或超额。
6. 发信域名 SPF、DKIM 和 DMARC 按服务商要求配置。

使用“测试成功后保存”可保证失败候选值不覆盖旧配置。系统 SMTP 失败不会回退为本服务器直接发信。完整说明见 注册、SMTP 认证邮件与 Turnstile。

NodeLoc 等级显示不对

• 注册来源只看账号最初由哪个提供方创建。
• 实际会员等级只看该账号在 oauth_account_bindings.external_level_code 保存的 TL0–TL4，不回退 users.level。
• 本站配额等级显示 L0–L4，不能拿来推断 NodeLoc 等级。
• “等级待同步”表示绑定存在但缺少可信等级，可重新授权同一个 NodeLoc 身份。
• 检查后台 TL 到 L 映射和“登录时同步第三方等级”。

普通账号绑定 NodeLoc 后仍显示普通账号，同时增加真实 NodeLoc 等级，这是预期行为。

重复进入首次引导

检查当前会话的用户 ID、邮箱列表接口和引导完成判断。地址提示“已被使用”通常说明邮箱已经创建，但旧前端仍停在引导路由。强制刷新后应按服务器实际邮箱状态进入收件箱。管理员应直接转到后台概览。

邮件客户端无法连接

推荐配置：

IMAP: mail.to9.us:993 SSL/TLS
POP3: mail.to9.us:995 SSL/TLS
SMTP: mail.to9.us:587 STARTTLS
用户名: 完整邮箱地址
密码: 应用专用密码

分别检查端口、TLS 主机名与有效期、账号和邮箱状态、协议访问开关、应用专用密码及限速。网页可用不能证明邮件端口正常。

收不到邮件

检查 MX、25 端口、邮箱接收开关、容量、Catch-All、收信规则、垃圾邮件文件夹、“被拦截邮件”和 rspamd，再查看 SMTP 日志。启用高风险隔离后，达到阈值的来信会保留完整原文供邮箱所有者净化预览、放行或永久删除；升级前的历史记录没有正文，只能删除。发件域 DMARC p=reject 验证失败仍可能直接拒绝。同一上游在短时间重试的重复副本会被指纹识别；若担心误去重，按邮箱、原始哈希和时间窗口核查。

邮箱转发没有到达

先确认原始来信已保存在本地邮箱，再检查外部地址格式、是否与源邮箱相同、域名发信资格、用户每日额度、能量、出站通道和邮件流转失败原因。邮箱设置可转到任意有效外部邮箱；收信规则只允许当前已验证的本人找回邮箱。自动生成或已经转发过的邮件会跳过，邮箱设置与规则的相同目标会合并为一次。转发是本地收信后的独立外发，外发失败不会撤回本地邮件。

业务发信失败

检查域名发信资格、用户申请、每日收件人数额度、能量、黑名单/抑制、出站通道状态、通道小时/每日额度和远端响应。个人邮箱查用户今日额度与能量；企业邮箱查组织套餐状态和全组织今日共享额度，它不会扣受派成员个人额度。系统 SMTP 认证邮件与业务出站通道是两套配置，不要在错误页面反复修改。

临时失败等待重试；永久拒绝根据远端响应修正。客户端超时后先查已发送和邮件流转，避免重复投递。

TLS 证书没有更新

比较磁盘证书与 587、993、995 实际握手证书的序列号、SAN 和到期时间。续期后必须重新加载后端；只重载网页 Nginx 不会更新邮件协议证书。

同时验证根域、www 和邮件 Web 主机的 HTTPS 行为，确保没有证书不匹配或落到其他虚拟主机。

迁移失败

保留第一条迁移错误和前后日志。050、058、062 和 063 会在 OAuth 身份、计费所有者或已验证找回邮箱存在歧义时停止。不要删除迁移记录或强行跳过；先在备份副本定位冲突，明确归属后再重新升级。

订单未到账

按订单号核对支付平台交易、回调签名、金额、币种、订单所有者、状态、钱包流水和订阅。使用幂等补偿，不能因为用户截图就重复手工加款。

提交工单需要的信息

提供发生时间、账号或邮箱、页面路径、操作步骤、订单号或邮件 ID，以及去除敏感信息后的错误文字。不要提交密码、API Key、Cookie、验证码、支付密钥、SMTP 密码或 TLS 私钥。