Esta página é uma tradução automática da página em inglês, que é a versão de referência. Ler a página em inglês
Administradores e papéis
Como criar o primeiro administrador, gerenciar papéis pela linha de comando, anunciar e realizar o encerramento do serviço, processar de novo as imagens enviadas, reconstruir o índice de busca, tratar os certificados TLS que o próprio servidor serve e exportar a página de manutenção.
Pré-requisitos
Seção intitulada “Pré-requisitos”- A configuração (
host,database,database_url,keke assim por diante) é definida como descreve a referência de configuração.my config checkverifica essa configuração. - O schema é aplicado ao banco de dados (
my schema apply; veja database.md). hosteaccount_domainsão definitivos. O primeiro comando que usa o banco de dados os registra, e todo comando posterior se recusa a executar quando a configuração é diferente (veja Configurações que não podem ser mudadas depois).
Criando um administrador
Seção intitulada “Criando um administrador”my admin create -username alice -email alice@example.com- Em um terminal, o comando pede a senha duas vezes, sem exibi-la.
- Quando a entrada padrão não é um terminal, a primeira linha da entrada padrão é a senha (por exemplo
my admin create ... < password.txt). A senha não pode ser passada como argumento de linha de comando nem como variável de ambiente, porque ambos vão parar em listas de processos e no histórico do shell. - Onde um comando avulso não tem nem terminal nem entrada padrão, como um job do Cloud Run, adicione
-password-link. O comando então não lê senha: ele define uma aleatória que ninguém conhece e imprime um link depois da linhacreated admin, que define a senha uma vez, por uma hora, comomy admin account password-reset-link(o log de auditoria o registra comopassword_reset_link_issued). Quem puder ler a saída do comando pode usar o link, e em uma plataforma assim essa saída fica nos logs da plataforma até o link ser usado ou expirar. Abra o link logo. Se ele expirar, emita outro commy admin account password-reset-link @alice. Se a emissão do link falhar, o administrador já existe: o comando diz isso e termina com o código 1, e o mesmo comando dá um novo link. - Uma senha tem de 8 a 128 caracteres. Ela nunca aparece na saída, nos logs nem em uma mensagem de erro.
- Uma transação cria o usuário, a senha, o endereço de e-mail principal, a conta local (com as chaves dela) e a concessão do papel
admin(sem concedente, o que significa a CLI). Os papéis embutidos são criados antes se estiverem faltando. - Em caso de sucesso, o comando imprime
created admin @alice@<account_domain> (user <id>, account <id>)e termina com o código 0. - Em um servidor de uma só pessoa, o comando não cria nenhuma conta e termina com o código 1. Enquanto o login está limitado a provedores de login, ele também avisa que a senha não pode entrar até o limite terminar.
Executando de novo
Seção intitulada “Executando de novo”- Quando o nome de usuário ou o endereço de e-mail (ambos sem distinção de maiúsculas e minúsculas) já está em uso, o comando não altera nada, informa qual deles está em uso e encerra com código 1. Ele nunca altera a senha nem as funções do usuário existente.
- Uma execução que falha não grava nada, então você pode corrigir a causa e executar o mesmo comando de novo.
- O código de saída 2 significa erro de uso.
Concedendo e revogando papéis
Seção intitulada “Concedendo e revogando papéis”Os papéis guardam permissões. Os papéis embutidos são admin (position 1000, todas as permissões) e
moderator (position 100, com manage_reports, manage_accounts e view_audit).
my serve verifica os papéis embutidos toda vez que inicia (em um processo de qualquer role), e my admin role os verifica toda vez que executa.
Cada um cria o que falta e dá ao admin todas as permissões da versão em execução.
Quando uma atualização adiciona uma permissão, nenhuma etapa manual é necessária. Um moderator mantém as permissões e a posição que o administrador definiu.
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-
As permissões pertencem a um de três grupos.
- Moderação:
manage_reports,manage_accounts,manage_domains,manage_invites,view_audit. - Administração do servidor:
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. - Recursos de membros:
view_finance,create_custom_emojis,start_voice_rooms,create_invites,keep_posts_longer,create_articles,create_events.
listimprime uma coluna por grupo (MODERATION,SERVER,MEMBER). O cliente web mostra “Moderação” e “Administração” para os dois primeiros grupos e não conta os recursos de membros em nenhum deles (veja moderation.md). - Moderação:
-
Uma mudança vale a partir da próxima requisição do usuário. As notificações para moderadores vão para as pessoas que têm a permissão quando a notificação é criada.
-
Concessões e revogações são gravadas no log de auditoria como
role_grantederole_revoked(tipo de alvorole). O autor de uma operação da CLI écli(my admin audit list -target-kind role). -
Conceder um papel que o usuário já tem, ou revogar um que ele não tem, não muda nem registra nada.
-
O último titular de
adminnão pode perdê-lo (código de saída 1). Concedaadmina outro usuário antes. -
A tela de administração “Papéis” (
/admin/roles) lista todos os papéis e os cria, altera e exclui: a página de um papel define a posição, as permissões e o selo dele. Ela oferece apenas o que as regras abaixo permitem: uma posição não maior que o seu papel mais alto, as permissões que você tem (as outras que um papel tem são nomeadas e mantidas), apenas o selo deadmine nenhuma exclusão deadminoumoderator. Excluir um papel pede que você digite o nome dele. Os papéis de um plano são definidos pelo plano. -
A API de administração é
GET /api/v1/admin/roles,GET /api/v1/admin/accounts/{id}/rolesePUT/DELETE /api/v1/admin/accounts/{id}/roles/{role}, e ela exige a permissãomanage_roles. Pela API, você não pode conceder nem revogar um papel acima da maiorpositionentre os seus papéis (403). Revogar o últimoadminretorna 409. -
A equipe age apenas sobre postos mais baixos. Pela API, as ações de moderação e o levantamento delas, a decisão de contestações, o levantamento de supressões de e-mail, a revelação de dados privados de uma conta, a emissão de um link de redefinição de senha e a remoção da autenticação em dois fatores exigem que a maior
positionentre os seus papéis esteja acima a de todos os papéis do alvo; um posto mais alto ou igual, a sua própria conta inclusive, retorna 403. Um moderador não pode agir sobre um administrador, e um administrador não pode agir sobre outro. Estes comandos (my admin account ...) não têm esse limite, então use-os quando os administradores discordarem. -
O único administrador não pode ser bloqueado nem removido:
disable_login,suspendebansobre ele são recusados, pela API (409) e por estes comandos (código de saída 1), e ele não pode excluir a própria conta (409). Outro titular deadminsó conta enquanto pode entrar: não depois de excluir a conta, nem enquanto suspenso, banido ou sobdisable_login.
Anunciando o fim do serviço
Seção intitulada “Anunciando o fim do serviço”Para encerrar o servidor, anuncie o encerramento primeiro. service-closure.md descreve o procedimento completo, do anúncio à exclusão dos dados.
O servidor continua funcionando normalmente durante o anúncio. closure em GET /api/v1/instance e metadata.serviceClosure no NodeInfo mostram o estado e as datas.
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-atnão tem limite inferior.-export-until(o prazo para retirar dados) deve ser igual ou posterior a-closes-at, e o padrão é 30 dias após a data de encerramento.- Quando a data de encerramento está a menos de 30 dias, o comando imprime um aviso na saída de erro padrão (o anúncio é gravado mesmo assim).
- Alterar as datas é registrado como um novo anúncio, e um anúncio feito após uma retirada também é um novo anúncio. Depois que o servidor é encerrado, você não pode anunciar nem retirar o anúncio (código de saída 1).
- Anunciar, alterar as datas e retirar o anúncio são gravados no registro de auditoria como
service_closure_announcedeservice_closure_withdrawn(tipo de alvoinstance; vejamy admin audit list -target-kind instance). - A API administrativa é
GET /api/v1/admin/closure,PUT/DELETE /api/v1/admin/closure/announcement,GET /api/v1/admin/closure/checkePOST /api/v1/admin/closure/close. Ela exige a permissãomanage_service_closure(entre as funções integradas, sóadmina tem). - Durante o anúncio, o servidor não aceita novos usuários nem novos pagamentos.
- O modo de registro efetivo é
closed(o valor deregistration_modenão muda, e volta a valer quando o anúncio é retirado). Nem cadastros nem cadastros com convite funcionam, e as solicitações pendentes não podem ser aprovadas (409). - Anunciar rejeita todas as solicitações pendentes (registradas como decididas por
service_closure) e cancela todas as assinaturas de apoiador em andamento ao fim do período. Os assinantes recebem uma notificação (supporter_service_closure) e um e-mail. Novas assinaturas retornam409. Retirar o anúncio não desfaz as rejeições nem os cancelamentos. - Cada anúncio, alteração de datas e retirada envia a notificação
service_closurea todos os usuários locais. Tudo isso roda como jobs, então não pare o worker. - Cada usuário com endereço de e-mail confirmado recebe um e-mail pelo anúncio, por uma alteração de datas, pela retirada, 7 dias e 1 dia antes da data de encerramento, pelo encerramento e 7 dias antes do prazo de exportação. Os usuários não podem optar por não receber (veja email.md).
- Após a data de encerramento, as pessoas que têm
manage_service_closurerecebem a notificaçãoadmin_service_closure_due. O servidor não se encerra sozinho.
- O modo de registro efetivo é
Após a data de encerramento, encerre o servidor. O encerramento não pode ser desfeito.
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 answeringcheckeclosemostram o número de contas locais, o número de caixas de entrada de destino (as caixas compartilhadas conhecidas), uma estimativa das atividadesDeletea enviar (o produto desses dois números), o número de assinaturas de apoiador em andamento, o número de migrações não concluídas (Move) e o número de contas sob retenção (retention_holds). Quando restam migrações ou há uma retenção, o comando emite um aviso na saída de erro padrão. Exporte os registros das contas sob retenção commy admin account export-moderatione guarde-os antes de descartar os dados.closerecusa sem perguntar quando não há anúncio e antes da data de encerramento (código de saída 1). Qualquer resposta diferente dey, ou uma entrada diferente do domínio do servidor (hostna configuração, sem distinção de maiúsculas e minúsculas), não altera nada e encerra com código 1.- O encerramento é gravado no registro de auditoria como
service_closure_closed. Na mesma transação, ele encerra todas as assinaturas de apoiador em andamento (motivoservice_closed) e enfileira os jobs que cancelam as assinaturas no provedor de pagamento imediatamente (CancelNow). - Após o encerramento, a API cliente aceita apenas estas requisições: ler a própria conta e as configurações, as exportações (
/exports,/csv_exports), as sessões (/sessions,/authorized_apps),GET /instancee a administração do encerramento e da fila de jobs. Todo o resto é recusado com403(/api/v1/problems/service-closed). Os streams param, e o Web Push não envia nada. Entrar e redefinir a senha continuam funcionando. - Após o encerramento, o worker entrega um
Deletedo ator de cada conta local aos pares da federação, 100 por vez (as contas migradas por último). Ele envia mesmo quandofederation_modeéoffouinbound, e nunca para um domínio suspenso.my admin closure status(eprogressemGET /api/v1/admin/closure) mostra quantas contas têm umDeleteregistrado, quantas entregas ainda faltam expandir e o número de entregas em cada estado (pending,succeeded,permanent_failure,skipped,dead). Mantenha o worker em execução durante a entrega. Quando todas as entregas terminam, uma verificação que roda a cada 10 minutos registradelivery_completed(service_closure_delivery_completedno registro de auditoria), e os atores locais passam a responder410. O servidor não executa de novo as entregasdeadpor conta própria; execute-as de novo commy job retry.
Depois do prazo de exportação, gere a página de encerramento estática que o seu domínio serve depois que o servidor é parado. O comando lê o banco de dados, então execute-o antes de descartar o banco de dados.
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- Saída:
<dir>/<locale>.htmlpara cada idioma e<dir>/index.htmlcom todos os idiomas um após o outro. As páginas usam o mesmo modelo demy maintenance exporte mostram o nome do servidor, a data de encerramento, a mensagem do operador no anúncio estatus_page_url. A saída também traz exemplos de configuração para o front end:nginx.conf,Caddyfileecloudfront-function.js. Eles respondem410para/ap/*,/inbox, WebFinger, host-meta, NodeInfo e/@*, e servem a página de encerramento para todo o resto. - O comando recusa (código de saída 1) a menos que o servidor esteja encerrado. Antes de
delivery_completed, ele imprime um aviso e ainda grava as páginas. service-closure.md descreve como trocar o front end pela página estática.
Processando de novo as imagens enviadas
Seção intitulada “Processando de novo as imagens enviadas”Cada imagem enviada mantém três tamanhos, e uma animação também mantém as suas versões em movimento. Uma nova versão de my pode mudar esses tamanhos ou formatos, e uma imagem existente mantém os seus arquivos até ser processada de novo:
my admin media reprocess -before 2027-01-31T09:00:00Z-beforerecebe o momento da mudança, como a hora em que você atualizou, no formato RFC 3339. Só são tratadas as imagens processadas pela última vez antes desse momento, e um horário que ainda não passou é recusado.- O worker faz o trabalho, 100 imagens por minuto, cada uma em um job próprio (
media.reprocess_walkemedia.reprocessna referência de jobs). Mantenha um worker em execução; a página de jobs administrativa (/admin/jobs) mostra a fila. - Executar de novo com o mesmo horário é seguro. As imagens já processadas são deixadas como estão, e as que a primeira execução não alcançou são tratadas.
- Os originais não são mantidos, então cada imagem é refeita a partir da sua versão grande. Detalhes que a versão grande perdeu não voltam, e cada execução com um horário posterior recodifica as imagens mais uma vez e perde um pouco de qualidade. Execute uma vez por mudança.
- Vídeos e áudios não são recodificados e ficam como estão. Uma imagem que os limites atuais não aceitam mais mantém a versão atual, e o worker registra um aviso.
A nova versão de uma imagem tem novas URLs. Os arquivos antigos permanecem por media_replaced_retention (30 dias por padrão, referência de configuração), para que as páginas abertas e os caches continuem funcionando, e depois o job horário media.purge_replaced os exclui. Outros servidores não são avisados das novas URLs: um servidor que ainda tenha uma URL antiga e não tenha cópia própria deixa de mostrar a imagem depois desse prazo. Reserve espaço extra de armazenamento até que os arquivos antigos sejam removidos.
Reconstruindo o índice de busca
Seção intitulada “Reconstruindo o índice de busca”my search cuida do índice da busca de texto completo das publicações, em um servidor com mecanismo de busca. Com search = none, cada comando informa isso, não faz nada e encerra com código 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 rebuildExecute my search rebuild de novo para retomar uma reconstrução que parou. Ela continua a partir da última publicação tratada e não esvazia o índice de novo. Enquanto uma reconstrução estiver incompleta, o outro modo é recusado com código de saída 1. Busca de texto completo das publicações explica quando usar cada um.
Certificados TLS
Seção intitulada “Certificados TLS”my tls trata os certificados de um servidor que serve HTTPS por conta própria (tls = acme ou tls = files; veja
Servindo HTTPS pelo servidor).
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 certificatestatusmostra, para cada host, o certificado atual (número de série, emissor, validade), quando ele é renovado, quantos pedidos seguidos não obtiveram certificado e os últimos pedidos com seus erros. Comtls = filesele mostra o certificado detls_cert_file; comtls = offele diz isso.renewerevokeexigemtls = acme, o servidor em execução (ele responde às verificações da autoridade certificadora) e umkvdiferente dememory. Eles terminam com o código 1 quando falham, quando outro processo está pedindo o certificado do host naquele momento, e comtls = filesoutls = off.-reasonékey_compromisequando a chave privada pode ser conhecida por outros, caso contráriosupersededouoperator.revoketermina com o código 0 e imprime um aviso quando revogou o certificado, mas não conseguiu pedir o substituto dele.
Comandos e métricas explica o que cada um faz com os processos em execução.
Exportando a página de manutenção
Seção intitulada “Exportando a página de manutenção”my maintenance export grava a página do modo de manutenção como HTML estático,
para um balanceador de carga, uma CDN ou um proxy reverso servir enquanto o próprio my serve não pode executar (uma imagem sendo substituída, uma revisão que não inicia).
Ele usa o mesmo modelo do modo de manutenção, então os dois mostram as mesmas palavras e a mesma aparência.
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- Saída:
<dir>/<locale>.htmlpara cada locale de-lang, para front-ends que escolhem uma página porAccept-Language, e<dir>/index.htmlcom todos os locales em sequência, para os que não conseguem. As páginas têm CSS inline, nenhum script e nenhum recurso externo; a Content-Security-Policy delas fica em um elemento<meta>. - Palavras: as configurações
maintenance_server_name,maintenance_message,maintenance_untilestatus_page_url(referência de configuração). - Sem
-offline, ele também lê o nome da instância (quandomaintenance_server_namenão está definido), o locale padrão dela (quando-langnão é informado) e as substituições de tokens do tema publicado. Quando o banco de dados não pode ser lido, ele imprime um aviso, grava as páginas a partir da configuração e do tema padrão e termina com 0. - Execute-o de novo sempre que essas configurações ou o tema mudarem, e antes de cada manutenção, para que as páginas no front-end continuem atuais.
Para LLMs e agentes de programação:llms.txt,llms-full.txt, llms-small.txt