PeerTube实例间联邦订阅失败问题的排查与解决

问题背景

在部署PeerTube视频平台时，管理员遇到了两个同域名的PeerTube实例（6.2.1版本）无法建立联邦订阅的问题。当尝试互相订阅时，系统显示"跟踪请求已发送"但实际未建立连接，日志中出现"找不到Actor URL"的Webfinger相关错误。

技术分析

联邦订阅机制

PeerTube使用ActivityPub协议实现实例间的联邦功能。订阅过程涉及以下关键技术点：

1. Webfinger协议：用于发现用户/实例信息
2. Nodeinfo端点：提供实例的元数据
3. ActivityStreams：JSON-LD格式的数据交换

典型错误表现

• 订阅操作无实际效果
• 日志报错："Do not follow [e-mail]:443 because we could not find the actor URL"
• 通过curl测试发现SSL证书验证问题

排查步骤

1. 基础配置验证

   • 确认两个实例的webserver配置正确
   • 检查HTTPS是否正常工作
   • 验证实例域名解析

2. 端点测试

   • 测试ActivityPub端点：/accounts/peertube
   • 检查Nodeinfo端点：/.well-known/nodeinfo
   • 验证Webfinger端点：/.well-known/webfinger

3. 证书诊断

   • 发现curl测试时出现SSL验证错误
   • 确认虽然使用了通配符证书(*.domain.com)，但中间证书缺失

解决方案

证书修复

1. 将中间证书与主证书合并
2. 确保证书链完整
3. 重启web服务使配置生效

配置建议

• 使用完整的证书链（包括中间证书）
• 确保证书包含所有需要的SAN(Subject Alternative Name)
• 定期检查证书有效期

经验总结

PeerTube的联邦功能对HTTPS配置有严格要求，特别是：

1. 证书链必须完整
2. 所有端点必须可通过HTTPS正常访问
3. Webfinger和Nodeinfo端点应返回正确的JSON响应

管理员在部署时应当特别注意SSL/TLS配置，这是许多联邦功能问题的常见根源。通过系统的端点测试和日志分析，可以快速定位并解决这类问题。