本指南介绍如何配置和排查 Discourse 中的 onebox（一键预览）。它涵盖了管理员设置、onebox 的工作原理以及解决常见问题的步骤。
所需用户级别：管理员
Onebox 是用户可以在帖子中创建的富链接预览。虽然用户可以轻松生成这些预览，但站点管理员拥有额外的控制权，并且可能需要在链接未按预期预览时进行排查。
管理员配置
要管理 onebox 设置：
- 进入管理员面板
- 导航到站点设置部分
- 搜索“onebox”
您将看到一个与 onebox 相关的设置列表：
一些值得注意的设置包括：
post onebox maxlength：控制 onebox 中包含的文本量enable inline onebox on all domains：启用内联 onebox，将纯 URL 转换为链接标题（例如，https://en.wikipedia.org/wiki/Fun_(band)变为 “Fun (band) - Wikipedia”）blocked onebox domains：允许您禁用特定域的 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.onebox(url)
=> "
<aside class=\"onebox …(elided)"