本页由英文页面机器翻译而来。内容以英文页面为准。 阅读英文页面
链接预览(OGP / X Card / fediverse:creator)
本页说明其他服务为本服务器的页面显示的预览、服务器为此返回的内容,以及手动检查的步骤。本服务器为自己帖子中的链接显示的卡片,见下文的帖子中链接的卡片;如何停止从某个域名获取卡片,见实例设置。
服务器返回的内容
Section titled “服务器返回的内容”my serve 会把 meta 标签嵌入 Web 客户端的外壳,返回以下页面的 HTML:首页(https://<host>/)、实例信息页面(https://<host>/about)、已发布文档的页面(/about/terms、/about/privacy、/about/commerce)、链接卡片爬虫的说明页面(/about/crawler)、个人资料(https://<host>/@alice)和帖子(https://<host>/@alice/status/<post ID>)。对 HTML 的请求一律视为未登录,因此预览只显示未登录访客能看到的内容。
| 页面 | 响应 |
|---|---|
首页(/)和实例信息页面(/about) |
200。带有介绍实例的 meta 标签的外壳(见下文“首页”) |
链接卡片爬虫的说明页面(/about/crawler) |
200。带有介绍实例的 meta 标签的外壳,标题为“链接卡片爬虫 | 实例名称” |
已发布文档的页面(/about/terms、/about/privacy、/about/commerce) |
200。带有介绍实例的 meta 标签的外壳,标题为“文档名称 | 实例名称”。未发布的文档的页面得到通用外壳 |
public 帖子、活跃的本站账号的个人资料 |
200。带有 meta 标签的外壳 |
unlisted 帖子 |
200。带有 meta 标签的外壳,另加 <meta name="robots" content="noindex, noarchive"> 和 X-Robots-Tag: noindex, noarchive |
local、private、direct、已删除或不存在的帖子,以及被暂停、已停用、已删除或受限账号的个人资料和帖子 |
404。通用外壳和 X-Robots-Tag: noindex, noarchive。无论原因如何,正文和响应头都相同 |
/@<old username>/status/<post ID> |
301,重定向到带有当前用户名的 URL |
话题标签的页面(/tags/<tag>) |
200。通用外壳,带有指向该话题标签 Atom 订阅源的链接(见下文“通用外壳”) |
| Web 客户端的其他所有页面(探索、公开的费用和支持者页面、登录等) | 200。通用外壳,带有实例的 meta 标签(见下文“通用外壳”) |
每个页面还会带有面向搜索引擎和 AI 爬虫的声明(noindex 和 noai 等 meta 标签,以及 X-Robots-Tag、Content-Usage 和 tdm-reservation),依据实例设置和所有者的设置(搜索引擎和 AI 爬虫)。上表中的 noindex 无论设置如何都会添加。noindex 不会阻止链接预览。
带有 ActivityPub Accept 的请求不会得到外壳,而是由 ActivityPub 一侧响应(个人资料以 actor 的 id 响应,未登录访客能看到的帖子以 302 重定向到它的 id)。每个响应都带有 Vary: Accept。
meta 标签
Section titled “meta 标签”| 标签 | 内容 |
|---|---|
og:title、<title> |
“显示名称(@username@account domain)”。显示名称为空时使用用户名。对于文章,则是它的标题 |
og:type |
个人资料为 profile,帖子和文章为 article |
og:url、<link rel="canonical"> |
规范 URL(带有当前用户名的 URL) |
og:description |
帖子正文的纯文本(个人资料则是简介),不含标签,截取到 200 个字素。带有内容警告的帖子,只取内容警告的文字。对于文章,则是它的摘要,即使它被标为敏感内容也是如此;文章的正文绝不会出现在页面中 |
og:image、og:image:alt / width / height |
按下面的顺序选定的图片 |
og:site_name |
实例名称(文本 name,在所有语言中都相同;没有时为 host;名称和域名) |
og:locale、<html lang dir> |
帖子的语言。未设置(und)时,使用作者默认的发帖语言,再没有则使用实例的 default_locale。它不会随 Accept-Language 而变化。og:locale 的形式为 language_TERRITORY:不带地区的语言会得到它通常的地区(ja → ja_JP,en → en_US,pt → pt_BR),而 <html lang> 保持语言标签原样 |
article:published_time、article:author |
仅限帖子。帖子的时间(UTC)和作者的个人资料 URL |
profile:username |
仅限个人资料。username@account domain |
twitter:card |
当图片宽于大约 2:1(宽 / 高 >= 1.7)且至少为 300x157 时为 summary_large_image,否则为 summary |
fediverse:creator |
@username@account domain。Mastodon 将它显示为“作者” |
<link rel="alternate" type="application/activity+json"> |
AP 的 id(actor 或帖子的对象) |
<link rel="alternate" type="application/atom+xml"> |
仅限有 Atom 订阅源的个人资料:订阅源的地址(https://<host>/@<username>.atom),标题与 og:title 相同。所有者关闭了订阅源的个人资料,以及受限或已迁移的账号,都没有它 |
首页的 meta 标签介绍的是实例本身。
og:type为website,og:title、<title>和og:site_name是实例名称,og:url和<link rel="canonical">是https://<host>/。og:description是实例文本short_description,截取到 200 个字素。没有时则省略。- 语言(
og:locale、<html lang dir>)是实例的default_locale。名称和描述在所有语言中都是同一个值。 og:image是实例图片:下面的第 3 项,如果没有,则是第 4、5 或 6 项。- 它不属于任何账号,因此不输出
fediverse:creator和 ActivityPub 的alternate。 - 实例信息页面(
/about)有相同的 meta 标签。og:title和<title>是“关于 {实例名称}”(server:preview.about_title),og:url和<link rel="canonical">是https://<host>/about。 - 已发布文档的页面(
/about/terms、/about/privacy、/about/commerce)也有相同的 meta 标签。og:title和<title>是“{文档名称} | {实例名称}”(server:preview.document_title),og:url和<link rel="canonical">是该页面的地址。未发布的文档的页面得到通用外壳。 - 链接卡片爬虫的说明页面(
/about/crawler)有相同的 meta 标签,标题和地址的形式也相同。
通用外壳由其他所有页面以及被隐藏帖子的 404 返回,它带有与首页相同的标签,只是没有自己的地址:og:type 为 website,实例名称作为 og:site_name 和 og:title,short_description 作为 og:description,以及 og:locale、实例图片和 twitter:card。它没有 og:url 和 <link rel="canonical">,因此同一份副本可以用于每个路径,被隐藏帖子的 404 也与其他任何页面保持一致。话题标签的页面只会额外添加指向该话题标签订阅源(https://<host>/tags/<tag>.atom)的 <link rel="alternate" type="application/atom+xml">,标题为“实例名称上的 #tag”(server:feed.tag_title),无论是否已有帖子使用过该话题标签。分享的话题标签链接或公开费用页面的链接,显示的是实例的卡片。
这些订阅源本身是 Atom 1.0 文档,包含最新的 20 条不是回复也不是转发的本站公开帖子,并带有 ETag、Last-Modified 和 Cache-Control: public, max-age=60。文章的条目是它的标题和摘要,以及指向文章的链接;它的正文留在文章自己的页面上。每个有订阅源的个人资料还有一个仅含文章的订阅源 https://<host>/@<username>/articles.atom,标题为“name(@handle)的文章”(server:feed.articles_title),遵循相同的规则;个人资料页面只链接它的主订阅源。服务器会把渲染好的每个订阅源在它的键值存储中保存一分钟,因此变更大约在一分钟内就会反映到订阅源中。订阅源带有与其个人资料相同的 X-Robots-Tag 和 AI 声明;话题标签的订阅源始终是 noindex,并声明它的任一作者的 AI 拒绝。没有订阅源的个人资料,以及没有帖子使用过的话题标签,都会返回 404。
og:image 按以下顺序选定。
- 帖子附带的第一张图片,或文章的封面(它的替代文字会写入
og:image:alt)。对于被标为敏感内容的帖子或文章,或带有内容警告的帖子,则不使用它。 - 个人资料的封面图片,否则是头像(
og:image:alt为“{name} 的封面图片”或“{name} 的头像”)。 - 实例预览图片(实例设置
preview_image,位于管理界面设置 → 常规中的“链接预览”下;og:image:alt是文本preview_image_alt,没有时为“{实例名称} 的图片”)。 - 实例缩略图(实例设置
thumbnail,即设置 → 常规页面的图片;og:image:alt是文本thumbnail_alt,没有时为“{实例名称} 的图片”)。 - 实例自己的标志的链接预览版本(标志和图标),即位于
https://<host>/brand/<revision>/preview-1200x630.png的 1200x630 PNG(og:image:alt为“{实例名称} 的图片”)。 - 内置的默认图片(
https://<host>/preview-image.png,白底的 mycroblog 字标的 1200x630 PNG,不含实例名称;og:image:alt为“mycroblog 的标志”)。
第 3 到第 6 项都是实例图片。因此显示预览的页面始终有 og:image 和 og:image:alt。第 1 到第 4 项的图片是处理后媒体的 large 变体,宽度和高度取自处理时的数值。如果 preview_image 未设置、仍在处理、处理失败或不是图片,则使用缩略图,再是标志,再是内置图片。实例设置在每个请求时读取,因此 my instance set preview_image ... 无需重启即可生效(操作步骤见实例设置)。
内置图片是二进制文件的一部分(约 20 KB)。它以 Cache-Control: no-cache 和 ETag 提供。
- 响应带有
Cache-Control: public, max-age=60, stale-while-revalidate=300。删除、可见范围的变更,或者发布或取消发布文档,在共享缓存中最多保留这么长时间。 - ETag 由以下内容的版本构成:模板、资源和实例设置,语言,帖子的版本(修订),实际可见范围,个人资料的版本,以及选定的图片(对于首页、信息页面、文档页面和爬虫说明页面:页面的地址、标题、实例描述和选定的图片;对于通用外壳:实例名称、描述和实例图片)。
If-None-Match会得到304。 - 如果你在前面放了 CDN,请把
Accept加入缓存键(这样 AP JSON 和 HTML 不会混淆)。
升级之后或更改预览设置之后,请在真实设备上检查每个服务。你需要一个可以从外部通过 HTTPS 访问的实例(预览机器人无法访问 localhost)。
-
用一个测试账号准备以下帖子。
- 一条带有横向图片(例如 1200x630)和替代文本的
public帖子 - 一条不带图片的
public帖子(来自设置了封面图片的账号) - 一条正文超过 200 个字符并包含表情符号(例如 👨👩👧👦)的
public帖子 - 一条
unlisted帖子 - 一条
private帖子 - 一条来自昵称包含
"><script>alert(1)</script>的账号的帖子
- 一条带有横向图片(例如 1200x630)和替代文本的
-
检查每个 URL 的 HTML。
终端窗口 curl -sS -D - -H 'Accept: text/html' https://<host>/@alice/status/<post ID>-
状态为 200,且有上表中的 meta 标签。
unlisted帖子带有noindex。 -
private帖子和不存在的 ID 返回相同的 404 正文,并带有X-Robots-Tag: noindex, noarchive(设置拒绝 AI 时还带有noai, noimageai)。终端窗口 diff <(curl -sS https://<host>/@alice/status/<private post ID>) <(curl -sS https://<host>/@alice/status/0192f3a4-7b1c-7d2e-9f00-1a2b3c4d5e6f) -
昵称中的
<script>被转义为<script>。
-
- 把带图片的帖子的 URL 粘贴到发帖界面(或私信)中。
- 检查大图卡片(
summary_large_image)显示了标题、域名和图片。 - 对于不带图片的帖子的 URL,检查卡片显示了封面图片。对于既没有封面图片也没有头像的账号,检查大卡片显示了默认图片(
preview_image,未设置时为内置图片)。 - 对于只有正方形头像的账号,检查卡片是小图卡片(
summary)。
X 会缓存卡片。要检查更改,请粘贴带查询参数的 URL(例如 ?v=2),让它被视为另一个 URL。
Mastodon
Section titled “Mastodon”- 用另一个实例上的账号发一条包含带图片帖子 URL 的帖子。
- 检查帖子下方出现了带有标题、描述和图片的预览卡片。
- 检查卡片下方把测试账号(
fediverse:creator)显示为“作者”,并且可以进入它的个人资料。
Mastodon 会在每个获取过该卡片的服务器上缓存它。要重新生成,请使用新的 URL(带查询参数)发帖。
Discord
Section titled “Discord”- 把带图片的帖子的 URL 粘贴到频道中。
- 检查嵌入内容显示了网站名称(实例名称)、标题、描述和大图。
- 对于超过 200 个字符的帖子,检查描述以
…结尾,且没有表情符号被从中间截断。
- 把带图片的帖子的 URL 粘贴到频道中。
- 检查展开的预览显示了网站名称、标题、描述和图片。
- 检查
unlisted帖子的 URL 也会出现预览(noindex针对的是搜索引擎,不会阻止预览)。
Slack 也会缓存预览。要检查更改,请在 URL 后加上查询参数。
- 在聊天中发送带图片的帖子的 URL。
- 检查出现了带有标题、描述和图片的预览。
LINE 也会缓存预览。要检查更改,请在 URL 后加上查询参数。
不得显示的内容
Section titled “不得显示的内容”在每个服务上,检查 private 帖子的 URL 和不存在的帖子的 URL 都给出相同的通用预览(只有实例名称,或什么都没有),并且不显示任何正文、昵称或图片。
帖子中链接的卡片
Section titled “帖子中链接的卡片”为了给帖子中的链接显示卡片,本服务器的任务会获取被链接的页面及其图片,并遵守被链接网站对此的要求。它对页面、图片和 robots.txt 的请求使用 my-linkcard/<version> (+https://<host>/)。服务器的其他所有请求,包括媒体代理的请求,仍使用 my/<version> (+https://<host>/)。这些请求不发送 Cookie,也不发送 Referer,不会透露是哪个账号或哪条帖子链接了该页面。
面向网站运营者的页面
Section titled “面向网站运营者的页面”https://<host>/about/crawler 告诉被链接网站的运营者:爬虫请求什么、发送什么、频率如何、如何退出,以及他们可以请你停止从他们的域名获取内容。任何人无需账号即可阅读。实例信息页面(/about)的“搜索引擎和 AI”部分链接到该页面;User-Agent 中只写明 https://<host>/。
页面根据 link_cards 和 link_cards_ignore_robots_txt 说明本服务器的行为,并显示实例的联系方式(contact_account、contact_email)。请设置联系方式,让网站有地方可以提出请求:没有联系方式时,页面会说明本服务器没有公开任何联系方式。开启 link_cards_ignore_robots_txt 时,页面会说明网站无法通过 robots.txt 拒绝本服务器。
robots.txt
Section titled “robots.txt”robots.txt 中使用的名称是 my-linkcard,不区分大小写。没有该名称的组时,按 RFC 9309 的规定适用 * 组。服务器读取 Allow、Disallow、* 和 $,以最长匹配为准,长度相同时 Allow 优先;不读取 Crawl-delay 和其他记录。robots.txt 最多在 10 秒内读取 512 KiB,文件更大时使用已读取的部分。服务器只按来源(scheme、主机和端口)保存适用于 my-linkcard 的规则。
robots.txt 的响应 |
服务器的行为 | 保存时长 |
|---|---|---|
| 200 | 遵守该文件 | 24 小时 |
| 429 以外的 4xx | 视为没有文件:获取 | 24 小时 |
| 429、5xx、网络故障,或服务器拒绝的重定向 | 不从该来源获取任何内容 | 1 小时 |
| 超过 5 次重定向 | 视为没有文件:获取 | 24 小时 |
- 无论帖子的可见范围如何,页面的 URL 都会在请求之前检查。它重定向到的每个 URL 也会按该 URL 来源的
robots.txt检查;重定向到被拒绝的 URL 时就此终止:服务器不会请求它,也不会生成卡片。 - 被
robots.txt禁止的 URL 与页面的其他失败一样,24 小时内不会再获取。如果只是无法读取该文件,服务器会在一小时后再次尝试该页面,直到达到任务的尝试次数上限。 - 图片也按其自身来源以同样方式检查。被禁止的图片会使卡片不带图片。如果只是无法读取该文件,之前记录的图片保留,新图片则在下一次重新获取之前不加入。
- 重新获取(帖子可能在上次获取 14 天后触发)时,如果
robots.txt禁止该 URL,卡片会被移除。如果只是无法读取该文件,卡片保留。 - 服务器不会逐一重新检查已有的卡片,因此更改了规则的网站,会在各张卡片下一次重新获取时失去该卡片。
link_cards_ignore_robots_txt(实例设置)会关闭上述全部行为:服务器既不获取也不使用 robots.txt。它仍然自称 my-linkcard,但被链接的网站将无法通过 robots.txt 拒绝这些获取:如面向网站运营者的页面所告知的,只剩下其页面中的指令,以及请你为其域名设置规则的请求。
服务器还会读取所获取页面的指令:<head> 中的 <meta name="robots"> 和 <meta name="my-linkcard">,以及不带机器人名称或带有 my-linkcard: 的 X-Robots-Tag。针对其他机器人的指令不适用。有多条指令时,以更严格的为准。无论 link_cards_ignore_robots_txt 如何设置,这些指令都适用。
| 指令 | 卡片 |
|---|---|
nosnippet、max-snippet:0 |
不带描述 |
noimageindex、max-image-preview:none |
不带图片,也不获取图片 |
noindex、nofollow、noarchive、none 及其他 |
无变化 |
无论使用哪种指令,标题、网站名称和作者都会保留;不希望显示这些内容的网站,应在 robots.txt 中拒绝获取。指令要在获取页面之后才能知道,因此它们不会阻止对页面的请求。重新获取时适用页面当时的指令。
每个主机的限制
Section titled “每个主机的限制”无论 link_cards_ignore_robots_txt 如何设置,爬虫对每个主机都很克制。主机是 URL 中的名称,不含端口,因此被链接的网站和其图片所在的主机各有各的限制。
- 对同一主机一次只进行一次获取,下一次至少在上一次结束 1 秒后开始。一次获取是一个请求及其重定向,以及在需要读取时它所需的
robots.txt。页面和它的图片是两次获取,即使在同一主机上也是如此。 429或503会停止从作出该响应的主机获取,即使它响应的是重定向、图片或robots.txt也是如此。停止时长取其Retry-After(秒数或日期),最短 1 秒,最长 1 小时。缺少或无法读取Retry-After时按 1 分钟计。- 需要等待轮次的任务会稍后再回来。没有 worker 在等待,也不消耗任务的尝试次数,因此即使大量链接同时指向一个网站,最终也会生成所有卡片,没有失败的任务。同一主机的任务大约每秒唤醒一个。
- 主机让爬虫暂停的 URL 会保留其卡片,不会被记为失败,并在暂停结束时获取。如果一个 URL 在 24 小时内收到 5 次这样的响应,该页面与其他非
200的页面一样算作失败,图片则不加入卡片。 - 等待图片的卡片会把从页面读取的内容保留最多 2 小时,以免再次请求该页面。
- 域名规则和域名处置优先:不从其获取任何内容的主机,不会有任何等待。
这些限制保存在键值存储中,并且都会过期:在获取过程中停止的 worker 会在 2 分钟内释放其主机。这些数值不是设置项。要查看限制的运作情况:
my.link_card.host_pauses按主机响应的状态统计暂停次数,每次暂停都会在INFO级别记录link card host paused,带有host、status和pause_seconds。- 带有
my.job.type="content.fetch_link_card"和my.outcome="postponed"的my.job.duration统计稍后再回来的运行次数。数值很大说明大量链接指向少数网站或暂停时间很长,并不是失败。
供 LLM 和编程智能体使用:llms.txt,llms-full.txt, llms-small.txt