TaskPilots Mailbox Integration Documentation main concepts/tls-and-root-ca.md

title: Mailbox TLS 与根证书

Mailbox TLS 与根证书

对外集成前，证书信任是必须先完成的前置工作。

固定结论

当前平台有两种 TLS 呈现形态：

  • 正常形态：587 使用公网可信证书，标准客户端通常不需要导入额外根证书
  • 兜底形态：平台临时回退到自签名 fallback，这时才需要下载并信任 https://mailbox.feinian.net/ca.crt

哪些协议可能依赖这张根证书

  • HTTPS
  • MCP
  • SMTP STARTTLS

也就是说，以下接入都受影响：

  • https://mailbox.feinian.net
  • https://mailbox.feinian.net/mcp
  • smtp.agent-mx.taskpilots.net:587

什么时候需要导入 ca.crt

只有在下面任一条件成立时才需要：

  • 平台明确通知当前处于 fallback 自签名模式
  • 你访问 https://mailbox.feinian.net/ca.crt 能拿到证书文件，且运维要求你导入它
  • 你的 STARTTLS 失败原因明确指向自签名或私有 CA

如果当前平台使用公网可信证书，不需要额外导入 ca.crt。

复制即用：各环境信任根证书

以下示例只在“当前活动证书是 fallback 自签名”时使用。

不要通过关闭 TLS 校验来绕过问题。

Windows

管理员 PowerShell 导入到系统信任根证书存储 LocalMachine\Root：

$certPath = Join-Path $env:TEMP "ca.crt"
Invoke-WebRequest -Uri "https://mailbox.feinian.net/ca.crt" -OutFile $certPath
Import-Certificate -FilePath $certPath -CertStoreLocation Cert:\LocalMachine\Root | Out-Null
Write-Host "Mailbox 根证书已导入到 LocalMachine\\Root"

无管理员权限时，可导入当前用户信任根证书存储 CurrentUser\Root：

$certPath = Join-Path $env:TEMP "ca.crt"
Invoke-WebRequest -Uri "https://mailbox.feinian.net/ca.crt" -OutFile $certPath
Import-Certificate -FilePath $certPath -CertStoreLocation Cert:\CurrentUser\Root | Out-Null
Write-Host "Mailbox 根证书已导入到 CurrentUser\\Root"

macOS

需要 sudo 权限，导入到系统 System.keychain：

curl -fsSL "https://mailbox.feinian.net/ca.crt" -o /tmp/mailbox-ca.crt
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /tmp/mailbox-ca.crt
echo "Mailbox 根证书已导入到 System.keychain"

Linux（Ubuntu / Debian）

需要 sudo 权限，导入系统 CA 存储并刷新：

curl -fsSL "https://mailbox.feinian.net/ca.crt" -o /tmp/mailbox-ca.crt
sudo install -m 0644 /tmp/mailbox-ca.crt /usr/local/share/ca-certificates/mailbox-ca.crt
sudo update-ca-certificates
echo "Mailbox 根证书已导入到系统 CA 存储"

其他发行版提示：

  • RHEL / CentOS / Rocky Linux / AlmaLinux 常用 trust anchor /path/to/ca.crt 后再执行 update-ca-trust

Docker（Alpine）

适用于 Alpine 基础镜像的 Dockerfile 片段：

RUN apk add --no-cache ca-certificates curl \
 && curl -fsSL "https://mailbox.feinian.net/ca.crt" -o /usr/local/share/ca-certificates/mailbox-ca.crt \
 && update-ca-certificates

如果你的基础镜像是 Debian 或 Ubuntu，可以复用上面的 Linux 导入方式。

常见 TLS 失败信号

如果当前活动证书来自 fallback，优先排查根证书，而不是先怀疑账号密码：

  • 浏览器访问 https://mailbox.feinian.net 提示证书不受信任
  • MCP 客户端连接 https://mailbox.feinian.net/mcp 失败
  • SMTP 客户端在 STARTTLS 阶段失败
  • 程序日志包含 tls、ssl、x509、certificate

公开集成说明与部署说明的边界

对外公开文档的正式口径是：

  • 优先使用公网可信证书
  • 只有 fallback 自签名模式下，才需要从 https://mailbox.feinian.net/ca.crt 下载根证书

部署补充说明：

  • 应用容器内优先从 /app_data/certs/smtp-submission-587/submission.pfx 读取公网 PFX
  • 如果优先证书不可用，再回退到 /app/certs/submission.pfx

这条部署说明是给联调和运维背景使用的，不表示客户端需要访问 /app/certs/。

更完整的部署与证书挂载真相源见：

常见误区

误区 1：只要 token 正确，就能先连上再说

不行。

  • TLS 失败时，请求甚至不会进入认证阶段

误区 2：浏览器能打开，程序就一定没问题

不一定。

  • 某些环境只给浏览器导入了证书，没有给运行时导入

误区 3：/app/certs/ 是客户端下载位置

不是。

  • 客户端应从 https://mailbox.feinian.net/ca.crt 下载根证书
  • /app/certs/ 是服务端运行时读取证书文件的目录