跳到內容

本頁由英文頁面機器翻譯而成。內容以英文頁面為準。 閱讀英文頁面

連結預覽(OGP / X Card / fediverse:creator)

本頁說明其他服務為這台伺服器的頁面顯示的預覽、伺服器為此回傳的內容,以及手動檢查的步驟。這台伺服器為自己貼文中的連結顯示的卡片,請參閱下方的貼文中連結的卡片;如何停止從某個網域擷取卡片,請參閱實例設定。

my serve 會將 meta 標籤嵌入網頁用戶端的外殼中,來回傳首頁(https://<host>/)、實例資訊頁面(https://<host>/about)、已發布文件的頁面(/about/terms、/about/privacy、/about/commerce)、連結卡片爬蟲的頁面(/about/crawler)、個人檔案(https://<host>/@alice)和貼文(https://<host>/@alice/status/<post ID>)的 HTML。 對 HTML 的請求一律視為未登入,所以預覽只會顯示未登入的訪客能看到的內容。

頁面 回應
首頁(/)和實例資訊頁面(/about) 200。帶有介紹實例的 meta 標籤的外殼(請見下方的「首頁」)
連結卡片爬蟲的頁面(/about/crawler) 200。帶有介紹實例的 meta 標籤的外殼,標題為「Link card crawler | 實例名稱」
已發布文件的頁面(/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 摘要訂閱源的連結(請見下方的「通用外殼」)
網頁用戶端的其他每個頁面(探索、公開的費用與支持者頁面、登入等) 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。

標籤 內容
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 on 實例名稱」(server:feed.tag_title),不論是否已有貼文使用過該主題標籤。分享主題標籤或公開費用頁面的連結,會顯示實例的卡片。

摘要訂閱源本身是 Atom 1.0 文件,內含最新 20 則不是回覆或轉發的本地公開貼文,並帶有 ETag、Last-Modified 和 Cache-Control: public, max-age=60。文章的項目是它的標題與摘要,並附上文章的連結;內文留在文章的頁面上。每個擁有摘要訂閱源的個人檔案也有只含文章的摘要訂閱源 https://<host>/@<username>/articles.atom,標題為「Articles by name (@handle)」(server:feed.articles_title),遵循相同的規則;個人檔案的頁面只連結它的主要摘要訂閱源。伺服器會將每個轉譯後的摘要訂閱源在它的鍵值儲存中保留一分鐘,所以變更會在約一分鐘內傳到摘要訂閱源。摘要訂閱源帶有與其個人檔案相同的 X-Robots-Tag 和 AI 聲明;主題標籤的摘要訂閱源一律為 noindex,並會表明其任何作者的 AI 拒絕。沒有摘要訂閱源的個人檔案,以及沒有貼文使用過的主題標籤,都回應 404。

og:image 依下列順序選出。

  1. 貼文所附的第一張圖片,或文章的封面(它的替代文字會放入 og:image:alt)。被標示為敏感內容的貼文或文章,以及有內容警告的貼文,不會使用它。
  2. 個人檔案的封面圖片,沒有則用大頭貼(og:image:alt 是「{name} 的封面圖片」或「{name} 的大頭貼」)。
  3. 實例預覽圖片(實例設定 preview_image,在管理的「設定 → 一般」中的「連結預覽」之下;og:image:alt 是文字 preview_image_alt,沒有時則為「{實例名稱} 的圖片」)。
  4. 實例縮圖(實例設定 thumbnail,「設定 → 一般」頁面的圖片;og:image:alt 是文字 thumbnail_alt,沒有時則為「{實例名稱} 的圖片」)。
  5. 實例自己標誌的連結預覽版本(標誌與圖示),位於 https://<host>/brand/<revision>/preview-1200x630.png 的 1200x630 PNG(og:image:alt 是「{實例名稱} 的圖片」)。
  6. 內建的預設圖片(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)。

  1. 用測試帳號準備以下貼文。

    • 附有橫向圖片(例如 1200x630)和替代文字的 public 貼文
    • 沒有圖片的 public 貼文(來自有封面圖片的帳號)
    • 內文超過 200 個字元並含有表情符號(例如 👨‍👩‍👧‍👦)的 public 貼文
    • unlisted 貼文
    • private 貼文
    • 來自顯示名稱含有 "><script>alert(1)</script> 的帳號的貼文
  2. 檢查每個 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> 被跳脫為 &lt;script&gt;。

  1. 把附有圖片的貼文 URL 貼到撰寫畫面(或私訊)中。
  2. 確認大圖卡片(summary_large_image)顯示了標題、網域和圖片。
  3. 對於沒有圖片的貼文 URL,確認卡片顯示了封面圖片。對於既沒有封面圖片也沒有大頭貼的帳號,確認大卡片顯示預設圖片(preview_image,未設定時為內建圖片)。
  4. 對於只有正方形大頭貼的帳號,確認卡片是小圖卡片(summary)。

X 會快取卡片。若要檢查變更,請在 URL 加上查詢字串(例如 ?v=2)再貼上,讓它被視為不同的 URL。

  1. 從其他實例上的帳號,發布一則包含附有圖片的貼文 URL 的貼文。
  2. 確認貼文下方出現了帶有標題、說明和圖片的預覽卡片。
  3. 確認卡片下方以「作者」顯示測試帳號(fediverse:creator),且可以前往其個人檔案。

Mastodon 會在每台擷取過卡片的伺服器上快取卡片。若要重新產生,請以新的 URL(加上查詢字串)發文。

  1. 把附有圖片的貼文 URL 貼到頻道中。
  2. 確認嵌入內容顯示了網站名稱(實例名稱)、標題、說明和大圖。
  3. 對於超過 200 個字元的貼文,確認說明以 … 結尾,且沒有任何表情符號在中間被截斷。
  1. 把附有圖片的貼文 URL 貼到頻道中。
  2. 確認展開的預覽顯示了網站名稱、標題、說明和圖片。
  3. 確認 unlisted 貼文的 URL 也會出現預覽(noindex 是給搜尋引擎的,不會阻止預覽)。

Slack 也會快取預覽。若要檢查變更,請在 URL 加上查詢字串。

  1. 在聊天中傳送附有圖片的貼文 URL。
  2. 確認出現了帶有標題、說明和圖片的預覽。

LINE 也會快取預覽。若要檢查變更,請在 URL 加上查詢字串。

在每個服務上,確認 private 貼文的 URL 和不存在的貼文的 URL 都會得到相同的通用預覽(只有實例名稱,或什麼都沒有),且不會出現任何內文、顯示名稱或圖片。

為了替貼文中的連結顯示卡片,這台伺服器的任務會擷取被連結的頁面及其圖片,並遵守被連結網站對此的聲明。它對頁面、圖片和 robots.txt 的請求使用 my-linkcard/<version> (+https://<host>/)。伺服器的其他所有請求,包括媒體代理,仍使用 my/<version> (+https://<host>/)。這些請求不傳送 Cookie 也不傳送 Referer,也不會透露是哪個帳號或貼文連結了該頁面。

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 中的名稱是 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 中拒絕擷取。指示要在擷取頁面後才會知道,因此不會阻止對頁面的請求。重新擷取時會套用頁面當時的指示。

不論 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.duration 中 my.job.type="content.fetch_link_card" 且 my.outcome="postponed" 的部分,會計算稍後再回來的執行次數。數字很大表示有許多連結指向少數網站或暫停時間很長,而不是失敗。

供 LLM 與程式設計代理使用:llms.txt,llms-full.txt, llms-small.txt

本站的流量分析