跳到內容

環境變數

Hollo 是透過環境變數進行設定的。你可以在專案根目錄的 .env 檔案中設定它們,或者使用 Docker 的 -e/--env 選項或 Railway 的環境變數進行設定。

PORT 可選 Railway 中未使用

Section titled “PORT ”

伺服器監聽的連接埠號碼。預設為 3000。

BIND 可選 Railway 中未使用

Section titled “BIND ”

伺服器監聽的位址。必須是有效的 IP 位址或 localhost。

DATABASE_URL Railway 中未使用

Section titled “DATABASE_URL ”

PostgreSQL 資料庫的 URL,例如:postgresql://hollo:password@localhost/hollo。

SECRET_KEY Railway 中未使用

Section titled “SECRET_KEY ”

用於保護工作階段的密鑰。必須至少 44 個字元長。你可以使用以下指令產生一個隨機密鑰:

openssl rand -hex 32

應用程式的時區。 必須是有效的時區識別碼,例如:UTC、America/New_York、Asia/Taipei。

預設是 UTC。

控制此程序中執行的元件。有效值為:

  • all(預設):執行 Web 伺服器、Fedify 訊息佇列、匯入工作器、 清理工作器、遠端回覆抓取工作器和投票通知任務
  • web:僅執行 Web 伺服器(HTTP API)
  • worker:僅執行工作器(Fedify 訊息佇列 + 匯入工作器 + 清理工作器 + 遠端回覆抓取工作器 + 投票通知任務)

這允許將 Web 伺服器與後台工作器分離以獲得更好的可擴展性。 在執行具有大量追蹤者的高流量實例時,分離工作器可以提高效能。

預設為 all。

匯入、清理、遠端回覆收集和投票通知使用工作器節點分離中說明的專用任務佇列。所有節點的任務定義必須相容。

BEHIND_PROXY 可選 Railway 中未使用

Section titled “BEHIND_PROXY ”

如果 Hollo 在反向代理後面,請將此設定為 true。如果你將 Hollo 放在 L7 負載均衡器後面(通常應該這樣做),請開啟此選項。

預設關閉。

啟用後,Hollo 使用以逗號分隔的 X-Forwarded-Host 和 X-Forwarded-Proto 標頭中的第一個非空值。無效的轉送主機會被忽略,並使用原始 Host 標頭。 請設定代理以覆寫用戶端提供的轉送標頭,並只允許受信任的代理直接連線至 Hollo。

在分域 WebFinger 設定中用作聯邦宇宙帳號句柄的網域名稱。 設定後,聯邦宇宙帳號的形式為 @user@HANDLE_HOST,但 Hollo 本身 仍在 WEB_ORIGIN 上執行。

必須與 WEB_ORIGIN 一起設定;只設定其中一個會導致 Hollo 啟動失敗。 請務必在建立第一個帳號之前完成設定——一旦聯邦開始後再更改 句柄網域名稱,會破壞所有遠端追蹤關係。

預設情況下不設定。

在分域 WebFinger 設定中 Hollo 的 ActivityPub 伺服器實際執行的來源(scheme + host),例如 https://ap.example.com。所有 actor URI、收件箱 URL 等聯邦端點 都將基於此來源建構。

必須與 HANDLE_HOST 一起設定; 只設定其中一個會導致 Hollo 啟動失敗。

預設情況下不設定。

將此選項設定為 true 將停用 SSRF(伺服器端請求偽造)保護。

開啟此選項可在本地網路中進行測試。

預設情況下關閉。

如果存在,首頁將重新導向到此 URL。如果未設定,首頁將顯示實例上的帳號清單。

以逗號分隔的本機貼文選用 Markdown 擴充功能清單。可用名稱為footnote、 deflist、sub、sup、mark、ruby、ins、abbr、tasklist和math。 例如,MARKDOWN_EXTENSIONS=footnote,ruby,math啟用註腳、注音和數學公式。 名稱前後的空白會被忽略,重複名稱會合併;未知名稱會導致啟動失敗。 未設定或為空時,所有選用擴充功能均關閉。表格和刪除線無需此設定即可使用。

擴充功能僅在建立或明確編輯本機貼文時套用,不用於個人簡介或資料欄位。 變更設定不會改變既有貼文儲存的原始文字或 HTML,也不會傳送更新。 編輯貼文時會使用目前設定重新呈現,因此關閉擴充功能後再編輯,可能會直接顯示其語法。

語法、跳脫和聯邦互通限制請參閱 Markdown 指南。

以逗號分隔的語言區域標籤模式清單,用於指定哪些本地貼文應透過 Gukhanmun為漢字加上韓文讀音。比對不區分大小寫,*可比對任意長度的 字串。例如,GUKHANMUN=ko,ko-*可比對ko、ko-KR、 ko-Kore-KR和ko-KP。

ko-*模式不會比對單獨的ko標籤,因此若要處理這兩種形式,需要同時列出 兩個模式。區域子標籤為KP的語言區域使用ko-kp轉換預設,其他符合的 語言區域使用ko-kr。詞語讀音取決於所選辭典,請參閱下方的GUKHANMUN_DICTS。

如果未設定此變數或將其留空,Hollo不會載入Gukhanmun。它只處理新建或編輯的 本地貼文,不會變更現有貼文或遠端貼文。載入或轉換失敗時,貼文請求也會失敗。

按優先順序以逗號分隔指定Gukhanmun使用的辭典。優先使用第一個符合辭典的 讀音。例如,GUKHANMUN_DICTS=loanwords,stdict會優先使用外來語標記用例, 其次使用標準國語大辭典。

支援loanwords(韓國國立國語院外來語標記用例)、stdict(標準國語大辭典)、 opendict:general(우리말샘的一般詞)、opendict:north-korean(北韓詞)、 opendict:dialect(方言)和opendict:archaic(古語)。opendict在清單中的 目前位置依序展開為一般詞、北韓詞、方言和古語四個類別。

預設值為loanwords,opendict:general,opendict:dialect,stdict。 所有語言區域使用相同的清單。若要優先使用北韓詞辭典的讀音,請將 opendict:north-korean放在前面。

忽略名稱兩側的空白和空清單項目。值為空時不載入詞語辭典,但仍使用Unihan的 單字讀音。未知名稱會導致轉換失敗。此設定本身不會啟用轉換,仍需透過 GUKHANMUN指定要處理的語言區域。

REMOTE_ACTOR_FETCH_POSTS 可選

Section titled “REMOTE_ACTOR_FETCH_POSTS ”

首次遇到遠端用戶時,從遠端用戶取得的最近公開貼文數量。

預設為 10。

REMOTE_REPLIES_SCRAPE_DEPTH 可選

Section titled “REMOTE_REPLIES_SCRAPE_DEPTH ”

背景取得遠端回覆的層數。如果貼文有 FEP-f228 context 集合,Hollo 會 先讀取該集合,並在需要時回退至 replies 集合。設為 0 可停用這兩種 收集方式。不會取得上下文集合中缺少的祖先貼文。缺少父貼文的貼文會儲存, 但在狀態上下文的回覆樹中不會連接至該父貼文。

預設值為 2。

REMOTE_REPLIES_SCRAPE_MAX_ITEMS 可選

Section titled “REMOTE_REPLIES_SCRAPE_MAX_ITEMS ”

每次上下文收集嘗試遍歷的項目數上限,包含已儲存的貼文。對於 replies 工作,此值限制儲存的回覆數。達到上限後會記錄為部分收集,並回退至 各起始貼文的 replies 集合。

預設值為 100。

REMOTE_REPLIES_SCRAPE_MAX_REQUESTS 可選

Section titled “REMOTE_REPLIES_SCRAPE_MAX_REQUESTS ”

每次收集嘗試呼叫文件載入器的次數上限,由集合遍歷與貼文、作者儲存共用。 快取文件與內建 JSON-LD 上下文不計入,自訂 JSON-LD 上下文計入。 不限制載入器內部的重新導向、簽章重試,以及 WebFinger、NodeInfo、媒體下載 或預覽卡片請求。達到上限後會記錄為部分收集,並回退至 replies 集合。

預設值為 200。

REMOTE_EMOJI_REACTIONS_FETCH_MAX_ITEMS 可選

Section titled “REMOTE_EMOJI_REACTIONS_FETCH_MAX_ITEMS ”

儲存遠端貼文時,從遠端 emojiReactions 集合匯入並儲存的表情回應項目 最大數量。設定為 0 可停用遠端表情回應匯入。

預設為 100。

REMOTE_REPLIES_SCRAPE_INTERVAL_SECONDS 可選

Section titled “REMOTE_REPLIES_SCRAPE_INTERVAL_SECONDS ”

對同一 origin 發起遠端回覆抓取請求之間的最小延遲秒數。

預設為 5。

REMOTE_REPLIES_SCRAPE_BACKOFF_SECONDS 可選

Section titled “REMOTE_REPLIES_SCRAPE_BACKOFF_SECONDS ”

當遠端伺服器回傳 HTTP 429 且未提供 Retry-After 時, 重試遠端回覆抓取作業前的等待秒數。

預設為 300。

REMOTE_REPLIES_SCRAPE_COOLDOWN_SECONDS 可選

Section titled “REMOTE_REPLIES_SCRAPE_COOLDOWN_SECONDS ”

完成的遠端收集工作抑制同一集合重複工作的時間。失敗的上下文工作也遵守 此冷卻時間,但各起始貼文仍可回退至 replies 集合。

預設值為 300 秒。

控制 Hollo 如何向用戶端提供位於遠端伺服器的媒體(頭像、橫幅圖、附件、 自訂表情、連結預覽卡片圖片)。可用值:

  • off(預設):Mastodon API 和 Web UI 將遠端 URL 原樣交給用戶端, 與歷史行為一致。
  • proxy:將所有遠端媒體 URL 改寫為帶簽章的 /proxy/<sig>/<b64url> 路徑,由 Hollo 自己提供。Hollo 在每次請求時 將上游位元組串流轉發,不寫入磁碟。用戶端只看到 Hollo 自身的來源, 避免遠端 CORS 設定的影響,也避免訪客的 IP 被洩露。
  • cache:URL 改寫與 proxy 相同,但會把串流取得的回應主體儲存到 所設定儲存後端的 proxy/<sha256>.bin,並把記錄內容類型的旁路檔案 儲存到 proxy/<sha256>.json。後續請求會跳過上游請求。與本機帳號 存在已核准追蹤關係的遠端 actor 頭像,也會在 actor 被儲存或重新整理時 預先擷取到此快取中。管理面板的 /thumbnail_cleanup 頁面可以按需清空快取。

布林同義值:true / on / 1 作為 proxy 的別名, false / off / 0 作為 off 的別名。磁碟快取必須用 cache 明確 開啟。

在 proxy 和 cache 模式下,Hollo 會拒絕代理非 HTTP(S) 協定,對上游 URL 和每一次重新導向目標執行 SSRF 檢查,將回應主體限制為 32 MiB,並且 絕不代理 image/svg+xml——SVG 可能包含會在 Hollo 自身來源上執行的內嵌 腳本。

預設為 off。

REMOTE_MEDIA_THUMBNAILS 可選

Section titled “REMOTE_MEDIA_THUMBNAILS ”

控制 Hollo 接收貼文時是否下載遠端附件媒體以產生本地 WebP 縮圖。 可用值為 on / true / 1(歷史行為)或 off / false / 0。

設定為 off 時,Hollo 會對收到的附件完全跳過上游下載和 Sharp 流程, 直接將遠端 URL 作為縮圖 URL 儲存。配合 MEDIA_PROXY=proxy 或 cache 使用時,用戶端在渲染時仍然得到同源 URL;若 MEDIA_PROXY=off, 用戶端會直接收到上游 URL。在接收大量媒體型貼文的實例上可以顯著 節省磁碟空間。

預設為 on。

REMOTE_ACTOR_STALENESS_DAYS 可選

Section titled “REMOTE_ACTOR_STALENESS_DAYS ”

遠端用戶的快取資料被視為過期的天數。 在處理活動時(例如收到轉發或新貼文),如果遇到過期的用戶, 其個人資料資料將被非同步刷新。

預設為 7。

REFRESH_ACTORS_ON_INTERACTION 可選

Section titled “REFRESH_ACTORS_ON_INTERACTION ”

設定為 true 時,會在所有傳入的活動(按讚、表情回應、追蹤等)中 檢查過期的用戶資料。設定為 false(預設)時, 僅在時間軸上顯示的活動(Announce、Create)中檢查。

預設情況下關閉。

將此設定為 false 後,將停用時間軸收件箱模式。啟用(預設)時, 時間軸上可見的所有貼文都實際儲存在資料庫中,而不是在顯示時即時過濾。 這對於有大量傳入貼文的相對較大的實例非常有用。

從 Hollo 0.9.0 起,預設值更改為 true。在 Hollo 1.0.0 中, 此選項將被完全刪除,屆時時間軸收件箱模式將成為唯一的行為。

預設情況下開啟。

將此設定為 true 後,您可以在 Markdown 中使用原始 HTML。 (Hollo 中用 Markdown 來介紹個人資料和發布內容等) 當您想要使用比 Markdown 支援的格式更多樣的格式時,它很有用, 但 HTML 標記和屬性受到一定限制,以防止 XSS 攻擊。

預設情況下關閉。

應用程式的記錄層級。可選項有:debug、info、warning、error 和 fatal。

預設是 info。

將此設定為 true 以記錄 SQL 查詢。

預設關閉。

指定要寫入結構化記錄的檔案路徑。記錄以結構化記錄格式寫入(預設為 JSON Lines)。

LOG_FILE 指定的記錄檔格式。有效值為:

  • jsonl(預設):JSON Lines 格式,每行一個 JSON 物件。 適合解析結構化 JSON 的記錄聚合工具。
  • logfmt:logfmt 格式,每行一組鍵值對。 易於人工閱讀,相容 Loki 等工具。

預設為 jsonl。

Sentry 專案的 DSN,用於發送錯誤報告和追蹤資訊。

將此設定為 true 以啟用 Fedify 除錯器,這是一個用於即時檢查 ActivityPub 追蹤和活動的內嵌除錯儀表板。啟用後,可在 /__debug__/ 存取除錯儀表板。

預設情況下關閉。

用於在 Hollo 上儲存頭像、自訂表情符號和其他媒體等檔案的磁碟驅動程式。

可以選擇 fs(本地檔案系統)或 s3(S3 相容物件儲存)。

出於向後相容性考量,s3 是預設設定,但建議明確設定,因為預設設定將來會被移除。

有關驅動程式的更多資訊,請參閱 FlyDrive 文件(英文)。

資產儲存的公開 URL 基礎,例如:https://media.hollo.social。

當使用 DRIVE_DISK=fs 時,您應該設定此項以透過 Web 存取提供本地檔案系統檔案, 通常格式為 https://<主機>/assets,例如:https://hollo.example.com/assets。

FS_STORAGE_PATH FS 驅動程式必填

Section titled “FS_STORAGE_PATH ”

檔案在本地檔案系統中的儲存路徑。例如:/var/lib/hollo。

S3_REGION S3 驅動程式必填

Section titled “S3_REGION ”

S3 相容物件儲存的區域,例如:us-east-1。在某些非 S3 服務中,可以省略此項。

S3_BUCKET S3 驅動程式必填

Section titled “S3_BUCKET ”

S3 相容物件儲存的儲存桶名稱,例如:hollo。

S3_ENDPOINT_URL S3 驅動程式必填

Section titled “S3_ENDPOINT_URL ”

S3 相容物件儲存的端點 URL,例如: https://s3.us-east-1.amazonaws.com。

是否強制在 S3 相容物件儲存中使用路徑格式的 URL。設定為 true 開啟,false 關閉。對於非 AWS 的 S3 相容服務非常有用。預設關閉。

AWS_ACCESS_KEY_ID S3 驅動程式必填

Section titled “AWS_ACCESS_KEY_ID ”

S3 相容物件儲存的存取金鑰 ID。

AWS_SECRET_ACCESS_KEY S3 驅動程式必填

Section titled “AWS_SECRET_ACCESS_KEY ”

S3 相容物件儲存的存取金鑰。