用 Go 自动同步腾讯云 SSL 证书到 Traefik：下载、校验与失败回滚
内容提要
文章介绍用 Go 工具 ssl-sync 将腾讯云 SSL 证书自动同步到 Traefik：查询并下载证书，校验域名、有效期和私钥配对，比较文件摘要避免重复部署，原子替换文件并重启 Traefik，再通过 TLS 连接核对叶证书指纹，失败则回滚；同时说明 Docker 挂载路径、systemd 定时任务及安装配置要点。
延伸解读
证书选择不是“搜到就用”
工具调用 DescribeCertificates 时用 SearchKey 模糊匹配，但命中后还会下载并校验域名、有效期和私钥配对，只取第一张通过检查的证书。列表按到期时间降序排列，优先尝试更晚到期的候选。这意味着搜索结果中的第一条未必被采用，配置 certificate_id 可固定证书，但后续新证书出现时需手动更新。
摘要相同就跳过，但跳过不等于健康
工具比较目标证书和私钥的 SHA-256 摘要，两者都相同就直接返回，不重启也不做 TLS 探测。这能避免重复部署，但也意味着如果磁盘文件已更新而 Traefik 仍加载旧证书，定时任务不会发现。因此它不能替代持续的 HTTPS 监控，入口证书是否生效仍需单独确认。
回滚有边界，不是万能恢复
部署失败时，工具会恢复备份并再次重启，但回滚本身也可能失败，源码会把两层错误一起返回。进程被强制终止或机器断电后，没有持久化事务日志自动恢复半成品。另外，证书和私钥是分别原子替换的，两个文件不在同一文件系统事务中，短暂的新旧不配套仍可能发生。
Docker 挂载要挂目录，不要只挂文件
工具采用临时文件加重命名替换目标文件。如果只把单个证书文件绑定挂载进容器，宿主机重命名后容器可能仍关联旧文件，导致宿主机已更新而 Traefik 读不到。应挂载整个证书目录，并注意容器内路径与宿主机写入路径是两套路径。重启成功不能排除挂载问题，实际 TLS 指纹检查仍有必要。
Q&A
ssl-sync 工具的主要功能是什么？
ssl-sync 是一个用 Go 编写的工具，用于自动将腾讯云 SSL 证书同步到 Traefik。它查询并下载腾讯云已签发的证书，校验域名、有效期和私钥配对，比较文件摘要避免重复部署，原子替换文件并重启 Traefik，最后通过 TLS 连接核对叶证书指纹，失败则回滚。
ssl-sync 如何从腾讯云选择要部署的证书？
工具调用 DescribeCertificates 接口，使用 SearchKey 模糊搜索域名，保留 Status == 1 的候选，按 CertEndTime 降序排列（到期时间相同则比较 CertBeginTime），然后逐张下载、解析，取第一张通过内容校验（域名覆盖、有效期、私钥配对）的证书。也可以配置 certificate_id 直接指定证书。
为什么 ssl-sync 在重启 Traefik 后还要进行 TLS 连接验证？
因为文件更新成功和重启命令执行成功只能证明文件操作和命令执行的结果，不能保证 Traefik 实际提供了新证书。TLS 连接验证通过连接入口获取服务端叶证书，比较其 SHA-256 指纹与预期叶证书是否一致，确保新证书已生效。
ssl-sync 在部署失败时如何回滚？
部署过程分为 Begin、Commit 和 Rollback 阶段。Begin 阶段备份旧文件并写入新文件、执行重启；若后续 TLS 验证失败，main.go 会调用 Rollback，使用独立的 context（默认 5 分钟超时）恢复原文件并再次执行重启命令。回滚本身也可能失败，此时会返回两层错误。
在 Docker 环境中使用 ssl-sync 需要注意什么？
需要将宿主机证书目录挂载到容器内（如 /opt/traefik/certs:/certs:ro），ssl-sync 在宿主机写入文件，Traefik 在容器内读取。应挂载整个目录而非单个文件，因为临时文件加重命名的替换方式可能导致单文件挂载后容器仍读取旧文件。更新后需重启 Traefik 或验证动态配置重载。
如何配置 ssl-sync 的定时任务？
项目提供 systemd service 和 timer 模板。timer 默认每天 03:17 和 15:17 执行（按服务器本地时区），并加入最多 30 分钟的随机延迟，Persistent=true 允许补做错过的任务。启用命令：systemctl enable --now ssl-sync.timer。程序自身使用 flock 锁避免并发执行。
