wholetrans/docs-mastodon
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update zh-cn translations

Browse source
This commit is contained in:
CDN 2025-04-06 03:29:30 +08:00
parent 5e2b739ee1
commit a939c23559
Signed by: CDN
GPG key ID: 0C656827F9F80080
168 changed files with 36955 additions and 1406 deletions
Download patch file Download diff file Expand all files Collapse all files

102
content/zh-cn/_index.md
View file

@ -1,106 +1,106 @@
---
title: 什么是Mastodon？
description: 欢迎来到Mastodon文档！
title: 什么是 Mastodon？
description: 欢迎阅读 Mastodon 文档！
menu:
docs:
weight: -99
---
## 什么是微博客？ {#microblogging}
## 什么是微博？{#microblogging}
类似于发布博客是将更新发布到网站上，**发布微博客**是将小的更新发布到你的个人信息流。你可以发布文本，也可以附加图片、音频、视频等媒体，或是发起投票。Mastodon可以让你发现并关注新的朋友们。
博客（blogging）是在网站上发布更新的行为。与之类似，**微博（microblogging）**则是在你的个人主页信息流中发布简短更新的行为。你可以发布纯文本贴文，也可以选择性地附上图片、音频、视频或投票等媒体。Mastodon 让你可以关注旧朋友并发现新朋友。
## 什么是联邦？ {#federation}
## 什么是联合？{#federation}
**联邦**是去中心化的一种形式。在联邦中，不是所有人共同使用一个中心服务，而是使用多个不限人数的服务器。
**联合**是去中心化的一种形式。它并非由单一的中央服务机构提供服务供所有人使用，而是存在多个服务，任何人都可以使用其中的任意一个。
| 中心化等级 | 示例 |
| 中心化程度 | 示例 |
| :--- | :--- |
| 中心化 | Twitter, Facebook, Instagram |
| 联邦式 | 电子邮件, XMPP, 电话网络, 邮政服务 |
| 分布式 | BitTorrent, IPFS, Scuttlebutt |
| 中心化 | Twitter、Facebook、Instagram |
| 联合式 | 电子邮件、XMPP、电话网络、实体邮件 |
| 分布式 | BitTorrent、IPFS、Scuttlebutt |
Mastodon站点可以独立运作。和传统网站一样，人们可以在上面注册、发布消息、上传图片、互相聊天。但与传统网站*不同*的是，Mastodon网站之间可以互动，让跨站用户互相交流，就好像只要你知道他们的电子邮件地址，你就可以从你的Gmail帐户发送电子邮件给使用Outlook、Fastmail、Protonmail或任何其他电子邮件供应商的用户。在Mastodon里，**你可以对任何人在任何网站上的地址进行“@”或私信**。
一个 Mastodon 站点可以像传统网站一样独立运行。人们可以在上面注册、发帖、上传图片以及相互交流。与传统网站*不同*的是，Mastodon 网站之间可以互通，不同站点的用户能够互相交流；就像你可以从 Gmail 账户向 Outlook、Fastmail、Protonmail 或任何其他电子邮件提供商的用户发送邮件一样，只要你知道对方的电子邮件地址，**你就可以使用任何网站上任何用户的地址来提及或私信他们**。
{{< figure src="assets/network-models.jpg" caption="上图从左到右依次为：集中式、联邦式、分布式" >}}
{{< figure src="assets/network-models.jpg" caption="从左到右：中心化、联合式、分布式" >}}
## ActivityPub是什么？ {#fediverse}
## 什么是 ActivityPub？{#fediverse}
Mastodon使用一种标准化的、开放的协议来实现站点之间的互动，这种协议叫做**ActivityPub**。任何通过ActivityPub实现互联的软件都可以与Mastodon无缝通信，就像Mastodon站点之间的通信一样。
Mastodon 使用一个标准化的开放协议来实现联合。这个协议叫做 **ActivityPub**。任何同样通过 ActivityPub 实现联合的软件都可以与 Mastodon 无缝通信，就像 Mastodon 网站之间可以互相通信一样。
**联邦宇宙**（fediverse）是所有可以通过ActivityPub和互联网互相交流的网站的统称。这包括所有Mastodon服务器，但也包括其他的一些实现：
**联邦宇宙**（“Fediverse”）是所有能够通过 ActivityPub 和互联网相互通信的网站的总称。这包括所有的 Mastodon 站点，也包括其它实现此协议的应用：
* Pleroma：一个模块化的微博客引擎
* Pixelfed：联邦式的图片分享平台，它可以让你分享和阅读媒体嘟文
* Misskey：包括一个可自定义界面的微博客
* PeerTube：它可以让你上传视频到频道
* Plume：它可以用来发布长篇文章
* 还有更多，包括许多个人网站！
- Pleroma，一个模块化的微博引擎
- Pixelfed，联合式的图片分享平台，允许你分享和浏览媒体贴文
- Misskey，除微博功能外，还提供可定制的仪表盘
- PeerTube，允许你将视频上传到频道
- Plume，允许你发布篇幅更长的文章
- 还有更多，包括独立站点和私人网站！
**联邦宇宙**没有自己的所谓品牌，所以你可能更常听到“来关注我的Mastodon吧”而不是“来关注我的联邦宇宙吧”。虽说从技术上讲，后者的说法更准确。
联邦宇宙本身没有统一的品牌标识，所以你可能更常听到“在 Mastodon 上关注我”，而不是“在联邦宇宙关注我”，但严格来说，后者更准确。
## 实际影响因素 {#implications}
## 实际影响 {#implications}
### 选择合适的服务提供者与用户政策 {#choice}
### 服务提供者和政策的选择 {#choice}
因为Mastodon只是可以用于驱动任何网站的软件，Mastodon的潜在用户拥有选择服务提供者的权利，用户可以从现有Mastodon站点中选择，或者如果用户愿意的话，也可以创建自己的Mastodon站点。Mastodon项目在 [joinmastodon.org](https://joinmastodon.org) 上维护了一个推荐服务提供者列表，该列表可按类别和/或语言进行排序。一些站点可能有额外的管理政策，例如要求对潜在敏感内容打上特定标签，另一些站点可能有更加宽松的管理政策，但是所有在列表中列出的站点均需遵守[《Mastodon服务器公约》](https://joinmastodon.org/covenant)，这意味着他们承诺积极处理并反对仇恨言论、每日进行备份、至少有一个应急管理员、关站前至少提前3个月发布关站通告。
Mastodon 仅仅是一款可以驱动任何网站的软件，Mastodon 的潜在用户可以选择一个已有的 Mastodon 网站作为服务提供者，或者如果他们愿意，也可以创建自己的 Mastodon 网站。Mastodon 项目在 [joinmastodon.org](https://joinmastodon.org) 维护了一个推荐的服务提供者列表，可按类别和/或语言排序。有些网站的审核政策可能比其它站点更严格，例如要求对潜在的敏感内容使用特定标签；而有些网站的审核政策可能更为宽松，但列表中的网站都同意遵守 [Mastodon 站点公约](https://joinmastodon.org/covenant)，这意味着它们承诺积极审核仇恨言论、每日进行数据备份、至少配备一名紧急管理员，并在关闭服务前至少提前 3 个月通知用户。
> 维护一个让所有成员都感到安全的社区并不容易。Mastodon提供了很多基础性的框架和工具来完成这件事，并将改变的权力从一个商业实体转移到社区自己手中。
> 维护让所有成员都感到安全的社区并非易事。Mastodon 为此提供了大量基础框架和工具，并将实现变革的力量从单一的商业实体转移到了社区自身手中。
>
> -- Eugen Rochko, Jul 6 2018, [《将Mastodon关到笼子里去》](https://blog.joinmastodon.org/2018/07/cage-the-mastodon/)
> -- Eugen Rochko，2018年7月6日，[《将 Mastodon 关入笼中》](https://blog.joinmastodon.org/2018/07/cage-the-mastodon/)
> 一个中心化的社交媒体平台有一个等级结构，在这个结构中平台的规则及其实施，以及平台的发展方向都是由CEO决定的[……] 一个去中心化的网络有意放弃了对平台所有权的控制，从本质上来讲是没有平台所有者的。
> 中心化的社交媒体平台采用层级结构，规则及规则的执行方式，以及平台的开发和方向都由 CEO 决定 [...] 去中心化网络则有意放弃了平台所有者的控制权，因为它根本就没有所有者。
>
> -- Eugen Rochko, Dec 30 2018, [《为什么去中心化很重要？》](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/)
> -- Eugen Rochko，2018年12月30日，[《去中心化为何重要？》](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/)
### 资金和盈利 {#monetization}
### 资金来源和商业模式 {#monetization}
Mastodon站点是由不同的人或组织完全独立运营的。Mastodon没有在软件中实现任何盈利策略。
Mastodon 网站由不同的人或组织完全独立运营。Mastodon 软件本身未实现任何商业变现策略。
有的服务器运营者选择提供付费帐户；有的服务器运营者是公司，这样便可以利用他们现有的基础设施；有的服务器运营者通过Patreon及其类似服务来众筹资金；有的服务器运营者只是自掏腰包，为自己和朋友搭建私人服务器。所以，如果你想支持你帐户所在服务器的运营者，请检查一下它是否提供了捐赠渠道。
一些服务器运营者选择提供付费账户，一些运营者是能够利用其现有基础设施的公司，一些则依靠用户通过 Patreon 及类似服务进行众筹，还有一些运营者是自负成本，为自己或许还有一些朋友维护个人站点。因此，如果你想支持托管你账户的服务器，请查看其是否提供了捐助途径。
Mastodon的开发同样是通过[Patreon](https://patreon.com/mastodon)和[OpenCollective](https://opencollective.com/mastodon)众筹的。**不涉及风险投资。**
Mastodon 的开发同样通过 [Patreon](https://patreon.com/mastodon) 和 [OpenCollective](https://opencollective.com/mastodon) 进行众筹。**没有任何风险投资参与。**
> 在我看来，“即时、公开、全球性的信息传递与交流” 实际上应该是*全球性的*。分布于能够自我管理的独立组织与行为者之中。一个公共设施，没有利用交流牟利的动机。
> 在我看来，“即时、公开、全球性的消息传递和对话”实际上就应该是_全球性_的。它应该分布在能够自我管理的独立组织和参与者之间。它应该是一种公共服务，没有为牟利而利用这些对话的动机。
>
> -- Eugen Rochko, Mar 3 2018, [《推特不是公共设施》](https://blog.joinmastodon.org/2018/03/twitter-is-not-a-public-utility/)
> -- Eugen Rochko，2018年3月3日，[《Twitter 不是公共服务》](https://blog.joinmastodon.org/2018/03/twitter-is-not-a-public-utility/)
### 跨平台互联 {#interoperability}
### 不同软件间的互操作性 {#interoperability}
实际上：你能否想象一下从你的推特帐户关注一个Instagram用户并在不离开你的帐户的情况下评论他们的照片。如果推特和Instagram是使用同样协议的联邦服务，那么这将是可能的。通过一个Mastodon帐户，**你可以与其他相兼容的网站通迅，** _**即使它并没有运行Mastodon**_。这些网站只需要它们的软件支持ActivityPub协议的相同子集，该协议子集允许创建消息和通过消息进行交互。想了解更多与Mastodon交互所需的技术规范，请参阅[ActivityPub](spec/activitypub)、[WebFinger](spec/webfinger)和[Security](spec/security)。想了解更多关于ActivityPub的用处，请参阅[《为什么ActivityPub是未来》](https://blog.joinmastodon.org/2018/06/why-activitypub-is-the-future/)。
具体来说：想象一下，如果你能在自己的 Twitter 账户上关注某个 Instagram 用户，并直接评论他们的照片，而无需离开 Twitter。如果 Twitter 和 Instagram 是使用相同协议的联合式服务，这就可能实现。拥有 Mastodon 账户后，**你可以与其它任何兼容的站点进行交流，**_**即使它并非运行 Mastodon 软件**_。唯一的要求是该软件支持 ActivityPub 协议中允许创建贴文更新并与之互动的那部分功能的子集。要了解与 Mastodon 互通所需的技术规范详情，请参阅 [ActivityPub](spec/activitypub)、[WebFinger](spec/webfinger) 和 [安全性说明](spec/security)。要进一步了解 ActivityPub 能让我们实现什么，请参阅 [为什么 ActivityPub 是未来](https://blog.joinmastodon.org/2018/06/why-activitypub-is-the-future/)。
> 所有这些平台都是不同的，它们关注不同的需求。然而，它们的基石都是相同的：一些人订阅接收其他人的帖子。因此，它们都是相互兼容的。
> 所有这些平台各不相同，专注于不同的需求。然而，它们的基础是相同的：人们订阅他人以接收他们的帖文。因此，这些平台都是相互兼容的。
>
> -- Eugen Rochko, Jun 27 2018, [《为什么ActivityPub是未来》](https://blog.joinmastodon.org/2018/06/why-activitypub-is-the-future/)
> -- Eugen Rochko，2018年6月27日，[《为什么 ActivityPub 是未来》](https://blog.joinmastodon.org/2018/06/why-activitypub-is-the-future/)
### 自由软件 {#libre}
### 自由/开源软件 {#libre}
与专有服务不同，**任何人都拥有运行，检查，审核，复制，修改，分发和重用Mastodon源代码的完全自由，只要他们保证任何衍生作品都具有同等的自由。** 就像Mastodon用户可以选择他们的服务提供者一样，你作为一个个体可以自由地向Mastodon贡献功能，或者发布包含不同功能的修改版本。这些修改后的版本，也被称为软件分支，被要求维持与Mastodon原始项目同等的自由。例如，[glitch-soc](https://glitch-soc.github.io/docs/)是一个添加了许多实验特性的软件发行版。除此而外，还有许多的独立分支存在，这些分支可能仅仅是主题稍微不同，或者包含对代码库的小修改。因为Mastodon是尊重你的自由的自由软件，像这样的个性化不仅是允许的，而且是鼓励的。
与专有服务不同，**任何人都有运行、研究、检查、复制、修改、分发和重用 Mastodon 源代码的完全自由，前提是他们必须保证任何衍生作品也享有同样的自由。**就像 Mastodon 用户可以选择他们的服务提供商一样，作为个人，你可以自由地为 Mastodon 贡献功能，或发布包含不同功能的 Mastodon 修改版本。这些修改版本，也被称为软件分支，同样需要维持与原始 Mastodon 项目相同的自由。例如，[glitch-soc](https://glitch-soc.github.io/docs/) 是一个添加了各种实验性功能的软件发行版。此外还存在许多个人分支，它们可能在主题样式上略有不同，或者对代码库进行了少量修改。因为 Mastodon 是尊重你自由的自由软件（libre software），像这样的个性化不仅是被允许的，而且是受鼓励的。
> 最终的力量在于让人们能够创建自己的空间、自己的社区，以自己的想法修改软件，但又不牺牲与来自不同社区的人们相互交流的能力。
> 最根本的力量在于赋予人们创造自己的空间、自己的社区的能力，让他们能按自己的意愿修改软件，同时又不牺牲不同社区成员之间相互交流的能力。
>
> -- Eugen Rochko, Feb 20 2017, [《建立社区的力量：对马克·扎克伯格的回应》](https://blog.joinmastodon.org/2017/02/the-power-to-build-communities/)
> -- Eugen Rochko，2017年2月20日，[《构建社区的力量：对 Mark Zuckerberg 的回应》](https://blog.joinmastodon.org/2017/02/the-power-to-build-communities/)
> 去中心化是数字世界的生物多样性，是健康生态系统的标志。像联邦宇宙这样的去中心化网络允许不同的用户界面、不同的软件、不同形式的治理方式共存与合作。
> 去中心化是数字世界的生物多样性，是健康生态系统的标志。像 Fediverse 这样的去中心化网络允许不同的用户界面、不同的软件、不同的治理形式共存与合作。
>
> -- Eugen Rochko, Dec 30 2018, [《为什么去中心化很重要？》](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/)
> -- Eugen Rochko，2018年12月30日，[《去中心化为何重要？(Why does decentralization matter?)》](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/)
## 开始你的旅程吧！ {#next-steps}
## 选择你的浏览路径 {#next-steps}
学习如何使用Mastodon：
了解如何使用 Mastodon：
{{< page-ref page="user/signup" >}}
学习如何安装Mastodon：
了解如何安装 Mastodon：
{{< page-ref page="admin/prerequisites" >}}
学习如何为Mastodon编写应用程序：
了解如何为 Mastodon 编写应用：
{{< page-ref page="client/intro" >}}
了解Mastodon后端以及如何向Mastodon项目做贡献：
了解 Mastodon 后端以及如何做出贡献：
{{< page-ref page="dev/overview" >}}
{{< translation-status-zh-cn raw_title="What is Mastodon?" raw_link="/" last_tranlation_time="2020-05-02" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}}
{{< translation-status-zh-cn raw_title="What is Mastodon?" raw_link="/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

38
content/zh-cn/admin/backups.md
View file

@ -1,55 +1,55 @@
---
title: 备份你的服务器
description: 设置日常备份（可选，但并非如此）
description: 设置定期备份（可选，但实际上很必要）
menu:
docs:
weight: 80
parent: admin
---
对于任何真实世界用途来说，你都应该保证日常备份Mastodon服务器。
对于所有实际使用的场景，你都应确保定期备份你的 Mastodon 服务器。
## 概览 {#overview}
## 概述 {#overview}
你所需要备份的东西，按重要程度排序：
需要备份的内容按重要程度排序如下：
1. PostgreSQL 数据库
2. `.env.production` 文件或等效文件中的应用密钥
2. 来自 `.env.production` 文件或等效文件的应用密钥
3. 用户上传的文件
4. Redis 数据库
## 故障模式 {#failure}
## 故障类别 {#failure}
人们通常要应对两种类型故障：硬件故障，诸如磁盘上数据损坏；以及人为软件故障，诸如误删特定文件。本文档中，仅考虑前一种类型。
人们通常会防范两种类型的故障：硬件故障，如磁盘数据损坏；以及人为和软件错误，如错误删除某特定数据。在本文档中，我们仅考虑前一种类型。
丢失PostgreSQL数据库，那一切都完了。Mastodon将所有重要数据存储于PostgreSQL数据库中。如果数据库消失，那你服务器上所有的帐户、所有的嘟文、所有关注者都将随之消失。
Mastodon 将所有最重要的数据存储在 PostgreSQL 数据库中。PostgreSQL 数据库的丢失将导致服务器完全故障，包括所有账户、嘟文与关注者信息。
如果你丢失了应用密钥，对你的用户而言，Mastodon的某些功能将停止工作。你服务器上的用户将被登出，双因子认证（2FA）将不可用，Web Push API订阅将停止工作。
如果你丢失了应用密钥，Mastodon 的某些功能将停止为用户工作，用户将被登出，双因素认证将不可用，且 Web Push API 订阅将停止工作。
如果你丢失了用户上传的文件，你将丢失头像、横幅、媒体附件，但Mastodon*仍会*继续工作。
如果丢失了用户上传的文件，你将丢失头像、资料卡横幅背景图和媒体附件，但 Mastodon 在未来仍能正常工作。
丢失Redis数据库几乎是无害的：唯一不可逆的数据是Sidekiq队列及之前失败任务的重试计划。主页与列表时间流虽然存储于Redis，但它们可以使用tootctl再生成。
丢失 Redis 数据库几乎无害：唯一不可恢复的数据是 Sidekiq 队列的内容和先前失败任务的计划重试时间。主页和列表信息流存储在 Redis 中，但可以通过 tootctl 重新生成。
最好的备份是所谓的异地备份，即与Mastodon自身不在同一台计算机上存储的备份。如果你托管的服务器起火了，硬盘爆炸了，存储于同一硬件备份将不可用。
最好的备份是被称为异地备份的备份模式，即不存储在与 Mastodon 服务器本身相同的机器上的备份。如果你的服务器着火并且硬盘驱动器爆炸，存储在同一硬盘上的备份将没有太大用处。
## 备份应用密钥 {#env}
应用密钥是最容易备份的，因为它们是不变的。你只需要将 `.env.production` 存储在安全的地方就可以了。
应用密钥是最容易备份的，因为它们从不变化。你只需将 `.env.production` 存储在安全的地方即可。
## 备份 PostgreSQL {#postgresql}
突然断电、硬盘故障、错误迁移数库库schema都会致使数据损坏。由于以上原因，推荐偶尔使用 `pg_dump` 或 `pg_dumpall` 备份数据库。
PostgreSQL 面临断电、硬盘驱动器故障与错误的架构迁移带来的数据损坏风险。因此，建议偶尔使用 `pg_dump` 或 `pg_dumpall` 进行备份。
如果要求高可用性，可以使用热流拷贝（hot streaming replication）使第二台PostgreSQL服务器始终具有最新数据，并做好另一台服务器出现故障切换至此的准备。
对于高可用配置，可以使用热数据流式复制来拥有一个数据始终最新的第二PostgreSQL服务器，以便在另一服务器宕机时随时切换。
## 备份用户上传的文件 {#media}
如果你使用外部对象存储，诸如Amazon S3、Google Cloud 或 Wasabi，你无需为怎么备份它们而担心。各自的公司将负责处理硬件故障。
如果你使用外部对象存储提供商，如亚马逊S3、谷歌云或 Wasabi，则无需担心备份这些文件。相应公司负责处理硬件故障。
如果你使用本地文件存储，复制体积巨大的 `public/system` 目录（默认存储上传文件的地方）。
如果你使用是本地文件存储，那么你需要自行对 `public/system` 这个大目录进行备份，该目录是上传文件的默认存储位置。
## 备份 Redis {#redis}
备份Redis是很容易的。Redis会定期将数据写入`/var/lib/redis/dump.rdb`文件，你只需要复制这个文件就可以了。
备份 Redis 很容易。Redis 定期写入 `/var/lib/redis/dump.rdb`，这是你唯一需要复制的文件。
{{< translation-status-zh-cn raw_title="Backing up your server" raw_link="/admin/backups/" last_tranlation_time="2020-05-06" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}}
{{< translation-status-zh-cn raw_title="Backing up your server" raw_link="/admin/backups/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

1349
content/zh-cn/admin/config.md
View file

File diff suppressed because it is too large Load diff

250
content/zh-cn/admin/elasticsearch.md Normal file
View file

@ -0,0 +1,250 @@
---
title: 配置全文搜索
description: 设置 Elasticsearch 以搜索嘟文(包括创建的嘟文、喜欢的嘟文和被提及的嘟文)、可公开索引的嘟文与账号
aliases:
- /admin/optional/elasticsearch
menu:
docs:
weight: 40
parent: admin
---
当 Elasticsearch 可用时，Mastodon 支持全文搜索。强烈建议配置此功能。
Mastodon 的全文搜索允许已登录用户查找以下内容：
- 选择在搜索结果中显示的账号发布的公开嘟文
- 自己创建的嘟文
- 提及自己的嘟文
- 自己喜欢的嘟文
- 自己收藏的嘟文
- 账号(显示名称、用户名和简介)
全文搜索有意不允许在整个数据库中搜索任意字符串。
## 安装 Elasticsearch {#install}
{{< hint style="info" >}}
Mastodon 经过测试与 Elasticsearch 7 版本兼容。它理论上也支持 OpenSearch 以及 Elasticsearch 6 和 8 版本，但这些设置不受官方支持。
{{< /hint >}}
Elasticsearch 需要 Java 运行环境。如果你尚未安装 Java，请立即进行安装。假设你以 `root` 用户身份登录：
```bash
apt install openjdk-17-jre-headless
```
将 Elasticsearch 官方仓库添加到 apt：
```bash
wget -O /usr/share/keyrings/elasticsearch.asc https://artifacts.elastic.co/GPG-KEY-elasticsearch
echo "deb [signed-by=/usr/share/keyrings/elasticsearch.asc] https://artifacts.elastic.co/packages/7.x/apt stable main" > /etc/apt/sources.list.d/elastic-7.x.list
```
现在你可以安装 Elasticsearch：
```bash
apt update
apt install elasticsearch
```
{{< hint style="warning" >}}
**安全警告：** 默认情况下， Elasticsearch 应仅绑定到 `localhost`，即无法从外部网络访问。你可以通过查看 `/etc/elasticsearch/elasticsearch.yml` 中的 `network.host` 来检查 Elasticsearch 绑定的地址。请考虑到任何能够访问 Elasticsearch 的人都可以访问和修改其中的任何数据，因为没有认证层。所以确保访问安全非常重要。建议使用防火墙，只开放 22、 80 和 443 端口，如[主安装说明](../../prerequisites/#install-a-firewall-and-only-whitelist-ssh-http-and-https-ports)中所述。如果你有多主机设置，你必须了解如何保护内部流量安全。
{{< /hint >}}
启动 Elasticsearch：
```bash
systemctl daemon-reload
systemctl enable --now elasticsearch
```
## 配置 Mastodon {#config}
编辑 `.env.production` 以添加以下变量：
```bash
ES_ENABLED=true
ES_HOST=localhost
ES_PORT=9200
ES_PRESET= # single_node_cluster, small_cluster或large_cluster
# ES_USER=
# ES_PASS=
```
_注意_：如果使用 TLS，请在主机名前加上 `https://`。例如：`https://elastic.example.com`。
### 选择正确的预设
`ES_PRESET` 的值取决于你的 Elasticsearch 规模，它将用于为你的索引设置最适合你设置的分片和副本数量：
- `single_node_cluster` 如果你的 Elasticsearch 集群中只有一个节点。索引将配置为无副本
- `small_cluster` 如果你的集群少于 6 个节点。索引将配置为单副本
- `large_cluster` 如果你的集群有 6 个或更多节点。索引将较之 `small_cluster` 配置更多的分片，以便它们可以分布在更多节点上
如果你在同一台机器上有多个 Mastodon 服务器，并且计划为所有这些服务器使用相同的 Elasticsearch 实例，请确保它们都在配置中设置了唯一的 `REDIS_NAMESPACE`，以区分索引。如果你需要覆盖 Elasticsearch 索引的前缀，可以直接设置 `ES_PREFIX`。
### 安全性
默认情况下，Elasticsearch 不处理任何认证，所有请求都以完全管理员权限进行。我们强烈建议你在集群上配置 Elasticsearch 安全功能。
要进行配置，请参考[官方文档](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-minimal-setup.html)。它将指导你进行以下操作：
- 启用安全功能（`xpack.security.enabled: true`）
- 为内置用户创建密码
完成后，你可以创建自定义用户组供 Mastodon 连接。
例如（可以参考此段命令并使用你的 Elastic 管理员密码）：
```sh
curl -X POST -u elastic:admin_password "localhost:9200/_security/role/mastodon_full_access?pretty" -H 'Content-Type: application/json' -d'
{
"cluster": ["monitor"],
"indices": [{
"names": ["*"],
"privileges": ["read", "monitor", "write", "manage"]
}]
}
'
```
[Elasticsearch用户组创建文档](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-api-put-role.html)
创建用户组后，你可以为Mastodon服务器创建用户，并为其分配用户组。
例如（请调整此片段以使用你的Elastic管理员密码，并自定义你新`mastodon`用户的密码）：
```sh
curl -X POST -u elastic:admin_password "localhost:9200/_security/user/mastodon?pretty" -H 'Content-Type: application/json' -d'
{
"password" : "l0ng-r4nd0m-p@ssw0rd",
"roles" : ["mastodon_full_access"]
}
'
```
[Elasticsearch用户创建文档](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-api-put-user.html)
完成后，你需要配置 Mastodon 使用新创建用户的凭据。
然后在 `.env.production` 中，调整你的配置：
```bash
ES_USER=mastodon
ES_PASS=l0ng-r4nd0m-p@ssw0rd
```
设置完成，你的 Elasticsearch 实例应该更安全了！
### 填充索引
保存新配置后，重启 Mastodon 进程使其生效：
```bash
systemctl restart mastodon-sidekiq
systemctl reload mastodon-web
```
现在是时候创建 Elasticsearch 索引并填充数据了：
```bash
su - mastodon
cd live
RAILS_ENV=production bin/tootctl search deploy
```
{{< hint style="info" >}}
创建 Elasticsearch 索引可能需要 JVM（Java 虚拟机）提供的更多内存。如果 Elasticsearch 在创建索引时崩溃，请尝试分配更多内存。
1. 在 `/etc/elasticsearch/jvm.options.d/` 目录下创建并打开一个文件（例如：`nano /etc/elasticsearch/jvm.options.d/ram.options`）
2. 添加以下文本并根据需求编辑分配的内存。根据经验， Elasticsearch 应使用你可用内存的25%-50%。请不要分配超过可用内存的内存量。
```
# Xms表示总堆空间的初始大小
# Xmx表示总堆空间的最大大小
# 两个值应该相同
-Xms2048m
-Xmx2048m
```
3. 保存文件。
4. 使用 `systemctl restart elasticsearch` 重启 Elasticsearch。
5. 重试创建 Elasticsearch 索引。如果 Elasticsearch 仍然崩溃，请尝试设置更高的数值。
{{< /hint >}}
## 其他语言的搜索优化
### 中文搜索优化 {#chinese-search-optimization}
标准分析器是 Elasticsearch 的默认分析器，但对于中文等某些语言来说，它可能不是最佳选择。要增强搜索体验，请考虑安装特定语言的分析器。在 Elasticsearch 中创建索引之前，请确保安装以下扩展：
- [elasticsearch-analysis-ik](https://github.com/medcl/elasticsearch-analysis-ik)
- [elasticsearch-analysis-stconvert](https://github.com/medcl/elasticsearch-analysis-stconvert)
然后按如下方式修改 Mastodon 的索引定义：
```diff
diff --git a/app/chewy/accounts_index.rb b/app/chewy/accounts_index.rb
--- a/app/chewy/accounts_index.rb
+++ b/app/chewy/accounts_index.rb
@@ -4,7 +4,7 @@ class AccountsIndex < Chewy::Index
settings index: { refresh_interval: '5m' }, analysis: {
analyzer: {
content: {
- tokenizer: 'whitespace',
+ tokenizer: 'ik_max_word',
filter: %w(lowercase asciifolding cjk_width),
},
diff --git a/app/chewy/statuses_index.rb b/app/chewy/statuses_index.rb
--- a/app/chewy/statuses_index.rb
+++ b/app/chewy/statuses_index.rb
@@ -16,9 +16,17 @@ class StatusesIndex < Chewy::Index
language: 'possessive_english',
},
},
+ char_filter: {
+ tsconvert: {
+ type: 'stconvert',
+ keep_both: false,
+ delimiter: '#',
+ convert_type: 't2s',
+ },
+ },
analyzer: {
content: {
- tokenizer: 'uax_url_email',
+ tokenizer: 'ik_max_word',
filter: %w(
english_possessive_stemmer
lowercase
@@ -27,6 +35,7 @@ class StatusesIndex < Chewy::Index
english_stop
english_stemmer
),
+ char_filter: %w(tsconvert),
},
},
}
diff --git a/app/chewy/tags_index.rb b/app/chewy/tags_index.rb
--- a/app/chewy/tags_index.rb
+++ b/app/chewy/tags_index.rb
@@ -2,10 +2,19 @@
class TagsIndex < Chewy::Index
settings index: { refresh_interval: '15m' }, analysis: {
+ char_filter: {
+ tsconvert: {
+ type: 'stconvert',
+ keep_both: false,
+ delimiter: '#',
+ convert_type: 't2s',
+ },
+ },
analyzer: {
content: {
- tokenizer: 'keyword',
+ tokenizer: 'ik_max_word',
filter: %w(lowercase asciifolding cjk_width),
+ char_filter: %w(tsconvert),
},
edge_ngram: {
```
{{< translation-status-zh-cn raw_title="Configuring full-text search" raw_link="/admin/elasticsearch/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

232
content/zh-cn/admin/install.md
View file

@ -1,6 +1,6 @@
---
title: 从源中安装
description: 创建你自己的Mastodon站点的教学指献。
title: 从源代码安装
description: 创建你自己的 Mastodon 站点的教程。
menu:
docs:
weight: 20
@ -9,105 +9,84 @@ menu:
## 前提条件 {#pre-requisites}
* 一台你有root访问权限的运行 **Ubuntu 18.04** 的机器
* 一个用于Mastodon站点的**域名**（或一个子域名），例如：`example.com`
* 一个电子邮件发送服务提供商，或其他**SMTP服务器**
* 一台运行 **Ubuntu 24.04** 或 **Debian 12** 的机器，你需要拥有root访问权限
* 一个用于 Mastodon 站点的**域名**（或子域名），例如 `example.com`
* 一个电子邮件发送服务或其他 **SMTP 服务器**
你需要使用root用户运行命令。如果你现在不是root用户，请切换至root用户：
在以下示例中，我们将使用 `example.com` 作为域名。请记得在运行任何命令前将其替换为你自己的域名。
### 软件仓库 {#system-repositories}
你将以 root 身份运行命令。如果你还不是 root 用户，请切换到 root：`sudo -i`
首先确保已经安装curl：
### 系统存储库 {#system-repositories}
首先确保已安装 curl、 wget、 gnupg、 apt-transport-https、 lsb-release 和 ca-certificates：
```bash
apt install -y curl wget gnupg apt-transport-https lsb-release ca-certificates
```
#### Node.js {#node-js}
```bash
curl -sL https://deb.nodesource.com/setup_12.x | bash -
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list
```
#### Yarn {#yarn}
#### PostgreSQL {#postgresql}
```bash
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list
wget -O /usr/share/keyrings/postgresql.asc https://www.postgresql.org/media/keys/ACCC4CF8.asc
echo "deb [signed-by=/usr/share/keyrings/postgresql.asc] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/postgresql.list
```
### 软件包 {#system-packages}
### 系统软件包 {#system-packages}
```bash
apt update
apt install -y \
imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file git-core \
g++ libprotobuf-dev protobuf-compiler pkg-config nodejs gcc autoconf \
imagemagick ffmpeg libvips-tools libpq-dev libxml2-dev libxslt1-dev file git-core \
g++ libprotobuf-dev protobuf-compiler pkg-config gcc autoconf \
bison build-essential libssl-dev libyaml-dev libreadline6-dev \
zlib1g-dev libncurses5-dev libffi-dev libgdbm5 libgdbm-dev \
nginx redis-server redis-tools postgresql postgresql-contrib \
certbot python-certbot-nginx yarn libidn11-dev libicu-dev libjemalloc-dev
zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev \
nginx nodejs redis-server redis-tools postgresql postgresql-contrib \
certbot python3-certbot-nginx libidn11-dev libicu-dev libjemalloc-dev
```
### 安装 Ruby {#installing-ruby}
#### Yarn {#yarn}
因为使用 rbenv 可以更容易的获得正确的版本并在新版本发布后进行更新，我们将使用 rbenv 来管理Ruby版本。rbenv 必须安装在单个Linux用户中，因此，我们首先需要使用以下命令创建一个Mastodon用户：
启用`corepack`，以便自动安装正确版本的`yarn`：
```bash
adduser --disabled-login mastodon
corepack enable
```
切换到mastodon用户：
### 创建 `mastodon` 用户 {#creating-the-mastodon-user}
执行以下命令，创建用于运行 Mastodon 的用户：
```bash
su - mastodon
```
执行以下步骤安装 rbenv 和 rbenv-build：
```bash
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv && src/configure && make -C src
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
exec bash
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
```
上述操作完成，我们便可以安装正确的 Ruby 版本：
```bash
RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 2.6.6
rbenv global 2.6.6
```
我们同样需要安装 bundler：
```bash
gem install bundler --no-document
```
返回root用户：
```bash
exit
adduser --disabled-password mastodon
```
## 配置 {#setup}
### 配置 PostgreSQL {#setting-up-postgresql}
#### 性能调优（可选） {#performance-configuration-optional}
#### 性能配置（可选） {#performance-configuration-optional}
为了优化性能，你可以使用 [pgTune](https://pgtune.leopard.in.ua/#/) 生成一个合适的配置文件。编辑 `/etc/postgresql/9.6/main/postgresql.conf` 中的相应数值并使用 `systemctl restart postgresql` 命令重启 PostgreSQL。
为获得最佳性能，你可以使用 [pgTune](https://pgtune.leopard.in.ua/#/) 生成适当的配置，并在使用 `systemctl restart postgresql` 重启 PostgreSQL 之前编辑 `/etc/postgresql/17/main/postgresql.conf` 中的值。
#### 创建帐户 {#creating-a-user}
#### 创建用户 {#creating-a-user}
你需创建一个供Mastodon使用的PostgreSQL帐户。创建一个使用“ident”认证方式的帐户是最容易的配置方法，即PostgreSQL帐户不需要独立的密码并由同名Linux用户使用。
你需要创建一个供 Mastodon 使用的 PostgreSQL 用户。在简单配置中，最简单的方法是使用 "ident" 认证，即 PostgreSQL 用户没有单独的密码，可以由具有相同用户名的 Linux 用户使用。
打开控制台：
打开命令行：
```bash
sudo -u postgres psql
```
在控制台中执行：
在命令行中执行：
```sql
CREATE USER mastodon CREATEDB;
@ -116,9 +95,9 @@ CREATE USER mastodon CREATEDB;
完成！
### 配置 Mastodon {#setting-up-mastodon}
### 设置 Mastodon {#setting-up-mastodon}
现在该下载Mastodon代码了。切换至mastodon用户：
现在是下载 Mastodon 代码的时候了。切换到 mastodon 用户：
```bash
su - mastodon
@ -126,111 +105,140 @@ su - mastodon
#### 检出代码 {#checking-out-the-code}
使用git下载最新稳定版Mastodon：
使用 git 下载 Mastodon 的最新稳定版本：
```bash
git clone https://github.com/mastodon/mastodon.git live && cd live
git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1)
git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1)
```
#### 安装依赖 {#installing-the-last-dependencies}
#### 安装 Ruby {#installing-ruby}
现在，安装Ruby和JavaScript依赖：
我们将使用 rbenv 来管理 Ruby 版本，因为它简化了获取正确版本和在新版本可用时进行更新的过程。
安装 rbenv 和 ruby-build：
```bash
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
exec bash
git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build
```
完成这些后，我们可以安装正确的Ruby版本：
```bash
RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install
```
#### 安装最后的依赖项 {#installing-the-last-dependencies}
现在安装 Ruby 和 JavaScript 依赖项：
```bash
bundle config deployment 'true'
bundle config without 'development test'
bundle install -j$(getconf _NPROCESSORS_ONLN)
yarn install --pure-lockfile
yarn install
```
{{< hint style="info" >}}
两个`bundle config`命令仅仅第一次安装依赖时需要。如果你之后进行升级或重安装依赖，只需要`bundle install`就够了。
仅在首次安装依赖项时需要执行两个 `bundle config` 命令。如果你之后要更新或重新安装依赖项，只需执行 `bundle install` 就足够了。
{{< /hint >}}
#### 生成配置文件 {#generating-a-configuration}
#### 生成配置 {#generating-a-configuration}
运行交互式安装向导：
运行交互式设置向导：
```bash
RAILS_ENV=production bundle exec rake mastodon:setup
RAILS_ENV=production bin/rails mastodon:setup
```
它将：
这将：
* 创建一个配置文件
* 预编译静态文件
* 创建数据库schema
* 运行资源预编译
* 创建数据库架构
配置文件被保存在`.env.production`。如果你愿意的话，你可以查看并编辑这个文件。请参阅[配置文件的文档]({{< relref "config" >}})。
配置文件保存为 `.env.production`。你可以查看并按照喜好编辑它。请参考[配置文档]({{< relref "config" >}})。
你已经完成需使用mastodon用户进行的操作，请切换回root用户：
现在你已完成 mastodon 用户的操作，切回 root 用户：
```bash
exit
```
### 配置 nginx {#setting-up-nginx}
### 获取SSL证书 {#acquiring-a-ssl-certificate}
从Mastodon目录复制配置文件模版到nginx：
我们将使用 Let's Encrypt 获取免费的 SSL 证书：
```bash
certbot certonly --nginx -d example.com
```
这将获取证书并将其保存在 `/etc/letsencrypt/live/example.com/` 目录下。
### 设置nginx {#setting-up-nginx}
从 Mastodon 目录复制 nginx 的配置模板：
```bash
cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon
ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon
rm /etc/nginx/sites-enabled/default
```
编辑 `/etc/nginx/sites-available/mastodon`
然后编辑 `/etc/nginx/sites-available/mastodon` 以
1. 替换 `example.com` 为你自己的域名
2. 启用 `ssl_certificate` 和 `ssl_certificate_key` 这两行，并把它们替换成如下两行（如果你使用自己的证书的话则可以忽略这一步）
1. 将 `example.com` 替换为你自己的域名
2. 取消注释 `ssl_certificate` 和 `ssl_certificate_key`（如果你使用自己的证书，请忽略此步骤）：
```
ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
```
```
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;;
```
3. 你还可以根据自己的需求做出其它的一些调整。
3. 进行你可能需要的任何其他调整。
重载 nginx 以使变更生效：
### 获取SSL证书 {#acquiring-a-ssl-certificate}
我们将使用 Let’s Encrypt 获取一个免费的SSL证书：
允许其他用户遍历 mastodon 用户的主目录，以便 nginx 的 `www-data` 用户可以访问资源文件：
```bash
certbot --nginx -d example.com
chmod o+x /home/mastodon
```
这个命令将获取一个证书，自动更新 `/etc/nginx/sites-available/mastodon` 以使用新证书并重载nginx以使变更生效。
现在你应该能够通过浏览器访问你的域名，然后看到一只大象锤击电脑屏幕的错误页面。这是因为我们还没有启动Mastodon进程。
### 配置 systemd 服务 {#setting-up-systemd-services}
从Mastodon目录复制systemd服务模版：
重启 nginx 使更改生效：
```bash
systemctl restart nginx
```
此时，你应该能够在浏览器中访问你的域名，看到大象撞击电脑屏幕的错误页面。这是因为我们还没有启动 Mastodon 进程。
### 设置 systemd 服务 {#setting-up-systemd-services}
从 Mastodon 目录复制 systemd 服务模板：
```sh
cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/
```
然后修改以下文件，以保证用户名与路径是正确的：
如果你修改了默认设置，请检查用户名和路径是否正确：
* `/etc/systemd/system/mastodon-web.service`
* `/etc/systemd/system/mastodon-sidekiq.service`
* `/etc/systemd/system/mastodon-streaming.service`
最后，启动新systemd服务并将该服务设为开机自动激活：
```bash
systemctl daemon-reload
systemctl start mastodon-web mastodon-sidekiq mastodon-streaming
systemctl enable mastodon-*
```sh
$EDITOR /etc/systemd/system/mastodon-*.service
```
他们将在开机启动时自动开始运行。
最后，启动并启用新的 systemd 服务：
```sh
systemctl daemon-reload
systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming
```
Mastodon 服务现在将在开机时自动启动。
{{< hint style="success" >}}
**欢呼吧！你现在可以从浏览器中访问你的域名了！**
**太好了！以上就是安装 Mastodon 的全部步骤。现在你可以在浏览器中访问你的站点了！**
{{< /hint >}}
{{< translation-status-zh-cn raw_title="Installing from source" raw_link="/admin/install/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}}
{{< translation-status-zh-cn raw_title="Installing from source" raw_link="/admin/install/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

133
content/zh-cn/admin/migrating.md
View file

@ -1,95 +1,154 @@
---
title: 迁移到新机器
description: 在不损失任何东西的情况下，把你的Mastodon复制安装至新的服务器上。
description: 将你的 Mastodon 站点无损复制到新服务器。
menu:
docs:
weight: 90
parent: admin
---
有时，出于各种原因，你需要将你的Mastodon实例从一台服务器迁移至另一台。幸运的是，这个过程并不太困解，虽然这可能导致一段时间的下线。
出于各种原因，你可能希望将 Mastodon 实例从一台服务器迁移到另一台。幸运的是，这个过程并不太困难，尽管可能会导致一些停机时间。
{{< hint style="info" >}}
本篇指南基于Ubuntu Server编写；根据其他设置的不同，你的过程可能会有变化。
本指南主要针对 Ubuntu Server 编写；对于其他配置环境，你的实际体验可能有所不同。
{{< /hint >}}
## 基本步骤 {#basic-steps}
1. 依照[产品指南]({{< relref "install" >}})安装新的Mastodon服务器（切记，不要运行 `mastodon:setup`）。
2. 停止旧服务器上的Mastodon（`systemctl stop 'mastodon-*.service'`）。
3. 依照如下指示，导出并导入PostgreSQL数据库。
4. 依照如下指示，复制 `system/` 目录下文件。（注意：如果你使用S3存储，你可以跳过此步）。
1. 使用[生产环境配置指南]({{< relref "install" >}})设置新的 Mastodon 服务器（但不要运行`mastodon:setup`，只保持PostgreSQL服务运行）。
2. 停止旧服务器上的 Mastodon 服务（例如`systemctl stop 'mastodon-*.service'`）。
3. 使用下面的说明导出和加载 PostgreSQL 数据库。
4. 使用下面的说明复制 `system/` 文件。（注意：如果你使用 S3，可以跳过此步骤。）
5. 复制 `.env.production` 文件。
6. 运行 `RAILS_ENV=production bundle exec rails assets:precompile` 编译 Mastodon。
7. 运行 `RAILS_ENV=production ./bin/tootctl feeds build` 重新构建每个用户的主页时间流。
8. 启动新服务器上的Mastodon。
9. 更新DNS设置，将其指向新服务器。
10. 更新或复制你的Nginx设置，如果必要的话可重获取LetsEncrypt证书。
11. 享受你的新服务器！
6. 保存 Redis 数据库，停止新旧机器上的 Redis 服务，并将 Redis 数据库从 `/var/lib/redis/` 复制到新服务器。
7. 运行 `RAILS_ENV=production bundle exec rails assets:precompile` 编译 Mastodon。
8. 在新服务器上启动 Mastodon 和 Redis。
9. 运行 `RAILS_ENV=production ./bin/tootctl feeds build` 为每个用户重建主时间线。
10. 运行 `RAILS_ENV=production ./bin/tootctl search deploy` 重建 Elasticsearch 索引（注意：如果你不使用 Elasticsearch，可以跳过此步骤。）
11. 更新 DNS 设置，指向新服务器。
12. 更新或复制 Nginx 配置，并根据需要重新运行 LetsEncrypt。
13. 享受你的新服务器！
## 详细步骤 {#detailed-steps}
### 什么数据需要被迁移 {#what-data-needs-to-be-migrated}
### 停止 Mastodon 服务
你必须需要复制如下内容：
```bash
systemctl stop 'mastodon-*.service'
```
* `~/live/public/system`目录，里面包含了用户上传的图片与视频（如果使用S3，可跳过此步）
* PostgreSQL数据库（使用[pg_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html)）
* `~/live/.env.production`文件，里面包含了服务器配置与密钥
### 需要迁移哪些数据 {#what-data-needs-to-be-migrated}
不太重要的部分，为了方便起见，你也可以复制如下内容：
总体而言，你需要复制以下内容：
* nginx配置文件（位于`/etc/nginx/sites-available/default`）
* systemd配置文件（`/etc/systemd/system/mastodon-*.service`），里面可能包括一些你服务器的调优与个性化
* PgBouncer配置文件，位于 `/etc/pgbouncer` （如果你使用PgBouncer的话）
* `~/live/public/system` 目录，该目录包含用户上传的图片和视频（如果使用 S3，则不需要）
* PostgreSQL 数据库（使用 [pg_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html)）
* `~/live/.env.production` 文件，其中包含服务器配置和密钥
* `/var/lib/redis/` 目录中的 Redis 数据库，其中包含未处理的 Sidekiq 任务。
### 导出并导入PostgreSQL数据库 {#dump-and-load-postgresql}
以下内容不太重要，但为方便起见，你可能仍然想要复制：
不要运行`mastodon:setup`，而是创建一个名为`template0`的空白PostgreSQL数据库（当导入PostgreSQL导出文件时，这是很有用的，参见[pg_dump文档](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)）。
* nginx 配置（位于 `/etc/nginx/sites-available/mastodon`）
* 域名的 SSL 证书（若使用 LetsEncrypt，应位于 `/etc/letsencrypt/live/`）
* systemd 配置文件（`/etc/systemd/system/mastodon-*.service`），其中可能包含你的服务器调整和自定义
* `/etc/pgbouncer` 下的 PgBouncer 配置（如果你使用它）
在你的旧系统，使用`mastodon`用户运行如下命令：
### 导出与导入 PostgreSQL {#dump-and-load-postgresql}
我们不运行 `mastodon:setup`，而是使用 `template0` 数据库创建一个空的 PostgreSQL 数据库（这在还原 PostgreSQL 转储文件时很有用，[如 pg_dump 文档所述](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)）。
如果你的 PostgreSQL 用户使用密码，为方便起见，你可能希望在新系统上配置 `mastodon` 用户使用与旧系统相同的密码：
```bash
sudo -u postgres psql
ALTER USER mastodon WITH PASSWORD 'YOUR_PASSWORD';
\q
```
在旧系统上以 `mastodon` 用户身份运行：
```bash
pg_dump -Fc mastodon_production -f backup.dump
```
使用 `rsync` 或 `scp` 复制 `backup.dump` 文件。然后在新系统，使用`mastodon`帐户创建一个空数据库：
使用 `rsync` 或 `scp` 复制 `backup.dump` 文件。然后在新系统上，以 `mastodon` 用户身份创建一个空数据库：
```bash
createdb -T template0 mastodon_production
```
然后导入它：
然后导入它（将 `-j#` 中的 `#` 替换为系统中的 CPU 数量以提高还原性能）：
```bash
pg_restore -U mastodon -n public --no-owner --role=mastodon \
pg_restore -Fc -j# -U mastodon -n public --no-owner --role=mastodon \
-d mastodon_production backup.dump
```
（注意：如果新服务器上的帐户名不是`mastodon`，你应当修改上面命令中 `-U` **和** `--role` 参数。两台服务器的用户名不同也可以。）
（请注意，如果新服务器上的用户名不是 `mastodon`，你应该更改上面的 `-U` 和 `--role` 值。两个服务器之间可以使用不同的用户名。）
### 复制文件 {#copy-files}
本操作可能花费一些时间，若你希望避免不必要重复制，建议使用`rsync`。在你的旧机器上，使用`mastodon`用户，运行：
这可能需要一些时间，为避免不必要的重复复制，建议使用 `rsync`。在旧机器上，以 `mastodon` 用户身份运行：
```bash
rsync -avz ~/live/public/system/ mastodon@example.com:~/live/public/system/
```
如果旧服务器上任何文件有改动，你需要重运行此命令。
如果旧服务器上的任何文件发生更改，你需要重新运行此命令。
你同样需要复制`.env.production`文件，该文件内含密钥。
你还应该复制 `.env.production` 文件，其中包含密钥。
可选的，你可以复制nginx、systemd、pgbouncer配置文件，或者从头开始重写它们。
在新机器上，确保 Redis 未运行，否则它可能会覆盖你尝试还原的转储文件。以 `root` 用户身份运行：
```bash
systemctl stop redis-server.service
```
现在复制你的 Redis 数据库（根据需要调整 Redis 数据库的位置）。在旧机器上，以 `root` 用户身份运行：
```bash
redis-cli SAVE
systemctl stop redis-server.service
rsync -avz /var/lib/redis/ root@example.com:/var/lib/redis
```
作为可选操作，你可以复制 nginx、systemd 和 PgBouncer 配置文件，或者从头重写它们。
### 迁移期间 {#during-migration}
你可以编辑旧机器上的`~/live/public/500.html`页面，如果你希望展示一个优雅的错误信息，让现有用户知晓正在进行迁移。
你可以编辑旧机器上的 `~/live/public/500.html` 页面，以显示一条友好的错误消息，让现有用户知道迁移正在进行中。
你也应该提前一天将DNS TTL设置为较小数值（30-60分钟）。这样当你把DNS指向新IP后，新纪录可以很快扩散开来。
你可能还想在提前一天将 DNS TTL 设置为较小的值（30-60分钟），这样一旦你将其指向新 IP 地址，DNS 就可以快速传播。
### 迁移后 {#after-migrating}
你可以使用[whatsmydns.net](https://whatsmydns.net/)来查看DNS扩散的过程。为了跳过这个过程，你可以修改你自己的`/etc/hosts`文件，将其指向你的新服务器，这样你可以尽早开始使用新服务器。
以mastodon用户身份运行以下命令：
{{< translation-status-zh-cn raw_title="Migrating to a new machine" raw_link="/admin/migrating/" last_tranlation_time="2020-05-06" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}}
```bash
RAILS_ENV=production bundle exec rails assets:precompile
```
现在以 root 用户身份运行以下命令：
```bash
systemctl daemon-reload
systemctl start redis-server
systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming
systemctl restart nginx
```
一旦服务器重新上线，你可以为用户重建主页时间线（这可能需要很长时间，取决于用户数量。）
```bash
RAILS_ENV=production ./bin/tootctl feeds build
```
如果你使用 Elasticsearch，请运行以下命令重建索引（这可能需要很长时间，取决于你拥有的状态数量。）
```bash
RAILS_ENV=production ./bin/tootctl search deploy
```
你可以查看 [whatsmydns.net](https://whatsmydns.net/) 以了解 DNS 传播的进度。要加速这个过程，你可以编辑自己的 `/etc/hosts` 文件，指向新服务器，这样你就可以提前开始使用它。
{{< translation-status-zh-cn raw_title="Migrating to a new machine" raw_link="/admin/migrating/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

314
content/zh-cn/admin/moderation.md
View file

@ -1,76 +1,320 @@
---
title: 运营操作
description: 处理不想要的用户与域名
title: 审核操作
description: 针对不受欢迎的用户或域名可以采取的操作。
menu:
docs:
weight: 110
parent: admin
---
## 帐户管理 {#individual-moderation}
## 针对个人用户的审核 {#individual-moderation}
Mastodon运营操作始终作用于本地，即从特定服务器查看的内容。一台服务器管理员（admin）或运营员（moderator）不能影响另一台服务器上的用户，他们只能影响另一台服务器用户的本地服务器副本。
Mastodon 中的审核始终在本站应用，即从特定实例的角度来看。一个实例的管理员或协管员不能影响另一个实例上的用户，他们只能影响该用户在自己实例上的本地副本。
### 禁止登录（disable login） {#disable-login}
从 v3.5.0 开始，所有默认的用户审核决定都会通过电子邮件通知受影响的用户。用户可以访问申诉页面，在决定做出后的 20 天内提交一次申诉。协管员可以批准或拒绝申诉。
Mastodon可以被禁止登录。这样可以禁止用户对帐户进行任何操作，但是其帐户的内容仍保持不变。这个限制是可撤销的，任何时候都可以重新激活该用户。本限制仅适用于你服务器的本地用户。
### 标记为敏感内容 {#sensitive-user}
### 隐藏（silence） {#silence-user}
当一个账户被标记为敏感时，该用户发布的所有媒体内容将自动被[标记为敏感内容](https://docs.joinmastodon.org/user/posting/#cw)。
在Mastodon，隐藏（silence）是沙箱（sandbox）的同义词。一个被隐藏的帐户不会出现在未关注该帐户的用户面前。该帐户所有内容仍存在，这些内容可以通过搜索查找到，该帐户可以被提及、被关注，但是这些内容是不可见的。
### 冻结 {#freeze-user}
此外，隐藏操作不会影响联邦宇宙。一个本地隐藏了的帐户*不会*自动在其他服务器隐藏。
Mastodon 账户可以被冻结。这会阻止用户使用该账户做任何事情，但所有内容仍然完好无损地保留。这种限制是可逆的；账户可以随时解冻。这种限制仅适用于你实例上的本站用户。
本限制是可撤销的，任何时间都可以去除该帐户的隐藏。
当用户的账户被冻结时，他们会被重定向到**账户设置**页面，并显示以下信息：
### 封禁（suspension） {#suspend-user}
> 你不能再登录你的账户，或以任何其他方式使用它，但你的个人资料和其他数据保持完整。
在Mastodon，封禁（suspension）是删除（deletion）的同义词。该帐户不会出现在搜索之中，其用户资料页将消失，该帐户的所有嘟文，上传，关注者以及所有其它数据都将被移除。本限制是**不可逆的**。当一个帐户被解除屏蔽，用户可以重新控制帐户，但旧数据已经一去不复返了。
当用户的账户解冻后，正常功能会恢复。
## 实例管理 {#server-wide-moderation}
### 限制 {#limit-user}
由于使用帐户管理单独处理来自行为异常服务器的大量用户是让人精疲力竭的事，所以可以预清空来自特定服务器的所有用户，即所谓的**域名屏蔽（domain block）**。该操作有多个不同严厉程度。
之前被称为"隐藏"。被限制的账户将对该实例上的所有其他用户隐藏，除非用户已经关注了被限制的账户。所有内容仍然存在，并且仍然可以通过搜索、提及和关注找到，但内容在公开场合不可见。
### 拒绝接收媒体文件（reject media） {#reject-media}
目前，限制不影响联合功能。在本站被限制的账户在其他实例*不会*被自动限制。账户限制是可逆的。
当这个选项被激活，来自该服务器的文件将不会传递至本地。其包括头像、横幅、emoji及媒体附件。
### 封禁 {#suspend-user}
### 隐藏（silence） {#silence-server}
Mastodon 中的封禁操作意味着账户实际上被删除。该账户不再出现在搜索中，账户页面消失，所有嘟文、上传的内容、关注者和所有其他数据在公开场合被移除。但是，自封禁起 30 天内，所有数据在管理后台仍然保留。这是为了给用户提供与实例管理员合作解决潜在问题并恢复账户的机会。
对来自该服务器的所有帐户应用隐藏（silence）操作。
如果账户在 30 天期限内被恢复，所有数据将再次可被公开访问，不会产生不良影响。 30 天期限过后，用户的**所有**数据将从被实例中清除。管理员还可以选择在 30 天内的任何时候立即删除用户的账户数据。
### 屏蔽（suspend） {#suspend-server}
无论数据在 30 天期限后被删除，还是被管理员提前强制删除，对应账户仍然可以被解除封禁。但是，该账户将不再与之关联的任何数据（状态、个人资料信息、头像或标题图像）。
对来自该服务器的所有帐户应用封禁（suspension）操作。本地将不储存除用户名外的任何数据。
对于外站账户，封禁将使其取消关注任何本站账户。即使外站账户在 30 天时间窗口内被解除封禁，这些关系也不会恢复。
## 反广告措施 {#spam-fighting-measures}
## 对整个站点进行审核 {#server-wide-moderation}
Mastodon有以下基本措施以阻止广告内容：
由于单个审核来自行为不端的站点的大量用户可能会很疲惫，因此可以使用**实例屏蔽**的功能对来自特定服务器的所有用户进行预先审核，这有几个不同的严重级别。
* 注册时需确认电子邮件地址
* 基于IP的注册频率限制
### 拒绝媒体 {#reject-media}
然而，专业广告发送者（spammer）将绕过这些措施。你可以应用的措施是**电子邮件域名屏蔽**。在注册期间，Mastodon将解析所给电子邮箱地址的A纪录或MX纪录，即电子邮件服务器的IP地址，并对照动态存储的黑名单中检查该IP地址。
启用此选项后，本站不会处理来自该实例的任何文件。这包括头像、背景横幅、表情与媒体附件。
### 屏蔽电子邮件域名 {#blocking-by-email-server}
### 限制 {#limit-server}
广告发送者（spammer）时常使用不同的电子邮件域名，以让他们看起来是使用许多不同的电子邮件服务器注册，而这些电子邮件域名很难被分别列入黑名单。但是，有时这些域名被解析到了同IP地址电子邮件服务器。如果你发现同一时间有大数广告发送者（spammer）注册，你可以使用在线DNS查询工具或 Linux `dig` 组件来检查，例如：`dig example.com` 将查询该域名的所有DNS A纪录。如果你注意到所有域名指向同一IP，你可以把它添加至电子邮件域名屏蔽列表中。
相当于[限制](#limit-user)来自该实例的所有过去和未来的账户。之前称为"隐藏"。
### 封禁IP {#blocking-by-ip}
### 封禁 {#suspend-server}
Mastodon自身不支持基于IP地址的访问者屏蔽，这不是一个万无一失的策略。IP有时会被不同的人共享，并时常会易手。但可以使用 Linux 防火墙来基于IP地址屏蔽访问者。下面的例子需要使用 `iptables` 和 `ipset`：
相当于[封禁](#suspend-user)来自该实例的所有过去和未来的账户。除用户名外，不会在本地存储来自该实例的任何内容。
封禁一个实例将删除本站账户与被封禁实例上账户之间的所有现存关注关系。如果外站实例稍后被解除封禁，这些关系不会恢复。
## 反垃圾信息措施 {#spam-fighting-measures}
Mastodon 中有一些基本措施来防止垃圾信息：
* 注册需要确认电子邮件地址
* 按 IP 地址限制注册速率
然而，专业的垃圾信息发送者会绕过这些措施。你可以采用的另一种措施是**电子邮件域名黑名单**。在注册过程中，Mastodon 会解析给定电子邮件地址的 A 或 MX 记录，即电子邮件服务器的 IP 地址，并检查该 IP 地址是否在动态存储的黑名单中。
### 按邮箱服务器屏蔽 {#blocking-by-e-mail-server}
垃圾信息发送者经常使用不同的电子邮件域名，使其看起来像是使用了许多不同的邮箱服务器，很难将这些域名全部添加到黑名单。但在某些情况下，所有这些域名都解析到单个邮箱服务器 IP。如果你看到大量垃圾信息发送者同时注册，你可以检查这一点，使用在线 DNS 查找工具或 Linux 的 `dig` 实用工具，例如 `dig example.com` 将返回该域的所有 DNS A 记录。如果你注意到所有域名的 IP 都相同，你可以将其添加到电子邮件域名黑名单中。
### 按 IP 屏蔽 {#blocking-by-ip}
在 Mastodon 本身中无法按 IP 地址屏蔽访问者，而且这不是一种万无一失的策略。 IP 有时由很多不同的人共享，且有时会更换。然而，可以在 Linux 中使用防火墙按 IP 地址屏蔽访问者。以下是使用 `iptables` 和 `ipset` 的示例：
```bash
# Install ipset
# 安装 ipset
sudo apt install ipset
# Create blacklist named "spambots"
# 创建名为 "spambots" 的黑名单
sudo ipset create spambots nethash
# Add 1.2.3.4 to the blacklist
# 将 1.2.3.4 添加到黑名单
sudo ipset add spambots 1.2.3.4
# Add firewall rule based on the blacklist
# 基于黑名单添加防火墙规则
sudo iptables -I INPUT 1 -m set --match-set spambots src -j DROP
```
但是注意，不要把你自己封禁了。
小心不要将自己锁在机器之外。
{{< translation-status-zh-cn raw_title="Moderation actions" raw_link="/admin/moderation/" last_tranlation_time="2020-05-08" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}}
### 用于审核级别事件的网络钩子 {#report-events-webhook}
你可以创建网络钩子，通过实时通知应用程序系统事件来促进审核API的自动化。这也实现了与 Discord、 IRC 和 Slack 等聊天应用的集成，有助于协调审核工作。
作为可选操作，你可使用来自 WebSub 规范的 X-Hub-Signature 标头来验证载荷的真实性。
当前支持的事件：
* account.approved
* account.created
* account.updated
* report.created
* report.updated
* status.created
* status.updated
#### 示例载荷：
```json
{
"event":"report.created",
"created_at":"2023-10-26T13:34:00.351Z",
"object":{
"id":"8437",
"action_taken":false,
"action_taken_at":null,
"category":"violation",
"comment":"",
"forwarded":true,
"created_at":"2023-10-26T13:34:00.348Z",
"updated_at":"2023-10-26T13:34:00.348Z",
"account":{
"id":"123456789",
"username":"bobisaburger",
"domain":null,
"created_at":"2023-07-13T04:39:22.493Z",
"email":"bobisaburger@emailservice.com",
"ip":"12.34.56.78",
"confirmed":true,
"suspended":false,
"silenced":false,
"sensitized":false,
"disabled":false,
"approved":true,
"locale":"en",
"invite_request":"I would love to be a member of your instance!",
"ips":[
{
"ip":"12.34.56.78",
"used_at":"2023-07-13T04:45:31.835Z"
},
{
"ip":"98.76.54.32",
"used_at":"2023-07-13T04:39:22.722Z"
}
],
"account":{
"id":"123456789",
"username":"bobisaburger",
"acct":"bobisaburger",
"display_name":"bobisaburger",
"locked":false,
"bot":false,
"discoverable":null,
"group":false,
"created_at":"2023-07-13T00:00:00.000Z",
"note":"",
"url":"https://mastodonwebsite/@bobisaburger",
"uri":"https://mastodonwebsite/users/bobisaburger",
"avatar":"https://locationofavatar.com/image.jpg",
"avatar_static":"https://locationofavatar.com/image.jpg",
"header":"locationofheader.com/image.jpg",
"header_static":"locationofheader.com/image.jpg",
"followers_count":100,
"following_count":200,
"statuses_count":9,
"last_status_at":"2023-08-05",
"noindex":true,
"emojis":[
],
"roles":[
],
"fields":[
]
},
"role":{
"id":"-99",
"name":"",
"permissions":"65536",
"color":"",
"highlighted":false
}
},
"target_account":{
"id":"123454321",
"username":"cheeseperson",
"domain":"someothermastodonsite.com",
"created_at":"2023-08-20T00:00:00.000Z",
"email":null,
"ip":null,
"confirmed":null,
"suspended":false,
"silenced":false,
"sensitized":false,
"disabled":null,
"approved":null,
"locale":null,
"invite_request":null,
"ips":null,
"account":{
"id":"123454321",
"username":"cheeseperson",
"acct":"cheeseperson@someothermastodonsite.com",
"display_name":"cheeseperson",
"locked":false,
"bot":false,
"discoverable":false,
"group":false,
"created_at":"2023-08-20T00:00:00.000Z",
"note":"",
"url":"https://someothermastodonsite.com/@cheeseperson",
"uri":"https://someothermastodonsite.com/users/cheeseperson",
"avatar":"https://someothermastadonsite.com/avatars/original/missing.png",
"avatar_static":"https://someothermastadonsite.com/avatars/original/missing.png",
"header":"locationofheader.com/image.jpg",
"header_static":"locationofheader.com/image.jpg",
"followers_count":2,
"following_count":2,
"statuses_count":95,
"last_status_at":"2023-10-26",
"emojis":[
],
"fields":[
]
},
"role":null
},
"assigned_account":null,
"action_taken_by_account":null,
"statuses":[
{
"id":"12345678987654321",
"created_at":"2023-10-26T11:29:13.000Z",
"in_reply_to_id":"1918282746465",
"in_reply_to_account_id":"101010101010",
"sensitive":false,
"spoiler_text":"",
"visibility":"public",
"language":"de",
"uri":"https://someothermastodonsite.com/users/cheeseperson/statuses/111301083360371621",
"url":"https://someothermastodonsite.com/@cheeseperson/111301083360371621",
"replies_count":0,
"reblogs_count":0,
"favourites_count":0,
"edited_at":"2023-10-26T11:30:31.000Z",
"content":"<p>Here is some content</p>",
"reblog":null,
"account":{
"id":"123454321",
"username":"cheeseperson",
"acct":"cheeseperson@someothermastodonsite.com",
"display_name":"cheeseperson",
"locked":false,
"bot":false,
"discoverable":false,
"group":false,
"created_at":"2023-08-20T00:00:00.000Z",
"note":"",
"url":"https://someothermastodonsite.com/@cheeseperson",
"uri":"https://someothermastodonsite.com/users/cheeseperson",
"avatar":"https://someothermastadonsite.com/avatars/original/missing.png",
"avatar_static":"https://someothermastadonsite.com/avatars/original/missing.png",
"header":"locationofheader.com/image.jpg",
"header_static":"locationofheader.com/image.jpg",
"followers_count":2,
"following_count":2,
"statuses_count":95,
"last_status_at":"2023-10-26",
"emojis":[
],
"fields":[
]
},
"media_attachments":[
],
"mentions":[
{
"id":"101010101010",
"username":"thirdperson",
"url":"https://thirdpersonsinstance.com/@thirdperson",
"acct":"thirdperson@emailwebsite.com"
}
],
"tags":[
],
"emojis":[
],
"card":null,
"poll":null
}
],
"rules":[
{
"id":"2",
"text":"不要做一个招人讨厌的人！"
}
]
}
}
```
{{< translation-status-zh-cn raw_title="Moderation actions" raw_link="/admin/moderation/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

10
content/zh-cn/admin/optional.md
View file

@ -1,5 +1,5 @@
---
title: 安装可选特色功能
title: 安装可选功能
menu:
docs:
weight: 40
@ -7,4 +7,10 @@ menu:
identifier: admin-optional
---
{{< translation-status-zh-cn raw_title="Installing optional features" raw_link="/admin/optional/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}}
Mastodon提供了一些可以根据需要使用的可选功能。
- [对象存储](./object-storage/)
- [匿名服务](./tor/)
- [单点登录](./sso/)
{{< translation-status-zh-cn raw_title="Installing optional features" raw_link="/admin/optional/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

34
content/zh-cn/admin/optional/captcha.md Normal file
View file

@ -0,0 +1,34 @@
---
title: 验证码
description: 缓解自动注册机器人的问题
menu:
docs:
weight: 30
parent: admin-optional
---
从 4.2 版本开始， Mastodon 支持使用验证码技术来帮助缓解机器人注册新账户的问题。
启用验证码后，新注册用户将需要在电子邮件验证过程中完成一个质询响应。
![](/assets/captcha/user-view.png)
{{< hint style="danger" >}}
对于某些人来说，使用中心化的验证码服务可能会引起安全和隐私方面的担忧。
此外，验证码可能会使注册过程的可访问性大大降低，尤其是对于视力障碍人士，如盲人或视力低下的人而言。
{{</ hint >}}
目前， hCaptcha 是 Mastodon 唯一支持的验证码提供商。
未来可能会添加其他提供商。
## hCaptcha
- 在 [hcaptcha.com](https://www.hcaptcha.com) 创建一个免费的 hCaptcha 账户
- 完成注册后，使用 hCaptcha 仪表板添加新站点，输入你的 Mastodon 站点域名并获取站点密钥(Site Key)
- 从 hCaptcha 的账户设置菜单中获取你的密钥(Secret Key)
- 将这些值添加到你的 Mastodon 环境配置中，分别添加 `HCAPTCHA_SITE_KEY` 和 `HCAPTCHA_SECRET_KEY`
- 重启服务器上运行的 Mastodon 服务
- 从 Mastodon 网页界面导航至**管理**>**服务器设置**>**注册**，并勾选标有"要求新用户解决验证码以确认其账户"的选项
![](/assets/captcha/admin-view.png)
{{< translation-status-zh-cn raw_title="Captcha" raw_link="/admin/optional/captcha/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

164
content/zh-cn/admin/optional/elasticsearch.md
View file

@ -1,164 +0,0 @@
---
title: 全文搜索
description: 设置Elasticsearch来搜索自己发出的嘟文、自己喜欢的嘟文、自己的书签和自己被提及的嘟文。
menu:
docs:
weight: 10
parent: admin-optional
---
当有可用Elasticsearch时，Mastodon支持全文搜索。Mastodon的全文搜索允许登录用户从他们自己的嘟文、他们喜欢的嘟文、他们的书签和他们被提及的嘟文中查找相应结果。Mastodon有意禁用了在全数据库搜索任意关键词的功能。
## 安装 Elasticsearch {#install}
Elasticsearch 需要 Java runtime。如果你还没有安装 Java，请立刻安装上它。以下操均假定你已经登录为`root`用户：
```bash
apt install openjdk-8-jre-headless
```
添加Elasticsearch官方软件仓库至apt：
```bash
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | apt-key add -
echo "deb https://artifacts.elastic.co/packages/6.x/apt stable main" | tee -a /etc/apt/sources.list.d/elastic-6.x.list
apt update
```
现在，你可以安装 Elasticsearch：
```bash
apt install elasticsearch
```
{{< hint style="warning" >}}
**安全警告：** 默认情况下，Elasticsearch仅绑定于localhost，即无法从外部网络访问。你可以通过查看 `/etc/elasticsearch/elasticsearch.yml` 中的 `network.host` 来检查 Elasticsearch 绑定了哪些地址。考虑到由于缺乏认证层，任何能访问 Elasticsearch 的人都可以读取或修改里面的数据。因此，确保访问安全非常重要。如[主要安装说明](../../prerequisites/#install-a-firewall-and-only-whitelist-ssh-http-and-https-ports)中所述，防火墙建议仅暴露了22、80、443端口。如果你是一个多主机配置，你必须知道如何保证内部流量安全。
{{< /hint >}}
{{< hint style="danger" >}}
**安全警告:** 由于近期Elasticsearch所使用的`log4j`库被披露出[安全漏洞](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44228)，使用了旧版本`log4j`(`2.0`到`2.14.1`)的ES可能会受到影响。如果使用了这些版本的`log4j`，请参阅 [此 issue](https://github.com/elastic/elasticsearch/issues/81618#issuecomment-991000240) 来暂时缓解此问题。
{{< /hint >}}
启动 Elasticsearch：
```bash
systemctl enable elasticsearch
systemctl start elasticsearch
```
## 配置 Mastodon {#config}
编辑 `.env.production`，添加如下变量：
```bash
ES_ENABLED=true
ES_HOST=localhost
ES_PORT=9200
```
如果你同一台机器上运行多个Mastodon服务器，你计划让它们使用同一个Elasticsearch，请确保他们都配置了互不重复的 `REDIS_NAMESPACE` 以分别他们的索引。如果你需要覆盖Elasticsearch索引前缀，你可以直接设置 `ES_PREFIX`。
保存新设置之后，使用如下命令创建Elasticsearch索引：
```bash
RAILS_ENV=production bundle exec rake chewy:upgrade
```
重启Mastodon进程以使新配置生效：
```bash
systemctl restart mastodon-sidekiq
systemctl reload mastodon-web
```
现在，新的嘟文将会被写入Elasticsearch索引。最后一步是导入所有旧有数据。这将花费很长一段时间：
```bash
RAILS_ENV=production bundle exec rake chewy:sync
```
{{< hint style="warning" >}}
**兼容性提示：** Ruby 2.6.0 由于已知Bug，无法进行上述操作。其它Ruby版本，例如：2.6.1，并不存在这个问题。
{{< /hint >}}
## 其它语言的搜索优化
### 中文搜索优化 {#chinese-search-optimize}
Elasticsearch默认使用标准分析器，这对于中文来说可能并不太适合。为了提高搜索体验，你可以安装特定语言的专用分析器。在创建Elasticsearch索引之前执行：
安装 [elasticsearch-analysis-ik](https://github.com/medcl/elasticsearch-analysis-ik)、[elasticsearch-analysis-stconvert](https://github.com/medcl/elasticsearch-analysis-stconvert) 插件至 Elasticsearch。
并对源码做出如下修改：
```diff
diff --git a/app/chewy/accounts_index.rb b/app/chewy/accounts_index.rb
--- a/app/chewy/accounts_index.rb
+++ b/app/chewy/accounts_index.rb
@@ -4,7 +4,7 @@ class AccountsIndex < Chewy::Index
settings index: { refresh_interval: '5m' }, analysis: {
analyzer: {
content: {
- tokenizer: 'whitespace',
+ tokenizer: 'ik_max_word',
filter: %w(lowercase asciifolding cjk_width),
},
diff --git a/app/chewy/statuses_index.rb b/app/chewy/statuses_index.rb
--- a/app/chewy/statuses_index.rb
+++ b/app/chewy/statuses_index.rb
@@ -16,9 +16,17 @@ class StatusesIndex < Chewy::Index
language: 'possessive_english',
},
},
+ char_filter: {
+ tsconvert: {
+ type: 'stconvert',
+ keep_both: false,
+ delimiter: '#',
+ convert_type: 't2s',
+ },
+ },
analyzer: {
content: {
- tokenizer: 'uax_url_email',
+ tokenizer: 'ik_max_word',
filter: %w(
english_possessive_stemmer
lowercase
@@ -27,6 +35,7 @@ class StatusesIndex < Chewy::Index
english_stop
english_stemmer
),
+ char_filter: %w(tsconvert),
},
},
}
diff --git a/app/chewy/tags_index.rb b/app/chewy/tags_index.rb
--- a/app/chewy/tags_index.rb
+++ b/app/chewy/tags_index.rb
@@ -2,10 +2,19 @@
class TagsIndex < Chewy::Index
settings index: { refresh_interval: '15m' }, analysis: {
+ char_filter: {
+ tsconvert: {
+ type: 'stconvert',
+ keep_both: false,
+ delimiter: '#',
+ convert_type: 't2s',
+ },
+ },
analyzer: {
content: {
- tokenizer: 'keyword',
+ tokenizer: 'ik_max_word',
filter: %w(lowercase asciifolding cjk_width),
+ char_filter: %w(tsconvert),
},
edge_ngram: {
```
{{< translation-status-zh-cn raw_title="Full-text search" raw_link="/admin/optional/elasticsearch/" last_tranlation_time="2020-05-05" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}}

129
content/zh-cn/admin/optional/object-storage-proxy.md Normal file
View file

@ -0,0 +1,129 @@
---
title: 通过 nginx 代理对象存储
description: 从自己的域名提供 Mastodon 中用户上传的文件
---
当使用 Amazon S3、Wasabi、Google Cloud 或其他对象存储提供商作为 Mastodon 的对象存储时，默认情况下，文件及其 URL 会通过存储提供商本身提供。这有以下缺点：
- 带宽通常是按量计费且非常昂贵
- 如果你决定稍后更换提供商，URL 将会失效
你可以选择从自己的域名提供文件，并在此过程中加入缓存机制。在 Mastodon 中，访问模式显示新文件经常被多个客户端同时访问，因为它们出现在通过流式 API 提供的新贴文中或通过联邦与州共享；相比之下，旧内容的访问频率较低。因此，仅依靠缓存并不能显著减少代理到实际对象存储的带宽使用。为了解决这个问题，我们可以实现一个缓存锁定机制，确保一次只进行一个代理请求。
以下是实现这一目标的nginx配置示例：
```nginx
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name files.example.com;
root /var/www/html;
ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
keepalive_timeout 30;
location = / {
index index.html;
}
location / {
try_files $uri @s3;
}
set $s3_backend 'https://YOUR_BUCKET_NAME.YOUR_S3_HOSTNAME';
location @s3 {
limit_except GET {
deny all;
}
resolver 8.8.8.8;
proxy_set_header Host YOUR_BUCKET_NAME.YOUR_S3_HOSTNAME;
proxy_set_header Connection '';
proxy_set_header Authorization '';
proxy_hide_header Set-Cookie;
proxy_hide_header 'Access-Control-Allow-Origin';
proxy_hide_header 'Access-Control-Allow-Methods';
proxy_hide_header 'Access-Control-Allow-Headers';
proxy_hide_header x-amz-id-2;
proxy_hide_header x-amz-request-id;
proxy_hide_header x-amz-meta-server-side-encryption;
proxy_hide_header x-amz-server-side-encryption;
proxy_hide_header x-amz-bucket-region;
proxy_hide_header x-amzn-requestid;
proxy_ignore_headers Set-Cookie;
proxy_pass $s3_backend$uri;
proxy_intercept_errors off;
proxy_cache CACHE;
proxy_cache_valid 200 48h;
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
proxy_cache_lock on;
expires 1y;
add_header Cache-Control public;
add_header 'Access-Control-Allow-Origin' '*';
add_header X-Cache-Status $upstream_cache_status;
add_header X-Content-Type-Options nosniff;
add_header Content-Security-Policy "default-src 'none'; form-action 'none'";
}
}
```
{{< hint style="info" >}}
我们使用 `$s3_backend` 作为变量来强制 nginx 对其值执行 DNS 解析，因为对象存储提供商的 IP 地址可能不会始终保持不变。
{{</ hint >}}
上述配置实现了以下效果：
- 阻止针对对象存储提供商的除 GET 请求之外的请求
- 阻止任何经过身份验证的请求到达对象存储提供商
- 阻止对象存储提供商设置cookie
- 移除对象存储提供商返回的不必要的标头信息
- 缓存有效文件最多 48 小时
- 如果对象存储不可用，允许使用旧缓存
- 使用缓存锁防止同时向对象存储发出请求
- 使返回的所有文件可被浏览器缓存长达一年
- 添加 Mastodon 网页界面所需的 CORS 头信息
- 添加一个特殊的头信息，告诉用户请求是否命中缓存
确保替换以下内容：
- `files.example.com`
- `YOUR_BUCKET_NAME`
- `YOUR_S3_HOSTNAME`
使用你的实际值，将配置保存到 `/etc/nginx/sites-available/files.example.com`，然后通过以下命令启用它：
```bash
ln -s /etc/nginx/sites-available/files.example.com /etc/nginx/sites-enabled/
systemctl reload nginx
```
你还需要为其获取SSL证书：
```bash
certbot --nginx -d files.example.com
systemctl reload nginx
```
最后，你需要确保 Mastodon 使用你的新代理生成文件 URL。编辑 Mastodon 的 `.env.production` 添加：
```bash
S3_ALIAS_HOST=files.example.com
```
然后重启 Mastodon：
```bash
systemctl restart mastodon-sidekiq
systemctl reload mastodon-web
```
{{< hint style="success" >}}
**现在你可以在浏览器中访问你的 Mastodon 以确认一切正常加载**
{{< /hint >}}
{{< translation-status-zh-cn raw_title="Proxying object storage through nginx" raw_link="/admin/optional/object-storage-proxy/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

320
content/zh-cn/admin/optional/object-storage.md Normal file
View file

@ -0,0 +1,320 @@
---
title: 对象存储
description: 使用外部对象存储来存储 Mastodon 中用户上传的文件
menu:
docs:
weight: 15
parent: admin-optional
---
用户上传的文件可以存储在主服务器的文件系统中，或者使用外部对象存储服务器。使用外部对象存储对于扩展 Mastodon 实例来说可能是必需的。
## 使用文件系统 {#FS}
最简单的存储用户上传文件的方式是使用服务器的文件系统。这是默认的工作方式，适用于小型服务器。
默认情况下， Mastodon 会将文件上传存储在安装目录下的 `public/system` 文件夹中，但可以通过使用 `PAPERCLIP_ROOT_PATH` 环境变量来覆盖此设置。
默认情况下，这些文件可以通过 `https://your-domain/system` 访问，可以使用 `PAPERCLIP_ROOT_URL` 和 `CDN_HOST` 来覆盖此访问路径。
{{< hint style="info" >}}
虽然使用服务器的文件系统对小型服务器来说完全可用，但使用外部对象存储更具可扩展性。
{{</ hint >}}
{{< hint style="danger" >}}
必须配置 Web 服务器，使其能够提供这些文件，但不允许列出它们（也就是说 `https://your-domain/system/` 不应返回文件列表）。如果你使用与 Mastodon 一起分发的配置文件，情况应该就是这样，但最好再次检查一下。
{{</ hint >}}
## 兼容 S3 的对象存储后端 {#S3}
Mastodon 可以使用兼容 S3 的对象存储后端。 建议支持 ACL，因为 ACL 允许 Mastodon 快速地让被封禁用户的媒体附件不可用，或略微提高私有数据的安全性。
Mastodon 使用 S3 API (`S3_REGION`, `S3_ENDPOINT`, `S3_BUCKET`,
`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `S3_SIGNATURE_VERSION`,
`S3_OVERRIDE_PATH_STYLE`) 进行所有的写入、删除和权限修改操作。这包括媒体上传（来自 Web 界面、 Mastodon API 客户端和 ActivityPub 服务器）、媒体删除（贴文被编辑或删除时）以及阻止对媒体的访问（当帐户被暂停时）。
Mastodon 会向 Web 界面、Mastodon API 客户端和 ActivityPub 服务器发送 URL，用于所有“读取”操作。因此，这些操作是匿名的（不需要身份验证或授权），并使用纯 HTTP GET 方法，这意味着它们可以通过反向代理和 CDN 路由并被缓存。 这也意味着这些 URL 可以包含与 S3 存储提供商本身使用的主机/域名完全不同的主机/域名（根据需要）。 请查看下面的详细文档，其中描述了如何构造这些 URL 以及涉及哪些环境变量。
要启用 S3 存储，请将 `S3_ENABLED` 环境变量设置为 `true`。
### 用于 S3 API 访问的环境变量
- `S3_REGION` (默认为 'us-east-1'，如果使用 AWS S3 则必需提供，使用其他存储提供商可能不需要)
- `S3_ENDPOINT` (默认为 'https://s3.<S3_REGION>.amazonaws.com'， 如果不使用 AWS S3 则必需提供)
- `S3_BUCKET=mastodata` (将 `mastodata` 替换为你的存储桶名称)
- `AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY` 需要设置为你的凭据
- `S3_SIGNATURE_VERSION` (默认为 'v4'，应该与大多数存储提供商兼容)
- `S3_OVERRIDE_PATH_STYLE` (仅当配置了 `S3_ENDPOINT` 时使用， 如果存储提供商要求将 API 操作发送到 '<S3_BUCKET>.<S3_ENDPOINT>`（域名样式），请将其设置为 `true`)
### 用于客户端访问媒体对象的环境变量
- `S3_PROTOCOL` (默认为 `https`)
- `S3_HOSTNAME` (默认为 's3-<S3_REGION>.amazonaws.com'， 如果不使用 AWS S3 且未设置 `S3_ALIAS_HOST`，则为必需)
- `S3_ALIAS_HOST` (如果你不希望 `S3_BUCKET` 包含在媒体 URL 中，可以使用 `S3_ALIAS_HOST` 代替 `S3_HOSTNAME`， 这需要你在存储提供商前面配置一个反向代理或 CDN)
如上所述，当客户端需要从存储提供商访问媒体对象时，Mastodon 将向客户端发送 URL。 这些 URL 构造如下：
- 如果未设置 `S3_ALIAS_HOST`，则 URL 将为 '<S3_PROTOCOL>://<S3_HOSTNAME>/<S3_BUCKET>/\<对象路径\>'
- 如果设置了 `S3_ALIAS_HOST`，则 URL 将为 '<S3_PROTOCOL>://<S3_ALIAS_HOST>/\<对象路径\>'
注意，当设置了 `S3_ALIAS_HOST` 时，存储桶名称 **不** 包含在生成的 URL 中； 这意味着存储桶名称必须包含在 `S3_ALIAS_HOST` 中（称为“域名样式”对象访问），或者 `S3_ALIAS_HOST` 必须指向一个反向代理或 CDN，它可以将存储桶名称包含在用于将请求发送到存储提供商的 URL 中。 这种类型的配置允许你从实例的客户端“隐藏”存储提供商，这意味着你可以更改存储提供商，而无需更改生成的 URL。
除隐藏存储提供商之外，这还可以让你在从存储提供商拉取媒体后缓存媒体，从而降低存储提供商的出口带宽成本。 这可以在你自己的反向代理中完成，也可以通过使用 CDN 来完成。
{{< page-ref page="admin/optional/object-storage-proxy.md" >}}
{{< hint style="info" >}}
你必须使用 CORS 标头来提供文件，否则 Mastodon Web UI 的某些功能将无法正常工作。 例如，`Access-Control-Allow-Origin: *`
{{</ hint >}}
### 可选环境变量
#### `S3_OPEN_TIMEOUT`
默认值：5 (秒)
HTTP 处理程序在尝试打开新的 HTTP 会话时应超时的秒数。
#### `S3_READ_TIMEOUT`
默认值：5 (秒)
HTTP 处理程序在等待 HTTP 响应时应超时的秒数。
#### `S3_FORCE_SINGLE_REQUEST`
默认值：false
如果你在处理大型文件时遇到问题，请将其设置为 `true`。
#### `S3_ENABLE_CHECKSUM_MODE`
默认值：false
使在 Mastodon 从存储提供商检索对象时验证对象校验和。 此功能在 AWS S3 中可用，但在其他兼容 S3 的实现中可能不可用。
#### `S3_STORAGE_CLASS`
默认值：none
当使用 AWS S3 时，此变量可以设置为 [存储类](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-class-intro.html) 的其中一个选项，这些选项会影响所选的用于上传对象的存储（以及它们的访问时间和成本）。 如果未指定存储类，则 AWS S3 将使用 `STANDARD` 类，但选项包括 `REDUCED_REDUNDANCY`、`GLACIER` 等。
#### `S3_MULTIPART_THRESHOLD`
默认值：15 (兆字节)
此大小及以下的对象将以单个操作上传，但更大的对象将使用多部分分块机制上传，这可以提高传输速度和可靠性。
#### `S3_PERMISSION`
默认值：`public-read`
定义上传新文件时的 S3 对象 ACL。 使用 [S3 阻止公共访问](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-control-block-public-access.html) 并启用 `BlockPublicAcls` 选项时请谨慎，因为使用 ACL `public-read` 上传对象将失败 (403)。 在这种情况下，需将 `S3_PERMISSION` 设置为 `private`。
{{< hint style="danger" >}}
无论 ACL 配置如何，你的 S3 存储桶都必须设置为确保所有对象都是公共可读，但不可写或可列出。 同时，Mastodon 本身应该对存储桶具有写入权限。 此配置通常在所有 S3 提供商中保持一致，常用提供商在本指南后面会重点介绍。
{{</ hint >}}
#### `S3_BATCH_DELETE_LIMIT`
默认值: `1000`
官方的 [Amazon S3 API](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) 可以处理在一个批处理作业中删除 1,000 个对象，但一些提供商可能在处理一个请求中的这么多对象时遇到问题，或者提供更低的限制。
#### `S3_BATCH_DELETE_RETRY`
默认值: 3
在批处理删除操作期间，S3 提供商可能会在处理删除请求时周期性地失败或超时。 Mastodon 会退避并重试该请求，直到达到最大重试次数。
### MinIO
MinIO 是 S3 对象提供程序的开源实现。 本节不介绍如何安装它，而是介绍如何配置存储桶以在 Mastodon 中使用。
你需要为匿名访问设置一个策略，该策略允许对存储桶包含的对象进行只读访问，而不允许列出它们。
为此，你需要设置一个自定义策略（将 `mastodata` 替换为你的 S3 存储桶的实际名称）：
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"*"
]
},
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::mastodata/*"
]
}
]
}
```
Mastodon 本身需要能够写入存储桶，因此请使用你的 MinIO 管理员帐户（不建议）或附加以下策略的 Mastodon 专用帐户（建议）（将 `mastodata` 替换为你的 S3 存储桶的实际名称）：
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": "arn:aws:s3:::mastodata/*"
}
]
}
```
你可以通过 MinIO 控制台（基于 Web 的用户界面）或命令行客户端 (`mcli` / `mc`) 设置这些策略。
#### 使用 MinIO 控制台
连接到 MinIO 控制台 Web 界面并创建一个新存储桶（或导航到你现有的存储桶）：
![](/assets/object-storage/minio-bucket.png)
然后，将“访问策略”配置为允许读取访问 (`s3:GetObject`) 而未写入访问或列出对象的能力的自定义策略（见上文）：
![](/assets/object-storage/minio-access-policy.png)
{{< hint style="info" >}}
如果 MinIO 控制台不允许你设置“自定义”策略，则可能需要更新 MinIO。 如果你在 *独立* 或 *文件系统* 模式下使用 MinIO，则 [`RELEASE.2022-10-24T18-35-07Z`](https://github.com/minio/minio/releases/tag/RELEASE.2022-10-24T18-35-07Z) 应该是一个安全的更新版本，不需要 [涉及迁移过程](https://min.io/docs/minio/linux/operations/install-deploy-manage/migrate-fs-gateway.html#migrate-from-gateway-or-filesystem-mode)。
{{< /hint >}}
新建一个 `mastodon-readwrite` 策略（见上文）：
![](/assets/object-storage/minio-mastodon-readwrite.png)
最后，使用 `mastodon-readwrite` 策略创建一个新的 `mastodon` 用户：
![](/assets/object-storage/minio-mastodon-user.png)
#### 使用命令行实用程序
使用 [MinIO 客户端](https://min.io/docs/minio/linux/reference/minio-mc.html) 命令行实用程序（可以根据安装位置调用 `mc` 或 `mcli`）也可以实现相同的目的。
创建一个新存储桶：
`mc mb myminio/mastodata`
将上面的匿名访问策略保存为 `anonymous-readonly-policy.json`，并将 Mastodon 用户访问策略保存为 `mastodon-readwrite.json`（确保将 `mastodata` 替换为你新创建的存储桶的名称）。
设置存储桶的匿名访问策略：
`mc anonymous set-json anonymous-readonly-policy.json myminio/mastodata`
添加 `mastodon-readwrite` 策略:
`mc admin policy add myminio mastodon-readwrite mastodon-readwrite.json`
添加 `mastodon` 用户（替换密码）：
`mc admin user add myminio mastodon SECRET_PASSWORD`
将 `mastodon-readwrite` 策略应用到 `mastodon` 用户：
`mc admin policy set myminio mastodon-readwrite user=mastodon`
### Wasabi 对象存储
创建一个新存储桶并定义其策略，允许对象进行匿名读取但不可列出：
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::mastodata/*"
}
]
}
```
![](/assets/object-storage/wasabi-access-policy.png)
{{< hint style="info" >}}
如果你使用旧存储桶，请确保你没有通过 Wasabi 的旧版访问控制设置授予“所有人”读取对象的权限，因为该设置允许列出对象并优先于上面定义的 IAM 策略。
![](/assets/object-storage/wasabi-access-control.png)
{{< /hint >}}
然后，创建一个 `mastodon-readwrite` 策略以授予对你的存储桶的读写访问权限：
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": "arn:aws:s3:::mastodata/*"
}
]
}
```
![](/assets/object-storage/wasabi-mastodon-readwrite.png)
最后，创建一个新的 `mastodon` 用户，并且不要忘记启用 `mastodon-readwrite` 策略：
![](/assets/object-storage/wasabi-mastodon-user.png)
在 Mastodon 端，你需要设置`S3_FORCE_SINGLE_REQUEST=true`来正确处理大型上传。
### DigitalOcean Spaces
在你的 DigitalOcean Spaces 存储桶中，确保“文件列表”对于拥有访问密钥的用户是“受限制的”。
![](/assets/object-storage/do-spaces.png)
### Scaleway
如果你想使用 Scaleway 对象存储，我们强烈建议你创建一个专用于 Mastodon 实例资产的 Scaleway 项目，并使用自定义 IAM 策略。
首先，创建一个新的 Scaleway 项目，在其中创建对象存储桶。 你需要将存储桶的可见性设置为“私有”，以不允许列出对象。
![](/assets/object-storage/scaleway-bucket.png)
现在你的存储桶已创建，你需要创建 API 密钥，以便在你的 Mastodon 实例配置中使用。
前往 IAM 设置（在你的组织菜单中，屏幕的右上角），然后创建一个新的 IAM 策略（例如 `mastodon-media-access`）
![](/assets/object-storage/scaleway-policy.jpg)
此策略需要有一个规则，允许它在你上面创建的 Scaleway 项目（作用域）中读取、写入和删除对象。
![](/assets/object-storage/scaleway-policy-rules.jpg)
然后前往 IAM 应用程序页面，创建一个新的应用程序（例如 `my-mastodon-instance`），并选择你上面创建的策略。
最后，单击你创建的应用程序，然后单击“API 密钥”，并创建一个新的 API 密钥，以便在你的实例配置中使用。 你应该使用“是，设置首选项目”选项，并选择你上面创建的项目作为此密钥的默认项目。
![](/assets/object-storage/scaleway-api-key.png)
复制 Access Key ID 和 Secret，并将它们用于你的 `AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY` 这两个 Mastodon 配置变量。
### Exoscale
在 Exoscale 中，你的存储桶不应有任何读取 ACL（Mastodon 将根据需要在对象本身上设置 ACL）。
你需要为 Mastodon 应用程序创建一个 API 密钥，该密钥限于对象存储 (`sos`) 服务，限于你的存储桶，并且操作不受限制。
![](/assets/object-storage/exoscale.png)
在 Mastodon 端，你需要设置`S3_FORCE_SINGLE_REQUEST=true`才能正确处理大型上传。
### Cloudflare R2
Cloudflare R2 不支持 ACL，因此需要指示 Mastodon 不尝试设置他们。 为此，需要将 `S3_PERMISSION` 环境变量设置为空字符串。
{{< hint style="warning" >}}
如果不支持 ACL，被封禁的用户的媒体文件仍然可以访问。
{{< /hint >}}
要获取在 Mastodon 中使用的凭据，请选择“管理 R2 API 令牌”并创建一个新的 API 令牌，具有“编辑”权限。
{{< hint style="warning" >}}
本节正在建设中。
{{< /hint >}}
{{< translation-status-zh-cn raw_title="Object storage" raw_link="/admin/optional/object-storage/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

10
content/zh-cn/admin/optional/sso.md
View file

@ -1,13 +1,15 @@
---
title: 单点登录（SSO）
title: 单点登录
menu:
docs:
weight: 30
weight: 40
parent: admin-optional
---
{{< hint style="danger" >}}
本页面仍在建设中。
此页面正在建设中。
目前，请参考[这个拉取请求](https://github.com/mastodon/mastodon/pull/16221)
{{< /hint >}}
{{< translation-status-zh-cn raw_title="Single Sign On" raw_link="/admin/optional/sso/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}}
{{< translation-status-zh-cn raw_title="Single Sign On" raw_link="/admin/optional/sso/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

62
content/zh-cn/admin/optional/tor.md
View file

@ -1,31 +1,31 @@
---
title: 匿名服务
description: 通过Tor的匿名服务来访问Mastodon。
title: 洋葱服务
description: 通过 Tor 洋葱服务提供 Mastodon 服务。
menu:
docs:
weight: 20
parent: admin-optional
---
可以通过Tor的匿名服务来访问Mastodon。这将给你一个只能通过 Tor 网络连接的 \*.onion 地址。
Mastodon 可以通过 Tor 作为洋葱服务提供服务。这将为你提供一个 `*.onion` 地址，该地址只能在连接到 Tor 网络时使用。
## 安装 Tor {#install}
首先，Tor的Debian软件仓库需要被添加至apt中。
首先需要将 Tor 的 Debian 存储库添加到 apt 中。
```text
deb https://deb.torproject.org/torproject.org stretch main
deb-src https://deb.torproject.org/torproject.org stretch main
```
接下来，添加相应gpg密钥。
接下来添加 gpg 密钥。
```bash
curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --import
gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | apt-key add -
```
最后，安装所需软件包。
最后安装所需的软件包。
```bash
apt install tor deb.torproject.org-keyring
@ -33,10 +33,10 @@ apt install tor deb.torproject.org-keyring
## 配置 Tor {#configure}
编辑 `/etc/tor/torrc` 并添加如下设置。
编辑 `/etc/tor/torrc` 文件并添加以下配置。
```text
HiddenServiceDir /var/lib/tor/hidden_service/
HiddenServiceDir /var/lib/tor/onion_service/
HiddenServiceVersion 3
HiddenServicePort 80 127.0.0.1:80
```
@ -47,34 +47,37 @@ HiddenServicePort 80 127.0.0.1:80
sudo service tor restart
```
现在，你的Tor域名可以在 `/var/lib/tor/hidden_service/hostname` 找到。
现在你可以在 `/var/lib/tor/hidden_service/hostname` 中找到你的 Tor 主机名。
## 移动你的Mastodon配置 {#nginx}
## 移动你的 Mastodon 配置 {#nginx}
我们将需要将你的Mastodon配置告诉Nginx两次。为了不自我重复（[DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)），我们需要将Mastodon配置移动到一个可被引用的独立文件。
我们需要在 Nginx 中配置两次 Mastodon。为了保持["DRY"](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)原则，我们需要将 Mastodon 配置移到自己的文件中，以便之后可以引用。
在 `/etc/nginx/snippets/mastodon.conf` 创建一个新文件。放入除`listen`、`server_name`、`include`及所有SSL相关选项之外的所有配置参数至新文件中。你的新文件看起来可能像这样。
创建一个新文件 `/etc/nginx/snippets/mastodon.conf`。复制所有 Mastodon 配置参数，除了 `listen`、`server_name`、`include` 指令以及所有 SSL 选项。包含一个 `Onion-Location` 头，让支持的浏览器知道该服务也可以通过 Tor 访问。你的新文件应该看起来像这样：
```text
```nginx
add_header Referrer-Policy "same-origin";
add_header Onion-Location mastodon.qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7.onion$request_uri;
keepalive_timeout 70;
sendfile on;
client_max_body_size 80m;
root /home/mastodon/live/public;
…
# …
error_page 500 501 502 503 504 /500.html;
access_log /var/log/nginx/mastodon_access.log;
error_log /var/log/nginx/mastodon_error.log warn;
```
替换你的旧Mastodon配置文件，在新配置文件中添加一个include指令。
在新的配置文件中，在原来 Mastodon 配置的位置添加 `include` 指令。
你的Nginx配置文件将看起来像这样。
你的 Nginx 配置文件现在应该看起来像这样：
```text
```nginx
server {
listen 80;
server_name mastodon.example.com;
@ -97,13 +100,15 @@ server {
}
```
## 通过http提供Tor服务 {#http}
## 通过 HTTP 提供 Tor 服务 {#http}
尽管通过https提供你的Tor版Mastodon可能很诱人，但对大多数人来说这不是一个好主意。请参阅Tor Project上的[这篇](https://blog.torproject.org/facebook-hidden-services-and-https-certs)博文，了解为什么https证书无法增加价值。由于你无法获得onion域名的SSL证书，当你尝试使用你的Mastodon时还会被证书错误所困扰。最近，一位Tor开发者在[这里](https://matt.traudt.xyz/p/o44SnkW2.html)阐述了为什么通过https提供Tor服务对大多数用例都没有好处的原因。
本节假设你希望同时在 Tor 和公共互联网上公开你的实例。
解决方法是通过http提供你的Mastodon服务，但仅供Tor使用。这可以通过在Nginx配置文件中添加额外的设置来完成。
虽然通过 HTTPS 提供 Mastodon 的 Tor 版本看起来很诱人，但这并不总是理想的选择。HTTPS 证书主要对能够使用自己的公司信息生成证书的大公司有用。没有证书颁发机构(CA)能[免费](https://community.torproject.org/onion-services/advanced/https/)提供它们，Tor 项目的[一篇博客文章](https://blog.torproject.org/facebook-hidden-services-and-https-certs)也解释了为什么 HTTPS 证书对安全性并没有真正的好处。但另一方面，Mastodon 使用了大量使用到 HTTPS 的重定向，有经过验证的证书可能会使你的用户更容易在 Tor 上使用你的实例，而无需手动删除 URL 中的 `https://` 前缀。
```text
在本节中，我们将介绍如何通过 HTTP 提供 Mastodon 实例，但仅限于 Tor。这可以通过在现有 Nginx 配置前添加额外配置来实现。
```nginx
server {
listen 80;
server_name mastodon.qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7.onion;
@ -132,11 +137,11 @@ server {
}
```
用你位于 `/var/lib/tor/hidden_service/hostname` 文件中的长hash替换上文中提供的。
用 `/var/lib/tor/hidden_service/hostname` 文件中的 Tor 域名替换这里提供的长哈希值。这也应该反映在 snippets 文件中的 `Onion-Location` 头中。
请注意，onion域名已经被附加了“mastodon.”前缀。你的Tor地址充当通配符域名。所有的子域名都将被路由，你可以配置你的Nginx来响应你想要的任何子域名。如果你不想在你的tor域名上托管任何其他服务，你可以省略子域名，或者选择一个不同的子域名。
注意洋葱主机名前面加了 "mastodon."。你的 Tor 地址充当通配符域名。所有子域名都会被路由，你可以配置 Nginx 响应你想要的任何子域名。如果你不希望在 Tor 地址上托管任何其他服务，可以省略子域名，或选择不同的子域名。
这里，你就可以看出移动你的mastodon配置到不同文件的好处了。如果不移动的话，你的所有配置都必须粘贴至两个地方，任何对你配置的改动你都必须同时修改两个地方。
现在你可以看到将 mastodon 配置移动到不同文件的好处。如果不这样做，所有配置都必须复制到两个地方。对配置的任何更改都必须在两个地方进行。
重启你的Web服务器。
@ -144,10 +149,11 @@ server {
service nginx restart
```
## 陷阱 {#gotchas}
## 注意事项 {#gotchas}
你需要注意一些事情。某些重定向会将你的用户跳转至https。他们必须手动把URL替换成http才能继续。
你需要注意几点事项：
许多的资源，诸如图片，将仍然从常规非Tor域名加载。问题的严重性很大程度上取决于用户的谨慎程度。
- 如前所述，Mastodon前端的某些URL会强制用户使用HTTPS URL。他们必须手动将URL替换为HTTP才能继续。
- 各种资源，如图像，仍将通过你常规的明网域名提供。这可能会成为问题，具体取决于你的用户希望、尝试或需要多高的隐私程度。
{{< translation-status-zh-cn raw_title="Hidden services" raw_link="/admin/optional/tor/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}}
{{< translation-status-zh-cn raw_title="Onion services" raw_link="/admin/optional/tor/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

106
content/zh-cn/admin/prerequisites.md
View file

@ -1,20 +1,24 @@
---
title: 准备你的机器
title: 准备你的服务器
menu:
docs:
weight: 10
parent: admin
---
如果你正在设置一台全新的机器，推荐你首要完成安全设置。以下内容假定你运行 **Ubuntu 18.04**：
如果你正在设置一台全新的服务器，建议你首先进行安全设置。假设你运行的是**Ubuntu 22.04**：
## 禁止密码登录SSH（仅允许密钥登录）
## 禁用基于密码的 SSH 登录(仅限密钥)
首先，请确保你实际上是通过密钥而不是通过密码登录到服务器的，否则这将使你无法登录。许多托管服务提供商支持上传公钥，并自动为新机器设置基于密钥的root登录。
首先，你需要确保自己现在已经是在使用密钥而非密码登录服务器，否则，这将使你无法登录。许多托管提供商支持上传公钥，并自动为新机器设置基于密钥的 root 登录。
编辑 `/etc/ssh/sshd_config` 并找到 `PasswordAuthentication`。确保它已被去除注释并被设为 `no`。如果你做了任何改动，请重启 sshd。
编辑 `/etc/ssh/sshd_config` 并找到 `PasswordAuthentication`。确保它已取消注释并设置为 `no`。做出更改后，请重启sshd：
## 更新系统
```bash
systemctl restart ssh.service
```
## 更新系统包
```bash
apt update && apt upgrade -y
@ -22,7 +26,13 @@ apt update && apt upgrade -y
## 安装 fail2ban 以阻止重复登录尝试
编辑 `/etc/fail2ban/jail.local` 并添加以下内容：
首先，安装fail2ban：
```bash
apt install fail2ban
```
编辑 `/etc/fail2ban/jail.local` 并在其中填入以下内容：
```text
[DEFAULT]
@ -32,66 +42,110 @@ sendername = Fail2Ban
[sshd]
enabled = true
port = 22
[sshd-ddos]
enabled = true
port = 22
mode = aggressive
```
最后重启fail2ban：
最后，重启 fail2ban：
```bash
systemctl restart fail2ban
```
## 安装防火墙并只暴露SSH、HTTP、HTTPS端口
## 安装防火墙并只允许 SSH、 HTTP 和 HTTPS 端口
首先，安装 iptables-persistent。在安装期间，它将询问你是否保留现有规则。
首先，安装 iptables-persistent。在安装过程中，它会询问你是否要保留当前规则——选择拒绝。
```bash
apt install -y iptables-persistent
```
编辑 `/etc/iptables/rules.v4` 并添加如下内容：
编辑 `/etc/iptables/rules.v4` 并在其中填入以下内容：
```text
*filter
# Allow all loopback (lo0) traffic and drop all traffic to 127/8 that doesn't use lo0
# 允许所有回环(lo0)流量，拒绝所有不通过 lo0 接口访问 127/8 地址段的流量
-A INPUT -i lo -j ACCEPT
-A INPUT ! -i lo -d 127.0.0.0/8 -j REJECT
# Accept all established inbound connections
# 接受所有已建立的入站连接
-A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
# Allow all outbound traffic - you can modify this to only allow certain traffic
# 允许所有出站流量 - 你可以修改此规则以实现只允许特定流量
-A OUTPUT -j ACCEPT
# Allow HTTP and HTTPS connections from anywhere (the normal ports for websites and SSL).
# 允许来自任何地方的 HTTP 和与HTTPS 连接(网站和 SSL 服务的标准端口)
-A INPUT -p tcp --dport 80 -j ACCEPT
-A INPUT -p tcp --dport 443 -j ACCEPT
# Allow SSH connections
# The -dport number should be the same port number you set in sshd_config
# (可选)允许来自任何位置的 HTTP/3 连接
-A INPUT -p udp --dport 443 -j ACCEPT
# 允许 SSH 连接
# 这里的端口号应该与你在 sshd_config 中设置的端口号一致
-A INPUT -p tcp -m state --state NEW --dport 22 -j ACCEPT
# Allow ping
# 允许 ping 请求
-A INPUT -p icmp -m icmp --icmp-type 8 -j ACCEPT
# Log iptables denied calls
# 允许目标不可达消息，这里类型 4(需要分片)的消息对于 PMTUD (路径 MTU 发现)功能至关重要
-A INPUT -p icmp -m icmp --icmp-type 3 -j ACCEPT
# 记录被 iptables 拒绝的请求
-A INPUT -m limit --limit 5/min -j LOG --log-prefix "iptables denied: " --log-level 7
# Reject all other inbound - default deny unless explicitly allowed policy
# 拒绝所有其他入站请求 - 默认拒绝策略，除非明确允许
-A INPUT -j REJECT
-A FORWARD -j REJECT
COMMIT
```
iptables-persistent 将在机器启动时自动加载配置。但是由于我们现在不会立刻重启，我们需要第一次手动加载它：
通过使用 iptables-persistent 进行配置，该配置将在启动时加载。但由于我们现在不重启，所以需要手动加载一次：
```bash
iptables-restore < /etc/iptables/rules.v4
```
{{< translation-status-zh-cn raw_title="Preparing your machine" raw_link="/admin/prerequisites/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}}
如果你的服务器也可以通过 IPv6 访问，编辑`/etc/iptables/rules.v6`并添加以下内容：
```text
*filter
# 允许所有本地回环(lo0)流量，并拒绝所有不通过 lo0 接口访问 127/8 地址段的流量
-A INPUT -i lo -j ACCEPT
-A INPUT ! -i lo -d ::1/128 -j REJECT
# 接受所有已建立的入站连接
-A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
# 允许所有出站流量 - 你可以修改此规则以实现只允许特定的流量
-A OUTPUT -j ACCEPT
# 允许来自任何位置的 HTTP 和 HTTPS 连接(网站和 SSL 服务的标准端口)
-A INPUT -p tcp --dport 80 -j ACCEPT
-A INPUT -p tcp --dport 443 -j ACCEPT
# (可选) 允许来自任何位置的 HTTP/3 连接
-A INPUT -p udp --dport 443 -j ACCEPT
# 允许 SSH 连接
# 这里的端口号应与 sshd_config 中设置的端口号一致
-A INPUT -p tcp -m state --state NEW --dport 22 -j ACCEPT
# 允许 ping
-A INPUT -p icmpv6 -j ACCEPT
# 记录被 iptables 拒绝的请求
-A INPUT -m limit --limit 5/min -j LOG --log-prefix "iptables denied: " --log-level 7
# 拒绝所有其他入站连接 - 默认拒绝策略，除非明确允许
-A INPUT -j REJECT
-A FORWARD -j REJECT
COMMIT
```
与 IPv4 规则类似，你可以这样手动加载它：
```bash
ip6tables-restore < /etc/iptables/rules.v6
```
{{< translation-status-zh-cn raw_title="Preparing your machine" raw_link="/admin/prerequisites/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

100
content/zh-cn/admin/roles.md Normal file
View file

@ -0,0 +1,100 @@
---
title: 用户组
description: 通过管理员仪表板管理用户组。
menu:
docs:
parent: admin
---
# 用户组 {#roles}
数据库初始化时，用户组是从[`~/config/roles.yml`](https://github.com/mastodon/mastodon/blob/main/config/roles.yml)中的值派生的。
{{< page-ref page="entities/Role" >}}
生成的[默认用户组](#default-roles)有`所有者`、`管理员`和`协管员`。
可以使用*用户组*(`/admin/roles`)页面上的[添加用户组](#add-role)来创建用户组及其属性。
![](/assets/admin-roles-ui.png)
可以使用[编辑用户组](#edit-role)功能更改现有用户组的属性。
## 默认用户组 {#default-roles}
### 基础用户组（*默认权限*） {#default-base-role}
影响所有用户，包括没有分配用户组的用户。
此用户组唯一可修改的权限标识是**邀请用户**。启用此权限允许所有用户发送邀请。
基础用户组的优先级为`0`，此值不能更改。
### 所有者 {#default-owner-role}
被分配了**管理员**权限标识的用户组，绕过所有权限检查。具有所有者用户组的用户拥有每一个[权限标识](/entities/Role/#permission-flags)。
可以更改该用户组的*名称*、*徽章颜色*和*显示徽章*属性。该用户组的权限不能被编辑/撤销。
所有者用户组具有最高的[优先级](#role-priority)(`1000`)。所有者可以修改任何其他用户组的属性。创建的用户组不能超越所有者用户组，因为新的和现有用户组的[用户组优先级](#role-priority)必须 <= `999`。
### 管理员 {#default-admin-role}
被分配了所有**审核**和**管理**权限标识的用户组。
此用户组的**DevOps**权限标识默认禁用，但可以由**所有者**(或具有更高优先级的自定义用户组)启用。
可以更改该用户组的*名称*、*徽章颜色*和*显示徽章*属性。
管理员用户组的优先级为`100`。
### 协管员 {#default-moderator-role}
被分配了某些**审核**权限标识的用户组。这些权限标识包括...
- **查看仪表板**
- **查看审计日志**
- **管理用户**
- **管理举报**
- **管理分类**
可以更改该用户组的*名称*、*徽章颜色*和*显示徽章*属性。
协管员用户组的优先级为`10`。
## 添加用户组 {#add-role}
`admin/roles/new`页面允许创建自定义用户组。
![](/assets/admin-roles-new-ui.png)
### 输入字段 {#add-role-input-fields}
{{< page-relref ref="entities/Role#name" caption="名称">}}
可以存在重复的用户组名称。它们在数据库中通过`id`区分，该`id`不能从网页界面设置。
{{< page-relref ref="entities/Role#color" caption="徽章颜色">}}
### 优先级 {#role-priority}
- 默认为`0`
- 不能 > `999`
- 可以是任何负整数值
- 两个用户组可以具有相同的优先级值
> "在特定情况下，由更高优先级的用户组决定冲突解决方式。某些操作只能对优先级较低的用户组执行。"
{{< page-relref ref="entities/Role#highlighted" caption="在账户页面显示用户组徽章">}}
{{< page-relref ref="entities/Role#permissions" caption="权限">}}
## 编辑用户组 {#edit-role}
![](/assets/admin-roles-edit-ui.png)
可以使用用户组列表中的*编辑*来编辑现有用户组及其属性。[输入字段](#add-role-input-fields)可以更改和保存，就像创建新用户组时一样。也可以使用此表单删除用户组。
![](/assets/admin-roles-edit-role-ui.png)
具有**管理用户组**权限的已登录用户始终能够看到每个用户组，但不能修改超过或等于其分配用户组[优先级](#role-priority)的用户组。
{{< translation-status-zh-cn raw_title="Roles" raw_link="/admin/roles/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

373
content/zh-cn/admin/scaling.md
View file

@ -1,218 +1,283 @@
---
title: 伸缩你的服务器
descriptions: 为服务更多用户而优化。
title: 扩大你的站点规模
descriptions: 为服务更多用户可以进行的优化。
menu:
docs:
weight: 100
parent: admin
---
## 并发管理 {#concurrency}
## 管理并发度 {#concurrency}
Mastodon有三种进程：
Mastodon 有三种类型的进程：
* Web (Puma)
* Streaming API
* 后台进程 (Sidekiq)
- Web (Puma)
- 流式 API
- 后台处理 (Sidekiq)
### Web (Puma) {#web}
web进程处理绝大多数应用的短HTTP请求。以下环境变量可以控制它：
Web 进程处理应用大部分的短周期 HTTP 请求。可通过以下环境变量控制并发度：
* `WEB_CONCURRENCY` 控制worker进程数
* `MAX_THREADS` 控制每进程的线程数
- `WEB_CONCURRENCY` 控制工作进程的数量
- `MAX_THREADS` 控制每个进程的线程数量
线程共享其父进程的内存。不同的线程被分配了专有内存，虽然他们通过copy-on-write共享了一些内存。数量较多的线程会先消耗掉你的CPU，数量较多的进程会先消耗掉你的内存。
线程共享其父进程的内存。不同的进程分配自己的内存，但通过写时复制共享一些内存。增加线程数量会优先耗尽你的 CPU，而增加进程数量会先耗尽你的 RAM。
这些数值会影响到可以同时处理多少HTTP请求。
上述变量的值可以影响同时能处理多少 HTTP 请求。
在吞吐量方面，多进程比多线程要好。
就吞吐量指标而言，增加进程数量比增加线程数量效果更好。
### Streaming API {#streaming}
### 流式 API {#streaming}
streaming API处理长HTTP连接与WebSockets连接，通过这些连接用户可以接受到实时更新。以下环境变量可以控制它：
流式 API 处理长周期 HTTP 和 WebSocket 连接，客户端通过这些连接接收实时更新。可通过以下环境变量控制并发度：
* `STREAMING_CLUSTER_NUM` 控制worker进程数
* `STREAMING_API_BASE_URL` 控制streaming API的base URL
- `STREAMING_API_BASE_URL` 控制流式 API 的根 URL
- `PORT` 控制流式 API 服务器将监听的端口，默认为4000。`BIND`和`SOCKET`环境变量也可以使用。
- 此外，流式 API 还使用共享的[数据库](/admin/config#postgresql)和 [Redis](/admin/config#redis) 环境变量。
一个进程可以处理相当数量的连接。 如果您愿意，streaming API可以托管在其他子域上，例如：避免nginx代理连接开销。
通过设置 `STREAMING_API_BASE_URL`，流式 API 可以使用不同的子域。这允许你为流式 API 和 Web API 请求使用不同的负载均衡器。然而，这也要求应用程序从[实例端点](/methods/instance/#v2)正确请求流式 API URL，而不是假设它与 Web API 托管在同一域名上。
### 后台进程 (Sidekiq) {#sidekiq}
流式 API 服务端的一个进程可以处理相当多的连接和吞吐量，但如果你发现单个进程无法处理你实例的负载，你可以通过改变每个进程的 `PORT` 号来运行多个进程，然后使用nginx将流量负载均衡到每个实例。例如，一个有大约 50000 个用户且月活跃用户为 10000 - 20000 个用户的社区，通常会有大约 800-1200 个并发流式 API 连接。
Mastodon许多任务都分配给后台进程，以确保HTTP请求快速响应，并防止HTTP请求中止影响到这些任务的执行。Sidekiq是单个进程，具有可配置的线程数。
流式 API 服务端还在 `/metrics` 上暴露了一个 [Prometheus](https://prometheus.io/) 端点，提供许多指标帮助你了解 Mastodon 流式 API 服务器的当前负载，一些关键指标包括：
#### 线程数 {#sidekiq-threads}
- `mastodon_streaming_connected_clients`：这是已连接客户端的数量，按客户端类型标记（websocket 或 eventsource）
- `mastodon_streaming_connected_channels`：这是当前订阅的"频道"数量（注意由于我们内部"系统"频道的工作方式，这个数字比连接的客户端要高得多）
- `mastodon_streaming_messages_sent_total`：这是自上次重启以来发送给客户端的消息总数。
- `mastodon_streaming_redis_messages_received_total`：这是从 Redis pubsub 接收的消息数量，用于补充[直接监控Redis](https://sysdig.com/blog/redis-prometheus/)。
虽然web进程数与web线程数影响Mastodon实例响应终端用户，分配给后台进程的线程数影响嘟文从作者分发至其他人的速度，电子邮件花多长时间发完等等。
{{< hint style="info" >}}
运行的流式 API 服务端进程越多， PostgreSQL 上消耗的数据库连接就越多，所以你可能需要使用 PgBouncer，如下文所述。
{{< /hint >}}
Sidekiq的线程数并不受环境变量控制，但是可通过命令行参数控制，例如：
下面是一个 nginx 配置示例，用于将流量路由到三个不同的进程，分别运行在 `PORT` 4000、 4001 和 4002 上：
```text
upstream streaming {
least_conn;
server 127.0.0.1:4000 fail_timeout=0;
server 127.0.0.1:4001 fail_timeout=0;
server 127.0.0.1:4002 fail_timeout=0;
}
```
如果你使用分布式 systemd 文件，那么可以使用以下命令启动多个流式 API 服务端：
```bash
$ sudo systemctl start mastodon-streaming@4000.service
$ sudo systemctl start mastodon-streaming@4001.service
$ sudo systemctl start mastodon-streaming@4002.service
```
默认情况下， `sudo systemctl start mastodon-streaming` 只在端口4000上启动一个进程，相当于运行 `sudo systemctl start mastodon-streaming@4000.service`。
{{< hint style="warning" >}}
Mastodon 的早期版本有一个 `STREAMING_CLUSTER_NUM` 环境变量，该变量使流式 API 服务端使用集群，它启动多个工作进程并使用 Node.js 进行负载均衡。
上述配置与其他配置的交互方式使容量规划变得困难，在涉及到数据库连接和 CPU 资源时尤为如此。默认情况下，流式 API 服务端会消耗所有可用 CPU 上的资源，这可能会与服务器上运行的其他软件产生冲突。另一个常见问题是配置错误的 `STREAMING_CLUSTER_NUM` 导致因为每个集群工作进程打开连接池而耗尽数据库连接，因此 `STREAMING_CLUSTER_NUM` 为 `5` 且 `DB_POOL` 为 `10` 可能会消耗50个数据库连接。
现在，单个流式 API 服务端进程最多只会使用 `DB_POOL` 个PostgreSQL连接，并且通过运行更多的流式 API 服务端实例来处理扩展。
{{< /hint >}}
### 后台处理 (Sidekiq) {#sidekiq}
Mastodon 中的许多任务都被委托给后台处理，以确保对 HTTP 请求的快速响应，并防止 HTTP 请求中止影响这些任务的执行。Sidekiq 是一个单一进程，具有可配置的线程数。
#### 线程数量 {#sidekiq-threads}
虽然 Web 进程中的线程数影响 Mastodon 实例对最终用户的响应速度，但分配给后台处理的线程数影响嘟文从作者传递给其他人的速度、邮件发送速度等。
线程数不是通过环境变量调整的，而是通过调用 Sidekiq 时的命令行参数调整，如下例所示：
```bash
bundle exec sidekiq -c 15
```
将启一个15线程的sidekiq进程。请注意每个线程都需要能够连接数据库，这意味着数据库连接池应足够大以满足所有进程。数据库连接池的大小由`DB_POOL`环境变量控制，该变量必须至少与进程数同样大。
这将以 15 个线程启动 Sidekiq 进程。需要注意的是，每个线程都需要一个数据库连接，所以这需要一个大的数据库池。这个池的大小由 `DB_POOL` 环境变量管理，它应该设置为至少等于线程数的值。
#### 队列 {#sidekiq-queues}
Sidekiq根据任务的重要性使用不同队列，这里的重要性是指如果队列不工作，其对本地用户体验的冲击有多大。按重要性降序排列：
Sidekiq 使用不同的队列来处理不同重要性的任务，其中重要性是指如果队列不工作，对服务器本地用户体验的影响程度。队列按重要性降序列出如下：
| 队列 | 重要性 |
| :--- | :--- |
| `default` | 影响本地用户的所有任务 |
| `push` | 推送消息至其它服务器 |
| `mailers` | 分发电子邮件 |
| `pull` | 从其它服务器拉取信息 |
| `scheduler` | 完成计划任务，例如更新当下流行标签及清理日志 |
`default`
: 影响本地用户的所有任务。
默认队列及其优先级存储于`config/sidekiq.yml`，但可通过调用Sidekiq命令行覆盖，例如：
`push`
: 将负载传递到其他服务器。
`ingress`
: 传入的外站活动。优先级低于默认队列，以便在服务器负载过重时本站用户仍能看到他们的嘟文。
`mailers`
: 负责邮件的传递。
`pull`
: 较低优先级的任务，如处理导入、备份、解析嘟文串、删除用户、转发回复。
`scheduler`
: 处理定时任务，如刷新热门话题标签和清理日志。
默认队列及其优先级存储在 [config/sidekiq.yml](https://github.com/mastodon/mastodon/blob/main/config/sidekiq.yml) 中，但可以通过 Sidekiq 的命令行调用进行覆盖，例如：
```bash
bundle exec sidekiq -q default
```
仅运行`default`队列。
此命令将只运行 `default` 队列。
Sidekiq处理队列的方式是，它首先检查第一个队列中的任务，如果没有，则检查下一个队列。这意味着，如果第一个队列已满，其他队列将延后。
Sidekiq 通过首先检查第一个队列中的任务来处理队列，如果没有找到，它会检查后续队列。因此，如果第一个队列过满，其他队列中的任务可能会遭遇延迟。
作为一种解决方案，可以启动为不同队列启动不同的Sidekiq进程以确保真正的并列执行，例如：使用不同Sidekiq参数创建多个systemd服务。
为队列创建不同的 Sidekiq 进程，可以实现真正的并行执行，例如为具有不同参数的 Sidekiq 创建多个 systemd 服务。
**请确保仅有一个`scheduler`队列！！**
{{< hint style="warning" >}}
你可以根据需要运行任意多的 Sidekiq 进程和线程，以有效处理运行中的作业，但是 `scheduler` 队列永远不应该在多个 Sidekiq 进程中同时运行。
{{< /hint >}}
## 使用PgBouncer进行事务池化 {#pgbouncer}
## 使用pgBouncer事务池 {#pgbouncer}
### 为什么你可能需要PgBouncer {#pgbouncer-why}
### 你为什么要用PgBouncer {#pgbouncer-why}
如果你开始耗尽可用的 PostgreSQL 连接（默认为100个），那么 PgBouncer 可能是一个好的解决方案。本文档描述了一些常见的问题，以及 Mastodon 的良好配置默认值。
如果开始耗尽可用的Postgres连接（默认为100），那PgBouncer可能是一个好方案。本文档将介绍Mastodon的一些常见陷阱及好的默认配置。
请注意，你可以在管理界面的“PgHero”查看当前使用了多少Postgres连接。通常Mastodon使用Puma、Sidekiq、streaming API三者线程数总和的连接数。
在 Mastodon 中具有 `DevOps` 权限的用户可以通过管理视图中的 PgHero 链接监控当前 PostgreSQL 连接的使用情况。通常，打开的连接数等于 Puma、Sidekiq 和流媒体 API 中的线程总数。
### 安装PgBouncer {#pgbouncer-install}
在Debian和Ubuntu：
在 Debian 和 Ubuntu 上：
```bash
sudo apt install pgbouncer
```
### 配置PgBouncer {#pgbouncer-config}
### 配置 PgBouncer {#pgbouncer-config}
#### 设置密码 {#pgbouncer-password}
首先，如果你的Postgres中`mastodon`帐户没有设置密码的话，你需要设置一个密码。
First off, if your `mastodon` user in PostgreSQL is set up without a password, you will need to set a password.
首先，如果你的 PostgreSQL 中的 `mastodon` 用户没有设置密码，你需要设置一个密码。
下面是如何重置密码：
以下是重置密码的方法：
```bash
psql -p 5432 -U mastodon mastodon_production -w
```
之后（很显然，使用一个与单词“password”不同的密码）：
然后（显然，此处应该使用不同于 "password" 的密码）：
```sql
ALTER USER mastodon WITH PASSWORD 'password';
```
然后输入 `\q` 退出。
然后使用 `\q` 退出。
#### 配置userlist.txt {#pgbouncer-userlist}
#### 配置 userlist.txt {#pgbouncer-userlist}
编辑 `/etc/pgbouncer/userlist.txt`
只要稍后你在 pgbouncer.ini 中指定一个用户名/密码，userlist.txt文件中的值*不必*与真实PostgreSQL用户相同。你可以随意设定用户名和密码，但是为方便起来，你可以重用“真实”的凭证。添加`mastodon`帐户至`userlist.txt`：
只要你在稍后的 `pgbouncer.ini` 中指定了用户/密码， `userlist.txt` 中的值就不必与真实的 PostgreSQL 用户组对应。你可以任意定义用户和密码，但为了简单起见，你可以重用"真实"的凭证。将 `mastodon` 用户添加到 `userlist.txt`：
```text
"mastodon" "md5d75bb2be2d7086c6148944261a00f605"
```
这里，我们使用md5格式，这里的md5密码就是字符串`密码 + 用户名`的md5值附加上`md5`。例如：为了获得用户名为`mastodon`密码为`password`的散列值，你可以这样做：
这里我们使用 md5 方案，其中 md5 密码只是 `password + username` 的 md5sum，前面加上字符串 `md5`。例如，为用户 `mastodon` 和密码 `password` 生成哈希：
```bash
# ubuntu, debian, etc.
# ubuntu, debian等
echo -n "passwordmastodon" | md5sum
# macOS, openBSD, etc.
# macOS, openBSD等
md5 -s "passwordmastodon"
```
然后将`md5`添加至开头。
然后只需在开头添加 `md5`。
你也可以创建一个`pgbouncer`管理帐户，以登入查看PgBouncer管理数据库。下面是一个`userlist.txt`文件的例子：
你还需要创建一个 `pgbouncer` 管理员用户来登录 PgBouncer 管理数据库。这里是一个示例 `userlist.txt`：
```text
"mastodon" "md5d75bb2be2d7086c6148944261a00f605"
"pgbouncer" "md5a45753afaca0db833a6f7c7b2864b9d9"
```
以上两个帐户密码者是`password`。
上述两个示例中的密码都为 `password`。
#### 配置 pgbouncer.ini {#pgbouncer-ini}
编辑 `/etc/pgbouncer/pgbouncer.ini`
在`[databases]`行下，列出你想连接的Postgres数据库。这里PgBouncer将使用同样的用户名/密码和数据库名称连接下层Postgres数据库：
在 `[databases]` 部分添加一行，列出你想连接的 PostgreSQL 数据库。这里我们只让 PgBouncer 使用相同的用户名/密码和数据库名来连接底层的 PostgreSQL 数据库：
```text
```ini
[databases]
mastodon_production = host=127.0.0.1 port=5432 dbname=mastodon_production user=mastodon password=password
```
`listen_addr` 和 `listen_port` 告诉 PgBouncer 从哪个地址/端口接收连接。默认值即可：
`listen_addr` 和 `listen_port` 将告知 PgBouncer 接受哪个地址/端口的连接。默认值的效果已经较为理想：
```text
```ini
listen_addr = 127.0.0.1
listen_port = 6432
```
将`auth_type`设为`md5`（假定你在`userlist.txt`使用md5格式）：
将 `auth_type` 设为 `md5`（假设你在 `userlist.txt` 中使用了 md5 格式）：
确保`pgbouncer`帐户为管理员：
```ini
auth_type = md5
```
**接下来的部分极其重要！** 默认连接池模式是基于连接（session-based），但是Mastodon需要基于事务（transaction-based）。换而言之，当一个事务创建一个Postgres连接随之创建，当事务完成该连接也随之结束。因此，你需要把`pool_mode`从`session`改为`transaction`：
确保 `pgbouncer` 用户是管理员：
接下来，`max_client_conn`定义PgBouncer自身接受多少连接，`default_pool_size`限制后台开启多少Postgres连接。（在PgHero，显示的连接数将与`default_pool_size`数目一致，因为它不知道PgBouncer。）
```ini
admin_users = pgbouncer
```
使用默认值启动即可，你可以随后调大他们：
Mastodon 需要不同于默认的基于会话的池化模式。具体而言，它需要基于事务的池化模式。这意味着 PostgreSQL 连接在事务开始时建立，在事务完成时终止。因此，必须将 `pool_mode` 设置从 `session` 更改为 `transaction`：
```text
```ini
pool_mode = transaction
```
接下来， `max_client_conn` 定义 PgBouncer 本身将接受多少个连接，而 `default_pool_size` 限制了底层会开启多少个 PostgreSQL 连接。（在 PgHero 中举报的连接数将对应于 `default_pool_size`，因为它不知道 PgBouncer 的存在）。
默认值可以开始，之后你可以随时增加它们：
```ini
max_client_conn = 100
default_pool_size = 20
```
完成更改后，不要忘记重载（reload）或重启（restart）pgbouncer：
修改完成后，不要忘记重新加载或重新启动 PgBouncer：
```bash
sudo systemctl reload pgbouncer
```
#### 调试，确保一切正常 {#pgbouncer-debug}
#### 调试并确认一切正常 {#pgbouncer-debug}
你应该能像连接Postgres一样连接PgBouncer：
你应该能够像连接 PostgreSQL 那样连接到 PgBouncer：
```bash
psql -p 6432 -U mastodon mastodon_production
```
然后，使用你的密码登录。
然后使用你的密码登录。
你也可以检查PgBouncer日专，就像这样：
你还可以这样检查 PgBouncer 日志：
```bash
tail -f /var/log/postgresql/pgbouncer.log
```
#### 配置 Mastodon 以连接 PgBouncer {#pgbouncer-mastodon}
#### 配置 Mastodon 与 PgBouncer 通信 {#pgbouncer-mastodon}
首先，确保`.env.production`文件这样设置：
在你的 `.env.production` 文件中，首先确保配置了：
```bash
PREPARED_STATEMENTS=false
```
因为我们使用基于事务（transaction-based）的连接池，我们不能使用参数化查询（prepared statement）。
由于我们使用基于事务的池化，我们不能使用预处理语句。
接下来，配置Mastodon使用6432端口（PgBouncer）而不是5432端口（PostgreSQL）就可以了：
接下来，配置 Mastodon 使用端口 6432（PgBouncer）而不是 5432（PostgreSQL），之后你应该就可以开始运行了：
```bash
DB_HOST=localhost
@ -223,18 +288,18 @@ DB_PORT=6432
```
{{< hint style="warning" >}}
你不能使用pgBouncer来执行 `db:migrate` 操作。但是这个问题很容易解决。如果你的postgres和pgBouncer位于同一台主机，只需要在执行任务时与 `RAILS_ENV=production` 一同定义 `DB_PORT=5432` 就可以了，例如：`RAILS_ENV=production DB_PORT=5432 bundle exec rails db:migrate`（如果主机不同，你也可以指定`DB_HOST`等等）
PgBouncer 不能用于执行 `db:migrate` 任务，但这很容易解决。如果你的 PostgreSQL 和 PgBouncer 在同一主机上，可以简单地在调用任务时定义 `DB_PORT=5432` 和 `RAILS_ENV=production`，例如： `RAILS_ENV=production DB_PORT=5432 bundle exec rails db:migrate` （如果不同，你也可以指定 `DB_HOST` 等）
{{< /hint >}}
#### 管理 PgBouncer {#pgbouncer-admin}
最简单的重启方法：
最简单的重启方法是：
```bash
sudo systemctl restart pgbouncer
```
但如果你设定了PgBouncer管理员帐户，你也可以用管理员帐户连接：
但如果你已经设置了 PgBouncer 管理员用户，你也可以以管理员身份连接：
```bash
psql -p 6432 -U pgbouncer pgbouncer
@ -246,22 +311,131 @@ psql -p 6432 -U pgbouncer pgbouncer
RELOAD;
```
使用 `\q` 以退出。
然后使用 `\q` 退出。
## 单独的Redis缓存 {#redis}
## 针对缓存分离Redis {#redis}
Redis被广泛使用于应用，但是某些用途比其他用途更重要。主页时间轴、列表时间轴、Sidekiq队列还有streaming API都是由Redis支持的，这些是你不希望丢失的重要数据（尽管丢失了也能存活，不像PostgreSQL数据库的丢失——永远不要丢失PostgreSQL数据库！）。然而，Redis也被用于易失性缓存。如果你正处于扩展阶段，担心你的Redis能否处理所有事情，你可以使用一个不同的Redis数据库来做缓存。在环境变量中，你可以指定 `CACHE_REDIS_URL` 或分离形式，就像 `CACHE_REDIS_HOST`、 `CACHE_REDIS_PORT`等等。未指定部分将会回落至没有前缀的相同设定值。
Redis 在整个应用中被广泛使用，但有些用途比其他用途更重要。主页订阅、列表订阅、 Sidekiq 队列以及流式 API 都由 Redis 支持，这些是你不想丢失的重要数据（虽然与比不可丢失的 PostgreSQL 数据库不同，丢失这些数据也可以恢复）。
至于Redis数据库配置，基本上你可以去除后台保存至磁盘，因为重启致使数据丢失也没关系，你可以以此节省一些磁盘I/O。你还可以添加最大内存限制和 key eviction policy，对于这部分，请参阅这个指南：[Using Redis as an LRU cache](https://redis.io/topics/lru-cache)。
Redis 也用于易失性缓存。如果你正在扩展站点规模，并担忧 Redis 处理负载的能力，你可以专门为缓存分配一个单独的 Redis 数据库。要做到这一点，请在环境中设置 `CACHE_REDIS_URL`，或者定义单独的组件如 `CACHE_REDIS_HOST`、 `CACHE_REDIS_PORT` 等。
## 只读副本（Read-replicas） {#read-replicas}
未指定的组件将默认为没有 `CACHE_` 前缀的值。
为了减轻你的Postgresql服务器负担，你可以使用热流复制（hot streaming replication）（只读副本（read replica））。有关示例，请参见[该指南](https://cloud.google.com/community/tutorials/setting-up-postgres-hot-standby)。你可以给以下Mastodon用途使用副本（replica）：
在配置用于缓存的 Redis 数据库时，可以禁用后台保存到磁盘的功能，因为在重启时数据丢失不是很关键，这可以节省一些磁盘 I/O。此外，考虑设置最大内存限制和实现键驱逐策略。有关这些配置的更多详细信息，请查看此指南：[使用 Redis 作为 LRU 缓存](https://redis.io/topics/lru-cache)
* streaming API 服务器无需写入，因此你可以将其直接使用副本（replica）。但由于 streaming API 服务器不经常查询数据库，这样的优化影响很小。
* 使用 Makara 驱动 web 与 sidekiq 进程，这样可以实现从主（primary）数据库写，从副本（replica）读。让我们开始吧。
## 针对 Sidekiq 分离 Redis {#redis-sidekiq}
编辑 `config/database.yml` 文件，将 `production` 替换为如下内容：
Redis 在 Sidekiq 中用于跟踪其锁和队列。尽管总体上性能提升不是很大，但一些实例可能会受益于为 Sidekiq 单独设置 Redis 实例。
在环境文件中，你可以指定 `SIDEKIQ_REDIS_URL` 或单独的部分如 `SIDEKIQ_REDIS_HOST`、 `SIDEKIQ_REDIS_PORT` 等。未指定的部分回退到不带 `SIDEKIQ_` 前缀的相同值。
创建一个单独的 Redis 实例用于 Sidekiq 相对简单：
首先复制默认的 redis systemd 服务：
```bash
cp /etc/systemd/system/redis.service /etc/systemd/system/redis-sidekiq.service
```
在 `redis-sidekiq.service` 文件中，更改以下值：
```bash
ExecStart=/usr/bin/redis-server /etc/redis/redis-sidekiq.conf --supervised systemd --daemonize no
PIDFile=/run/redis/redis-server-sidekiq.pid
ReadWritePaths=-/var/lib/redis-sidekiq
Alias=redis-sidekiq.service
```
为新的 Sidekiq Redis 实例复制 Redis 配置文件：
```bash
cp /etc/redis/redis.conf /etc/redis/redis-sidekiq.conf
```
在复制后的 `redis-sidekiq.conf` 文件中，更改以下值：
```bash
port 6479
pidfile /var/run/redis/redis-server-sidekiq.pid
logfile /var/log/redis/redis-server-sidekiq.log
dir /var/lib/redis-sidekiq
```
在启动新的 Redis 实例之前，创建一个数据目录：
```bash
mkdir /var/lib/redis-sidekiq
chown redis /var/lib/redis-sidekiq
```
启动新的 Redis 实例：
```bash
systemctl enable --now redis-sidekiq
```
更新你的环境变量，并添加以下行：
```bash
SIDEKIQ_REDIS_URL=redis://127.0.0.1:6479/
```
重启 Mastodon 以使用新的 Redis 实例。确保同时重启 web 和 Sidekiq（否则其中一个仍将从错误的实例工作）：
```bash
systemctl restart mastodon-web.service
systemctl restart redis-sidekiq.service
```
## 用于高可用场景的 Redis Sentinel {#redis-sentinel}
如前所述， Redis 是 Mastodon 实例运行的关键部分。默认情况下，你的部署将使用单个 Redis 实例，或者如果你设置了缓存，则使用多个实例。但是，如果该实例宕机，也可能导致整个 Mastodon 实例宕机。为了缓解这个问题，可以使用 Redis Sentinel 来跟踪你的 Redis 实例，并在一个实例宕机时自动将客户端引导到新的主实例。你可以指定 `REDIS_SENTINELS`，这是 Mastodon 可以与之交互的 Sentinel 实例的 IP:Port 组合的以逗号分隔的列表，以确定当前的主 Redis 节点。你还需要在 `REDIS_SENTINEL_MASTER` 中指定你想要连接的主节点的名称。默认情况下， Sentinel 将在当前主节点无法访问一分钟后将其设置为宕机并选择新的主节点，但这可以根据你的设置进行配置。
所有与 sentinel 相关的变量也可以设置 `CACHE_`和`SIDEKIQ_` 前缀，以便使用多个redis实例。
了解更多关于 Redis sentinel 的信息：https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/
## 读副本 {#read-replicas}
为了减轻 PostgreSQL 服务器的负载，你可能希望设置热数据流式复制（读副本）。[参见此指南获取示例](https://cloud.google.com/community/tutorials/setting-up-postgres-hot-standby)。
### Mastodon >= 4.2
从 4.2 版本开始，Mastodon 内置了对副本的支持。你可以为每个服务（包括 Sidekiq）使用相同的配置，当情况允许时，某些查询将使用 Rails 内置的副本支持被定向到读副本。如果你的副本落后超过几秒钟，应用将停止向它发送查询，直到它赶上进度。
要配置读副本，请使用以下环境变量：
```
REPLICA_DB_HOST
REPLICA_DB_PORT
REPLICA_DB_NAME
REPLICA_DB_USER
REPLICA_DB_PASS
REPLICA_PREPARED_STATEMENTS
REPLICA_DB_TASKS
```
或者，如果你想使用同一个变量配置上述所有配置，也可以使用 `REPLICA_DATABASE_URL`。
`REPLICA_DB_TASKS=false` 将使应用连接到副本数据库，但不执行任何数据库管理任务，如模型管理、迁移、种子管理等。默认情况下，它被设为 true。
作为可选选项，可用 `REPLICA_PREPARED_STATEMENTS` 覆盖 `PREPARED_STATEMENTS` 的值。如果未设置 `PREPARED_STATEMENTS`，默认为 true。
应用上述配置后，你应该开始看到对副本服务器的请求了！
### Mastodon <= 4.1
对于 4.2 之前的 Mastodon 版本，你可以通过以下方式在 Mastodon 中使用副本：
- 流式 API 服务端完全不发出写操作，所以你可以直接将其连接到副本（它无论如何也不经常查询数据库，所以这样做的影响很小）。
- 在 web 和 Sidekiq 进程中使用 Makara 驱动程序，使写操作发送到主数据库，而读操作发送到副本。让我们来讨论这个。
{{< hint style="warning" >}}
Sidekiq 进程当前不支持读副本，对 Sidekiq 进程使用读副本将导致作业失败和数据丢失。
{{< /hint >}}
你将需要为web进程使用单独的 `config/database.yml` 文件，并编辑它以替换 `production` 部分，如下所示：
```yaml
production:
@ -279,10 +453,27 @@ production:
url: postgresql://db_user:db_password@db_host:db_port/db_name
```
确保URL指向PostgreSQL服务器所在位置。你可以添加多个副本（replica）。你可以本地安装一个pgBouncer，该pgBouncer可被配置为根据数据库名称连接两个不同服务器，例如：“mastodon”连接主服务器，“mastodon_replica”连接副本服务器，这样上面文件中的两个URL可以使用同样用户名、密码、主机、端口，不同数据库名称。可能的设置有很多！有关Makara的更多信息，请参阅[其文档](https://github.com/taskrabbit/makara#databaseyml)。
确保 URL 指向 PostgreSQL 服务器的正确位置。你可以添加多个副本。你可以在本地安装一个 PgBouncer，并配置其基于数据库名称连接到两个不同的服务器，例如， "mastodon" 连接到主服务器， "mastodon_replica" 连接到副本，因此在上面的文件中，两个URL都会指向具有相同用户、密码、主机和端口但数据库名称不同的本地 PgBouncer。这样设置的可能性很多。有关 Makara 的更多信息，[请查看其文档](https://github.com/taskrabbit/makara#databaseyml)。
{{< hint style="warning" >}}
Sidekiq无法可靠的使用只读副本（read-replicas），因为即使是最微小的复制延迟也会导致查询不到相关纪录所致的任务失败。
确保 sidekiq 进程运行使用标准的 `config/database.yml`，以避免作业失败和数据丢失！
{{< /hint >}}
{{< translation-status-zh-cn raw_title="Scaling up your server" raw_link="/admin/scaling/" last_tranlation_time="2020-05-06" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}}
## 使用 Web 负载均衡器
像 DigitalOcean、AWS、Hetzner 等云提供商提供虚拟负载均衡解决方案，它们在多个服务器之间分配网络流量，但提供单一的公共 IP 地址。
可以扩展你的部署架构，在其中一个虚拟负载均衡器后面设置多个 web/Puma 服务器，以减少单个服务器被用户流量压垮的风险，帮助提供更一致的性能，并在进行维护或升级时减少停机时间。你应该咨询提供商的文档了解如何设置和配置负载均衡器，但要考虑到你需要配置负载均衡器来监控后端 web/Puma 节点的健康状况，否则你可能会向不响应的服务发送流量。
以下端点可用于监控此目的：
- **Web/Puma:** `/health`
- **流媒体API:** `/api/v1/streaming/health`
这两个端点都应返回HTTP状态码200，以及文本`OK`作为结果。
{{< hint style="info" >}}
你也可以将这些端点用于第三方监控/警报工具的健康检查。
{{< /hint >}}
{{< translation-status-zh-cn raw_title="Scaling up your server" raw_link="/admin/scaling/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

36
content/zh-cn/admin/setup.md
View file

@ -1,25 +1,29 @@
---
title: 配置你的新实例
description: 一些需要在安装完Mastodon做的事情
title: 设置你的新实例
description: 安装 Mastodon 后需要做的事情
menu:
docs:
weight: 50
parent: admin
---
## 创建一个管理员帐户 {#admin}
## 创建管理员账户 {#admin}
### 通过浏览器 {#admin-gui}
### 在浏览器中创建 {#admin-gui}
在通过浏览器完成帐户注册后，你需要使用命令行给你新创建的帐户以管理员特权。假设你帐户的用户名为`alice`：
在浏览器中注册后，你需要使用命令行给你新创建的账户授予管理员权限。假设你的用户名是 `alice`：
```bash
RAILS_ENV=production bin/tootctl accounts modify alice --role Owner
```
### 通过命令行 {#admin-cli}
{{<hint style="warning">}}
在 Mastodon 4.0 之前，用户组被硬编码为 `user`、`moderator` 或 `admin` 之一。从 4.0 版本开始， Mastodon 有了一个可自定义的用户组系统，默认创建的用户组为 `Moderator`、`Admin` 和 `Owner`。自定义用户组的名称区分大小写。
{{</hint>}}
你可以使用命令行创建一个全新帐户。
### 从命令行 {#admin-cli}
你可以使用命令行创建一个新账户。
```bash
RAILS_ENV=production bin/tootctl accounts create \
@ -29,19 +33,19 @@ RAILS_ENV=production bin/tootctl accounts create \
--role Owner
```
一个随机密码将会显示在终端上。
终端将输出随机生成的密码。
## 填写站点信息 {#info}
登录后，打开**网站设置**页面。虽然从技术上来说无需填写这些信息，但对于操作服务器的人而言，这被认为是至关重要的。
登录后，转到**站点设置**页面（在**首选项** -> **管理**下）。理论上填写这些信息不是必须的，但对于运营一个面向人类的站点来说，这被认为是至关重要的。
| 设置 | 含意 |
| 设置 | 含义 |
| :--- | :--- |
| 用于联系的公开用户名 | 你的用户名，人们可以知道谁运营着这台服务器 |
| 用于联系的公开电子邮件地址 | 一个可以联系到你的电子邮件地址，可供那些帐户被锁或没有帐户的人使用 |
| 本站简介 | 你为什么启动这个站点？为谁运营？什么使它与众不同？ |
| 本站详细介绍 | 你可以在此放置各种信息，但建议放置**行为准则**。 |
| 联系人用户名 | 你的用户名，让人们知道谁拥有此站点 |
| 业务邮箱 | 一个电子邮件地址，方便被锁定在账户之外的人或没有账户的人联系你 |
| 实例描述 | 你为什么创建这个站点？它适合谁？它有什么不同？ |
| 自定义扩展信息 | 你可以在这里各种信息，但推荐放置**行为准则** |
填写完这些后，请点击“保存更改”。
填写完这些信息后，点击"保存更改"。
{{< translation-status-zh-cn raw_title="Setting up your new instance" raw_link="/admin/setup/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}}
{{< translation-status-zh-cn raw_title="Setting up your new instance" raw_link="/admin/setup/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

995
content/zh-cn/admin/tootctl.md
View file

File diff suppressed because it is too large Load diff

48
content/zh-cn/admin/troubleshooting.md
View file

@ -1,29 +1,53 @@
---
title: 故障分析
title: 故障排除
menu:
docs:
weight: 120
parent: admin
identifier: admin-troubleshooting
---
## **我看到一个故障页说一些东西出错了。我怎么找出哪里出错了？**
## **我看到一个错误页面，上面说出了问题。我怎样才能找出是什么问题？**
所有带堆栈追踪（stack traces）的错误信息都将会被写入系统日志。当使用systemd时，可使用 `journalctl -u mastodon-web`（替换以相应的服务名） 来浏览每个服务的日志。当使用Docker时，与之类似：`docker logs mastodon_web_1`（替换以相应的容器名）。
所有带有堆栈跟踪的错误消息都会写入系统日志。当使用 systemd 时，可以通过`journalctl -u mastodon-web`（请将 `mastodon-web` 替换为实际的正确服务名称）浏览每个 systemd 服务的日志。当使用 Docker 时，可以通过类似的命令 `docker logs mastodon_web_1`（请将 `mastodon_web_1` 替换为实际的正确容器名称）查看日志。
服务端详细错误信息将*永不会*公开显示，因为它们可能会暴露你的内部设置，并为攻击者提供线索，让他们了解如何更好的入侵或如何更高效的滥用。
服务器端错误的具体详情_永远不会_向公众显示，因为它们可能会揭示你的内部设置情况，并为攻击者提供如何入侵或更有效地滥用系统的线索。
来自Mastodon web服务器的每一个响应都带有独一无二的请求ID（request ID），该ID也将反映在日志中。通过检查错误页的请求头，你可以在日志中轻松找到与之对应的堆栈追踪（stack traces）。
来自 Mastodon 网络服务器的每个响应都带有一个包含唯一请求 ID 的标头，这也将反映在日志中。通过检查错误页面的标头信息，你可以轻松在日志中找到相应的堆栈跟踪。
## **升级新版本后，有些页面看起来很奇怪，就像它们含有未设置样式的元素一样。为什么？**
## **我在日志中看不到太多内容。如何启用额外的日志/调试信息？**
检查升级后，你是否运行 `RAILS_ENV=production bin/rails assets:precompile` 并重启Mastodon web 进程。因为这看起来像提供了过期的样式与脚本。这也有可能由于内存缺乏导致预编译失败，很不幸webpack会占用大量内存。如果是这个原因，请确保你已经分配了swap空间。另外，也可以在另一台机器上预编译静态文件，然后把它们复制至 `public/packs` 目录。
默认情况下，你的日志将显示 `info` 级别的日志记录。要查看更多调试消息，你可以修改 `.env.production` 文件以提高相关服务的级别：
## **升级新版本后，一些请求失败了，日志中的错误信息是 missing columns or tables。为什么？**
- **Web/Sidekiq：**将 `RAILS_LOG_LEVEL` 的值设为 `debug`，然后重启你正在尝试排除故障的服务。
- **Streaming：**将 `LOG_LEVEL` 的值设为 `silly`，然后重启你正在尝试排除故障的服务。
检查升级后，你是否运行 `RAILS_ENV=production bin/rails db:migrate`。因为这看起来Mastodon代码访问了一个更新或更旧的数据库schema。如果你使用PgBouncer，请确保此命令直接连接PostgreSQL，因为PgBouncer不支持迁移过程中的锁表操作。
有关这些选项的其他日志级别的更多信息，可以在[配置环境](https://docs.joinmastodon.org/admin/config)页面找到。
## **我试图运行 `tootctl` 或 `rake`/`rails` 命令，但我得到 uninitialized constants 错误信息。哪里出错了？**
`debug` 或 `silly` 级别可能非常详细，因此在完成故障排除后，你应该注意将日志级别改回较低级别。
检查你是否在命令前使用 `RAILS_ENV=production` 指定正确的环境。默认情况下，假定使用开发环境，因此代码尝试加载开发相关gem。然而，在生产环境中，我们避免安装这些gem。这就是错误的来源。
## **升级到较新版本后，某些页面看起来很奇怪，例如出现了没有任何样式的元素。为什么？**
{{< translation-status-zh-cn raw_title="Troubleshooting errors" raw_link="/admin/troubleshooting/" last_tranlation_time="2020-05-08" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}}
请检查你是否在升级后运行了 `RAILS_ENV=production bin/rails assets:precompile`，并重启了 Mastodon 的 web 进程，因为它似乎正在提供过时的样式表和脚本。也可能是由于内存不足导致预编译失败，这是因为遗憾的是 webpack 非常消耗内存。如果是这种情况，请确保你分配了一些交换内存。或者，可以在不同的机器上预编译资源，然后复制 `public/packs` 目录。
## **升级到较新版本后，一些请求失败，日志显示关于缺少列或表的错误消息。为什么？**
检查你是否在升级后运行了 `RAILS_ENV=production bin/rails db:migrate`，因为看起来 Mastodon 的代码正在访问较新或较旧的数据库架构。如果你使用 PgBouncer，请确保此命令直接连接到 PostgreSQL，因为 PgBouncer 不支持迁移中使用的表锁定类型。
## **我尝试运行 `tootctl` 或 `rake`/`rails` 命令，但出现关于未初始化常量的错误。怎么回事？**
检查你是否在命令前指定了正确的环境变量 `RAILS_ENV=production`。默认情况下，环境被假定为开发环境，因此代码尝试加载与开发相关的gems。然而，在生产环境中，我们避免安装这些gems，这就是错误的来源。
## **在执行 `RAILS_ENV=production bundle exec rails assets:precompile` 时遇到编译错误，但没有提供更多信息。如何修复？**
这通常是因为你的服务器在编译资源时内存不足。使用交换文件或增加交换空间以增加内存容量。运行 `RAILS_ENV=production bundle exec rake tmp:cache:clear` 清除缓存，然后执行 `RAILS_ENV=production bundle exec rails assets:precompile` 重新编译。确保在编译错误后清除缓存，否则会显示"一切正常"但资源保持不变。
## **我收到这个错误：`Read-only file system @ dir_s_mkdir`。为什么？**
默认情况下，Mastodon使用[ systemd 的沙箱功能](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Sandboxing)，这种方式不允许在 `/home/mastodon` 以外的位置执行写入。如果 Mastodon 安装在其他位置，你可能需要允许 `mastodon-sidekiq` 和 `mastodon-web` 写入自定义目录：
1. 在文件 `/etc/systemd/system/mastodon-sidekiq.service` 和 `/etc/systemd/system/mastodon-web.service` 中添加参数 `ReadWritePaths`。例如 - `ReadWritePaths=/example/mastodon/live`。
2. 执行 `systemctl stop mastodon-sidekiq mastodon-web`
3. 执行 `systemctl daemon-reload`
4. 执行 `systemctl start mastodon-sidekiq mastodon-web`
{{< translation-status-zh-cn raw_title="Troubleshooting errors" raw_link="/admin/troubleshooting/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

111
content/zh-cn/admin/troubleshooting/index-corruption.md Normal file
View file

@ -0,0 +1,111 @@
---
title: 数据库索引损坏
description: 如何从数据库索引损坏中恢复。
menu:
docs:
weight: 10
parent: admin-troubleshooting
---
一个比较常见的配置问题可能导致整个数据库的索引损坏。本页尝试解释为什么会发生这种情况以及如何修复它。
## 语言数据与排序规则 {#explanation}
数据库中的文本值，如用户名或状态标识符，使用所谓的排序规则进行比较，这些规则定义了字符的排序方式和大小写转换方式。
在设置数据库时，Mastodon 会使用数据库服务器的默认语言设置，包括默认排序规则，这通常由操作系统的设置决定。
不幸的是，在2018年末，一次 `glibc` 更新改变了许多区域设置的排序规则，这意味着使用受影响的语言设置的数据库现在会以不同方式排序文本值。
由于数据库索引依赖于它们所索引的值的排序的算法结构，一些索引可能会变得不一致。
更多信息：https://wiki.postgresql.org/wiki/Locale_data_changes https://postgresql.verite.pro/blog/2018/08/27/glibc-upgrade.html
## 我是否受到这个问题的影响？ {#am-i-affected}
如果你的数据库未使用 `C` 或 `POSIX` 作为其排序规则（你可以通过 `SELECT datcollate FROM pg_database WHERE datname = current_database();` 检查），
并且你曾经使用过 glibc 2.28 之前的版本，并且在更新到 glibc 2.28 或更新版本后没有立即重新索引你的数据库，那么你的索引可能不一致。
{{< hint style="info" >}}
你可能是因为 PgHero 警告"重复索引"而找到此页面的。虽然这类警告有时可能表明部署或更新 Mastodon 时出现问题，**但它们与数据库索引损坏无关，也不表明数据库存在任何功能问题**。
{{< /hint >}}
你可以使用 [PostgreSQL 的 `amcheck` 模块](https://www.postgresql.org/docs/10/amcheck.html)检查你的索引是否一致：作为数据库服务器的超级用户，连接到你的 Mastodon 数据库并执行以下命令（这可能需要一段时间）：
```SQL
CREATE EXTENSION IF NOT EXISTS amcheck;
SELECT bt_index_check(c.oid)
FROM pg_index i
JOIN pg_class c ON i.indexrelid = c.oid
WHERE c.relname IN ('index_account_domain_blocks_on_account_id_and_domain',
'index_account_proofs_on_account_and_provider_and_username',
'index_accounts_on_username_and_domain_lower', 'index_accounts_on_uri',
'index_accounts_on_url', 'index_conversations_on_uri',
'index_custom_emoji_categories_on_name',
'index_custom_emojis_on_shortcode_and_domain',
'index_devices_on_access_token_id', 'index_domain_allows_on_domain',
'index_domain_blocks_on_domain', 'index_email_domain_blocks_on_domain',
'index_invites_on_code', 'index_markers_on_user_id_and_timeline',
'index_media_attachments_on_shortcode', 'index_preview_cards_on_url',
'index_statuses_on_uri', 'index_tags_on_name_lower',
'index_tombstones_on_uri', 'index_unavailable_domains_on_domain',
'index_users_on_email', 'index_webauthn_credentials_on_external_id'
);
```
如果出现错误，则你的数据库已损坏，需要修复。如果没有错误，你可能需要执行更复杂的检查以确保。
与之前的检查不同，这些更复杂的检查在运行时会锁表，从而影响实例的可用性。
```SQL
CREATE EXTENSION IF NOT EXISTS amcheck;
SELECT bt_index_parent_check(c.oid)
FROM pg_index i
JOIN pg_class c ON i.indexrelid = c.oid
WHERE c.relname IN ('index_account_domain_blocks_on_account_id_and_domain',
'index_account_proofs_on_account_and_provider_and_username',
'index_accounts_on_username_and_domain_lower', 'index_accounts_on_uri',
'index_accounts_on_url', 'index_conversations_on_uri',
'index_custom_emoji_categories_on_name',
'index_custom_emojis_on_shortcode_and_domain',
'index_devices_on_access_token_id', 'index_domain_allows_on_domain',
'index_domain_blocks_on_domain', 'index_email_domain_blocks_on_domain',
'index_invites_on_code', 'index_markers_on_user_id_and_timeline',
'index_media_attachments_on_shortcode', 'index_preview_cards_on_url',
'index_statuses_on_uri', 'index_tags_on_name_lower',
'index_tombstones_on_uri', 'index_unavailable_domains_on_domain',
'index_users_on_email', 'index_webauthn_credentials_on_external_id'
);
```
如果执行成功，没有返回错误，你的数据库应该是一致的，你可以安全地忽略 Mastodon 在运行 `db:migrate` 时发出的警告。
## 修复问题 {#fixing}
如果你受到影响但不采取行动，随着时间推移，你的数据库可能会变得越来越不一致。因此，尽快修复这个问题非常重要。
Mastodon 3.2.2 及更高版本附带了一个半交互式脚本，以尽可能良好的方式修复这些损坏。如果你使用的是早期版本，请先更新到 3.2.2。由于这些损坏的存在，可能在运行数据库迁移到 3.2.2 时会失败，但数据库应该会变成一个可以被 Mastodon 3.2.2 附带的维护工具恢复的状态。
在尝试修复数据库之前，**停止 Mastodon 并备份你的数据库**。然后，在**Mastodon 仍处于停止状态**的情况下，运行维护脚本：
```
RAILS_ENV=production bin/tootctl maintenance fix-duplicates
```
该脚本将遍历数据库以自动查找重复项并修复它们。在某些情况下，这些操作是破坏性的。在最具破坏性的情况下，你将被要求选择要保留的记录和要丢弃的记录。在所有情况下，搜索整个数据库中的重复项是一项极其耗时的操作。
{{< hint style="warning" >}}
在某些情况下，重复记录可能有无法调和的冲突（例如两个不同的本站用户共享相同的用户名）。在这些情况下，去重操作可能是**部分破坏性的**，你将被询问哪些记录保持不变，哪些记录将被更改。
因此，此脚本是半交互式的。在所有情况下，搜索整个数据库中的重复项是一项极其耗时的操作。
{{< /hint >}}
{{< hint style="danger" >}}
**由于维护脚本将暂时移除索引， Mastodon 必须在整个过程中完全停止，以防止出现其他重复项。**
{{< /hint >}}
## 避免问题
要避免这个问题，请在任何 libc 更新后立即重新索引你的数据库。
[SQL 命令 `REINDEX`](https://www.postgresql.org/docs/current/sql-reindex.html)
或
[`reindexdb` 命令行工具](https://www.postgresql.org/docs/current/app-reindexdb.html)
可能对此有用。
{{< translation-status-zh-cn raw_title="Database index corruption" raw_link="/admin/troubleshooting/index-corruption/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

40
content/zh-cn/admin/upgrading.md
View file

@ -7,70 +7,80 @@ menu:
---
{{< hint style="info" >}}
当一个新的Mastodon版本释出后，它将出现在[GitHub releases页面](https://github.com/mastodon/mastodon/releases)。请注意：运行来自`main`分支的未释出代码，虽然可以进行，但不推荐这样做。
当 Mastodon 发布新版本时，它会出现在[ GitHub 发布页面](https://github.com/mastodon/mastodon/releases) 上。请注意，虽然可以运行 `main` 分支中的未发布代码，但不推荐这样做。
{{< /hint >}}
Mastodon版本与git tags一致。在尝试升级之前，请至[GitHub releases页面](https://github.com/mastodon/mastodon/releases)查找所需版本。该页面包含了一个**更新日专**，其中描述你需要了解的所有差异，以及**特定的升级指令**。
### 自动更新验证 {#automated_checks}
开始之前，切换至`mastodon`用户：
从 v4.2.0 版本开始，Mastodon 将自动检查可用更新并通知服务器上拥有 `DevOps` 权限的用户。
这通过每 30 分钟在后台获取 `https://api.joinmastodon.org/update-check?version=<current_version>` 来实现。 `current_version` 省略了构建元数据（如果版本字符串中含有`+`，则为第一个 `+` 之后的所有内容）。例如，如果你的版本是 `4.3.0-beta2+my-fork`，Mastodon 将查询 `https://api.joinmastodon.org/update-check?version=4.3.0-beta2`。
你可以通过设置 `UPDATE_CHECK_URL` 环境变量来更改 Mastodon 查询的 URL。你也可以通过将此环境变量设置为空字符串来完全禁用此行为，但我们强烈建议不要这样做，除非你通过其他方式关注 Mastodon 更新，因为 Mastodon 偶尔会发布必须及时应用的关键安全更新。
### 升级步骤
Mastodon 的发布版本对应 git 标签。在尝试升级之前，请在[ GitHub 发布页面](https://github.com/mastodon/mastodon/releases) 上查看所需的发布版本。该页面将包含**变更日志**，描述关于新版本不同之处的所有信息，以及**特定的升级说明**。
首先，切换到`mastodon`用户：
```bash
su - mastodon
```
并转至Mastodon根目录：
并转到 Mastodon 根目录：
```bash
cd /home/mastodon/live
```
下载相应版本代码，这里假定版本为`v3.1.2`：
下载发布版本的代码，假设版本为`v3.1.2`：
```bash
git fetch --tags
git checkout v3.1.2
```
现在，执行GitHub版本发布说明中的升级指令。因为不同的版本有不同的指令，所以本页面将不包括任何指令。
现在执行[ GitHub 上该版本的发行说明](https://github.com/mastodon/mastodon/releases) 中包含的升级说明。由于不同的发布版本需要不同的说明，我们不在此页面上包含任何说明。
{{< hint style="info" >}}
从旧版本升级时，你可以安全的跳过中间版本。你无需单独检出他们。然而，你确实需要追踪每一个版本的升级指令。大多数指令都是重叠的，你只需要确保每条至少执行一次即可。
从旧版本升级时，你可以安全地跳过中间版本。你不需要单独检出它们。但是，你需要跟随每个版本的说明。大多数说明的步骤是重复的，你只需确保至少执行一次所有内容。
{{< /hint >}}
当你执行完版本发布说明中的指令后，切换回root用户：
在执行完发布说明中的指令后，切回 root 用户：
```bash
exit
```
重启**后台worker**：
重启**后台工作进程**：
```bash
systemctl restart mastodon-sidekiq
```
并重载**web进程**：
并重新加载 **Web 进程**：
```bash
systemctl reload mastodon-web
```
{{< hint style="info" >}}
`reload`操作是零下线时间的重启（restart），也被称为“分阶段重启（phased restart）”。因此，Mastodon升级通常不需要为计划下线而提前发布公告。罕见情况下，你可以改用`restart`操作，但你的用户将感到（短暂的）服务中断。
`reload` 操作是一种零停机重启，也称为"分阶段重启"。因此，Mastodon 升级通常不需要提前通知用户计划停机。在极少数情况下，你可以使用 `restart` 操作代替，但用户会感受到（短暂的）服务中断。
{{< /hint >}}
罕见情况下，**streaming API** 服务也会被更新并需要重启：
**流式 API** 服务器也会更新并需要重启，这将导致所有已连接的客户端断开连接，可能增加服务器负载：
```bash
systemctl restart mastodon-streaming
```
{{< hint style="danger" >}}
更新streaming API服务非常罕见，在大多数版本中，*不*需要重启它。重启streaming API将导致服务器负载增加，因为断线的用户会尝试重连或改用REST API轮询。因此请尽量避免重启streaming API服务
重启流式 API 会增加服务器负载，因为断开连接的客户端会尝试重新连接或改为轮询 REST API，所以尽可能避免这样做。
{{< /hint >}}
{{< hint style="success" >}}
**就这样！** 您现在正在运行新版本的Mastodon。
**以上就是所有步骤！**你现在正在运行新版本的 Mastodon。
{{< /hint >}}
{{< translation-status-zh-cn raw_title="Upgrading to a new release" raw_link="/admin/upgrading/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}}
{{< translation-status-zh-cn raw_title="Upgrading to a new release" raw_link="/admin/upgrading/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

64
content/zh-cn/api/datetime-format.md Normal file
View file

@ -0,0 +1,64 @@
---
title: Datetime 格式
description: Datetime 格式
menu:
docs:
weight: 10
parent: api
---
## Datetime {#datetime}
“Datetime”指定某个时刻。
Datetime 的字符串表示形式使用 [RFC3339 第 5.6 节](https://www.rfc-editor.org/rfc/rfc3339#section-5.6) 中定义的“互联网日期/时间格式”。
总的来说，它包含以下必须包含的部分：
```
[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[s][TZD]
```
其中：
- `[YYYY]` = 四位数的年份
- `[MM]` = 两位数的月份（01=一月，以此类推）
- `[DD]` = 两位数的月份中的日期（01 到 31）
- `[hh]` = 小时的两位数字（00 到 23）（不允许 24）
- `[mm]` = 分钟的两位数字（00 到 59）
- `[ss]` = 秒的两位数字（00 到 60）
- `[s]` = 一位或多位数字表示秒的小数部分
- `[TZD]` = 时区指示符（UTC 为 `Z`，或者 `+[hh]:[mm]` 或 `-[hh]:[mm]` 表示与 UTC 的偏移量）
例如，`1994-11-05T13:15:30.000Z`（等同于 `1994-11-05T08:15:30-05:00`）。
有关完整的 [ABNF 语法](https://www.rfc-editor.org/rfc/rfc2234)，请查看 [RFC3339 第 5.6 节](https://www.rfc-editor.org/rfc/rfc3339#section-5.6)。
### 互操作性
- 日期和时间部分始终用大写 `T` 分隔（不是小写，也不是空格）。
- 时区指示符 `Z` 始终为大写，而不是小写。
- 秒的小数部分（`[s]`）至少用一位数字表示，最多三位数字表示。
- 精确度较低的字段也可以表示为 Datetime。 例如，服务器可能会将某个 Datetime 值截断至当天午夜。
## 日期 {#date}
“日期”指定活动发生的公历日期，以 UTC 为准。
日期的字符串表示形式使用 ISO 8601（日期和时间表示的国际标准，第 5.2.1.1 节）中的完整、扩展的日历日期表示形式。 这也是 [W3C 日期与时间格式](https://www.w3.org/TR/NOTE-datetime)中的“完整日期”格式。
包含以下必须包含的组成部分：
```
[YYYY]-[MM]-[DD]
```
- `[YYYY]` = 四位数的年份
- `[MM]` = 两位数的月份（01=一月，以此类推）
- `[DD]` = 两位数的月份中的日期（01 到 31）
### 互操作性
- 年、月和日期组件始终用 `-` 分隔。
{{< translation-status-zh-cn raw_title="Datetime formats" raw_link="/api/datetime-format/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

162
content/zh-cn/api/guidelines.md Normal file
View file

@ -0,0 +1,162 @@
---
title: 指南与最佳实践
description: 实现 Mastodon 应用时需要注意的事项。
menu:
docs:
weight: 10
parent: api
---
## 登录 {#login}
**用户必须能够从应用登录到任何 Mastodon 实例**。 这意味着你必须询问服务器的域名，并使用应用注册 API 动态获取 OAuth2 凭据。
{{< page-ref page="client/authorized" >}}
{{< page-relref ref="methods/oauth" caption="OAuth 方法" >}}
{{< page-relref ref="api/oauth-scopes" caption="OAuth 作用域" >}}
## 用户名 {#username}
**去中心化对于用户而言必须是透明的**。 用户应该能够看到给定的用户来自另一个服务器，例如，可以通过在某处显示他们的 `acct` 实现这一点。 请注意，对于本站用户，`acct` 等于 `username`，对于外站用户，`acct` 等于 `username@domain`。
## 处理和排序 ID {#id}
原始的 Mastodon 实体 ID 以整数形式生成并转换为字符串。 但是，这并不意味着 ID *是* 整数，也不应该将其转换为整数！ 这样做可能会因整数溢出而导致客户端应用崩溃，因此请**始终将 ID 视为字符串。**
话虽如此，由于 ID 是数字的字符串表示形式，因此仍然可以通过以下步骤轻松地按时间顺序对其进行排序：
1. 按大小排序。 较新的嘟文将具有更长的 ID。
2. 按字典顺序排序。 较新的嘟文在按位置比较时，至少会有一个数字更高。
## 通过 API 响应进行分页 {#pagination}
许多 API 方法允许你使用 `limit`、`max_id`、`min_id` 和 `since_id` 等参数进行分页以获取更多信息。
limit
: 要返回的最大结果数。 通常存在默认限制和最大限制； 这些限制将根据 API 方法而异。
max_id
: 字符串。 返回的所有结果都将小于此 ID。 该参数实际上设置了结果的上限。
since_id
: 字符串。 返回的所有结果都将大于此 ID。 该参数实际上设置了结果的下限。
min_id
: 字符串。 返回紧邻此 ID 之后的新结果。 该参数实际上在此 ID 处设置了游标，并据此游标向前分页。（自 v2.6.0 起可用。）
例如，我们可能会使用某些参数获取 `https://mastodon.example/api/v1/accounts/1/statuses`，并且在下列情况下，我们将分别获得以下结果：
- 设置 `?max_id=1` 将不返回任何嘟文，因为没有 ID 早于 `1` 的嘟文。
- 设置 `?since_id=1` 将返回最新的嘟文，因为自 `1` 以来已经有很多嘟文。
- 设置 `?min_id=1` 将返回最旧的嘟文，因为 `min_id` 设置了游标。
某些 API 方法作用于未在 API 响应中公开公开的实体 ID，并且仅为后端和数据库所知。（与这种情况有关的通常是引用其他实体的实体，例如引用帐户的 Follow 实体，或引用嘟文的 Favourite 实体等。）
为了解决这个问题，Mastodon 可能会返回指向“prev”和“next”页面的链接。 这些链接通过响应中的 HTTP `Link` 标头提供。 考虑以下虚构的 API 调用：
```http
GET https://mastodon.example/api/v1/endpoint HTTP/1.1
Authorization: Bearer <access_token>
Link: <https://mastodon.example/api/v1/endpoint?max_id=7163058>; rel="next", <https://mastodon.example/api/v1/endpoint?min_id=7275607>; rel="prev"
[
{
// some Entity
},
// more Entities in an Array
]
```
在这种情况下，你可以检索 `Link` 标头并解析它以查找指向较旧或较新页面的链接。 请记住以下规则：
- 这些链接将全部通过一个 `Link` 标头返回，并用逗号和空格 (`, `) 分隔
- 每个链接都包含一个 URL 和一个链接关系，用分号和空格 (`; `) 分隔
- URL 将用尖括号 (`<>`) 括起来，链接关系将用双引号 (`""`) 括起来，并以 `rel=` 为前缀。
- 链接关系的值将为 `prev` 或 `next`。
跟随 `next` 链接应显示较旧的结果。 跟随 `prev` 链接应显示较新的结果。
## 弃用 {#deprecations}
Mastodon 很少删除 API，但这种情况仍然会不时发生。 因此，建议及时了解 Mastodon 的发布版本，并留意已弃用的 API。
此外，为了帮助实施者发现已弃用的 API 的使用情况，Mastodon 4.4.0 使用了 [RFC9745](https://datatracker.ietf.org/doc/html/rfc9745) 中定义的 `Deprecation` 标头。 建议库和应用程序开发人员查找此标头并在其开发环境中显示警告，以便可以在这些已弃用的 API 被淘汰之前发现它们。
## 格式化 {#formatting}
无法从外站服务器获取纯文本内容，并且纯文本语法规则在 Mastodon 和其他 fediverse 应用程序之间可能差异很大。 对于某些属性，例如嘟文的内容，**Mastodon 提供经过清理的 HTML**。 有关更多详细信息，请查看 [HTML 清理]({{< relref "spec/activitypub#sanitization" >}})。 你可以预期一下标签出现在内容中：
* `<p>`
* `<br>`
* `<span>`
* `<a>`
{{< page-relref ref="spec/activitypub#sanitization" caption="ActivityPub > HTML 清理" >}}
### 提及、话题标签和自定义表情 {#tags}
提及和话题标签是 `<a>` 标签。 自定义表情符号保留其纯文本简码形式。 为了赋予这些实体语义含义并添加特殊处理，例如在应用内打开提及的账户而不是按网页打开， [Status]({{< relref "entities/Status" >}}) 中包含了对应的元数据，可以将其与特定标签匹配。
{{< page-relref ref="entities/Status" caption="嘟文实体" >}}
{{< page-relref ref="entities/Status#mentions" caption="嘟文#mentions" >}}
{{< page-relref ref="entities/Status#tags" caption="嘟文#tags" >}}
{{< page-relref ref="entities/Status#emojis" caption="嘟文#emojis" >}}
### 链接缩短 {#links}
Mastodon 中的链接不会使用 URL 缩短器缩短，并且强烈建议不要使用 URL 缩短器。 文本中的 URL 始终计为 23 个字符，旨在以可视化方式缩短。 为此，链接的标记如下所示：
```html
<a href="https://example.com/page/that/is/very/long">
<span class="invisible">https://</span>
<span class="ellipsis">example.com/page</span>
<span class="invisible">/that/is/very/long</span>
</a>
```
带有 `invisible` 类的 span 可以隐藏。 中间的 span 旨在保持可见。 如果 URL 不是非常长，则它可能没有类； 否则，它将具有 `ellipsis` 类。 标记中未插入省略号 (`…`) 字符； 相反，如果你需要在应用中使用它，则应该自己插入它。
## 过滤规则 {#filters}
### 服务端过滤规则（v2，Mastodon 4.0 及更高版本） {#server-filtered}
如果过滤规则针对嘟文，则相应的 FilterResult 将包含在 `filtered` 属性中。 客户端应检查此属性是否存在任何匹配项，并使用它们来应用预期的过滤规则操作。
但是，客户端实现可能仍然希望在客户端执行自己的规则匹配，因为这将允许追溯应用过滤规则更改，而无需从服务器重新获取嘟文。 这样操作时，应用应注意不要忽略具有 `keyword_matches` 以外的其他属性的 `filtered` 条目，以便处理过滤系统的扩展（例如 `status_matches`）。
命中的过滤规则需要根据上下文（`home`、`notifications`、`public`、`thread` 或 `profile`）和到期日期进行过滤。
当至少一个被命中且正在生效的过滤规则在 `filter_action` 的值为 `hide` 时，则不应显示该嘟文。 否则，如果至少一个被命中且正在生效的过滤规则在 `filter_action` 的值为 `warn`，则应隐藏该嘟文并显示警告，并且应允许用户在被告知命中了哪些过滤规则后显示该嘟文（通过 `title` 而不是通过实际匹配的关键字来标识）。
为了进行扩展，`filter_action` 的未知值应被视为 `warn`。
### 客户端过滤（v1，Mastodon 4.0 之前） {#client-filtered}
客户端必须基于从 API 返回的过滤规则执行自己的文本过滤。 服务器将为 `home` 和 `notifications` 上下文应用 `irreversible` 过滤规则，但**其他任何内容仍由客户端过滤**！ 如果以某种方式未通过 `irreversible` 过滤规则删除嘟文，则客户端仍应对其进行过滤。
服务器不会删除过期的过滤规则。 它们应该不再生效，但它们仍然由服务器存储，因为用户可能会更新到期时间以重新启用该过滤规则。 用户最终可以删除这些过滤规则（如果他们希望这样做）。
如果 `whole_word` 为 true，则客户端应用应执行以下操作：
* 为你的应用定义“单词组成字符”。 在官方实现中，JavaScript 中为 `[A-Za-z0-9_]`，Ruby 中为 `[[:word:]]`。 Ruby 使用 POSIX 字符类（字母 | 标记 | 十进制数字 | 连接标点符号）。
* 如果短语以单词字符开头，且匹配范围之前的上一个字符是一个单词字符，则应将它的匹配范围视为未命中。
* 如果短语以单词字符结尾，且匹配范围之后的下一个字符是一个单词字符，则应将它的匹配范围视为未命中。
请查看 Mastodon 源代码中的 `app/javascript/mastodon/selectors/index.js` 和 `app/lib/feed_manager.rb` 以获取更多详细信息。
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/javascript/mastodon/selectors/index.js" caption="app/javascript/mastodon/selectors/index.js" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/feed_manager.rb" caption="app/lib/feed_manager.rb" >}}
## 用于裁剪媒体缩略图的焦点 {#focal-points}
服务器端的预览图像永远不会被裁剪，以便支持各种应用和用户界面。 因此，裁剪必须由应用完成。 为了智能地执行裁剪，可以使用焦点来确保图像的特定部分始终在裁剪后的视口内。 请查看[关于如何定义焦点的指南](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point)。 总之，浮点范围为 -1.0 到 1.0，从左到右或从下到上。 (0,0) 是图像的中心。 (0.5, 0.5) 将位于右上象限的中心。 (-0.5, -0.5) 将位于左下象限的中心。 作为参考，Mastodon 前端中的缩略图一般为 16:9。
{{< figure src="assets/focal-points.jpg" caption="各种焦点及其坐标的演示" >}}
{{< translation-status-zh-cn raw_title="Guidelines and best practices" raw_link="/api/guidelines/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

171
content/zh-cn/api/oauth-scopes.md Normal file
View file

@ -0,0 +1,171 @@
---
title: OAuth 作用域
description: 定义你对 API 拥有哪些权限
menu:
docs:
weight: 20
parent: api
---
## OAuth 作用域
API 访问被划分为若干 OAuth 作用域，这些作用域基于 [访问令牌]({{< relref "api/oauth-tokens" >}}) 注册和请求的作用域，限制 API 客户端可以执行的操作。Mastodon 中的作用域是分层的。例如，如果你请求了 `read` 作用域，你将自动获得 `read:accounts` 的访问权限。然而，**我们建议你的应用程序尽可能请求最有限的作用域**，也就是说，如果你只需要对列表和当前用户账户详情的读取权限，那么你应该使用 `profile read:lists` 作为你的作用域，而不是 `read`。
{{< hint style="info" >}}
如果只是想检索当前已验证用户的详细信息，请使用 `profile` 作用域，该作用域只能访问 [`GET /api/v1/accounts/verify_credentials`]({{< relref "methods/accounts#verify_credentials" >}}) 端点。\
此作用域是在 Mastodon 4.3 中添加的，因此我们建议在使用此作用域时，遵循下面“发现给定 Mastodon 实例支持的 OAuth 作用域”的指引。
{{</ hint >}}
### 发现给定 Mastodon 实例支持的 OAuth 作用域
从 Mastodon 4.3.0 开始，增加了对 [RFC 8414](https://tools.ietf.org/html/rfc8414)'s `GET /.well-known/oauth-authorization-server` 终端的支持，允许你发现 Mastodon 实例支持的作用域（以及其他 OAuth 相关信息，例如终端和授权流程）。
我们建议使用此终端，以便为你的 OAuth 应用程序支持多个 Mastodon 版本。
如果你向 `GET /.well-known/oauth-authorization-server` 终端发出请求，并且返回 404，那么你可以认为该 Mastodon 实例运行的版本低于 4.3。在这种情况下，你需要查看你的应用程序需要的特定作用域，以及你希望支持的 Mastodon 版本范围内最低的通用作用域。
{{< hint style="info" >}}
**示例：** 你想使用 `profile` 作用域，但也想支持没有该作用域且需要 `read:accounts` 的旧 Mastodon 实例。你可以通过向此终端发出请求来发现实例是否支持该作用域。
{{< /hint >}}
{{< page-relref ref="methods/oauth#authorization-server-metadata" caption="GET /.well-known/oauth-authorization-server" >}}
### 可以同时请求多个作用域
在创建应用程序期间，你可以使用 `scopes` 参数指定多个以空格分隔的作用域。在授权阶段，你可以使用 `scope` 查询参数执行相同的操作。
{{< hint style="danger" >}}
在应用程序创建期间保存的作用域集必须包含你将在授权请求中请求的所有作用域，否则，授权将失败。
{{< /hint >}}
{{< hint style="info" >}}
请注意 `scope` 和 `scopes` 的区别。这是因为 `scope` 是一个标准的 OAuth 参数名称，因此它在 OAuth 方法中使用。Mastodon 自己的 REST API 使用更合适的 `scopes` 名称。
{{< /hint >}}
如果你没有在授权请求中指定 `scope`，或者在应用程序创建请求中指定 `scopes`，则生成的访问令牌/应用程序将被分配默认作用域。截至 Mastodon 4.3，当前为 `read`，但将来可能会更改。
{{< page-relref ref="methods/apps#create" caption="POST /api/v1/apps" >}}
### 版本历史 {#versions}
- 0.9.0 - 添加了 read、write、follow 作用域
- 2.4.0 - 添加了用于推送通知的 push 作用域
- 2.4.3 - 添加了细粒度作用域 [#7929](https://github.com/mastodon/mastodon/pull/7929)
- 2.6.0 - 弃用了 `read:reports`（未使用的存根） [#8736/adcf23f](https://github.com/mastodon/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f)
- 2.6.0 - 添加了 `write:conversations` [#9009](https://github.com/mastodon/mastodon/pull/9009)
- 2.9.1 - 添加了管理和审核作用域 [#9387](https://github.com/mastodon/mastodon/pull/9387)
- 3.1.0 - 添加了书签作用域 [#7107](https://github.com/mastodon/mastodon/pull/7107)
- 3.5.0 - 弃用了 `follow` 作用域，转而支持细粒度作用域 [#17678](https://github.com/mastodon/mastodon/pull/17678)
- 4.1.0 - 添加了用于阻止和允许的管理员作用域 [#20918](https://github.com/mastodon/mastodon/pull/20918)
- 4.3.0 - 添加了 `profile` 作用域，仅用于获取有关当前已验证用户的信息 [#29087](https://github.com/mastodon/mastodon/pull/29087), [#30357](https://github.com/mastodon/mastodon/pull/30357)
## 高级作用域列表
我们建议你使用下表中右栏显示的[细粒度作用域](#granular-scopes)，而不是使用以下作用域：
- `read`
- `write`
- `follow` {{%deprecated%}}
- `admin:read`
- `admin:write`
当只需要有关当前已验证用户的信息时，请使用 `profile` 作用域。
### `profile` {#profile}
仅授予对 [`GET /api/v1/accounts/verify_credentials`]({{< relref "methods/accounts#verify_credentials" >}}) 终端的访问权限。允许你仅检索有关当前已验证用户的信息。
### `read` {#read}
授予读取数据的权限，包括其他用户的数据。请求 `read` 也会授予下表中右栏所示的[细粒度作用域](#granular-scopes)。
### `write` {#write}
授予写入数据的权限。请求 `write` 也会授予下表中右栏所示的[细粒度作用域](#granular-scopes)。
### `push` {#push}
授予对 [Web Push API 订阅]({{< relref "methods/push" >}})的访问权限。在 Mastodon 2.4.0 中添加。
### `follow` {#follow}
{{< hint style="danger" >}}
**已弃用**\
此作用域已在 3.5.0 及更高版本中弃用。你应该单独请求[细粒度作用域](#granular-scopes)，或者根据需要请求 `read`/`write` 作用域。
{{< /hint >}}
授予管理关系的权限。请求 `follow` 也会授予下表中右栏所示的[细粒度作用域](#granular-scopes)。
### `admin:read` 和 `admin:write` {#admin}
用于管理和审核 API。在 Mastodon 2.9.1 中添加。
请求 `admin:read` 或 `admin:write` 也会授予下表中右栏所示的[细粒度作用域](#granular-scopes)。
{{< hint style="info" >}}
请注意，没有可用的单一 `admin` 作用域。
{{< /hint >}}
## 细粒度作用域 {#granular}
建议你使用细粒度作用域，除非你确实需要通过使用 `scope` 的 `read write follow push` 对所有内容进行完全访问。
| 作用域 | 细粒度作用域 |
| :------------------------ | :----------------------------------- |
| `profile` | |
| `push` | |
| `read` | |
| | `read:accounts` |
| | `read:blocks` |
| | `read:bookmarks` |
| | `read:favourites` |
| | `read:filters` |
| | `read:follows` |
| | `read:lists` |
| | `read:mutes` |
| | `read:notifications` |
| | `read:search` |
| | `read:statuses` |
| `write` | |
| | `write:accounts` |
| | `write:blocks` |
| | `write:bookmarks` |
| | `write:conversations` |
| | `write:favourites` |
| | `write:filters` |
| | `write:follows` |
| | `write:lists` |
| | `write:media` |
| | `write:mutes` |
| | `write:notifications` |
| | `write:reports` |
| | `write:statuses` |
| `follow` {{%deprecated%}} | |
| | `read:follows` |
| | `write:follows` |
| | `read:blocks` |
| | `write:blocks` |
| | `read:mutes` |
| | `write:mutes` |
| `admin:read` | |
| | `admin:read:accounts` |
| | `admin:read:reports` |
| | `admin:read:domain_allows` |
| | `admin:read:domain_blocks` |
| | `admin:read:ip_blocks` |
| | `admin:read:email_domain_blocks` |
| | `admin:read:canonical_email_blocks` |
| `admin:write` | |
| | `admin:write:accounts` |
| | `admin:write:reports` |
| | `admin:write:domain_allows` |
| | `admin:write:domain_blocks` |
| | `admin:write:ip_blocks` |
| | `admin:write:email_domain_blocks` |
| | `admin:write:canonical_email_blocks` |
## 已删除的作用域 {#removed}
* Mastodon 3.2.0 到 4.3.0 版本确实支持用于端到端加密 API 的 `crypto` 作用域，但是，此功能从未被记录或完全实现，并且已从 4.3.0 版本中删除。使用该作用域注册的任何应用程序在服务器升级到 4.3.0 及更高版本时，都将被删除该作用域。
{{< translation-status-zh-cn raw_title="OAuth Scopes" raw_link="/api/oauth-scopes/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

29
content/zh-cn/api/oauth-tokens.md Normal file
View file

@ -0,0 +1,29 @@
---
title: OAuth 令牌
description: 定义本文档中使用的令牌类型
menu:
docs:
weight: 15
parent: api
---
## OAuth 令牌
Mastodon 支持两种不同的 OAuth 令牌类型：应用令牌和用户令牌。在本文档中，你将在 API 端点的 `OAuth` 字段中看到对这些令牌类型的引用。
`OAuth` 字段也引用了“Public”，在这种情况下，访问 API 端点无需提供 OAuth 访问令牌。
### 应用令牌
要接收应用令牌，你必须执行[客户端凭据授权流程]({{<relref "client/token#flow" >}})，这将为你提供一个令牌，该令牌可用于代表 OAuth 应用程序与 API 交互。目前，只有以下 API 端点接受此令牌类型：
- [`GET /api/v1/apps/verify_credentials`]({{<relref "methods/apps#verify_credentials" >}})
- [`POST /api/v1/accounts`]({{<relref "/methods/accounts#create" >}})
### 用户令牌
要创建用户令牌，你必须执行[授权码授权流程]({{<relref "client/authorized#flow">}})，这将为你提供一个与批准访问授权请求的用户关联的访问令牌。
许多 Mastodon API 需要用户令牌和特定的作用域才能访问。
{{< translation-status-zh-cn raw_title="OAuth Tokens" raw_link="/api/oauth-tokens/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

51
content/zh-cn/api/rate-limits.md Normal file
View file

@ -0,0 +1,51 @@
---
title: 速率限制
description: 定义调用 REST API 的频率
menu:
docs:
weight: 30
parent: api
---
## 响应头
速率限制信息将在响应头中返回：
`X-RateLimit-Limit`
: 在一个时间段内允许的请求数量
`X-RateLimit-Remaining`
: 你还可以发起的请求数量
`X-RateLimit-Reset`
: 你的速率限制何时重置的时间戳
{{< hint style="info" >}}
一个 API 方法可能会受到多个重叠的速率限制。 响应头会返回你最接近超过的那个限制的信息。
{{</ hint >}}
## 限制
默认情况下，以下限制是硬编码的：
### 每个帐户
所有端点和方法可以在 5 分钟内被调用 300 次。
#### 上传媒体
`POST /api/v1/media` 可以在 30 分钟内被调用 30 次。
#### 删除状态
`DELETE /api/v1/statuses/:id` 或 `POST /api/v1/statuses/:id/unreblog` 可以在 30 分钟内被调用 30 次。
### 每个 IP
所有端点和方法可以在 5 分钟内被调用 300 次。
#### 创建帐户
`POST /api/v1/accounts` 可以在 30 分钟内被调用 5 次。
{{< translation-status-zh-cn raw_title="Rate limits" raw_link="/api/rate-limits/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

144
content/zh-cn/client/authorized.md Normal file
View file

@ -0,0 +1,144 @@
---
title: 使用帐户登录
description: 如何从用户处获取授权，并代表用户执行操作。
menu:
docs:
weight: 40
parent: client
---
## 作用域说明 {#scopes}
当我们注册应用及授权用户时，我们需要明确定义生成的令牌将具有哪些权限。这通过使用 [OAuth 作用域]({{< relref "api/oauth-scopes" >}}) 来完成。每个 API 方法都有一个关联的作用域，只有当用于授权的令牌是通过对应的作用域生成的，才能调用该方法。
当授权用户时，`scope` 查询参数必须是我们创建应用时指定的作用域的子集。在我们的示例中，我们在创建应用时指定了 `read write push` 作为我们的作用域，但更好的做法是仅请求你的应用实际需要的 [细粒度作用域]({{< relref "api/oauth-scopes#granular-scopes" >}})。
有关作用域的完整列表，请查看 [OAuth 作用域]({{< relref "api/oauth-scopes" >}})。每个 API 方法的文档也将指定 OAuth [令牌类型]({{< relref "api/oauth-tokens" >}}) 和调用该方法所需的作用域。如果一个端点指定了 `read:statuses` 并且你具有 `read` 权限，那么你将能够调用该端点，因为作用域是分层的。
{{< page-relref ref="api/oauth-scopes" caption="OAuth 作用域" >}}
## **授权码流程示例** {#flow}
与之前的身份验证流程类似，但这次，我们还需要从用户处获取授权。
### 客户端 ID 与密钥 {#client}
在开始操作之前，如果你尚未注册客户端应用，请查看上一页的 [创建我们的应用]({{< relref "client/token#creating-our-application" >}}) 或直接转到 [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) 以获取该方法的完整文档。我们将需要应用的 `client_id` 和 `client_secret`。
### 获得用户授权 {#login}
要获取用户授权，请在浏览器中请求 [GET /oauth/authorize]({{< relref "methods/oauth#authorize" >}}) 并使用以下查询参数：
```bash
https://mastodon.example/oauth/authorize
?client_id=CLIENT_ID
&scope=read+write+push
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&response_type=code
```
请注意以下几点：
* `client_id` 是在注册应用时获得的对应 `client_id`。
* `scope` 必须为我们的应用已注册的作用域的子集。最好只请求你所需要的作用域。 有关更多信息，请查看 [OAuth 作用域]({{< relref "api/oauth-scopes" >}})。
* `redirect_uri` 是我们的应用注册的 URI 之一。
在本示例中，我们仍然使用“非常规”方式，这意味着我们将不得不手动复制和粘贴结果代码，但如果你使用你控制的 URI 注册了你的应用，那么代码将通过你的重定向 URI 的请求处理程序作为参数 `code` 的值返回。有关这方面的更多信息，请查看 API 方法文档的响应部分。
{{< hint style="warning" >}}
你应该将 `code` 查询参数视为密码，确保它不会记录在请求日志中。
{{< /hint >}}
### 获取令牌 {#token}
获取授权 `code` 后，让我们获取一个访问令牌，该令牌将用于对授权用户的请求进行身份验证。为此，像以前一样使用 [POST /oauth/token]({{< relref "methods/oauth#token" >}})，但传递我们刚刚获得的授权码：
```bash
curl -X POST \
-F 'grant_type=authorization_code' \
-F 'client_id=your_client_id_here' \
-F 'client_secret=your_client_secret_here' \
-F 'redirect_uri=urn:ietf:wg:oauth:2.0:oob' \
-F 'code=user_authzcode_here' \
https://mastodon.example/oauth/token
```
请注意以下几点：
- 我们正在请求一个 `grant_type` 为 `authorization_code` 的令牌。
- `client_id` 和 `client_secret` 在你注册应用时已在响应体中提供。
- `redirect_uri` 必须是在注册应用时定义的 URI 之一。
- `code` 只能使用一次。如果你需要获取新令牌，你将需要用户通过重复上述 [授权用户]({{< relref "client/authorized#authorize-the-user" >}}) 步骤再次授权。
此方法的响应是一个 [令牌]({{< relref "entities/token" >}}) 实体。我们将需要 `access_token` 值。获得访问令牌后，将其保存在本地缓存中。
生成的访问令牌的 `scope` 将为在 [授权请求]({{< relref "client/authorized#login" >}}) 期间批准的作用域。
{{< hint style="warning" >}}
你应该将 `access_token` 视为密码。我们建议你在存储在缓存中时加密此值，以防止意外的凭据泄露。
{{< /hint >}}
要在请求中使用它，请将 HTTP 标头 `Authorization: Bearer <access_token>` 添加到任何需要 OAuth 的 API 调用（即，不是公开可访问的）。
让我们通过调用 [GET /api/v1/accounts/verify_credentials]({{< relref "methods/accounts#verify_credentials" >}}) 来验证我们获得的凭据是否有效：
```bash
curl \
-H 'Authorization: Bearer <access_token>' \
https://mastodon.example/api/v1/accounts/verify_credentials
```
如果我们正确地获得了令牌并设置了请求格式，我们应该看到我们的详细信息按 [帐户]({{< relref "entities/account" >}}) 实体的格式返回给我们，其中包含 `source` 参数。
## 以授权用户身份执行操作 {#actions}
有了授权用户的 OAuth 令牌后，我们现在可以以该用户的身份执行令牌作用域内的任何操作。
### 发布和删除嘟文 {#statuses}
- 有关如何创建嘟文的信息，请查看 [POST /api/v1/statuses]({{< relref "methods/statuses#create" >}})。
- 有关创建媒体附件的信息，请查看 [/api/v1/media]({{< relref "methods/media" >}})。
- 有关管理计划嘟文的信息，请查看 [/api/v1/scheduled_statuses]({{< relref "methods/scheduled_statuses" >}})。
### 与时间线交互 {#timelines}
- 有关访问时间线的信息，请查看 [/api/v1/timelines]({{< relref "methods/timelines" >}})。
- 有关保存和加载时间线中的位置的信息，请查看 [/api/v1/markers]({{< relref "methods/markers" >}})。
- 有关对嘟文执行操作的信息，请查看 [/api/v1/statuses]({{< relref "methods/statuses" >}})。
- 有关查看和参与投票的信息，请查看 [/api/v1/polls]({{< relref "methods/polls" >}})。
- 有关获取列表 ID 以与 [GET /api/v1/timelines/list/:list_id]({{< relref "methods/timelines#list" >}}) 一起使用的信息，请查看 [/api/v1/lists]({{< relref "methods/lists" >}})。
- 有关获取私下提及的信息，请查看 [/api/v1/conversations]({{< relref "methods/conversations" >}})。
- 有关喜欢列表的信息，请查看 [/api/v1/favourites]({{< relref "methods/favourites" >}})。
- 有关列出书签的信息，请查看 [/api/v1/bookmarks]({{< relref "methods/bookmarks" >}})。
### 与其他用户交互 {#accounts}
- 有关对其他用户执行操作的信息，请查看 [/api/v1/accounts]({{< relref "methods/accounts" >}})。
- 有关处理关注请求的信息，请查看 [/api/v1/follow_requests]({{< relref "methods/follow_requests" >}})。
- 有关隐藏列表的信息，请查看 [/api/v1/mutes]({{< relref "methods/mutes" >}})。
- 有关屏蔽列表的信息，请查看 [/api/v1/blocks]({{< relref "methods/blocks" >}})。
### 接收通知 {#notifications}
- 有关管理用户通知的信息，请查看 [/api/v1/notifications]({{< relref "methods/notifications" >}})。
- 有关订阅推送通知的信息，请查看 [/api/v1/push]({{< relref "methods/push" >}})。
### 发现功能 {#discovery}
- 有关查询资源的信息，请查看 [/api/v2/search]({{< relref "methods/search#v2" >}})。
- 有关推荐关注的账户的信息，请查看 [/api/v1/suggestions]({{< relref "methods/suggestions" >}})。
### 用户安全功能 {#safety}
- 有关管理过滤关键词的信息，请查看 [/api/v1/filters]({{< relref "methods/filters" >}})。
- 有关管理被屏蔽的实例的信息，请查看 [/api/v1/domain_blocks]({{< relref "methods/domain_blocks" >}})。
- 有关创建举报的信息，请查看 [/api/v1/reports]({{< relref "methods/reports" >}})。
- 有关审核操作的信息，请查看 [/api/v1/admin]({{< relref "methods/admin" >}})。
### 管理帐户信息 {#manage}
- 有关管理用户账户页中的特色帐户的信息，请查看 [/api/v1/endorsements]({{< relref "methods/endorsements" >}})。
- 有关管理用户账户页中的特色话题标签的信息，请查看 [/api/v1/featured_tags]({{< relref "methods/featured_tags" >}})。
- 有关读取用户设置的信息，请查看 [/api/v1/preferences]({{< relref "methods/preferences" >}})。
{{< translation-status-zh-cn raw_title="Logging in with an account" raw_link="/client/authorized/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

139
content/zh-cn/client/intro.md Normal file
View file

@ -0,0 +1,139 @@
---
title: API 入门指南
description: '有关 REST API、HTTP 请求与响应，以及请求参数的入门知识。'
menu:
docs:
weight: 10
parent: client
---
## REST 简介 {#rest}
Mastodon 通过 REST API 提供对其数据的访问通道。REST 代表具象状态传输规范（REpresentational State Transfer），但就我们的目的而言，只需将其视为根据请求发送和接收有关各种资源的信息即可。Mastodon REST API 使用 HTTP 进行请求，使用 JSON 作为其有效载荷。
## 了解 HTTP 请求和响应 {#http}
REST API 端点可以用某些 HTTP 方法调用，并且可以对同一端点使用多种方法。Mastodon API 通常会使用以下 HTTP 方法：
* **GET**：读取或查看资源。
* **POST**：向服务器发送信息。
* **PUT** \| **PATCH**：更新资源。
* **DELETE**：删除资源。
你喜欢的编程语言可能具有用来发出 HTTP 请求的实用程序或库。在本节中，示例将使用 cURL 实用程序，它是一个命令行实用程序，默认包含在许多操作系统中（命令名称 `curl`）。
使用 cURL 时，默认的 HTTP 方法是 GET，但你可以使用 `--request` 或 `-X` 标志指定要发出的请求类型；例如，`curl -X POST` 将发送 POST 请求而不是 GET 请求。你可能还想使用 `-i` 标志来包含可能作为响应的一部分返回的其他 HTTP 标头（如果这与用例相关）。
## 提供参数 {#parameters}
HTTP 请求可以包含各种不同的参数，但最值得注意的是，Mastodon API 可以接收查询字符串、表单数据和 JSON。
{{< hint style="info" >}}
API 同等程度地理解通过 POST 请求体提交的查询字符串、表单数据和 JSON。期望将查询字符串用于 GET 请求，将表单数据或 JSON 用于所有其他请求。
{{< /hint >}}
### 查询字符串 {#query-strings}
可以在请求 URL 的末尾附加查询字符串。可以通过先键入 ?，然后以 parameter=value 的格式附加它们。可以通过用 & 分隔来附加多个查询字符串。例如：
```bash
curl https://mastodon.example/endpoint?q=test&n=0
```
### 表单数据 {#form-data}
你可以单独发送数据，而不是使用查询字符串（使用查询字符串会更改 URL）。使用 cURL 时，可以通过使用 `--data` 或 `-d` 标志传递数据来完成这一点。可以像查询字符串一样一并发送数据，也可以使用多个数据标志作为键值对单独发送数据。你也可以使用 `--form` 或 `-F` 标志作为键值对，这也允许发送多部分数据，例如文件。请求示例：
```bash
# 将原始数据作为查询字符串发送
curl -X POST \
-d 'q=test&n=0' \
https://mastodon.example/endpoint
# 单独发送原始数据
curl -X POST \
-d 'q=test' \
-d 'n=0' \
https://mastodon.example/endpoint
# 显式表单编码；允许使用多部分数据
curl -X POST \
-F 'q=test' \
-F 'n=0' \
-F 'file=@filename.jpg' \
https://mastodon.example/endpoint
```
### JSON {#json}
ECMA-404 中定义的 *JavaScript 对象表示法*。你可以查看 [JSON](https://www.json.org/) 的快速单页概述。
发送 JSON 与发送表单数据类似，但需要添加一个额外的标头来指定数据采用 JSON 格式。要使用 cURL 发送 JSON 请求，请使用标头将内容类型指定为 JSON，然后将 JSON 数据作为表单数据发送：
```bash
curl -X POST \
-H 'Content-Type: application/json' \
-d '{"parameter": "value"}' \
https://mastodon.example/endpoint
```
## 数据类型 {#types}
### 多个值（数组） {#array}
必须使用括号符号对数组参数进行编码。例如，`array[]=foo&array[]=bar` 将转换为以下内容：
```ruby
array = [
'foo',
'bar',
]
```
使用 JSON 时，数组的格式如下：
```json
{
"array": ["foo", "bar"]
}
```
### 嵌套参数（哈希） {#hash}
有些参数需要嵌套。为此，还必须使用括号表示法。例如，`source[privacy]=public&source[language]=en` 将转换为：
```ruby
source = {
privacy: 'public',
language: 'en',
}
```
使用 JSON 时，哈希的格式如下：
```json
{
"source": {
"privacy": "public",
"language": "en"
}
}
```
### 真与假（布尔值） {#boolean}
对于值 `0`、`f`、`F`、`false`、`FALSE`、`off`、`OFF`，布尔值将被认为是 false；对于空字符串，则认为未提供；对于所有其他值，则认为是 true。使用 JSON 数据时，请改用字面量 `true`、`false` 和 `null`。
### 文件 {#file}
文件上传必须使用 `multipart/form-data` 进行编码。
这也可能与数组结合使用。
## 如何使用 API 响应数据 {#responses}
Mastodon REST API 将返回 JSON 作为响应文本。它还会返回 HTTP 标头，这些标头可能有助于处理响应，以及 HTTP 状态代码，该代码应让你知道服务器如何处理请求。可能会出现以下 HTTP 状态代码：
- 200 = OK。请求已成功处理。
- 4xx = 客户端错误。你的请求不正确。最常见的是，你可能会看到 401 Unauthorized（未授权）、404 Not Found（未找到）、410 Gone（已删除）或 422 Unprocessed（无法处理）。
- 5xx = 服务器错误。处理请求时出现问题。最常见的是，你可能会看到 503 Unavailable（服务不可用）。
{{< translation-status-zh-cn raw_title="Getting started with the API" raw_link="/client/intro/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

160
content/zh-cn/client/libraries.md Normal file
View file

@ -0,0 +1,160 @@
---
title: 库与实现
description: 用于各种编程语言的 Mastodon API 的代码、库和 SDK。
menu:
docs:
weight: 60
parent: client
---
感谢我们出色的开发者社区，他们通过各种 API 实现为项目提供了支持。如果你为 Mastodon API 构建了库或 SDK，请[告诉我们](https://github.com/mastodon/mastodon/discussions)，它可能会在未来更新文档时被包含在下面。
请注意检查库的最后更新时间，以及它是否包含你可能想要使用的 API 功能。
## Arduino / ESP32 / IoT {#arduino-iot}
* [lyuba](https://github.com/ringtailsoftware/lyuba)
## C# (.NET Standard) {#c-net-standard}
* [MastodonAPI](https://github.com/golf1052/MastodonAPI)
* [Mastodot](https://github.com/yamachu/Mastodot)
* [Mastonet](https://github.com/glacasa/Mastonet)
* [TootNet](https://github.com/cucmberium/TootNet)
* [mastodon-api-cs](https://github.com/pawotter/mastodon-api-cs)
* [Mastodon.Net](https://github.com/Tlaster/Mastodon.Net)
## C++ {#c}
* [mastodonpp](https://schlomp.space/tastytea/mastodonpp)
## Common Lisp {#common-lisp}
* [mastodon-cl](https://github.com/compufox/mastodon-cl)
* [tooter](https://github.com/Shinmera/tooter)
## Crystal {#crystal}
* [mastodon-api-crystal](https://github.com/renatolond/mastodon-api-crystal)
## Dart {#dart}
* [mastodon_dart](https://pub.dev/packages/mastodon_dart)
* [mastodon-api](https://github.com/mastodon-dart/mastodon-api)
* [mastodon-oauth](https://github.com/mastodon-dart/mastodon-oauth2)
* [mastodon](https://github.com/mykdavies/Mastodon)
* [dartodon](https://github.com/darkcl/dartodon)
* [mastodon_entities](https://github.com/MahanRahmati/mastodon-entities)
## Elixir {#elixir}
* [hunter](https://github.com/milmazz/hunter)
## Erlang {#erlang}
* [masterldon](https://github.com/igb/masterldon)
## Go {#go}
* [go-mastodon](https://github.com/mattn/go-mastodon)
* [madon](https://github.com/McKael/madon)
* [go-mastodon-api](https://github.com/aaronland/go-mastodon-api)
## Haskell {#haskell}
* [hastodon](https://github.com/syucream/hastodon)
## Java {#java}
* [BigBone](https://github.com/andregasser/bigbone)
* [Mastodon4J](https://github.com/Mastodon4J/Mastodon4J)
* [mastodon-jfx](https://github.com/wakingrufus/mastodon-jfx)
## JavaScript {#javascript}
* [megalodon](https://github.com/h3poteto/megalodon)
* [masto.js](https://github.com/neet/masto.js)
* [libodonjs](https://github.com/Zatnosk/libodonjs)
## JavaScript (Browser) {#javascript-browser}
* [mastodon.js](https://github.com/Kirschn/mastodon.js)
## JavaScript (Node.js) {#javascript-node-js}
* [mastodon-api](https://github.com/vanita5/mastodon-api)
## Kotlin {#kotlin}
* [BigBone](https://github.com/andregasser/bigbone)
* [mastodonk](https://github.com/outadoc/mastodonk)
## Nim {#nim}
* [Mastonim](https://github.com/matrix07012/Mastonim)
## Objective-C {#objective-c}
* [Cocotodon](https://github.com/shibafu528/Cocotodon)
## Perl {#perl}
* [Mastodon::Client](https://metacpan.org/pod/Mastodon::Client)
## PHP {#php}
* [mastodon-api-client](https://github.com/vazaha-nl/mastodon-api-client)
* [Phediverse Mastodon REST Client](https://github.com/phediverse/mastodon-rest)
* [TootoPHP](https://framagit.org/MaxKoder/TootoPHP)
* [oauth2-mastodon](https://github.com/lrf141/oauth2-mastodon)
* [MastodonBotPHP](https://github.com/Eleirbag89/MastodonBotPHP)
* [mastodon-api-php-oauth](https://github.com/yks118/Mastodon-api-php-oauth)
* [mastodon-api-php](https://github.com/colorfield/mastodon-api-php)
* [Mastodon API for Laravel](https://github.com/kawax/laravel-mastodon-api)
* [Mastodon for Drupal](https://www.drupal.org/project/mastodon)
* [Mastodon for Socialite](https://github.com/kawax/socialite-mastodon)
## PowerShell {#powershell}
* [Mastodon](https://github.com/JB405/Mastodon)
## Python {#python}
* [Mastodon.py](https://github.com/halcy/Mastodon.py)
* [mastopy](https://gitlab.com/spla/mastopy)
## R {#r}
* [mastodon](https://github.com/ThomasChln/mastodon)
* [rtoot](https://github.com/schochastics/rtoot)
## Ruby {#ruby}
* [mastodon-api](https://github.com/mastodon/mastodon-api)
## Rust {#rust}
* [megalodon-rs](https://github.com/h3poteto/megalodon-rs)
* [mastodon-async](https://github.com/dscottboggs/mastodon-async)
## Scala {#scala}
* [scaladon](https://github.com/schwitzerm/scaladon)
## Scheme {#scheme}
### Guile {#guile}
* [Guile-Mastodon](https://codeberg.org/WammKD/Guile-Mastodon)
## Swift {#swift}
* [Mastodon.swift](https://github.com/Swiftodon/Mastodon.swift)
* [MastodonKit](https://github.com/MastodonKit/MastodonKit)
* [tootsdk](https://github.com/tootsdk/tootsdk)
* [MastodonAPI](https://github.com/li-bei/MastodonAPI)
## TypeScript {#typescript}
* [tsl-mastodon](https://github.com/typescriptlibs/tsl-mastodon-api)
{{< translation-status-zh-cn raw_title="Libraries and implementations" raw_link="/client/libraries/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

116
content/zh-cn/client/public.md Normal file
View file

@ -0,0 +1,116 @@
---
title: 使用公开数据
description: 熟悉端点与实体。
menu:
docs:
weight: 20
parent: client
---
现在，你已经知道如何使用 cURL 或你喜欢的编程语言的 HTTP 实用程序或库来构造 HTTP 请求，那么现在是时候了解端点和响应了。
## 关于端点 {#endpoints}
所有 HTTP 请求都是针对目标 URL 发出的。当你请求网站的数据时，你需要使用特定的 URL。根据 URL 的不同，你的请求将被 HTTP 服务器解释，并向你返回适当的响应。
本文的示例将使用虚构的 Mastodon 网站 mastodon.example，该网站托管在 `https://mastodon.example`。此网站的根目录为 `/`，特定的子目录和路径被称为端点。Mastodon 的 API 端点位于 `/api` 命名空间下，目前大多数方法都将其端点放置于 `/api/v1` 下。请求将按其 HTTP 方法和端点列出；例如，GET /api/v1/endpoint 应解释为对你域名上的该端点发出的 GET 请求，或者换句话说，`https://mastodon.example/api/v1/endpoint`。
## 获取公开时间线 {#timelines}
让我们来了解 Mastodon 公开数据最基础的用例之一——公共时间线。
我们可以尝试请求 [GET /api/v1/timelines/public]({{< relref "methods/timelines" >}})，如下所示：
```bash
curl https://mastodon.example/api/v1/timelines/public
```
哇，响应中有很多文本！公共时间线默认返回 20 条嘟文。
{{< hint style="danger" >}}
一些 Mastodon 实例可能会通过管理设置禁用对其时间线的公开访问。如果你的实例进行了这样的配置，那么你将收到错误响应。
{{</ hint >}}
我们可以使用 `limit` 参数来请求更少的内容。让我们尝试请求相同的端点，但这次限制为 2：
```bash
curl https://mastodon.example/api/v1/timelines/public?limit=2
```
这次我们的响应应该更容易管理。我们可以使用我们选择的实用程序解析或美化这个 JSON，我们应该看到响应类似这样：
```json
[
{
"id": "103206804533200177",
"created_at": "2019-11-26T23:27:31.000Z",
// ...
"visibility": "public",
// ...
},
{
"id": "103206804086086361",
"created_at": "2019-11-26T23:27:32.000Z",
// ...
"visibility": "public",
// ...
}
]
```
对于话题标签，我们可以通过调用 [GET /api/v1/timelines/tag/:hashtag]({{< relref "methods/timelines#tag" >}}) 来执行类似的操作——这里，冒号表示端点的这一部分是路径参数。对于 :hashtag，这意味着我们使用标签的名称（我们再次将返回的结果数限制为 2）：
```bash
curl https://mastodon.example/api/v1/timelines/tag/cats?limit=2
```
我们应该再次看到，在 [Status]({{< relref "entities/status" >}}) 实体的 JSON 数组中返回了 2 条嘟文。我们可以按数组，然后按对象解析 JSON。如果我们使用的是 Python，我们的代码可能如下所示：
```python
import requests
import json
response = requests.get("https://mastodon.example/api/v1/timelines/tag/cats?limit=2")
statuses = json.loads(response.text) # this converts the json to a python list of dictionary
assert statuses[0]["visibility"] == "public" # we are reading a public timeline
print(statuses[0]["content"]) # this prints the status text
```
{{< hint style="info" >}}
解析 JSON 并在你的程序中使用它超出了本教程的范围，因为它会因你选择的编程语言和你的程序设计方案而异。你可以查找有关如何在你选择的编程语言中与 JSON 一起使用的其他教程。
{{</ hint >}}
{{< hint style="info" >}}
[MastoVue](https://mastovue.glitch.me) 是一个应用示例，可让你浏览公开时间线。
{{</ hint >}}
## 获取公开帐户和嘟文 {#posts}
现在，我们熟悉了如何发出请求以及如何处理响应，你可以尝试更多公开数据。以下方法可能会引起你的兴趣：
* 一旦获取了帐户的 id，你就可以使用 [GET /api/v1/accounts/:id]({{< relref "methods/accounts" >}}) 来查看 [Account]({{< relref "entities/account" >}}) 实体。
* 要查看该帐户发布的公开嘟文，你可以使用 [GET /api/v1/accounts/:id/statuses]({{< relref "methods/statuses" >}}) 并解析生成的 [Status]({{< relref "entities/status" >}}) 实体数组。
* 一旦获取了嘟文的 id，你就可以使用 [GET /api/v1/statuses/:id]({{< relref "methods/statuses#get-one" >}}) 来查看 Status 实体。
* 你还可以使用 [GET /api/v1/statuses/:id/reblogged_by]({{< relref "methods/statuses#boosted_by" >}}) 查看谁转发了该嘟文，
* 或 [GET /api/v1/statuses/:id/favourited_by]({{< relref "methods/statuses#favourited_by" >}}) 查看谁喜欢了该嘟文。
* 请求 [GET /api/v1/statuses/:id/context]({{< relref "methods/statuses#context" >}}) 将向你显示该嘟文在对话串中的上级嘟文和下级嘟文。
* 如果该嘟文附加了一个投票，你可以使用 [GET /api/v1/polls/:id]({{< relref "methods/polls" >}}) 单独查看该投票。
帐户和嘟文的 ID 是 Mastodon 网站数据库本地的，并且每个 Mastodon 网站都会有所不同。
## 获取公开实例数据 {#instance}
你可以使用匿名请求做的最后一件事是查看有关 Mastodon 实例的信息。
* 使用 [GET /api/v1/instance]({{< relref "methods/instance#fetch-instance" >}}) 查看常规信息，
* 使用 [GET /api/v1/instance/peers]({{< relref "methods/instance#peers" >}}) 查看其联合列表，或
* 使用 [GET /api/v1/instance/activity]({{< relref "methods/instance#activity" >}}) 查看其每周活动，或
* 使用 [GET /api/v1/custom_emojis]({{< relref "methods/custom_emojis" >}}) 列出所有可用的自定义表情。
* 有关所有可用配置文件的目录，参见 [GET /api/v1/directory]({{< relref "methods/directory" >}})。
* 有关当前热门话题，参见 [GET /api/v1/trends]({{< relref "methods/trends" >}})。
{{< hint style="info" >}}
有关仅使用实例数据可以做什么的实际示例，请查看 [emojos.in](https://emojos.in/)，它允许你预览给定实例中的所有自定义表情符号。
{{</ hint >}}
{{< translation-status-zh-cn raw_title="Playing with public data" raw_link="/client/public/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

89
content/zh-cn/client/token.md Normal file
View file

@ -0,0 +1,89 @@
---
title: 获取客户端应用访问权限
description: 熟悉身份验证和授权的基础知识。
menu:
docs:
weight: 30
parent: client
---
## 身份验证和授权 {#auth}
到目前为止，我们一直在处理公开可用的信息，但并非所有信息都是公开的。某些信息在查看之前需要获得许可，以便审计谁在请求该信息（并可能撤销或拒绝访问）。
这就是 [OAuth]({{< relref "spec/oauth" >}}) 发挥作用的地方。OAuth 是一种生成访问令牌的机制，该令牌可用于 _验证_ 请求来自特定客户端，并确保请求的操作已获得服务器访问控制策略的 _授权_。
## 创建应用 {#app}
我们需要做的第一件事是注册一个应用，以便稍后能够生成访问令牌。可以像这样创建应用：
```bash
curl -X POST \
-F 'client_name=Test Application' \
-F 'redirect_uris=urn:ietf:wg:oauth:2.0:oob' \
-F 'scopes=read write push' \
-F 'website=https://myapp.example' \
https://mastodon.example/api/v1/apps
```
在上面的示例中，我们指定了客户端名称和网站，如果适用，它们将显示在状态中。但更重要的是，请注意以下两个参数：
- `redirect_uris` 被设置为“非常规”令牌生成，这意味着任何生成的令牌都必须手动复制和粘贴。该参数之所以称为 `redirect_uris`，是因为可以定义多个重定向 URI，但是在生成令牌时，我们需要提供一个包含在此列表中的 URI。
- `scopes` 允许我们定义稍后可以请求的权限。但是，稍后请求的范围需要是这些已注册范围的子集。有关更多信息，请查看 [OAuth 范围]({{< relref "api/oauth-scopes" >}})。
你还可以将 JSON 请求体 POST 到同一端点来创建应用，如[POST /api/v1/apps]({{< relref "methods/apps#create-request-example" >}}) 中所述。
{{< hint style="info" >}}
从 Mastodon 4.3.0 开始，你可以通过向 [`/.well-known/oauth-authorization-server`]({{< relref "methods/oauth#authorization-server-metadata" >}}) 端点发出请求来发现服务器支持哪些 `scopes` 以及其他信息。
{{< /hint >}}
我们应该看到返回了一个 [CredentialApplication]({{< relref "entities/application#CredentialApplication" >}}) 实体，但目前，我们只关心 `client_id` 和 `client_secret`。
`client_id` 和 `client_secret` 值将用于生成访问令牌，因此应将其缓存以供以后使用。有关注册应用程序的更多详细信息，请查看 [POST /api/v1/apps]({{< relref "methods/apps#create" >}})。
{{< hint style="warning" >}}
将 `client_id` 和 `client_secret` 属性视为密码。我们建议你在存储在缓存中时对其进行加密，以防止意外的凭据泄露。
{{< /hint >}}
## 身份验证代码示例 {#flow}
现在我们有了一个应用，让我们获取一个访问令牌，该令牌将以刚创建好的应用的身份令服务端验证我们的请求。为此，请使用 [POST /oauth/token]({{< relref "methods/oauth#token" >}}) 如下所示：
```bash
curl -X POST \
-F 'client_id=your_client_id_here' \
-F 'client_secret=your_client_secret_here' \
-F 'redirect_uri=urn:ietf:wg:oauth:2.0:oob' \
-F 'grant_type=client_credentials' \
https://mastodon.example/oauth/token
```
请注意以下事项：
- 注册应用时，`client_id` 和 `client_secret` 已在响应体中提供。
- `redirect_uri` 必须是在注册应用时定义的 URI 之一。
- 我们正在请求 `client_credentials` 的 `grant_type`，默认情况下会为我们提供 `read` 范围。
此方法的响应是一个 [Token]({{< relref "entities/token" >}}) 实体。我们将需要 `access_token` 值。获得访问令牌后，将其保存在你的本地缓存中。
{{< hint style="warning" >}}
将 `access_token` 视为密码。我们建议你在存储在缓存中时加密此值，以防止意外的凭据泄露。
{{< /hint >}}
要在请求中使用它，请将 HTTP 标头 `Authorization: Bearer <access_token>` 添加到任何需要 OAuth 的 API 调用（即，不可公开访问的 API 调用）。
让我们通过调用 [GET /api/v1/apps/verify_credentials]({{< relref "methods/apps#verify_credentials" >}}) 来验证我们获得的凭据是否有效：
```bash
curl \
-H 'Authorization: Bearer <access_token>' \
https://mastodon.example/api/v1/apps/verify_credentials
```
如果我们已经获得了我们的令牌并正确格式化了我们的请求，我们应该看到我们的详细信息通过 [Application]({{< relref "entities/application" >}}) 实体返回给我们（不包括 `client_secret` 属性）。
## 我们可以用身份验证做什么 {#methods}
通过经过身份验证的客户端应用程序，我们可以查看帐户之间的关系，例如 [GET /api/v1/accounts/:id/following]({{< relref "methods/accounts#following" >}}) 和 [GET /api/v1/accounts/:id/followers]({{< relref "methods/accounts#followers" >}})。此外，某些实例可能要求对本来可以公开访问的方法进行身份验证，因此如果你之前在尝试使用公共方法时遇到任何身份验证错误，这些方法现在应该可以工作了。
{{< translation-status-zh-cn raw_title="Obtaining client app access" raw_link="/client/token/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

75
content/zh-cn/dev/code.md Normal file
View file

@ -0,0 +1,75 @@
---
title: 代码结构
description: 在哪里可以找到代码库的特定部分。
menu:
docs:
weight: 30
parent: dev
---
### 代码结构 {#structure}
下面的概述不应被视为完整或权威的，而只是一个粗略的指引，以帮助你在应用程序中确定查找方向。
#### Ruby {#ruby}
`app/controllers`
: 将业务逻辑绑定到模板的代码。
`app/helpers`
: 可以从视图中使用的代码，即常见操作。
`app/lib`
: 不适合其他类别的代码。
`app/models`
: 数据实体及其关联方法的表示。
`app/policies`
: 在调用相关方法之前进行的权限检查和其他验证。
`app/serializers`
: 从模型生成 JSON 的代码。
`app/services`
: 涉及多个模型的复杂逻辑操作。
`app/views`
: 用于生成 HTML 或其他输出的模板。
`app/workers`
: 在请求-响应周期之外执行的代码。
`spec`
: 自动化测试套件。
#### JavaScript {#javascript}
`app/javascript/mastodon`
: 前端 React.js 应用程序的代码。
`app/javascript/packs`
: 非 React.js 页面的代码。
#### CSS 和其他资源 {#assets}
`app/javascript/images`
: 图像。
`app/javascript/styles`
: 通过 Sass 转换为 CSS 的代码。
#### 本地化 {#localizations}
`config/locales`
: 服务器端 YML 格式的本地化。
`app/javascript/mastodon/locales`
: 客户端 JSON 格式的本地化。
所有语言设置文件都经过标准化，以确保一致的格式和键顺序，从而最大限度地减少版本控制中的变更范围。
- 运行 `bundle exec i18n-tasks normalize` 来规范化服务器端翻译。
- 运行 `yarn run i18n:extract` 将客户端翻译提取并将其规范化到 `en.json` 中。
{{< translation-status-zh-cn raw_title="Code structure" raw_link="/dev/code/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

18
content/zh-cn/dev/disclosure.md Normal file
View file

@ -0,0 +1,18 @@
---
title: 漏洞赏金与责任披露
description: 如果你发现了一个严重的漏洞，该怎么办
menu:
docs:
weight: 9999
parent: dev
---
如果你认为你在 Mastodon 中发现了一个安全漏洞（一个令本不应该发生的事情发生的漏洞），你应该将举报发送至 **security@joinmastodon.org**。我们将很乐意通过我们的 OpenCollective 基金，根据问题的严重程度给予此类举报相应的奖励。
请*勿*在 GitHub 或其他公共空间举报此类问题，以便我们有时间发布修复程序，避免 Mastodon 用户面临更高的风险。
{{< hint style="info" >}}
“Mastodon 中的漏洞”是指在我们 GitHub 主要源代码存储库中分发的代码中存在的漏洞。特定于某个实例的漏洞（例如，配置错误）应举报给该实例的所有者，而不是我们。
{{< /hint >}}
{{< translation-status-zh-cn raw_title="Bug bounties and responsible disclosure" raw_link="/dev/disclosure/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

34
content/zh-cn/dev/overview.md Normal file
View file

@ -0,0 +1,34 @@
---
title: 技术概览
description: 关于 Mastodon 架构的描述。
menu:
docs:
weight: 10
parent: dev
---
<style>
#TableOfContents {display: none}
</style>
Mastodon 是一个使用 React.js 前端的 Ruby on Rails 应用程序。 它遵循这些框架的标准实践，因此如果你已经熟悉 Rails 或 React.js，在这里你不会发现任何意外。
在开发环境中，使用 Mastodon 的最佳方式是在你的系统上安装所有依赖项，而不是使用 Docker 或 Vagrant。 你需要 Ruby、Node.js、PostgreSQL 和 Redis，这是 Rails 应用程序的一组相当标准的依赖项。
有关安装这些依赖项的教程可以在文档的“运行 Mastodon”部分中的“从源代码安装”页面上找到。 按照“运行 Mastodon”部分中的安装指南操作后，请查看“设置开发环境”页面，以获取有关如何配置开发环境的更多说明。
### 环境 {#environments}
“环境”是一组用于特定用例的配置值。 环境可能是：开发(development)，你通常打算在其中更改代码；测试(test)，你通常打算在其中运行自动化测试套件；暂存(staging)，旨在向最终用户预览代码；以及生产，旨在面向最终用户。 Mastodon 带有开发、测试和生产的配置。
`RAILS_ENV` 的默认值为 `development`，因此你无需设置任何额外的东西即可在开发模式下运行 Mastodon。 事实上，Mastodon 的所有配置都具有适用于开发环境的正确默认值，因此除非你需要自定义某些内容，否则你不需要 `.env` 文件。 以下是开发环境和生产环境之间的一些不同行为：
- 当你更改 Ruby 代码时，代码会自动重载，这意味着你无需重新启动 Rails 服务端进程即可查看更改
- 你遇到的所有错误的堆栈跟踪都会在浏览器中显示，而不是隐藏在通用错误页面之后
- Webpack 会持续运行，并在你更改任何前端文件时重新编译 JS 和 CSS 资源，并且页面会自动重新加载
- 默认禁用缓存
- 在 `db:seed` 期间会自动创建一个电子邮件为 `admin@localhost:3000` 且密码为 `mastodonadmin` 的管理员帐户
应该注意的是，与 Mastodon 一起分发的 Docker 配置针对生产环境进行了优化，因此极其不适合开发。 另一方面，Vagrant 配置专门用于开发环境，而不是生产用途。
{{< translation-status-zh-cn raw_title="Technical overview" raw_link="/dev/overview/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

208
content/zh-cn/dev/routes.md Normal file
View file

@ -0,0 +1,208 @@
---
title: 路由
description: HTTP 方法如何映射到控制器与操作。
menu:
docs:
weight: 40
parent: dev
---
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/config/routes.rb" caption="config/routes.rb" >}}
## 路由说明 {#routes}
Mastodon 使用 Ruby on Rails，它在 config/routes.rb 中定义其路由配置。本页只解释 Mastodon 如何处理路由的基础知识，你可以查看 [Ruby on Rails 路由指南](https://guides.rubyonrails.org/routing.html) 以获取更详细的信息。
### 路由的构建方式 {#router}
`namespace` 是映射到特定控制器目录的路由的前缀。`resources` 映射到该命名空间目录中的控制器。`scope` 传递到 `module` 的控制器。例如，考虑以下缩写代码：
{{< code title="config/routes.rb 摘录" >}}
```ruby
namespace :api do
namespace :v1 do
resources :statuses, only [:create, :show, :destroy] do
scope module: :statuses do
resource :favourite, only: :create
resource :unfavourite, to: 'favourites#destroy'
member do
get :context
end
end
end
end
end
```
{{< /code >}}
第一个可用的资源是 :statuses，它嵌套在 :api 和 :v1 命名空间下。因此，生成的 HTTP 路由将是 /api/v1/statuses。`only` 定义某些允许的方法，这些方法将在 `app/controllers/api/v1/statuses_controller.rb` 的控制器中定义。
在 /api/v1/statuses 中，有一个模块 :statuses 的作用域，其中定义了其他资源。这些资源的控制器位于 `app/controllers/api/v1/statuses/` 中。例如，:favourite 将由 `app/controllers/api/v1/statuses/favourites_controller.rb` 中的 #create 操作处理，而 :unfavourite 将由同一控制器中的 #destroy 操作处理。
还为该作用域内的任何 `member` 定义了一个自定义方法，或者换句话说，对于任何要由 `app/controllers/api/v1/statuses_controller.rb` 控制的状态，该方法都映射到 GET /api/v1/statuses/:id/context 并且由该控制器中定义的 :context 操作处理。
### 可用方法 {#methods}
#### :index
映射到 HTTP GET，用于列出。由控制器中的 #index 操作处理。
#### :show
映射到 HTTP GET，用于显示单个视图。由控制器中的 #show 操作处理。
#### :create
映射到 HTTP POST。由控制器中的 #create 操作处理。
#### :update
映射到 HTTP PUT。由控制器中的 #update 操作处理。
#### :destroy
映射到 HTTP DELETE。由控制器中的 #destroy 操作处理。
## .well-known {#well-known}
### /.well-known/host-meta {#host-meta}
可扩展资源描述符 (XRD)。 声明 Webfinger 的存在。
### /.well-known/nodeinfo {#nodeinfo}
映射到 `/nodeinfo/2.0` 的 NodeInfo 2.0 端点，用于声明软件名称和版本、协议、使用统计信息以及是否开放注册。
### /.well-known/webfinger {#webfinger}
用于发现 ActivityPub 行为体 ID。有关更多信息，请查看 [对 &gt; WebFinger 的合规性说明]({{< relref "spec/webfinger" >}})。
### /.well-known/change-password {#change-password}
映射到帐户设置页面。
### /.well-known/keybase-proof-config {#keybase}
用于与 Keybase 集成，定义哪些用户名可接受以及可以在哪里检查证明。
{{< hint style="warning" >}}
以下部分正在建设中。
{{< /hint >}}
## 公开 URI {#public}
* `/users/username` = 用户 URI
* `/users/username/remote_follow` = 外站关注对话框
* `/users/username/statuses/id` = 嘟文 URI
* `/@username` = “嘟文”选项卡
* `/@username/with_replies` = “嘟文与回复”选项卡
* `/@username/media` = “媒体”选项卡
* `/@username/tagged/:hashtag` = 用户标记的嘟文
* `/@username/:status_id` = 嘟文永久链接
* `/@username/:status_id/embed` = 可嵌入版本
* `/interact/:status_id` = 外站交互对话框
* `/explore` = 用户目录
* `/explore/:hashtag` = 简介中包含此标签的用户
* `/public` = 公共时间线预览
* `/about` = 落地页
* `/about/more` = 详细描述
* `/terms` = 服务条款
## API {#api}
* /api/oembed
* /api/proofs
* /api/v1
* [statuses]({{< relref "methods/statuses" >}}) [create, show, destroy]
* reblogged_by [index]
* favourited_by [index]
* reblog [create]
* unreblog [POST reblog#destroy]
* favourite [create]
* unfavourite [POST favourites#destroy]
* bookmark [create]
* unbookmark [POST bookmarks#destroy]
* mute [create]
* unmute [POST mutes#destroy]
* pin [create]
* unpin [POST pins#destroy]
* context [GET]
* [timelines]({{< relref "methods/timelines" >}})
* home [show]
* public [show]
* tag [show]
* list [show]
* [streaming]({{< relref "methods/streaming" >}}) [index]
* [custom_emojis]({{< relref "methods/custom_emojis" >}}) [index]
* [suggestions]({{< relref "methods/suggestions" >}}) [index, destroy]
* [scheduled_statuses]({{< relref "methods/scheduled_statuses" >}}) [index, show, update, destroy]
* [preferences]({{< relref "methods/preferences" >}}) [index]
* [conversations]({{< relref "methods/conversations" >}}) [index, destroy]
* read [POST]
* [media]({{< relref "methods/media" >}}) [create, update]
* [blocks]({{< relref "methods/blocks" >}}) [index]
* [mutes]({{< relref "methods/mutes" >}}) [index]
* [favourites]({{< relref "methods/favourites" >}}) [index]
* [bookmarks]({{< relref "methods/bookmarks" >}}) [index]
* [reports]({{< relref "methods/reports" >}}) [create]
* [trends]({{< relref "methods/trends" >}}) [index]
* [filters]({{< relref "methods/filters" >}}) [index, create, show, update, destroy]
* [endorsements]({{< relref "methods/endorsements" >}}) [index]
* [markers]({{< relref "methods/markers" >}}) [index, create]
* [apps]({{< relref "methods/apps" >}}) [create]
* verify_credentials [credentials#show]
* [instance]({{< relref "methods/instance" >}}) [show]
* peers [index]
* activity [show]
* [domain_blocks]({{< relref "methods/domain_blocks" >}}) [show, create, destroy]
* [directory]({{< relref "methods/directory" >}}) [show]
* [follow_requests]({{< relref "methods/follow_requests" >}}) [index]
* authorize [POST]
* reject [POST]
* [notifications]({{< relref "methods/notifications" >}}) [index, show]
* clear [POST]
* dismiss [POST]
* [accounts]({{< relref "methods/accounts" >}})
* verify_credentials [GET credentials#show]
* update_credentials [PATCH credentials#update]
* search [show (search#index)]
* relationships [index]
* [accounts]({{< relref "methods/accounts" >}}) [create, show]
* statuses [index accounts/statuses]
* followers [index accounts/follower_accounts]
* following [index accounts/following_accounts]
* lists [index accounts/lists]
* identity_proofs [index accounts/identity_proofs]
* follow [POST]
* unfollow [POST]
* block [POST]
* unblock [POST]
* mute [POST]
* unmute [POST]
* pin [POST]
* unpin [POST]
* [lists]({{< relref "methods/lists" >}}) [index, create, show, update, destroy]
* accounts [POST accounts/pins#destroy]
* [featured_tags]({{< relref "methods/featured_tags" >}}) [index, create, destroy]
* suggestions [GET suggestions#index]
* [polls]({{< relref "methods/polls" >}}) [create, show]
* votes [create polls/votes]
* [push]({{< relref "methods/push" >}})
* subscription [create, show, update, destroy]
* [admin]({{< relref "methods/admin" >}})
* accounts [index, show]
* enable [POST]
* unsilence [POST]
* unsuspend [POST]
* approve [POST]
* reject [POST]
* action [create account_actions]
* reports [index, show]
* assign_to_self [POST]
* unassign [POST]
* reopen [POST]
* resolve [POST]
* /api/v2
* [search]({{< relref "methods/search" >}}) [GET search#index]
{{< translation-status-zh-cn raw_title="Routes" raw_link="/dev/routes/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

115
content/zh-cn/dev/setup.md Normal file
View file

@ -0,0 +1,115 @@
---
title: 设置开发环境
description: 关于如何开始为 Mastodon 进行开发的说明。
menu:
docs:
weight: 20
parent: dev
---
## Vagrant 使用快速入门 {#vagrant}
为了方便起见，Mastodon 仓库包含一个 Vagrantfile，用于快速设置开发环境，无需手动配置。要使用此开发环境，请使用二进制可执行文件或通过包管理器安装 [Vagrant](https://vagrantup.com)。
安装 Vagrant 后，为方便起见，建议安装一个插件来自动更新你机器的 hosts 文件。这将允许你通过 `http://mastodon.local` 访问开发环境，而无需手动编辑 hosts 文件。为此，请执行以下操作：
```sh
vagrant plugin install vagrant-hostsupdater
```
然后可以启动虚拟机：
```sh
vagrant up
```
启动虚拟机后，你可以启动 Foreman 任务执行器来启动各种 Mastodon 进程：
```sh
vagrant ssh -c "cd /vagrant && foreman start"
```
Mastodon 进程完全启动后，你可以在浏览器中加载 `http://mastodon.local` 以访问 VM 中的 Mastodon 实例。你可以使用用户名 `admin@mastodon.local` 和密码 `mastodonadmin` 以默认管理员用户身份登录。
对源代码的任何更改将在保存文件后立即生效。
要将 VM 重置为全新状态，你可以销毁它并重新启动它：
```sh
vagrant destroy
vagrant up
```
## 从源代码手动安装 {#manual}
你可以按照[生产指南中的前提条件说明]({{<relref "admin/install">}})进行配置，但不要创建 `mastodon` 用户。你也不必安装 `nginx`、`certbot` 和 `python-certbot-nginx`，因为开发环境自带 Web 服务器。 如果你使用的是 Windows，在 WSL2 上设置和运行开发环境也已证明是可行的。
### 设置 {#setup}
在项目目录中运行以下命令：
```sh
bundle install
yarn install
```
在开发环境中，Mastodon 将使用 PostgreSQL 作为当前已登录的 Linux 用户，并使用 `ident` 方法。确保你已为当前已登录的用户创建了 PostgreSQL 用户和数据库：
```sh
sudo -u postgres createuser $YOUR_USERNAME_HERE --createdb
```
现在，你可以创建数据库 `mastodon_development` 和 `mastodon_test`，将 schema 加载到其中，并将 `db/seeds/` 中定义的种子数据加载到 `mastodon_development` 中。
```sh
rails db:setup
```
现在，你可以在浏览器中启动 `http://localhost:3000` 并使用默认管理员用户 (`admin@localhost` / `mastodonadmin`) 登录。
{{<hint style="warning">}}
默认情况下，Mastodon 将在端口 3000 上运行。如果你为其配置了其他端口，则生成的管理员帐户也将使用该端口号。
{{</hint>}}
### 运行 {#running}
需要运行多个进程才能实现 Mastodon 的全部功能，尽管可以选择性地省略它们。要仅使用一个命令运行所有进程，你可以安装并使用 Foreman：
```sh
gem install foreman --no-document
foreman start
```
这将启动 `Procfile.dev` 中定义的进程，这将为你提供：一个 Rails 服务端、一个 Webpack 服务端、一个流式 API 服务端和一个 Sidekiq。当然，你也可以根据需要单独运行任何这些进程。
## 在开发中使用电子邮件
在开发模式下，Mastodon 将使用一个名为 [Letter Opener](https://github.com/ryanb/letter_opener) 的 gem 来“发送”电子邮件，这允许你在浏览器中调试电子邮件，而无需通过 SMTP 服务器实际发送电子邮件。
为了使用电子邮件，你需要运行 Sidekiq、Redis 和 PostgreSQL，然后可以通过访问 `http://localhost:3000/letter_opener/` 来查看电子邮件。
如果你在 docker 中进行开发，则需要设置 `REMOTE_DEV=true` 环境变量。
## 用于测试的有用命令 {#testing}
`rspec`
: 运行 Ruby 测试套件
`yarn run test`
: 运行 JavaScript 测试套件
`rubocop`
: 检查 Ruby 代码是否符合我们的代码风格
## 更新你的开发实例 {#update}
`bundle install`
: 更新 Ruby gems 并安装任何新的依赖项
`yarn install`
: 更新 Javascript 包并安装任何新的依赖项
`RAILS_ENV=development rails db:migrate`
: 为你的开发实例的数据库运行新的数据库迁移
{{< translation-status-zh-cn raw_title="Setting up a dev environment" raw_link="/dev/setup/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

460
content/zh-cn/entities/Account.md Normal file
View file

@ -0,0 +1,460 @@
---
title: Account
description: 表示 Mastodon 的一个账户及其相关的账户。
menu:
docs:
parent: entities
aliases: [
"/entities/source/",
"/entities/Source/",
"/entities/field/",
"/entities/Field/",
"/entities/account",
"/entities/Account",
"/entities/credentialaccount",
"/entities/CredentialAccount",
"/entities/mutedaccount",
"/entities/MutedAccount",
"/api/entities/source/",
"/api/entities/Source/",
"/api/entities/field/",
"/api/entities/Field/",
"/api/entities/account",
"/api/entities/Account",
"/api/entities/credentialaccount",
"/api/entities/CredentialAccount",
"/api/entities/mutedaccount",
"/api/entities/MutedAccount",
]
---
## 示例
```json
{
"id": "23634",
"username": "noiob",
"acct": "noiob@awoo.space",
"display_name": "ikea shark fan account",
"locked": false,
"bot": false,
"created_at": "2017-02-08T02:00:53.274Z",
"attribution_domains": ["example.com", "example.net"],
"note": "<p>:ms_rainbow_flag:​ :ms_bisexual_flagweb:​ :ms_nonbinary_flag:​ <a href=\"https://awoo.space/tags/awoo\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>awoo</span}.space <a href=\"https://awoo.space/tags/admin\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>admin</span} ~ <a href=\"https://awoo.space/tags/bi\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>bi</span} ~ <a href=\"https://awoo.space/tags/nonbinary\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>nonbinary</span} ~ compsci student ~ likes video <a href=\"https://awoo.space/tags/games\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>games</span} and weird/ old electronics and will post obsessively about both ~ avatar by <span class=\"h-card\"><a href=\"https://weirder.earth/@dzuk\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>dzuk</span}</span></p>",
"url": "https://awoo.space/@noiob",
"avatar": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
"avatar_static": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
"header": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
"header_static": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
"followers_count": 547,
"following_count": 404,
"statuses_count": 28468,
"last_status_at": "2019-11-17",
"emojis": [
{
"shortcode": "ms_rainbow_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/028/691/original/6de008d6281f4f59.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/028/691/static/6de008d6281f4f59.png",
"visible_in_picker": true
},
{
"shortcode": "ms_bisexual_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/050/744/original/02f94a5fca7eaf78.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/050/744/static/02f94a5fca7eaf78.png",
"visible_in_picker": true
},
{
"shortcode": "ms_nonbinary_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/105/099/original/8106088bd4782072.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/105/099/static/8106088bd4782072.png",
"visible_in_picker": true
}
],
"fields": [
{
"name": "Pronouns",
"value": "they/them",
"verified_at": null
},
{
"name": "Alt",
"value": "<span class=\"h-card\"><a href=\"https://cybre.space/@noiob\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>noiob</span}</span>",
"verified_at": null
},
{
"name": "Bots",
"value": "<span class=\"h-card\"><a href=\"https://botsin.space/@darksouls\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>darksouls</span}</span>, <span class=\"h-card\"><a href=\"https://botsin.space/@nierautomata\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>nierautomata</span}</span>, <span class=\"h-card\"><a href=\"https://mastodon.social/@fedi\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>fedi</span}</span>, code for <span class=\"h-card\"><a href=\"https://botsin.space/@awoobot\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>awoobot</span}</span>",
"verified_at": null
},
{
"name": "Website",
"value": "<a href=\"http://shork.xyz\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">http://</span><span class=\"\">shork.xyz</span><span class=\"invisible\"></span}",
"verified_at": "2019-11-10T10:31:10.744+00:00"
}
]
}
```
## 属性
### `id` {#id}
**描述:** 帐户 ID。\
**类型:** 字符串（从整数转换而来，但不保证一定是数字）\
**版本历史:**\
0.1.0 - 添加
### `username` {#username}
**描述:** 帐户的用户名，不包含域名。\
**类型:** 字符串\
**版本历史:**\
0.1.0 - 添加
### `acct` {#acct}
**描述:** Webfinger 帐户 URI。对于本站用户，等于 `username`；对于外站用户，等于 `username@domain`。\
**类型:** 字符串\
**版本历史:**\
0.1.0 - 添加
### `url` {#url}
**描述:** 账户页的位置。\
**类型:** 字符串 (URL)\
**版本历史:**\
0.1.0 - 添加
### `display_name` {#display_name}
**描述:** 账户的昵称。\
**类型:** 字符串\
**版本历史:**\
0.1.0 - 添加
### `note` {#note}
**描述:** 账户的简介或描述。\
**类型:** 字符串 (HTML)\
**版本历史:**\
0.1.0 - 添加
### `avatar` {#avatar}
**描述:** 一个图像图标，显示在嘟文旁边和账户中。\
**类型:** 字符串 (URL)\
**版本历史:**\
0.1.0 - 添加
### `avatar_static` {#avatar_static}
**描述:** 头像的静态版本。如果其值为静态图像，则等于 `avatar`；如果 `avatar` 是动画 GIF，则不同。\
**类型:** 字符串 (URL)\
**版本历史:**\
1.1.2 - 添加
### `header` {#header}
**描述:** 显示在账户上方和账户资料卡中的横幅图片。\
**类型:** 字符串 (URL)\
**版本历史:**\
0.1.0 - 添加
### `header_static` {#header_static}
**描述:** 横幅图片的静态版本。如果其值为静态图像，则等于 `header`；如果 `header` 是动画 GIF，则不同。\
**类型:** 字符串 (URL)\
**版本历史:**\
1.1.2 - 添加
### `locked` {#locked}
**描述:** 帐户是否手动批准关注请求。\
**类型:** 布尔值\
**版本历史:**\
0.1.0 - 添加
### `fields` {#fields}
**描述:** 附加到账户的其他元数据，以名称-值对的形式存在。\
**类型:** [Field](#Field) 的数组\
**版本历史:**\
2.4.0 - 添加
### `emojis` {#emojis}
**描述:** 在渲染账户时要使用的自定义表情实体。\
**类型:** [CustomEmoji]({{< relref "entities/CustomEmoji" >}}) 数组\
**版本历史:**\
2.4.0 - 添加
### `bot` {#bot}
**描述:** 表示该帐户可能执行自动操作、可能未被监控或标识为机器人。\
**类型:** 布尔值\
**版本历史:**\
2.4.0 - 添加
### `group` {#group}
**描述:** 表示该帐户代表一个组用户组。\
**类型:** 布尔值\
**版本历史:**\
3.1.0 - 添加
### `discoverable` {#discoverable}
**描述:** 帐户是否已选择加入账户目录等发现功能。\
**类型:** {{<nullable>}} 布尔值\
**版本历史:**\
3.1.0 - 添加
### `noindex` {{%optional%}} {#noindex}
**描述:** 该用户是否已选择不被搜索引擎索引。\
**类型:** {{<nullable>}} 布尔值\
**版本历史:**\
4.0.0 - 添加
### `moved` {{%optional%}} {#moved}
**描述:** 表示该账户当前处于非活动状态，并且其用户已转移到新帐户。\
**类型:** {{<nullable>}} [Account]({{< relref "entities/Account" >}})，如果账户被封禁，则为 null。\
**版本历史:**\
2.1.0 - 添加
### `suspended` {{%optional%}} {#suspended}
**描述:** 仅当帐户被封禁时才返回的额外属性。\
**类型:** 布尔值\
**版本历史:**\
3.3.0 - 添加
### `limited` {{%optional%}} {#limited}
**描述:** 一个额外的属性，仅当帐户被隐藏时才会返回。如果为真，则表示应将帐户隐藏并在账户页显示警告。\
**类型:** 布尔值\
**版本历史:**\
3.5.3 - 添加
### `created_at` {#created_at}
**描述:** 帐户的创建时间。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
0.1.0 - 添加\
3.4.0 - 现在解析为午夜，而不是确切的时间
### `last_status_at` {#last_status_at}
**描述:** 发布最新嘟文的时间。\
**类型:** {{<nullable>}} 字符串 ([Date](/api/datetime-format#date))，如果没有嘟文则为 null\
**版本历史:**\
3.0.0 - 添加\
3.1.0 - 现在只返回日期，没有时间
### `statuses_count` {#statuses_count}
**描述:** 此帐户拥有多少条嘟文。\
**类型:** 整数\
**版本历史:**\
0.1.0 - 添加
### `followers_count` {#followers_count}
**描述:** 本实例举报的此账户的关注者数量。\
**类型:** 整数\
**版本历史:**\
0.1.0 - 添加
### `following_count` {#following_count}
**描述:** 本实例举报的此账户的关注数量。\
**类型:** 整数\
**版本历史:**\
0.1.0 - 添加
## CredentialAccount 实体属性 {#CredentialAccount}
```json
{
"id": "14715",
"username": "trwnh",
"acct": "trwnh",
"display_name": "infinite love ⴳ",
// ...
"attribution_domains": ["example.com", "example.net"],
"note": "<p>i have approximate knowledge of many things. perpetual student. (nb/ace/they)</p><p>xmpp/email: a@trwnh.com<br /><a href=\"https://trwnh.com\" target=\"_blank\" rel=\"nofollow noopener noreferrer\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a><br />help me live: <a href=\"https://liberapay.com/trwnh\" target=\"_blank\" rel=\"nofollow noopener noreferrer\"><span class=\"invisible\">https://</span><span class=\"\">liberapay.com/trwnh</span><span class=\"invisible\"></span></a> or paypal</p><p>- my triggers are moths and glitter<br />- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise<br />- dm me if i did something wrong, so i can improve<br />- purest person on fedi, do not lewd in my presence</p>",
// ...
"source": {
"privacy": "public",
"sensitive": false,
"language": "",
"note": "i have approximate knowledge of many things. perpetual student. (nb/ace/they)\r\n\r\nxmpp/email: a@trwnh.com\r\nhttps://trwnh.com\r\nhelp me live: https://liberapay.com/trwnh or paypal\r\n\r\n- my triggers are moths and glitter\r\n- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise\r\n- dm me if i did something wrong, so i can improve\r\n- purest person on fedi, do not lewd in my presence",
"fields": [
{
"name": "Website",
"value": "https://trwnh.com",
"verified_at": "2019-08-29T04:14:55.571+00:00"
},
{
"name": "Portfolio",
"value": "https://abdullahtarawneh.com",
"verified_at": "2021-02-11T20:34:13.574+00:00"
},
{
"name": "Fan of:",
"value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
"verified_at": null
},
{
"name": "What to expect:",
"value": "talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people! and to spill my thoughts.",
"verified_at": null
}
],
"follow_requests_count": 5
},
// ...
"fields": [
{
"name": "Website",
"value": "<a href=\"https://trwnh.com\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a>",
"verified_at": "2019-08-29T04:14:55.571+00:00"
},
{
"name": "Portfolio",
"value": "<a href=\"https://abdullahtarawneh.com\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"><span class=\"invisible\">https://</span><span class=\"\">abdullahtarawneh.com</span><span class=\"invisible\"></span></a>",
"verified_at": "2021-02-11T20:34:13.574+00:00"
},
{
"name": "Fan of:",
"value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo&#39;s Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
"verified_at": null
},
{
"name": "What to expect:",
"value": "talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i&#39;m just here to hang out and talk to cool people! and to spill my thoughts.",
"verified_at": null
}
],
"role": {
"id": "-99",
"name": "",
"permissions": "65536",
"color": "",
"highlighted": false
}
}
```
### `attribution_domains` {#attribution_domains}
**描述:** 允许对帐户进行标记的网站域。\
**类型:** 字符串数组\
**版本历史:**\
4.4.0 (`mastodon` [API version]({{< relref "entities/Instance#api-versions" >}}) 3) - 添加
### `source` {#source}
**描述:** 一个额外的属性，其中包含要与 API 方法一起使用的源值，这些方法[验证凭据]({{< relref "methods/accounts#verify_credentials" >}})和[更新凭据]({{< relref "methods/accounts#update_credentials" >}})。\
**类型:** 哈希\
**版本历史:**\
2.4.0 - 添加
#### `source[note]` {#source-note}
**描述:** 账户简介，采用纯文本而不是 HTML。\
**类型:** 字符串\
**版本历史:**\
1.5.0 - 添加
#### `source[fields]` {#source-fields}
**描述:** 关于帐户的元数据。\
**类型:** [Field](#Field) 数组\
**版本历史:**\
2.4.0 - 添加
#### `source[privacy]` {#source-privacy}
**描述:** 用于新嘟文的默认嘟文隐私值。\
**类型:** 字符串（可枚举，oneOf）\
`public`=公开嘟文\
`unlisted`=未列出嘟文\
`private`=仅关注者可见嘟文\
`direct`=私下提及嘟文\
**版本历史:**\
1.5.0 - 添加
#### `source[sensitive]` {#source-sensitive}
**描述:** 默认情况下是否应将新嘟文标记为敏感。\
**类型:** 布尔值\
**版本历史:**\
1.5.0 - 添加
#### `source[language]` {#source-language}
**描述:** 新嘟文的默认发布语言。\
**类型:** 字符串（ISO 639-1 语言双字母代码）或空字符串\
**版本历史:**\
2.4.2 - 添加
#### `source[follow_requests_count]` {#follow_requests_count}
**描述:** 待处理的关注请求数。\
**类型:** 整数\
**版本历史:**\
3.0.0 - 添加
### `role` {#role}
**描述:** 分配给当前授权用户的用户组。\
**类型:** [Role]({{< relref "entities/Role" >}})\
**版本历史:**\
4.0.0 - 添加
## MutedAccount 实体属性 {#MutedAccount}
### `mute_expires_at` {#mute_expires_at}
**描述:** 定时隐藏到期的时间（如果适用）。\
**类型:** {{<nullable>}} 字符串 ([Datetime](/api/datetime-format#datetime))；如果隐藏是无限期的，则为 null\
**版本历史:**\
3.3.0 - 添加
## Field 实体属性 {#Field}
### `name` {#name}
**描述:** 给定字段的键值对的键。\
**类型:** 字符串\
**版本历史:**\
2.4.0 - 添加
### `value` {#value}
**描述:** 与 `name` 键关联的值。\
**类型:** 字符串 (HTML)\
**版本历史:**\
2.4.0 - 添加
### `verified_at` {#verified_at}
**描述:** 实例验证 rel="me" 链接的 URL 值的时间戳。\
**类型:** {{<nullable>}} 字符串 ([Datetime](/api/datetime-format#datetime))（如果 `value` 是经过验证的 URL）。否则，为 null。\
**版本历史:**\
2.6.0 - 添加
## 另请参考
{{< page-relref ref="methods/accounts" caption="accounts API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/account_serializer.rb" caption="app/serializers/rest/account_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/credential_account_serializer.rb" caption="app/serializers/rest/credential_account_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/muted_account_serializer.rb" caption="app/serializers/rest/muted_account_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Account" raw_link="/entities/Account/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

71
content/zh-cn/entities/AccountWarning.md Normal file
View file

@ -0,0 +1,71 @@
---
title: AccountWarning
description: 针对特定帐户的管理警告。
menu:
docs:
parent: entities
aliases: [
"/entities/AccountWarning",
"/api/entities/AccountWarning",
]
---
## 属性
### `id` {#id}
**描述：** 数据库中帐户警告的 ID。\
**类型：** 字符串（从整数转换而来）\
**版本历史：**\
4.3.0 - 添加
### `action` {#action}
**描述：** 对帐户采取的措施。\
**类型：** 字符串（枚举类型 oneOf）\
`none` = 未采取任何措施，这只是一个简单的警告\
`disable` = 目标账户被停用\
`mark_statuses_as_sensitive` = 来自目标帐户的特定嘟文已被标记为敏感\
`delete_statuses` = 来自目标帐户的特定嘟文已被删除\
`sensitive` = 来自目标帐户的所有嘟文都被标记为敏感\
`silence` = 目标帐户已被限制\
`suspend` = 目标帐户已被封禁\
**版本历史：**\
4.3.0 - 添加
### `text` {#text}
**描述：** 管理员向目标帐户发送的消息。\
**类型：** 字符串\
**版本历史：**\
4.3.0 - 添加
### `status_ids` {#status_ids}
**描述：** 与警告相关的嘟文 ID 列表。当 `action` 为 `mark_statuses_as_sensitive` 或 `delete_statuses` 时，该字段表示受影响的嘟文。\
**类型：** {{<nullable>}} 字符串数组（从整数转换而来），或 null\
**版本历史：**\
4.3.0 - 添加
### `target_account` {#target_account}
**描述：** 管理操作针对的目标帐户。\
**类型：** [Account]({{< relref "entities/Account" >}})\
**版本历史：**\
4.3.0 - 添加
### `appeal` {#appeal}
**描述：** 目标帐户提交的申诉（如有）。\
**类型：** {{<nullable>}} [Appeal]({{< relref "entities/Appeal" >}})，或 null\
**版本历史：**\
4.3.0 - 添加
### `created_at` {#created_at}
**描述：** 事件发生的时间。\
**类型：** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史：**\
4.3.0 - 添加
{{< translation-status-zh-cn raw_title="AccountWarning" raw_link="/entities/AccountWarning/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

215
content/zh-cn/entities/Admin_Account.md Normal file
View file

@ -0,0 +1,215 @@
---
title: Admin::Account
description: 给定账户在管理视图下的信息。
menu:
docs:
parent: entities
aliases: [
"/entities/admin-account",
"/entities/Admin-Account",
"/entities/admin_account",
"/entities/Admin_Account",
"/api/entities/admin-account",
"/api/entities/Admin-Account",
"/api/entities/admin_account",
"/api/entities/Admin_Account",
]
---
## 示例
```json
{
"id": "108965278956942133",
"username": "admin",
"domain": null,
"created_at": "2022-09-08T23:03:26.762Z",
"email": "admin@mastodon.local",
"ip": "192.168.42.1",
"role": {
"id": 3,
"name": "Owner",
"color": "",
"position": 1000,
"permissions": 1,
"highlighted": true,
"created_at": "2022-09-08T22:48:07.983Z",
"updated_at": "2022-09-08T22:48:07.983Z"
},
"confirmed": true,
"suspended": false,
"silenced": false,
"disabled": false,
"approved": true,
"locale": null,
"invite_request": null,
"ips": [
{
"ip": "192.168.42.1",
"used_at": "2022-09-15T01:38:58.851Z"
}
],
"account": {
"id": "108965278956942133",
"username": "admin",
"acct": "admin",
"display_name": "",
"locked": false,
"bot": false,
"discoverable": null,
"group": false,
"created_at": "2022-09-08T00:00:00.000Z",
"note": "",
"url": "http://mastodon.local/@admin",
"avatar": "http://mastodon.local/avatars/original/missing.png",
"avatar_static": "http://mastodon.local/avatars/original/missing.png",
"header": "http://mastodon.local/headers/original/missing.png",
"header_static": "http://mastodon.local/headers/original/missing.png",
"followers_count": 0,
"following_count": 0,
"statuses_count": 0,
"last_status_at": null,
"emojis": [],
"fields": []
}
}
```
## 属性
### `id` {#id}
**描述:** 数据库中账户的 ID。\
**类型:** 字符串（从整数转换而来，但不保证一定为数字）\
**版本历史:**\
2.9.1 - 添加
### `username` {#username}
**描述:** 账户的用户名。\
**类型:** 字符串\
**版本历史:**\
2.9.1 - 添加
### `domain` {#domain}
**描述:** 外站账户的域名。\
**类型:** {{<nullable>}} 字符串，对本站账户为 null\
**版本历史:**\
2.9.1 - 添加
### `created_at` {#created_at}
**描述:** 账户首次被发现的时间。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
2.9.1 - 添加
### `email` {#email}
**描述:** 与账户关联的电子邮件地址。\
**类型:** 字符串\
**版本历史:**\
2.9.1 - 添加
### `ip` {#ip}
**描述:** 最后一次登录此账户使用的 IP 地址。\
**类型:** {{<nullable>}} 字符串\
**版本历史:**\
2.9.1 - 添加\
3.5.0 - 由于一个错误，返回类型从 String 更改为 [Admin::Ip]({{< relref "entities/Admin_Ip" >}})\
4.0.0 - 错误已修复，返回类型现在再次为 String
### `ips` {#ip}
**描述:** 与此账户关联的所有已知 IP 地址。\
**类型:** [Admin::Ip]({{< relref "entities/Admin_Ip" >}}) 数组\
**版本历史:**\
3.5.0 - 添加
### `locale` {#locale}
**描述:** 账户的语言设置。\
**类型:** 字符串（ISO 639 Part 1 双字符语言代码）\
**版本历史:**\
2.9.1 - 添加
### `invite_request` {#invite_request}
**描述:** 请求邀请时给出的理由（对于需要手动批准注册的实例）\
**类型:** {{<nullable>}} 字符串\
**版本历史:**\
2.9.1 - 添加
### `role` {#role}
**描述:** 账户的当前用户组。\
**类型:** [Role]({{<relref "entities/role">}})\
**版本历史:**\
2.9.1 - 添加，返回一个 String (可枚举，`user` `moderator` `admin` 其中之一)\
4.0.0 - 现在使用 Role 实体
### `confirmed` {#confirmed}
**描述:** 账户是否已确认其电子邮件地址。\
**类型:** 布尔值\
**版本历史:**\
2.9.1 - 添加
### `approved` {#approved}
**描述:** 账户当前是否已批准。\
**类型:** 布尔值\
**版本历史:**\
2.9.1 - 添加
### `disabled` {#disabled}
**描述:** 账户当前是否已被禁用。\
**类型:** 布尔值\
**版本历史:**\
2.9.1 - 添加
### `silenced` {#silenced}
**描述:** 账户当前是否已被隐藏。
**类型:** 布尔值\
**版本历史:**\
2.9.1 - 添加
### `suspended` {#suspended}
**描述:** 账户当前是否已被封禁。\
**类型:** 布尔值\
**版本历史:**\
2.9.1 - 添加
### `account` {#account}
**描述:** 关于账户的用户级信息。\
**类型:** [Account]({{< relref "entities/account" >}})\
**版本历史:**\
2.9.1 - 添加
### `created_by_application_id` {{%optional%}} {#created_by_application_id}
**描述:** 创建此帐户的 [Application]({{< relref "entities/application" >}}) 的 ID（如果适用）。\
**类型:** 字符串（从整数转换而来，但不保证一定为数字）\
**版本历史:**\
2.9.1 - 添加
### `invited_by_account_id` {{%optional%}} {#invited_by_account_id}
**描述:** 邀请此用户的 [Account]({{< relref "entities/account" >}}) 的 ID（如果适用）。\
**类型:** 字符串（从整数转换而来，但不保证一定为数字）\
**版本历史:**\
2.9.1 - 添加
## 另请参考
{{< page-relref ref="methods/admin/accounts" caption="admin/accounts API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/account_serializer.rb" caption="app/serializers/rest/admin/account_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Admin::Account" raw_link="/entities/Admin_Account/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

50
content/zh-cn/entities/Admin_CanonicalEmailBlock.md Normal file
View file

@ -0,0 +1,50 @@
---
title: Admin::CanonicalEmailBlock
description: 表示一个标准电子邮件屏蔽（将被哈希处理）。
menu:
docs:
parent: entities
aliases: [
"/entities/admin-canonicalemailblock",
"/entities/Admin-CanonicalEmailBlock",
"/entities/admin_canonicalemailblock",
"/entities/Admin_CanonicalEmailBlock",
"/api/entities/admin-canonicalemailblock",
"/api/entities/Admin-CanonicalEmailBlock",
"/api/entities/admin_canonicalemailblock",
"/api/entities/Admin_CanonicalEmailBlock",
]
---
## 示例
```json
{
"id": "2",
"canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
}
```
## 属性
### `id` {#id}
**描述:** 数据库中电子邮件屏蔽的 ID。\
**类型:** 字符串 (从整数转换，但不能保证是数字)\
**版本历史:**\
4.0.0 - 添加
### `canonical_email_hash` {#canonical_email_hash}
**描述:** 标准电子邮件地址的 SHA256 哈希值。\
**类型:** 字符串 (SHA256)\
**版本历史:**\
4.0.0 - 添加
## 参见
{{< page-relref ref="methods/admin/canonical_email_blocks" caption="admin/canonical_email_blocks API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/canonical_email_block_serializer.rb" caption="app/serializers/rest/admin/canonical_email_block_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Admin::CanonicalEmailBlock" raw_link="/entities/Admin_CanonicalEmailBlock/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

137
content/zh-cn/entities/Admin_Cohort.md Normal file
View file

@ -0,0 +1,137 @@
---
title: Admin::Cohort
description: 表示一组留存指标。
menu:
docs:
parent: entities
aliases: [
"/entities/admin-cohort",
"/entities/Admin-Cohort",
"/entities/admin_cohort",
"/entities/Admin_Cohort",
"/api/entities/admin-cohort",
"/api/entities/Admin-Cohort",
"/api/entities/admin_cohort",
"/api/entities/Admin_Cohort",
]
---
## 示例
以下是 2022 年 9 月的月度留存数据示例，假设有 2 位用户在 2022 年 9 月注册，并在该月至少活跃过一次。
```json
{
"period": "2022-09-01T00:00:00+00:00",
"frequency": "month",
"data": [
{
"date": "2022-09-01T00:00:00+00:00",
"rate": 1.0,
"value": "2"
}
]
}
```
以下是 2022 年 9 月 8 日至 2022 年 9 月 14 日这一周的每日留存数据示例，假设有 2 位用户在 2022 年 9 月 8 日注册，其中 1 位用户在 2022 年 9 月 9 日后停止活跃。
```json
{
"period": "2022-09-08T00:00:00+00:00",
"frequency": "day",
"data": [
{
"date": "2022-09-08T00:00:00+00:00",
"rate": 1.0,
"value": "2"
},
{
"date": "2022-09-09T00:00:00+00:00",
"rate": 1.0,
"value": "2"
},
{
"date": "2022-09-10T00:00:00+00:00",
"rate": 0.5,
"value": "1"
},
{
"date": "2022-09-11T00:00:00+00:00",
"rate": 0.5,
"value": "1"
},
{
"date": "2022-09-12T00:00:00+00:00",
"rate": 0.5,
"value": "1"
},
{
"date": "2022-09-13T00:00:00+00:00",
"rate": 0.5,
"value": "1"
},
{
"date": "2022-09-14T00:00:00+00:00",
"rate": 0.5,
"value": "1"
}
]
}
```
## 属性
### `period` {#period}
**描述:** 周期开始的时间戳，午夜。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
3.5.0 - 添加
### `frequency` {#frequency}
**描述:** 返回数据的时间段大小。\
**类型:** 字符串 (可枚举 oneOf)\
`day` = 每日\
`month` = 每月\
**版本历史:**\
3.5.0 - 添加
### `data` {#data}
**描述:** 在给定周期内注册的用户的留存数据。\
**类型:** Array of [CohortData](#CohortData)\
**版本历史:**\
3.5.0 - 添加
## CohortData entity attributes {#CohortData}
### `date` {#date}
**描述:** 时间段开始的时间戳，午夜。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
3.5.0 - 添加
### `rate` {#rate}
**描述:** 在指定 `period` 内注册并在给定 `date` 时间段内活跃的用户的百分比。\
**类型:** 数值\
**版本历史:**\
3.5.0 - 添加
### `value` {#value}
**描述:** 在指定的 `period` 内注册并在给定的 `date` 时间段内活跃的用户人数。\
**类型:** 整数\
**版本历史:**\
3.5.0 - 添加
## 另请参考
{{< page-relref ref="methods/admin/retention" caption="admin/retention API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/cohort_serializer.rb" caption="app/serializers/rest/admin/cohort_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Admin::Cohort" raw_link="/entities/Admin_Cohort/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

308
content/zh-cn/entities/Admin_Dimension.md Normal file
View file

@ -0,0 +1,308 @@
---
title: Admin::Dimension
description: 表示关于实例的定性数据。
menu:
docs:
parent: entities
aliases: [
"/entities/admin-dimension",
"/entities/Admin-Dimension",
"/entities/admin_dimension",
"/entities/Admin_Dimension",
"/api/entities/admin-dimension",
"/api/entities/Admin-Dimension",
"/api/entities/admin_dimension",
"/api/entities/Admin_Dimension",
]
---
## 属性
### `key` {#key}
**描述:** 请求维度的唯一键。\
**类型:** 字符串\
**版本历史:**\
3.5.0 - 添加
### `data` {#data}
**描述:** 请求维度可用的数据。\
**类型:** 哈希值的数组\
**版本历史:**\
3.5.0 - 添加
## Data attributes
### `key` {#data-key}
**描述:** 此数据项的唯一键。\
**类型:** 字符串\
**版本历史:**\
3.5.0 - 添加
### `human_key` {#data-human_key}
**描述:** 此数据项的可读键。\
**类型:** 字符串\
**版本历史:**\
3.5.0 - 添加
### `value` {#data-value}
**描述:** 此数据项的值。\
**类型:** 字符串\
**版本历史:**\
3.5.0 - 添加
### `unit` {{%optional%}} {#data-unit}
**描述:** 与此数据项的值相关的单位（如果适用）。\
**类型:** 字符串\
**版本历史:**\
3.5.0 - 添加
### `human_value` {{%optional%}} {#data-human_value}
**描述:** 此数据项的可读格式化值。\
**类型:** 字符串\
**版本历史:**\
3.5.0 - 添加
## 示例
### `languages` {#languages}
统计每种语言发布的本站嘟文的数量，然后展示关于每种语言受欢迎程度的维度数据。
```json
{
"key": "languages",
"data": [
{
"key": "en",
"human_key": "English",
"value": "10"
},
{
"key": "es",
"human_key": "Spanish",
"value": "1"
},
// ...
]
}
```
### `sources` {#sources}
统计由给定客户端发布的本站嘟文的数量，然后展示关于每个客户端受欢迎程度的维度数据。
```json
{
"key": "sources",
"data": [
{
"key": "web",
"human_key": "Website",
"value": "2"
},
// ...
]
}
```
### `servers` {#servers}
统计从给定域发布的嘟文数量，然后展示关于最受欢迎的外站实例的维度数据。
```json
{
"key": "servers",
"data": [
{
"key": "botsin.space",
"human_key": "botsin.space",
"value": "13738"
},
{
"key": "mastodon.social",
"human_key": "mastodon.social",
"value": "8928"
},
// ...
]
}
```
### `space_usage` {#space_usage}
展示关于实例堆栈中每个软件占用的空间的维度数据。
```json
{
"key": "space_usage",
"data": [
{
"key": "postgresql",
"human_key": "PostgreSQL",
"value": "14924935",
"unit": "bytes",
"human_value": "14.2 MB"
},
{
"key": "redis",
"human_key": "Redis",
"value": "1972544",
"unit": "bytes",
"human_value": "1.88 MB"
},
{
"key": "media",
"human_key": "Media storage",
"value": "0",
"unit": "bytes",
"human_value": "0 Bytes"
}
]
}
```
### `software_versions` {#software_versions}
展示关于实例堆栈中正在使用的软件版本的维度数据。
```json
{
"key": "software_versions",
"data": [
{
"key": "mastodon",
"human_key": "Mastodon",
"value": "3.5.3",
"human_value": "3.5.3"
},
{
"key": "ruby",
"human_key": "Ruby",
"value": "3.0.4p208",
"human_value": "3.0.4p208"
},
{
"key": "postgresql",
"human_key": "PostgreSQL",
"value": "10.22",
"human_value": "10.22"
},
{
"key": "redis",
"human_key": "Redis",
"value": "4.0.9",
"human_value": "4.0.9"
}
]
}
```
### `tag_servers` {#tag_servers}
统计包含给定 `id` 的热门话题标签的嘟文数量，然后展示关于使用该热门话题标签的最受欢迎的实例的维度数据。
```json
{
"key": "tag_servers",
"data": [
{
"key": "live.hatnix.net",
"human_key": "live.hatnix.net",
"value": "6"
},
{
"key": "linuxrocks.online",
"human_key": "linuxrocks.online",
"value": "4"
}
]
}
```
### `tag_languages` {#tag_languages}
统计包含给定 `id` 的热门话题标签的嘟文数量，然后展示关于这些嘟文的最受欢迎的语言的维度数据。
```json
{
"key": "tag_languages",
"data": [
{
"key": "und",
"human_key": "und",
"value": "8"
},
{
"key": "en",
"human_key": "English",
"value": "7"
},
// ...
]
}
```
### `instance_accounts` {#instance_accounts}
统计给定 `domain` 中每个账户的关注者数量，然后展示关于该外站实例中最受欢迎的账户的维度数据。
```json
{
"key": "instance_accounts",
"data": [
{
"key": "fribbledom",
"human_key": "fribbledom",
"value": "33"
},
{
"key": "ShugoWah",
"human_key": "ShugoWah",
"value": "26"
},
// ...
]
}
```
### `instance_languages` {#instance_languages}
统计给定 `domain` 中每种语言发布的嘟文数量，然后展示关于该外站实例上每种语言的受欢迎程度的维度数据。
```json
{
"key": "instance_languages",
"data": [
{
"key": "en",
"human_key": "English",
"value": "5848"
},
{
"key": "de",
"human_key": "German",
"value": "155"
},
// ...
]
}
```
## 另请参考
{{< page-relref ref="methods/admin/dimensions" caption="admin/dimensions API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/dimension_serializer.rb" caption="app/serializers/rest/admin/dimension_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/dimension.rb" caption="app/lib/admin/metrics/dimension.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/dimension/" caption="app/lib/admin/metrics/dimension/" >}}
{{< translation-status-zh-cn raw_title="Admin::Dimension" raw_link="/entities/Admin_Dimension/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

58
content/zh-cn/entities/Admin_DomainAllow.md Normal file
View file

@ -0,0 +1,58 @@
---
title: Admin::DomainAllow
description: 表示允许进行联合的域名。
menu:
docs:
parent: entities
aliases: [
"/entities/admin-domainallow",
"/entities/Admin-DomainAllow",
"/entities/admin_domainallow",
"/entities/Admin_DomainAllow",
"/api/entities/admin-domainallow",
"/api/entities/Admin-DomainAllow",
"/api/entities/admin_domainallow",
"/api/entities/Admin_DomainAllow",
]
---
## 示例
```json
{
"id": "1",
"domain": "mastodon.social",
"created_at": "2022-09-14T21:23:02.755Z"
}
```
## 属性
### `id` {#id}
**描述:** 数据库中 DomainAllow 的 ID。\
**类型:** 字符串（从整数转换而来，但不保证一定是数字）\
**版本历史:**\
4.0.0 - 添加
### `domain` {#domain}
**描述:** 允许进行联合的域名。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `created_at` {#created_at}
**描述:** 域名被允许进行联合的时间。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
4.0.0 - 添加
## 参见
{{< page-relref page="methods/admin/domain_allows" caption="admin/domain_allows API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/domain_allow_serializer.rb" caption="app/serializers/rest/admin/domain_allow_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Admin::DomainAllow" raw_link="/entities/Admin_DomainAllow/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

117
content/zh-cn/entities/Admin_DomainBlock.md Normal file
View file

@ -0,0 +1,117 @@
---
title: Admin::DomainBlock
description: 表示被限制联合的域名。
menu:
docs:
parent: entities
aliases: [
"/entities/admin-domainblock",
"/entities/Admin-DomainBlock",
"/entities/admin_domainblock",
"/entities/Admin_DomainBlock",
"/api/entities/admin-domainblock",
"/api/entities/Admin-DomainBlock",
"/api/entities/admin_domainblock",
"/api/entities/Admin_DomainBlock",
]
---
## 示例
```json
{
"id": "1",
"domain": "example.com",
"digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947",
"created_at": "2022-11-16T08:15:34.238Z",
"severity": "noop",
"reject_media": false,
"reject_reports": false,
"private_comment": null,
"public_comment": null,
"obfuscate": false
}
```
## 属性
### `id` {#id}
**描述:** 数据库中 DomainBlock 的 ID。\
**类型:** 字符串 (从整数转换而来，但不保证一定是数字)\
**版本历史:**\
4.0.0 - 添加
### `domain` {#domain}
**描述:** 不允许进行联合的域名。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `digest` {#digest}
**描述:** 不允许进行联合的域名的 sha256 十六进制摘要。\
**类型:** 字符串\
**版本历史:**\
4.3.0 - 添加
### `created_at` {#created_at}
**描述:** 该域名被阻止进行联合的时间。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
4.0.0 - 添加
### `severity` {#severity}
**描述:** 将应用于此域名屏蔽的策略。\
**类型:** 字符串 (可枚举的 oneOf)\
`silence` = 默认情况下，来自此域名的帐户发布的嘟文将被隐藏\
`suspend` = 来自此域名的所有传入数据将被拒绝\
`noop` = 不执行任何操作。允许拒绝媒体或举报\
**版本历史:**\
4.0.0 - 添加
### `reject_media` {#reject_media}
**描述:** 是否拒绝来自此域名的媒体附件\
**类型:** 布尔值\
**版本历史:**\
4.0.0 - 添加
### `reject_reports` {#reject_reports}
**描述:** 是否拒绝来自此域名的举报\
**类型:** 布尔值\
**版本历史:**\
4.0.0 - 添加
### `private_comment` {#private_comment}
**描述:** \
**类型:** {{<nullable>}} 字符串\
**版本历史:**\
4.0.0 - 添加
### `public_comment` {#public_comment}
**描述:** \
**类型:** {{<nullable>}} 字符串\
**版本历史:**\
4.0.0 - 添加
### `obfuscate` {#obfuscate}
**描述:** 是否在公开展示时混淆该被屏蔽的域名\
**类型:** 布尔值\
**版本历史:**\
4.0.0 - 添加
## 参见
{{< page-relref page="methods/admin/domain_blocks" caption="admin/domain_blocks API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/domain_block_serializer.rb" caption="app/serializers/rest/admin/domain_block_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Admin::DomainBlock" raw_link="/entities/Admin_DomainBlock/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

123
content/zh-cn/entities/Admin_EmailDomainBlock.md Normal file
View file

@ -0,0 +1,123 @@
---
title: Admin::EmailDomainBlock
description: 表示一个不能用于注册的电子邮件域名。
menu:
docs:
parent: entities
aliases: [
"/entities/admin-emaildomainblock",
"/entities/Admin-EmailDomainBlock",
"/entities/admin_emaildomainblock",
"/entities/Admin_EmailDomainBlock",
"/api/entities/admin-emaildomainblock",
"/api/entities/Admin-EmailDomainBlock",
"/api/entities/admin_emaildomainblock",
"/api/entities/Admin_EmailDomainBlock",
]
---
## 示例
```json
{
"id": "1",
"domain": "foo",
"created_at": "2022-11-16T06:09:36.176Z",
"history": [
{
"day": "1668556800",
"accounts": "0",
"uses": "0"
},
{
"day": "1668470400",
"accounts": "0",
"uses": "0"
},
{
"day": "1668384000",
"accounts": "0",
"uses": "0"
},
{
"day": "1668297600",
"accounts": "0",
"uses": "0"
},
{
"day": "1668211200",
"accounts": "0",
"uses": "0"
},
{
"day": "1668124800",
"accounts": "0",
"uses": "0"
},
{
"day": "1668038400",
"accounts": "0",
"uses": "0"
}
]
}
```
## 属性
### `id` {#id}
**描述:** 数据库中 EmailDomainBlock 的 ID。\
**类型:** 字符串 (从整数转换而来，但不保证一定是数字)\
**版本历史:**\
4.0.0 - 添加
### `domain` {#domain}
**描述:** 不允许用于注册的电子邮件域名。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `created_at` {#created_at}
**描述:** 该电子邮件域名何时被禁止用于注册。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
4.0.0 - 添加
### `history` {#history}
**描述:** 给定日期（通常是过去一周）的使用统计信息。\
**类型:** 哈希值的数组\
**版本历史:**\
4.0.0 - 添加
#### `history[][day]` {#history-day}
**描述:** 给定日期午夜的 UNIX 时间戳。\
**类型:** 字符串 (UNIX 时间戳)\
**版本历史:**\
4.0.0 - 添加
#### `history[][accounts]` {#history-accounts}
**描述:** 当天使用该电子邮件域名尝试注册的帐户数。\
**类型:** 字符串 (从整数转换而来)\
**版本历史:**\
4.0.0 - 添加
#### `history[][uses]` {#history-uses}
**描述:** 当天该电子邮件域名的 IP 注册尝试次数。\
**类型:** 字符串 (从整数转换而来)\
**版本历史:**\
4.0.0 - 添加
## 另请参考
{{< page-relref page="methods/admin/email_domain_blocks" caption="admin/email_domain_blocks API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/email_domain_block_serializer.rb" caption="app/serializers/rest/admin/email_domain_block_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Admin::EmailDomainBlock" raw_link="/entities/Admin_EmailDomainBlock/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

50
content/zh-cn/entities/Admin_Ip.md Normal file
View file

@ -0,0 +1,50 @@
---
title: Admin::Ip
description: 表示与用户关联的 IP 地址。
menu:
docs:
parent: entities
aliases: [
"/entities/admin-ip",
"/entities/Admin-Ip",
"/entities/admin_ip",
"/entities/Admin_Ip",
"/api/entities/admin-ip",
"/api/entities/Admin-Ip",
"/api/entities/admin_ip",
"/api/entities/Admin_Ip",
]
---
## 示例
```json
{
"ip": "192.168.42.1",
"used_at": "2022-09-15T01:38:58.851Z"
}
```
## 属性
### `ip` {#id}
**描述:** IP 地址。\
**类型:** 字符串 (IP 地址)\
**版本历史:**\
3.5.0 - 添加
### `used_at` {#used_at}
**描述:** 此 IP 地址最后一次被对应帐户使用时的时间戳。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
3.5.0 - 添加
## 参见
{{< page-relref ref="entities/Admin_Account#ips" caption="Admin::Account (`ips` attribute)" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/ip_serializer.rb" caption="app/serializers/rest/admin/ip_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Admin::Ip" raw_link="/entities/Admin_Ip/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

85
content/zh-cn/entities/Admin_IpBlock.md Normal file
View file

@ -0,0 +1,85 @@
---
title: Admin::IpBlock
description: 表示一个不能用于注册的 IP 地址段。
menu:
docs:
parent: entities
aliases: [
"/entities/admin-ipblock",
"/entities/Admin-IpBlock",
"/entities/admin_ipblock",
"/entities/Admin_IpBlock",
"/api/entities/admin-ipblock",
"/api/entities/Admin-IpBlock",
"/api/entities/admin_ipblock",
"/api/entities/Admin_IpBlock",
]
---
## 示例
```json
{
"id": "1",
"ip": "8.8.8.8/32",
"severity": "no_access",
"comment": "",
"created_at": "2022-11-16T07:22:00.501Z",
"expires_at": null
}
```
## 属性
### `id` {#id}
**描述:** 数据库中 DomainBlock 的 ID。\
**类型:** 字符串（从整数转换而来，但不保证是一个数字）\
**版本历史:**\
4.0.0 - 添加
### `ip` {#ip}
**描述:** 不允许进行联合的 IP 地址段。\
**类型:** 字符串（IP 地址和前缀）\
**版本历史:**\
4.0.0 - 添加
### `severity` {#severity}
**描述:** 与此 IP 段关联的策略。\
**类型:** 字符串（枚举，oneOf）\
`sign_up_requires_approval` = 来自此 IP 段的任何注册的账户都需要手动批准。\
`sign_up_block` = 将拒绝来自此 IP 段的任何注册。\
`no_access` = 将完全拒绝来自此 IP 段的任何活动。\
**版本历史:**\
4.0.0 - 添加
### `comment` {#comment}
**描述:** 此 IP 块的记录原因。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `created_at` {#created_at}
**描述:** IP 屏蔽的创建时间。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
4.0.0 - 添加
### `expires_at` {#expires_at}
**描述:** IP 屏蔽的过期时间。\
**类型:** {{<nullable>}} ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
4.0.0 - 添加
## 参见
{{< page-relref page="methods/admin/ip_blocks" caption="admin/ip_blocks API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/ip_block_serializer.rb" caption="app/serializers/rest/admin/ip_block_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Admin::IpBlock" raw_link="/entities/Admin_IpBlock/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

789
content/zh-cn/entities/Admin_Measure.md Normal file
View file

@ -0,0 +1,789 @@
---
title: Admin::Measure
description: 表示关于实例的定量数据。
menu:
docs:
parent: entities
aliases: [
"/entities/admin-measure",
"/entities/Admin-Measure",
"/entities/admin_measure",
"/entities/Admin_Measure",
"/api/entities/admin-measure",
"/api/entities/Admin-Measure",
"/api/entities/admin_measure",
"/api/entities/Admin_Measure",
]
---
## 属性
### `key` {#key}
**描述:** 请求的指标的唯一键。\
**类型:** 字符串\
**版本历史:**\
3.5.0 - 添加
### `unit` {#unit}
**描述:** 与此数据项的值关联的单位（如果适用）。\
**类型:** {{<nullable>}} 字符串 或 null\
**版本历史:**\
3.5.0 - 添加
### `total` {#total}
**描述:** 与请求的指标关联的数值总计。\
**类型:** 字符串 (从整数转换)\
**版本历史:**\
3.5.0 - 添加
### `human_value` {{%optional%}} {#data-human_value}
**描述:** 此数据项的人类可读格式化值。\
**类型:** 字符串\
**版本历史:**\
3.5.0 - 添加
### `previous_total` {{%optional%}} {#previous_total}
**描述:** 在前一个周期中，与请求的指标关联的数值总计。前一个周期通过从 start_at 和 end_at 得到长度，然后将 start 和 end 日期都向后偏移相同的时间段长度来计算。\
**类型:** 字符串 (从整数转换)\
**版本历史:**\
3.5.0 - 添加
### `data` {#data}
**描述:** 请求的指标的可用数据，按日分成数据桶。\
**类型:** 哈希值的数组\
**版本历史:**\
3.5.0 - 添加
#### `data[][date]` {#data-date}
**描述:** 请求时间段内当天的午夜。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
3.5.0 - 添加
#### `data[][value]` {#data-value}
**描述:** 请求的指标的数值。\
**类型:** 字符串 (从整数转换)\
**版本历史:**\
3.5.0 - 添加
## 示例
### `active_users`
时间段从 2022-09-14 开始到 2022-09-22 结束，你实例上的活跃用户总数
```json
{
"key": "active_users",
"unit": null,
"total": "2",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-15T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-16T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-17T00:00:00Z",
"value": "1"
},
{
"date": "2022-09-18T00:00:00Z",
"value": "1"
},
{
"date": "2022-09-19T00:00:00Z",
"value": "1"
},
{
"date": "2022-09-20T00:00:00Z",
"value": "2"
},
{
"date": "2022-09-21T00:00:00Z",
"value": "1"
}
]
}
```
### `new_users`
时间段从 2022-09-14 开始到 2022-09-22 结束，加入你实例的用户
```json
{
"key": "new_users",
"unit": null,
"total": "2",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "1"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "1"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `interactions`
时间段从 2022-09-14 开始到 2022-09-22 结束，本站嘟文上的互动总数（收藏、转发、回复）
```json
{
"key": "interactions",
"unit": null,
"total": "0",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-15T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-16T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-17T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-18T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-19T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-20T00:00:00Z",
"value": "0"
},
{
"date": "2022-09-21T00:00:00Z",
"value": "0"
}
]
}
```
### `opened_reports`
时间段从 2022-09-14 开始到 2022-09-22 结束，提交的举报总数
```json
{
"key": "opened_reports",
"unit": null,
"total": "0",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `resolved_reports`
时间段从 2022-09-14 开始到 2022-09-22 结束，已解决的举报总数
```json
{
"key": "resolved_reports",
"unit": null,
"total": "0",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `tag_accounts`
时间段从 2022-09-14 开始到 2022-09-22 结束，至少在一条嘟文中使用过话题标签的帐户总数
```json
{
"key": "tag_accounts",
"unit": null,
"total": "1",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "1"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `tag_uses`
时间段从 2022-09-14 开始到 2022-09-22 结束，使用过话题标签的嘟文总数
```json
{
"key": "tag_uses",
"unit": null,
"total": "2",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "1"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "1"
}
]
}
```
### `tag_servers`
时间段从 2022-09-14 开始到 2022-09-22 结束，使用过话题标签的嘟文的外站原始实例总数
```json
{
"key": "tag_servers",
"unit": null,
"total": "0",
"previous_total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `instance_accounts`
时间段从 2022-09-14 开始到 2022-09-22 结束，来自外站的帐户总数
```json
{
"key": "instance_accounts",
"unit": null,
"total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `instance_media_attachments`
时间段从 2022-09-14 开始到 2022-09-22 结束，来自外站的媒体附件使用的总空间
```json
{
"key": "instance_media_attachments",
"unit": "bytes",
"total": "0",
"human_value": "0 Bytes",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": ""
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": ""
}
]
}
```
### `instance_reports`
时间段从 2022-09-14 开始到 2022-09-22 结束，针对来自外站的帐户提交的举报总数
```json
{
"key": "instance_reports",
"unit": null,
"total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `instance_statuses`
时间段从 2022-09-14 开始到 2022-09-22 结束，来自外站的嘟文总数
```json
{
"key": "instance_statuses",
"unit": null,
"total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `instance_follows`
时间段从 2022-09-14 开始到 2022-09-22 结束，本站用户关注的来自外站的帐户总数
```json
{
"key": "instance_follows",
"unit": null,
"total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
### `instance_followers`
时间段从 2022-09-14 开始到 2022-09-22 结束，来自外站的帐户关注的本站帐户总数
```json
{
"key": "instance_followers",
"unit": null,
"total": "0",
"data": [
{
"date": "2022-09-14T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-15T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-16T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-17T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-18T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-19T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-20T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-21T00:00:00.000+00:00",
"value": "0"
},
{
"date": "2022-09-22T00:00:00.000+00:00",
"value": "0"
}
]
}
```
## 另请参考
{{< page-relref ref="methods/admin/dimensions" caption="admin/dimensions API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/measure_serializer.rb" caption="app/serializers/rest/admin/measure_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/measure.rb" caption="app/lib/admin/metrics/measure.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/measure/" caption="app/lib/admin/metrics/measure/" >}}
{{< translation-status-zh-cn raw_title="Admin::Measure" raw_link="/entities/Admin_Measure/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

175
content/zh-cn/entities/Admin_Report.md Normal file
View file

@ -0,0 +1,175 @@
---
title: Admin::Report
description: 关于已提交举报的管理级信息。
menu:
docs:
parent: entities
aliases: [
"/entities/admin-report",
"/entities/Admin-Report",
"/entities/admin_report",
"/entities/Admin_Report",
"/api/entities/admin-report",
"/api/entities/Admin-Report",
"/api/entities/admin_report",
"/api/entities/Admin_Report",
]
---
## 示例
```json
{
"id": "1",
"action_taken": false,
"action_taken_at": null,
"category": "spam",
"comment": "",
"forwarded": false,
"created_at": "2022-09-09T21:19:23.085Z",
"updated_at": "2022-09-09T21:19:23.085Z",
"account": {
"id": "108965218747268792",
"username": "admin",
"domain": null,
"created_at": "2022-09-08T22:48:07.985Z",
"email": "admin@mastodon.local",
// ...
"account": {
"id": "108965218747268792",
"username": "admin",
"acct": "admin",
// ...
}
},
"target_account": {
"id": "108965430868193066",
"username": "goody",
"domain": null,
"created_at": "2022-09-08T23:42:04.731Z",
"email": "goody@mastodon.local",
// ...
"account": {
"id": "108965430868193066",
"username": "goody",
"acct": "goody",
// ...
}
},
"assigned_account": null,
"action_taken_by_account": null,
"statuses": [],
"rules": []
}
```
## 属性
### `id` {#id}
**描述:** 数据库中举报的ID。\
**类型:** 字符串 (从整数转换而来，但不保证是一个数字)\
**版本历史:**\
2.9.1 - 添加
### `action_taken` {#action_taken}
**描述:** 是否针对此举报采取行动并解决此举报。\
**类型:** 布尔值\
**版本历史:**\
2.9.1 - 添加
### `action_taken_at` {#action_taken_at}
**描述:** 如果当前举报已解决，则为采取行动的时间。\
**类型:** {{<nullable>}} 字符串 ([Datetime](/api/datetime-format#datetime)) 或 null\
**版本历史:**\
2.9.1 - 添加
### `category` {#category}
**描述:** 举报被归类到的类别。\
**类型:** 字符串 (可枚举的 oneOf)\
`spam` = 恶意、虚假或重复的内容\
`violation` = 违反一条或多条特定的 [`规则`](#rules)\
`other` = 默认（兜底）类别\
**版本历史:**\
3.5.0 - 添加
### `comment` {#comment}
**描述:** 可选，举报理由。\
**类型:** 字符串\
**版本历史:**\
2.9.1 - 添加
### `forwarded` {#forwarded}
**描述:** 举报是否被转发到外站实例。\
**类型:** 布尔值\
**版本历史:**\
4.0.0 - 添加
### `created_at` {#created_at}
**描述:** 提交举报的时间。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
2.9.1 - 添加
### `updated_at` {#updated_at}
**描述:** 此举报上一次操作的时间。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
2.9.1 - 添加
### `account` {#account}
**描述:** 提交举报的帐户。\
**类型:** [Admin::Account]({{< relref "entities/Admin_Account" >}})\
**版本历史:**\
2.9.1 - 添加
### `target_account` {#target_account}
**描述:** 被举报的帐户。\
**类型:** [Admin::Account]({{< relref "entities/Admin_Account" >}})\
**版本历史:**\
2.9.1 - 添加
### `assigned_account` {#assigned_account}
**描述:** 分配给此举报的审核员的帐户。\
**类型:** {{<nullable>}} [Admin::Account]({{< relref "entities/Admin_Account" >}}) 或 null\
**版本历史:**\
2.9.1 - 添加
### `action_taken_by_account` {#action_taken_by_account}
**描述:** 处理举报的审核员的帐户。\
**类型:** {{<nullable>}} [Admin::Account]({{< relref "entities/Admin_Account" >}}) 或 null\
**版本历史:**\
2.9.1 - 添加
### `statuses` {#statuses}
**描述:** 附加到举报的嘟文，用于提供上下文信息。\
**类型:** [Status]({{< relref "entities/Status" >}}) 数组\
**版本历史:**\
2.9.1 - 添加
### `rules` {#rules}
**描述:** 附加到举报的规则，用于提供上下文信息。\
**类型:** [Rule]({{< relref "entities/Rule" >}}) 数组\
**版本历史:**\
3.5.0 - 添加
## 参见
{{< page-relref page="methods/admin/reports" caption="admin/reports API 方法">}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/report_serializer.rb" caption="app/serializers/rest/admin/report_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Admin::Report" raw_link="/entities/Admin_Report/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

214
content/zh-cn/entities/Announcement.md Normal file
View file

@ -0,0 +1,214 @@
---
title: Announcement
description: 表示管理员设置的公告。
menu:
docs:
parent: entities
aliases: [
"/entities/announcement",
"/entities/Announcement",
"/api/entities/announcement",
"/api/entities/Announcement",
]
---
## 示例
```json
{
"id": "8",
"content": "<p>Looks like there was an issue processing audio attachments without embedded art since yesterday due to an experimental new feature. That issue has now been fixed, so you may see older posts with audio from other servers pop up in your feeds now as they are being finally properly processed. Sorry!</p>",
"starts_at": null,
"ends_at": null,
"all_day": false,
"published_at": "2020-07-03T01:27:38.726Z",
"updated_at": "2020-07-03T01:27:38.752Z",
"read": true,
"mentions": [],
"statuses": [],
"tags": [],
"emojis": [],
"reactions": [
{
"name": "bongoCat",
"count": 9,
"me": false,
"url": "https://files.mastodon.social/custom_emojis/images/000/067/715/original/fdba57dff7576d53.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/067/715/static/fdba57dff7576d53.png"
},
{
"name": "thonking",
"count": 1,
"me": false,
"url": "https://files.mastodon.social/custom_emojis/images/000/098/690/original/a8d36edc4a7032e8.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/098/690/static/a8d36edc4a7032e8.png"
},
{
"name": "AAAAAA",
"count": 1,
"me": false,
"url": "https://files.mastodon.social/custom_emojis/images/000/071/387/original/AAAAAA.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/071/387/static/AAAAAA.png"
},
{
"name": "🤔",
"count": 1,
"me": true
}
]
}
```
## 属性
### `id` {#id}
**描述:** 数据库中公告的 ID。\
**类型:** 字符串（从整数转换而来，但不保证一定是数字）\
**版本历史:**\
3.1.0 - 添加
### `content` {#content}
**描述:** 公告的文本内容。\
**类型:** 字符串 (HTML)\
**版本历史:**\
3.1.0 - 添加
### `starts_at` {#starts_at}
**描述:** 公告开始的时间。\
**类型:** {{<nullable>}} 字符串 ([Datetime](/api/datetime-format#datetime)) 或 null\
**版本历史:**\
3.1.0 - 添加
### `ends_at` {#ends_at}
**描述:** 公告结束的时间。\
**类型:** {{<nullable>}} 字符串 ([Datetime](/api/datetime-format#datetime)) 或 null\
**版本历史:**\
3.1.0 - 添加
### `published` {#published}
**描述:** 公告当前是否处于发布状态。\
**类型:** 布尔值\
**版本历史:**\
3.1.0 - 添加
### `all_day` {#all_day}
**描述:** 公告是否应仅在日期上开始和结束，而不是在特定的时间点开始和结束。如果没有 `starts_at` 或 `ends_at` 时间，则为 false。\
**类型:** 布尔值\
**版本历史:**\
3.1.0 - 添加
### `published_at` {#created_at}
**描述:** 公告发布的时间。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
3.1.0 - 添加
### `updated_at` {#updated_at}
**描述:** 公告上次更新的时间。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
3.1.0 - 添加
### `read` {{%optional%}} {#read}
**描述:** 当前已读该公告的用户。\
**类型:** 布尔值\
**版本历史:**\
3.1.0 - 添加
### `mentions` {#mentions}
**描述:** 公告文本中提及的帐户。\
**类型:** Array of [Announcement::Account](#Account)\
**版本历史:**\
3.1.0 - 添加
### `statuses` {#statuses}
**描述:** 公告文本中链接的嘟文。\
**类型:** Array of [Announcement::Status](#Status)\
**版本历史:**\
3.1.0 - 添加
### `tags` {#tags}
**描述:** 公告文本中链接的话题标签。\
**类型:** Array of [Status::Tag]({{< relref "entities/Status#Tag" >}})\
**版本历史:**\
3.1.0 - 添加
### `emojis` {#emojis}
**描述:** 公告文本中使用的自定义表情。\
**类型:** Array of [CustomEmoji]({{< relref "entities/CustomEmoji" >}})\
**版本历史:**\
3.1.0 - 添加
### `reactions` {#reactions}
**描述:** 附加到公告的表情回应。\
**类型:** Array of [Reaction]({{< relref "entities/Reaction" >}})\
**版本历史:**\
3.1.0 - 添加
## Announcement::Account attributes {#Account}
### `id` {#Account-id}
**描述:** 被提及用户的帐户 ID。\
**类型:** 字符串（从整数转换而来，但不保证一定是数字）\
**版本历史:**\
3.1.0 - 添加
### `username` {#Account-username}
**描述:** 被提及用户的用户名。\
**类型:** 字符串\
**版本历史:**\
3.1.0 - 添加
### `url` {#Account-url}
**描述:** 被提及用户的账户位置。\
**类型:** 字符串 (URL)\
**版本历史:**\
3.1.0 - 添加
### `acct` {#Account-acct}
**描述:** 被提及用户的 webfinger acct: URI。对于本站用户，等同于 `username`；对于外站用户，等同于 `username@domain`。\
**类型:** 字符串\
**版本历史:**\
3.1.0 - 添加
## Announcement::Status attributes {#Status}
### `id` {#Status-id}
**描述:** 数据库中附加嘟文的 ID。\
**类型:** 字符串（从整数转换而来，但不保证一定是数字）\
**版本历史:**\
3.1.0 - 添加
### `url` {#Status-url}
**描述:** 附加嘟文的 URL。\
**类型:** 字符串 (URL)\
**版本历史:**\
3.1.0 - 添加
## 参见
{{< page-relref ref="methods/announcements" caption="公告 API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/announcement_serializer.rb" caption="app/serializers/rest/announcement_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Announcement" raw_link="/entities/Announcement/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

32
content/zh-cn/entities/Appeal.md Normal file
View file

@ -0,0 +1,32 @@
---
title: Appeal
description: 对管理操作的申诉。
menu:
docs:
parent: entities
aliases: [
"/entities/Appeal",
"/api/entities/Appeal",
]
---
## 属性
### `text` {#text}
**描述:** 受到管理的账号向管理员发起的申诉文本。\
**类型:** 字符串\
**版本历史:**\
4.3.0 - 添加
### `state` {#state}
**描述:** 申诉的状态。\
**类型:** 字符串 (枚举类型，取值之一)\
`approved` = 申诉已被管理者批准\
`rejected` = 申诉已被管理者驳回\
`pending` = 申诉已提交，但尚未批准或驳回\
**版本历史:**\
4.3.0 - 添加
{{< translation-status-zh-cn raw_title="Appeal" raw_link="/entities/Appeal/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

115
content/zh-cn/entities/Application.md Normal file
View file

@ -0,0 +1,115 @@
---
title: Application
description: 表示一个通过 REST API 访问帐户或发布嘟文的应用。
menu:
docs:
parent: entities
aliases: [
"/entities/application",
"/entities/Application",
"/api/entities/application",
"/api/entities/Application",
]
---
## 示例
```json
{
"name": "Test Application",
"website": "https://app.example",
"scopes": ["read", "write", "push"],
"redirect_uri": "https://app.example/callback\nhttps://app.example/register",
"redirect_uris": [
"https://app.example/callback",
"https://app.example/register"
]
}
```
## 属性
### `name` {#name}
**描述:** 你的应用的名称。\
**类型:** 字符串\
**版本历史:**\
0.9.9 - 添加
### `website` {{%optional%}} {#website}
**描述:** 与你的应用关联的网站。\
**类型:** {{<nullable>}} 字符串 (URL)\
**版本历史:**\
0.9.9 - 添加\
3.5.1 - this property is now nullable
### `scopes` {#scopes}
**描述:** 你的应用的作用域。按空格分隔的已注册的 `scopes` 字符串。\
**类型:** 字符串数组\
**版本历史:**\
4.3.0 - 添加
### `redirect_uris` {#redirect_uris}
**描述:** 你的应用的已注册重定向 URI。\
**类型:** 字符串数组 (数组中元素的值为 URL 或 `"urn:ietf:wg:oauth:2.0:oob"`)\
**版本历史:**\
4.3.0 - 添加
### `redirect_uri` {{%deprecated%}} {#redirect_uri}
**描述:** 你的应用的已注册重定向 URI。\
当注册了多个重定向 URI 时，可能包含 `\n` 字符。\
**类型:** 字符串\
**版本历史:**\
0.0.0 - 添加\
4.3.0 - 已弃用，推荐使用 [`redirect_uris`]({{< relref "entities/Application#redirect_uris" >}})，因为当注册了多个重定向 URI 时，此属性的值不是一个格式规范的 URI
### `vapid_key` {{%deprecated%}} {#vapid_key}
**描述:** 用于流式推送 API。与 [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) 一同返回。等同于 [WebPushSubscription#server_key]({{< relref "entities/WebPushSubscription#server_key" >}}) 和 [Instance#vapid_public_key]({{< relref "entities/Instance#vapid_public_key" >}})\
**类型:** 字符串\
**版本历史:**\
2.8.0 - 添加\
4.3.0 - 已弃用，等待移除，请参阅 [api/v2/instance]({{< relref "methods/Instance#v2">}}) 以获取此值 (`configuration.vapid.public_key`)
## CredentialApplication 属性 {#CredentialApplication}
所有 [Application](#attributes) 属性以及以下属性：
### `client_id` {#client_id}
**描述:** 客户端 ID 密钥，用于获取 OAuth 令牌\
**类型:** 字符串\
**版本历史:**\
0.9.9 - 添加
4.3.0 - moved to `CredentialApplication` from `Application`
### `client_secret` {#client_secret}
**描述:** 客户端密钥，用于获取 OAuth 令牌\
**类型:** 字符串\
**版本历史:**\
0.9.9 - 添加
4.3.0 - moved to `CredentialApplication` from `Application`
### `client_secret_expires_at` {#client_secret_expires_at}
**描述:** 客户端密钥到期时间，目前始终返回 `0`，表示 OAuth 客户端不会过期\
**类型:** 字符串\
**版本历史:**\
4.3.0 - 添加
## 参见
{{< page-relref ref="methods/apps" caption="应用 API 方法" >}}
{{< page-relref ref="entities/Status#application" caption="嘟文（`application` 属性）" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/application_serializer.rb" caption="app/serializers/rest/application_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/credential_application_serializer.rb" caption="app/serializers/rest/credential_application_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Application" raw_link="/entities/Application/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

72
content/zh-cn/entities/Context.md Normal file
View file

@ -0,0 +1,72 @@
---
title: Context
description: 表示给定嘟文周围的树状结构。用于重建嘟文的嘟文串。
menu:
docs:
parent: entities
aliases: [
"/entities/context",
"/entities/Context",
"/api/entities/context",
"/api/entities/Context",
]
---
## 示例
```json
{
"ancestors": [
{
"id": "103188938570975982",
"created_at": "2019-11-23T19:44:00.124Z",
"in_reply_to_id": null,
// ...
},
{
"id": "103188971072973252",
"created_at": "2019-11-23T19:52:23.398Z",
"in_reply_to_id": "103188938570975982",
// ...
},
{
"id": "103188982235527758",
"created_at": "2019-11-23T19:55:08.208Z",
"in_reply_to_id": "103188971072973252",
// ...
}
],
"descendants": [
{
"id": "103189026958574542",
"created_at": "2019-11-23T20:06:36.011Z",
"in_reply_to_id": "103189005915505698",
// ...
}
]
}
```
## 属性
### `ancestors` {#ancestors}
**描述:** 嘟文串中的上级嘟文。\
**类型:** [Status]({{< relref "entities/Status" >}})数组\
**版本历史:**\
0.6.0 - 添加
### `descendants` {#descendants}
**描述:** 嘟文串中的下级嘟文。\
**类型:** [Status]({{< relref "entities/Status" >}})数组\
**版本历史:**\
0.6.0 - 添加
## 另请参阅
{{< page-relref ref="methods/statuses#context" caption="GET /api/v1/statuses/:id/context" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/context_serializer.rb" caption="app/serializers/rest/context_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Context" raw_link="/entities/Context/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

75
content/zh-cn/entities/Conversation.md Normal file
View file

@ -0,0 +1,75 @@
---
title: Conversation
description: 表示具有“私下提及”可见性的会话。
menu:
docs:
parent: entities
aliases: [
"/entities/conversation",
"/entities/Conversation",
"/api/entities/conversation",
"/api/entities/Conversation",
]
---
## 示例
```json
{
"id": "418450",
"unread": true,
"accounts": [
{
"id": "482403",
"username": "amic",
"acct": "amic@nulled.red",
// ...
}
],
"last_status": {
"id": "103196583826321184",
"created_at": "2019-11-25T04:08:24.000Z",
"in_reply_to_id": "103196540587943467",
"in_reply_to_account_id": "14715",
// ...
}
}
```
## 属性
### `id` {#id}
**描述:** 数据库中会话的 ID。\
**类型:** 字符串（从整数转换而来，但不保证是一个数字）\
**版本历史:**\
2.6.0 - 添加
### `unread` {#unread}
**描述:** 会话当前是否标记为未读？\
**类型:** 布尔值\
**版本历史:**\
2.6.0 - 添加
### `accounts` {#accounts}
**描述:** 会话的参与者。\
**类型:** [Account]({{< relref "entities/Account" >}}) 数组\
**版本历史:**\
2.6.0 - 添加
### `last_status` {#last_status}
**描述:** 会话中的最后一条嘟文。\
**类型:** {{<nullable>}} [Status]({{< relref "entities/Status" >}})\
**版本历史:**\
2.6.0 - 添加
## 参见
{{< page-relref ref="methods/conversations" caption="会话 API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/conversation_serializer.rb" caption="app/serializers/rest/conversation_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Conversation" raw_link="/entities/Conversation/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

78
content/zh-cn/entities/CustomEmoji.md Normal file
View file

@ -0,0 +1,78 @@
---
title: CustomEmoji
description: 表示一个自定义表情。
menu:
docs:
parent: entities
aliases: [
"/entities/emoji",
"/entities/Emoji",
"/entities/customemoji",
"/entities/CustomEmoji",
"/api/entities/emoji",
"/api/entities/Emoji",
"/api/entities/customemoji",
"/api/entities/CustomEmoji",
]
---
## 示例
```json
{
"shortcode": "blobaww",
"url": "https://files.mastodon.social/custom_emojis/images/000/011/739/original/blobaww.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/011/739/static/blobaww.png",
"visible_in_picker": true,
"category": "Blobs"
}
```
## 属性
### `shortcode` {#shortcode}
**描述:** 自定义表情的名称。\
**类型:** 字符串\
**版本历史:**\
2.0.0 - 添加
### `url` {#url}
**描述:** 自定义表情的链接。\
**类型:** 字符串 (URL)\
**版本历史:**\
2.0.0 - 添加
### `static_url` {#static_url}
**描述:** 自定义表情的静态副本的链接。\
**类型:** 字符串 (URL)\
**版本历史:**\
2.0.0 - 添加
### `visible_in_picker` {#visible_in_picker}
**描述:** 此表情是否在选择器中可见或不公开列出。\
**类型:** 布尔值\
**版本历史:**\
2.0.0 - 添加
### `category` {#category}
**描述:** 用于在选择器中对自定义表情进行排序。\
**类型:** {{<nullable>}} 字符串\
**版本历史:**\
3.0.0 - 添加
## 参见
{{< page-relref ref="methods/custom_emojis" caption="GET /api/v1/custom_emojis" >}}
{{< page-relref ref="entities/Status#emojis" caption="Status (`emojis` attribute)" >}}
{{< page-relref ref="entities/Announcement#emojis" caption="Announcement (`emojis` attribute)" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/custom_emoji_serializer.rb" caption="app/serializers/rest/custom_emoji_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="CustomEmoji" raw_link="/entities/CustomEmoji/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

64
content/zh-cn/entities/DomainBlock.md Normal file
View file

@ -0,0 +1,64 @@
---
title: DomainBlock
description: 表示实例屏蔽的域名。
menu:
docs:
parent: entities
aliases: [
"/entities/domainblock",
"/entities/DomainBlock",
"/api/entities/domainblock",
"/api/entities/DomainBlock",
]
---
## 示例
```json
{
"domain":"daji******.com",
"digest":"3752f63a7079d60c2de5dceb8bd7608e86a15544eb78a494a482041c3684b37f",
"severity":"suspend",
"comment":"Inappropriate content"
}
```
## 属性
### `domain` {#domain}
**描述:** 被屏蔽的域名。 这可能会被混淆或由部分删节。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `digest` {#digest}
**描述:** 域字符串的 SHA256 哈希摘要。\
**类型:** 字符串 (SHA256)\
**版本历史:**\
4.0.0 - 添加
### `severity` {#severity}
**描述:** 域名屏蔽的级别。\
**类型:** 字符串 (Enumerable, oneOf)\
`silence` = 来自此域的用户将从时间线、话题标签和通知中隐藏（除非你关注了该用户）。\
`suspend` = 来自此域名的传入消息将被拒绝并完全丢弃。\
**版本历史:**\
4.0.0 - 添加
### `comment` {{%optional%}} {#comment}
**描述:** 域名屏蔽的可选原因。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
## 另请参阅
{{< page-relref ref="methods/instance#domain_blocks" caption="GET /api/v1/instance/domain_blocks" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/domain_block_serializer.rb" caption="app/serializers/rest/domain_block_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="DomainBlock" raw_link="/entities/DomainBlock/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

91
content/zh-cn/entities/EncryptedMessage.md Normal file
View file

@ -0,0 +1,91 @@
---
title: EncryptedMessage
description: 表示一条加密消息。
menu:
docs:
parent: entities
aliases: [
"/entities/encryptedmessage",
"/entities/EncryptedMessage",
"/entities/encryptedmessage",
"/entities/EncryptedMessage",
]
draft: true
---
{{< hint style="info" >}}
此实体当前未使用。
{{</hint>}}
## 示例
```json
```
## 属性
### `id` {#id}
**描述:** EncryptedMessage 在数据库中的 ID。\
**类型:** 字符串 (从整数转换而来，但不保证是数字)\
**版本历史:**\
3.2.0 - 添加
### `account_id` {#account_id}
**描述:** 发送此消息的 Account 的 ID。\
**类型:** 字符串 (从整数转换而来，但不保证是数字)\
**版本历史:**\
3.2.0 - 添加
### `device_id` {#device_id}
**描述:** 发送此消息的 Device 的 ID。\
**类型:** 字符串 (从整数转换而来，但不保证是数字)\
**版本历史:**\
3.2.0 - 添加
### `type` {#type}
**描述:** 消息是预共享密钥消息（用于建立新会话）还是正常加密消息（现有会话的一部分）。\
**类型:** 字符串 (枚举类型, oneOf)\
`0` = 预共享密钥消息（用于建立新会话）\
`1` = 正常加密消息（现有会话的一部分）\
**版本历史:**\
3.2.0 - 添加
### `body` {#body}
**描述:** 加密的消息内容。\
**类型:** 字符串\
**版本历史:**\
3.2.0 - 添加
### `digest` {#digest}
**描述:** 消息的 HMAC SHA-256 摘要哈希值。\
**类型:** 字符串 (SHA256)\
**版本历史:**\
3.2.0 - 添加
### `message_franking` {#message_franking}
**描述:** 一个签名值，用于举报消息正文的内容。\
**类型:** 字符串\
**版本历史:**\
3.2.0 - 添加
### `created_at` {#created_at}
**描述:** 消息创建的时间戳。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
3.2.0 - 添加
## 参见
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/encrypted_message_serializer.rb" caption="app/serializers/rest/encrypted_message_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/pull/13820" caption="添加端到端加密 API (#13820)" >}}
{{< translation-status-zh-cn raw_title="EncryptedMessage" raw_link="/entities/EncryptedMessage/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

122
content/zh-cn/entities/Error.md Normal file
View file

@ -0,0 +1,122 @@
---
title: Error
description: 表示一条错误消息。
menu:
docs:
parent: entities
aliases: [
"/entities/error",
"/entities/Error",
"/api/entities/error",
"/api/entities/Error",
]
---
## 示例
```json
{
"error": "invalid_grant",
"error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}
```
{{< hint style="info" >}}
**错误响应中最重要的是 HTTP 状态码。** 遵循标准语义。 错误的 body 是一个 JSON 对象，包含更多信息（如果可用）。
{{< /hint >}}
## 属性
### `error` {#error}
**描述:** 错误消息。\
**类型:** 字符串\
**版本历史:**\
0.6.0 - 添加
### `error_description` {{%optional%}} {#error_description}
**描述:** 错误的更长描述，主要与 OAuth API 一起提供。\
**类型:** 字符串\
**版本历史:**\
0.6.0 - 添加
## 可能的原因 {#reasons}
### 400 - 非法请求
#### ParameterMissing {#parameter-missing}
错误: {string}。 当 API 调用中缺少必需的参数时出现。
### 401 - 未授权 {#401}
#### require_authenticated_user! {#auth}
错误: 此 API 要求用户进行身份验证。 当实例处于安全模式时出现，该模式禁用 API 方法的所有公共使用。
### 403 - 禁止访问 {#403}
#### NotPermitted {#not-permitted}
错误: 不允许此操作。 尝试调用你没有权限的方法（例如管理或工作人员方法），或执行不允许你执行的操作（例如关注阻止你的用户）时出现。
#### current_user.disabled? {#disabled}
错误: 你的账户当前已被禁用。 当 OAuth 令牌的授权用户已由管理员禁用其帐户时出现。
#### !current_user.confirmed? {#unconfirmed}
错误: 你的账户缺少已确认的电子邮件地址。 当与 OAuth 令牌的授权用户的帐户关联的电子邮件地址尚未确认时出现。
#### !current_user.approved? {#unapproved}
错误: 你的账户当前正在等待批准。 当 OAuth 令牌的授权用户在需要批准注册的实例上注册，并且用户尚未由管理员批准其帐户时出现。
### 404 - 未找到 {#404}
#### RecordNotFound {#not-found}
错误: 未找到记录。 当实体记录不存在，或者授权用户不在私有实体的访问范围内时出现。
### 422 - 无法处理的实体 {#422}
#### RecordInvalid {#invalid}
错误: {string}。 当实体创建失败时可能会出现。
#### RecordNotUnique {#not-unique}
错误: 重复记录。 当你尝试置顶一个已置顶的帐户或嘟文时出现。
#### !current_user {#user-required}
错误: 此方法需要经过身份验证的用户。 尝试调用需要处理用户的 API 方法时，在使用没有授权用户的 OAuth 令牌（或根本没有令牌）时出现。
### 429 - 请求过于频繁 {#429}
错误: {translated string}。 当你超过速率限制时出现。 有关更多信息，请参见 [速率限制]({{< relref "api/rate-limits" >}})。
### 503 - 服务不可用 {#503}
#### UnexpectedResponseError {#unexpected-response}
错误: 无法获取外站数据。 当 Mastodon 调用返回错误的外站服务（例如来自另一个实例的 WebFinger）时出现。
#### SSLError {#ssl}
错误: 无法验证外站 SSL 证书。 调用外站服务时，但它具有无效的 SSL 证书时出现。
#### NetworkingError {#networking-error}
错误: 为你的请求提供服务时出现临时问题，请重试。 当对 S3 存储实例的调用失败时出现。
#### RaceConditionError {#race-condition}
错误: 为你的请求提供服务时出现临时问题，请重试。 由于实例端代码中存在争用情况导致错误时出现。
## 另请查看
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/base_controller.rb" caption="app/controllers/api/base_controller.rb" >}}
{{< translation-status-zh-cn raw_title="Error" raw_link="/entities/Error/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

46
content/zh-cn/entities/ExtendedDescription.md Normal file
View file

@ -0,0 +1,46 @@
---
title: ExtendedDescription
description: 表示实例的详细描述，将显示在其“关于”页面上。
menu:
docs:
parent: entities
aliases: [
"/entities/extendeddescription",
"/entities/ExtendedDescription",
"/api/entities/extendeddescription",
"/api/entities/ExtendedDescription",
]
---
## 示例
```json
{
"updated_at":"2022-11-03T04:09:07Z",
"content":"<p>For inquiries not related specifically to the operation of this server, such as press inquiries, please contact <a href=\"mailto:press@joinmastodon.org\">press@joinmastodon.org</a>.</p>\n\n<h2>Funding</h2>\n\n<p>This server is crowdfunded by <a href=\"https://patreon.com/mastodon\">Patreon donations</a>. For a list of sponsors, see <a href=\"https://joinmastodon.org/sponsors\">joinmastodon.org</a>.</p>\n\n<h2>Reporting and moderation</h2>\n\n<p>When reporting accounts, please make sure to include at least a few posts that show rule-breaking behaviour, when applicable. If there is any additional context that might help make a decision, please also include it in the comment. This is especially important when the content is in a language nobody on the moderation team speaks.</p>\n\n<p>We usually handle reports within 24 hours. Please mind that you are not notified when a report you have made has led to a punitive action, and that not all punitive actions are externally visible. For first time offenses, we may opt to delete offending content, escalating to harsher measures on repeat offenses.</p>\n\n<h2>Impressum</h2>\n\n<p>Mastodon gGmbH<br>\nMühlenstraße 8a<br>\n14167 Berlin<br>\nGermany</p>\n\n<p>E-Mail-Adresse: hello@joinmastodon.org</p>\n\n<p>Vertretungsberechtigt: Eugen Rochko (Geschäftsführer)</p>\n\n<p>Umsatzsteuer Identifikationsnummer (USt-ID): DE344258260</p>\n\n<p>Handelsregister<br>\nGeführt bei: Amtsgericht Charlottenburg<br>\nNummer: HRB 230086 B</p>\n"
}
```
## 属性
### `updated_at` {#updated_at}
**描述:** 扩展描述上次更新的时间戳。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
4. 0.0 - 添加
### `content` {#content}
**描述:** 扩展描述 HTML 渲染后的内容。\
**类型:** 字符串 (HTML)\
**版本历史:**\
4. 0.0 - 添加
## 参见
{{< page-relref ref="methods/instance#extended_description" caption="GET /api/v1/instance/extended_description" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/extended_description_serializer.rb" caption="app/serializers/rest/extended_description_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="ExtendedDescription" raw_link="/entities/ExtendedDescription/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

66
content/zh-cn/entities/FamiliarFollowers.md Normal file
View file

@ -0,0 +1,66 @@
---
title: FamiliarFollowers
description: 表示你的关注者中，同时也关注了其他用户的子集。
menu:
docs:
parent: entities
aliases: [
"/entities/familiarfollowers",
"/entities/FamiliarFollowers",
"/api/entities/familiarfollowers",
"/api/entities/FamiliarFollowers",
]
---
## 示例
```json
[
{
"id":"1",
"accounts":[
{
"id":"1087990",
"username":"moss",
"acct":"moss@goblin.camp",
// ...
},
{
"id":"1092723",
"username":"vivianrose",
"acct":"vivianrose",
// ...
},
// ...
]
},
{
"id":"2",
"accounts":[]
}
]
```
## 属性
### `id` {#id}
**描述:** 数据库中账户的ID。\
**类型:** 字符串（从整数转换而来，但不保证一定是数字）\
**版本历史:**\
3.5.0 - 添加
### `accounts` {#accounts}
**描述:** 你关注的，并且也关注了这个账户的其他账户。\
**类型:** [Account]({{< relref "entities/Account" >}}) 数组\
**版本历史:**\
3.5.0 - 添加
## 另请参阅
{{< page-relref ref="methods/accounts#familiar_followers" caption="GET /api/v1/accounts/:id/familiar_followers" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/familiar_followers_serializer.rb" caption="app/serializers/rest/familiar_followers_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="FamiliarFollowers" raw_link="/entities/FamiliarFollowers/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

70
content/zh-cn/entities/FeaturedTag.md Normal file
View file

@ -0,0 +1,70 @@
---
title: FeaturedTag
description: 表示账户上显示的精选话题标签。
menu:
docs:
parent: entities
aliases: [
"/entities/featuredtag",
"/entities/FeaturedTag",
"/api/entities/featuredtag",
"/api/entities/FeaturedTag",
]
---
## 示例
```json
{
"id": "627",
"name": "nowplaying",
"url": "https://mastodon.social/@trwnh/tagged/nowplaying",
"statuses_count": "70",
"last_status_at": "2022-08-29"
}
```
## 属性
### `id` {#id}
**描述:** 精选话题标签在数据库中的内部 ID。\
**类型:** 字符串（从整数转换而来，但不保证一定是数字）\
**版本历史:**\
3.0.0 - 添加
### `name` {#name}
**描述:** 精选话题标签的名称。\
**类型:** 字符串\
**版本历史:**\
3.0.0 - 添加
### `url` {#url}
**描述:** 指向用户包含此话题标签的所有嘟文的链接。\
**类型:** 字符串 (URL)\
**版本历史:**\
3.3.0 - 添加
### `statuses_count` {#statuses_count}
**描述:** 包含此话题标签的已发布嘟文的数量。\
**类型:** 字符串\
**版本历史:**\
3.0.0 - 添加
### `last_status_at` {#last_status_at}
**描述:** 包含此话题标签的最新发布嘟文的日期。\
**类型:** 字符串 ([Date](/api/datetime-format#date))\
**版本历史:**\
3.0.0 - 添加
## 另请参阅
{{< page-relref ref="methods/featured_tags" caption="featured_tags API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/featured_tag_serializer.rb" caption="app/serializers/rest/featured_tag_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="FeaturedTag" raw_link="/entities/FeaturedTag/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

112
content/zh-cn/entities/Filter.md Normal file
View file

@ -0,0 +1,112 @@
---
title: Filter
description: 表示用户定义的过滤规则，用于确定哪些嘟文不应向用户显示。
menu:
docs:
parent: entities
aliases: [
"/entities/filter",
"/entities/Filter",
"/api/entities/filter",
"/api/entities/Filter",
]
---
## 示例
```json
{
"id": "19972",
"title": "Test filter",
"context": [
"home"
],
"expires_at": "2022-09-20T17:27:39.296Z",
"filter_action": "warn",
"keywords": [
{
"id": "1197",
"keyword": "bad word",
"whole_word": false
}
],
"statuses": [
{
"id": "1",
"status_id": "109031743575371913"
}
]
}
```
## 属性
### `id` {#id}
**描述:** 数据库中过滤规则的 ID。\
**类型:** 字符串 (从整数强制转换，但不保证一定是数字)\
**版本历史:**\
4.0.0 - 添加
### `title` {#title}
**描述:** 用户为过滤规则指定的标题。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `context` {#context}
**描述:** 过滤规则的应用到场景。\
**类型:** 字符串数组 (可枚举，anyOf)\
`home` = 首页时间线和列表\
`notifications` = 通知时间线\
`public` = 公共时间线\
`thread` = 展开的嘟文串\
`account` = 查看账户时\
**版本历史:**\
4.0.0 - 添加
### `expires_at` {#expires_at}
**描述:** 过滤规则何时不再生效。\
**类型:** {{<nullable>}} 字符串 ([Datetime](/api/datetime-format#datetime))，如果过滤规则永不过期，则为 null\
**版本历史:**\
4.0.0 - 添加
### `filter_action` {#filter_action}
**描述:** 当嘟文与此过滤规则匹配时要采取的操作。\
**类型:** 字符串 (可枚举，oneOf)\
`warn` = 显示警告，警告内容为命中的过滤规则的标题，并允许用户展开被过滤的嘟文。这是默认值（并且未知值应被视为等同于“warn”）。\
`hide` = 如果匹配到对应的嘟文，则不显示\
`blur` = 隐藏/模糊媒体附件，并显示警告，警告内容为命中的过滤规则的标题
**版本历史:**\
4.0.0 - 添加\
4.4.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 5) - 将 `blur` 值添加到 `filter_action` 属性
### `keywords` {#keywords}
**描述:** 此过滤规则下的关键词。\
**类型:** [FilterKeyword]({{< relref "entities/FilterKeyword" >}}) 数组\
**版本历史:**\
4.0.0 - 添加
### `statuses` {#statuses}
**描述:** 此过滤规则下的嘟文。\
**类型:** [FilterStatus]({{< relref "entities/FilterStatus" >}}) 数组\
**版本历史:**\
4.0.0 - 添加
## 参见
{{< page-relref ref="api/guidelines#filters" caption="过滤的实现指引" >}}
{{< page-relref ref="entities/V1_Filter" caption="V1::Filter（适用于 Mastodon 3.5 及更早版本）" >}}
{{< page-relref ref="methods/filters" caption="/api/v2/filters 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_serializer.rb" caption="app/serializers/rest/filter_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Filter" raw_link="/entities/Filter/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

56
content/zh-cn/entities/FilterKeyword.md Normal file
View file

@ -0,0 +1,56 @@
---
title: FilterKeyword
description: 表示一个关键词，如果匹配，则应采取过滤规则操作。
menu:
docs:
parent: entities
aliases: [
"/entities/filterkeyword",
"/entities/FilterKeyword",
"/api/entities/filterkeyword",
"/api/entities/FilterKeyword",
]
---
## 示例
```json
{
"id": "1197",
"keyword": "bad word",
"whole_word": false
}
```
## 属性
### `id` {#id}
**描述:** 数据库中 FilterKeyword 的 ID。\
**类型:** 字符串 (从整数转换而来，但不保证一定为数字)\
**版本历史:**\
4.0.0 - 添加
### `keyword` {#keyword}
**描述:** 要匹配的短语。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `whole_word` {#whole_word}
**描述:** 过滤规则是否应考虑单词边界？ 请参阅[过滤规则实现指引]({{< relref "api/guidelines#filters" >}})。\
**类型:** 布尔值\
**版本历史:**\
4.0.0 - 添加
## 参见
{{< page-relref ref="api/guidelines#filters" caption="过滤规则实现指引" >}}
{{< page-relref ref="methods/filters" caption="/api/v2/filters 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_keyword_serializer.rb" caption="app/serializers/rest/filter_keyword_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="FilterKeyword" raw_link="/entities/FilterKeyword/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

68
content/zh-cn/entities/FilterResult.md Normal file
View file

@ -0,0 +1,68 @@
---
title: FilterResult
description: 表示关键词与给定嘟文匹配的过滤规则。
menu:
docs:
parent: entities
aliases: [
"/entities/filterresult",
"/entities/FilterResult",
"/api/entities/filterresult",
"/api/entities/FilterResult",
]
---
## 示例
```json
{
"filter": {
"id": "3",
"title": "Hide completely",
"context": [
"home"
],
"expires_at": "2022-09-20T17:27:39.296Z",
"filter_action": "hide"
},
"keyword_matches": [
"bad word"
],
"status_matches": [
"109031743575371913"
]
}
```
## 属性
### `filter` {#filter}
**描述:** 命中的过滤规则。\
**类型:** [Filter]({{< relref "entities/Filter" >}})\
**版本历史:**\
4.0.0 - 添加
### `keyword_matches` {#keyword_matches}
**描述:** 过滤规则中命中的关键词。\
**类型:** {{<nullable>}} 字符串数组，或 null\
**版本历史:**\
4.0.0 - 添加
### `status_matches` {#status_matches}
**描述:** 过滤规则中命中的嘟文 ID。\
**类型:** {{<nullable>}} 字符串数组，或 null\
**版本历史:**\
4.0.0 - 添加
## 参见
{{< page-relref ref="api/guidelines#filters" caption="过滤规则实现指引" >}}
{{< page-relref ref="methods/filters" caption="/api/v2/filters 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_result_serializer.rb" caption="app/serializers/rest/filter_result_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="FilterResult" raw_link="/entities/FilterResult/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

48
content/zh-cn/entities/FilterStatus.md Normal file
View file

@ -0,0 +1,48 @@
---
title: FilterStatus
description: 表示一条嘟文 ID，如果匹配，则应采取过滤规则操作。
menu:
docs:
parent: entities
aliases: [
"/entities/filterstatus",
"/entities/FilterStatus",
"/api/entities/filterstatus",
"/api/entities/FilterStatus",
]
---
## 示例
```json
{
"id": "1",
"status_id": "109031743575371913"
}
```
## 属性
### `id` {#id}
**描述:** 数据库中 FilterStatus 的 ID。\
**类型:** 字符串（从整数转换而来，但不保证是一个数字）\
**版本历史:**\
4.0.0 - 添加
### `status_id` {#keyword}
**描述:** 将被过滤的嘟文的 ID。\
**类型:** 字符串（从整数转换而来，但不保证是一个数字）\
**版本历史:**\
4.0.0 - 添加
## 参见
{{< page-relref ref="api/guidelines#filters" caption="过滤规则实现指引" >}}
{{< page-relref ref="methods/filters" caption="/api/v2/filters 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_status_serializer.rb" caption="app/serializers/rest/filter_status_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="FilterStatus" raw_link="/entities/FilterStatus/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

72
content/zh-cn/entities/IdentityProof.md Normal file
View file

@ -0,0 +1,72 @@
---
title: IdentityProof
description: 表示来自外部身份提供者的证明。
menu:
docs:
parent: entities
aliases: [
"/entities/identityproof",
"/entities/IdentityProof",
"/api/entities/identityproof",
"/api/entities/IdentityProof",
]
---
{{< hint style="danger" >}}
身份证明已在 3.5.0 及更高版本中弃用。 在此之前，唯一受支持的证明提供商是 Keybase，但自从被 Zoom 收购以来，Keybase 的开发已完全停滞。
{{< /hint >}}
```json
{
"provider": "Keybase",
"provider_username": "gargron",
"updated_at": "2019-07-21T20:14:39.596Z",
"proof_url": "https://keybase.io/gargron/sigchain#5cfc20c7018f2beefb42a68836da59a792e55daa4d118498c9b1898de7e845690f",
"profile_url": "https://keybase.io/gargron"
}
```
## 属性
### `provider` {#provider}
**描述:** 身份提供者的名称。\
**类型:** 字符串\
**版本历史:**\
2.8.0 - 添加
### `provider_username` {#provider_username}
**描述:** 帐户所有者在身份提供者服务上的用户名。\
**类型:** 字符串\
**版本历史:**\
2.8.0 - 添加
### `updated_at` {#updated_at}
**描述:** 身份证明最近一次更新的时间。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
2.8.0 - 添加
### `proof_url` {#proof_url}
**描述:** 指向身份证明声明的链接，由身份提供商托管。\
**类型:** 字符串 (URL)\
**版本历史:**\
2.8.0 - 添加
### `profile_url` {#profile_url}
**描述:** 帐户所有者在身份提供者上的账户 URL。\
**类型:** 字符串 (URL)\
**版本历史:**\
2.8.0 - 添加
## 另请参考
{{< page-relref ref="methods/accounts#identity_proofs" caption="GET /api/v1/accounts/:id/identity_proofs" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/pull/17045" caption="Remove Keybase integration (#17045)" >}}
{{< translation-status-zh-cn raw_title="IdentityProof" raw_link="/entities/IdentityProof/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

594
content/zh-cn/entities/Instance.md Normal file
View file

@ -0,0 +1,594 @@
---
title: Instance
description: 表示在此域名上运行的 Mastodon 实例。
menu:
docs:
parent: entities
aliases: [
"/entities/instance",
"/entities/Instance",
"/api/entities/instance",
"/api/entities/Instance",
]
---
## 示例
```json
{
"domain": "mastodon.social",
"title": "Mastodon",
"version": "4.0.0rc1",
"source_url": "https://github.com/mastodon/mastodon",
"description": "The original server operated by the Mastodon gGmbH non-profit",
"usage": {
"users": {
"active_month": 123122
}
},
"thumbnail": {
"url": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png",
"blurhash": "UeKUpFxuo~R%0nW;WCnhF6RjaJt757oJodS$",
"versions": {
"@1x": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png",
"@2x": "https://files.mastodon.social/site_uploads/files/000/000/001/@2x/57c12f441d083cde.png"
}
},
"icon": [
{
"src": "https://files.mastodon.social/site_uploads/files/000/000/003/36/accf17b0104f18e5.png",
"size": "36x36"
},
{
"src": "https://files.mastodon.social/site_uploads/files/000/000/003/72/accf17b0104f18e5.png",
"size": "72x72"
},
{
"src": "https://files.mastodon.social/site_uploads/files/000/000/003/192/accf17b0104f18e5.png",
"size": "192x192"
},
{
"src": "https://files.mastodon.social/site_uploads/files/000/000/003/512/accf17b0104f18e5.png",
"size": "512x512"
}
],
"languages": [
"en"
],
"configuration": {
"urls": {
"streaming": "wss://mastodon.social"
},
"vapid": {
"public_key": "BCkMmVdKDnKYwzVCDC99Iuc9GvId-x7-kKtuHnLgfF98ENiZp_aj-UNthbCdI70DqN1zUVis-x0Wrot2sBagkMc="
},
"accounts": {
"max_featured_tags": 10,
"max_pinned_statuses": 4
},
"statuses": {
"max_characters": 500,
"max_media_attachments": 4,
"characters_reserved_per_url": 23
},
"media_attachments": {
"supported_mime_types": [
"image/jpeg",
"image/png",
"image/gif",
"image/heic",
"image/heif",
"image/webp",
"video/webm",
"video/mp4",
"video/quicktime",
"video/ogg",
"audio/wave",
"audio/wav",
"audio/x-wav",
"audio/x-pn-wave",
"audio/vnd.wave",
"audio/ogg",
"audio/vorbis",
"audio/mpeg",
"audio/mp3",
"audio/webm",
"audio/flac",
"audio/aac",
"audio/m4a",
"audio/x-m4a",
"audio/mp4",
"audio/3gpp",
"video/x-ms-asf"
],
"description_limit": 1500,
"image_size_limit": 10485760,
"image_matrix_limit": 16777216,
"video_size_limit": 41943040,
"video_frame_rate_limit": 60,
"video_matrix_limit": 2304000
},
"polls": {
"max_options": 4,
"max_characters_per_option": 50,
"min_expiration": 300,
"max_expiration": 2629746
},
"translation": {
"enabled": true
}
},
"registrations": {
"enabled": false,
"approval_required": false,
"reason_required": false,
"message": null,
"min_age": 16
},
"api_versions": {
"mastodon": 1,
},
"contact": {
"email": "staff@mastodon.social",
"account": {
"id": "1",
"username": "Gargron",
"acct": "Gargron",
"display_name": "Eugen 💀",
"locked": false,
"bot": false,
"discoverable": true,
"group": false,
"created_at": "2016-03-16T00:00:00.000Z",
"note": "<p>Founder, CEO and lead developer <span class=\"h-card\"><a href=\"https://mastodon.social/@Mastodon\" class=\"u-url mention\">@<span>Mastodon</span></a></span>, Germany.</p>",
"url": "https://mastodon.social/@Gargron",
"avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg",
"avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg",
"header": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg",
"header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg",
"followers_count": 133026,
"following_count": 311,
"statuses_count": 72605,
"last_status_at": "2022-10-31",
"noindex": false,
"emojis": [],
"fields": [
{
"name": "Patreon",
"value": "<a href=\"https://www.patreon.com/mastodon\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span></a>",
"verified_at": null
}
]
}
},
"rules": [
{
"id": "1",
"text": "Sexually explicit or violent media must be marked as sensitive when posting"
},
{
"id": "2",
"text": "No racism, sexism, homophobia, transphobia, xenophobia, or casteism"
},
{
"id": "3",
"text": "No incitement of violence or promotion of violent ideologies"
},
{
"id": "4",
"text": "No harassment, dogpiling or doxxing of other users"
},
{
"id": "5",
"text": "No content illegal in Germany"
},
{
"id": "7",
"text": "Do not share intentionally false or misleading information"
}
]
}
```
## 属性
### `domain` {#domain}
**描述:** 实例的域名。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `title` {#title}
**描述:** 站点的标题。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `version` {#version}
**描述:** 实例上安装的 Mastodon 版本。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `source_url` {#source_url}
**描述:** 根据 AGPL 许可要求，运行在此实例上的软件的源代码的 URL。\
**类型:** 字符串 (URL)\
**版本历史:**\
4.0.0 - 添加
### `description` {#description}
**描述:** 管理员定义的简短纯文本描述。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `usage` {#usage}
**描述:** 此实例的使用数据。\
**类型:** Hash\
**版本历史:**\
4.0.0 - 添加
#### `usage[users]` {#users}
**描述:** 与此实例上的用户相关的使用数据。\
**类型:** Hash\
**版本历史:**\
4.0.0 - 添加
##### `usage[users][active_month]` {#active_month}
**描述:** 过去 4 周内的活跃用户数。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
### `thumbnail` {#thumbnail}
**描述:** 用于表示此实例的图像。\
**类型:** Hash\
**版本历史:**\
4.0.0 - 添加
#### `thumbnail[url]` {#thumbnail-url}
**描述:** 缩略图图像的 URL。\
**类型:** 字符串 (URL)\
**版本历史:**\
4.0.0 - 添加
#### `thumbnail[blurhash]` {{<optional>}} {#blurhash}
**描述:** 一种由 [BlurHash 算法](https://github.com/woltapp/blurhash) 计算出的哈希值，用于在媒体尚未下载时生成彩色预览缩略图。\
**类型:** 字符串 (Blurhash)\
**版本历史:**\
4.0.0 - 添加
#### `thumbnail[versions]` {{<optional>}} {#thumbnail-versions}
**描述:** 指向缩放分辨率图像的链接，适用于高 DPI 屏幕。\
**类型:** Hash\
**版本历史:**\
4.0.0 - 添加
##### `thumbnail[versions][@1x]` {{<optional>}} {#1x}
**描述:** 1x 分辨率的缩略图图像的 URL。\
**类型:** 字符串 (URL)\
**版本历史:**\
4.0.0 - 添加
##### `thumbnail[versions][@2x]` {{<optional>}} {#2x}
**描述:** 2x 分辨率的缩略图图像的 URL。\
**类型:** 字符串 (URL)\
**版本历史:**\
4.0.0 - 添加
### `icon` {#icon}
**描述:** 为此实例配置的图标的可用尺寸变体的列表。\
**类型:** [InstanceIcon](#InstanceIcon) 数组\
**版本历史:**\
4.3.0 - 添加
### `languages` {#languages}
**描述:** 网站及其工作人员的主要语言。\
**类型:** 字符串 (ISO 639-1 双字符代码) 数组\
**版本历史:**\
4.0.0 - 添加
### `configuration` {#configuration}
**描述:** 此网站的配置值和限制。\
**类型:** Hash\
**版本历史:**\
4.0.0 - 添加
#### `configuration[urls]` {#urls}
**描述:** 客户端应用感兴趣的 URL。\
**类型:** Hash\
**版本历史:**\
4.0.0 - 添加
##### `configuration[urls][streaming]` {#streaming}
**描述:** 用于连接到流式 API 的 Websockets URL。\
**类型:** 字符串 (URL)\
**版本历史:**\
4.0.0 - 添加
### `configuration[vapid][public_key]` {#vapid_public_key}
**描述:** 实例的 VAPID 公钥，用于推送通知，与 [WebPushSubscription#server_key]({{< relref "entities/WebPushSubscription#server_key" >}}) 相同。\
**类型:** 字符串\
**版本历史:**\
4.3.0 - 添加
#### `configuration[accounts]` {#accounts}
**描述:** 与帐户相关的限制。\
**类型:** Hash\
**版本历史:**\
4.0.0 - 添加
##### `configuration[accounts][max_featured_tags]` {#max_featured_tags}
**描述:** 每个帐户允许的最大精选话题标签数。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
##### `configuration[accounts][max_pinned_statuses]` {#max_pinned_statuses}
**描述:** 每个帐户允许的最大置顶嘟文数。\
**类型:** 整数\
**版本历史:**\
4.3.0 - 添加
#### `configuration[statuses]` {#statuses}
**描述:** 与撰写嘟文相关的限制。\
**类型:** Hash\
**版本历史:**\
4.0.0 - 添加
##### `configuration[statuses][max_characters]` {#max_characters}
**描述:** 每条嘟文允许的最大字符数。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
##### `configuration[statuses][max_media_attachments]` {#max_media_attachments}
**描述:** 可以添加到嘟文的最大媒体附件数。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
##### `configuration[statuses][characters_reserved_per_url]` {#characters_reserved_per_url}
**描述:** 嘟文中的每个 URL 将被假定为占用的字符数。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
#### `configuration[media_attachments]` {#media_attachments}
**描述:** 有关将接受哪些附件的提示。\
**类型:** Hash\
**版本历史:**\
4.0.0 - 添加
##### `configuration[media_attachments][supported_mime_types]` {#supported_mime_types}
**描述:** 包含可以上传的 MIME 类型。\
**类型:** 字符串数组\
**版本历史:**\
4.0.0 - 添加
##### `configuration[media_attachments][description_limit]` {#description_limit}
**描述:** 描述的最大大小（以字符为单位）。\
**类型:** 整数\
**版本历史:**\
4.4.0 - 添加
##### `configuration[media_attachments][image_size_limit]` {#image_size_limit}
**描述:** 任何上传图像的最大大小（以字节为单位）。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
##### `configuration[media_attachments][image_matrix_limit]` {#image_matrix_limit}
**描述:** 图像上传的最大像素数（宽度乘以高度）。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
##### `configuration[media_attachments][video_size_limit]` {#video_size_limit}
**描述:** 任何上传视频的最大大小（以字节为单位）。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
##### `configuration[media_attachments][video_frame_rate_limit]` {#video_frame_rate_limit}
**描述:** 任何上传视频的最大帧速率。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
##### `configuration[media_attachments][video_matrix_limit]` {#video_matrix_limit}
**描述:** 视频上传的最大像素数（宽度乘以高度）。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
#### `configuration[polls]` {#polls}
**描述:** 与投票相关的限制。\
**类型:** Hash\
**版本历史:**\
4.0.0 - 添加
##### `configuration[polls][max_options]` {#max_options}
**描述:** 每个投票最多允许的选项数。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
##### `configuration[polls][max_characters_per_option]` {#max_characters_per_option}
**描述:** 每个投票选项允许的字符数。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
##### `configuration[polls][min_expiration]` {#min_expiration}
**描述:** 允许的最短投票持续时间（以秒为单位）。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
##### `configuration[polls][max_expiration]` {#max_expiration}
**描述:** 允许的最长投票持续时间（以秒为单位）。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
#### `configuration[translation]` {#translation}
**描述:** 与翻译相关的提示。\
**类型:** Hash\
**版本历史:**\
4.0.0 - 添加
##### `configuration[translation][enabled]` {#translation-enabled}
**描述:** 此实例是否提供 Translations API。\
**类型:** 布尔值\
**版本历史:**\
4.0.0 - 添加
### `registrations`
**描述:** 有关注册此网站的信息。\
**类型:** Hash\
**版本历史:**\
4.0.0 - 添加
#### `registrations[enabled]` {#registrations-enabled}
**描述:** 是否启用注册。\
**类型:** 布尔值\
**版本历史:**\
4.0.0 - 添加
#### `registrations[approval_required]` {#approval_required}
**描述:** 注册是否需要管理员批准。\
**类型:** 布尔值\
**版本历史:**\
4.0.0 - 添加
#### `registrations[message]` {#registrations-message}
**描述:** 注册关闭时显示的自定义消息。\
**类型:** {{<nullable>}} 字符串 (HTML) or null\
**版本历史:**\
4.0.0 - 添加
#### `registrations[min_age]` {#registrations-min_age}
**描述:** 若配置，则为注册所需的最小年龄。\
**类型:** {{<nullable>}} 整数或 null\
**版本历史:**\
4.4.0 - 添加
#### `registrations[reason_required]` {#registrations-reason_required}
**描述:** 注册是否需要用户提供加入理由。仅当 `registrations[approval_required]` 为 true 时适用。\
**类型:** {{<nullable>}} 布尔值\
**版本历史:**\
4.4.0 - 添加
### `api_versions` {#api-versions}
**描述:** 有关此实例实现的 API 版本的信息。它至少包含一个 `mastodon` 属性，其他实现可能具有自己的附加属性。\
**类型:** Hash\
**版本历史:**\
4.3.0 - 添加
### `api_versions[mastodon]`
**描述:** 此实例实现的 API 版本号。 从 Mastodon v4.3.0 开始，API 更改将附带一个版本号，客户端可以根据此值进行检查。\
**类型:** 整数\
**版本历史:**\
4.3.0 - 添加
### `contact` {#contact}
**描述:** 与联系网站代表相关的提示。\
**类型:** Hash\
**版本历史:**\
4.0.0 - 添加
#### `contact[email]` {#contact-email}
**描述:** 可以发送消息以询问或举报问题的电子邮件地址。\
**类型:** 字符串 (Email)\
**版本历史:**\
4.0.0 - 添加
#### `contact[account]` {#contact-account}
**描述:** 可以通过网络联系以询问或举报问题的帐户。\
**类型:** {{<nullable>}} [Account]({{< relref "entities/Account" >}}) or null\
**版本历史:**\
4.0.0 - 添加
### `rules` {#rules}
**描述:** 此网站的规则的详细列表。\
**类型:** [Rule]({{< relref "entities/Rule" >}}) 数组\
**版本历史:**\
4.0.0 - 添加
## InstanceIcon 属性 {#InstanceIcon}
### `src` {#src}
**描述:** 此图标的 URL。\
**类型:** 字符串\
**版本历史:**\
4.3.0 - 添加
### `size` {#size}
**描述:** 此图标的大小。\
**类型:** 字符串 (格式形如 `12x34`, 其中 `12` 是图标宽度，`34` 是图标高度)\
**版本历史:**\
4.3.0 - 添加
## 参见
{{< page-relref ref="methods/instance#v2" caption="GET /api/v2/instance" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/instance_serializer.rb" caption="app/serializers/rest/instance_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Instance" raw_link="/entities/Instance/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

58
content/zh-cn/entities/List.md Normal file
View file

@ -0,0 +1,58 @@
---
title: List
description: 表示用户所关注的一些用户的列表。
menu:
docs:
parent: entities
aliases: [
"/entities/list",
"/entities/List",
"/api/entities/list",
"/api/entities/List",
]
---
## 示例
```json
{
"id": "12249",
"title": "Friends"
}
```
## 属性
### `id` {#id}
**描述:** 列表的内部数据库 ID。\
**类型:** 字符串（从整数转换而来，但不保证是一个数字）\
**版本历史:**\
2.1.0 - 添加
### `title` {#title}
**描述:** 用户自定义的列表标题。\
**类型:** 字符串\
**版本历史:**\
2.1.0 - 添加
### `replies_policy` {#replies_policy}
**描述:** 应在列表中显示哪些回复。\
**类型:** 字符串（可枚举的 oneOf）\
`followed` = 显示对任何已关注用户的回复\
`list` = 显示对列表成员的回复\
`none` = 不显示对任何人的回复\
**版本历史:**\
3.3.0 - 添加
## 参见
{{< page-relref ref="methods/accounts#lists" caption="GET /api/v1/accounts/:id/lists" >}}
{{< page-relref ref="methods/lists" caption="lists API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/list_serializer.rb" caption="app/serializers/rest/list_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="List" raw_link="/entities/List/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

52
content/zh-cn/entities/Marker.md Normal file
View file

@ -0,0 +1,52 @@
---
title: Marker
description: 表示用户在时间线中最后阅读的位置。
menu:
docs:
parent: entities
aliases: [
"/entities/marker",
"/entities/Marker",
"/api/entities/marker",
"/api/entities/Marker",
]
---
## 示例
```json
{
"last_read_id": "103194548672408537",
"version": 462,
"updated_at": "2019-11-24T19:39:39.337Z"
}
```
## 属性
### `last_read_id` {#last_read_id}
**描述:** 最近查看的实体的 ID。\
**类型:** 字符串（从整数转换而来，但不保证一定是数字）\
3.0.0 - 添加
### `version` {#version}
**描述:** 一个递增的计数器，用于锁定以防止写冲突。\
**类型:** 整数\
**版本历史:**\
3.0.0 - 添加
### `updated_at` {#updated_at}
**描述:** 标记被设置的时间戳。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
3.0.0 - 添加
## 参见
{{< page-relref ref="methods/markers" caption="markers API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/marker_serializer.rb" caption="app/serializers/rest/marker_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Marker" raw_link="/entities/Marker/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

242
content/zh-cn/entities/MediaAttachment.md Normal file
View file

@ -0,0 +1,242 @@
---
title: MediaAttachment
description: 表示可以被添加到嘟文的的文件或媒体附件。
menu:
docs:
parent: entities
aliases: [
"/entities/attachment",
"/entities/Attachment",
"/entities/mediaattachment",
"/entities/MediaAttachment",
"/api/entities/attachment",
"/api/entities/Attachment",
"/api/entities/mediaattachment",
"/api/entities/MediaAttachment",
]
---
## 示例
### 图像
```json
{
"id": "22345792",
"type": "image",
"url": "https://files.mastodon.social/media_attachments/files/022/345/792/original/57859aede991da25.jpeg",
"preview_url": "https://files.mastodon.social/media_attachments/files/022/345/792/small/57859aede991da25.jpeg",
"remote_url": null,
"text_url": "https://mastodon.social/media/2N4uvkuUtPVrkZGysms",
"meta": {
"original": {
"width": 640,
"height": 480,
"size": "640x480",
"aspect": 1.3333333333333333
},
"small": {
"width": 461,
"height": 346,
"size": "461x346",
"aspect": 1.3323699421965318
},
"focus": {
"x": -0.27,
"y": 0.51
}
},
"description": "测试媒体描述文本",
"blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}"
}
```
### 视频
```json
{
"id": "22546306",
"type": "video",
"url": "https://files.mastodon.social/media_attachments/files/022/546/306/original/dab9a597f68b9745.mp4",
"preview_url": "https://files.mastodon.social/media_attachments/files/022/546/306/small/dab9a597f68b9745.png",
"remote_url": null,
"text_url": "https://mastodon.social/media/wWd1HJIBmH1MZGDfg50",
"meta": {
"length": "0:01:28.65",
"duration": 88.65,
"fps": 24,
"size": "1280x720",
"width": 1280,
"height": 720,
"aspect": 1.7777777777777777,
"audio_encode": "aac (LC) (mp4a / 0x6134706D)",
"audio_bitrate": "44100 Hz",
"audio_channels": "stereo",
"original": {
"width": 1280,
"height": 720,
"frame_rate": "6159375/249269",
"duration": 88.654,
"bitrate": 862056
},
"small": {
"width": 400,
"height": 225,
"size": "400x225",
"aspect": 1.7777777777777777
}
},
"description": null,
"blurhash": "U58E0g8_0M.94T?bIr00?bD%NGoM?bD%oLt7"
}
```
### GIFV
```json
{
"id": "21130559",
"type": "gifv",
"url": "https://files.mastodon.social/media_attachments/files/021/130/559/original/bc84838f77991326.mp4",
"preview_url": "https://files.mastodon.social/media_attachments/files/021/130/559/small/bc84838f77991326.png",
"remote_url": null,
"text_url": "https://mastodon.social/media/2ICiasGyjezmi7cQYM8",
"meta": {
"length": "0:00:01.11",
"duration": 1.11,
"fps": 33,
"size": "600x332",
"width": 600,
"height": 332,
"aspect": 1.8072289156626506,
"original": {
"width": 600,
"height": 332,
"frame_rate": "100/3",
"duration": 1.11,
"bitrate": 1627639
},
"small": {
"width": 400,
"height": 221,
"size": "400x221",
"aspect": 1.8099547511312217
}
},
"description": null,
"blurhash": "URHT%Jm,2a1d%MRO%LozkrNH$*n*oMn$Rjt7"
}
```
### 音频
```json
{
"id": "21165404",
"type": "audio",
"url": "https://files.mastodon.social/media_attachments/files/021/165/404/original/a31a4a46cd713cd2.mp3",
"preview_url": "https://files.mastodon.social/media_attachments/files/021/165/404/small/a31a4a46cd713cd2.mp3",
"remote_url": null,
"text_url": "https://mastodon.social/media/5O4uILClVqBWx0NNgvo",
"meta": {
"length": "0:06:42.86",
"duration": 402.86,
"audio_encode": "mp3",
"audio_bitrate": "44100 Hz",
"audio_channels": "stereo",
"original": {
"duration": 402.860408,
"bitrate": 166290
}
},
"description": null,
"blurhash": null
}
```
## 属性
### `id` {#id}
**描述:** 附件在数据库中的 ID。\
**类型:** 字符串 (从整数转换而来，但不保证为数字)\
**版本历史:**\
0.6.0 - 添加
### `type` {#type}
**描述:** 附件的类型。\
**类型:** 字符串 (可枚举，oneOf)\
`unknown` = 不支持或无法识别的文件类型\
`image` = 静态图像\
`gifv` = 循环播放、无声动画\
`video` = 视频剪辑\
`audio` = 音轨\
**版本历史:**\
0.6.0 - 添加\
2.9.1 - 添加 `audio`
### `url` {#url}
**描述:** 原始完整尺寸附件的位置。\
**类型:** 字符串 (URL)\
**版本历史:**\
0.6.0 - 添加
### `preview_url` {#preview_url}
**描述:** 附件的缩略图的位置。\
**类型:** {{<nullable>}} 字符串 (URL)\
**版本历史:**\
0.6.0 - 添加
### `remote_url` {#remote_url}
**描述:** 外站的完整尺寸原始附件的位置。\
**类型:** {{<nullable>}} 字符串 (URL)，如果附件是本站的，则为 null\
**版本历史:**\
0.6.0 - 添加
### `meta` {#meta}
**描述:** Paperclip 返回的元数据。\
**类型:** Hash\
**版本历史:**\
1.5.0 - 添加\
2.3.0 - 添加 `meta.focus`
可以包含 `small` 和 `original` 子树，及各种其他顶层属性。
更重要的是，从 2.3.0 开始，图像上可能还有另一个顶层 `focus` Hash 对象，其坐标可用于智能缩略图裁剪——请参阅[裁剪媒体缩略图的焦点]({{< relref "api/guidelines#focal-points" >}}) 获取更多信息。
### `description` {#description}
**描述:** 用于描述媒体附件内容的替代文本，适用于视障人士或媒体附件未加载时的情况。\
**类型:** {{<nullable>}} 字符串，如果未为媒体附件提供替代文本，则为 null\
**版本历史:**\
2.0.0 - 添加
### `blurhash` {#blurhash}
**描述:** 由 [BlurHash 算法](https://github.com/woltapp/blurhash) 计算的哈希值，用于在媒体尚未下载时生成彩色预览缩略图。\
**类型:** {{<nullable>}} 字符串 (Blurhash)\
**版本历史:**\
2.8.1 - 添加
### `text_url` {{%removed%}} {#text_url}
**描述:** 附件的短 URL。\
**类型:** 字符串 (URL)\
**版本历史:**\
0.6.0 - 添加\
3.5.0 - 移除
## 参见
{{< page-relref ref="entities/Status#media_attachments" caption="Status (`media_attachments` attribute)" >}}
{{< page-relref ref="methods/media" caption="media API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/media_attachment_serializer.rb" caption="app/serializers/rest/media_attachment_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="MediaAttachment" raw_link="/entities/MediaAttachment/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

158
content/zh-cn/entities/Notification.md Normal file
View file

@ -0,0 +1,158 @@
---
title: Notification
description: 表示与用户相关的事件通知。
menu:
docs:
parent: entities
aliases: [
"/entities/notification",
"/entities/Notification",
"/entities/notification",
"/entities/Notification",
]
---
## 属性
### `id` {#id}
**描述:** 数据库中通知的 ID。\
**类型:** 字符串 (从整数转换而来，但不保证是一个数字)\
**版本历史:**\
0.9.9 - 添加
### `type` {#type}
**描述:** 导致通知的事件类型。\
**类型:** 字符串 (可枚举 oneOf)\
`mention` = 有人在他们的嘟文中提到了你\
`status` = 你启用了发嘟通知的用户发布了嘟文\
`reblog` = 有人转发了你的一条嘟文\
`follow` = 有人关注了你\
`follow_request` = 有人请求关注你\
`favourite` = 有人喜欢了你的一条嘟文\
`poll` = 你投票或创建的投票已结束\
`update` = 你转发的嘟文已被编辑\
`admin.sign_up` = 有人注册了（可选择发送给管理员）\
`admin.report` = 有新的举报被提交\
`severed_relationships` = 由于管理或屏蔽事件，你的一些关注关系已被切断\
`moderation_warning` = 管理员已对你的帐户采取了行动或向你发送了警告\
**版本历史:**\
0.9.9 - 添加\
2.8.0 - 添加 `poll`\
3.1.0 - 添加 `follow_request`\
3.3.0 - 添加 `status`\
3.5.0 - 添加 `update` and `admin.sign_up`\
4.0.0 - 添加 `admin.report`\
4.3.0 - 添加 `severed_relationships` and `moderation_warning`
### `group_key` {#group_key}
**描述:** 类似通知共享的群组键，用于分组通知功能。应被视为不透明，但可以假定未分组的通知具有 `group_key` 形式 `ungrouped-{notification_id}`。
**类型:** 字符串\
**版本历史:**\
4.3.0 - 添加
### `created_at` {#created_at}
**描述:** 通知的时间戳。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
0.9.9 - 添加
### `account` {#account}
**描述:** 执行了生成通知的操作的帐户。\
**类型:** [Account]({{< relref "entities/Account" >}})\
**版本历史:**\
0.9.9 - 添加
### `status` {{%optional%}} {#status}
**描述:** 作为通知对象的嘟文。当通知的 `type` 为 `favourite`、`reblog`、`status`、`mention`、`poll` 或 `update` 时附加。\
**类型:** [Status]({{< relref "entities/Status" >}})\
**版本历史:**\
0.9.9 - 添加
### `report` {{%optional%}} {#report}
**描述:** 作为通知对象的举报。当通知的 `type` 为 `admin.report` 时附加。\
**类型:** [Report]({{< relref "entities/Report" >}})\
**版本历史:**\
4.0.0 - 添加
### `event` {{%optional%}} {#relationship_severance_event}
**描述:** 导致关注关系中断的事件摘要。当通知的 `type` 为 `severed_relationships` 时附加。\
**类型:** [RelationshipSeveranceEvent]({{< relref "entities/RelationshipSeveranceEvent" >}})\
**版本历史:**\
4.3.0 - 添加
### `moderation_warning` {{%optional%}} {#moderation_warning}
**描述:** 导致通知的管理警告。当通知的 `type` 为 `moderation_warning` 时附加。\
**类型:** [AccountWarning]({{< relref "entities/AccountWarning" >}})\
**版本历史:**\
4.3.0 - 添加
## 示例
### Mention
```json
{
"id": "34975861",
"type": "mention",
"created_at": "2019-11-23T07:49:02.064Z",
"account": {
"id": "971724",
"username": "zsc",
"acct": "zsc",
// ...
},
"status": {
"id": "103186126728896492",
"created_at": "2019-11-23T07:49:01.940Z",
"in_reply_to_id": "103186038209478945",
"in_reply_to_account_id": "14715",
// ...
}
}
```
### Favourite
```json
{
"id": "34975535",
"type": "favourite",
"created_at": "2019-11-23T07:29:18.903Z",
"account": {
"id": "297420",
"username": "haskal",
"acct": "haskal@cybre.space",
// ...
},
"status": {
"id": "103186046267791694",
"created_at": "2019-11-23T07:28:34.210Z",
// ...
"account": {
"id": "14715",
"username": "trwnh",
"acct": "trwnh",
// ...
},
// ...
}
}
```
## 另请参考
{{< page-relref ref="methods/notifications" caption="notifications API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/notification_serializer.rb" caption="app/serializers/rest/notification_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Notification" raw_link="/entities/Notification/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

94
content/zh-cn/entities/NotificationPolicy.md Normal file
View file

@ -0,0 +1,94 @@
---
title: NotificationPolicy
description: 表示用户的通知过滤策略。
menu:
docs:
parent: entities
aliases: [
"/entities/NotificationPolicy",
]
---
## 属性
### `for_not_following` {#for_not_following}
**描述:** 是否 `accept`（接受）、`filter`（过滤）或 `drop`（丢弃）来自用户未关注帐户的通知。`drop` 将完全阻止通知对象的创建（不会阻止底层活动），`filter` 会将其标记为已过滤，而 `accept` 不会影响其处理。\
**类型:** 字符串 (`accept`, `filter` or `drop` 之一)\
**版本历史:**\
4.3.0 - 新增
### `for_not_followers` {#for_not_followers}
**描述:** 是否 `accept`（接受）、`filter`（过滤）或 `drop`（丢弃）来自未关注用户的帐户的通知。`drop` 将完全阻止通知对象的创建（不会阻止底层活动），`filter` 会将其标记为已过滤，而 `accept` 不会影响其处理。\
**类型:** 字符串 (`accept`, `filter` or `drop` 之一)\
**版本历史:**\
4.3.0 - 新增
### `for_new_accounts` {#for_new_accounts}
**描述:** 是否 `accept`（接受）、`filter`（过滤）或 `drop`（丢弃）来自过去 30 天内创建的帐户的通知。`drop` 将完全阻止通知对象的创建（不会阻止底层活动），`filter` 会将其标记为已过滤，而 `accept` 不会影响其处理。\
**类型:** 字符串 (`accept`, `filter` or `drop` 之一)\
**版本历史:**\
4.3.0 - 新增
### `for_private_mentions` {#for_private_mentions}
**描述:** 是否 `accept`（接受）、`filter`（过滤）或 `drop`（丢弃）来自私有提及的通知。`drop` 将完全阻止通知对象的创建（不会阻止底层活动），`filter` 会将其标记为已过滤，而 `accept` 不会影响其处理。对用户发起的私有提及的回复，以及用户关注的帐户，始终被允许，无论此值如何。\
**类型:** 字符串 (`accept`, `filter` or `drop` 之一)\
**版本历史:**\
4.3.0 - 新增
### `for_limited_accounts` {#for_limited_accounts}
**描述:** 是否 `accept`（接受）、`filter`（过滤）或 `drop`（丢弃）来自被管理员限制的帐户的通知。`drop` 将完全阻止通知对象的创建（不会阻止底层活动），`filter` 会将其标记为已过滤，而 `accept` 不会影响其处理。\
**类型:** 字符串 (`accept`, `filter` or `drop` 之一)\
**版本历史:**\
4.3.0 - 新增
### `summary` {#summary}
**描述:** 已过滤通知的摘要。\
**类型:** Hash\
**版本历史:**\
4.3.0 - 新增
### `summary[pending_requests_count]` {#pending_requests_count}
**描述:** 用户收到的过滤后且未处理通知的来源帐户的数量。上限为 100。\
**类型:** 整数\
**版本历史:**\
4.3.0 - 新增
### `summary[pending_notifications_count]` {#pending_notifications_count}
**描述:** 过滤后未处理的通知总数。可能不准确。\
**类型:** 整数\
**版本历史:**\
4.3.0 - 新增
## 示例
```json
{
"for_not_following": "accept",
"for_not_followers": "accept",
"for_new_accounts": "accept",
"for_private_mentions": "drop",
"for_limited_accounts": "filter",
"summary": {
"pending_requests_count": 0,
"pending_notifications_count": 0
}
}
```
## 另请参考
{{< page-relref ref="methods/notifications" caption="notifications API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/notification_policy_serializer.rb" caption="app/serializers/rest/notification_policy_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="NotificationPolicy" raw_link="/entities/NotificationPolicy/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

106
content/zh-cn/entities/NotificationRequest.md Normal file
View file

@ -0,0 +1,106 @@
---
title: NotificationRequest
description: 表示来自特定用户的被过滤的通知组。
menu:
docs:
parent: entities
aliases: [
"/entities/NotificationRequest",
]
---
## 属性
### `id` {#id}
**描述:** 数据库中通知请求的 ID。\
**类型:** 字符串 (从整数转换而来，但不保证为数字)\
**版本历史:**\
4.3.0 - 添加
### `created_at` {#created_at}
**描述:** 通知请求的时间戳，即来自该用户的第一个被过滤的通知的创建时间。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
4.3.0 - 添加
### `updated_at` {#updated_at}
**描述:** 上次更新通知请求的时间戳。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
4.3.0 - 添加
### `account` {#account}
**描述:** 执行了生成过滤通知的操作的帐户。\
**类型:** [Account]({{< relref "entities/Account" >}})\
**版本历史:**\
4.3.0 - 添加
### `notifications_count` {#notifications_count}
**描述:** 此帐户有多少通知被过滤。\
**类型:** 字符串\
**版本历史:**\
4.3.0 - 添加
### `last_status` {{%optional%}} {#last_status}
**描述:** 与该帐户的过滤通知关联的最新嘟文。\
**类型:** [Status]({{< relref "entities/Status" >}})\
**版本历史:**\
4.3.0 - 添加
## 示例
```json
{
"id": "112456967201894256",
"created_at": "2024-05-17T14:45:41.171Z",
"updated_at": "2024-05-17T14:45:41.171Z",
"notifications_count": "1",
"account": {
"id": "971724",
"username": "zsc",
"acct": "zsc",
// ...
},
"last_status": {
"id": "103186126728896492",
"created_at": "2019-11-23T07:49:01.940Z",
"in_reply_to_id": "103186038209478945",
"in_reply_to_account_id": "14715",
// ...
"content": "<p><span class=\"h-card\"><a href=\"https://mastodon.social/@trwnh\" class=\"u-url mention\">@<span>trwnh</span></a></span> sup!</p>",
// ...
"account": {
"id": "971724",
"username": "zsc",
"acct": "zsc",
// ...
},
// ...
"mentions": [
{
"id": "14715",
"username": "trwnh",
"url": "https://mastodon.social/@trwnh",
"acct": "trwnh"
}
],
// ...
}
}
```
## 另请参阅
{{< page-relref ref="methods/notifications" caption="notifications API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/notification_request_serializer.rb" caption="app/serializers/rest/notification_request_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="NotificationRequest" raw_link="/entities/NotificationRequest/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

139
content/zh-cn/entities/Poll.md Normal file
View file

@ -0,0 +1,139 @@
---
title: Poll
description: 表示被附加到嘟文的投票。
menu:
docs:
parent: entities
aliases: [
"/entities/poll",
"/entities/Poll",
"/api/entities/poll",
"/api/entities/Poll",
]
---
## 示例
```json
{
"id": "34830",
"expires_at": "2019-12-05T04:05:08.302Z",
"expired": true,
"multiple": false,
"votes_count": 10,
"voters_count": null,
"voted": true,
"own_votes": [
1
],
"options": [
{
"title": "accept",
"votes_count": 6
},
{
"title": "deny",
"votes_count": 4
}
],
"emojis": []
}
```
## 属性
### `id` {#id}
**描述:** 数据库中投票的ID。\
**类型:** 字符串（从整数转换而来，但不保证是数字）\
**版本历史:**\
2.8.0 - 添加
### `expires_at` {#expires_at}
**描述:** 投票结束的时间。\
**类型:** {{<nullable>}} 字符串 ([Datetime](/api/datetime-format#datetime))，如果投票永不结束，则为 null\
**版本历史:**\
2.8.0 - 添加
### `expired` {#expired}
**描述:** 投票当前是否已结束？\
**类型:** 布尔值\
**版本历史:**\
2.8.0 - 添加
### `multiple` {#multiple}
**描述:** 投票是否允许多选？\
**类型:** 布尔值\
**版本历史:**\
2.8.0 - 添加
### `votes_count` {#votes_count}
**描述:** 投票收到的票数。\
**类型:** 整数\
**版本历史:**\
2.8.0 - 添加
### `voters_count` {#voters_count}
**描述:** 在一个多选投票中，有多少个独立账户进行了投票。\
**类型:** {{<nullable>}} 整数，如果 `multiple` 为 false，则为 null。\
**版本历史:**\
2.8.0 - 添加
### `options` {#options}
**描述:** 投票的选项。\
**类型:** [Poll::Option](#Option) 数组\
**版本历史:**\
2.8.0 - 添加
### `emojis` {#emojis}
**描述:** 用于渲染投票选项的自定义表情。\
**类型:** [CustomEmoji]({{< relref "entities/CustomEmoji" >}}) 数组\
**版本历史:**\
2.8.0 - 添加
### `voted` {{%optional%}} {#voted}
**描述:** 当使用用户令牌调用对应的 API 时，该令牌的授权用户是否已投票？\
**类型:** 布尔值\
**版本历史:**\
2.8.0 - 添加
### `own_votes` {{%optional%}} {#own_votes}
**描述:** 当使用用户令牌调用对应的 API 时，该令牌的授权用户选择了哪些选项？ 包含 `options` 的索引值数组。\
**类型:** 整数数组\
**版本历史:**\
2.8.0 - 添加
## Poll::Option 属性 {#Option}
### `title` {#option-title}
**描述:** 投票选项的文本值。\
**类型:** 字符串\
**版本历史:**\
2.8.0 - 添加
#### `votes_count` {#option-votes_count}
**描述:** 此选项收到的总票数。\
**类型:** {{<nullable>}} 整数，如果结果尚未发布，则为 null。\
**版本历史:**\
2.8.0 - 添加
## 参见
{{< page-relref ref="entities/Status#poll" caption="嘟文 (`poll` 属性)" >}}
{{< page-relref ref="methods/polls" caption="polls API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/poll_serializer.rb" caption="app/serializers/rest/poll_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Poll" raw_link="/entities/Poll/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

77
content/zh-cn/entities/Preferences.md Normal file
View file

@ -0,0 +1,77 @@
---
title: Preferences
description: 表示用户的偏好设置。
menu:
docs:
parent: entities
aliases: [
"/entities/preferences",
"/entities/Preferences",
"/api/entities/preferences",
"/api/entities/Preferences",
]
---
## 示例
```json
{
"posting:default:visibility": "public",
"posting:default:sensitive": false,
"posting:default:language": null,
"reading:expand:media": "default",
"reading:expand:spoilers": false
}
```
## 属性
### `posting:default:visibility` {#posting-default-visibility}
**描述:** 新嘟文的默认可见性。等同于 [CredentialAccount#source\[privacy\]]({{< relref "entities/Account#source-privacy" >}})。\
**类型:** 字符串 (枚举, 取值之一)\
`public` = 公开\
`unlisted` = 悄悄公开\
`private` = 仅关注者可见\
`direct` = 私下提及\
**版本历史:**\
2.8.0 - 添加
### `posting:default:sensitive` {#posting-default-sensitive}
**描述:** 新嘟文的默认敏感标记。等同于 [CredentialAccount#source\[sensitive\]]({{< relref "entities/Account#source-sensitive" >}})。\
**类型:** 布尔值\
**版本历史:**\
2.8.0 - 添加
### `posting:default:language` {#posting-default-language}
**描述:** 新嘟文的默认语言。等同于 [CredentialAccount#source\[language\]]({{< relref "entities/Account#source-language" >}})\
**类型:** {{<nullable>}} 字符串 (ISO 639-1 双字符语言代码), 或 null\
**版本历史:**\
2.8.0 - 添加
### `reading:expand:media` {#reading-expand-media}
**描述:** 媒体附件是否应自动显示或模糊/隐藏。\
**类型:** 字符串 (枚举, 取值之一)\
`default` = 隐藏标记为敏感的媒体\
`show_all` = 默认始终显示所有媒体，无论是否敏感\
`hide_all` = 默认始终隐藏所有媒体，无论是否敏感\
**版本历史:**\
2.8.0 - 添加
### `reading:expand:spoilers` {#reading-expand-spoilers}
**描述:** CW(内容警告) 是否应默认展开。\
**类型:** 布尔值\
**版本历史:**\
2.8.0 - 添加
## 参见
{{< page-relref ref="methods/preferences" caption="preferences API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/preferences_serializer.rb" caption="app/serializers/rest/preferences_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Preferences" raw_link="/entities/Preferences/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

294
content/zh-cn/entities/PreviewCard.md Normal file
View file

@ -0,0 +1,294 @@
---
title: PreviewCard
description: 表示使用来自 URL 的 OpenGraph 标签生成的富媒体预览卡片。
menu:
docs:
parent: entities
aliases: [
"/entities/card",
"/entities/Card",
"/entities/previewcard",
"/entities/PreviewCard",
"/api/entities/card",
"/api/entities/Card",
"/api/entities/previewcard",
"/api/entities/PreviewCard",
]
---
## 示例
### 视频
```json
{
"url": "https://www.youtube.com/watch?v=OMv_EPMED8Y",
"title": "♪ Brand New Friend (Christmas Song!)",
"description": "",
"type": "video",
"author_name": "YOGSCAST Lewis & Simon",
"author_url": "https://www.youtube.com/user/BlueXephos",
"provider_name": "YouTube",
"provider_url": "https://www.youtube.com/",
"html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/OMv_EPMED8Y?feature=oembed\" frameborder=\"0\" allowfullscreen=\"\"></iframe>",
"width": 480,
"height": 270,
"image": "https://files.mastodon.social/preview_cards/images/014/179/145/original/9cf4b7cf5567b569.jpeg",
"embed_url": "",
"blurhash": "UvK0HNkV,:s9xBR%njog0fo2W=WBS5ozofV@"
}
```
### 图片
```json
{
"url": "https://www.flickr.com/photos/tomfenskephotography/49088768431/",
"title": "Oregon",
"description": "",
"type": "photo",
"author_name": "Tom Fenske Photography",
"author_url": "https://www.flickr.com/photos/tomfenskephotography/",
"provider_name": "Flickr",
"provider_url": "https://www.flickr.com/",
"html": "",
"width": 1024,
"height": 427,
"image": "https://files.mastodon.social/preview_cards/images/014/287/139/original/651b1c6976817824.jpeg",
"embed_url": "https://live.staticflickr.com/65535/49088768431_6a4322b3bb_b.jpg",
"blurhash": "UnE{@jt6M_oIAhjYs+ayT2WBf9ayRkkDXAj["
}
```
### 链接
```json
{
"url": "https://www.theguardian.com/money/2019/dec/07/i-lost-my-193000-inheritance-with-one-wrong-digit-on-my-sort-code",
"title": "‘I lost my £193,000 inheritance – with one wrong digit on my sort code’",
"description": "When Peter Teich’s money went to another Barclays customer, the bank offered £25 as a token gesture",
"type": "link",
"authors": [],
"author_name": "",
"author_url": "",
"provider_name": "",
"provider_url": "",
"html": "",
"width": 0,
"height": 0,
"image": null,
"embed_url": "",
"blurhash": null
}
```
## 属性
### `url` {#url}
**描述:** 链接资源的地址。\
**类型:** 字符串 (URL)\
**版本历史:**\
1.0.0 - 添加
### `title` {#title}
**描述:** 链接资源的标题。\
**类型:** 字符串\
**版本历史:**\
1.0.0 - 添加
### `description` {#description}
**描述:** 预览的描述。\
**类型:** 字符串\
**版本历史:**\
1.0.0 - 添加
### `type` {#type}
**描述:** 预览卡片的类型。\
**类型:** 字符串 (可枚举, oneOf)\
`link` = 链接 OEmbed\
`photo` = 图片 OEmbed\
`video` = 视频 OEmbed\
`rich` = iframe OEmbed。当前不接受，因此实际上不会显示。\
**版本历史:**\
1.3.0 - 添加
### `authors` {#authors}
**描述:** 原始资源的作者的 Fediverse 账号。\
**类型:** Array of [PreviewCardAuthor]({{< relref "entities/PreviewCardAuthor">}})\
**版本历史:**\
4.3.0 - 添加
### `author_name` {#author_name}
**描述:** 原始资源的作者。自 4.3.0 起已弃用，客户端应改用 `authors`。\
**类型:** 字符串\
**版本历史:**\
1.3.0 - 添加\
4.3.0 - deprecated
### `author_url` {#author_url}
**描述:** 指向原始资源作者的链接。自 4.3.0 起已弃用，客户端应改用 `authors`。\
**类型:** 字符串 (URL)\
**版本历史:**\
1.3.0 - 添加\
4.3.0 - deprecated
### `provider_name` {#provider_name}
**描述:** 原始资源的提供者。\
**类型:** 字符串\
**版本历史:**\
1.3.0 - 添加
### `provider_url` {#provider_url}
**描述:** 指向原始资源提供者的链接。\
**类型:** 字符串 (URL)\
**版本历史:**\
1.3.0 - 添加
### `html` {#html}
**描述:** 用于生成预览卡片的 HTML。\
**类型:** 字符串 (HTML)\
**版本历史:**\
1.3.0 - 添加
### `width` {#height}
**描述:** 预览的宽度，以像素为单位。\
**类型:** 整数\
**版本历史:**\
1.3.0 - 添加
### `height` {#height}
**描述:** 预览的高度，以像素为单位。\
**类型:** 整数\
**版本历史:**\
1.3.0 - 添加
### `image` {#image}
**描述:** 预览缩略图。\
**类型:** {{<nullable>}} 字符串 (URL)\
**版本历史:**\
1.0.0 - 添加
### `embed_url` {#embed_url}
**描述:** 用于照片嵌入，替代自定义的 `html`。\
**类型:** 字符串 (URL)\
**版本历史:**\
2.1.0 - 添加
### `blurhash` {#blurhash}
**描述:** 由 [BlurHash 算法](https://github.com/woltapp/blurhash)计算出的哈希值，用于在媒体尚未下载时生成彩色预览缩略图。\
**类型:** {{<nullable>}} 字符串\
**版本历史:**\
3.2.0 - 添加
## Trends::Link 实体属性 {#trends-link}
```json
{
"url": "https://www.nbcnews.com/specials/plan-your-vote-2022-elections/index.html",
"title": "Plan Your Vote: 2022 Elections",
"description": "Everything you need to know about the voting rules where you live, including registration, mail-in voting, changes since 2020, and more.",
"type": "link",
"author_name": "NBC News",
"author_url": "",
"provider_name": "NBC News",
"provider_url": "",
"html": "",
"width": 400,
"height": 225,
"image": "https://files.mastodon.social/cache/preview_cards/images/045/027/478/original/0783d5e91a14fd49.jpeg",
"embed_url": "",
"blurhash": "UcQmF#ay~qofj[WBj[j[~qof9Fayofofayay",
"history": [
{
"day": "1661817600",
"accounts": "7",
"uses": "7"
},
{
"day": "1661731200",
"accounts": "23",
"uses": "23"
},
{
"day": "1661644800",
"accounts": "0",
"uses": "0"
},
{
"day": "1661558400",
"accounts": "0",
"uses": "0"
},
{
"day": "1661472000",
"accounts": "0",
"uses": "0"
},
{
"day": "1661385600",
"accounts": "0",
"uses": "0"
},
{
"day": "1661299200",
"accounts": "0",
"uses": "0"
}
]
}
```
### `history` {#history}
**描述:** 给定日期的使用统计信息（通常是过去一周）。\
**类型:** 哈希值的数组\
**版本历史:**\
3.5.0 - 添加
#### `history[][day]` {#history-day}
**描述:** 给定日期午夜的 UNIX 时间戳。\
**类型:** 字符串 (UNIX 时间戳)\
**版本历史:**\
3.5.0 - 添加
#### `history[][accounts]` {#history-accounts}
**描述:** 当天使用该链接的已计数帐户数。\
**类型:** 字符串 (从整数转换而来)\
**版本历史:**\
3.5.0 - 添加
#### `history[][uses]` {#history-uses}
**描述:** 当天使用该链接的已计数嘟文数。\
**类型:** 字符串 (从整数转换而来)\
**版本历史:**\
3.5.0 - 添加
## 参见
{{< page-relref ref="entities/Status#card" caption="Status (`card` 属性)" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/preview_card_serializer.rb" caption="app/serializers/rest/preview_card_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/trends/link_serializer.rb" caption="app/serializers/rest/trends/link_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/trends/links.rb" caption="app/models/trends/links.rb" >}}
{{< translation-status-zh-cn raw_title="PreviewCard" raw_link="/entities/PreviewCard/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

41
content/zh-cn/entities/PreviewCardAuthor.md Normal file
View file

@ -0,0 +1,41 @@
---
title: PreviewCardAuthor
description: 表示富媒体预览卡片中的作者。
menu:
docs:
parent: entities
aliases: [
"/entities/PreviewCardAuthor",
]
---
## 属性
### `name` {#name}
**描述:** 原始资源的作者姓名。替换预览卡片中已弃用的 `author_name` 属性。\
**类型:** 字符串\
**版本历史:**\
4.3.0 - 添加
### `url` {#url}
**描述:** 指向原始资源作者的链接。替换预览卡片中已弃用的 `author_url` 属性。\
**类型:** 字符串 (URL)\
**版本历史:**\
4.3.0 - 添加
### `account` {{%nullable%}} {#account}
**描述:** 作者的联邦宇宙账号。\
**类型:** [Account]({{< relref "entities/Account">}})\
**版本历史:**\
4.3.0 - 添加
## 另请参考
{{< page-relref ref="entities/PreviewCard#authors" caption="PreviewCard (`authors` 属性)" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/preview_card_serializer.rb" caption="app/serializers/rest/preview_card_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="PreviewCardAuthor" raw_link="/entities/PreviewCardAuthor/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

46
content/zh-cn/entities/PrivacyPolicy.md Normal file
View file

@ -0,0 +1,46 @@
---
title: PrivacyPolicy
description: 表示实例的隐私政策。
menu:
docs:
parent: entities
aliases: [
"/entities/privacypolicy",
"/entities/PrivacyPolicy",
"/api/entities/privacypolicy",
"/api/entities/PrivacyPolicy",
]
---
## 示例
```json
{
"updated_at": "2022-10-07T00:00:00+00:00",
"content": "<p>This privacy policy describes how example.com (&quot;example.com&quot;, &quot;we&quot;, &quot;us&quot;) collects,\nprotects and uses the personally identifiable information you may provide\nthrough the example.com website or its API.</p>\n\n<h1>What information do we collect?</h1>\n\n<ul>\n<li><strong>Basic account information</strong>: If you register on this server, you may be\nasked to enter a username, an e-mail address and a password.</li>\n<li><strong>Posts, following and other public information</strong>: The list of people you\nfollow is listed publicly, the same is true for your followers.</li>\n<li><strong>Direct and followers-only posts</strong>: All posts are stored and processed on the\nserver. You may\ntoggle an option to approve and reject new followers manually in the settings.\n<strong>Please keep in mind that the operators of the server and any receiving\nserver may view such messages</strong>, and that recipients may screenshot, copy or\notherwise re-share them. <strong>Do not share any sensitive information over\nMastodon.</strong></li>\n<li><strong>IPs and other metadata</strong>: When you log in, we record the IP address you log\nin from, as well as the name of your browser application.</li>\n</ul>\n\n<hr>\n\n<p>This document is CC-BY-SA. Originally adapted from the <a href=\"https://github.com/discourse/discourse\">Discourse privacy\npolicy</a>.</p>\n"
}
```
## 属性
### `updated_at` {#updated_at}
**描述:** 隐私政策上次更新的时间戳。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
4.0.0 - 添加
### `content` {#content}
**描述:** 隐私政策的渲染后的 HTML 内容。\
**类型:** 字符串 (HTML)\
**版本历史:**\
4.0.0 - 添加
## 参见
{{< page-relref ref="methods/instance#privacy_policy" caption="GET /api/v1/instance/privacy_policy" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/privacy_policy_serializer.rb" caption="app/serializers/rest/privacy_policy_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="PrivacyPolicy" raw_link="/entities/PrivacyPolicy/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

83
content/zh-cn/entities/Reaction.md Normal file
View file

@ -0,0 +1,83 @@
---
title: Reaction
description: 表示对公告的一个表情回应。
menu:
docs:
parent: entities
aliases: [
"/entities/announcementreaction",
"/entities/AnnouncementReaction",
"/entities/reaction",
"/entities/Reaction",
"/api/entities/announcementreaction",
"/api/entities/AnnouncementReaction",
"/api/entities/reaction",
"/api/entities/Reaction",
]
---
## 示例
```json
[
{
"name": "bongoCat",
"count": 9,
"me": false,
"url": "https://files.mastodon.social/custom_emojis/images/000/067/715/original/fdba57dff7576d53.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/067/715/static/fdba57dff7576d53.png"
},
{
"name": "🤔",
"count": 1,
"me": true
}
]
```
## 属性
### `name` {#name}
**描述:** 用于回应的表情。可以是 Unicode 表情，也可以是自定义表情的短代码。\
**类型:** 字符串\
**版本历史:**\
3.1.0 - 添加
### `count` {#count}
**描述:** 添加此回应的用户总数。\
**类型:** 整数\
**版本历史:**\
3.1.0 - 添加
### `me` {{%optional%}} {#me}
**描述:** 如果存在当前已授权用户：该授权用户是否添加了此回应？\
**类型:** 布尔值\
**版本历史:**\
3.1.0 - 添加
### `url` {{%optional%}} {#url}
**描述:** 如果回应是自定义表情：指向自定义表情的链接。\
**类型:** 字符串 (URL)\
**版本历史:**\
3.1.0 - 添加
### `static_url` {{%optional%}} {#static_url}
**描述:** 如果回应是自定义表情：指向非动画版本自定义表情的链接。\
**类型:** 字符串 (URL)\
**版本历史:**\
3.1.0 - 添加
## 参见
{{< page-relref ref="methods/announcements#put-reactions" caption="向公告添加回应" >}}
{{< page-relref ref="methods/announcements#delete-reactions" caption="从公告中删除回应" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/reaction_serializer.rb" caption="app/serializers/rest/reaction_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Reaction" raw_link="/entities/Reaction/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

149
content/zh-cn/entities/Relationship.md Normal file
View file

@ -0,0 +1,149 @@
---
title: Relationship
description: 表示账户之间的关系，例如关注/屏蔽/隐藏等。
menu:
docs:
parent: entities
aliases: [
"/entities/relationship",
"/entities/Relationship",
"/api/entities/relationship",
"/api/entities/Relationship",
]
---
## 示例
```json
{
"id": "1",
"following": true,
"showing_reblogs": true,
"notifying": false,
"followed_by": true,
"blocking": false,
"blocked_by": false,
"muting": false,
"muting_notifications": false,
"requested": false,
"requested_by": false,
"domain_blocking": false,
"endorsed": false,
"note": ""
}
```
## 属性
### `id` {#id}
**描述:** 账户 ID。\
**类型:** 字符串 (从整数转换而来，但不保证一定是数字)\
**版本历史:**
0.6.0 - 添加
### `following` {#following}
**描述:** 你是否正在关注此用户？\
**类型:** 布尔值\
**版本历史:**
0.6.0 - 添加
### `showing_reblogs` {#showing_reblogs}
**描述:** 你是否在你的首页时间线中接收此用户的转发？\
**类型:** 布尔值\
**版本历史:**
2.1.0 - 添加
### `notifying` {#notifying}
**描述:** 你是否为此用户启用了通知？\
**类型:** 布尔值\
**版本历史:**
3.3.0 - 添加
### `languages` {#languages}
**描述:** 你正在关注此用户的哪些语言？\
**类型:** 字符串数组 (ISO 639-1 双字符语言代码)\
**版本历史:**
4.0.0 - 添加
### `followed_by` {#followed_by}
**描述:** 此用户是否正在关注你？\
**类型:** 布尔值\
**版本历史:**
0.6.0 - 添加
### `blocking` {#blocking}
**描述:** 你是否正在屏蔽此用户？\
**类型:** 布尔值\
**版本历史:**
0.6.0 - 添加
### `blocked_by` {#blocked_by}
**描述:** 此用户是否正在屏蔽你？\
**类型:** 布尔值\
**版本历史:**
2.8.0 - 添加
### `muting` {#muting}
**描述:** 你是否正在隐藏此用户？\
**类型:** 布尔值\
**版本历史:**
1.1.0 - 添加
### `muting_notifications` {#muting_notifications}
**描述:** 你是否正在隐藏来自此用户的通知？\
**类型:** 布尔值\
**版本历史:**
2.1.0 - 添加
### `requested` {#requested}
**描述:** 你是否有对此用户待处理的关注请求？\
**类型:** 布尔值\
**版本历史:**
0.9.9 - 添加
### `requested_by` {#requested_by}
**描述:** 此用户是否请求关注你？\
**类型:** 布尔值\
**版本历史:**
4.1.0 - 添加
### `domain_blocking` {#domain_blocking}
**描述:** 你是否正在屏蔽此用户的域名？\
**类型:** 布尔值\
**版本历史:**
1.4.0 - 添加
### `endorsed` {#endorsed}
**描述:** 你是否在你的账户上推荐此用户？\
**类型:** 布尔值\
**版本历史:**
2.5.0 - 添加
### `note` {#note}
**描述:** 此用户的账户简介\
**类型:** 字符串\
**版本历史:**
3.2.0 - 添加
## 参见
{{< page-relref ref="methods/accounts#relationships" caption="GET /api/v1/accounts/relationships" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/relationship_serializer.rb" caption="app/serializers/rest/relationship_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Relationship" raw_link="/entities/Relationship/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

67
content/zh-cn/entities/RelationshipSeveranceEvent.md Normal file
View file

@ -0,0 +1,67 @@
---
title: RelationshipSeveranceEvent
description: 导致关注关系断开的管理或屏蔽事件的摘要。
menu:
docs:
parent: entities
aliases: [
"/entities/RelationshipSeveranceEvent",
"/api/entities/RelationshipSeveranceEvent",
]
---
## 属性
### `id` {#id}
**描述:** 数据库中关系断开事件的 ID。\
**类型:** 字符串 (从整数转换而来)\
**版本历史:**\
4.3.0 - 添加
### `type` {#type}
**描述:** 事件类型。\
**类型:** 字符串 (可枚举的 oneOf)\
`domain_block` = 审核员封禁了整个域名\
`user_domain_block` = 用户屏蔽了整个域名\
`account_suspension` = 审核员封禁了特定帐户\
**版本历史:**\
4.3.0 - 添加
### `purged` {#purged}
**描述:** 由于导致该事件的问题已被清除，断开的关系列表是否不可用。\
**类型:** 布尔值\
**版本历史:**\
4.3.0 - 添加
### `target_name` {#target_name}
**描述:** 审核/屏蔽事件的目标名称。 这可以是域名或用户名，具体取决于事件类型。\
**类型:** 字符串\
**版本历史:**\
4.3.0 - 添加
### `followers_count` {#followers_count}
**描述:** 由于该事件而被移除的关注者数量。\
**类型:** 整数\
**版本历史:**\
4.3.0 - 添加
### `following_count` {#following_count}
**描述:** 用户由于该事件而停止关注的帐户数量。\
**类型:** 整数\
**版本历史:**\
4.3.0 - 添加
### `created_at` {#created_at}
**描述:** 事件发生的时间。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
4.3.0 - 添加
{{< translation-status-zh-cn raw_title="RelationshipSeveranceEvent" raw_link="/entities/RelationshipSeveranceEvent/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

139
content/zh-cn/entities/Report.md Normal file
View file

@ -0,0 +1,139 @@
---
title: Report
description: 举报用户和/或嘟文，供审核员采取行动。
menu:
docs:
parent: entities
aliases: [
"/entities/report",
"/entities/Report",
"/api/entities/report",
"/api/entities/Report",
]
---
## 示例
```json
{
"id": "48914",
"action_taken": false,
"action_taken_at": null,
"category": "spam",
"comment": "Spam account",
"forwarded": false,
"created_at": "2022-08-25T09:56:16.763Z",
"status_ids": [
"108882889550545820"
],
"rule_ids": null,
"target_account": {
"id": "108366849347798387",
"username": "Baluke",
"acct": "Baluke",
"display_name": "Baluke Dental Studios",
"locked": false,
"bot": false,
"discoverable": false,
"group": false,
"created_at": "2022-05-26T00:00:00.000Z",
"note": "<p>Baluke Dental Studios is a full service dental lab offering fabrication, staining, and digital services. Advanced technologies and a meticulous process ensure reduced chair time, lower costs, and better patient outcomes with beautiful smiles. Talk to a representative today.</p><p><a href=\"https://baluke.com/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\"><span class=\"invisible\">https://</span><span class=\"\">baluke.com/</span><span class=\"invisible\"></span></a></p>",
"url": "https://mastodon.social/@Baluke",
"avatar": "https://files.mastodon.social/accounts/avatars/108/366/849/347/798/387/original/dbcfe99ed5def0f4.png",
"avatar_static": "https://files.mastodon.social/accounts/avatars/108/366/849/347/798/387/original/dbcfe99ed5def0f4.png",
"header": "https://static-cdn.mastodon.social/headers/original/missing.png",
"header_static": "https://static-cdn.mastodon.social/headers/original/missing.png",
"followers_count": 0,
"following_count": 0,
"statuses_count": 38,
"last_status_at": "2022-08-25",
"emojis": [],
"fields": []
}
}
```
## 属性
### `id` {#id}
**描述:** 数据库中举报的 ID。\
**类型:** 字符串 (从整数转换而来)\
**版本历史:**
1.1.0 - 添加
### `action_taken` {#action_taken}
**描述:** 是否已采取行动。\
**类型:** 布尔值\
**版本历史:**
1.1.0 - 添加
### `action_taken_at` {#action_taken_at}
**描述:** 针对举报采取行动的时间。\
**类型:** {{<nullable>}} 字符串 ([Datetime](/api/datetime-format#datetime)) or null\
**版本历史:**
4.0.0 - 添加
### `category` {#category}
**描述:** 举报的一般原因。\
**类型:** 字符串 (可枚举的 oneOf)\
`spam` = 不受欢迎或重复的内容\
`violation` = 违反了特定规则\
`other` = 其他原因\
**版本历史:**
4.0.0 - 添加
### `comment` {#comment}
**描述:** 举报的原因。\
**类型:** 字符串\
**版本历史:**
4.0.0 - 添加
### `forwarded` {#forwarded}
**描述:** 举报是否已转发到外站。\
**类型:** 布尔值\
**版本历史:**
4.0.0 - 添加
### `created_at` {#created_at}
**描述:** 举报的创建时间。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**
4.0.0 - 添加
### `status_ids` {#status_ids}
**描述:** 附加到此举报的嘟文 ID，用于提供额外上下文信息。\
**类型:** {{<nullable>}} Array of String (从整数转换而来), or null\
**版本历史:**
4.0.0 - 添加
### `rule_ids` {#rule_ids}
**描述:** 此举报中引用的、被违反的规则 ID。\
**类型:** {{<nullable>}} Array of String (从整数转换而来), or null\
**版本历史:**
4.0.0 - 添加
### `target_account` {#target_account}
**描述:** 被举报的帐户。\
**类型:** [Account]({{< relref "entities/account" >}})\
**版本历史:**
4.0.0 - 添加
## 参见
{{< page-relref ref="methods/reports" caption="举报 API 方法" >}}
{{< page-relref ref="entities/Notification#report" caption="通知 (`report` 属性)" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/report_serializer.rb" caption="app/serializers/rest/report_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Report" raw_link="/entities/Report/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

132
content/zh-cn/entities/Role.md Normal file
View file

@ -0,0 +1,132 @@
---
title: Role
description: 表示带有自定义权限设定的用户组。
menu:
docs:
parent: entities
aliases: [
"/entities/role",
"/entities/Role",
"/api/entities/role",
"/api/entities/Role",
]
---
## 示例
```json
{
"id": "3",
"name": "Owner",
"color": "#ff3838",
"permissions": "1048575",
"highlighted": true
}
```
## 属性
### `id` {#id}
**描述:** 数据库中用户组的 ID。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `name` {#name}
**描述:** 用户组的名称。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `color` {#color}
**描述:** 分配给此用户组的十六进制代码。如果未分配十六进制代码，则字符串将为空。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `permissions` {#permissions}
**描述:** 一个位掩码，表示授予该用户组的所有权限的总和。\
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
### `highlighted` {#highlighted}
**描述:** 是否在用户账户页上公开显示该用户组徽章。\
**类型:** 布尔值\
**版本历史:**\
4.0.0 - 添加
## 权限标志
要确定特定用户组可用的权限，请将 `permissions` 属性转换为二进制，然后从最低有效位开始进行比较。为了方便起见（并防止术语变得太长），权限将在下面使用十六进制值表示。
0x1
: **Administrator（管理员）**。拥有此权限的用户将绕过所有权限。
0x2
: **Devops（运维）**。允许用户访问 Sidekiq 和 PgHero 仪表板。
0x4
: **View Audit Log（查看审计日志）**。允许用户查看管理员操作的历史记录。
0x8
: **View Dashboard（查看仪表板）**。允许用户访问仪表板和各种指标。
0x10
: **Manage Reports（管理举报）**。允许用户审查举报并对其执行管理操作。
0x20
: **Manage Federation（管理联合）**。允许用户阻止或允许与其他域的联合，并控制可交付性。
0x40
: **Manage Settings（管理设置）**。允许用户更改站点设置。
0x80
: **Manage Blocks（管理屏蔽）**。允许用户屏蔽电子邮件提供商和 IP 地址。
0x100
: **Manage Taxonomies（管理热门内容）**。允许用户查看热门内容并更新话题标签设置。
0x200
: **Manage Appeals（管理申诉）**。允许用户审查针对管理操作的申诉。
0x400
: **Manage Users（管理用户）**。允许用户查看其他用户的详细信息并对其执行管理操作。
0x800
: **Manage Invites（管理邀请）**。允许用户浏览和停用邀请链接。
0x1000
: **Manage Rules（管理规则）**。允许用户更改实例规则。
0x2000
: **Manage Announcements（管理公告）**。允许用户管理实例上的公告。
0x4000
: **Manage Custom Emojis（管理自定义表情）**。允许用户管理实例上的自定义表情。
0x8000
: **Manage Webhooks（管理 Webhook）**。允许用户为管理事件设置 Webhook。
0x10000
: **Invite Users（邀请用户）**。允许用户邀请新人加入实例。
0x20000
: **Manage Roles（管理用户组）**。允许用户管理和分配权限低于其用户组权限的用户组。
0x40000
: **Manage User Access（管理用户权限）**。允许用户禁用其他用户的双因素身份验证、更改其电子邮件地址和重置其密码。
0x80000
: **Delete User Data（删除用户数据）**。允许用户立即删除其他用户的数据。
## 另请参见
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/role_serializer.rb" caption="app/serializers/rest/role_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Role" raw_link="/entities/Role/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

56
content/zh-cn/entities/Rule.md Normal file
View file

@ -0,0 +1,56 @@
---
title: Rule
description: 表示实例用户应遵守的规则。
menu:
docs:
parent: entities
aliases: [
"/entities/rule",
"/entities/Rule",
"/api/entities/rule",
"/api/entities/Rule",
]
---
## 示例
```json
{
"id": "2",
"text": "No racism, sexism, homophobia, transphobia, ableism, xenophobia, or casteism.",
"hint": "Transphobic behavior such as intentional misgendering and deadnaming is strictly prohibited. Promotion of \"conversion therapy\" is strictly prohibited. Criticism of governments and religions is permissible unless being used as a proxy for discrimination."
}
```
## 属性
### `id` {#id}
**描述:** 规则的标识符。\
**类型:** 字符串 (从整数转换而来，但不保证一定是数字)\
**版本历史:**\
3.4.0 - 添加
### `text` {#text}
**描述:** 需要遵守的规则内容。\
**类型:** 字符串 \
**版本历史:**\
3.4.0 - 添加
### `hint` {#hint}
**描述:** 规则的详细描述。\
**类型:** 字符串 \
**版本历史:**\
4.3.0 - 添加
## 参见
{{< page-relref ref="methods/instance#rules" caption="GET /api/v1/instance/rules" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/rule.rb" caption="app/models/rule.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/rule_serializer.rb" caption="app/serializers/rest/rule_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Rule" raw_link="/entities/Rule/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

219
content/zh-cn/entities/ScheduledStatus.md Normal file
View file

@ -0,0 +1,219 @@
---
title: ScheduledStatus
description: 表示一条计划在未来日期发布的嘟文。
menu:
docs:
parent: entities
aliases: [
"/entities/scheduledstatus",
"/entities/ScheduledStatus",
"/api/entities/scheduledstatus",
"/api/entities/ScheduledStatus",
]
---
## 示例
`POST /api/v1/statuses?status=test post&scheduled_at=2022-09-29` 返回：
```json
{
"id": "1",
"scheduled_at": "2022-09-29T00:00:00.000Z",
"params": {
"text": "test post",
"media_ids": null,
"sensitive": null,
"spoiler_text": null,
"visibility": null,
"language": null,
"scheduled_at": null,
"poll": null,
"idempotency": null,
"with_rate_limit": false,
"in_reply_to_id": null,
"application_id": 3
},
"media_attachments": []
}
```
`GET /api/v1/scheduled_statuses` 返回：
```json
{
"id": "1",
"scheduled_at": "2022-09-29T00:00:00.000Z",
"params": {
"poll": null,
"text": "test post",
"language": null,
"media_ids": null,
"sensitive": null,
"visibility": null,
"idempotency": null,
"scheduled_at": null,
"spoiler_text": null,
"application_id": 3,
"in_reply_to_id": null,
"with_rate_limit": false
},
"media_attachments": []
}
```
## 属性
### `id` {#id}
**描述:** 数据库中定时嘟文的 ID。\
**类型:** 字符串 (由整数转换而来，但不保证为数字)\
**版本历史:**\
2.7.0 - 添加
### `scheduled_at` {#scheduled_at}
**描述:** 嘟文计划被发布的 Unix 时间戳。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
2.7.0 - 添加
### `params` {#params}
**描述:** 调度嘟文时使用的参数，将在发布嘟文时使用。\
**类型:** 哈希\
**版本历史:**\
2.7.0 - 添加
#### `params[text]` {#params-text}
**描述:** 将用作嘟文内容的文本。\
**类型:** 字符串\
**版本历史:**\
2.7.0 - 添加
#### `params[poll]` {#params-poll}
**描述:** 要附加到嘟文的投票。\
**类型:** {{<nullable>}} 哈希\
**版本历史:**\
2.8.0 - 添加
##### `params[poll][options[]]` {#params-poll-options}
**描述:** 要使用的投票选项。\
**类型:** 字符串数组\
**版本历史:**\
2.8.0 - 添加
##### `params[poll][expires_in]` {#params-poll-expires_in}
**描述:** 投票在关闭前应持续多少秒。\
**类型:** 字符串（从整数转换）\
**版本历史:**\
2.8.0 - 添加
##### `params[poll][multiple]` {#params-poll-multiple}
**描述:** 投票是否允许多选。\
**类型:** {{<optional>}} 布尔值\
**版本历史:**\
2.8.0 - 添加
##### `params[poll][hide_totals]` {#params-poll-hide_totals}
**描述:** 投票是否应隐藏总票数，直到投票结束后再显示。\
**类型:** {{<optional>}} 布尔值\
**版本历史:**\
2.8.0 - 添加
#### `params[media_ids]` {#params-media_ids}
**描述:** 将附加到嘟文的 MediaAttachment 的 ID。\
**类型:** {{<nullable>}} 字符串数组\
**版本历史:**\
2.7.0 - 添加
#### `params[sensitive]` {#params-sensitive}
**描述:** 嘟文是否将被标记为敏感。\
**类型:** {{<nullable>}} 布尔值\
**版本历史:**\
2.7.0 - 添加
#### `params[spoiler_text]` {#params-spoiler_text}
**描述:** 嘟文的内容警告或摘要的文本。\
**类型:** {{<nullable>}} 字符串\
**版本历史:**\
2.7.0 - 添加
#### `params[visibility]` {#params-visibility}
**描述:** 嘟文发布后将具有的可见性。\
**类型:** 字符串 (可枚举 oneOf)\
`public` = 对所有人可见，显示在公共时间线中。\
`unlisted` = 对公众可见，但不包含在公共时间线中。\
`private` = 仅对关注者和任何被提及的用户可见。\
`direct` = 仅对被提及的用户可见。\
**版本历史:**\
2.7.0 - 添加
#### `params[in_reply_to_id]` {#params-in_reply_to_id}
**描述:** 将回复的嘟文的 ID。\
**类型:** {{<nullable>}} 整数\
**版本历史:**\
2.7.0 - 添加
#### `params[language]` {#params-language}
**描述:** 将用于嘟文的语言。\
**类型:** {{<nullable>}} 字符串 (ISO 639-1 双字母语言代码)\
**版本历史:**\
2.7.0 - 添加
#### `params[application_id]` {{%deprecated%}} {#params-application_id}
**描述:** 发布嘟文的应用的内部 ID。 仅为保留后向兼容性提供，可以忽略。\
**类型:** 整数\
**版本历史:**\
2.7.0 - 添加
#### `params[scheduled_at]` {#params-scheduled_at}
**描述:** 嘟文的定时发布时间。 这将为 null，因为嘟文只被计划一次。\
**类型:** {{<nullable>}} Null\
**版本历史:**\
2.7.0 - 添加
#### `params[idempotency]` {#params-idempotency}
**描述:** 幂等性键，用于防止重复发布嘟文。\
**类型:** {{<nullable>}} 字符串\
**版本历史:**\
2.7.0 - 添加
#### `params[with_rate_limit]` {{%deprecated%}} {#params-with_rate-limit}
**描述:** 嘟文创建是否受速率限制。 仅为保留后向兼容性提供，可以忽略。\
**类型:** 布尔值\
**版本历史:**\
2.7.0 - 添加
### `media_attachments` {#media_attachments}
**描述:** 发布嘟文时将附加的媒体。\
**类型:** [MediaAttachment]({{< relref "entities/MediaAttachment" >}}) 数组\
**版本历史:**\
2.7.0 - 添加
## 参见
{{< page-relref ref="methods/statuses#create" caption="POST /api/v1/statuses (带有 `scheduled_at` 参数)" >}}
{{< page-relref ref="methods/scheduled_statuses" caption="scheduled_statuses API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/scheduled_status_serializer.rb" caption="app/serializers/rest/scheduled_status_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="ScheduledStatus" raw_link="/entities/ScheduledStatus/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

120
content/zh-cn/entities/Search.md Normal file
View file

@ -0,0 +1,120 @@
---
title: Search
description: 表示搜索结果。
menu:
docs:
parent: entities
aliases: [
"/entities/results",
"/entities/Results",
"/entities/search",
"/entities/Search",
"/api/entities/results",
"/api/entities/Results",
"/api/entities/search",
"/api/entities/Search",
]
---
## 示例
关于 q=cats limit=2 的搜索结果采样片段
```json
{
"accounts": [
{
"id": "180744",
"username": "catstar",
"acct": "catstar@catgram.jp",
"display_name": "catstar",
// ...
},
{
"id": "214293",
"username": "catsareweird",
"acct": "catsareweird",
"display_name": "Cats Are Weird",
// ...
}
],
"statuses": [
{
"id": "103085519055545958",
"created_at": "2019-11-05T13:23:09.000Z",
// ...
"content": "<p>cats<br>cats never change</p>",
// ...
},
{
"id": "101068121469614510",
"created_at": "2018-11-14T06:31:48.000Z",
// ...
"spoiler_text": "Cats",
// ...
"content": "<p>Cats are inherently good at self-care. </p><p><a href=\"https://mspsocial.net/tags/cats\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>cats</span}</p>",
// ...
},
// ...
],
"hashtags": [
{
"name": "cats",
"url": "https://mastodon.social/tags/cats",
"history": [
{
"day": "1574553600",
"uses": "10",
"accounts": "9"
},
// ...
]
},
{
"name": "catsofmastodon",
"url": "https://mastodon.social/tags/catsofmastodon",
"history": [
{
"day": "1574553600",
"uses": "6",
"accounts": "5"
},
// ...
]
}
]
}
```
## 属性
### `accounts` {#accounts}
**描述:** 与给定关键词匹配的帐户。\
**类型:** [Account]({{< relref "entities/Account" >}}) 数组\
**版本历史:**\
1.1.0 - 添加
### `statuses` {#statuses}
**描述:** 与给定关键词匹配的嘟文。\
**类型:** [Status]({{< relref "entities/Status" >}}) 数组\
**版本历史:**\
1.1.0 - 添加
### `hashtags` {#hashtags}
**描述:** 与给定关键词匹配的话题标签。\
**类型:** [Tag]({{< relref "entities/Tag" >}}) 数组\
**版本历史:**\
1.1.0 - 添加\
2.4.1 - v1/search 已弃用，因为它返回字符串数组。添加了返回标签数组的 v2/search。\
3.0.0 - 删除了 v1/search
## 参见
{{< page-relref ref="methods/search" caption="搜索 API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/search_serializer.rb" caption="app/serializers/rest/search_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Search" raw_link="/entities/Search/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

397
content/zh-cn/entities/Status.md Normal file
View file

@ -0,0 +1,397 @@
---
title: Status
description: 表示帐户发布的嘟文。
menu:
docs:
parent: entities
aliases: [
"/entities/mention",
"/entities/Mention",
"/entities/status",
"/entities/Status",
"/api/entities/mention",
"/api/entities/Mention",
"/api/entities/status",
"/api/entities/Status",
]
---
## 示例
```json
{
"id": "103270115826048975",
"created_at": "2019-12-08T03:48:33.901Z",
"in_reply_to_id": null,
"in_reply_to_account_id": null,
"sensitive": false,
"spoiler_text": "",
"visibility": "public",
"language": "en",
"uri": "https://mastodon.social/users/Gargron/statuses/103270115826048975",
"url": "https://mastodon.social/@Gargron/103270115826048975",
"replies_count": 5,
"reblogs_count": 6,
"favourites_count": 11,
"favourited": false,
"reblogged": false,
"muted": false,
"bookmarked": false,
"content": "<p>&quot;I lost my inheritance with one wrong digit on my sort code&quot;</p><p><a href=\"https://www.theguardian.com/money/2019/dec/07/i-lost-my-193000-inheritance-with-one-wrong-digit-on-my-sort-code\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"ellipsis\">theguardian.com/money/2019/dec</span><span class=\"invisible\">/07/i-lost-my-193000-inheritance-with-one-wrong-digit-on-my-sort-code</span}</p>",
"reblog": null,
"application": {
"name": "Web",
"website": null
},
"account": {
"id": "1",
"username": "Gargron",
"acct": "Gargron",
"display_name": "Eugen",
"locked": false,
"bot": false,
"discoverable": true,
"group": false,
"created_at": "2016-03-16T14:34:26.392Z",
"note": "<p>Developer of Mastodon and administrator of mastodon.social. I post service announcements, development updates, and personal stuff.</p>",
"url": "https://mastodon.social/@Gargron",
"avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg",
"avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg",
"header": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png",
"header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png",
"followers_count": 322930,
"following_count": 459,
"statuses_count": 61323,
"last_status_at": "2019-12-10T08:14:44.811Z",
"emojis": [],
"fields": [
{
"name": "Patreon",
"value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span}",
"verified_at": null
},
{
"name": "Homepage",
"value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span}",
"verified_at": "2019-07-15T18:29:57.191+00:00"
}
]
},
"media_attachments": [],
"mentions": [],
"tags": [],
"emojis": [],
"card": {
"url": "https://www.theguardian.com/money/2019/dec/07/i-lost-my-193000-inheritance-with-one-wrong-digit-on-my-sort-code",
"title": "‘I lost my £193,000 inheritance – with one wrong digit on my sort code’",
"description": "When Peter Teich’s money went to another Barclays customer, the bank offered £25 as a token gesture",
"type": "link",
"author_name": "",
"author_url": "",
"provider_name": "",
"provider_url": "",
"html": "",
"width": 0,
"height": 0,
"image": null,
"embed_url": ""
},
"poll": null
}
```
## 属性
### `id` {#id}
**描述:** 数据库中嘟文的 ID。\
**类型:** 字符串（从整数转换而来，但不保证是数字）\
**版本历史:**\
0.1.0 - 添加
### `uri` {#uri}
**描述:** 用于联合的嘟文 URI。\
**类型:** 字符串\
**版本历史:**\
0.1.0 - 添加
### `created_at` {#created_at}
**描述:** 此嘟文创建的日期。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
0.1.0 - 添加
### `account` {#account}
**描述:** 撰写此嘟文的帐户。\
**类型:** [Account]({{< relref "entities/Account" >}})\
**版本历史:**\
0.1.0 - 添加
### `content` {#content}
**描述:** HTML 格式的嘟文内容。\
**类型:** 字符串 (HTML)\
**版本历史:**\
0.1.0 - 添加
### `visibility` {#visibility}
**描述:** 此嘟文的可见性。\
**类型:** 字符串（可枚举的 oneOf 类型）\
`public` = 公开可见，显示在公共时间线中。\
`unlisted` = 公开可见，但不包含在公共时间线中。\
`private` = 仅对关注者以及任何被提及的用户可见。\
`direct` = 仅对被提及的用户可见。\
**版本历史:**\
0.9.9 - 添加
### `sensitive` {#sensitive}
**描述:** 此嘟文是否标记为敏感内容？\
**类型:** 布尔值\
**版本历史:**\
0.9.9 - 添加
### `spoiler_text` {#spoiler_text}
**描述:** 主题或摘要，嘟文内容将被折叠在该文本之后，直到被展开为止。\
**类型:** 字符串\
**版本历史:**\
1.0.0 - 添加
### `media_attachments` {#media_attachments}
**描述:** 附加到此嘟文的媒体。\
**类型:** [MediaAttachment]({{< relref "entities/MediaAttachment" >}}) 数组\
**版本历史:**\
0.6.0 - 添加
### `application` {{%optional%}} {#application}
**描述:** 用于发布此嘟文的应用。\
**类型:** 哈希\
**版本历史:**\
0.9.9 - 添加
#### `application[name]` {#application-name}
**描述:** 发布此嘟文的应用的名称。\
**类型:** 字符串\
**版本历史:**\
0.9.9 - 添加
#### `application[website]` {#application-website}
**描述:** 与发布此嘟文的应用关联的网站。\
**类型:** {{<nullable>}} 字符串 (URL) 或 null\
**版本历史:**\
0.9.9 - 添加\
3.5.1 - this property is now nullable
### `mentions` {#mentions}
**描述:** 在嘟文内容中提及的用户。\
**类型:** [Status::Mention](#Mention) 数组\
**版本历史:**\
0.6.0 - 添加
### `tags` {#tags}
**描述:** 在嘟文内容中使用的话题标签。\
**类型:** [Status::Tag](#Tag) 数组\
**版本历史:**\
0.6.0 - 添加
### `emojis` {#emojis}
**描述:** 渲染嘟文内容时要使用的自定义表情。\
**类型:** [CustomEmoji]({{< relref "entities/CustomEmoji" >}}) 数组\
**版本历史:**\
2.0.0 - 添加
### `reblogs_count` {#reblogs_count}
**描述:** 此嘟文的被转发数。\
**类型:** 整数\
**版本历史:**\
0.1.0 - 添加
### `favourites_count` {#favorites_count}
**描述:** 此嘟文已收到的点赞数。\
**类型:** 整数\
**版本历史:**\
0.1.0 - 添加
### `replies_count` {#replies_count}
**描述:** 此嘟文已收到的回复数。\
**类型:** 整数\
**版本历史:**\
2.5.0 - 添加
### `url` {#url}
**描述:** 指向嘟文的 HTML 表示的链接。\
**类型:** {{<nullable>}} 字符串 (URL) 或 null\
**版本历史:**\
0.1.0 - 添加
### `in_reply_to_id` {#in_reply_to_id}
**描述:** 要回复的嘟文的 ID。\
**类型:** {{<nullable>}} 字符串（从整数转换而来，但不保证是数字）或 null\
**版本历史:**\
0.1.0 - 添加
### `in_reply_to_account_id` {#in_reply_to_account_id}
**描述:** 撰写要回复的嘟文的帐户的 ID。\
**类型:** {{<nullable>}} 字符串（从整数转换而来，但不保证是数字）或 null\
**版本历史:**\
0.1.0 - 添加
### `reblog` {#reblog}
**描述:** 要转发的嘟文。\
**类型:** {{<nullable>}} [Status]({{< relref "entities/status" >}}) 或 null\
**版本历史:**\
0.1.0 - 添加
### `poll` {#poll}
**描述:** 附加到嘟文的投票。\
**类型:** {{<nullable>}} [Poll]({{< relref "entities/Poll" >}}) 或 null\
**版本历史:**\
2.8.0 - 添加
### `card` {#card}
**描述:** 嘟文内容中包含的链接的预览卡片。\
**类型:** {{<nullable>}} [PreviewCard]({{< relref "entities/PreviewCard" >}}) 或 null\
**版本历史:**\
2.6.0 - 添加
### `language` {#language}
**描述:** 此嘟文的主要语言。\
**类型:** {{<nullable>}} 字符串（ISO 639 第 1 部分两位字母语言代码）或 null\
**版本历史:**\
1.4.0 - 添加
### `text` {#text}
**描述:** 嘟文的原始纯文本。当嘟文被删除时返回，而不是返回 `content`，因此用户可以从源文本中重新起草，而无需客户端从 HTML 内容中逆向得到原始文本。\
**类型:** {{<nullable>}} 字符串或 null\
**版本历史:**\
2.9.0 - 添加
### `edited_at` {#edited_at}
**描述:** 上次编辑嘟文的时间戳。\
**类型:** {{<nullable>}} ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
3.5.0 - 添加
### `favourited` {{%optional%}} {#favourited}
**描述:** 如果当前令牌具有授权用户：该授权用户是否喜欢了此嘟文？\
**类型:** 布尔值\
**版本历史:**\
0.1.0 - 添加
### `reblogged` {{%optional%}} {#reblogged}
**描述:** 如果当前令牌具有授权用户：该授权用户是否已转发此嘟文？\
**类型:** 布尔值\
**版本历史:**\
0.1.0 - 添加
### `muted` {{%optional%}} {#muted}
**描述:** 如果当前令牌具有授权用户：该授权用户是否隐藏了有关此嘟文的通知？\
**类型:** 布尔值\
**版本历史:**\
1.4.0 - 添加
### `bookmarked` {{%optional%}} {#bookmarked}
**描述:** 如果当前令牌具有授权用户：该授权用户是否已将此嘟文添加到书签？\
**类型:** 布尔值\
**版本历史:**\
3.1.0 - 添加
### `pinned` {{%optional%}} {#pinned}
**描述:** 如果当前令牌具有授权用户：该授权用户是否已置顶此嘟文？仅当嘟文可置顶时才会返回。\
**类型:** 布尔值\
**版本历史:**\
1.6.0 - 添加
### `filtered` {{%optional%}} {#filtered}
**描述:** 如果当前令牌具有授权用户：此嘟文命中的过滤规则和关键词。\
**类型:** [FilterResult]({{< relref "entities/FilterResult" >}}) 数组\
**版本历史:**\
4.0.0 - 添加
## Status::Mention 属性 {#Mention}
### `id` {#Mention-id}
**描述:** 被提及用户的帐户 ID。\
**类型:** 字符串（从整数类型转换而来，但不保证是数字）\
**版本历史:**\
0.6.0 - 添加
### `username` {#Mention-username}
**描述:** 被提及用户的用户名。\
**类型:** 字符串\
**版本历史:**\
0.6.0 - 添加
### `url` {#Mention-url}
**描述:** 被提及用户的账户位置。\
**类型:** 字符串 (URL)\
**版本历史:**\
0.6.0 - 添加
### `acct` {#Mention-acct}
**描述:** 被提及用户的 webfinger acct: URI。对于本站用户，等同于 `username`，对于外站用户，等同于 `username@domain`。\
**类型:** 字符串\
**版本历史:**\
0.6.0 - 添加
## Status::Tag 属性 {#Tag}
### `name` {#Tag-name}
**描述:** # 符号后的话题标签名。\
**类型:** 字符串\
**版本历史:**\
0.9.0 - 添加
### `url` {#Tag-url}
**描述:** 指向实例上话题标签的链接。\
**类型:** 字符串 (URL)\
**版本历史:**\
0.9.0 - 添加
## 参见
{{< page-relref ref="methods/accounts#statuses" caption="GET /api/v1/accounts/:id/statuses" >}}
{{< page-relref ref="methods/search#v2" caption="POST /api/v2/search/" >}}
{{< page-relref ref="methods/statuses" caption="statuses methods" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/status_serializer.rb" caption="app/serializers/rest/status_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Status" raw_link="/entities/Status/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

146
content/zh-cn/entities/StatusEdit.md Normal file
View file

@ -0,0 +1,146 @@
---
title: StatusEdit
description: 表示已被编辑的嘟文的一个修订版本。
menu:
docs:
parent: entities
aliases: [
"/entities/statusedit",
"/entities/StatusEdit",
"/api/entities/statusedit",
"/api/entities/StatusEdit",
]
---
## 示例
```json
{
"content": "<p>this is a status that has been edited three times. this time a poll has been added.</p>",
"spoiler_text": "",
"sensitive": false,
"created_at": "2022-09-05T00:03:32.480Z",
"poll": {
"options": [
{
"title": "cool"
},
{
"title": "uncool"
},
{
"title": "spiderman (this option has been changed)"
}
]
},
"account": {
"id": "14715",
"username": "trwnh",
"acct": "trwnh",
"display_name": "infinite love ⴳ",
// ...
},
"media_attachments": [],
"emojis": []
}
```
## 属性
### `content` {#content}
**描述:** 此修订版本中嘟文的内容。\
**类型:** 字符串 (HTML)\
**版本历史:**\
3.5.0 - 添加
**版本历史：**\
3.5.0 - 添加
### `spoiler_text` {#spoiler_text}
**描述:** 此修订版本中的主题或内容警告。\
**类型:** 字符串 (HTML)\
**版本历史:**\
3.5.0 - 添加
**版本历史：**\
3.5.0 - 添加
### `sensitive` {#sensitive}
**描述:** 此修订版本中嘟文是否标记为敏感。\
**类型:** 布尔值\
**版本历史:**\
3.5.0 - 添加
**版本历史：**\
3.5.0 - 添加
### `created_at` {#created_at}
**描述:** 发布此修订版本的时间戳。\
**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\
**版本历史:**\
3.5.0 - 添加
**版本历史：**\
3.5.0 - 添加
### `account` {#account}
**描述:** 发布此修订版本的帐户。\
**类型:** [Account]({{<relref "entities/Account">}})\
**版本历史:**\
3.5.0 - 添加
**版本历史：**\
3.5.0 - 添加
### `poll` {{%optional%}} {#poll}
**描述:** 此修订版本中的投票。请注意，更改投票选项的编辑将被合并为一次编辑，因为此操作会重置投票。\
**类型:** Hash\
**版本历史:**\
3.5.0 - 添加
**版本历史：**\
3.5.0 - 添加
#### `poll.options[]` {#poll-options}
**描述:** 此修订版本中的投票选项。\
**类型:** 哈希值的数组\
**版本历史:**\
3.5.0 - 添加
**版本历史：**\
3.5.0 - 添加
#### `poll.options[].title` {#poll-options-title}
**描述:** 投票选项的文本。\
**类型:** 字符串\
**版本历史:**\
3.5.0 - 添加
**版本历史：**\
3.5.0 - 添加
### `media_attachments` {#media_attachments}
**描述:** 此修订版本中的媒体附件。\
**类型:** Array of [MediaAttachment]({{<relref "entities/MediaAttachment">}})\
**版本历史:**\
3.5.0 - 添加
**版本历史：**\
3.5.0 - 添加
### `emojis` {#emojis}
**描述:** 当前修订版本中使用的任何自定义表情。\
**类型:** Array of [CustomEmoji]({{<relref "entities/CustomEmoji">}})\
**版本历史:**\
3.5.0 - 添加
**版本历史：**\
3.5.0 - 添加
## 另请参阅
{{< page-relref ref="methods/statuses#history" caption="GET /api/v1/statuses/:id/history" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/status_edit_serializer.rb" caption="app/serializers/rest/status_edit_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="StatusEdit" raw_link="/entities/StatusEdit/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

54
content/zh-cn/entities/StatusSource.md Normal file
View file

@ -0,0 +1,54 @@
---
title: StatusSource
description: 以纯文本形式表示嘟文的来源。
menu:
docs:
parent: entities
aliases: [
"/entities/statussource",
"/entities/StatusSource",
"/api/entities/statussource",
"/api/entities/StatusSource",
]
---
## 示例
```json
{
"id": "108942703571991143",
"text": "this is a status that will be edited",
"spoiler_text": ""
}
```
## 属性
### `id` {#id}
**描述:** 嘟文在数据库中的 ID。\
**类型:** 字符串 (从整数转换而来，但不保证一定为数字)\
**版本历史:**\
3.5.0 - 新增
### `text` {#text}
**描述:** 用于构成嘟文的纯文本。\
**类型:** 字符串\
**版本历史:**\
3.5.0 - 新增
### `spoiler_text` {#spoiler_text}
**描述:** 用于构成嘟文的主题或内容警告的纯文本。\
**类型:** 字符串\
**版本历史:**\
3.5.0 - 新增
## 参见
{{< page-relref ref="methods/statuses#source" caption="GET /api/v1/statuses/:id/source" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/status_source_serializer.rb" caption="app/serializers/rest/status_source_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="StatusSource" raw_link="/entities/StatusSource/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

71
content/zh-cn/entities/Suggestion.md Normal file
View file

@ -0,0 +1,71 @@
---
title: Suggestion
description: 表示一个推荐关注的帐户以及推荐的原因。
menu:
docs:
parent: entities
aliases: [
"/entities/suggestion",
"/entities/Suggestion",
"/api/entities/suggestion",
"/api/entities/Suggestion",
]
---
## 示例
```json
{
"source": "staff",
"account": {
"id": "109031732217496096",
"username": "alice",
"acct": "alice",
// ...
}
}
```
## 属性
### `source` {#source}
**描述：** 推荐此帐户的原因。\
**类型：** 字符串 (可枚举的 oneOf)\
`staff` = 此帐户由你的实例的管理团队手动推荐\
`past_interactions` = 你之前与此帐户互动过\
`global` = 此帐户在过去 30 天内拥有大量的转嘟、喜欢或活跃的本站关注者\
**版本历史：**\
3.4.0 - 添加\
4.3.0 - 已弃用，请改用 `sources`
### `sources` {#sources}
**描述：** 推荐此帐户的一系列原因。 这取代了 `source`\
**类型：** 字符串数组 (可枚举的 oneOf)\
`featured` = 此帐户由你的管理团队手动推荐。 相当于 `source` 的 `staff` 值\
`most_followed` = 此帐户拥有许多活跃的本站关注者\
`most_interactions` = 此帐户在过去 30 天内有很多转嘟和喜欢\
`similar_to_recently_followed` = 此帐户的账户与你最近关注的帐户相似\
`friends_of_friends` = 此帐户被你关注的人关注\
**版本历史：**\
4.3.0 - 添加
### `account` {#account}
**描述：** 推荐关注的帐户。\
**类型：** [帐户]({{< relref "entities/Account" >}})\
**版本历史：**\
3.4.0 - 添加
## 参见
{{< page-relref ref="methods/suggestions#v2" caption="GET /api/v2/suggestions" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/suggestion_serializer.rb" caption="app/serializers/rest/suggestion_serializer.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/account_suggestions.rb" caption="app/models/account_suggestions.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/account_suggestions/" caption="app/models/account_suggestions/" >}}
{{< translation-status-zh-cn raw_title="Suggestion" raw_link="/entities/Suggestion/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

199
content/zh-cn/entities/Tag.md Normal file
View file

@ -0,0 +1,199 @@
---
title: Tag
description: 表示嘟文内容中使用的话题标签。
menu:
docs:
parent: entities
aliases: [
"/entities/tag",
"/entities/Tag",
"/api/entities/tag",
"/api/entities/Tag",
]
---
## 示例
```json
{
"name": "nowplaying",
"url": "https://mastodon.social/tags/nowplaying",
"history": [
{
"day": "1574553600",
"uses": "200",
"accounts": "31"
},
{
"day": "1574467200",
"uses": "272",
"accounts": "39"
},
{
"day": "1574380800",
"uses": "345",
"accounts": "40"
},
{
"day": "1574294400",
"uses": "366",
"accounts": "46"
},
{
"day": "1574208000",
"uses": "226",
"accounts": "32"
},
{
"day": "1574121600",
"uses": "217",
"accounts": "42"
},
{
"day": "1574035200",
"uses": "214",
"accounts": "34"
}
],
"following": false
}
```
## 属性
### `name` {#name}
**描述:** # 符号后的话题标签名。\
**类型:** 字符串\
**版本历史:**\
0.9.0 - 添加
### `url` {#url}
**描述:** 实例上话题标签的链接。\
**类型:** 字符串 (URL)\
**版本历史:**\
0.9.0 - 添加
### `history` {#history}
**描述:** 给定时间段（通常为过去一周）的使用统计信息。\
**类型:** 哈希值的数组\
**版本历史:**\
2.4.1 - 添加
#### `history[][day]` {#history-day}
**描述:** 给定时间段午夜的 UNIX 时间戳。\
**类型:** 字符串 (UNIX 时间戳)\
**版本历史:**\
2.4.1 - 添加
#### `history[][uses]` {#history-uses}
**描述:** 该话题标签在当前时段被使用的次数。\
**类型:** 字符串 (从整数转换而来)\
**版本历史:**\
2.4.1 - 添加
#### `history[][accounts]` {#history-accounts}
**描述:** 当前时段使用该话题标签的帐户总数。\
**类型:** 字符串 (从整数转换而来)\
**版本历史:**\
2.4.1 - 添加
### `following` {{%optional%}} {#following}
**描述:** 当前令牌的授权用户是否正在关注此话题标签。\
**类型:** 布尔值\
**版本历史:**\
4.0.0 - 添加
## Admin::Tag 属性 {#admin}
```json
{
"name": "caturday",
"url": "https://mastodon.example/tags/caturday",
"history": [
{
"day": "1669507200",
"accounts": "53",
"uses": "56"
},
{
"day": "1669420800",
"accounts": "142",
"uses": "171"
},
{
"day": "1669334400",
"accounts": "11",
"uses": "11"
},
{
"day": "1669248000",
"accounts": "8",
"uses": "9"
},
{
"day": "1669161600",
"accounts": "8",
"uses": "20"
},
{
"day": "1669075200",
"accounts": "11",
"uses": "11"
},
{
"day": "1668988800",
"accounts": "17",
"uses": "22"
}
],
"id": "802",
"trendable": true,
"usable": true,
"requires_review": false
}
```
### `id` {#id}
**描述:** 话题标签在数据库中的 ID。\
**类型:** 字符串 (从整数转换而来，但不保证是数字)\
**版本历史:**\
3.5.0 - 添加
### `trendable` {#trendable}
**描述:** 该话题标签是否已被批准成为热门话题标签。\
**类型:** 布尔值\
**版本历史:**\
3.5.0 - 添加
### `usable` {#usable}
**描述:** 是否未禁用自动链接到此话题标签。\
**类型:** 布尔值\
**版本历史:**\
3.5.0 - 添加
### `requires_review` {#requires_review}
**描述:** 该话题标签是否尚未被批准成为成为热门话题标签。\
**类型:** 布尔值\
**版本历史:**\
3.5.0 - 添加
## 参见
{{< page-relref ref="entities/Search#tags" caption="搜索（`tags` 属性）" >}}
{{< page-relref ref="methods/tags" caption="tags API 方法" >}}
{{< page-relref ref="methods/featured_tags#suggestions" caption="GET /api/v1/featured_tags/suggestions" >}}
{{< translation-status-zh-cn raw_title="Tag" raw_link="/entities/Tag/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

66
content/zh-cn/entities/Token.md Normal file
View file

@ -0,0 +1,66 @@
---
title: Token
description: 表示用于与 API 进行身份验证和执行操作的 OAuth 令牌。
menu:
docs:
parent: entities
aliases: [
"/entities/token",
"/entities/Token",
"/api/entities/token",
"/api/entities/Token",
]
---
## 示例
```json
{
"access_token": "ZA-Yj3aBD8U8Cm7lKUp-lm9O9BmDgdhHzDeqsY8tlL0",
"token_type": "Bearer",
"scope": "read write follow push",
"created_at": 1573979017
}
```
## 属性
### `access_token` {#access_token}
**描述:** 用于授权的 OAuth 令牌。\
**类型:** 字符串\
**版本历史:**\
0.1.0 - 添加
### `token_type` {#token_type}
**描述:** OAuth 令牌类型。 Mastodon 使用 `Bearer` 令牌。\
**类型:** 字符串\
**版本历史:**\
0.1.0 - 添加
### `scope` {#scope}
**描述:** 此令牌授予的 OAuth 作用域，以空格分隔。\
**类型:** 字符串\
**版本历史:**\
0.1.0 - 添加
### `created_at` {#created_at}
**描述:** 令牌生成的时间。\
**类型:** Number (UNIX 时间戳)\
**版本历史:**\
0.1.0 - 添加
## 另请参阅
{{< page-relref ref="oauth-scopes" caption="OAuth 作用域" >}}
{{< page-relref ref="methods/oauth" caption="oauth 方法" >}}
{{< page-ref page="client/token" >}}
{{< page-ref page="client/authorized" >}}
{{< translation-status-zh-cn raw_title="Token" raw_link="/entities/Token/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

147
content/zh-cn/entities/Translation.md Normal file
View file

@ -0,0 +1,147 @@
---
title: Translation
description: 表示机器翻译某些嘟文内容的结果
menu:
docs:
parent: entities
aliases: [
"/api/entities/Translation",
"/api/entities/translation",
]
---
## 示例
包含内容警告和媒体的嘟文翻译
```json
{
"content": "<p>Hello world</p>",
"spoiler_text": "Greatings ahead",
"media_attachments": [
{
"id": "22345792",
"description": "Status author waving at the camera"
}
],
"poll": null,
"detected_source_language": "es",
"provider": "DeepL.com"
}
```
包含投票的嘟文翻译：
```json
{
"content": "<p>Should I stay or should I go?</p>",
"spoiler_text": "",
"media_attachments": [],
"poll": {
"id": "34858",
"options": [
{
"title": "Stay"
},
{
"title": "Go"
}
]
},
"detected_source_language": "ja",
"provider": "DeepL.com"
}
```
## 属性
### `content` {#content}
**描述:** 嘟文的HTML编码的翻译内容。\
**类型:** 字符串 (HTML)\
**版本历史:**\
4.0.0 - 添加
### `spoiler_text` {#spoiler_text}
**描述:** 嘟文翻译后的内容警告。\
**类型:** 字符串\
**版本历史:**\
4.2.0 - 添加
### `poll` {{%optional%}} {#poll}
**描述:** 嘟文翻译后的投票。\
**类型:** [Translation::Poll](#Poll)\
**版本历史:**\
4.2.0 - 添加
### `media_attachments` {#media_attachments}
**描述:** 嘟文翻译后的媒体描述。\
**类型:** [Translation::Attachment](#Attachment) 的数组\
**版本历史:**\
4.2.0 - 添加
### `detected_source_language` {#detected_source_language}
**描述:** 源文本的语言，由机器翻译提供商自动检测。\
**类型:** 字符串 (ISO 639 语言代码)\
**版本历史:**\
4.0.0 - 添加
### `provider` {#provider}
**描述:** 机器翻译提供商。
**类型:** 字符串\
**版本历史:**\
4.0.0 - 添加
## Translation::Poll 属性 {#Poll}
### `id` {#Poll-id}
**描述:** 投票的 ID。\
**类型:** 字符串（从整数转换而来，但不保证是数字）\
**版本历史:**\
4.2.0 - 添加
### `options` {#Poll-options}
**描述:** 翻译后的投票选项。\
**类型:** [Translation::Poll::Option](#Option) 的数组\
**版本历史:**\
4.2.0 - 添加
## Translation::Poll::Option 属性 {#Option}
### `title` {#Option-title}
**描述:** 投票选项的翻译后的标题。\
**类型:** 字符串\
**版本历史:**\
4.2.0 - 添加
## Translation::Attachment 属性 {#Attachment}
### `id` {#Attachment-id}
**描述:** 附件的 id。\
**类型:** 字符串（从整数转换而来，但不保证是数字）\
**版本历史:**\
4.2.0 - 添加
### `description` {#Attachment-description}
**描述:** 媒体附件翻译后的描述。\
**类型:** 字符串\
**版本历史:**\
4.2.0 - 添加
## 参见
{{< page-relref ref="methods/statuses#translate" caption="POST /api/v1/statuses/:id/translate" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/translation_serializer.rb" caption="app/serializers/rest/translation_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="Translation" raw_link="/entities/Translation/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

91
content/zh-cn/entities/V1_Filter.md Normal file
View file

@ -0,0 +1,91 @@
---
title: V1::Filter
description: 表示用户自定义的过滤规则，用于确定哪些嘟文不应向用户显示。包含单个关键词或短语。
menu:
docs:
parent: entities
aliases: [
"/entities/v1_filter/",
"/entities/V1_Filter",
"/api/entities/v1_filter/",
"/api/entities/V1_Filter",
]
---
## 示例
```json
{
"id": "8449",
"phrase": "test",
"context": [
"home",
"notifications",
"public",
"thread"
],
"whole_word": false,
"expires_at": "2019-11-26T09:08:06.254Z",
"irreversible": true
}
```
## 属性
### `id` {#id}
**描述:** 数据库中过滤规则的 ID。\
**类型:** 字符串 (从整数转换而来，但不保证一定是数字)\
**版本历史:**\
2.4.3 - 添加
### `phrase` {#phrase}
**描述:** 要过滤的文本。\
**类型:** 字符串\
**版本历史:**\
2.4.3 - 添加
### `context` {#context}
**描述:** 过滤规则的应用场景。\
**类型:** 字符串数组 (可枚举的 anyOf)\
`home` = 首页时间线和列表\
`notifications` = 通知时间线\
`public` = 公共时间线\
`thread` = 展开后的嘟文串\
`account` = 查看账户时\
**版本历史:**\
2.4.3 - 添加\
3.1.0 - 添加 `account`
### `expires_at` {#expires_at}
**描述:** 过滤规则应不再生效的时间。\
**类型:** {{<nullable>}} 字符串 ([Datetime](/api/datetime-format#datetime))，如果过滤规则永不过期，则为 null\
**版本历史:**\
2.4.3 - 添加
### `irreversible` {#irreversible}
**描述:** 实例是否应该删除首页和通知中该过滤规则命中的实体？请参阅[过滤规则实现指引]({{< relref "api/guidelines#filters" >}})。\
**类型:** 布尔值\
**版本历史:**\
2.4.3 - 添加
### `whole_word` {#whole_word}
**描述:** 过滤规则是否应考虑单词边界？请参阅[过滤规则实现指引]({{< relref "api/guidelines#filters" >}})。\
**类型:** 布尔值\
**版本历史:**\
2.4.3 - 添加
## 另请参阅
{{< page-relref ref="api/guidelines#filters" caption="过滤规则实现指引" >}}
{{< page-relref ref="methods/filters#v1" caption="v1 过滤规则 API" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/v1/filter_serializer.rb" caption="app/serializers/rest/v1/filter_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="V1::Filter" raw_link="/entities/V1_Filter/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

421
content/zh-cn/entities/V1_Instance.md Normal file
View file

@ -0,0 +1,421 @@
---
title: V1::Instance
description: 表示在此域名上运行的 Mastodon 软件实例。
menu:
docs:
parent: entities
aliases: [
"/entities/v1_instance",
"/entities/V1_Instance",
"/api/entities/v1_instance",
"/api/entities/V1_Instance",
]
---
## 示例
```json
{
"uri":"mastodon.social",
"title":"Mastodon",
"short_description":"The original server operated by the Mastodon gGmbH non-profit",
"description":"",
"email":"staff@mastodon.social",
"version":"3.5.3",
"urls":{
"streaming_api":"wss://mastodon.social"
},
"stats":{
"user_count":812303,
"status_count":38151616,
"domain_count":25255
},
"thumbnail":"https://files.mastodon.social/site_uploads/files/000/000/001/original/vlcsnap-2018-08-27-16h43m11s127.png",
"languages":[
"en"
],
"registrations":false,
"approval_required":false,
"invites_enabled":true,
"configuration":{
"statuses":{
"max_characters":500,
"max_media_attachments":4,
"characters_reserved_per_url":23
},
"media_attachments":{
"supported_mime_types":[
"image/jpeg",
"image/png",
"image/gif",
"image/webp",
"video/webm",
"video/mp4",
"video/quicktime",
"video/ogg",
"audio/wave",
"audio/wav",
"audio/x-wav",
"audio/x-pn-wave",
"audio/vnd.wave",
"audio/ogg",
"audio/vorbis",
"audio/mpeg",
"audio/mp3",
"audio/webm",
"audio/flac",
"audio/aac",
"audio/m4a",
"audio/x-m4a",
"audio/mp4",
"audio/3gpp",
"video/x-ms-asf"
],
"image_size_limit":10485760,
"image_matrix_limit":16777216,
"video_size_limit":41943040,
"video_frame_rate_limit":60,
"video_matrix_limit":2304000
},
"polls":{
"max_options":4,
"max_characters_per_option":50,
"min_expiration":300,
"max_expiration":2629746
}
},
"contact_account":{
"id":"1",
"username":"Gargron",
"acct":"Gargron",
"display_name":"Eugen",
"locked":false,
"bot":false,
"discoverable":true,
"group":false,
"created_at":"2016-03-16T00:00:00.000Z",
"note":"\u003cp\u003eFounder, CEO and lead developer \u003cspan class=\"h-card\"\u003e\u003ca href=\"https://mastodon.social/@Mastodon\" class=\"u-url mention\"\u003e@\u003cspan\u003eMastodon\u003c/span\u003e\u003c/a\u003e\u003c/span\u003e, Germany.\u003c/p\u003e",
"url":"https://mastodon.social/@Gargron",
"avatar":"https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg",
"avatar_static":"https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg",
"header":"https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg",
"header_static":"https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg",
"followers_count":118944,
"following_count":305,
"statuses_count":72309,
"last_status_at":"2022-08-24",
"emojis":[
],
"fields":[
{
"name":"Patreon",
"value":"\u003ca href=\"https://www.patreon.com/mastodon\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"\u003e\u003cspan class=\"invisible\"\u003ehttps://www.\u003c/span\u003e\u003cspan class=\"\"\u003epatreon.com/mastodon\u003c/span\u003e\u003cspan class=\"invisible\"\u003e\u003c/span\u003e\u003c/a\u003e",
"verified_at":null
}
]
},
"rules":[
{
"id":"1",
"text":"Sexually explicit or violent media must be marked as sensitive when posting"
},
{
"id":"2",
"text":"No racism, sexism, homophobia, transphobia, xenophobia, or casteism"
},
{
"id":"3",
"text":"No incitement of violence or promotion of violent ideologies"
},
{
"id":"4",
"text":"No harassment, dogpiling or doxxing of other users"
},
{
"id":"5",
"text":"No content illegal in Germany"
},
{
"id":"7",
"text":"Do not share intentionally false or misleading information"
}
]
}
```
## 属性
### `uri` {#uri}
**描述:** 实例的域名。\
**类型:** 字符串\
**版本历史:**\
1.1.0 - 添加
### `title` {#title}
**描述:** 网站的标题。\
**类型:** 字符串\
**版本历史:**\
1.1.0 - 添加
### `short_description` {#short_description}
**描述:** 由管理员定义的简短纯文本描述。\
**类型:** 字符串\
**版本历史:**\
2.9.2 - 添加
### `description` {#description}
**描述:** 允许使用 HTML 的 Mastodon 站点描述。\
**类型:** 字符串\
**版本历史:**\
1.1.0 - 添加
### `email` {#email}
**描述:** 可供任何咨询联系的电子邮件地址。\
**类型:** 字符串\
**版本历史:**\
1.1.0 - 添加
### `version` {#version}
**描述:** 实例上安装的 Mastodon 版本。\
**类型:** 字符串\
**版本历史:**\
1.3.0 - 添加
### `urls` {#urls}
**描述:** 客户端应用感兴趣的 URL。\
**类型:** Hash\
**版本历史:**\
1.4.2 - 添加
#### `urls[streaming_api]` {#streaming_api}
**描述:** 用于连接到流式 API 的 Websockets URL。\
**类型:** 字符串 (URL)\
**版本历史:**\
1.4.2 - 添加
### `stats` {#stats}
**描述:** 关于实例包含多少信息的统计数据。\
**类型:** Hash\
**版本历史:**\
1.6.0 - 添加
#### `stats[user_count]` {#user_count}
**描述:** 此实例上的用户总数。\
**类型:** 整数\
**版本历史:**\
1.6.0 - 添加
#### `stats[status_count]` {#status_count}
**描述:** 此实例上的嘟文总数。\
**类型:** 整数\
**版本历史:**\
1.6.0 - 添加
#### `stats[domain_count]` {#domain_count}
**描述:** 此实例发现的域名总数。\
**类型:** 整数\
**版本历史:**\
1.6.0 - 添加
### `thumbnail` {#thumbnail}
**描述:** 网站的横幅图片。\
**类型:** {{<nullable>}} 字符串 (URL)\
**版本历史:**\
1.6.1 - 添加
### `languages` {#languages}
**描述:** 网站及其工作人员的主要语言。\
**类型:** Array of String (ISO 639-1 双字母代码)\
**版本历史:**\
2.3.0 - 添加
### `registrations` {#registrations}
**描述:** 是否允许注册。\
**类型:** 布尔值\
**版本历史:**\
2.7.2 - 添加
### `approval_required` {#approval_required}
**描述:** 注册是否需要管理员批准。\
**类型:** 布尔值\
**版本历史:**\
2.9.2 - 添加
### `invites_enabled` {#invites_enabled}
**描述:** 是否启用了邀请。\
**类型:** 布尔值\
**版本历史:**\
3.1.4 - 添加
### `configuration` {#configuration}
**描述:** 此网站的配置值和限制。\
**类型:** Hash\
**版本历史:**\
3.4.2 - 添加
#### `configuration[accounts]` {#accounts}
**描述:** 与帐户相关的限制。\
**类型:** Hash\
**版本历史:**\
4.0.0 - 添加
##### `configuration[accounts][max_featured_tags]` {#max_featured_tags}
**描述:** 每个帐户允许的最大特色话题标签数。\
**类型:** 整数\
**版本历史:**\
4.0.0 - 添加
#### `configuration[statuses]` {#statuses}
**描述:** 与发布嘟文相关的限制。\
**类型:** Hash\
**版本历史:**\
3.4.2 - 添加
##### `configuration[statuses][max_characters]` {#max_characters}
**描述:** 每条嘟文允许的最大字符数。\
**类型:** 整数\
**版本历史:**\
3.4.2 - 添加
##### `configuration[statuses][max_media_attachments]` {#max_media_attachments}
**描述:** 可以添加到嘟文的媒体附件的最大数量。\
**类型:** 整数\
**版本历史:**\
3.4.2 - 添加
##### `configuration[statuses][characters_reserved_per_url]` {#characters_reserved_per_url}
**描述:** 嘟文中的每个 URL 将被假定占据的字符数。\
**类型:** 整数\
**版本历史:**\
3.4.2 - 添加
#### `configuration[media_attachments]` {#media_attachments}
**描述:** 有关可接受的媒体附件格式范围的提示。\
**类型:** Hash\
**版本历史:**\
3.4.2 - 添加
##### `configuration[media_attachments][supported_mime_types]` {#supported_mime_types}
**描述:** 包含可以上传的 MIME 类型。\
**类型:** 字符串数组\
**版本历史:**\
3.4.2 - 添加
##### `configuration[media_attachments][image_size_limit]` {#image_size_limit}
**描述:** 所有上传图像的最大大小（以字节为单位）。\
**类型:** 整数\
**版本历史:**\
3.4.2 - 添加
##### `configuration[media_attachments][image_matrix_limit]` {#image_matrix_limit}
**描述:** 图像上传的最大像素数（宽度乘以高度）。\
**类型:** 整数\
**版本历史:**\
3.4.2 - 添加
##### `configuration[media_attachments][video_size_limit]` {#video_size_limit}
**描述:** 所有上传视频的最大大小（以字节为单位）。\
**类型:** 整数\
**版本历史:**\
3.4.2 - 添加
##### `configuration[media_attachments][video_frame_rate_limit]` {#video_frame_rate_limit}
**描述:** 所有上传视频的最大帧速率。\
**类型:** 整数\
**版本历史:**\
3.4.2 - 添加
##### `configuration[media_attachments][video_matrix_limit]` {#video_matrix_limit}
**描述:** 视频上传的最大像素数（宽度乘以高度）。\
**类型:** 整数\
**版本历史:**\
3.4.2 - 添加
#### `configuration[polls]` {#polls}
**描述:** 与投票相关的限制。\
**类型:** Hash\
**版本历史:**\
3.4.2 - 添加
##### `configuration[polls][max_options]` {#max_options}
**描述:** 每次投票最多允许的选项数。\
**类型:** 整数\
**版本历史:**\
3.4.2 - 添加
##### `configuration[polls][max_characters_per_option]` {#max_characters_per_option}
**描述:** 每个投票选项允许包含的字符数。\
**类型:** 整数\
**版本历史:**\
3.4.2 - 添加
##### `configuration[polls][min_expiration]` {#min_expiration}
**描述:** 允许的最短投票持续时间（以秒为单位）。\
**类型:** 整数\
**版本历史:**\
3.4.2 - 添加
##### `configuration[polls][max_expiration]` {#max_expiration}
**描述:** 允许的最长投票持续时间（以秒为单位）。\
**类型:** 整数\
**版本历史:**\
3.4.2 - 添加
### `contact_account` {#contact_account}
**描述:** 可供联系的用户，作为 `email` 的替代方案。\
**类型:** {{<nullable>}} [Account]({{< relref "entities/Account" >}}) or null\
**版本历史:**\
2.3.0 - 添加
### `rules` {#rules}
**描述:** 此网站的规则的详细列表。\
**类型:** [Rule]({{< relref "entities/Rule" >}}) 的数组\
**版本历史:**\
3.4.0 - 添加
## 参见
{{< page-relref ref="methods/instance#v1" caption="GET /api/v1/instance" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/v1/instance_serializer.rb" caption="app/serializers/rest/v1/instance_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="V1::Instance" raw_link="/entities/V1_Instance/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

92
content/zh-cn/entities/V1_NotificationPolicy.md Normal file
View file

@ -0,0 +1,92 @@
---
title: V1::NotificationPolicy
description: 表示用户的通知过滤策略。
menu:
docs:
parent: entities
aliases: [
"/entities/v1_NotificationPolicy",
]
---
{{< hint style="warning" >}}
此版本的通知过滤策略 API 已弃用，且未在任何版本中发布。请参考[当前版本]({{< relref "entities/NotificationPolicy">}}) 。
{{</ hint >}}
## 属性
### `filter_not_following` {#filter_not_following}
**描述:** 是否过滤来自用户未关注帐户的通知。\
**类型:** 布尔值\
**版本历史:**\
4.3.0 - 添加
### `filter_not_followers` {#filter_not_followers}
**描述:** 是否过滤来自未关注用户的帐户的通知。\
**类型:** 布尔值\
**版本历史:**\
4.3.0 - 添加
### `filter_new_accounts` {#filter_new_accounts}
**描述:** 是否过滤来自过去 30 天内创建的帐户的通知。\
**类型:** 布尔值\
**版本历史:**\
4.3.0 - 添加
### `filter_private_mentions` {#filter_private_mentions}
**描述:** 是否过滤私下提及的通知。对由用户发起的私下提及的回复，以及用户关注的帐户发起的私下提及永远不会被过滤。\
**类型:** 布尔值\
**版本历史:**\
4.3.0 - 添加
### `summary` {#summary}
**描述:** 已过滤通知的摘要
**类型:** Hash\
**版本历史:**\
4.3.0 - 添加
### `summary[pending_requests_count]` {#pending_requests_count}
**描述:** 用户收到但未忽略的已过滤通知的来源帐户的数量。上限为 100。
**类型:** 整数\
**版本历史:**\
4.3.0 - 添加
### `summary[pending_notifications_count]` {#pending_notifications_count}
**描述:** 未忽略的已过滤通知的总数。可能不准确。
**类型:** 整数\
**版本历史:**\
4.3.0 - 添加
## 示例
```json
{
"filter_not_following": false,
"filter_not_followers": false,
"filter_new_accounts": false,
"filter_private_mentions": true,
"summary": {
"pending_requests_count": 0,
"pending_notifications_count": 0
}
}
```
## 另请参考
{{< page-relref ref="entities/NotificationPolicy" caption="NotificationPolicy（已发布版本）" >}}
{{< page-relref ref="methods/notifications" caption="notifications API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/v1/notification_policy_serializer.rb" caption="app/serializers/rest/v1/notification_policy_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="V1::NotificationPolicy" raw_link="/entities/V1_NotificationPolicy/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

155
content/zh-cn/entities/WebPushSubscription.md Normal file
View file

@ -0,0 +1,155 @@
---
title: WebPushSubscription
description: 表示一个对流式推送的订阅。
menu:
docs:
parent: entities
aliases: [
"/entities/pushsubscription",
"/entities/PushSubscription",
"/entities/webpushsubscription",
"/entities/WebPushSubscription",
"/api/entities/pushsubscription",
"/api/entities/PushSubscription",
"/api/entities/webpushsubscription",
"/api/entities/WebPushSubscription",
]
---
## 示例
```json
{
"id": 328183,
"endpoint": "https://yourdomain.example/listener",
"standard": true,
"alerts": {
"follow": false,
"favourite": false,
"reblog": false,
"mention": true,
"poll": false
},
"server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}
```
## 属性
### `id` {#id}
**描述:** Web Push 订阅在数据库中的ID。\
**类型:** 字符串 (从整数转换而来，但不保证一定为数字)\
**版本历史:**\
2.4.0 - 添加
### `endpoint` {#endpoint}
**描述:** 推送通知将发送到的地址。\
**类型:** 字符串（URL）\
**版本历史:**\
2.4.0 - 添加
### `standard` {#standard}
**描述:** 推送消息是否遵循标准化规范 (RFC8030+RFC8291+RFC8292)。若为 `false`，则遵循该规范的旧版本（RFC8291 的第 4 版草案和 RFC8292 的第 1 版草案）。
**类型:** 布尔值\
**版本历史:**\
4.4.0 - 添加
### `server_key` {#server_key}
**描述:** 流式推送实例的 VAPID 密钥。\
**类型:** 字符串\
**版本历史:**\
2.4.0 - 添加
### `alerts` {#alerts}
**描述:** 哪些提醒会被传递到 `endpoint`。\
**类型:** 哈希\
**版本历史:**\
2.4.0 - 添加\
2.8.0 - 添加 `alerts[poll]`\
3.1.0 - 添加 `alerts[follow_request]`\
3.3.0 - 添加 `alerts[status]`\
3.5.0 - 添加 `alerts[update]` 和 `alerts[admin.sign_up]`\
4.0.0 - 添加 `alerts[admin.report]`
#### `alerts[mention]` {#mention}
**描述:** 当有人在嘟文中提及你时，是否接收推送通知？\
**类型:** 布尔值\
**版本历史:**\
2.4.0 - 添加
#### `alerts[status]` {#status}
**描述:** 当启用了发嘟通知的帐户发布嘟文时，是否接收推送通知？\
**类型:** 布尔值\
**版本历史:**\
3.3.0 - 添加
#### `alerts[reblog]` {#reblog}
**描述:** 当你创建的嘟文被其他人转发时，是否接收推送通知？\
**类型:** 布尔值\
**版本历史:**\
2.4.0 - 添加
#### `alerts[follow]` {#follow}
**描述:** 当有人关注你时，是否接收推送通知？\
**类型:** 布尔值\
**版本历史:**\
2.4.0 - 添加
#### `alerts[follow_request]` {#follow_request}
**描述:** 当有人请求关注你时，是否接收推送通知？\
**类型:** 布尔值\
**版本历史:**\
3.1.0 - 添加
#### `alerts[favourite]` {#favourite}
**描述:** 当你创建的嘟文被其他人喜欢时，是否接收推送通知？\
**类型:** 布尔值\
**版本历史:**\
2.4.0 - 添加
#### `alerts[poll]` {#poll}
**描述:** 当你投票或创建的投票结束时，是否接收推送通知？\
**类型:** 布尔值\
**版本历史:**\
2.8.0 - 添加
#### `alerts[update]` {#update}
**描述:** 当你互动过的嘟文被编辑时，是否接收推送通知？\
**类型:** 布尔值\
**版本历史:**\
3.5.0 - 添加
#### `alerts[admin.sign_up]` {#admin-sign_up}
**描述:** 当有新用户注册时，是否接收推送通知？\
**类型:** 布尔值\
**版本历史:**\
3.5.0 - 添加
#### `alerts[admin.report]` {#admin-report}
**描述:** 当提交新的举报时，是否接收推送通知？\
**类型:** 布尔值\
**版本历史:**\
4.0.0 - 添加
## 参见
{{< page-relref ref="methods/push" caption="push API 方法" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/web_push_subscription_serializer.rb" caption="app/serializers/rest/web_push_subscription_serializer.rb" >}}
{{< translation-status-zh-cn raw_title="WebPushSubscription" raw_link="/entities/WebPushSubscription/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

2365
content/zh-cn/methods/accounts.md Normal file
View file

File diff suppressed because it is too large Load diff

12
content/zh-cn/methods/admin/_index.md Normal file
View file

@ -0,0 +1,12 @@
---
title: admin API 方法
description: 查看和管理管理信息。
menu:
docs:
weight: 80
name: admin
parent: methods
identifier: methods-admin
---
{{< translation-status-zh-cn raw_title="admin API methods" raw_link="/methods/admin/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}}

Some files were not shown because too many files have changed in this diff Show more