このページは英語のページを機械翻訳したものです。内容は英語のページが正です。 英語のページを読む
管理者とロール
最初の管理者の作り方、コマンドラインからのロールの管理、サービス終了の告知と実施、アップロードされた画像の再処理、検索インデックスの再構築、サーバー自身が配信する TLS 証明書の扱い、メンテナンスページの書き出しについて説明します。
- 設定(
host、database、database_url、kekなど)が、設定リファレンスの説明どおりに設定されていること。my config checkで確認できます。 - データベースにスキーマが適用されていること(
my schema apply。database.md を参照してください)。 hostとaccount_domainが確定していること。データベースを使う最初のコマンドがこれらを記録し、以降のコマンドは設定が異なると実行を拒否します(あとから変えられない設定を参照してください)。
管理者を作る
Section titled “管理者を作る”my admin create -username alice -email alice@example.com- 端末から実行すると、コマンドはパスワードを 2 回、画面に表示せずに尋ねます。
- 標準入力が端末でないときは、標準入力の 1 行目がパスワードになります(たとえば
my admin create ... < password.txt)。 パスワードはコマンドライン引数や環境変数では渡せません。これらはプロセス一覧やシェルの履歴に残るためです。 - Cloud Run ジョブのように、単発のコマンドに端末も標準入力もない環境では、
-password-linkを付けます。このときコマンドはパスワードを読まず、誰も知らないランダムなパスワードを設定し、created adminの行のあとにリンクを出力します。このリンクはmy admin account password-reset-linkと同じように、1 時間のあいだ 1 回だけパスワードを設定できます(監査ログにはpassword_reset_link_issuedとして記録されます)。 コマンドの出力を読める人なら誰でもこのリンクを使えます。そうしたプラットフォームでは、リンクが使われるか期限が切れるまで、その出力がプラットフォームのログに残ります。リンクはすぐに開いてください。期限が切れたら、my admin account password-reset-link @aliceでもう一度発行します。リンクの発行に失敗した場合、管理者はすでに作られています。コマンドはそのことを伝えて終了コード 1 で終了し、同じコマンドで新しいリンクを得られます。 - パスワードは 8 文字以上 128 文字以下です。出力、ログ、エラーメッセージには決して表示されません。
- 1 つのトランザクションで、ユーザー、パスワード、メインのメールアドレス、ローカルアカウント(鍵を含む)、そして
adminロールの付与(付与者なし。これは CLI を意味します)を作ります。 組み込みのロールがなければ、先にそれらを作ります。 - 成功すると、コマンドは
created admin @alice@<account_domain> (user <id>, account <id>)を出力し、終了コード 0 で終了します。 - 一人用のサーバーでは、コマンドはアカウントを作らず、終了コード 1 で終了します。 ログインをログインプロバイダーに限定しているあいだは、その限定が終わるまでパスワードではログインできないことも警告します。
もう一度実行する
Section titled “もう一度実行する”- ユーザー名またはメールアドレス(どちらも大文字と小文字を区別しません)がすでに使われているときは、コマンドは何も変えず、どちらが使われているかを出力して、終了コード 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-
権限は 3 つのグループのいずれかに属します。
- モデレーション:
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はグループごとに 1 列を出力します(MODERATION、SERVER、MEMBER)。Web クライアントは最初の 2 つのグループを「モデレーション」と「管理」として表示し、メンバーの機能はどちらにも数えません(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のほかの保持者は、ログインできるあいだだけ数えられます。アカウントを削除したあとや、凍結、BAN、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が送られます。これらはすべてジョブとして実行されるので、ワーカーを止めないでください。 - 確認済みのメールアドレスを持つすべてのユーザーに、告知、日付の変更、取り下げ、終了日の 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は、ローカルアカウントの数、配送先の inbox の数(既知の共有 inbox)、送る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 は何も送りません。ログインとパスワードのリセットはそのまま使えます。 - 終了後、ワーカーはすべてのローカルアカウントのアクターの
Deleteを、連合先に 100 件ずつ配送します(移行したアカウントは最後です)。federation_modeがoffやinboundでも送り、停止中のドメインには決して送りません。my admin closure status(とGET /api/v1/admin/closureのprogress)は、Deleteが記録されたアカウントの数、まだ展開されていない配送の数、状態ごとの配送の数(pending、succeeded、permanent_failure、skipped、dead)を表示します。配送のあいだはワーカーを動かし続けてください。 すべての配送が終わると、10 分ごとに実行される確認がdelivery_completed(監査ログではservice_closure_delivery_completed)を記録し、以降ローカルのアクターは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 “アップロードされた画像の再処理”アップロードされた画像は、それぞれ 3 つのサイズを持ち、アニメーションは動くバージョンも持ちます。my の新しいリリースでこれらのサイズや形式が変わることがあり、既存の画像は再処理するまで今のファイルのままです。
my admin media reprocess -before 2027-01-31T09:00:00Z-beforeには、アップグレードした時刻など、変更の時刻を RFC 3339 で指定します。その時刻より前に最後に処理された画像だけが対象になり、まだ来ていない時刻は拒否されます。- 処理はワーカーが行い、1 分に 100 枚ずつ、1 枚ごとに別のジョブで処理します(ジョブのリファレンスの
media.reprocess_walkとmedia.reprocess)。ワーカーを動かしておいてください。管理画面のジョブのページ(/admin/jobs)でキューを確認できます。 - 同じ時刻でもう一度実行しても安全です。処理済みの画像はそのままで、最初の実行で届かなかった画像が処理されます。
- 元のファイルは保存されていないので、各画像は大きいサイズのバージョンから作り直されます。大きいサイズで失われた細部は戻らず、より後の時刻で実行するたびに画像はもう一度エンコードされ、少しずつ画質が落ちます。変更ごとに 1 回だけ実行してください。
- 動画と音声のファイルは再エンコードされず、そのままです。今の制限では受け付けられない画像は今のバージョンのままになり、ワーカーが警告をログに出します。
画像の新しいバージョンには新しい URL が付きます。古いファイルは media_replaced_retention(既定では 30 日、設定リファレンス)のあいだ残るので、開いているページやキャッシュは動き続けます。その後、1 時間ごとのジョブ 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 として書き出します。
my serve 自体が動けないあいだ(イメージの入れ替え中や、起動しないリビジョンなど)に、ロードバランサー、CDN、リバースプロキシが配信するためのものです。
メンテナンスモードと同じテンプレートを使うので、どちらも同じ文言と見た目になります。
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を指定しないとき)、 テーマのトークンの上書きも読みます。データベースを読めないときは、 警告を出し、設定と既定のテーマからページを書き出して、0 で終了します。- フロントエンドのページを最新に保つため、これらの設定やテーマを変えたときと、メンテナンスの前には毎回もう一度実行してください。
LLM とコーディングエージェント向け:llms.txt,llms-full.txt, llms-small.txt