本頁由英文頁面機器翻譯而成。內容以英文頁面為準。 閱讀英文頁面
管理員與角色
本頁說明如何建立第一位管理員、從命令列管理角色、公告並執行服務終止、重新處理上傳的圖片、重建搜尋索引、處理伺服器自行提供的 TLS 憑證,以及匯出維護頁面。
- 設定(
host、database、database_url、kek等)已依照設定參考的說明設好。my config check會驗證設定。 - 結構描述(schema)已套用到資料庫(
my schema apply;請參閱 database.md)。 host和account_domain已經確定。第一個使用資料庫的指令會記錄這兩個值,之後只要設定不同,每個指令都會拒絕執行(請參閱之後無法變更的設定)。
my admin create -username alice -email alice@example.com- 從終端機執行時,指令會要求輸入兩次密碼,輸入內容不會顯示在畫面上。
- 標準輸入不是終端機時,標準輸入的第一行就是密碼(例如
my admin create ... < password.txt)。密碼不能以命令列引數或環境變數提供,因為這些會留在行程列表和 shell 歷史記錄中。 - 在一次性指令既沒有終端機也沒有標準輸入的環境(例如 Cloud Run job)中,請加上
-password-link。此時指令不會讀取密碼:它會設定一組沒有人知道的隨機密碼,並在created admin這一行之後印出一個連結。這個連結和my admin account password-reset-link一樣,可以在一小時內設定一次密碼(稽核記錄會記為password_reset_link_issued)。能讀到指令輸出的人都可以使用這個連結,而在這類平台上,輸出會一直留在平台的日誌中,直到連結被使用或過期為止。請立刻開啟連結。如果連結過期,請用my admin account password-reset-link @alice再發一個。如果發行連結失敗,管理員已經建立好了:指令會說明這一點並以結束代碼 1 結束,再執行同一個指令就會得到新的連結。 - 密碼長度為 8 到 128 個字元。密碼絕不會出現在輸出、日誌或錯誤訊息中。
- 一個交易會建立使用者、密碼、主要電子郵件地址、本站帳號(含其金鑰),以及
admin角色的授予(沒有授予者,代表由 CLI 授予)。如果內建角色不存在,會先建立它們。 - 成功時,指令會印出
created admin @alice@<account_domain> (user <id>, account <id>),並以結束代碼 0 結束。 - 在單人伺服器上,指令不會建立帳號,並以結束代碼 1 結束。當登入限定使用登入提供者時,指令也會警告:在限制解除之前,這組密碼無法用來登入。
- 當使用者名稱或電子郵件地址(兩者都不分大小寫)已被使用時,指令不會做任何變更,會印出哪一個已被使用,並以結束代碼 1 結束。它絕不會變更現有使用者的密碼或角色。
- 失敗的執行不會寫入任何東西,所以你可以排除原因後再執行同一個指令。
- 結束代碼 2 表示用法錯誤。
授予與撤銷角色
Section titled “授予與撤銷角色”角色包含權限。內建角色有 admin(position 為 1000,擁有所有權限)和 moderator(position 為 100,擁有 manage_reports、manage_accounts 和 view_audit)。
my serve 每次啟動時(不論 role 為何的程序)都會檢查內建角色,my admin role 每次執行時也會檢查。
兩者都會建立缺少的角色,並讓 admin 擁有目前執行版本的所有權限。
升級新增權限時,不需要任何手動步驟。moderator 會保留管理員所設定的權限與 position。
my admin role list # each role's position, permissions (grouped as moderation, server administration, and member features), and holdersmy admin role list -user alice # the roles of alicemy admin role grant alice moderatormy admin role revoke alice moderator-
權限分屬三個群組之一。
- 審核:
manage_reports、manage_accounts、manage_domains、manage_invites、view_audit。 - 伺服器管理:
manage_settings、manage_rules、manage_roles、manage_jobs、manage_login_recovery、manage_custom_emojis、manage_webhooks、manage_announcements、manage_finance、manage_supporters、manage_oauth_apps、manage_service_closure、manage_errors、manage_login_providers。 - 成員功能:
view_finance、create_custom_emojis、start_voice_rooms、create_invites、keep_posts_longer、create_articles、create_events。
list會為每個群組輸出一欄(MODERATION、SERVER、MEMBER)。網頁用戶端會將前兩個群組顯示為「審核」和「管理」,成員功能則不計入這兩者(請參閱 moderation.md)。 - 審核:
-
變更會在使用者的下一次請求時生效。給版主的通知,會送給通知建立當下持有該權限的人。
-
授予與撤銷會以
role_granted和role_revoked(目標種類為role)寫入稽核紀錄。CLI 操作的執行者是cli(my admin audit list -target-kind role)。 -
授予使用者已有的角色,或撤銷他沒有的角色,不會變更也不會記錄任何東西。
-
admin的最後一位持有者不能失去它(結束碼 1)。請先將admin授予另一位使用者。 -
管理畫面「角色」(
/admin/roles)會列出所有角色,並可建立、變更和刪除角色:角色的頁面可設定它的位置、權限和徽章。它只提供下列規則允許的選項:不高於你最高角色的位置、你自己持有的權限(角色擁有的其他權限會列出名稱並保留)、只有admin的徽章,以及不能刪除admin或moderator。刪除角色時需要輸入它的名稱。方案的角色由方案設定。 -
管理 API 是
GET /api/v1/admin/roles、GET /api/v1/admin/accounts/{id}/roles,以及PUT/DELETE /api/v1/admin/accounts/{id}/roles/{role},且需要manage_roles權限。 透過 API,你不能授予或撤銷高於你自己所有角色中最高position的角色(403)。撤銷最後一個admin會回傳 409。 -
工作人員只能對較低的層級採取行動。透過 API,審核動作與解除這些動作、裁決申訴、解除電子郵件抑制、揭露帳號的私人資料、發出密碼重設連結,以及移除雙重驗證,都要求你的角色中最高的
position高於目標的每一個角色;較高或相等的層級(包括你自己的帳號)會回傳 403。版主不能對管理員採取行動,一位管理員也不能對另一位管理員採取行動。這些指令(my admin account ...)沒有這樣的限制,所以在管理員之間意見不合時請使用它們。 -
唯一的管理員不能被鎖在門外或被移除:對他執行
disable_login、suspend和ban都會被拒絕,不論是透過 API(409)還是這些指令(結束碼 1),而且他不能刪除自己的帳號(409)。另一位admin持有者,只有在他還能登入時才算數:刪除帳號之後、遭到停權或封鎖期間,或處於disable_login之下,都不算。
公告服務終止
Section titled “公告服務終止”要關閉伺服器,請先公告關閉。service-closure.md 說明從公告到捨棄資料的完整程序。公告期間伺服器照常運作。GET /api/v1/instance 中的 closure 和 NodeInfo 中的 metadata.serviceClosure 會顯示狀態和日期。
my admin closure announce -closes-at 2027-01-31T15:00:00Z -message "Thank you for using this server."my admin closure announce -closes-at 2027-02-28 -export-until 2027-04-30 # change the dates (a bare date means 00:00 UTC)my admin closure status # the state and the schedule in effectmy admin closure withdraw # withdraw the announcement-closes-at沒有下限。-export-until(取出資料的期限)必須在-closes-at當天或之後,預設為關閉日的 30 天後。- 關閉日距今不到 30 天時,指令會在標準錯誤輸出印出警告(公告仍會被記錄)。
- 變更日期會被記錄為一則新的公告,撤回後再發的公告也是新的公告。伺服器關閉後,就既不能公告也不能撤回(結束代碼 1)。
- 公告、變更日期和撤回會以
service_closure_announced和service_closure_withdrawn(目標種類instance;請參閱my admin audit list -target-kind instance)寫入稽核記錄。 - 管理 API 為
GET /api/v1/admin/closure、PUT/DELETE /api/v1/admin/closure/announcement、GET /api/v1/admin/closure/check和POST /api/v1/admin/closure/close。需要manage_service_closure權限(內建角色中只有admin擁有)。 - 公告期間,伺服器不接受新使用者,也不接受新的付款。
- 實際生效的註冊模式為
closed(registration_mode的值不會改變,撤回公告後會恢復生效)。一般註冊和使用邀請的註冊都無法使用,待審核的申請也無法核准(409)。 - 公告時會拒絕所有待審核的申請(記錄為由
service_closure裁決),並將所有進行中的支持者訂閱設為在其期間結束時取消。訂閱者會收到通知(supporter_service_closure)和電子郵件。新的訂閱會回傳409。撤回公告不會復原這些拒絕和取消。 - 每一次公告、變更日期和撤回,都會將
service_closure通知送給所有本站使用者。這些都以任務執行,所以請不要停止 worker。 - 所有已確認電子郵件地址的使用者,會在公告、變更日期、撤回、關閉日前 7 天和 1 天、關閉時,以及匯出期限前 7 天收到電子郵件。使用者無法拒收(請參閱 email.md)。
- 關閉日過後,擁有
manage_service_closure的人會收到admin_service_closure_due通知。伺服器不會自行關閉。
- 實際生效的註冊模式為
關閉日過後,請關閉伺服器。關閉無法復原。
my admin closure check # review what the closure endsmy admin closure close # show the review, then ask for y and the domain namemy admin closure close -confirm-domain social.example # for automation: pass the domain name instead of answeringcheck和close會顯示本站帳號數、目的地收件匣數(已知的共用收件匣)、預計要送出的Delete活動數(兩者的乘積)、進行中的支持者訂閱數、尚未完成的搬遷(Move)數,以及處於保留措施下的帳號數(retention_holds)。還有搬遷未完成或存在保留措施時,指令會在標準錯誤輸出發出警告。請用my admin account export-moderation匯出處於保留措施下帳號的紀錄,並在捨棄資料前妥善保存。- 沒有公告時以及關閉日之前,
close會不經詢問直接拒絕(結束代碼 1)。回答y以外的任何內容,或輸入與伺服器網域(設定中的host,不分大小寫)不同的值時,不會做任何變更,並以結束代碼 1 結束。 - 關閉會以
service_closure_closed寫入稽核記錄。在同一個交易中,它會結束所有進行中的支持者訂閱(原因為service_closed),並將立即在付款服務商取消訂閱的任務(CancelNow)排入佇列。 - 關閉後,用戶端 API 只放行以下請求:讀取你自己的帳號和設定、匯出(
/exports、/csv_exports)、工作階段(/sessions、/authorized_apps)、GET /instance,以及關閉和任務佇列的管理。其他一切都會以403(/api/v1/problems/service-closed)拒絕。串流會停止,Web Push 也不再送出任何東西。登入和重設密碼仍可使用。 - 關閉後,worker 會將每個本站帳號 actor 的
Delete遞送給聯邦中的對方伺服器,每次 100 個(已搬遷的帳號排在最後)。即使federation_mode為off或inbound也會送出,但絕不會送到已停權的網域。my admin closure status(以及GET /api/v1/admin/closure中的progress)會顯示已記錄Delete的帳號數、尚待展開的遞送數,以及各狀態(pending、succeeded、permanent_failure、skipped、dead)的遞送數。遞送期間請讓 worker 持續執行。所有遞送完成後,每 10 分鐘執行一次的檢查會記錄delivery_completed(稽核記錄中為service_closure_delivery_completed),之後本站 actor 會回應410。伺服器不會自行重新執行dead的遞送;請用my job retry重新執行。
匯出期限過後,請寫出伺服器停止後由你的網域提供的靜態關閉頁面。這個指令會讀取資料庫,所以請在捨棄資料庫之前執行。
my admin closure export-html -out ./closure # every locale (the instance's default locale first)my admin closure export-html -out ./closure -lang ja,en # choose the locales and the order in index.html- 輸出:每個語系一個
<dir>/<locale>.html,以及依序包含所有語系的<dir>/index.html。這些頁面使用與my maintenance export相同的範本,顯示伺服器名稱、關閉日、公告中營運者的訊息,以及status_page_url。輸出中也包含前端的設定範例:nginx.conf、Caddyfile和cloudfront-function.js。它們對/ap/*、/inbox、WebFinger、host-meta、NodeInfo 和/@*回應410,其他一切則提供關閉頁面。 - 除非伺服器已關閉,否則指令會拒絕執行(結束代碼 1)。在
delivery_completed之前,它會印出警告但仍會寫出頁面。service-closure.md 說明如何將前端切換到靜態頁面。
重新處理上傳的圖片
Section titled “重新處理上傳的圖片”每張上傳的圖片會保留三種尺寸,動畫圖片還會保留其動態版本。my 的新版本可能會變更這些尺寸或格式,而現有圖片會一直保留原本的檔案,直到你重新處理為止:
my admin media reprocess -before 2027-01-31T09:00:00Z-before以 RFC 3339 格式指定變更的時間,例如你升級的時間。只有最後處理時間早於該時間的圖片會被處理,尚未到來的時間會被拒絕。- 任務由 worker 執行,每分鐘 100 張圖片,每張各一個任務(任務參考中的
media.reprocess_walk和media.reprocess)。請讓 worker 保持執行;管理頁面的任務頁(/admin/jobs)會顯示佇列。 - 以相同時間再次執行是安全的。已處理的圖片不會被動到,第一次執行沒處理到的圖片則會被接手處理。
- 原始檔不會保留,所以每張圖片都是從其大尺寸版本重新製作。大尺寸版本已失去的細節不會回來,而且每次以更晚的時間執行,都會再重新編碼一次而損失一些畫質。每次變更請只執行一次。
- 影片和音訊檔案不會重新編碼,也不會被動到。目前限制已不再接受的圖片會保留現有版本,worker 會記錄警告。
圖片的新版本會有新的 URL。舊檔案會保留 media_replaced_retention 的時間(預設 30 天,設定參考),讓開著的頁面和快取能繼續運作,之後每小時執行的任務 media.purge_replaced 會刪除它們。其他伺服器不會被告知新的 URL:仍持有舊 URL 且沒有自己副本的伺服器,在那之後就無法再顯示該圖片。在舊檔案刪除之前,請預留額外的儲存空間。
重建搜尋索引
Section titled “重建搜尋索引”在有搜尋引擎的伺服器上,my search 負責處理貼文全文搜尋的索引。在 search = none 時,每個指令都會說明這一點、不做任何事,並以結束代碼 0 結束。
my search rebuild # empty the index, then have the worker add every post that qualifiesmy search rebuild --keep # add them without emptying the indexmy search rebuild --rate 50 # at most 50 posts a second (20 by default, 1000 at most)my search clear # empty the index and end any rebuildmy search status # the backend and the progress and failures of the latest rebuild再次執行 my search rebuild 可以繼續已停止的重建。它會從最後處理的貼文接著進行,不會再次清空索引。有一個重建尚未完成時,另一種模式會被拒絕,並以結束代碼 1 結束。貼文的全文搜尋說明了各自的使用時機。
TLS 憑證
Section titled “TLS 憑證”my tls 處理自己提供 HTTPS 的伺服器(tls = acme 或 tls = files;請參閱由伺服器提供 HTTPS)的憑證。
my tls status # each host: certificate, renewal, failures, latest ordersmy tls renew -host social.example # order a certificate now, without waitingmy tls revoke -host social.example -reason key_compromise # replace, then revoke the current certificatestatus會顯示每個主機目前的憑證(序號、簽發者、到期日)、何時更新、連續有多少次申請沒有取得憑證,以及最近的申請與其錯誤。在tls = files下,它會顯示tls_cert_file的憑證;在tls = off下,它會說明這一點。renew和revoke需要tls = acme、執行中的伺服器(它會回應憑證授權單位的檢查),以及不是memory的kv。它們失敗時、當時有另一個程序正在申請該主機的憑證時,以及在tls = files或tls = off下,都會以結束碼 1 結束。- 私密金鑰可能已被他人得知時,
-reason為key_compromise,否則為superseded或operator。revoke已撤銷憑證但無法申請替代的憑證時,會以結束碼 0 結束並印出警告。
指令與指標說明各指令對執行中程序的影響。
匯出維護頁面
Section titled “匯出維護頁面”my maintenance export 會將維護模式的頁面寫成靜態 HTML,讓負載平衡器、CDN 或反向代理在 my serve 本身無法執行時(正在替換映像檔、某個修訂版本無法啟動)提供。
它使用與維護模式相同的範本,所以兩者顯示的文字和外觀相同。
my maintenance export -out ./maintenance -lang en,ja # reads the database for at most 5 secondsmy maintenance export -out ./maintenance -lang en,ja -offline # the configuration and the default theme only- 輸出:
-lang的每個語系一個<dir>/<locale>.html,供依Accept-Language選擇頁面的前端使用;以及依序包含所有語系的<dir>/index.html,供無法這樣選擇的前端使用。 這些頁面使用內嵌 CSS,沒有指令碼,也沒有外部資源;其 Content-Security-Policy 寫在<meta>元素中。 - 文字:設定
maintenance_server_name、maintenance_message、maintenance_until和status_page_url(設定參考)。 - 未加上
-offline時,它還會讀取實例的名稱(maintenance_server_name未設定時)、預設語系(未指定-lang時),以及已發布主題的 token 覆寫值。無法讀取資料庫時,它會印出警告,以設定和預設主題寫出頁面,並以 0 結束。 - 每當這些設定或主題變更時,以及每次維護之前,請再次執行,讓前端中的頁面保持最新。
供 LLM 與程式設計代理使用:llms.txt,llms-full.txt, llms-small.txt