本页由英文页面机器翻译而来。内容以英文页面为准。 阅读英文页面
用户注册(注册模式、邀请、审批、邮箱确认)
用户如何注册并确认邮箱地址,以及注册模式、邀请码、注册申请的审批、密码重置和注册屏蔽。
从注册到使用应用
Section titled “从注册到使用应用”从图的上方往下:
- 开始。 访客在注册页面(
/auth/sign_up)上用用户名、邮箱地址和密码创建账号;注册仅限登录提供方时,该页面不提供这种方式。或者,访客用某个登录提供方登录,而其在该提供方的账号尚未关联到任何用户;如果该提供方允许注册(-allow-signup),访客会看到同样的表单,只是没有密码栏。 - 依次进行的检查。 注册模式(
closed拒绝所有注册)、每个网络的限制(每 30 分钟 5 次)、CAPTCHA(当captcha不是none时)、注册屏蔽(reject拒绝,require_approval转为等待审批)、邀请码(必须可用,invite模式下必填)、对没有邀请的注册进行审查的signup.check插件,以及用户名和邮箱地址未被占用。未通过检查的注册会被拒绝,表单上会显示错误,并且不会写入任何内容。 - 注册后的状态。 新用户会立即登录。在
open模式下,注册直接获批,mail = none时则等待审批;在approval模式下,注册等待审批,有可用的邀请时则直接获批;在invite模式下,注册直接获批。无论哪种模式,require_approval屏蔽或signup.check的暂缓都会让注册处于等待审批状态。 - 账号可用之前。 等待审批的注册需要审核员批准(
my registration approve或管理页面)。在mail = smtp时,邮箱地址必须通过邮件中的链接确认;登录提供方已验证的地址会立即确认,在mail = none时则不需要确认。被拒绝的注册不会获批,该账号无法使用应用。 - 应用。 可用的账号会进入欢迎步骤(设置昵称和头像),然后进入首页时间线。
以下各节说明每个步骤。
用户在 https://<host>/auth/sign_up 上用用户名、邮箱地址和密码注册,除非注册仅限登录提供方。注册后,该浏览器会立即登录。和登录页面一样,它受 CSRF 令牌和拒绝跨源请求的保护。如果你选择用 CAPTCHA 防范机器人,注册和登录页面会显示其组件,并需要 JavaScript(CAPTCHA)。
注册模式是实例设置 registration_mode。可以用 CLI 选择,也可以在 Web 客户端中“服务器设置”的“注册”页面(/admin/settings/registration)上选择(实例设置)。更改从下一次注册起生效。在服务器宣布关闭期间以及关闭之后,无论设置如何,注册都视为 closed(管理 CLI)。在单人服务器上也是如此:那里同样不提供邀请、注册审查和注册屏蔽,并且没有任何方式可以创建账号,包括 my admin create。
my instance set registration_mode invite| 模式 | 页面 | 注册后的状态 |
|---|---|---|
open |
任何人都可以注册;邀请码可选 | 直接获批;但在 mail = none 时会等待审核员批准(见下文)。邀请不改变任何东西,只记录是谁邀请了该用户 |
approval(默认) |
还会询问“你为什么想加入?”(可选,最多 1,000 个字符);邀请码可选 | 等待审批;有可用的邀请时直接获批 |
invite |
必须填写邀请码 | 直接获批 |
closed |
只显示不接受注册 | 无 |
-
除
closed以外的所有模式下,页面上都有邀请码栏,会从邀请链接(?invite=<code>)中自动填入。无效的邀请码(未知、已撤销、已过期、已用完,或者来自不能再邀请的成员)在所有模式下都会被拒绝而不是被忽略,以免输错的邀请码无人察觉。 -
需要审批的注册屏蔽即使有邀请,也会让注册处于等待审批状态(注册屏蔽)。
-
如果为决策钩子
signup.check设置了插件,没有邀请的注册在通过 CAPTCHA 和屏蔽检查之后,还会由该插件审查,插件可以将其转为等待审批或拒绝。 -
来自同一网络(IP 地址;IPv6 为
/64)的注册限制为每 30 分钟 5 次。超出后,服务器返回带有Retry-After的429。 -
如果用户名或邮箱地址已被占用,页面会在该栏显示错误,并且不会写入任何内容(邀请也不会被消耗)。
-
如果你设置了外部登录提供方(OpenID Connect、GitHub、Discord 或 Mastodon),并允许新用户通过它注册,登录和注册页面会为每个已启用的提供方显示一个按钮,按钮上的名称与你输入的提供方显示名称完全一致(GitHub 提供方显示“使用 GitHub 登录”,Discord 提供方显示“使用 Discord 登录”,以访客的语言显示)。在该提供方的账号尚未关联到本服务器用户的人,会看到同样的注册表单,只是没有密码栏,新用户只能通过该提供方登录。注册模式、邀请码、加入理由、CAPTCHA、注册屏蔽、
signup.check和网络限制都与密码表单一样适用;在closed模式下,或者提供方不允许注册时,登录页面会显示没有关联的账号。提供方标记为已验证的地址(email_verified;GitHub 为已验证的主要地址;Discord 为 Discord 标记为已验证的地址),如果用户保留该地址,会立即确认;其他地址,以及通过 Mastodon 服务器注册的用户的所有地址(Mastodon 不提供地址),按下文通过邮件确认。与现有用户相同的邮箱地址绝不会关联到该用户:表单会显示该地址已被占用。启用了双重验证的用户通过提供方登录后,仍需输入验证码。GitHub 提供方会向 GitHub 请求user:email作用域;如果你列出了允许的 Organization,还会请求read:org,之后服务器在每次登录时都会检查用户是否属于其中之一,不属于则拒绝登录。请把https://<host>/auth/external/<provider ID>/callback注册为你的 GitHub OAuth 应用的回调 URL。Discord 提供方会向 Discord 请求identify和email作用域;如果你列出了允许的服务器,还会请求guilds,之后服务器在每次登录时都会检查用户是否属于其中之一。请在你的 Discord 应用中注册同样的回调 URL。 -
已登录的用户可以在设置的“关联的账号”中关联某个提供方的账号,需要先用密码、通行密钥或另一个已关联的账号确认,并且只限允许关联的提供方。浏览器必须以同一用户登录了登录页面;否则服务器会要求先登录。已被其他用户关联的提供方账号会被拒绝,每个用户在每个提供方最多关联一个账号。用户可以取消关联某个账号,除非它是最后一种登录方式(没有密码、没有通行密钥,也没有其他已关联的账号)。
-
没有密码也没有通行密钥的用户,在进行原本需要它们确认的操作(设置密码、添加通行密钥、删除或迁移账号、关联另一个账号)时,通过在已关联的提供方重新登录来确认。OpenID Connect 提供方会被要求重新验证用户(
max_age=0和prompt=login),之前的验证会被拒绝。该确认只能使用一次,只对该操作有效,期限为 10 分钟;用非关联的账号登录会计为一次错误尝试,与输错密码共用同一个限制。 -
每次注册和登录时,服务器都会记录客户端 IP 地址(登录时还会记录 User-Agent)。这些记录会在 180 天后自动删除(实例设置
session_origins_retention_days和registration_origins_retention_days,至少 90 天)。处于保留冻结状态的账号的记录会被保留(记录保留与冻结)。请在你的隐私政策中写明这一保留期限(隐私政策模板)。
用户何时可以使用应用
Section titled “用户何时可以使用应用”等待审批、被拒绝或尚未确认邮箱地址的用户,仍然可以在登录页面登录。自己停用了账号的用户在账号删除日期之前也可以登录:他们会在那里看到该日期,并可以重新启用或删除账号(审核)。登录后,他们会看到自己在等待什么(审核员批准或邮箱地址确认),或者看到注册未获批准,并且无法继续操作。只有获批的用户才能使用应用(客户端 API 的 OAuth 授权和令牌签发);在要求邮箱确认的配置下,还必须已确认邮箱地址。
能够立即使用应用的新用户,会从注册页面直接进入应用,来到要求设置昵称和头像的欢迎步骤。之后首页时间线会显示入门清单和推荐关注的人(推荐)。在确认邮箱地址的页面上选择“继续”,也会进入同样的欢迎步骤。
用 my admin create 创建的管理员视为已获批并已确认。
设置 mail(配置参考)决定邮件的发送方式。SMTP 示例、DNS 设置以及如何解读投递失败,见发送电子邮件。
mail = smtp:服务器在注册时发送确认邮件。链接有效期为 24 小时,只能使用一次。打开链接会显示一个带有确认按钮的页面,用户按下按钮后地址才会被确认(这样,预先抓取邮件中链接的扫描程序就不会消耗令牌)。登录后,用户每小时最多可以要求重发 3 次邮件。与 SMTP 服务器的连接始终用 STARTTLS 加密,服务器会在验证身份和发送之前校验证书。它从不向不提供 STARTTLS 的服务器发送邮件。mail = none(默认):服务器不发送任何邮件,而是把mail not sent (mail = none)连同消息类别写入服务器日志。只有在profile = development时,该行才会同时包含地址和正文(包括确认链接)。由于邮件永远到不了用户,服务器会改为要求审核员批准,而不是邮箱确认。因此open模式下的注册也会从等待审批开始,未确认的邮箱地址不会妨碍使用应用。
除了这条开发用的日志行之外,确认令牌不会被记录在任何地方(访问日志不记录查询字符串)。数据库只存储令牌的 SHA-256。
注册仅限登录提供方
Section titled “注册仅限登录提供方”当实例设置 login_providers_only 开启且至少启用了一个登录提供方时,注册页面没有密码表单,只提供允许注册的提供方;链接中的邀请码会带到提供方的注册表单中。无论表单中填写了什么,用密码注册都会被拒绝。如果没有允许注册的提供方,注册视为 closed。如果没有已启用的提供方,该设置不生效。
密码重置与更改
Section titled “密码重置与更改”当实例设置 login_providers_only 生效时,重置链接以及设置或更改密码都会被拒绝(该限制的作用)。
mail = smtp:用户在登录页面的“忘记密码?”中输入邮箱地址后,服务器会向以该地址为主要地址的用户发送设置新密码的链接。无论账号是否存在,页面的回答都相同。链接有效期为 1 小时,只能使用一次;如果在此期间密码通过其他途径更改,链接就会失效。请求限制为每个客户端 IP 地址每 30 分钟 5 次,邮件限制为每个地址每小时 3 封(超出限制的请求不会发送任何内容,但得到同样的回答)。启用 CAPTCHA 时,该表单也会经过验证。mail = none:页面会说明无法发送链接,并让用户联系管理员。管理员在管理页面中该账号的“管理”页面上,或者用my admin account password-reset-link @alice签发链接,再交给用户(审核)。- 已登录的用户可以在设置的“密码”中输入当前密码来更改密码(每个用户每小时最多输错 5 次)。
- 重置或更改密码会撤销该用户的其他会话和应用令牌(在设置中更改时,只保留进行更改的那个应用)。通行密钥和双重验证保持不变。等待输入双重验证码的登录,以及尚未完成的应用授权,也会失效:用户需要重新开始。在
mail = smtp时,服务器还会给用户发邮件,告知密码已更改。
邀请在 open、approval 和 invite 模式下有效。工作人员的邀请通过下面的 CLI、审核界面和管理员 API 创建;成员也可以创建自己的邀请(成员邀请)。在 closed 模式下,无法创建邀请,也没有任何邀请有效。
my invite create # single use, expires in 7 daysmy invite create -max-uses 10 -expires-in 72hmy invite create -max-uses 0 -expires-in 0 # no limit on uses or timemy invite list # newest first; states: usable / revoked / expired / used upmy invite revoke <code>create会输出邀请码(16 个字符),以及已填入该邀请码的注册页面链接(https://<host>/auth/sign_up?invite=<code>)。- 邀请码匹配时忽略大小写、空格和连字符。
- 即使多人同时注册,邀请码也绝不会被使用超过其限制(
invite_redemptions上有唯一约束)。 - 已撤销、已过期或已用完的邀请码都会给出相同的错误(邀请不可用)。
- 除了 CLI,你还可以在 Web 客户端的审核界面(“邀请”,
/moderation/invites)以及通过客户端 API(GET/POST /api/v1/admin/invites和POST /api/v1/admin/invites/{id}/revoke)创建、列出和撤销邀请。两者都需要角色权限manage_invites(内置的moderator没有该权限,所以若要委派这件事,请创建一个带有该权限的角色并授予它)。自行发放邀请的服务会使用范围为admin:manage_invites的令牌调用同一个 API(让另一个服务使用管理员 API)。列表上的“创建邀请”会打开表单(/moderation/invites/new),其中会显示新邀请的邀请码和注册链接。列表会显示每个邀请的邀请码、创建者、有多少人用它注册、截止时间和状态;选中邀请后选择“撤销”,会先要求确认。 - 列表会显示每一个邀请,包括工作人员的和成员的,以及谁创建了它(
created_by)和创建方式(creator_kind:staff或member)。拥有manage_invites的人可以撤销其中任何一个。 - 审核界面中账号的审查页面(
GET /api/v1/admin/accounts/{id},权限manage_accounts)会显示该账号注册时使用的邀请,以及谁创建了它,也就是邀请该用户的人。 - 无论是从界面、API 还是 CLI,创建和撤销邀请都会记录在审计日志中(
invite_created、invite_revoked)。目标名称是邀请码的前 4 个字符(ABCD…);完整的邀请码不会复制到审计日志中。撤销已经撤销的邀请不会改变任何内容,因此不会记录。
除工作人员外,成员也可以创建自己的邀请。谁可以创建由实例设置 invite_creators 决定(实例设置):
permitted(默认):只有角色拥有create_invites权限的用户。默认只有内置的admin角色拥有该权限。你可以把它加到手动授予的角色中,或者加到支持者方案的角色中,让支持者可以邀请他人。everyone:所有已登录的本站用户。
无论哪种方式,账号被封禁或受限、或者注册未获批准的用户都无法创建邀请;注册模式为 closed 时,任何人都无法创建。拥有 manage_invites 的人仍可以继续创建工作人员的邀请,下文的限制都不适用于这些邀请。
成员可以在 Web 客户端的设置(“邀请”,/settings/invites)中,或者通过客户端 API(GET / POST /api/v1/invites 和 POST /api/v1/invites/{id}/revoke),创建、列出和撤销自己的邀请,并复制可用邀请的链接。设置中只会为当前可以创建邀请的用户列出该页面;不能再创建邀请的用户仍可以通过地址打开它,页面会说明原因,用户可以在那里撤销自己创建的邀请。列表会显示每个邀请是可用、已撤销、已过期、已用完,还是因为创建者不能再邀请而不可用。
以下限制同样是实例设置,只适用于成员邀请。管理员可以在服务器设置的“注册”页面(/admin/settings/registration)上的“成员邀请”中更改它们以及 invite_creators:
| 设置 | 含义 | 默认值 | 范围 |
|---|---|---|---|
member_invite_max_active |
一名成员同时可以持有多少个可用的邀请(未撤销、未过期、未用完) | 5 |
0-100(0:成员无法创建邀请) |
member_invite_max_uses |
一个邀请最多可供多少人注册 | 10 |
1-1,000 |
member_invite_max_lifetime_seconds |
一个邀请最长有效多久,以秒为单位 | 2592000(30 天) |
3,600(1 小时)到 31,536,000(365 天) |
- 成员在限制范围内选择使用次数和有效期;不选择时,邀请允许 1 次注册,有效期 7 天(限制更低时则更短)。无法创建没有使用次数或时间限制的邀请。
- 降低限制不会改变现有的邀请;它从下一个创建的邀请起生效。
- 每次使用成员邀请注册时,都会检查其创建者是否仍能创建邀请。如果创建者失去了
create_invites(例如其方案到期)、invite_creators改回了permitted,或者账号被封禁、受限或删除,该邀请就会失效,注册页面会显示它无效。邀请本身不会被更改,因此在有效期内,当创建者重新可以邀请时,它会再次生效。 - 成员的创建和撤销会以
invite_created和invite_revoked记录在审计日志中,执行者为该成员。
在 approval 模式下,可用的邀请会让新用户直接获批:邀请人代替了审核员的审查。因此在 invite_creators = everyone 时,每个用户都可以不经审查放人进来,这会削弱审批模式的作用。如果你依赖审查,请保持 permitted,并只把 create_invites 授予你信任的人,或者把 member_invite_max_active 和 member_invite_max_uses 设得较低。
my registration list # waiting for approval (longest wait first); shows the reason and whether the email is confirmedmy registration list -state rejectedmy registration approve alicemy registration reject -note "spam" bob- 参数是本站账号的用户名(开头的
@可以省略)。 - 只能对等待审批的注册作出决定。对于已作出决定的注册,或者不经注册页面创建的用户(
my admin create),命令不会改变任何东西,并以代码 1 退出。 - 退出代码 2 表示参数错误。
同样的决定也可以在管理页面(客户端 API)中作出。所有操作都需要 manage_accounts 权限。
在 Web 客户端中,“审核 → 注册”(/moderation/registrations)会列出等待审批的注册,以及它们的邮箱地址、是否已确认和加入理由;选中它们后选择“批准”或“拒绝”,会先要求确认,并可以给审核员留下备注。单人服务器不显示该页面。
| 操作 | 作用 |
|---|---|
GET /api/v1/admin/registrations |
等待审批的注册(等待最久的在前)。返回注册的 ID、加入理由、邮箱地址及其是否已确认,以及本站账号 |
POST /api/v1/admin/registrations/{id}/approve |
批准。正文 {"note": "..."} 可选。回答中以 decision_note 显示备注;对已作出决定的注册,回答中不含邮箱地址 |
POST /api/v1/admin/registrations/{id}/reject |
拒绝。正文与 approve 相同 |
- 这与 CLI 是同一个用例,会把决定记录在
registration_decisions和审计日志中(registration_approved、registration_rejected)。CLI 作出的决定,执行者为cli;API 作出的决定,执行者为作出决定的审核员。 - 对已作出决定的注册再次作出决定不会改变任何东西,并返回当前状态(如果两个人同时作出决定,只会记录一个)。不经注册页面创建的用户返回 404。
屏蔽规则按邮箱域名、邮箱地址或 IP 范围,拒绝来自注册页面的注册,或者将其转为需要审批。
my admin signup-block create -kind email_domain spam.example # also applies to subdomains; a U-label works toomy admin signup-block create -kind ip_range -severity require_approval -duration 720h 192.0.2.0/24my admin signup-block create -kind email_hash spammer@example.com # only a hash of the address is keptmy admin signup-block list -activemy admin signup-block lift <block id>- 匹配
-severity reject(默认)屏蔽规则的注册会被拒绝;匹配require_approval的注册无论注册模式如何,都会从等待审批开始。多条规则匹配时,适用更严格的那条。注册页面不会显示拒绝的原因。 email_hash与转为小写、并去掉本地部分中从第一个+起的部分后的地址进行匹配。IP 范围与注册 IP(与registration_origins相同的值)进行匹配,对 IP 未知的注册从不适用。- 已过期和已解除的屏蔽规则不起作用。添加和解除都会记录在审计日志中(
signup_block_added、signup_block_lifted)。 - 用
-block-email(API 中为block_email: true)封禁本站账号时,服务器还会为该用户的邮箱地址创建一条email_hash屏蔽规则。
对于有数千个条目的列表(例如一次性邮箱服务的域名),可以用 import 从文件批量添加(- 表示标准输入)。所有值都使用相同的种类、严重程度、备注和期限。
my admin signup-block import -kind email_domain -comment "disposable email" disposable.txt- 列表每行一个值(与
add的<value>形式相同),或者是第一列为值的 CSV 行。空行和以#开头的行会被跳过。一次导入最多 10,000 个条目。 - 命令会输出添加了多少条,并对每个未添加的行输出行号、值和原因。原因有
invalid(不是该种类的有效值)、duplicate(与同一列表中较早的行规范形式相同)或already_blocked(已有相同种类和值、且同等或更严格的屏蔽规则生效)。 - 每条添加的屏蔽规则都会和
add一样记录在审计日志中(signup_block_added),并且可以逐条解除。 - 导入以每几百条为一个事务写入,因此中途失败时,之前添加的内容会保留。再次导入同一个列表只会添加剩余的部分。
- 本软件不附带任何列表,也不会定期从 URL 获取列表。公开列表(例如 GitHub 上的 disposable-email-domains)需要你自己获取和更新,并再次导入更新后的列表。
同样的操作也可以在管理页面(客户端 API)中进行。所有操作都需要 manage_accounts 权限。在 Web 客户端中,打开“审核”→“注册屏蔽”(/moderation/signup-blocks)。列表显示每条屏蔽规则的值、种类、状态和结束时间,可以只看生效中的或查看全部;“添加屏蔽规则”会打开表单(/moderation/signup-blocks/new),“从列表添加”会导入列表并显示跳过的行(/moderation/signup-blocks/import),选择某个值会打开该屏蔽规则的页面,显示其效果和备注,在那里选择“解除”即可结束它。
| 操作 | 作用 |
|---|---|
GET /api/v1/admin/signup_blocks |
列出屏蔽规则(最新的在前)。可以用 kind 和 active 筛选 |
POST /api/v1/admin/signup_blocks |
添加屏蔽规则。正文包含 kind、value、severity、comment 和 expires_in(秒,最长十年) |
POST /api/v1/admin/signup_blocks/import |
从列表添加屏蔽规则。正文包含 kind、text(列表)、severity、comment 和 expires_in。响应包含 added(添加的数量)和 skipped(未添加的行:line、value、reason) |
GET /api/v1/admin/signup_blocks/{id} |
返回一条屏蔽规则 |
POST /api/v1/admin/signup_blocks/{id}/lift |
解除屏蔽规则。已解除的屏蔽规则保持原样 |
供 LLM 和编程智能体使用:llms.txt,llms-full.txt, llms-small.txt