本指南介绍如何在 Discourse 中配置和排查 onebox（富链接预览）。内容涵盖管理员设置、onebox 的工作原理，以及解决常见问题的步骤。
所需用户等级：管理员
Oneboxes 是用户可在帖子中创建的富链接预览。虽然用户可以轻松生成这些预览，但网站管理员拥有更多控制权限，并可能在链接未按预期显示预览时需要进行故障排查。
管理员配置
要管理 onebox 设置：
- 进入管理面板
- 导航至站点设置部分
- 搜索“onebox”
您将看到与 onebox 相关的设置列表：
一些重要的设置包括：
post onebox maxlength：控制 onebox 中包含的文本量max oneboxes per post：限制单个帖子中可显示的 onebox 数量（默认：50）enable inline onebox on all domains：在所有域名上启用内联 onebox，将纯 URL 转换为带标题的链接（例如，https://en.wikipedia.org/wiki/Fun_(band)变为“Fun (band) - Wikipedia”）。此功能默认启用。blocked onebox domains：允许您禁用特定域名的 oneboxblock onebox on redirect：启用后，阻止对重定向到不同目标的 URL 进行 onebox 处理
Onebox 的工作原理
当帖子中包含链接时，Discourse 会访问目标页面，并查找 Open Graph 或 oEmbed 标签，包括：
- 网站地址
- 标题
- 特色图片
- 网站图标（或 favicon）
- 描述（必需）
- 产品价格（如适用）
Discourse 要求描述标签存在并包含足够的文本以概括页面内容。如果没有该描述，目标链接将不会生成 onebox。
以下是 https://discourse.org 的一个 onebox 示例，显示了网站标题、特色图片、图标和描述：
故障排查
如果 onebox 未按预期工作，请尝试以下步骤：
-
使用 iFramely 测试网站：
- 粘贴链接，检查其是否使用了正确的 OpenGraph 或 oEmbed 元标签
- 确保描述文本存在且内容充分
-
检查 onebox 请求是否被阻止：
- 某些主机可能会阻止“未知”用户代理
- 确认目标网站未阻止 Discourse 的用户代理
-
针对未显示为 onebox 的内部链接：
- 确保链接不在安全类别中
- 出于安全原因，内部链接仅在公开类别或同一类别内生成 onebox
在 Rails 控制台中，您可以在测试时通过调用 相关方法 来显式使 onebox 失效或重新获取：
[1] pry(main)> Oneboxer.invalidate(url)
=> 0
[2] pry(main)> Oneboxer.onebox(url)
=> "<aside class=\"onebox …(elided)"
[3] pry(main)> InlineOneboxer.invalidate(url)
=> 0
[4] pry(main)> InlineOneboxer.lookup(url)
=> {url: "https://example.com", title: "Example Page Title"}