From df6555446e5296d9dc1f8a6e1a612efdc2422ad7 Mon Sep 17 00:00:00 2001 From: CDN18 Date: Sat, 2 Nov 2024 05:58:56 +0800 Subject: [PATCH] [docs] add zh docs --- README.zh.md | 520 + docs/locales/zh/.readthedocs.yaml | 17 + docs/locales/zh/admin/backup_and_restore.md | 223 + docs/locales/zh/admin/cli.md | 465 + docs/locales/zh/admin/database_maintenance.md | 55 + docs/locales/zh/admin/domain_blocks.md | 73 + docs/locales/zh/admin/federation_modes.md | 62 + docs/locales/zh/admin/media_caching.md | 57 + .../zh/admin/request_filtering_modes.md | 31 + docs/locales/zh/admin/robots.md | 13 + docs/locales/zh/admin/settings.md | 169 + docs/locales/zh/admin/signups.md | 59 + docs/locales/zh/admin/spam.md | 23 + docs/locales/zh/admin/themes.md | 13 + docs/locales/zh/advanced/builds/nowasm.md | 27 + docs/locales/zh/advanced/caching/api.md | 84 + .../zh/advanced/caching/assets-media.md | 132 + docs/locales/zh/advanced/caching/index.md | 11 + docs/locales/zh/advanced/certificates.md | 108 + docs/locales/zh/advanced/healthchecks.md | 48 + .../zh/advanced/host-account-domain.md | 116 + docs/locales/zh/advanced/index.md | 19 + docs/locales/zh/advanced/metrics.md | 57 + docs/locales/zh/advanced/outgoing-proxy.md | 21 + .../locales/zh/advanced/replicating-sqlite.md | 102 + docs/locales/zh/advanced/security/firewall.md | 174 + docs/locales/zh/advanced/security/index.md | 11 + .../zh/advanced/security/sandboxing.md | 63 + .../zh/advanced/sqlite-networked-storage.md | 35 + docs/locales/zh/advanced/tracing.md | 44 + docs/locales/zh/api/authentication.md | 149 + docs/locales/zh/api/ratelimiting.md | 41 + docs/locales/zh/api/swagger.md | 21 + docs/locales/zh/api/swagger.yaml | 11393 ++++++++++++++++ docs/locales/zh/api/throttling.md | 35 + docs/locales/zh/configuration/accounts.md | 44 + docs/locales/zh/configuration/advanced.md | 152 + docs/locales/zh/configuration/database.md | 192 + docs/locales/zh/configuration/general.md | 121 + docs/locales/zh/configuration/httpclient.md | 67 + docs/locales/zh/configuration/index.md | 138 + docs/locales/zh/configuration/instance.md | 115 + docs/locales/zh/configuration/media.md | 87 + .../locales/zh/configuration/observability.md | 53 + docs/locales/zh/configuration/oidc.md | 156 + docs/locales/zh/configuration/smtp.md | 78 + docs/locales/zh/configuration/statuses.md | 38 + docs/locales/zh/configuration/storage.md | 189 + docs/locales/zh/configuration/syslog.md | 40 + docs/locales/zh/configuration/tls.md | 64 + docs/locales/zh/configuration/web.md | 21 + docs/locales/zh/faq.md | 41 + docs/locales/zh/federation/access_control.md | 11 + docs/locales/zh/federation/actors.md | 368 + docs/locales/zh/federation/glossary.md | 73 + docs/locales/zh/federation/http_signatures.md | 85 + docs/locales/zh/federation/index.md | 7 + docs/locales/zh/federation/moderation.md | 41 + docs/locales/zh/federation/posts.md | 924 ++ docs/locales/zh/federation/ratelimiting.md | 7 + docs/locales/zh/getting_started/index.md | 185 + .../getting_started/installation/container.md | 164 + .../zh/getting_started/installation/index.md | 14 + .../zh/getting_started/installation/metal.md | 164 + docs/locales/zh/getting_started/releases.md | 11 + .../reverse_proxy/apache-httpd.md | 261 + .../zh/getting_started/reverse_proxy/caddy.md | 110 + .../zh/getting_started/reverse_proxy/index.md | 43 + .../zh/getting_started/reverse_proxy/nginx.md | 186 + .../reverse_proxy/websocket.md | 43 + .../zh/getting_started/user_creation.md | 49 + docs/locales/zh/index.md | 17 + docs/locales/zh/mkdocs.yml | 98 + docs/locales/zh/user_guide/custom_css.md | 73 + docs/locales/zh/user_guide/migration.md | 78 + .../zh/user_guide/password_management.md | 19 + docs/locales/zh/user_guide/posts.md | 300 + docs/locales/zh/user_guide/rss.md | 15 + docs/locales/zh/user_guide/search.md | 20 + docs/locales/zh/user_guide/settings.md | 268 + 80 files changed, 19701 insertions(+) create mode 100644 README.zh.md create mode 100644 docs/locales/zh/.readthedocs.yaml create mode 100644 docs/locales/zh/admin/backup_and_restore.md create mode 100644 docs/locales/zh/admin/cli.md create mode 100644 docs/locales/zh/admin/database_maintenance.md create mode 100644 docs/locales/zh/admin/domain_blocks.md create mode 100644 docs/locales/zh/admin/federation_modes.md create mode 100644 docs/locales/zh/admin/media_caching.md create mode 100644 docs/locales/zh/admin/request_filtering_modes.md create mode 100644 docs/locales/zh/admin/robots.md create mode 100644 docs/locales/zh/admin/settings.md create mode 100644 docs/locales/zh/admin/signups.md create mode 100644 docs/locales/zh/admin/spam.md create mode 100644 docs/locales/zh/admin/themes.md create mode 100644 docs/locales/zh/advanced/builds/nowasm.md create mode 100644 docs/locales/zh/advanced/caching/api.md create mode 100644 docs/locales/zh/advanced/caching/assets-media.md create mode 100644 docs/locales/zh/advanced/caching/index.md create mode 100644 docs/locales/zh/advanced/certificates.md create mode 100644 docs/locales/zh/advanced/healthchecks.md create mode 100644 docs/locales/zh/advanced/host-account-domain.md create mode 100644 docs/locales/zh/advanced/index.md create mode 100644 docs/locales/zh/advanced/metrics.md create mode 100644 docs/locales/zh/advanced/outgoing-proxy.md create mode 100644 docs/locales/zh/advanced/replicating-sqlite.md create mode 100644 docs/locales/zh/advanced/security/firewall.md create mode 100644 docs/locales/zh/advanced/security/index.md create mode 100644 docs/locales/zh/advanced/security/sandboxing.md create mode 100644 docs/locales/zh/advanced/sqlite-networked-storage.md create mode 100644 docs/locales/zh/advanced/tracing.md create mode 100644 docs/locales/zh/api/authentication.md create mode 100644 docs/locales/zh/api/ratelimiting.md create mode 100644 docs/locales/zh/api/swagger.md create mode 100644 docs/locales/zh/api/swagger.yaml create mode 100644 docs/locales/zh/api/throttling.md create mode 100644 docs/locales/zh/configuration/accounts.md create mode 100644 docs/locales/zh/configuration/advanced.md create mode 100644 docs/locales/zh/configuration/database.md create mode 100644 docs/locales/zh/configuration/general.md create mode 100644 docs/locales/zh/configuration/httpclient.md create mode 100644 docs/locales/zh/configuration/index.md create mode 100644 docs/locales/zh/configuration/instance.md create mode 100644 docs/locales/zh/configuration/media.md create mode 100644 docs/locales/zh/configuration/observability.md create mode 100644 docs/locales/zh/configuration/oidc.md create mode 100644 docs/locales/zh/configuration/smtp.md create mode 100644 docs/locales/zh/configuration/statuses.md create mode 100644 docs/locales/zh/configuration/storage.md create mode 100644 docs/locales/zh/configuration/syslog.md create mode 100644 docs/locales/zh/configuration/tls.md create mode 100644 docs/locales/zh/configuration/web.md create mode 100644 docs/locales/zh/faq.md create mode 100644 docs/locales/zh/federation/access_control.md create mode 100644 docs/locales/zh/federation/actors.md create mode 100644 docs/locales/zh/federation/glossary.md create mode 100644 docs/locales/zh/federation/http_signatures.md create mode 100644 docs/locales/zh/federation/index.md create mode 100644 docs/locales/zh/federation/moderation.md create mode 100644 docs/locales/zh/federation/posts.md create mode 100644 docs/locales/zh/federation/ratelimiting.md create mode 100644 docs/locales/zh/getting_started/index.md create mode 100644 docs/locales/zh/getting_started/installation/container.md create mode 100644 docs/locales/zh/getting_started/installation/index.md create mode 100644 docs/locales/zh/getting_started/installation/metal.md create mode 100644 docs/locales/zh/getting_started/releases.md create mode 100644 docs/locales/zh/getting_started/reverse_proxy/apache-httpd.md create mode 100644 docs/locales/zh/getting_started/reverse_proxy/caddy.md create mode 100644 docs/locales/zh/getting_started/reverse_proxy/index.md create mode 100644 docs/locales/zh/getting_started/reverse_proxy/nginx.md create mode 100644 docs/locales/zh/getting_started/reverse_proxy/websocket.md create mode 100644 docs/locales/zh/getting_started/user_creation.md create mode 100644 docs/locales/zh/index.md create mode 100644 docs/locales/zh/mkdocs.yml create mode 100644 docs/locales/zh/user_guide/custom_css.md create mode 100644 docs/locales/zh/user_guide/migration.md create mode 100644 docs/locales/zh/user_guide/password_management.md create mode 100644 docs/locales/zh/user_guide/posts.md create mode 100644 docs/locales/zh/user_guide/rss.md create mode 100644 docs/locales/zh/user_guide/search.md create mode 100644 docs/locales/zh/user_guide/settings.md diff --git a/README.zh.md b/README.zh.md new file mode 100644 index 000000000..15c7e02d9 --- /dev/null +++ b/README.zh.md @@ -0,0 +1,520 @@ + +# GoToSocial + +**有关企业赞助的更新：我们欢迎与符合我们价值观的组织建立赞助关系；请查看下述条件** + +GoToSocial 是一个用 Golang 编写的 [ActivityPub](https://activitypub.rocks/) 社交网络服务端。 + +通过 GoToSocial，你可以与朋友保持联系，发帖、阅读和分享图片及文章，且不会被追踪或广告打扰！ + +

+ +

+ +**GoToSocial 仍然是 [BETA 软件](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta)**。它已经可被部署和使用，并能与许多其他 Fediverse 服务端顺利联合（但还不是与所有服务端）。然而，许多功能尚未实现，而且还有不少漏洞！我们在 2024 年 9 月/10 月离开了 Alpha 阶段，并计划于 2026 年结束 Beta。 + +文档位于 [docs.gotosocial.org](https://docs.gotosocial.org/zh-cn/)。你可以直接跳至 [API 文档](https://docs.gotosocial.org/zh-cn/latest/api/swagger/)。 + +要从源代码构建，请查看 [CONTRIBUTING.md](https://github.com/superseriousbusiness/gotosocial/blob/main/CONTRIBUTING.md) 文件。 + +这是实例首页的截图！ + +![GoToSocial 实例 goblin.technology 的首页截图。它展示了实例的基本信息，如用户数和贴文数等。](https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/docs/assets/instancesplash.png) + + +## 目录 + +- [什么是 GoToSocial？](#什么是-gotosocial) + - [联合](#联合) + - [历史与现状](#历史与现状) +- [功能](#功能) + - [兼容 Mastodon API](#兼容-mastodon-api) + - [精细的贴文可见性设置](#精细的贴文可见性设置) + - [回复控制](#回复控制) + - [仅本站贴文](#仅本站贴文) + - [RSS 源](#rss-源) + - [富文本格式化](#富文本格式化) + - [主题与自定义 CSS](#主题与自定义-css) + - [易于运行](#易于运行) + - [隐私+安全功能](#隐私安全功能) + - [多种联合模式](#多种联合模式) + - [OIDC 集成](#oidc-集成) + - [后端优先设计](#后端优先设计) +- [已知问题](#已知问题) +- [安装 GoToSocial](#安装-gotosocial) + - [支持的平台](#支持的平台) + - [FreeBSD](#freebsd) + - [32位](#32位) + - [OpenBSD](#openbsd) + - [稳定版本](#稳定版本) + - [快照版本](#快照版本) + - [Docker](#docker) + - [二进制发布 .tar.gz](#二进制发布-targz) + - [从源代码构建](#从源代码构建) + - [第三方打包](#第三方打包) +- [参与贡献](#参与贡献) +- [联系我们](#联系我们) +- [致谢](#致谢) + - [库](#库) + - [图像归属与许可](#图像归属与许可) + - [团队成员](#团队成员) + - [特别鸣谢](#特别鸣谢) +- [赞助与资金支持](#赞助与资金支持) + - [众筹](#众筹) + - [企业赞助](#企业赞助) + - [NLnet](#nlnet) +- [许可](#许可) + + +## 什么是 GoToSocial？ + +GoToSocial 提供了一个轻量级、可定制且注重安全的进入 [联邦宇宙](https://en.wikipedia.org/wiki/Fediverse) 的入口，它类似但不同于像 [Mastodon](https://joinmastodon.org/)、[Pleroma](https://pleroma.social/)、[Friendica](https://friendi.ca) 和 [PixelFed](https://pixelfed.org/) 这样的现有项目。 + +如果你曾使用过 Twitter 或 Tumblr（甚至是 Myspace）等服务，GoToSocial 可能会让你感到熟悉：你可以关注他人并拥有粉丝，发布贴文，点赞、回复和分享他人的帖子，并通过时间线浏览你关注的人的贴文。你可以撰写长篇或短篇贴文，或者仅发布图片，一切随你选择。当然，你也可以屏蔽他人，或通过选择仅向朋友发布来限制不想要的互动。 + +![GoToSocial 中的网页版账户页截图，显示了头像、简介和粉丝/关注人数。](https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/docs/assets/profile1.png) + +**GoToSocial 不使用推荐算法，也不收集你的数据来推荐内容或“改善你的体验”**。时间线是按时间顺序排列的：你在时间线顶部看到的内容是*刚刚发布的*，而不是根据你的个人资料选择的“有趣”或“有争议”的内容。 + +GoToSocial 并不是为拥有成千上万粉丝的“必追”网红设计的，也不是设计被用来让人上瘾的。你的时间线和体验由你关注的人和你与他人的互动方式决定，而不是你的参与度的相关指标！ + +GoToSocial 不会宣称比其他应用更“好”，但它提供了一些可能特别*适合你*的东西。 + +### 联合 + +因为 GoToSocial 使用 [ActivityPub](https://activitypub.rocks/)，你不仅可以与本站上的人交流，还可以无缝与 [联邦宇宙](https://en.wikipedia.org/wiki/Fediverse) 上的人交流。 + +![activitypub 标志](https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/docs/assets/ap_logo.svg) + +联合意味着你的实例是一个遍布世界的、使用相同协议通信的服务器网络的一部分。你的数据不再集中在一家公司服务器上，而是在你自己的服务器上，根据你的意愿，跨越由其他人运行的服务器组成的弹性网络实现共享。 + +这种联合方式也意味着你不必受制于可能远在千里之外的庞大公司设定的任意规则。你的实例有自己的规则和文化；你的实例的居民是你的网上邻居；你很可能会认识你的服务器管理员和站务，或者自己成为管理员。 + +GoToSocial 的愿景是让许多小而特别的实例遍布联邦宇宙，让人们感到宾至如归，而不是让联邦宇宙被少数大的通用的实例占据，在那里一个人的声音可能会在大量其它账号的声音中迷失。 + +### 历史与现状 + +该项目于 2021 年 2/3 月因对其他联合式微博/社交媒体应用的安全和隐私功能的不满而起步，并希望实现一些不同的东西。 + +它最初是一个个人项目，然后随着更多开发者的兴趣和加入而加速发展。 + +我们在 2021 年 11 月进行了首次 Alpha 发布。我们于 2024 年 9 月/10 月离开 Alpha，进入 Beta 阶段。 + +要详细了解已实现和未实现的内容，以及 [稳定发布](https://en.wikipedia.org/wiki/Software_release_life_cycle#Stable_release) 的进展，请查看 [路线图](https://github.com/superseriousbusiness/gotosocial/blob/main/ROADMAP.md)。 + +--- + +## 功能 + +### 兼容 Mastodon API + +Mastodon API 已成为客户端与联邦宇宙服务端通信的事实标准，因此 GoToSocial 实现并在自定义功能上扩展了该 API。 + +大多数实现 Mastodon API 的应用程序都应该可以使用 GoToSocial，但以下这些优秀的应用程序已经过测试，可与 GoToSocial 可靠地配合使用： + +* [Tusky](https://tusky.app/) 适用于 Android +* [Semaphore](https://semaphore.social/) 适用于浏览器 +* [Feditext](https://github.com/feditext/feditext) (beta) 适用于 iOS, iPadOS 和 macOS + +如果你之前通过第三方应用来使用 Mastodon，使用 GoToSocial 将是轻而易举的。 + +### 精细的贴文可见性设置 + +发布内容时，选择谁能看到很重要。 + +GoToSocial 提供公开、不列出/悄悄公开、仅粉丝和私信（最好让对方事先同意）的贴文选项。 + +### 回复控制 + +GoToSocial 允许你通过 [互动规则](https://docs.gotosocial.org/zh-cn/latest/user_guide/settings/#default-interaction-policies) 选择谁可以回复你的贴文。你可以选择允许任何人回复贴文，仅允许朋友回复，等等。 + +![互动规则设置](https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/docs/assets/user-settings-interaction-policy-1.png) + +### 仅本站贴文 + +有时你只想与同一实例中的人们交流。GoToSocial 通过仅本站可见贴文支持这一点，确保贴文仅保留在你的实例中。（当前，仅本站可见贴文能否使用取决于客户端支持。） + +### RSS 源 + +GoToSocial 允许你选择将个人资料暴露为 RSS 订阅源，这样人们可以订阅你的公开源而不会错过任何贴文。 + +### 富文本格式化 + +使用 GoToSocial，你可以使用流行且易用的 Markdown 标记语言来撰写帖子，从而生成丰富的 HTML 贴文，支持引用段落、语法高亮代码块、列表、内嵌链接等。 + +![markdown 格式化贴文](https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/docs/assets/markdown-post.png) + +### 主题与自定义 CSS + +用户可以为他们的账户页 [选择多种有趣的主题](https://docs.gotosocial.org/zh-cn/latest/user_guide/settings/#select-theme)，或甚至编写自己的 [自定义 CSS](https://docs.gotosocial.org/zh-cn/latest/user_guide/settings/#custom-css)。 + +管理员也可以轻松地为用户 [添加自定义主题](https://docs.gotosocial.org/zh-cn/latest/admin/themes/) 供用户选择。 + +
+显示主题示例 +
+ +
Blurple dark
+
+
+
+ +
Blurple light
+
+
+
+ +
Brutalist light
+
+
+
+ +
Brutalist dark
+
+
+
+ +
Ecks pee
+
+
+
+ +
Midnight trip
+
+
+ +
Moonlight hunt
+
+
+
+ +
Rainforest
+
+
+
+ +
Soft
+
+
+
+ +
Solarized dark
+
+
+
+ +
Solarized light
+
+
+
+ +
Sunset
+
+
+
+ +### 易于运行 + +GoToSocial 仅需约 250-350MiB 的 RAM，并且只要求极少的 CPU 频率，因此非常适合单板计算机、旧笔记本和每月 5 美元的小 VPS。 + +![Grafana 图标显示 GoToSocial 堆占用约为 250MB，偶尔飙升至 400MB-500MB。](https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/docs/assets/getting-started-memory-graph.png) + +除数据库外无需其他依赖（也可以仅使用 SQLite！）。 + +只需下载二进制文件和对应资源（或 Docker 镜像），调整配置并运行。 + +### 隐私+安全功能 + +- 内置 [Let's Encrypt](https://letsencrypt.org/) 的自动使用 HTTPS 支持。 +- 严格执行贴文可见性和屏蔽逻辑。 +- 导入与导出允许联合实例列表和拒绝联合实例列表。订阅社区创建的屏蔽列表（类似于用于实例间联合的广告拦截器！）（功能仍在进行中）。 +- HTTP 签名认证：GoToSocial 在发送和接收消息时要求 [HTTP 签名](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12)，以确保消息不能被篡改，身份不能被伪造。 + +### 多种联合模式 + +GoToSocial 对联合并不采取一刀切的方法。你的实例应该与谁联合应由你决定。 + +- “屏蔽列表”模式（默认）：发现新实例；屏蔽你不喜欢的实例。 +- “允许列表”模式（实验性）；只选择与信任的实例联合。 +- “零”联合模式；保持你的服务器私密（尚未实现）。 + +[查看文档了解更多信息](https://docs.gotosocial.org/zh-cn/latest/admin/federation_modes)。 + +### OIDC 集成 + +GoToSocial 支持 [OpenID Connect (OIDC)](https://openid.net/connect/) 身份提供商，这意味着你可以将其与现有的用户管理服务（如 [Auth0](https://auth0.com/)、[Gitlab](https://docs.gitlab.com/ee/integration/openid_connect_provider.html) 等）集成，或者部署你自己的 OIDC 服务并与之相连（我们推荐使用 [Dex](https://dexidp.io/)）。 + +### 后端优先设计 + +与其他联邦宇宙服务端项目不同，GoToSocial 不附带集成的客户端前端（例如，网页端应用）。 + +相反，与 Matrix.org 的 [Synapse](https://github.com/matrix-org/synapse) 项目类似，它提供了一个相对通用的后端服务器实现，一些用于展示账户和贴文的美观的页面，以及一个[具有完善文档的 API](https://docs.gotosocial.org/zh-cn/latest/api/swagger/)。 + +在该 API 基础上，GoToSocial 鼓励开发者构建任何他们想要的前端实现或移动应用，无论它们是类似于 Tumblr、Facebook、Twitter，还是完全不同的东西。 + +--- + +## 已知问题 + +由于 GoToSocial 仍处于测试阶段，存在很多错误。我们使用 [GitHub issues](https://github.com/superseriousbusiness/gotosocial/issues?q=is%3Aissue+is%3Aopen+label%3Abug) 跟踪这些问题。 + +由于每个 ActivityPub 服务端实现对协议的解释略有不同，有些服务端尚未与 GoToSocial 正常联合。我们在 [这个项目](https://github.com/superseriousbusiness/gotosocial/projects/4) 中跟踪这些问题。最终，我们希望确保任何可以与 Mastodon 正确联合的 ActivityPub 实现也能够与 GoToSocial 联合。 + +--- + +## 安装 GoToSocial + +查看我们的 [入门文档](https://docs.gotosocial.org/zh-cn/latest/getting_started/)，并浏览我们的 [发布页面](https://github.com/superseriousbusiness/gotosocial/releases)。 + +--- + + +### 支持的平台 + +虽然我们尽力支持合理数量的架构和操作系统，但由于库的限制或性能问题，对特定平台的支持有时是不可能实现的。 + +某些平台不被我们正式支持，但仍*可能*工作，我们无法测试或保证其性能或稳定性。 + +以下是 GoToSocial 当前针对不同平台的支持状态（如果某个平台未列出，则表示我们尚未检查，因此我们不清楚）： + +| 操作系统 | 架构 | 支持程度 | 二进制文件 | Docker 容器 | +| ------- | --------------------- | ---------------------------------- | ---------- | --------------- | +| Linux | x86-64/AMD64 (64位) | 🟢 完全支持 | 是 | 是 | +| Linux | Armv8/ARM64 (64位) | 🟢 完全支持 | 是 | 是 | +| FreeBSD | x86-64/AMD64 (64位) | 🟢 完全支持[1](#freebsd) | 是 | 否 | +| Linux | x86-32/i386 (32位) | 🟡 部分支持[2](#32-bit) | 是 | 是 | +| Linux | Armv7/ARM32 (32位) | 🟡 部分支持[2](#32-bit) | 是 | 是 | +| Linux | Armv6/ARM32 (32位) | 🟡 部分支持[2](#32-bit) | 是 | 是 | +| OpenBSD | 任何架构 | 🔴 不支持[3](#openbsd) | 否 | 否 | + +#### FreeBSD + +大多数情况下可用，只是在 WASM SQLite 上有一些问题；在 FreeBSD 上安装时请仔细查看发行说明。如果使用 Postgres，则不应出现问题。 + +#### 32位 + +GtS 在像 i386 或 Armv6/v7 这样的 32 位系统上表现不佳，这主要是媒体解码性能的问题。 + +我们不建议在 32 位系统上运行 GtS，但你可以尝试关闭外站媒体处理功能，或使用完全**不受支持、实验性**的 [nowasm](https://docs.gotosocial.org/zh-cn/latest/advanced/builds/nowasm/) 标签自行构建二进制文件。 + +有关更多指导，请在尝试在 32 位系统上安装时检查发行说明。 + +#### OpenBSD + +由于性能问题（空闲时的高内存占用，在处理媒体时崩溃），此系统被标记为不支持。 + +虽然我们不支持在 OpenBSD 上运行 GtS，但你可以尝试使用完全**不受支持、实验性**的 [nowasm](https://docs.gotosocial.org/zh-cn/latest/advanced/builds/nowasm/) 标签自行构建二进制文件。 + +### 稳定版本 + +我们为二进制构建和 Docker 容器打包稳定版本，这样你就不需要自己从源代码构建。 + +Docker 镜像 `superseriousbusiness/gotosocial:latest` 始终对应于最新稳定版本。由于此标签经常被覆盖，你可能希望使用 Docker CLI 标志 `--pull always` 确保每次运行此标签时都有最新的镜像，或者也可在使用前手动运行 `docker pull superseriousbusiness/gotosocial:latest`。 + +### 快照版本 + +我们还会在每次将代码合并到主分支时进行快照版的构建，因此如果你愿意，可以从主分支的代码运行。 + +请注意，风险自负！我们会尝试确保主分支正常工作，但不能做出任何保证。如果不确定，请选择稳定版。 + +#### Docker + +要使用 Docker 从主分支运行，请使用 `snapshot` Docker 标签。Docker 镜像 `superseriousbusiness/gotosocial:snapshot` 始终对应主分支上的最新提交。由于此标签经常被覆盖，你可能希望使用 Docker CLI 标志 `--pull always` 确保每次运行此标签时都有最新的镜像，或者也可在使用前手动运行 `docker pull superseriousbusiness/gotosocial:snapshot`。 + +#### 二进制发布 .tar.gz + +要使用二进制发布从主分支运行，请从我们的 [自托管 Minio S3 仓库](https://minio.s3.superseriousbusiness.org/browser/gotosocial-snapshots)下载适合你架构的 .tar.gz 文件。 + +S3 存储桶中的快照版二进制发布由 Github 提交哈希控制。要获取最新的，请按上次修改时间排序，或者查看 [这里的提交列表](https://github.com/superseriousbusiness/gotosocial/commits/main)，复制最新的 SHA，并在 Minio 控制台过滤器中粘贴。快照二进制发布会在 28 天后过期，以降低我们的托管成本。 + +### 从源代码构建 + +有关从源代码构建 GoToSocial 的说明，请参见 [CONTRIBUTING.md](https://github.com/superseriousbusiness/gotosocial/blob/main/CONTRIBUTING.md) 文件。 + +### 第三方打包 + +非常感谢那些将时间和精力投入到打包 GoToSocial 的人！ + +这些包不是由 GoToSocial 维护的，因此请将问题和反馈发往对应的存储库维护者（并考虑向他们捐款！）。 + +[![打包状态](https://repology.org/badge/vertical-allrepos/gotosocial.svg)](https://repology.org/project/gotosocial/versions) + +你还可以通过以下方式部署自己的 GoToSocial 实例： + +- [YunoHost 上的 GoToSocial 打包](https://github.com/YunoHost-Apps/gotosocial_ynh)：作者 [OniriCorpe](https://github.com/OniriCorpe)。 +- [Ansible Playbook (MASH)](https://github.com/mother-of-all-self-hosting/mash-playbook)：该 Playbook 支持包括 GoToSocial 在内的多项服务。[文档](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/services/gotosocial.md) +- [GoToSocial Helm Chart](https://github.com/fSocietySocial/charts/tree/main/charts/gotosocial)：作者 [0hlov3](https://github.com/0hlov3)。 + + +--- + +## 参与贡献 + +你想为 GtS 作出贡献吗？太好了！❤️❤️❤️ 请查看问题页面，看看是否有你想参与的内容，并阅读 [CONTRIBUTING.md](https://github.com/superseriousbusiness/gotosocial/blob/main/CONTRIBUTING.md) 文件以获取指南并配置开发环境。 + +--- + +## 联系我们 + +如果你有问题或反馈，可以[加入我们的 Matrix 空间](https://matrix.to/#/#gotosocial-space:superseriousbusiness.org)，地址是 `#gotosocial-space:superseriousbusiness.org`。这是联系开发人员的最快方式。你也可以发送邮件至 [admin@gotosocial.org](mailto:admin@gotosocial.org)。 + +对于错误和功能请求，请先查看是否[已有相应问题](https://github.com/superseriousbusiness/gotosocial/issues)，如果没有，可以开一个新问题工单(issue)，或者使用上述渠道提出请求（如果你没有 Github 账户的话）。 + +--- + +## 致谢 + +### 库 + +GoToSocial 使用以下开源库、框架和工具，在此声明并致谢 💕 + +- [buckket/go-blurhash](https://github.com/buckket/go-blurhash); 用于生成图像模糊哈希。 [GPL-3.0 许可证](https://spdx.org/licenses/GPL-3.0-only.html)。 +- [coreos/go-oidc](https://github.com/coreos/go-oidc); OIDC 客户端库。 [Apache-2.0 许可证](https://spdx.org/licenses/Apache-2.0.html)。 +- [DmitriyVTitov/size](https://github.com/DmitriyVTitov/size); 运行时模型内存大小计算。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- Gin: + - [gin-contrib/cors](https://github.com/gin-contrib/cors); Gin CORS 中间件。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [gin-contrib/gzip](https://github.com/gin-contrib/gzip); Gin gzip 中间件。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [gin-contrib/sessions](https://github.com/gin-contrib/sessions); Gin 会话中间件。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [gin-gonic/gin](https://github.com/gin-gonic/gin); 高速路由引擎。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- [google/uuid](https://github.com/google/uuid); UUID 生成。 [BSD-3-Clause 许可证](https://spdx.org/licenses/BSD-3-Clause.html)。 +- Go-Playground: + - [go-playground/form](https://github.com/go-playground/form); 表单映射支持。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [go-playground/validator](https://github.com/go-playground/validator); 结构验证。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- Gorilla: + - [gorilla/feeds](https://github.com/gorilla/feeds); RSS + Atom 提要生成。 [BSD-2-Clause 许可证](https://spdx.org/licenses/BSD-2-Clause.html)。 + - [gorilla/websocket](https://github.com/gorilla/websocket); WebSocket 连接。 [BSD-2-Clause 许可证](https://spdx.org/licenses/BSD-2-Clause.html)。 +- [go-swagger/go-swagger](https://github.com/go-swagger/go-swagger); Swagger OpenAPI 规范生成。 [Apache-2.0 许可证](https://spdx.org/licenses/Apache-2.0.html)。 +- gruf: + - [gruf/go-bytesize](https://codeberg.org/gruf/go-bytesize); 字节大小解析/格式化。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [gruf/go-cache](https://codeberg.org/gruf/go-cache); LRU 和 TTL 缓存。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [gruf/go-debug](https://codeberg.org/gruf/go-debug); 调试构建标记。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [gruf/go-errors](https://codeberg.org/gruf/go-errors); 类似上下文的错误与值包装。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [gruf/go-fastcopy](https://codeberg.org/gruf/go-fastcopy); 高性能 I/O 复制（缓冲池）。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [gruf/go-ffmpreg](https://codeberg.org/gruf/go-ffmpreg); 嵌入式 ffmpeg / ffprobe WASM 二进制文件。 [GPL-3.0 许可证](https://spdx.org/licenses/GPL-3.0-only.html)。 + - [gruf/go-kv](https://codeberg.org/gruf/go-kv); 日志字段格式化。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [gruf/go-list](https://codeberg.org/gruf/go-list); 通用双向链表。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [gruf/go-mutexes](https://codeberg.org/gruf/go-mutexes); 安全互斥锁和互斥图。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [gruf/go-runners](https://codeberg.org/gruf/go-runners); 同步工具。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [gruf/go-sched](https://codeberg.org/gruf/go-sched); 任务调度器。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [gruf/go-storage](https://codeberg.org/gruf/go-storage); 文件存储后端（本地及 s3）。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [gruf/go-structr](https://codeberg.org/gruf/go-structr); 结构缓存+队列及按字段索引。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- jackc: + - [jackc/pgconn](https://github.com/jackc/pgconn); Postgres 驱动程序。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + - [jackc/pgx](https://github.com/jackc/pgx); Postgres 驱动程序及工具包。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- [KimMachineGun/automemlimit](https://github.com/KimMachineGun/automemlimit); cgroups 内存限制检查。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- [k3a/html2text](https://github.com/k3a/html2text); HTML 转文本转换。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- [mcuadros/go-syslog](https://github.com/mcuadros/go-syslog); Syslog 服务器库。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- [microcosm-cc/bluemonday](https://github.com/microcosm-cc/bluemonday); HTML 用户输入清理。 [BSD-3-Clause 许可证](https://spdx.org/licenses/BSD-3-Clause.html)。 +- [miekg/dns](https://github.com/miekg/dns); DNS 工具。 [Go 许可证](https://go.dev/LICENSE)。 +- [minio/minio-go](https://github.com/minio/minio-go); S3 客户端 SDK。 [Apache-2.0 许可证](https://spdx.org/licenses/Apache-2.0.html)。 +- [mitchellh/mapstructure](https://github.com/mitchellh/mapstructure); Go 接口 => 结构解析。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- [modernc.org/sqlite](https://gitlab.com/cznic/sqlite); 简明的 SQLite。 [其他许可证](https://gitlab.com/cznic/sqlite/-/blob/master/LICENSE)。 +- [mvdan.cc/xurls](https://github.com/mvdan/xurls); URL 解析正则表达式。 [BSD-3-Clause 许可证](https://spdx.org/licenses/BSD-3-Clause.html)。 +- [oklog/ulid](https://github.com/oklog/ulid); 顺序友好的数据库 ID 生成。 [Apache-2.0 许可证](https://spdx.org/licenses/Apache-2.0.html)。 +- [open-telemetry/opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go); OpenTelemetry API + SDK。 [Apache-2.0 许可证](https://spdx.org/licenses/Apache-2.0.html)。 +- spf13: + - [spf13/cobra](https://github.com/spf13/cobra); 命令行工具。 [Apache-2.0 许可证](https://spdx.org/licenses/Apache-2.0.html)。 + - [spf13/viper](https://github.com/spf13/viper); 配置管理。 [Apache-2.0 许可证](https://spdx.org/licenses/Apache-2.0.html)。 +- [stretchr/testify](https://github.com/stretchr/testify); 测试框架。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- superseriousbusiness: + - [superseriousbusiness/activity](https://github.com/superseriousbusiness/activity) 从 [go-fed/activity](https://github.com/go-fed/activity) 派生; Golang ActivityPub/ActivityStreams 库。 [BSD-3-Clause 许可证](https://spdx.org/licenses/BSD-3-Clause.html)。 + - [superseriousbusiness/exif-terminator](https://codeberg.org/superseriousbusiness/exif-terminator); EXIF 数据擦除。 [GNU AGPL v3 许可证](https://spdx.org/licenses/AGPL-3.0-or-later.html)。 + - [superseriousbusiness/httpsig](https://github.com/superseriousbusiness/httpsig) 从 [go-fed/httpsig](https://github.com/go-fed/httpsig) 派生; 安全 HTTP 签名库。 [BSD-3-Clause 许可证](https://spdx.org/licenses/BSD-3-Clause.html)。 + - [superseriousbusiness/oauth2](https://github.com/superseriousbusiness/oauth2) 从 [go-oauth2/oauth2](https://github.com/go-oauth2/oauth2) 派生; OAuth 服务器框架和令牌处理。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- [tdewolff/minify](https://github.com/tdewolff/minify); Markdown 帖文的 HTML 压缩。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- [uber-go/automaxprocs](https://github.com/uber-go/automaxprocs); GOMAXPROCS 自动化。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- [ulule/limiter](https://github.com/ulule/limiter); http 流量限制中间件。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- [uptrace/bun](https://github.com/uptrace/bun); 数据库 ORM。 [BSD-2-Clause 许可证](https://spdx.org/licenses/BSD-2-Clause.html)。 +- [wagslane/go-password-validator](https://github.com/wagslane/go-password-validator); 密码强度验证。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 +- [yuin/goldmark](https://github.com/yuin/goldmark); Markdown 解析器。 [MIT 许可证](https://spdx.org/licenses/MIT.html)。 + +### 图像归属与许可 + +树懒标志由 [Anna Abramek](https://abramek.art/) 设计。 + +Creative Commons License
GoToSocial 的树懒吉祥物采用 知识共享署名-相同方式共享 4.0 国际许可协议。 + +该许可具体适用于以下存储库内的文件和子目录： + +- [树懒标志 png](https://github.com/superseriousbusiness/gotosocial/blob/main/web/assets/logo.png) +- [树懒标志 webp](https://github.com/superseriousbusiness/gotosocial/blob/main/web/assets/logo.webp) +- [树懒标志 svg](https://github.com/superseriousbusiness/gotosocial/blob/main/web/assets/logo.svg) +- [所有默认头像](https://github.com/superseriousbusiness/gotosocial/blob/main/web/assets/default_avatars) + +根据许可证条款，你可以： + +- 分享 — 在任何媒介或格式中复制、传播上述材料。 +- 演绎 — 混合、转换与再创作上述材料，并用于任何目的，包括商业用途。 + +### 团队成员 + +按字母顺序（... 和气味顺序）排列： + +- daenney +- f0x \[[通过 liberapay 捐赠](https://liberapay.com/f0x)\] +- kim \[在 @ [codeberg](https://codeberg.org/gruf) 查看我的代码, 或在 @ [@kim](https://k.iim.gay/@kim) 找到我\] +- tobi \[[通过 liberapay 捐赠](https://liberapay.com/GoToSocial/)\] +- vyr + +### 特别鸣谢 + +特别感谢来自 [go-fed](https://github.com/go-fed/activity) 的 CJ：没有你的工作，GoToSocial 不可能实现。 + +感谢所有使用 GtS 的人，包括提交问题的，提出改进建议的，提供资金支持的，以及以其他方式支持或鼓励该项目的人！ + +--- + +## 赞助与资金支持 + +**有关企业赞助的更新：我们欢迎与符合我们价值观的组织进行赞助合作；请参阅以下条件** + +### 众筹 + +![open collective 标准树懒 徽章](https://opencollective.com/gotosocial/tiers/standard-sloth/badge.svg?label=Standard%20Sloth&color=brightgreen) ![open collective 稳定树懒 徽章](https://opencollective.com/gotosocial/tiers/stable-sloth/badge.svg?label=Stable%20Sloth&color=green) ![open collective 特别树懒 徽章](https://opencollective.com/gotosocial/tiers/special-sloth/badge.svg?label=Special%20Sloth&color=yellowgreen) ![open collective 糖果树懒 徽章](https://opencollective.com/gotosocial/tiers/sugar-sloth/badge.svg?label=Sugar%20Sloth&color=blue) + +如果你希望为 GoToSocial 捐款以支持开发，[你可以通过我们的 OpenCollective 捐助](https://opencollective.com/gotosocial#support)！ + +![LiberaPay 赞助人](https://img.shields.io/liberapay/patrons/GoToSocial.svg?logo=liberapay) ![通过 LiberaPay 接收捐赠](https://img.shields.io/liberapay/receives/GoToSocial.svg?logo=liberapay) + +如果你喜欢通过 LiberaPay 赞助，我们也有一个 LiberaPay 帐户！你可以在[这里找到我们](https://liberapay.com/GoToSocial/)。 + +通过我们 OpenCollective 和 Liberapay 账户的众筹捐款将用于支付核心团队的工资、服务器成本以及 GtS 的艺术、设计等其他开支。 + +💕 🦥 💕 谢谢你们！ + +### 企业赞助 + +GoToSocial 欢迎与符合我们价值观的组织进行合作。在此对您的支持表示感谢，我们将在存储库和文档中展示你的 Logo、网站及简短的标语。赞助有以下限制： + +1. GoToSocial 的项目方向始终由核心团队完全掌控，永远不会受到企业赞助的支配或影响。这是不可商量的。当然，企业同样可以像任何其他用户一样建议/请求功能，但不会获得特殊待遇。 + +2. 企业赞助取决于你的组织是否符合我们团队的伦理准则。这不是一套具体的规则，而是“你的公司是否造成了伤害？”的问题。例如，国防行业的不需要申请，因为答案显然是肯定的！ + +如果在阅读后您仍有兴趣赞助我们，那太好了！请通过 admin@gotosocial.org 与我们联系以进一步讨论 :) + +### NLnet + +NGIZero logo + +结合以上众筹来源，2023 年 GoToSocial Alpha 阶段的开发得到了 [NGI0 Entrust Fund](https://nlnet.nl/entrust/) 旗下的 [NLnet](https://nlnet.nl/) 提供的 50,000 欧元资助。详情请见[此处](https://nlnet.nl/project/GoToSocial/#ack)。成功的资助申请存档在[此处](https://github.com/superseriousbusiness/gotosocial/blob/main/archive/nlnet/2022-next-generation-internet-zero.md)。 + +2024 年 GoToSocial Beta 阶段的开发将从 [NGI0 Entrust Fund](https://nlnet.nl/entrust/) 旗下的 [NLnet](https://nlnet.nl/) 那里再获得 50,000 欧元的资助。 + +--- + +## 许可 + +![GNU AGPL 徽标](https://www.gnu.org/graphics/agplv3-155x51.png) + +GoToSocial 是自由软件，采用 [GNU AGPL v3 许可](https://github.com/superseriousbusiness/gotosocial/blob/main/LICENSE)。我们鼓励你对代码进行派生和修改，进行各种实验。 + +有关 AGPL 和 GPL 许可之间的区别，请参阅[这里](https://www.gnu.org/licenses/why-affero-gpl.html)，关于 GPL 许可（包括 AGPL）的常见问题解答，请参阅[这里](https://www.gnu.org/licenses/gpl-faq.html)。 + +如果你修改了 GoToSocial 的源码，并以网络可访问的方式运行修改后的代码，你*必须*根据许可的指引提供你对源码的修改副本： + +> 如果你修改了程序，并且你的修改版本支持通过计算机网络与用户进行远程交互，你的版本必须显著地向所有这些用户提供获得你的版本对应源码的机会，方式需为通过网络服务器以不收费的方式，或通过某种标准或习惯方式提供以便于复制软件。 + +版权所有 (C) 全体 GoToSocial 贡献者 + + + diff --git a/docs/locales/zh/.readthedocs.yaml b/docs/locales/zh/.readthedocs.yaml new file mode 100644 index 000000000..bfeb50cf3 --- /dev/null +++ b/docs/locales/zh/.readthedocs.yaml @@ -0,0 +1,17 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "mambaforge-22.9" # https://docs.readthedocs.io/en/stable/guides/conda.html#making-builds-faster-with-mamba + +mkdocs: + configuration: "docs/locales/zh/mkdocs.yml" + +conda: + environment: "docs/environment.yml" diff --git a/docs/locales/zh/admin/backup_and_restore.md b/docs/locales/zh/admin/backup_and_restore.md new file mode 100644 index 000000000..2a5b50bf1 --- /dev/null +++ b/docs/locales/zh/admin/backup_and_restore.md @@ -0,0 +1,223 @@ +# 备份和恢复 + +由于 GoToSocial 数据库包含了实例以及所有用户的签名密钥，备份是至关重要的。如果这些密钥丢失，您将无法再从此域名进行联合与交流。请记住加密备份，以确保数据在静置时的安全。 + +除了灾难恢复之外，还有其他一些保持备份的好理由。您可以考虑以下几种可能的场景： + +* 您想关闭实例，但可能会在以后重新创建，并且不希望破坏联合功能。 +* 出于某种原因，您需要迁移到不同的数据库（从 Postgres 到 SQLite 或反之亦然）。 +* 您准备对实例进行一些调整，希望快速备份以防出错导致数据丢失。 + +## 需要备份的内容 + +### 数据库 + +大多数备份工具都内置对常见的数据库的支持，如 PostgreSQL 和 SQLite。请确保首先查看他们的文档，因为它们通常会详细说明备份成功完成和恢复所需满足的某些注意事项和条件。 + +### 媒体文件 + +本站媒体文件应被备份。您可以使用 [GoToSocial CLI](cli.md#gotosocial-admin-media-list-local) 列出属于您的实例及其用户的所有媒体文件。 + +外站媒体无需备份。这可以有效地控制备份大小。外站媒体会从原始实例获取，就像因为媒体保留而被修剪掉后再次获取一样。 + +## 如何备份 + +您可以通过以下几种方式进行备份： + +* 为实例和数据库运行所在的 VM/机器制作镜像 +* 使用 CLI 转储 GoToSocial 的状态 +* 备份数据库和媒体文件 +* 使用备份软件 + +尽管设置备份软件可能需要更多工作，但这无疑是最佳选择。它确保了一致和加密的备份，并可以抵御文件系统损坏，而磁盘快照和复制原始数据库及媒体文件无法做到这一点。 + +### 镜像您的磁盘 + +如果您在 VPS（云端的远程机器）上运行 GoToSocial，制作附加到 VPS 的磁盘镜像可能是保存所有数据库条目和媒体的最简单方法。这将保留整个磁盘。许多 VPS 提供商提供定时自动创建备份的选项，因此即使数据丢失，您也可以随时恢复。 + +优点： + +* 相对容易操作。 +* 易于自动化（视具体的 VPS 而定）。 +* 保留完整的媒体和数据库条目。 + +缺点： + +* 可能会根据您的 VPS 产生额外费用。 +* 可能也会保留您不需要的其他程序运行的数据。 +* 与供应商绑定，数据难以迁移。 + +### 使用 GoToSocial CLI + +GoToSocial CLI 工具还提供了从实例备份和恢复数据的命令，这将保留所有必要的最少数据以备份和恢复您的实例，而不破坏与其他实例的联邦。 + +将**保留**的内容有： + +* 所有本站账户条目，包括私钥和公钥。 +* 关注/被关注的外站账户，包括公钥。 +* 关注/关注请求。 +* 实例屏蔽列表。 +* 账户屏蔽列表。 +* 账户封禁列表。 +* 用户名和密码条目，电子邮件地址。 + +将**丢弃**的： + +* 所有贴文。 +* 媒体。 +* 收藏。 +* 书签。 +* 置顶。 +* 应用程序。 +* 令牌。 + +生成的备份文件将是一个以行分隔的 JSON 对象序列（而不是 JSON 数组！）。例如： + +```json +{"type":"account","id":"01F8MH5NBDF2MV7CTC4Q5128HF","createdAt":"2021-08-31T12:00:53.985645Z","username":"1happyturtle","locked":true,"language":"en","uri":"http://localhost:8080/users/1happyturtle","url":"http://localhost:8080/@1happyturtle","inboxURI":"http://localhost:8080/users/1happyturtle/inbox","outboxURI":"http://localhost:8080/users/1happyturtle/outbox","followingUri":"http://localhost:8080/users/1happyturtle/following","followersUri":"http://localhost:8080/users/1happyturtle/followers","featuredCollectionUri":"http://localhost:8080/users/1happyturtle/collections/featured","actorType":"Person","privateKey":"-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAzLP7oyyR+BU9ejn0CN9K+WpX3L37pxUcCgZAGH5lf3cGPZjz\nausfsFME94OjVyzw3K5M2beDkZ4E+Fak46NLtakLB1yovy9jKtj4Y4txHoMvRJLz\neUPxdfeXtpx2d3FDj++Uq4DEE0BhbePXhTGJWaNdC9MQmWKghJnCS5mrnFkdpEFx\njUz9l0UHl2Z4wppxPdpt7FyevcdfKqzGsAA3BxTM0dg47ZJWjtcvfCiSYpAKFNJY\nfKhKn9T3ezZgrLsF+o0IpD23KxWe1X4d5lgJRU9T4FmLmbvyJKUnfgYXbSEvLUcq\n79WbhgRcWwxWubjmWXgPGwzULVhhpYlwd2Cv3wIDAQABAoIBAGF+MxHjD15VV2NY\nKKb1GjMx98i1Xx6TijgoA+zmfha4LGu35e79Lql+0LXFp0zEpa6lAQsMQQhgd0OD\nmKKmSk+pxAvskJ4FxrhIf/yBFA4RMrj5OCaAOocRtdsOJ8n5UtFBrNAF0tzMY9q/\nkgzoq97aVF1mV9iFxaeBx6zT8ozSdqBq1PK/3w1dVg89S5tfKYc7Q0lQ00SfsTnd\niTDClKyqurebo9Pt6M7gXavgg3tvBlmwwr6XHs34Leng3oiN9mW8DVzaBMPzn+rE\nxF2eqs3v9vVpj8es88OwCh5P+ff8vJYvhu7Fcr/bJ8BItBQwfb8QBDATg/MXU2BI\n2ssW6AECgYEA4wmIyYGeu9+hzDa/J3Vh8GnlVNUCohHcChQdOsWsFXUgpVlUIHrX\neKHn42vD4Rzy52/YzJts4NkZTM9sL+kEXIEcpMG/S9xIIud7U0m/hMSAlmnJK/9j\niEXws3o4jo0E77jnRcBdIjpG4K5Eekm0DSR3SFhtZfEdN2DWPvu7K98CgYEA5tER\n/qJwFMc51AobMU87ZjXON7hI2U1WY/pVF62jSl0IcSsnj2riEKWLrs+GRG+HUg+U\naFSqAHcxaVHA0h0AYR8RopAhDdVKh0kvB8biLo+IEzNjPv2vyn0yRN5YSfXdGzyJ\nUjVU6kWdQOwmzy86nHgFaqEx7eofHIaGZzJK/AECgYEAu2VNQHX63TuzQuoVUa5z\nzoq5vhGsALYZF0CO98ndRkDNV22qIL0ESQ/qZS64GYFZhWouWoQXlGfdmCbFN65v\n6SKwz9UT3rvN1vGWO6Ltr9q6AG0EnYpJT1vbV2kUcaU4Y94NFue2d9/+TMnKv91B\n/m8Q/efvNGuWH/WQIaCKV6UCgYBz89WhYMMDfS4M2mLcu5vwddk53qciGxrqMMjs\nkzsz0Va7W12NS7lzeWaZlAE0gf6t98urOdUJVNeKvBoss4sMP0phqxwf0eWV3ur0\ncjIQB+TpGGikLVdRVuGY/UXHKe9AjoHBva8B3aTpB3lbnbNJBXZbIc1uYq3sa5w7\nXWWUAQKBgH3yW73RRpQNcc9hTUssomUsnQQgHxpfWx5tNxqod36Ytd9EKBh3NqUZ\nvPcH6gdh7mcnNaVNTtQOHLHsbPfBK/pqvb3MAsdlokJcQz8MQJ9SGBBPY6PaGw8z\nq/ambaQykER6dwlXTIlU20uXY0bttOL/iYjKmgo3vA66qfzS6nsg\n-----END RSA PRIVATE KEY-----\n","publicKey":"-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEAzLP7oyyR+BU9ejn0CN9K+WpX3L37pxUcCgZAGH5lf3cGPZjzausf\nsFME94OjVyzw3K5M2beDkZ4E+Fak46NLtakLB1yovy9jKtj4Y4txHoMvRJLzeUPx\ndfeXtpx2d3FDj++Uq4DEE0BhbePXhTGJWaNdC9MQmWKghJnCS5mrnFkdpEFxjUz9\nl0UHl2Z4wppxPdpt7FyevcdfKqzGsAA3BxTM0dg47ZJWjtcvfCiSYpAKFNJYfKhK\nn9T3ezZgrLsF+o0IpD23KxWe1X4d5lgJRU9T4FmLmbvyJKUnfgYXbSEvLUcq79Wb\nhgRcWwxWubjmWXgPGwzULVhhpYlwd2Cv3wIDAQAB\n-----END RSA PUBLIC KEY-----\n","publicKeyUri":"http://localhost:8080/users/1happyturtle#main-key"} +{"type":"account","id":"01F8MH0BBE4FHXPH513MBVFHB0","createdAt":"2021-09-08T10:00:53.985634Z","username":"weed_lord420","locked":true,"language":"en","uri":"http://localhost:8080/users/weed_lord420","url":"http://localhost:8080/@weed_lord420","inboxURI":"http://localhost:8080/users/weed_lord420/inbox","outboxURI":"http://localhost:8080/users/weed_lord420/outbox","followingUri":"http://localhost:8080/users/weed_lord420/following","followersUri":"http://localhost:8080/users/weed_lord420/followers","featuredCollectionUri":"http://localhost:8080/users/weed_lord420/collections/featured","actorType":"Person","privateKey":"-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEAzsCcTHzwIgpWKVvut0Q/t1bFwnbj9hO6Ic6k0KXCXbf6qi0b\nMIyLRZr8DS61mD+SPSO2QKEL647xxyW2D8YGtwN6Cc6MpWETsWJkNtS8t7tDL//P\nceYpo5LiqKgn0TXj0Pq8Lvb7rqpH8QJ2EVm14SK+elhKZW/Bi5ZOEwfL8pw6EHI4\nus6VxCNQ099dksu++kbdD7zxqEKnk/4zOttYt0whlVrxzkibTjlKdlSlTYpIstU+\nfNyYVE0xWvrn+yF7jVlEwZYOFGfZbpELadrdOr2k1hvAk7upkrpKmLqYfwqD/xPc\nqwtx0iS6AEnmkSiTcAvju5vLkoLFRU7Of4AZ2wIDAQABAoIBAEAA4GHNS4k+Ke4j\nx4J0XkUjV5UbuPY0pSpSDjOJHOJmUfLcg85Ds9mYYO6zxwOaqmrC42ieclI5rh84\nTWQUqX9+VAk1J9UKeE4xZ1SSBtnZ3rK9PjrERZ+dmQ0dATaCuEO5Wwgu7Trk++Bg\nIqy8WNGZL94v9tfwALp1jTXW9AvmQoNdCFBP62vcmYW4YLjnggxLCFTA8YKfdePa\nTuxxY6uLkeBbxzWpbRU2+bmlxd5OnCkiRSMHIX+6JdtCu2JdWpUTCnWrFi2n1TZz\nZQx9z5rvowK1O785jGMFum5vBWpjIU8sJcXmPjGMU25zzmrhzfmkJsTXER3CXoUo\nSqSPqgECgYEA78OR7bY5KKQQ7Lyz6dru4Fct5P/OXTQoOg5aS7TKb95LVWj+TANn\n5djwIbLmAUV30z0Id9VgiZOL0Hny8+3VV9eU088Z408pAy5WQrL3dB8tZLUJSq5c\n5k6X15/VjWOOZKppDxShzoV3mcohrnwVwkv4fhPFQQOJJBYz6xurWs0CgYEA3MDE\nsDMd9ahzO0dl62ynojkkA8ZTcn2UdyvLpGj9UxT5j9vWF3CfqitXgcpNiVSIbxqQ\nbo/pBch7c/2Xakv5zkdcrJj5/6gyr+m1/tK2o7+CjDaSE4SYwufXx+qkl03Zpyzt\nKdOi7Hz/b2tdjump7ECEDE45mG2ea8oSnPgXl0cCgYBkGGFzu/9g2B24t47ksmHH\nhp3CXIjqoDurARLxSCi7SzJoFc0ULtfRPSAC8YzUOwwrQ++lF4+V3+MexcqHy2Kl\nqXqYcn18SC/3BAE/Fzf3Yoyw3mNiqihefbEmc7PTsxxfKkVx5ksmzNGBgsFM9sCe\nvNigyeAvpCo8xogmPwbqgQKBgE34mIBTzcUzFmBdu5YH7r3RyPK8XkUWLhZZlbgg\njTmHMw6o61mkIgENBf+F4RUckoQLsfAbTIcKZPB3JcAZzcYaVpVwAv1V/3E671lu\nO6xivE2iCL50GzDcis7GBhSbHsF5kNsxMV6uV9qW5ZjQ13/m2b0u9BDuxwHzgdeH\nmW2JAoGAIUOYniuEwdygxWVnYatpr3NPjT3BOKoV5i9zkeJRu1hFpwQM6vQ4Ds5p\nGC5vbMKAv9Cwuw62e2HvqTun3+U2Y5Uived3XCpgM/50BFrFHCfuqXEnu1bEzk5z\n9mIhp8uXPxzC5N7tRQfb3/eU1IUcb6T6ksbr2P81z0j03J55erg=\n-----END RSA PRIVATE KEY-----\n","publicKey":"-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEAzsCcTHzwIgpWKVvut0Q/t1bFwnbj9hO6Ic6k0KXCXbf6qi0bMIyL\nRZr8DS61mD+SPSO2QKEL647xxyW2D8YGtwN6Cc6MpWETsWJkNtS8t7tDL//PceYp\no5LiqKgn0TXj0Pq8Lvb7rqpH8QJ2EVm14SK+elhKZW/Bi5ZOEwfL8pw6EHI4us6V\nxCNQ099dksu++kbdD7zxqEKnk/4zOttYt0whlVrxzkibTjlKdlSlTYpIstU+fNyY\nVE0xWvrn+yF7jVlEwZYOFGfZbpELadrdOr2k1hvAk7upkrpKmLqYfwqD/xPcqwtx\n0iS6AEnmkSiTcAvju5vLkoLFRU7Of4AZ2wIDAQAB\n-----END RSA PUBLIC KEY-----\n","publicKeyUri":"http://localhost:8080/users/weed_lord420#main-key"} +{"type":"account","id":"01F8MH17FWEB39HZJ76B6VXSKF","createdAt":"2021-09-05T10:00:53.985641Z","username":"admin","locked":true,"language":"en","uri":"http://localhost:8080/users/admin","url":"http://localhost:8080/@admin","inboxURI":"http://localhost:8080/users/admin/inbox","outboxURI":"http://localhost:8080/users/admin/outbox","followingUri":"http://localhost:8080/users/admin/following","followersUri":"http://localhost:8080/users/admin/followers","featuredCollectionUri":"http://localhost:8080/users/admin/collections/featured","actorType":"Person","privateKey":"-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEAxr2e1pqfLwwUCwHUdx56Mxnq5Kzc2EBwqN6jIPjiqVaG5eVq\nhujDhdqwMq0hnpBSPzLnvjiOtEh7Bwhx0MjuC/GRPTM9oNWPYD4PcjX5ofrubyLR\nBI97qD0SbyzUWzeyBi6R5tpW8LK1MJXNbnYlz5WouEiC4mY77ulri0EN2hCq80wg\nfvtEjEvELcKBqIytKH3rutIzfAyqXD7LSQ8UDoNh9GHyIfq8Zj32gWVk2MiPI3+G\n8kQJDmD8CKEasnrGVdSJBQUg3xDAtOibPXLP+07AIsKYMon35hVNvQNQPS7ru/Bk\nRhhGp2R44zqj6L9mxYbSrhFAaKDedu8oVe1aLQIDAQABAoIBAGK0aIADOU4ffJDe\n7sveiih5Fc1PATwx/QIR2QkWM1SREdx6LYclcX44V8xDanAbE44p1SkHY/CsEtYy\nXnyoXnn2FwFDQrdveY7+I6PApOPLAcKWkyLltC+hbVdj92/6YGNrm7EA/a77wruH\nmwjiivLnTG2CLecNiXSl33DA9YU4Yz+2Tza3IpTdjt8c/dz/BKKaxaWV+i9ew5VR\nioo5v51B+J8PrneCM/p8LGiLV148Njr0JqV6eFy1JuzItYMYdc3Fp+YnMzsuMZEA\n1akMcoln/ucVJyOFnCn6jx47nIoPZLl1KxX3aRDRfvrejm6W4yAkkTmR5voSRqax\njPL3rI0CgYEA9Acu4TO8xJ3uGaUad0N9JTYQVSmtAaE/g+df9LGMSzoj8X95S4xE\nQsGPqNGDm2VWADJjK4P05twZ+LfsfSKQ86wbp4/gbgnXpqB1P5Lty/B7KxiTnNwt\nwb1WGWTCukxfUSL3PRyf8uylkrg72RxKiBx4zKO3WVSLWOZWrFtn0qMCgYEA0H2p\nJs9Nv20ADOOX5tQ7+ruS6/B/Fhyj5fhflSYCAtOW7aME7+zQKJyqSQZ4b2Aub3Tp\nGIaUbRIGzjHyuTultFFWvjU3H5aI/0g1G9WKaBhNkyTIYVmMKtYyhXNvouWing8x\noraWx8TTBP8Cdnnk+QgdR2fpug8cghKupp5wvO8CgYA1JFtRL7MsHjh73TimQExA\njkWARlMmx7bNQtXis8eZmk+5h8kiaqly4DQoz3eZn7fa0x5Fm7b5j3UYdPVLSvvG\nFPTwyKRXUk1kPA1MivK+NuCbwf5jao+MYW8emJLPf1JCmRq+dD1g6aglC3n9Dewt\nOAYWipCjI4Y1FfRKFJ3HgQKBgEAb47+DTyzln3ZXJYZdDHR06SCTuwBZnixAy2NZ\nZJTp6yb3UbVU5E0Yn2QFEVNuB9lN4b8g4tMHEACnazN6G+HugPXL9z9HUqjs0yfT\n6dNIZdIxJUyJ9IfXhYFzlYhJhE+F7IVUD9kttJV8tI0pvja1QAuM8Fm9+84jYIDr\nh08RAoGAMYbjKHbtejcHBwt1kIcSss0cDmlZbBleJo8tdmdg4ndf5GE9N4/EL7tq\nm2zYSfr7OVdnOwRhoO+xF/6d1L7+TR1wz+k2fuMsI71aM5Ocp1nYTutjIkBTcldZ\nZzvjOgZWng5icuRLQQiDSKG5uqazqL/xGXkijb4kp4WW6myWY3c=\n-----END RSA PRIVATE KEY-----\n","publicKey":"-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEAxr2e1pqfLwwUCwHUdx56Mxnq5Kzc2EBwqN6jIPjiqVaG5eVqhujD\nhdqwMq0hnpBSPzLnvjiOtEh7Bwhx0MjuC/GRPTM9oNWPYD4PcjX5ofrubyLRBI97\nqD0SbyzUWzeyBi6R5tpW8LK1MJXNbnYlz5WouEiC4mY77ulri0EN2hCq80wgfvtE\njEvELcKBqIytKH3rutIzfAyqXD7LSQ8UDoNh9GHyIfq8Zj32gWVk2MiPI3+G8kQJ\nDmD8CKEasnrGVdSJBQUg3xDAtOibPXLP+07AIsKYMon35hVNvQNQPS7ru/BkRhhG\np2R44zqj6L9mxYbSrhFAaKDedu8oVe1aLQIDAQAB\n-----END RSA PUBLIC KEY-----\n","publicKeyUri":"http://localhost:8080/users/admin#main-key"} +{"type":"account","id":"01F8MH1H7YV1Z7D2C8K2730QBF","createdAt":"2021-09-06T10:00:53.985643Z","username":"the_mighty_zork","locked":true,"language":"en","uri":"http://localhost:8080/users/the_mighty_zork","url":"http://localhost:8080/@the_mighty_zork","inboxURI":"http://localhost:8080/users/the_mighty_zork/inbox","outboxURI":"http://localhost:8080/users/the_mighty_zork/outbox","followingUri":"http://localhost:8080/users/the_mighty_zork/following","followersUri":"http://localhost:8080/users/the_mighty_zork/followers","featuredCollectionUri":"http://localhost:8080/users/the_mighty_zork/collections/featured","actorType":"Person","privateKey":"-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEApBmF8U+or+E0mgUMH3LE4uRIWzeV9rhYnvSMm9OpOsxwJiss\n5mEA/NtPHvQlq2UwrqXX89Wvu94K9EzZ4VyWYQGdxaiPpt17vRqUfsHUnXkY0pvC\nC9zt/aNlJtdt2xm+7PTC0YQd4+E1FX3aaoUPJL8MXzNlpJzaUtuwLZe1iBmFfatZ\nFHptEgc4nlf6TNLTzj3Yw1/7zIGVS8Vi7VquHc0Xo8dRiL2RxCGzLWnwL6GlrxY1\ntMhsUg467XeoiwegFCpcIhAhPFREKoTnCEksL/N0rpXl7m6CAy5uqBGs5mMXnXlq\nefr58l0j2dU6zc60LCHH9TJC+roXsKJhy9sx/QIDAQABAoIBAFa+UypbFG1cW2Tr\nNBxPm7ngOEtXl8MicV4dIVKh0TwOo13ZxtNFBbOj7jALmPn/9HrtmbkABPQHDL1U\n/nt9aNSAeTjpwH3RaD5vFX3n0g8n2zJBOZLxxzAjNi4RBLYj5uP1AiKkdvRlsJza\nuSFDkty2zMBqN9mLPHE+RePj5Qa6tjYfIQqQzu/+YnYMlXHoC2yHNKsvz6S5FhVj\nv5zATv2JlJQH3RSmhuPOah73iQnKCLzYYEAHleawKrCg/rZ3ht37Guvabeq7MqQN\nvi9pJdAA+RMxPsboHajskePjOTYJgKQSxEAMRTMfBR40aZxklxQL0EoBd1Y3CHXh\nfMg0xWECgYEA0ORrpJ1A2WNQwKcDDeBBsaJqWF4EraoFzYrugKZrAYEeVyuGD0zq\nARUaWkZTZ1f6wQ10i1WxAuKlBEds7QsLdZzLsA4um4JlBroCZiYfPnmTtb8op1LY\nFqeYTByvAmnfWWTuOI67GX9ruLg8tEGuz38kuQVSxYs51its3tScNPUCgYEAyRst\nwRbqpOqnwoRoS6pxv0Vpc3nUcfaVYwsg/qobJkiwAdlUYeE7alvEY926VW4cvU/X\nhy3L1punAqnyLI7uuqCefXEbNxO0Cebyy4Kv2Ye1uzl0OHsJczSNdfpNqfAIKwtN\nHLCYDGCsluQhz+I/5Pd0dT+JDPPW9hKS2HG7o+kCgYBqugn1VRLo/sEnbS02TbnC\n1ESZWY/yWsgUOEObH2vUnO+vgeFAt/9nBi0sqnm6d0z6jbFZ7zI9UycUhJm2ksoM\nEUxQay6M7ZZIVYkcP6X++YbqePyAYOdey8oYOR+BkC45MkQ0SVh2so+LFTaOsnBq\nO3+7uGiN3ZBzSESbpO0acQKBgQCONrsXZeZO82XpB4tdns3LbgGRWKEkajTgEnml\nvZNvck2NMSwb/5PttbFe0ei4CyMluPV4MamJPQ9Qse+BFR67OWR63uZY/4T8z6X4\nxpUmZnLcUFfgrRlUr+AtgvEy8HxGPDquxC7x6deC6RcEFEIM3/UqCOEZGMJ1x1Ky\n31LLKQKBgGCKwVgQ8+4JyHZFkie3YdHhxJDokgY+Opb0HNnoBY/lZ54UMCCJQPS2\n0XPSu651j/3adr3RQneU04gF6U2/D5JzFEV0kUsqZ4Zy2EEU0LU4ibus0gyomSpK\niWhU4QrC/M4ELxYZinlNu3ThPWNQ/PMNteVWfdgOcV7uUWl0ViFp\n-----END RSA PRIVATE KEY-----\n","publicKey":"-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEApBmF8U+or+E0mgUMH3LE4uRIWzeV9rhYnvSMm9OpOsxwJiss5mEA\n/NtPHvQlq2UwrqXX89Wvu94K9EzZ4VyWYQGdxaiPpt17vRqUfsHUnXkY0pvCC9zt\n/aNlJtdt2xm+7PTC0YQd4+E1FX3aaoUPJL8MXzNlpJzaUtuwLZe1iBmFfatZFHpt\nEgc4nlf6TNLTzj3Yw1/7zIGVS8Vi7VquHc0Xo8dRiL2RxCGzLWnwL6GlrxY1tMhs\nUg467XeoiwegFCpcIhAhPFREKoTnCEksL/N0rpXl7m6CAy5uqBGs5mMXnXlqefr5\n8l0j2dU6zc60LCHH9TJC+roXsKJhy9sx/QIDAQAB\n-----END RSA PUBLIC KEY-----\n","publicKeyUri":"http://localhost:8080/users/the_mighty_zork#main-key"} +{"type":"block","id":"01FEXXET6XXMF7G2V3ASZP3YQW","createdAt":"2021-09-08T09:00:53.965362Z","uri":"http://localhost:8080/users/1happyturtle/blocks/01FEXXET6XXMF7G2V3ASZP3YQW","accountId":"01F8MH5NBDF2MV7CTC4Q5128HF","targetAccountId":"01F8MH5ZK5VRH73AKHQM6Y9VNX"} +{"type":"account","id":"01F8MH5ZK5VRH73AKHQM6Y9VNX","createdAt":"2021-08-31T12:00:53.985646Z","username":"foss_satan","domain":"fossbros-anonymous.io","locked":true,"language":"en","uri":"http://fossbros-anonymous.io/users/foss_satan","url":"http://fossbros-anonymous.io/@foss_satan","inboxURI":"http://fossbros-anonymous.io/users/foss_satan/inbox","outboxURI":"http://fossbros-anonymous.io/users/foss_satan/outbox","followingUri":"http://fossbros-anonymous.io/users/foss_satan/following","followersUri":"http://fossbros-anonymous.io/users/foss_satan/followers","featuredCollectionUri":"http://fossbros-anonymous.io/users/foss_satan/collections/featured","actorType":"Person","publicKey":"-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEA2OyVgkaIL9VohXKYTh319j4OouHRX/8QC7piXj71k7q5RDzEyvis\nVZBc5/C1/crCpxt895i0Ai2CiXQx+dISV7s/JBhAGl8s7TQ8jLlMuptrI0+sdkBC\nlu8pU0qQmoeXVnlquOzNmqGufUxIDtLXLZDN17qf/7vWA23q4d0tG5KQhGGGKiVM\n61Ufvr9MmgPBSpyUvYMAulFlz1264L49aGWeVgOz3qUQzqtxjrP0kaIbeyt56miP\nKr5AqkRgSsXci+FAo6suxR5gzo9NgleNkbZWF9MQyKlawukPwZUDSh396vtNQMee\n/4mto7mAXw8iio0IacrYO3F7iyewXnmI/QIDAQAB\n-----END RSA PUBLIC KEY-----\n","publicKeyUri":"http://fossbros-anonymous.io/users/foss_satan/main-key"} +{"type":"follow","id":"01F8PYDCE8XE23GRE5DPZJDZDP","createdAt":"2021-09-08T09:00:54.749465Z","uri":"http://localhost:8080/users/the_mighty_zork/follow/01F8PYDCE8XE23GRE5DPZJDZDP","accountId":"01F8MH1H7YV1Z7D2C8K2730QBF","targetAccountId":"01F8MH5NBDF2MV7CTC4Q5128HF"} +{"type":"follow","id":"01F8PY8RHWRQZV038T4E8T9YK8","createdAt":"2021-09-06T12:00:54.749459Z","uri":"http://localhost:8080/users/the_mighty_zork/follow/01F8PY8RHWRQZV038T4E8T9YK8","accountId":"01F8MH1H7YV1Z7D2C8K2730QBF","targetAccountId":"01F8MH17FWEB39HZJ76B6VXSKF"} +{"type":"domainBlock","id":"01FF22EQM7X8E3RX1XGPN7S87D","createdAt":"2021-09-08T10:00:53.968971Z","domain":"replyguys.com","createdByAccountID":"01F8MH17FWEB39HZJ76B6VXSKF","privateComment":"i blocked this domain because they keep replying with pushy + unwarranted linux advice","publicComment":"reply-guying to tech posts","obfuscate":false} +{"type":"user","id":"01F8MGYG9E893WRHW0TAEXR8GJ","createdAt":"2021-09-08T10:00:53.97247Z","accountID":"01F8MH0BBE4FHXPH513MBVFHB0","encryptedPassword":"$2y$10$ggWz5QWwnx6kzb9g0tnIJurFtE0dhr5Zfeaqs9iFuUIXzafQlJVZS","locale":"en","lastEmailedAt":"0001-01-01T00:00:00Z","confirmationToken":"a5a280bd-34be-44a3-8330-a57eaf61b8dd","confirmationTokenSentAt":"2021-09-08T10:00:53.972472Z","unconfirmedEmail":"weed_lord420@example.org","moderator":false,"admin":false,"disabled":false,"approved":false} +{"type":"user","id":"01F8MGWYWKVKS3VS8DV1AMYPGE","createdAt":"2021-09-05T10:00:53.972475Z","email":"admin@example.org","accountID":"01F8MH17FWEB39HZJ76B6VXSKF","encryptedPassword":"$2y$10$ggWz5QWwnx6kzb9g0tnIJurFtE0dhr5Zfeaqs9iFuUIXzafQlJVZS","currentSignInAt":"2021-09-08T09:50:53.972477Z","lastSignInAt":"2021-09-08T08:00:53.972477Z","chosenLanguages":["en"],"locale":"en","lastEmailedAt":"2021-09-08T09:30:53.972478Z","confirmedAt":"2021-09-05T10:00:53.972478Z","moderator":true,"admin":true,"disabled":false,"approved":true} +{"type":"user","id":"01F8MGVGPHQ2D3P3X0454H54Z5","createdAt":"2021-09-06T22:00:53.97248Z","email":"zork@example.org","accountID":"01F8MH1H7YV1Z7D2C8K2730QBF","encryptedPassword":"$2y$10$ggWz5QWwnx6kzb9g0tnIJurFtE0dhr5Zfeaqs9iFuUIXzafQlJVZS","currentSignInAt":"2021-09-08T09:30:53.972481Z","lastSignInAt":"2021-09-08T08:00:53.972481Z","chosenLanguages":["en"],"locale":"en","lastEmailedAt":"2021-09-08T09:05:53.972482Z","confirmationTokenSentAt":"2021-09-06T22:00:53.972483Z","confirmedAt":"2021-09-07T00:00:53.972482Z","moderator":false,"admin":false,"disabled":false,"approved":true} +{"type":"user","id":"01F8MH1VYJAE00TVVGMM5JNJ8X","createdAt":"2021-09-06T22:00:53.972485Z","email":"tortle.dude@example.org","accountID":"01F8MH5NBDF2MV7CTC4Q5128HF","encryptedPassword":"$2y$10$ggWz5QWwnx6kzb9g0tnIJurFtE0dhr5Zfeaqs9iFuUIXzafQlJVZS","currentSignInAt":"2021-09-08T09:30:53.972485Z","lastSignInAt":"2021-09-08T08:00:53.972486Z","chosenLanguages":["en"],"locale":"en","lastEmailedAt":"2021-09-08T09:05:53.972487Z","confirmationTokenSentAt":"2021-09-06T22:00:53.972487Z","confirmedAt":"2021-09-07T00:00:53.972487Z","moderator":false,"admin":false,"disabled":false,"approved":true} +{"type":"instance","id":"01BZDDRPAB8J645ABY31HHF68Y","createdAt":"2021-09-08T10:00:54.763912Z","domain":"localhost:8080","title":"localhost:8080","uri":"http://localhost:8080","reputation":0} +``` + +有关如何使用命令导入/导出的信息，参见[此处](cli.md#gotosocial-admin-export)。尽管 `export` 命令不会备份媒体，但可以使用 [`media list-local`](cli.md#gotosocial-admin-media-list-local) 命令来确定应该保留哪些媒体文件。 + +优势： + +* 数据库无关：导出的数据采用了一种通用格式，可以使用 `import` 命令将这些数据插入 Postgres 或 SQLite 数据库中。 +* 轻量级：仅保留必要的内容，因此备份文件可以非常小（甚至小到可以通过电子邮件发送）。备份/导入命令只需几秒钟即可运行。 +* 易读格式：输出是 JSON 格式。 + +劣势： + +* 贴文/收藏等的丢失：除非你愿意丢失某些内容，否则不要这样进行备份/恢复。 +* 需要使用 GoToSocial CLI 工具将数据插回数据库，除非你为此编写自定义工具。 + +### 备份你的数据库文件和媒体 + +无论你是使用 PostgreSQL 还是 SQLite 作为 GoToSocial 数据库，都可以直接使用类似 [rclone](https://rclone.org/) 的工具来备份数据库文件，或者遵循 [Postgres 数据备份的最佳实践](https://www.postgresql.org/docs/15/backup.html) 或 [SQLite 数据备份的最佳实践](https://sqlite.org/backup.html)。 + +使用 GoToSocial CLI 的媒体 [`list-attachments`](cli.md#gotosocial-admin-media-list-attachments) 和 [`list-emojis`](cli.md#gotosocial-admin-media-list-emojis) 命令来获取需要保护的媒体文件列表。 + +优势： + +* 备份相对便携 - 可以将数据从一台机器迁移到另一台。 +* 有大量文档和工具可供参考。 +* 可以根据需要有多种备份方式。 + +劣势： + +* 初次设置可能有点复杂。 +* 需要确定备份的存放位置。 +* 从备份中恢复可能比较麻烦。 +* 除非同时备份媒体，否则数据库中的媒体附件引用将会中断。 + +### 备份软件 + +备份软件专为帮助你创建、管理和恢复备份而设计。它通常知道如何安全地备份数据库，因此你不用成为 PostgreSQL 或 SQLite 备份专家。它也可以从文件系统中进行备份。 + +尽管与直接备份数据库文件的方法大致具有相同的优点和缺点，这种方法还有一些额外的好处： + +* 备份高度便携，可以从零开始恢复数据库。 +* 备份按照常规计划进行，并有可配置的保留策略。 +* 备份是增量和压缩的，以节省存储和带宽。 +* 备份是加密的。 +* 内置工具可以列出快照并从中恢复。 + +!!! tip + [Rsync.net](https://rsync.net/)、[BorgBase](https://www.borgbase.com/) 和 [Hetzner Storage](https://www.hetzner.com/storage/storage-box) 提供了可用于备份的经济实惠的存储。Rsync.net 有一种专门为 Borg 设计的备份产品，比他们的常规存储产品便宜得多。如果你只想使用 Borg 管理的备份，请在[此处注册](https://www.rsync.net/products/borg.html)。 + +#### Borgmatic + +[Borgmatic](https://torsion.org/borgmatic/) 是一个帮助使用 [Borg](https://www.borgbackup.org/) 进行备份的工具。它通过使用 YAML 的声明性配置文件驱动。BorgBase、Rsync.net 和 Hetzner 都支持 Borg。 + +!!! warning + 初始化 Borg 仓库时，确保使用强加密密钥进行设置，并将密钥安全地存放在某处。否则将无法在将来解密备份。ArchWiki 上关于 Borgmatic 的条目解释了如何安全地将你的加密密钥传递给 Borgmatic，而不在配置文件中以明文形式存储它。 + +如何使用 Borgmatic 备份数据库有其[单独的文档页面](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/)，你应当在备份前查看一下。对于使用 SQLite 的 GoToSocial，Borgmatic 的简单 `config.yaml` 如下： + + +```yaml +location: + repositories: + - path: ssh://<在你的提供商控制面板中查找ssh地址> + label: <可以是任意内容，但通常是提供商名称，例如 borgbase> + patterns_from: + - /etc/borgmatic/gotosocial_patterns + +storage: + compression: auto,zstd + archive_name_format: '{hostname}-{now:%Y-%m-%d-%H%M%S}' + retries: 5 + retry_wait: 30 + +retention: + keep_daily: 7 + keep_weekly: 6 + keep_monthly: 12 + +hooks: + before_backup: + - /usr/bin/systemctl stop gotosocial + after_backup: + - /usr/bin/systemctl start gotosocial + sqlite_databases: + - name: gotosocial + path: /path/to/sqlite.db +``` + +对于 PostgreSQL，你应该使用 `postgresql_databases`。 + +`patterns_from` 中提到的文件可以通过转换 GoToSocial CLI 媒体命令 [`list-attachments`](cli.md#gotosocial-admin-media-list-attachments) 和 [`list-emojis`](cli.md#gotosocial-admin-media-list-emojis) 的输出来创建。要生成正确的模式，您可以使用 [`media-to-borg-patterns.py`](https://github.com/superseriousbusiness/gotosocial/tree/main/example/borgmatic/media-to-borg-patterns.py) 脚本。有关 Borg 模式如何工作的详情，参见 [他们的文档](https://man.archlinux.org/man/borg-patterns.1)。 + +您需要将该文件放在您的 GoToSocial 实例上，并确保该文件是可执行的。它需要 Python 3，安装 Borg 和 Borgmatic 后您应该已经具备。它仅依赖于 Python 标准库。 + +!!! note + 为了确保可靠运行，您应确保 GoToSocial 配置中的 [storage-local-base-path](../configuration/storage.md) 使用的是绝对路径。否则您将需要自己调整路径。 + +```sh +$ gotosocial admin media list-attachments --local-only | \ + /path/to/media-to-borg-patterns.py \ + +``` + +这将在控制台上输出一个类似于以下内容的模式集： + +``` +R ++ pp:/ +- /* +``` + +!!! tip + 你可以通过向 `media-to-borg-patterns.py` 传递 `--help` 来查看帮助。通过将文件位置作为脚本的最后一个参数，也可以将输出直接写入文件。 + +给定这组模式，Borg 将从 `` 开始寻找文件。任何匹配路径前缀 `pp:` 的都会被包括进去。其他的则会匹配最后一个模式，从存档中排除。 + +在单用户实例中，你可以运行此命令一次，并直接在 Borgmatic 配置中内联模式 [使用 `patterns` 键](https://torsion.org/borgmatic/docs/reference/configuration/)。在多用户实例中，你应该在用户注册后运行此命令。或者，每次备份前都可以运行它。 + +如果你将 Borgmatic 作为 systemd 服务运行，可以为 `borgmatic.service` [创建一个 drop-in](https://wiki.archlinux.org/title/systemd#Drop-in_files)，在备份开始前运行模式生成： + + +```ini +[Service] +ExecStartPre=/path/to/gotosocial admin media list-attachments --local-only | /path/to/media-to-borg-patterns.py /etc/borgmatic/gotosocial_patterns +``` + +建议查看的文档： + +* Borgmatic [配置参考](https://torsion.org/borgmatic/docs/reference/configuration/) +* ArchWiki 关于 [Borgmatic 的条目](https://wiki.archlinux.org/title/Borgmatic) +* ArchWiki 关于 [Borg 的条目](https://wiki.archlinux.org/title/Borg_backup) +* BorgBase [文档](https://docs.borgbase.com/) +* Hetzner 社区指南关于 [设置 Borgmatic](https://community.hetzner.com/tutorials/install-and-configure-borgmatic) diff --git a/docs/locales/zh/admin/cli.md b/docs/locales/zh/admin/cli.md new file mode 100644 index 000000000..24ea8745b --- /dev/null +++ b/docs/locales/zh/admin/cli.md @@ -0,0 +1,465 @@ +# GtS CLI 工具 + +GoToSocial 编译为二进制可执行文件。 + +使用此二进制文件的标准方法是通过运行 `gotosocial server start` 命令启动服务器。 + +不过，此二进制文件也可以作为管理工具和调试工具使用。 + +以下是 `gotosocial --help` 的完整输出，不包括全局配置选项的大列表。 + +```text +GoToSocial - 一个联邦制社交媒体服务器 + +帮助文档参见：https://docs.gotosocial.org。 + +代码仓库：https://github.com/superseriousbusiness/gotosocial + +用法： + gotosocial [command] + +可用命令： + admin gotosocial 管理相关任务 + debug gotosocial 调试相关任务 + help 获取任何命令的帮助 + server gotosocial 服务器相关任务 +``` + +在 `可用命令` 下，可以看到标准的 `server` 命令。但是也有处理管理和调试的命令，这些将在本文档中进行解释。 + +!!! Info "将全局配置传递给 CLI" + + 对于所有这些命令，你仍然需要正确设置全局选项，以便 CLI 工具知道如何连接到你的数据库，以及使用哪个数据库、哪个主机和账户域等。 + + 你可以使用环境变量设置这些选项，通过 CLI 标志传递它们（例如，`gotosocial [commands] --host example.org`），或者只需将 CLI 工具指向你的配置文件（例如，`gotosocial --config-path ./config.yaml [commands]`）。 + +!!! Info + + 运行 CLI 命令时，你将会看到如下输出： + + ```text + time=XXXX level=info msg=connected to SQLITE database + time=XXXX level=info msg=there are no new migrations to run func=doMigration + time=XXXX level=info msg=closing db connection + ``` + + 这是正常的，表示命令已按预期运行。 + +!!! Warning "运行管理命令后重启 GtS" + + 由于 GoToSocial 的内部缓存机制，你可能需要在运行某些命令后重启 GoToSocial，以使命令的效果“生效”。我们仍在寻找一种无需重启的方法。在此期间，需要在运行命令后重启的命令将在下文中突出显示。 + +## gotosocial admin + +包含 `account`、`export`、`import` 和 `media` 子命令。 + +### gotosocial admin account create + +此命令可用于在你的实例上创建新账户。 + +`gotosocial admin account create --help`: + +```text +创建一个新的本站账户 + +用法： + gotosocial admin account create [flags] + +标志： + --email string 该账户的电子邮件地址 + -h, --help 获取创建命令的帮助 + --password string 为该账户设置的密码 + --username string 要创建/删除等的用户名 +``` + +示例： + +```bash +gotosocial admin account create \ + --username some_username \ + --email someuser@example.org \ + --password 'somelongandcomplicatedpassword' \ + --config-path config.yaml +``` + +### gotosocial admin account confirm + +此命令可用于确认你的实例上的用户+账户，允许他们登录并使用账户。 + +!!! Info + + 如果账户是使用 `admin account create` 创建的，则不必在账户上运行 `confirm`，它将已被确认。 + +`gotosocial admin account confirm --help`: + +```text +手动确认现有本站账户，从而跳过电子邮件确认 + +用法： + gotosocial admin account confirm [flags] + +标志： + -h, --help 获取确认命令的帮助 + --username string 要创建/删除等的用户名 +``` + +示例： + +```bash +gotosocial admin account confirm --username some_username --config-path config.yaml +``` + +### gotosocial admin account promote + +此命令可用于将用户提升为管理员。 + +!!! Warning "需要重启服务器" + + 为使更改生效，此命令需要在运行命令后重启 GoToSocial。 + +`gotosocial admin account promote --help`: + +```text +将本站账户提升为管理员 + +用法： + gotosocial admin account promote [flags] + +标志： + -h, --help 获取提升命令的帮助 + --username string 要创建/删除等的用户名 +``` + +示例： + +```bash +gotosocial admin account promote --username some_username --config-path config.yaml +``` + +### gotosocial admin account demote + +此命令可用于将用户从管理员降级为普通用户。 + +!!! Warning "需要重启服务器" + + 为使更改生效，此命令需要在运行命令后重启 GoToSocial。 + +`gotosocial admin account demote --help`: + +```text +将本站账户从管理员降级为普通用户 + +用法： + gotosocial admin account demote [flags] + +标志： + -h, --help 获取降级命令的帮助 + --username string 要创建/删除等的用户名 +``` + +示例： + +```bash +gotosocial admin account demote --username some_username --config-path config.yaml +``` + +### gotosocial admin account disable + +此命令可用于在你的实例上禁用一个账户：禁止其登录或执行任何操作，但不删除数据。 + +!!! Warning "需要重启服务器" + + 为使更改生效，此命令需要在运行命令后重启 GoToSocial。 + +`gotosocial admin account disable --help`: + +```text +将本站账户的 `disabled` 设置为 true，以防止其登录或发布等，但不删除任何内容 + +用法： + gotosocial admin account disable [flags] + +标志： + -h, --help 获取禁用命令的帮助 + --username string 要创建/删除等的用户名 +``` + +示例： + +```bash +gotosocial admin account disable --username some_username --config-path config.yaml +``` + +### gotosocial admin account enable + +此命令可用于重新启用你实例上的账户，撤销之前的 `disable` 命令。 + +!!! Warning "需要重启服务器" + + 为使更改生效，此命令需要在运行命令后重启 GoToSocial。 + +`gotosocial admin account enable --help`: + +```text +通过将本站账户的 `disabled` 设置为 false，撤销之前的禁用命令 + +用法： + gotosocial admin account enable [flags] + +标志： + -h, --help 获取启用命令的帮助 + --username string 要创建/删除等的用户名 +``` + +示例： + +```bash +gotosocial admin account enable --username some_username --config-path config.yaml +``` + +### gotosocial admin account password + +此命令可用于为指定的本站账户设置新密码。 + +!!! Warning "需要重启服务器" + + 为使更改生效，此命令需要在运行命令后重启 GoToSocial。 + +`gotosocial admin account password --help`: + +```text +为指定的本站账户设置新密码 + +用法： + gotosocial admin account password [flags] + +标志： + -h, --help 获取密码命令的帮助 + --password string 为该账户设置的密码 + --username string 要创建/删除等的用户名 +``` + +示例： + +```bash +gotosocial admin account password --username some_username --password some_really_good_password --config-path config.yaml +``` + +### gotosocial admin export + +此命令可用于将你的 GoToSocial 实例中的数据导出到文件，以便备份/存储。 + +文件格式将是一系列以换行符分隔的 JSON 对象。 + +`gotosocial admin export --help`: + +```text +将数据从数据库导出到指定路径的文件 + +用法： + gotosocial admin export [flags] + +标志： + -h, --help 获取导出命令的帮助 + --path string 导入/导出文件的路径 +``` + +Example: + +```bash +gotosocial admin export --path example.json --config-path config.yaml +``` + +`example.json`: + +```json +{"type":"account","id":"01F8MH5NBDF2MV7CTC4Q5128HF","createdAt":"2021-08-31T12:00:53.985645Z","username":"1happyturtle","locked":true,"language":"en","uri":"http://localhost:8080/users/1happyturtle","url":"http://localhost:8080/@1happyturtle","inboxURI":"http://localhost:8080/users/1happyturtle/inbox","outboxURI":"http://localhost:8080/users/1happyturtle/outbox","followingUri":"http://localhost:8080/users/1happyturtle/following","followersUri":"http://localhost:8080/users/1happyturtle/followers","featuredCollectionUri":"http://localhost:8080/users/1happyturtle/collections/featured","actorType":"Person","privateKey":"-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAzLP7oyyR+BU9ejn0CN9K+WpX3L37pxUcCgZAGH5lf3cGPZjz\nausfsFME94OjVyzw3K5M2beDkZ4E+Fak46NLtakLB1yovy9jKtj4Y4txHoMvRJLz\neUPxdfeXtpx2d3FDj++Uq4DEE0BhbePXhTGJWaNdC9MQmWKghJnCS5mrnFkdpEFx\njUz9l0UHl2Z4wppxPdpt7FyevcdfKqzGsAA3BxTM0dg47ZJWjtcvfCiSYpAKFNJY\nfKhKn9T3ezZgrLsF+o0IpD23KxWe1X4d5lgJRU9T4FmLmbvyJKUnfgYXbSEvLUcq\n79WbhgRcWwxWubjmWXgPGwzULVhhpYlwd2Cv3wIDAQABAoIBAGF+MxHjD15VV2NY\nKKb1GjMx98i1Xx6TijgoA+zmfha4LGu35e79Lql+0LXFp0zEpa6lAQsMQQhgd0OD\nmKKmSk+pxAvskJ4FxrhIf/yBFA4RMrj5OCaAOocRtdsOJ8n5UtFBrNAF0tzMY9q/\nkgzoq97aVF1mV9iFxaeBx6zT8ozSdqBq1PK/3w1dVg89S5tfKYc7Q0lQ00SfsTnd\niTDClKyqurebo9Pt6M7gXavgg3tvBlmwwr6XHs34Leng3oiN9mW8DVzaBMPzn+rE\nxF2eqs3v9vVpj8es88OwCh5P+ff8vJYvhu7Fcr/bJ8BItBQwfb8QBDATg/MXU2BI\n2ssW6AECgYEA4wmIyYGeu9+hzDa/J3Vh8GnlVNUCohHcChQdOsWsFXUgpVlUIHrX\neKHn42vD4Rzy52/YzJts4NkZTM9sL+kEXIEcpMG/S9xIIud7U0m/hMSAlmnJK/9j\niEXws3o4jo0E77jnRcBdIjpG4K5Eekm0DSR3SFhtZfEdN2DWPvu7K98CgYEA5tER\n/qJwFMc51AobMU87ZjXON7hI2U1WY/pVF62jSl0IcSsnj2riEKWLrs+GRG+HUg+U\naFSqAHcxaVHA0h0AYR8RopAhDdVKh0kvB8biLo+IEzNjPv2vyn0yRN5YSfXdGzyJ\nUjVU6kWdQOwmzy86nHgFaqEx7eofHIaGZzJK/AECgYEAu2VNQHX63TuzQuoVUa5z\nzoq5vhGsALYZF0CO98ndRkDNV22qIL0ESQ/qZS64GYFZhWouWoQXlGfdmCbFN65v\n6SKwz9UT3rvN1vGWO6Ltr9q6AG0EnYpJT1vbV2kUcaU4Y94NFue2d9/+TMnKv91B\n/m8Q/efvNGuWH/WQIaCKV6UCgYBz89WhYMMDfS4M2mLcu5vwddk53qciGxrqMMjs\nkzsz0Va7W12NS7lzeWaZlAE0gf6t98urOdUJVNeKvBoss4sMP0phqxwf0eWV3ur0\ncjIQB+TpGGikLVdRVuGY/UXHKe9AjoHBva8B3aTpB3lbnbNJBXZbIc1uYq3sa5w7\nXWWUAQKBgH3yW73RRpQNcc9hTUssomUsnQQgHxpfWx5tNxqod36Ytd9EKBh3NqUZ\nvPcH6gdh7mcnNaVNTtQOHLHsbPfBK/pqvb3MAsdlokJcQz8MQJ9SGBBPY6PaGw8z\nq/ambaQykER6dwlXTIlU20uXY0bttOL/iYjKmgo3vA66qfzS6nsg\n-----END RSA PRIVATE KEY-----\n","publicKey":"-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEAzLP7oyyR+BU9ejn0CN9K+WpX3L37pxUcCgZAGH5lf3cGPZjzausf\nsFME94OjVyzw3K5M2beDkZ4E+Fak46NLtakLB1yovy9jKtj4Y4txHoMvRJLzeUPx\ndfeXtpx2d3FDj++Uq4DEE0BhbePXhTGJWaNdC9MQmWKghJnCS5mrnFkdpEFxjUz9\nl0UHl2Z4wppxPdpt7FyevcdfKqzGsAA3BxTM0dg47ZJWjtcvfCiSYpAKFNJYfKhK\nn9T3ezZgrLsF+o0IpD23KxWe1X4d5lgJRU9T4FmLmbvyJKUnfgYXbSEvLUcq79Wb\nhgRcWwxWubjmWXgPGwzULVhhpYlwd2Cv3wIDAQAB\n-----END RSA PUBLIC KEY-----\n","publicKeyUri":"http://localhost:8080/users/1happyturtle#main-key"} +{"type":"account","id":"01F8MH0BBE4FHXPH513MBVFHB0","createdAt":"2021-09-08T10:00:53.985634Z","username":"weed_lord420","locked":true,"language":"en","uri":"http://localhost:8080/users/weed_lord420","url":"http://localhost:8080/@weed_lord420","inboxURI":"http://localhost:8080/users/weed_lord420/inbox","outboxURI":"http://localhost:8080/users/weed_lord420/outbox","followingUri":"http://localhost:8080/users/weed_lord420/following","followersUri":"http://localhost:8080/users/weed_lord420/followers","featuredCollectionUri":"http://localhost:8080/users/weed_lord420/collections/featured","actorType":"Person","privateKey":"-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEAzsCcTHzwIgpWKVvut0Q/t1bFwnbj9hO6Ic6k0KXCXbf6qi0b\nMIyLRZr8DS61mD+SPSO2QKEL647xxyW2D8YGtwN6Cc6MpWETsWJkNtS8t7tDL//P\nceYpo5LiqKgn0TXj0Pq8Lvb7rqpH8QJ2EVm14SK+elhKZW/Bi5ZOEwfL8pw6EHI4\nus6VxCNQ099dksu++kbdD7zxqEKnk/4zOttYt0whlVrxzkibTjlKdlSlTYpIstU+\nfNyYVE0xWvrn+yF7jVlEwZYOFGfZbpELadrdOr2k1hvAk7upkrpKmLqYfwqD/xPc\nqwtx0iS6AEnmkSiTcAvju5vLkoLFRU7Of4AZ2wIDAQABAoIBAEAA4GHNS4k+Ke4j\nx4J0XkUjV5UbuPY0pSpSDjOJHOJmUfLcg85Ds9mYYO6zxwOaqmrC42ieclI5rh84\nTWQUqX9+VAk1J9UKeE4xZ1SSBtnZ3rK9PjrERZ+dmQ0dATaCuEO5Wwgu7Trk++Bg\nIqy8WNGZL94v9tfwALp1jTXW9AvmQoNdCFBP62vcmYW4YLjnggxLCFTA8YKfdePa\nTuxxY6uLkeBbxzWpbRU2+bmlxd5OnCkiRSMHIX+6JdtCu2JdWpUTCnWrFi2n1TZz\nZQx9z5rvowK1O785jGMFum5vBWpjIU8sJcXmPjGMU25zzmrhzfmkJsTXER3CXoUo\nSqSPqgECgYEA78OR7bY5KKQQ7Lyz6dru4Fct5P/OXTQoOg5aS7TKb95LVWj+TANn\n5djwIbLmAUV30z0Id9VgiZOL0Hny8+3VV9eU088Z408pAy5WQrL3dB8tZLUJSq5c\n5k6X15/VjWOOZKppDxShzoV3mcohrnwVwkv4fhPFQQOJJBYz6xurWs0CgYEA3MDE\nsDMd9ahzO0dl62ynojkkA8ZTcn2UdyvLpGj9UxT5j9vWF3CfqitXgcpNiVSIbxqQ\nbo/pBch7c/2Xakv5zkdcrJj5/6gyr+m1/tK2o7+CjDaSE4SYwufXx+qkl03Zpyzt\nKdOi7Hz/b2tdjump7ECEDE45mG2ea8oSnPgXl0cCgYBkGGFzu/9g2B24t47ksmHH\nhp3CXIjqoDurARLxSCi7SzJoFc0ULtfRPSAC8YzUOwwrQ++lF4+V3+MexcqHy2Kl\nqXqYcn18SC/3BAE/Fzf3Yoyw3mNiqihefbEmc7PTsxxfKkVx5ksmzNGBgsFM9sCe\nvNigyeAvpCo8xogmPwbqgQKBgE34mIBTzcUzFmBdu5YH7r3RyPK8XkUWLhZZlbgg\njTmHMw6o61mkIgENBf+F4RUckoQLsfAbTIcKZPB3JcAZzcYaVpVwAv1V/3E671lu\nO6xivE2iCL50GzDcis7GBhSbHsF5kNsxMV6uV9qW5ZjQ13/m2b0u9BDuxwHzgdeH\nmW2JAoGAIUOYniuEwdygxWVnYatpr3NPjT3BOKoV5i9zkeJRu1hFpwQM6vQ4Ds5p\nGC5vbMKAv9Cwuw62e2HvqTun3+U2Y5Uived3XCpgM/50BFrFHCfuqXEnu1bEzk5z\n9mIhp8uXPxzC5N7tRQfb3/eU1IUcb6T6ksbr2P81z0j03J55erg=\n-----END RSA PRIVATE KEY-----\n","publicKey":"-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEAzsCcTHzwIgpWKVvut0Q/t1bFwnbj9hO6Ic6k0KXCXbf6qi0bMIyL\nRZr8DS61mD+SPSO2QKEL647xxyW2D8YGtwN6Cc6MpWETsWJkNtS8t7tDL//PceYp\no5LiqKgn0TXj0Pq8Lvb7rqpH8QJ2EVm14SK+elhKZW/Bi5ZOEwfL8pw6EHI4us6V\nxCNQ099dksu++kbdD7zxqEKnk/4zOttYt0whlVrxzkibTjlKdlSlTYpIstU+fNyY\nVE0xWvrn+yF7jVlEwZYOFGfZbpELadrdOr2k1hvAk7upkrpKmLqYfwqD/xPcqwtx\n0iS6AEnmkSiTcAvju5vLkoLFRU7Of4AZ2wIDAQAB\n-----END RSA PUBLIC KEY-----\n","publicKeyUri":"http://localhost:8080/users/weed_lord420#main-key"} +{"type":"account","id":"01F8MH17FWEB39HZJ76B6VXSKF","createdAt":"2021-09-05T10:00:53.985641Z","username":"admin","locked":true,"language":"en","uri":"http://localhost:8080/users/admin","url":"http://localhost:8080/@admin","inboxURI":"http://localhost:8080/users/admin/inbox","outboxURI":"http://localhost:8080/users/admin/outbox","followingUri":"http://localhost:8080/users/admin/following","followersUri":"http://localhost:8080/users/admin/followers","featuredCollectionUri":"http://localhost:8080/users/admin/collections/featured","actorType":"Person","privateKey":"-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEAxr2e1pqfLwwUCwHUdx56Mxnq5Kzc2EBwqN6jIPjiqVaG5eVq\nhujDhdqwMq0hnpBSPzLnvjiOtEh7Bwhx0MjuC/GRPTM9oNWPYD4PcjX5ofrubyLR\nBI97qD0SbyzUWzeyBi6R5tpW8LK1MJXNbnYlz5WouEiC4mY77ulri0EN2hCq80wg\nfvtEjEvELcKBqIytKH3rutIzfAyqXD7LSQ8UDoNh9GHyIfq8Zj32gWVk2MiPI3+G\n8kQJDmD8CKEasnrGVdSJBQUg3xDAtOibPXLP+07AIsKYMon35hVNvQNQPS7ru/Bk\nRhhGp2R44zqj6L9mxYbSrhFAaKDedu8oVe1aLQIDAQABAoIBAGK0aIADOU4ffJDe\n7sveiih5Fc1PATwx/QIR2QkWM1SREdx6LYclcX44V8xDanAbE44p1SkHY/CsEtYy\nXnyoXnn2FwFDQrdveY7+I6PApOPLAcKWkyLltC+hbVdj92/6YGNrm7EA/a77wruH\nmwjiivLnTG2CLecNiXSl33DA9YU4Yz+2Tza3IpTdjt8c/dz/BKKaxaWV+i9ew5VR\nioo5v51B+J8PrneCM/p8LGiLV148Njr0JqV6eFy1JuzItYMYdc3Fp+YnMzsuMZEA\n1akMcoln/ucVJyOFnCn6jx47nIoPZLl1KxX3aRDRfvrejm6W4yAkkTmR5voSRqax\njPL3rI0CgYEA9Acu4TO8xJ3uGaUad0N9JTYQVSmtAaE/g+df9LGMSzoj8X95S4xE\nQsGPqNGDm2VWADJjK4P05twZ+LfsfSKQ86wbp4/gbgnXpqB1P5Lty/B7KxiTnNwt\nwb1WGWTCukxfUSL3PRyf8uylkrg72RxKiBx4zKO3WVSLWOZWrFtn0qMCgYEA0H2p\nJs9Nv20ADOOX5tQ7+ruS6/B/Fhyj5fhflSYCAtOW7aME7+zQKJyqSQZ4b2Aub3Tp\nGIaUbRIGzjHyuTultFFWvjU3H5aI/0g1G9WKaBhNkyTIYVmMKtYyhXNvouWing8x\noraWx8TTBP8Cdnnk+QgdR2fpug8cghKupp5wvO8CgYA1JFtRL7MsHjh73TimQExA\njkWARlMmx7bNQtXis8eZmk+5h8kiaqly4DQoz3eZn7fa0x5Fm7b5j3UYdPVLSvvG\nFPTwyKRXUk1kPA1MivK+NuCbwf5jao+MYW8emJLPf1JCmRq+dD1g6aglC3n9Dewt\nOAYWipCjI4Y1FfRKFJ3HgQKBgEAb47+DTyzln3ZXJYZdDHR06SCTuwBZnixAy2NZ\nZJTp6yb3UbVU5E0Yn2QFEVNuB9lN4b8g4tMHEACnazN6G+HugPXL9z9HUqjs0yfT\n6dNIZdIxJUyJ9IfXhYFzlYhJhE+F7IVUD9kttJV8tI0pvja1QAuM8Fm9+84jYIDr\nh08RAoGAMYbjKHbtejcHBwt1kIcSss0cDmlZbBleJo8tdmdg4ndf5GE9N4/EL7tq\nm2zYSfr7OVdnOwRhoO+xF/6d1L7+TR1wz+k2fuMsI71aM5Ocp1nYTutjIkBTcldZ\nZzvjOgZWng5icuRLQQiDSKG5uqazqL/xGXkijb4kp4WW6myWY3c=\n-----END RSA PRIVATE KEY-----\n","publicKey":"-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEAxr2e1pqfLwwUCwHUdx56Mxnq5Kzc2EBwqN6jIPjiqVaG5eVqhujD\nhdqwMq0hnpBSPzLnvjiOtEh7Bwhx0MjuC/GRPTM9oNWPYD4PcjX5ofrubyLRBI97\nqD0SbyzUWzeyBi6R5tpW8LK1MJXNbnYlz5WouEiC4mY77ulri0EN2hCq80wgfvtE\njEvELcKBqIytKH3rutIzfAyqXD7LSQ8UDoNh9GHyIfq8Zj32gWVk2MiPI3+G8kQJ\nDmD8CKEasnrGVdSJBQUg3xDAtOibPXLP+07AIsKYMon35hVNvQNQPS7ru/BkRhhG\np2R44zqj6L9mxYbSrhFAaKDedu8oVe1aLQIDAQAB\n-----END RSA PUBLIC KEY-----\n","publicKeyUri":"http://localhost:8080/users/admin#main-key"} +{"type":"account","id":"01F8MH1H7YV1Z7D2C8K2730QBF","createdAt":"2021-09-06T10:00:53.985643Z","username":"the_mighty_zork","locked":true,"language":"en","uri":"http://localhost:8080/users/the_mighty_zork","url":"http://localhost:8080/@the_mighty_zork","inboxURI":"http://localhost:8080/users/the_mighty_zork/inbox","outboxURI":"http://localhost:8080/users/the_mighty_zork/outbox","followingUri":"http://localhost:8080/users/the_mighty_zork/following","followersUri":"http://localhost:8080/users/the_mighty_zork/followers","featuredCollectionUri":"http://localhost:8080/users/the_mighty_zork/collections/featured","actorType":"Person","privateKey":"-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEApBmF8U+or+E0mgUMH3LE4uRIWzeV9rhYnvSMm9OpOsxwJiss\n5mEA/NtPHvQlq2UwrqXX89Wvu94K9EzZ4VyWYQGdxaiPpt17vRqUfsHUnXkY0pvC\nC9zt/aNlJtdt2xm+7PTC0YQd4+E1FX3aaoUPJL8MXzNlpJzaUtuwLZe1iBmFfatZ\nFHptEgc4nlf6TNLTzj3Yw1/7zIGVS8Vi7VquHc0Xo8dRiL2RxCGzLWnwL6GlrxY1\ntMhsUg467XeoiwegFCpcIhAhPFREKoTnCEksL/N0rpXl7m6CAy5uqBGs5mMXnXlq\nefr58l0j2dU6zc60LCHH9TJC+roXsKJhy9sx/QIDAQABAoIBAFa+UypbFG1cW2Tr\nNBxPm7ngOEtXl8MicV4dIVKh0TwOo13ZxtNFBbOj7jALmPn/9HrtmbkABPQHDL1U\n/nt9aNSAeTjpwH3RaD5vFX3n0g8n2zJBOZLxxzAjNi4RBLYj5uP1AiKkdvRlsJza\nuSFDkty2zMBqN9mLPHE+RePj5Qa6tjYfIQqQzu/+YnYMlXHoC2yHNKsvz6S5FhVj\nv5zATv2JlJQH3RSmhuPOah73iQnKCLzYYEAHleawKrCg/rZ3ht37Guvabeq7MqQN\nvi9pJdAA+RMxPsboHajskePjOTYJgKQSxEAMRTMfBR40aZxklxQL0EoBd1Y3CHXh\nfMg0xWECgYEA0ORrpJ1A2WNQwKcDDeBBsaJqWF4EraoFzYrugKZrAYEeVyuGD0zq\nARUaWkZTZ1f6wQ10i1WxAuKlBEds7QsLdZzLsA4um4JlBroCZiYfPnmTtb8op1LY\nFqeYTByvAmnfWWTuOI67GX9ruLg8tEGuz38kuQVSxYs51its3tScNPUCgYEAyRst\nwRbqpOqnwoRoS6pxv0Vpc3nUcfaVYwsg/qobJkiwAdlUYeE7alvEY926VW4cvU/X\nhy3L1punAqnyLI7uuqCefXEbNxO0Cebyy4Kv2Ye1uzl0OHsJczSNdfpNqfAIKwtN\nHLCYDGCsluQhz+I/5Pd0dT+JDPPW9hKS2HG7o+kCgYBqugn1VRLo/sEnbS02TbnC\n1ESZWY/yWsgUOEObH2vUnO+vgeFAt/9nBi0sqnm6d0z6jbFZ7zI9UycUhJm2ksoM\nEUxQay6M7ZZIVYkcP6X++YbqePyAYOdey8oYOR+BkC45MkQ0SVh2so+LFTaOsnBq\nO3+7uGiN3ZBzSESbpO0acQKBgQCONrsXZeZO82XpB4tdns3LbgGRWKEkajTgEnml\nvZNvck2NMSwb/5PttbFe0ei4CyMluPV4MamJPQ9Qse+BFR67OWR63uZY/4T8z6X4\nxpUmZnLcUFfgrRlUr+AtgvEy8HxGPDquxC7x6deC6RcEFEIM3/UqCOEZGMJ1x1Ky\n31LLKQKBgGCKwVgQ8+4JyHZFkie3YdHhxJDokgY+Opb0HNnoBY/lZ54UMCCJQPS2\n0XPSu651j/3adr3RQneU04gF6U2/D5JzFEV0kUsqZ4Zy2EEU0LU4ibus0gyomSpK\niWhU4QrC/M4ELxYZinlNu3ThPWNQ/PMNteVWfdgOcV7uUWl0ViFp\n-----END RSA PRIVATE KEY-----\n","publicKey":"-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEApBmF8U+or+E0mgUMH3LE4uRIWzeV9rhYnvSMm9OpOsxwJiss5mEA\n/NtPHvQlq2UwrqXX89Wvu94K9EzZ4VyWYQGdxaiPpt17vRqUfsHUnXkY0pvCC9zt\n/aNlJtdt2xm+7PTC0YQd4+E1FX3aaoUPJL8MXzNlpJzaUtuwLZe1iBmFfatZFHpt\nEgc4nlf6TNLTzj3Yw1/7zIGVS8Vi7VquHc0Xo8dRiL2RxCGzLWnwL6GlrxY1tMhs\nUg467XeoiwegFCpcIhAhPFREKoTnCEksL/N0rpXl7m6CAy5uqBGs5mMXnXlqefr5\n8l0j2dU6zc60LCHH9TJC+roXsKJhy9sx/QIDAQAB\n-----END RSA PUBLIC KEY-----\n","publicKeyUri":"http://localhost:8080/users/the_mighty_zork#main-key"} +{"type":"block","id":"01FEXXET6XXMF7G2V3ASZP3YQW","createdAt":"2021-09-08T09:00:53.965362Z","uri":"http://localhost:8080/users/1happyturtle/blocks/01FEXXET6XXMF7G2V3ASZP3YQW","accountId":"01F8MH5NBDF2MV7CTC4Q5128HF","targetAccountId":"01F8MH5ZK5VRH73AKHQM6Y9VNX"} +{"type":"account","id":"01F8MH5ZK5VRH73AKHQM6Y9VNX","createdAt":"2021-08-31T12:00:53.985646Z","username":"foss_satan","domain":"fossbros-anonymous.io","locked":true,"language":"en","uri":"http://fossbros-anonymous.io/users/foss_satan","url":"http://fossbros-anonymous.io/@foss_satan","inboxURI":"http://fossbros-anonymous.io/users/foss_satan/inbox","outboxURI":"http://fossbros-anonymous.io/users/foss_satan/outbox","followingUri":"http://fossbros-anonymous.io/users/foss_satan/following","followersUri":"http://fossbros-anonymous.io/users/foss_satan/followers","featuredCollectionUri":"http://fossbros-anonymous.io/users/foss_satan/collections/featured","actorType":"Person","publicKey":"-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEA2OyVgkaIL9VohXKYTh319j4OouHRX/8QC7piXj71k7q5RDzEyvis\nVZBc5/C1/crCpxt895i0Ai2CiXQx+dISV7s/JBhAGl8s7TQ8jLlMuptrI0+sdkBC\nlu8pU0qQmoeXVnlquOzNmqGufUxIDtLXLZDN17qf/7vWA23q4d0tG5KQhGGGKiVM\n61Ufvr9MmgPBSpyUvYMAulFlz1264L49aGWeVgOz3qUQzqtxjrP0kaIbeyt56miP\nKr5AqkRgSsXci+FAo6suxR5gzo9NgleNkbZWF9MQyKlawukPwZUDSh396vtNQMee\n/4mto7mAXw8iio0IacrYO3F7iyewXnmI/QIDAQAB\n-----END RSA PUBLIC KEY-----\n","publicKeyUri":"http://fossbros-anonymous.io/users/foss_satan/main-key"} +{"type":"follow","id":"01F8PYDCE8XE23GRE5DPZJDZDP","createdAt":"2021-09-08T09:00:54.749465Z","uri":"http://localhost:8080/users/the_mighty_zork/follow/01F8PYDCE8XE23GRE5DPZJDZDP","accountId":"01F8MH1H7YV1Z7D2C8K2730QBF","targetAccountId":"01F8MH5NBDF2MV7CTC4Q5128HF"} +{"type":"follow","id":"01F8PY8RHWRQZV038T4E8T9YK8","createdAt":"2021-09-06T12:00:54.749459Z","uri":"http://localhost:8080/users/the_mighty_zork/follow/01F8PY8RHWRQZV038T4E8T9YK8","accountId":"01F8MH1H7YV1Z7D2C8K2730QBF","targetAccountId":"01F8MH17FWEB39HZJ76B6VXSKF"} +{"type":"domainBlock","id":"01FF22EQM7X8E3RX1XGPN7S87D","createdAt":"2021-09-08T10:00:53.968971Z","domain":"replyguys.com","createdByAccountID":"01F8MH17FWEB39HZJ76B6VXSKF","privateComment":"i blocked this domain because they keep replying with pushy + unwarranted linux advice","publicComment":"reply-guying to tech posts","obfuscate":false} +{"type":"user","id":"01F8MGYG9E893WRHW0TAEXR8GJ","createdAt":"2021-09-08T10:00:53.97247Z","accountID":"01F8MH0BBE4FHXPH513MBVFHB0","encryptedPassword":"$2y$10$ggWz5QWwnx6kzb9g0tnIJurFtE0dhr5Zfeaqs9iFuUIXzafQlJVZS","locale":"en","lastEmailedAt":"0001-01-01T00:00:00Z","confirmationToken":"a5a280bd-34be-44a3-8330-a57eaf61b8dd","confirmationTokenSentAt":"2021-09-08T10:00:53.972472Z","unconfirmedEmail":"weed_lord420@example.org","moderator":false,"admin":false,"disabled":false,"approved":false} +{"type":"user","id":"01F8MGWYWKVKS3VS8DV1AMYPGE","createdAt":"2021-09-05T10:00:53.972475Z","email":"admin@example.org","accountID":"01F8MH17FWEB39HZJ76B6VXSKF","encryptedPassword":"$2y$10$ggWz5QWwnx6kzb9g0tnIJurFtE0dhr5Zfeaqs9iFuUIXzafQlJVZS","currentSignInAt":"2021-09-08T09:50:53.972477Z","lastSignInAt":"2021-09-08T08:00:53.972477Z","chosenLanguages":["en"],"locale":"en","lastEmailedAt":"2021-09-08T09:30:53.972478Z","confirmedAt":"2021-09-05T10:00:53.972478Z","moderator":true,"admin":true,"disabled":false,"approved":true} +{"type":"user","id":"01F8MGVGPHQ2D3P3X0454H54Z5","createdAt":"2021-09-06T22:00:53.97248Z","email":"zork@example.org","accountID":"01F8MH1H7YV1Z7D2C8K2730QBF","encryptedPassword":"$2y$10$ggWz5QWwnx6kzb9g0tnIJurFtE0dhr5Zfeaqs9iFuUIXzafQlJVZS","currentSignInAt":"2021-09-08T09:30:53.972481Z","lastSignInAt":"2021-09-08T08:00:53.972481Z","chosenLanguages":["en"],"locale":"en","lastEmailedAt":"2021-09-08T09:05:53.972482Z","confirmationTokenSentAt":"2021-09-06T22:00:53.972483Z","confirmedAt":"2021-09-07T00:00:53.972482Z","moderator":false,"admin":false,"disabled":false,"approved":true} +{"type":"user","id":"01F8MH1VYJAE00TVVGMM5JNJ8X","createdAt":"2021-09-06T22:00:53.972485Z","email":"tortle.dude@example.org","accountID":"01F8MH5NBDF2MV7CTC4Q5128HF","encryptedPassword":"$2y$10$ggWz5QWwnx6kzb9g0tnIJurFtE0dhr5Zfeaqs9iFuUIXzafQlJVZS","currentSignInAt":"2021-09-08T09:30:53.972485Z","lastSignInAt":"2021-09-08T08:00:53.972486Z","chosenLanguages":["en"],"locale":"en","lastEmailedAt":"2021-09-08T09:05:53.972487Z","confirmationTokenSentAt":"2021-09-06T22:00:53.972487Z","confirmedAt":"2021-09-07T00:00:53.972487Z","moderator":false,"admin":false,"disabled":false,"approved":true} +{"type":"instance","id":"01BZDDRPAB8J645ABY31HHF68Y","createdAt":"2021-09-08T10:00:54.763912Z","domain":"localhost:8080","title":"localhost:8080","uri":"http://localhost:8080","reputation":0} +``` + +### gotosocial admin import + +此命令可用于将文件中的数据导入到你的 GoToSocial 数据库中。 + +如果数据库中尚未存在 GoToSocial 表，它们将被创建。 + +如果在导入过程中出现任何冲突（例如尝试导入特定帐户时已经存在），则进程将中止。 + +文件格式应为一系列以换行符分隔的 JSON 对象（参见上文）。 + +`gotosocial admin import --help`: + +```text +从文件中导入数据到数据库 + +用法: + gotosocial admin import [选项] + +选项: + -h, --help 导入命令的帮助信息 + --path string 要导入/导出文件的路径 +``` + +示例: + +```bash +gotosocial admin import --path example.json --config-path config.yaml +``` + +### gotosocial admin media list-attachments + +可用于列出实例上的本站、外站或所有媒体附件的存储路径（包括头像和头图）。 + +`local-only` 和 `remote-only` 可用作过滤器；它们不能同时被设置。 + +如果既未设置 `local-only` 也未设置 `remote-only`，则将列出实例上的所有媒体附件。 + +你可能希望在运行此命令时将 `GTS_LOG_LEVEL` 设置为 `warn` 或 `error`，否则会记录大量你可能不需要的信息日志。 + +`gotosocial admin media list-attachments --help`: + +```text +列出本站、外站或所有附件 + +用法: + gotosocial admin media list-attachments [选项] + +选项: + -h, --help list-attachments 命令的帮助信息 + --local-only 仅列出本站附件/表情；如果指定，则 remote-only 不能为 true + --remote-only 仅列出外站附件/表情；如果指定，则 local-only 不能为 true +``` + +示例输出: + +```text +/gotosocial/062G5WYKY35KKD12EMSM3F8PJ8/attachment/original/01PFPMWK2FF0D9WMHEJHR07C3R.jpg +/gotosocial/01F8MH1H7YV1Z7D2C8K2730QBF/attachment/original/01PFPMWK2FF0D9WMHEJHR07C3Q.jpg +/gotosocial/01F8MH5ZK5VRH73AKHQM6Y9VNX/attachment/original/01FVW7RXPQ8YJHTEXYPE7Q8ZY0.jpg +/gotosocial/01F8MH1H7YV1Z7D2C8K2730QBF/attachment/original/01F8MH8RMYQ6MSNY3JM2XT1CQ5.jpg +/gotosocial/01F8MH1H7YV1Z7D2C8K2730QBF/attachment/original/01F8MH7TDVANYKWVE8VVKFPJTJ.gif +/gotosocial/01F8MH17FWEB39HZJ76B6VXSKF/attachment/original/01F8MH6NEM8D7527KZAECTCR76.jpg +/gotosocial/01F8MH1H7YV1Z7D2C8K2730QBF/attachment/original/01F8MH58A357CV5K7R7TJMSH6S.jpg +/gotosocial/01F8MH1H7YV1Z7D2C8K2730QBF/attachment/original/01CDR64G398ADCHXK08WWTHEZ5.gif +``` + +### gotosocial admin media list-emojis + +用于列出您实例上的本站、外站或所有表情符号的存储路径。 + +`local-only` 和 `remote-only` 可用作过滤器；它们不能同时设置。 + +如果未设置 `local-only` 或 `remote-only`，将列出您实例上的所有表情符号。 + +您可能需要在运行时将 `GTS_LOG_LEVEL` 设置为 `warn` 或 `error`，否则将记录许多您可能不需要的信息消息。 + +`gotosocial admin media list-emojis --help`: + +```text +列出本站、外站或所有表情符号 + +用法： + gotosocial admin media list-emojis [标志] + +标志： + -h, --help 获取 list-emojis 帮助信息 + --local-only 仅列出本站附件/表情符号；如果指定，则 remote-only 不能为真 + --remote-only 仅列出外站附件/表情符号；如果指定，则 local-only 不能为真 +``` + +示例输出： + +```text +/gotosocial/01AY6P665V14JJR0AFVRT7311Y/emoji/original/01GD5KP5CQEE1R3X43Y1EHS2CW.png +/gotosocial/01AY6P665V14JJR0AFVRT7311Y/emoji/original/01F8MH9H8E4VG3KDYJR9EGPXCQ.png +``` + +### gotosocial admin media prune orphaned + +此命令可用于删除您 GoToSocial 中的孤立媒体。 + +孤立媒体定义为存储中使用 GoToSocial 格式的键存在，但没有相应数据库条目的媒体。这对于删除可能在以前安装中遗留的文件，或错误放置在存储中的文件非常有用。 + +!!! warning "需要停止服务器" + + 此命令仅在 GoToSocial 未运行时起作用，因为它需要获取存储的独占锁。 + + 在运行此命令之前，请先停止 GoToSocial！ + +```text +删除存储中的孤立媒体 + +用法： + gotosocial admin media prune orphaned [标志] + +标志： + --dry-run 执行试运行，仅记录可删除项目的数量（默认值为 true） + -h, --help 获取 orphaned 帮助信息 +``` + +默认情况下，此命令执行试运行，将记录可以删除的项目数量。要真正执行删除，请在命令中添加 `--dry-run=false`。 + +示例（试运行）： + +```bash +gotosocial admin media prune orphaned +``` + +示例（实际执行）： + +```bash +gotosocial admin media prune orphaned --dry-run=false +``` + +### gotosocial admin media prune remote + +此命令可用于删除您 GoToSocial 中未使用/过时的外站媒体。 + +过时媒体是指外站实例中早于 `media-remote-cache-days` 的头像/头图/状态附件。 + +如果需要，这些项目将会在之后按需重新获取。 + +未使用媒体是指当前账号或状态未使用的头像/头图/状态附件。 + +!!! warning "需要停止服务器" + + 此命令仅在 GoToSocial 未运行时起作用，因为它需要获取存储的独占锁。 + + 在运行此命令之前，请先停止 GoToSocial！ + +```text +从存储中删除未使用/过时的外站媒体，时间早于指定天数 + +用法： + gotosocial admin media prune remote [标志] + +标志： + --dry-run 执行试运行，仅记录可删除项目的数量（默认值为 true） + -h, --help 获取 remote 帮助信息 +``` + +默认情况下，此命令执行试运行，将记录可以删除的项目数量。要真正执行删除，请在命令中添加 `--dry-run=false`。 + +示例（试运行）： + +```bash +gotosocial admin media prune remote +``` + +示例（实际执行）： + +```bash +gotosocial admin media prune remote --dry-run=false +``` diff --git a/docs/locales/zh/admin/database_maintenance.md b/docs/locales/zh/admin/database_maintenance.md new file mode 100644 index 000000000..36b0159bb --- /dev/null +++ b/docs/locales/zh/admin/database_maintenance.md @@ -0,0 +1,55 @@ +# 数据库维护 + +无论你选择使用 SQLite 还是 Postgres 来运行 GoToSocial，可能都需要偶尔执行一些维护工作，以保持数据库的良好运作。 + +!!! tip + + 尽管此处提供的维护建议旨在不破坏现有数据，你还是应该在手动执行维护操作之前备份数据库。这样，如果输入错误或意外运行了不当命令，可以恢复备份并重试。 + +!!! danger + + **强烈不建议**手动创建、删除或更新 GoToSocial 数据库中的条目，这里不会提供相关命令。即使你认为自己知道在做什么，运行 `DELETE` 等语句可能会引入非常难以排查的问题。以下维护建议旨在帮助你的实例平稳运行；如果你手动进入数据库并对条目、表和索引进行修改，它们不会拯救你的数据。 + +## SQLite + +要进行手动 SQLite 维护，你首先应该在存储 GoToSocial sqlite.db 文件的机器上安装 SQLite 命令行工具 `sqlite3`。有关 `sqlite3` 的详细信息，请参见[此处](https://sqlite.org/cli.html)。 + +### 分析/优化 + +按照 [SQLite 最佳实践](https://sqlite.org/lang_analyze.html#recommended_usage_pattern)，GoToSocial 在关闭数据库连接时运行 `optimize` SQLite pragma，`analysis_limit=1000`，以保持索引信息的更新。 + +在每次数据库迁移后（例如，启动新版本的 GoToSocial 时），GoToSocial 将运行 `ANALYZE`，以确保查询计划器正确考虑迁移新增或删除的索引。 + +`ANALYZE` 命令可能需要大约 10 分钟，具体时间取决于硬件和数据库文件的大小。 + +由于上述自动化步骤，正常情况下你不需要针对 SQLite 数据库文件手动运行 `ANALYZE` 命令。 + +然而，如果你中断了之前的 `ANALYZE` 命令，并发现查询运行缓慢，可能是因为 SQLite 内部表中存储的索引元数据已被删除或不当修改。 + +如果是这种情况，可以尝试手动运行完整的 `ANALYZE` 命令，步骤如下： + +1. 停止 GoToSocial。 +2. 在 `sqlite3` shell 中连接到你的 GoToSocial 数据库文件，运行 `PRAGMA analysis_limit=0; ANALYZE;`（这可能需要几分钟）。 +3. 启动 GoToSocial。 + +[查看更多信息](https://sqlite.org/lang_analyze.html#approximate_analyze_for_large_databases). + +### 清理（Vacuum） + +GoToSocial 当前未启用 SQLite 的自动清理（auto-vacuum）。要将数据库文件重新打包到最佳大小，你可能需要定期（例如每几个月）在 SQLite 数据库上运行 `VACUUM` 命令。 + +可以在[此处](https://sqlite.org/lang_vacuum.html)查看有关 `VACUUM` 命令的详细信息。 + +基本步骤如下： + +1. 停止 GoToSocial。 +2. 在 `sqlite3` shell 中连接到你的 GoToSocial 数据库文件，运行 `VACUUM;`（这可能需要几分钟）。 +3. 启动 GoToSocial。 + +### 副本 + +为数据库设置副本等保护措施是常见做法。SQLite 可以使用外部软件进行副本创建。基本步骤描述在 [配置 SQLite 副本](../advanced/replicating-sqlite.md) 页面。 + +## Postgres + +待完成：Postgres 的维护建议。 diff --git a/docs/locales/zh/admin/domain_blocks.md b/docs/locales/zh/admin/domain_blocks.md new file mode 100644 index 000000000..00be4d3f8 --- /dev/null +++ b/docs/locales/zh/admin/domain_blocks.md @@ -0,0 +1,73 @@ +# 域名屏蔽 + +GoToSocial 支持屏蔽/封禁那些你不想与你的实例联合的域名。在我们的文档中，“屏蔽”和“封禁”这两个术语在涉及域名时可以互换使用，因为它们的意思相同：屏蔽你的实例与目标域名上的实例相互通信，有效地切断两个实例之间的联合。 + +你可以使用[实例管理面板](./settings.md#联合)查看、创建和移除域名屏蔽和域名允许。 + +本文档重点说明域名屏蔽实际*作用*是什么，以及创建新域名屏蔽时会产生哪些副作用。 + +## 域名屏蔽如何工作 + +域名屏蔽通过两种方式工作： + +首先，它指示你的实例拒绝来自目标域名的任何请求： + +- 从被屏蔽域名到你的实例的所有传入请求将以 HTTP 状态码 `403 Forbidden` 响应。 +- 这使目标域名上的帐户无法与你实例上的帐户或该帐户创建的任何贴文进行互动，因为你的实例会简单地拒绝处理请求。 +- 这也延伸到 GET 请求：你的实例将不再对被屏蔽实例的请求提供 ActivityPub 响应，例如获取帐户简介或置顶贴文等。 +- 你的实例上的帐户的贴文转发也不应对被屏蔽的实例可见，因为那些实例将无法获取已转发贴文的内容。 + +其次，域名屏蔽指示你的实例不再向目标实例发出任何请求。这意味着： + +- 你的实例不会向被屏蔽域名上的实例发送任何消息。 +- 也不会从该实例获取贴文、帐户、媒体或表情符号。 + +## 安全顾虑 + +### 屏蔽规避 + +域名屏蔽并不完全严密。GoToSocial *可以* 确保自身既不响应来自被屏蔽域名的请求，也不向这些实例发出请求。不幸的是，它*无法*保证你的实例上的帐户不会以任何方式对被屏蔽实例的用户可见。请考虑以下情况，这些都代表了一种[屏蔽规避](https://en.wikipedia.org/wiki/Block_(Internet)#Evasion)： + +- 你屏蔽了 `blocked.instance.org`。`blocked.instance.org` 上的用户在 `not-blocked.domain` 上创建了一个帐户，以便他们可以使用新帐户与你的帖子互动或向你发送消息。他们可能会直接跳脸，告诉你他们是谁，或者使用假身份。 +- 你屏蔽了 `blocked.instance.org`。`not-blocked.domain` 上的用户截屏了你的贴文并将其发送给 `blocked.instance.org` 上的某人。 +- 你屏蔽了 `blocked.instance.org`。`blocked.instance.org` 上的用户通过浏览器访问你的个人资料，以查看你的公开贴文。 +- 你屏蔽了 `blocked.instance.org`。你的个人资料启用了 RSS。`blocked.instance.org` 上的用户订阅了你的 RSS feed 以阅读你的公开贴文。 + +在上述情况下，`blocked.instance.org` 依然被屏蔽，但该实例的用户可能仍有其他方式查看你的贴文并可能联系到你。 + +考虑到这一点，你应始终将域名屏蔽视为隐私保护的*一个层次*。也就是说，域名屏蔽应该与其他层次一起部署，以实现你所满意的隐私水平。这应包括不公开发布敏感信息、不在照片中意外暴露个人信息等。 + +### 屏蔽公告机器人 + +不幸的是，联邦宇宙中有一些恶意用户，他们将域名屏蔽视为敌人而试图打破。为达到此目的，他们通常会针对那些使用域名屏蔽来保护用户的实例。 + +因此，联邦宇宙中有机器人抓取实例域名屏蔽，并向机器人的关注者宣布任何发现的屏蔽，从而使屏蔽实例的管理员可能面临骚扰。这些机器人使用 `api/v1/instance/peers?filter=suspended` 端点来收集域名屏蔽信息。 + +默认情况下，GoToSocial 不会公开此端点，因此你的实例将不会被这种方式抓取。然而，如果你在 config.yaml 文件中将 `instance-expose-suspended` 设置为 `true`，你可能会发现此端点偶尔会被抓取，并且你的屏蔽可能会被恶意机器人宣布。 + +## 创建域名屏蔽的副作用 + +当你创建新的域名屏蔽（或重新提交现有的域名屏蔽）时，你的实例将处理该屏蔽的副作用。这些副作用是： + +1. 将数据库中存储自目标域的所有帐户标记为已封禁，并删除被标记帐户的大多数信息（简介、显示名称、字段等）。 +2. 清除本地帐户与封禁帐户之间的所有互关或单方面关系（关注、被关注、关注请求、收藏等）。 +3. 删除封禁帐户的所有贴文。 +4. 删除封禁帐户及其贴文的所有媒体，包括媒体附件、头像、头图和表情符号。 + +!!! danger + 目前，上述大多数副作用是**不可逆**的。如果你在屏蔽后取消屏蔽一个域名，该域名上的所有帐户将不再被标记为已封禁，并且你将能够再次与他们互动，但所有关系仍将被清除，所有贴文和媒体将被删除。 + + 在屏蔽一个域名之前请仔细考虑。 + +## 屏蔽一个域名及其所有子域 + +当你添加一个新的域名屏蔽时，GoToSocial 也将屏蔽该域名的所有子域。如果你不信任域名所有者，你可以选择屏蔽某些特定子域，或者更一般地屏蔽整个域名。 + +一些例子： + +1. 你屏蔽 `example.org`。这将屏蔽以下域名（非详尽列表）：`example.org`，`subdomain.example.org`，`another-subdomain.example.org`，`sub.sub.sub.domain.example.org`。 +2. 你屏蔽 `baddies.example.org`。这将屏蔽以下域名（非详尽列表）：`baddies.example.org`，`really-bad.baddies.example.org`。然而，以下域名不会被屏蔽（非详尽列表）：`example.org`，`subdomain.example.org`，`not-baddies.example.org`。 + +一个更实际的例子： + +某个家伙拥有域名 `fossbros-anonymous.io`。他们不仅在 `mastodon.fossbros-anonymous.io` 运行 Mastodon 实例，还在 `gts.fossbros-anonymous.io` 运行 GoToSocial 实例，以及在 `akko.fossbros-anonymous.io` 运行 Akkoma 实例。你希望一次性屏蔽他们的所有这些实例（以及他们可能在未来创建的任何实例，例如 `pl.fossbros-anonymous.io` 等）。你可以通过简单地为 `fossbros-anonymous.io` 创建域名屏蔽来实现。子域上的任何实例将无法与你的实例通信。搞定！ diff --git a/docs/locales/zh/admin/federation_modes.md b/docs/locales/zh/admin/federation_modes.md new file mode 100644 index 000000000..a3958b10f --- /dev/null +++ b/docs/locales/zh/admin/federation_modes.md @@ -0,0 +1,62 @@ +# 联合模式 + +GoToSocial 当前提供“黑名单”和“白名单”联合模式，可以通过在 `config.yaml` 中设置 `instance-federation-mode`，或者使用环境变量 `GTS_INSTANCE_FEDERATION_MODE` 来配置。这些模式如下所述。 + +## 黑名单联合模式（默认） + +当 `instance-federation-mode` 设置为 `blocklist` 时，你的实例将与其他实例自由联合，没有限制，但你在设置面板中明确创建的屏蔽的实例除外。 + +当你的实例收到来自不在黑名单内的实例的新请求时，如果请求有效，并且请求者被允许查看所请求的资源（考虑贴文的可见性和任何用户级屏蔽），实例将处理该请求。 + +当你的实例遇到它以前未见过的贴文或账户的提及或公告时，如果该资源的域未通过域屏蔽条目被屏蔽，它将会去获取该资源。 + +!!! info + 黑名单联合模式是 GoToSocial 的默认联合模式。它也是大多数其他 ActivityPub 服务器实现的默认联合模式。 + +## 白名单联合模式 + +!!! warning + 白名单联合模式仍然被认为是“实验性”的，我们正在研究其在实际中的表现。它应该如其名称所示，但可能会在其他地方导致错误或出现边缘情况，我们还不确定！ + +当 `instance-federation-mode` 设置为 `allowlist` 时，你的实例将仅与通过设置面板明确设为允许的实例联合，并限制任何未被允许的实例的访问。 + +当你的实例收到来自白名单之外实例的新请求时，它将拒绝处理该请求。如果请求来自白名单中的域名，你的实例将处理该请求（考虑贴文的可见性和任何用户级别的屏蔽）。 + +当你的实例遇到它以前未见过的贴文或账户的提及或公告时，它只会在资源所属域名被明确允许时才去获取资源。 + +!!! tip + 白名单联合模式在你希望仅与选择的“可信”实例联合的情况下非常有用。然而，这会影响发现过程。在黑名单联合模式下，你会通过转发和回复自然地遇到未知实例的贴文和账户，但在白名单联合模式下，这样的偶然发现不会发生。 + + 因此，建议你要么先从黑名单联合模式开始，然后在确定喜欢哪些其他实例后切换到白名单联合模式，要么从白名单联合模式开始，并在首次启动实例后准备好并导入白名单，以便“启动”它。 + +## 结合屏蔽与允许 + +可以同时屏蔽和允许同一个域，结合这两者的效果取决于你的实例当前使用的联合模式。 + +![一个流程图，显示两种不同联合模式如何处理传入的请求。](../../../assets/diagrams/federation_modes.png) + +### 在黑名单模式下 + +如图所示，在黑名单模式下（图的左侧），显式添加允许条目可以用来覆盖域名屏蔽。 + +这在你从其他人处导入黑名单，但导入的黑名单中包含了一些你实际上不想屏蔽的实例时很有用。为了避免屏蔽这些实例，你可以先为这些实例显式创建允许条目。然后，当你导入黑名单时，显式允许的域将不会被屏蔽，并且创建屏蔽所导致的副作用（删除贴文、媒体、关系等）将不会被处理。 + +如果你以后移除对于同时存在屏蔽的域的显式允许，该实例将被屏蔽，并且将处理屏蔽创建的相关影响。 + +相反，如果你为被屏蔽的域添加显式允许，将处理解除屏蔽的相关影响。 + +### 在白名单模式下 + +如图所示，在白名单模式下（图的右侧），显式域名屏蔽条目会优先于显式域名允许条目。在运行白名单模式时，必须满足以下两个条件才能允许一个实例通过： + +1. 实例没有存在对应的显式域名屏蔽。 +2. 实例存在对应的显式域名允许。 + +如果上述任何条件不满足，请求将被拒绝。 + +!!! danger + 结合屏蔽和允许是一项棘手的工作！ + + 在导入允许和黑名单时，你应该始终手动审核列表，以确保不会无意中屏蔽你不想屏蔽的实例，因为这可能会有**非常烦人的副作用**，例如移除关注/被关注、贴文等。 + + 有疑问时，请始终首先添加显式允许作为保险策略！ diff --git a/docs/locales/zh/admin/media_caching.md b/docs/locales/zh/admin/media_caching.md new file mode 100644 index 000000000..d33e73358 --- /dev/null +++ b/docs/locales/zh/admin/media_caching.md @@ -0,0 +1,57 @@ +# 媒体缓存 + +GoToSocial 使用配置的[存储后端](https://docs.gotosocial.org/zh-cn/latest/configuration/storage/)来存储由本站用户上传到实例的媒体（图像、视频等），并缓存从外站实例联合过来的贴文和个人资料中附带的媒体。 + +由本站用户上传的媒体将会永久保存在存储中（除非其所属的贴文或账户被删除），以便能够随时响应来自外站的请求。 + +另一方面，外站媒体仅会被临时缓存。经过一段时间（见下文）后，它将从存储中移除，以帮助缓解存储空间的使用。通过这种方式被移除缓存的外站媒体，如果再次需要，将自动从外站重新获取。 + +!!! info "为什么要缓存？" + 你可能会认为应该完全不缓存外站媒体，因为它始终可以在原始服务器上获取。为什么不完全放弃缓存，而依赖外站根据需求提供服务呢？ + + 虽然这是节省存储空间的一种简单方法，但它可能会引发其他问题，并且通常被认为是不够礼貌的做法。 + + 例如，假设某个小实例的用户发布了一条带有图片的有趣贴文。该贴文被一个拥有1000名跨5个不同实例（每个实例200人）关注者的账号转发。这1000人便会同时在时间线上看到这个图片。 + + 如果没有外站媒体缓存，可能会导致多达1000个请求同时冲击小实例，因为每个接收者的浏览器必须单独请求从小实例获取该图片。这会导致小实例的流量激增。在极端情况下，可能导致实例无响应或崩溃，本质上是对其进行分布式拒绝服务攻击（DDOS）。 + + 然而，通过启用外站媒体缓存，将一条贴文转发给1000名来自5个不同实例的用户仅会向小实例发出5个请求：每个实例1个请求。然后，每个实例会从缓存的外站图片版本为其本站用户提供200个请求，有效地分散了负载，保护了较小的实例。 + +## 清理 + +外站媒体缓存的清理是一个计划的后台进程，管理员无需手动干预。根据服务器速度、配置的存储速度和待处理的媒体数量，清理时间大约在5到30分钟之间。 + +GoToSocial 提供了三个变量，让你（管理员）可以调节何时以及如何进行这些操作：`media-remote-cache-days`、`media-cleanup-from` 和 `media-cleanup-every`。 + +默认情况下，这些变量设置如下： + +| 变量名称 | 默认值 | 含义 | +|-----------------------------|--------------|----------| +| `media-remote-cache-days` | `7` | 7天 | +| `media-cleanup-from` | `"00:00"` | 午夜 | +| `media-cleanup-every` | `"24h"` | 每日 | + +换句话说，默认设置意味着每晚午夜，超过一周的外站媒体将被清除并从存储中移除。 + +你可以通过调节这些变量实现不同的效果。例如，如果你希望在凌晨4:30而不是午夜进行清理，你可以将 `media-cleanup-from` 改为 `"04:30"`。 + +如果你只想每隔几天而不是每晚进行清理，可以将 `media-cleanup-every` 设置为更高的值，如 `"48h"` 或 `"72h"`。 + +如果你想采用更积极的清理策略以尽量减少存储使用，可以设置以下值： + +| 变量名称 | 设置值 | 含义 | +|-----------------------------|--------------|-----------------| +| `media-remote-cache-days` | `1` | 1天 | +| `media-cleanup-from` | `"00:00"` | 午夜 | +| `media-cleanup-every` | `"8h"` | 每8小时 | + +上述设置意味着从午夜开始每8小时，GoToSocial 将清除任何缓存超过1天（24小时）的媒体。清理任务将在 00:00、08:00 和 16:00，即午夜、上午8点和下午4点运行。使用此配置，你可能将外站媒体在存储中保留的最长时间约为32小时。 + +!!! tip + 将 `media-remote-cache-days` 设置为0或更小意味着外站媒体将永不被清除。然而，本站孤立媒体的清理任务和其他一致性检查仍将按其他变量定义的计划运行。 + +!!! tip + 如果你愿意，你也可以通过管理面板手动执行一次性清理操作（[查看文档](./settings.md#媒体)）。 + +!!! warning + 将 `media-cleanup-every` 设置为非常小的值，如 `"30m"` 或更小，可能会导致你的实例不断遍历附件，导致数据使用率高而效益甚微。我们不建议将该值设置为小于约 `"8h"`，即便如此，可能也显得过度。 diff --git a/docs/locales/zh/admin/request_filtering_modes.md b/docs/locales/zh/admin/request_filtering_modes.md new file mode 100644 index 000000000..0079c5424 --- /dev/null +++ b/docs/locales/zh/admin/request_filtering_modes.md @@ -0,0 +1,31 @@ +# HTTP 请求头过滤模式 + +GoToSocial 当前提供“屏蔽”、“允许”和禁用的 HTTP 请求头过滤模式，可以通过在 config.yaml 中设置 `advanced-header-filter-mode`，或使用环境变量 `GTS_ADVANCED_HEADER_FILTER_MODE` 来配置。这些模式的具体说明如下。 + +!!! warning + HTTP 请求头过滤是一个高级设置。如果你不熟悉 HTTP 请求头的使用和复杂性，修改这些设置可能会导致联合功能中断，甚至无法访问你自己的实例。 + + HTTP 请求头过滤仍被视为“实验性”功能。它应该能如预期工作，但可能会导致其他地方出现错误或边缘情况，这点我们尚不确定！ + +## 禁用请求头过滤模式（默认） + +当 `advanced-header-filter-mode` 设置为 `""`（即空字符串）时，将禁用所有请求头过滤。 + +## 屏蔽过滤模式 + +当 `advanced-header-filter-mode` 设置为 `"block"` 时，你的实例将正常接受 HTTP 请求（需进行 API 令牌检查、HTTP 签名检查等），但会拒绝符合你通过设置面板明确创建的屏蔽头过滤规则的请求。 + +在屏蔽模式中，可以使用允许头过滤规则来覆盖现有的屏蔽过滤规则，以提供更细致的控制。 + +在屏蔽模式下，请求将被接受，前提是该请求被明确允许或未被明确屏蔽。 + +## 允许过滤模式 + +当 `advanced-header-filter-mode` 设置为 `"allow"` 时，你的实例只会接受那些与通过设置面板明确创建的允许头过滤规则相匹配的 HTTP 请求。所有其他请求将被拒绝。 + +在允许模式中，可以使用屏蔽头过滤规则来覆盖现有的允许过滤规则，以提供更细致的控制。 + +在允许模式下，请求只有在被明确允许且未被明确屏蔽的情况下才会被接受。 + +!!! danger + 允许过滤模式是一个极为严格的模式，几乎肯定会阻止许多（合法的）客户端访问你的实例，包括你自己。只有在完全明确你的目标时才应启用此模式。 diff --git a/docs/locales/zh/admin/robots.md b/docs/locales/zh/admin/robots.md new file mode 100644 index 000000000..89a3d4c2d --- /dev/null +++ b/docs/locales/zh/admin/robots.md @@ -0,0 +1,13 @@ +# Robots.txt + +GoToSocial 在主域名上提供一个 `robots.txt` 文件。该文件包含试图屏蔽已知 AI 爬虫的一些规则，以及其他一些索引器。它还包括一些规则，以确保诸如 API 端点之类的内容不会被搜索引擎索引，因为这些内容没有被索引的必要。 + +## AI 爬虫 + +AI 爬虫来自一个[社区维护的仓库][airobots]。目前是手动保持同步的。如果你知道有任何遗漏的爬虫，请给他们提交一个 PR！ + +已知有许多 AI 爬虫即便明确匹配其 User-Agent，也会忽略 `robots.txt` 中的条目。这意味着 `robots.txt` 文件并不是确保 AI 爬虫不抓取你的内容的万无一失的方法。 + +如果你想完全屏蔽这些爬虫，需要在反向代理中根据 User-Agent 头进行屏蔽，直到 GoToSocial 能够根据 User-Agent 头过滤请求。 + +[airobots]: https://github.com/ai-robots-txt/ai.robots.txt/ diff --git a/docs/locales/zh/admin/settings.md b/docs/locales/zh/admin/settings.md new file mode 100644 index 000000000..df03e89ad --- /dev/null +++ b/docs/locales/zh/admin/settings.md @@ -0,0 +1,169 @@ +# 管理设置面板 + +GoToSocial 管理设置面板使用 [管理 API](https://docs.gotosocial.org/zh-cn/latest/api/swagger/#operations-tag-admin) 来管理你的实例。它与 [用户设置面板](../user_guide/settings.md) 结合使用，并采用与普通客户端相同的 OAuth 机制（范围：admin）。 + +## 设置管理员账户权限和登录 + +要使用管理设置面板，你的账户必须被提升为管理员： + +```bash +./gotosocial --config-path ./config.yaml admin account promote --username 你的用户名 +``` + +为了使提权生效，可能需要在运行命令后重启你的实例。 + +之后，你可以访问 `https://[your-instance-name.org]/settings`，在登录字段中输入你的域名，然后像使用其他客户端一样登录。现在，你应该可以看到管理设置。 + +## 管理 + +实例管理设置。 + +### 举报 + +![一个展示未解决举报的举报列表。](../../../assets/admin-settings-reports.png) + +举报部分显示来自本站用户或外站（匿名显示，仅显示实例名称，不显示具体用户名）的举报列表。 + +点击举报可以查看其是否已解决（若有理由则显示），更多信息，以及由举报用户选定的被举报贴文列表。你也可以在此视图中将举报标记为已解决，并填写评论。如果该用户来自你的实例，你在此处输入的任何评论都会对创建举报的用户可见。 + +![待处理的举报的详细视图，显示被举报的贴文和举报理由。](../../../assets/admin-settings-report-detail.png) + +点击被举报账户的用户名会在“账户”视图中打开该账户，从而允许你对其执行管理操作。 + +### 账户 + +你可以使用此部分搜索账户并对其执行管理操作。 + +### 联合 + +![已封禁实例列表，有一个字段用于过滤/添加新的屏蔽。下面是批量导入/导出界面的链接](../../../assets/admin-settings-federation.png) + +在联合部分，你可以创建、删除和审核明确的域名屏蔽和域名允许。 + +关于联合设置的更多详细信息，特别是域名允许和域名屏蔽如何结合使用，请参阅 [联合模式部分](./federation_modes.md) 和 [域名屏蔽部分](./domain_blocks.md)。 + +#### 域名屏蔽 + +你可以在搜索字段中输入一个要封禁的域名，这将过滤列表以显示你是否已有该域名的屏蔽条目。 + +点击“封禁”会显示一个表单，允许你添加公开和/或私人评论，并提交以添加屏蔽。添加封禁后，该实例上的所有已知账户将被封禁，并阻止与该被屏蔽实例上的任何用户的新互动。 + +#### 域名允许 + +域名允许部分的工作方式与域名屏蔽部分类似，只是用于明确的域名允许而不是域名屏蔽。 + +#### 批量导入/导出 + +通过联合部分底部的链接（或访问 `/settings/admin/federation/import-export`），你可以批量导入/导出屏蔽列表和允许列表。 + +![导入中包含的域列表，提供选择某些或全部域的方法，更改其域，以及更新子域使用方法。](../../../assets/admin-settings-federation-import-export.png) + +通过输入字段或文件导入列表后，你可以在导入子集之前查看列表中的条目。你还会在使用子域的条目中收到警告，此处还提供一种轻松将其更改为主域的方法。 + +## 管理 + +实例管理设置。 + +### 操作 + +运行一次性管理操作。 + +#### 电子邮件 + +你可以使用此部分向指定的电子邮件地址发送测试邮件，并附加可选的测试信息。 + +#### 媒体 + +你可以使用此部分运行清理外站媒体缓存的操作，可以指定天数。超过指定天数的媒体将从存储中删除（s3 或本地）。以这种方式删除的媒体将未来需要时重新尝试获取。此操作在功能上与自动运行的媒体清理相同。 + +#### 密钥 + +你可以使用此部分使来自特定外站实例的公钥过期/失效。下次你的实例收到使用过期密钥的签名请求时，它将尝试重新获取和存储公钥。 + +### 自定义表情 + +包含在外站贴文中的自定义表情将自动获取，但要在你的帖子中使用它们，必须在你的实例上启用。 + +#### 本站 + +![本站自定义表情部分，显示按类别排序的自定义表情概览。有很多加菲猫表情。](../../../assets/admin-settings-emoji-local.png) + +此部分显示你的实例上启用的所有自定义表情的概览，按类别排序。点击某个表情可显示其详细信息，并提供更改类别或图像的选项，或完全删除它。这里无法更新短代码，你需要自己上传带有新短代码的表情（可以选择删除旧的表情）。 + +在概览下方，你可以在预览表情在贴文中的效果后上传自己的自定义表情。支持 PNG 和（动画）GIF 格式。 + +#### 外站 + +![外站自定义表情部分，显示从输入的贴文中解析的 3 个表情的列表： blobcat、blobfoxbox 和 blobhajmlem。可以选择它们，微调短代码，并在提交复制或删除操作前为其分配类别](../../../assets/admin-settings-emoji-remote.png) + +通过“外站”部分，你可以查找任何外站贴文的链接（前提是该实例未被封禁）。如果使用了任何自定义表情，它们将被列出，这样就提供了一种轻松复制到本站表情的方法（供你自己在贴文中使用），或者也可以禁止它们（从贴文中隐藏）。 + +**注意：**由于 testrig 服务器未进行联合，此功能在开发过程中无法使用（500：内部服务器错误）。 + +### 实例设置 + +![GoToSocial 管理面板的截图，显示了更改实例设置的字段](../../../assets/admin-settings-instance.png) + +在这里，你可以为你的实例设置各种元数据，如显示名称/标题、缩略图、（简短）描述和联系信息。 + +#### 实例外观 + +这些设置主要影响你的实例在网络和他人眼中的显示方式。 + +你的 **实例标题** 将显示在你实例每个网页的顶部，并在 OpenGraph 元标签中出现，所以选择一个能代表你实例氛围的名称。 + +**实例头像** 类似于你实例的吉祥物。它将出现在每个网页顶上的实例标题旁边，并作为浏览器标签、OpenGraph 链接等的预览图像。 + +如果你设置了实例头像，我们强烈建议同时设置 **头像描述**。这将为你设置为头像的图片提供替代文字，帮助屏幕阅读器用户理解图片中描绘的内容。替代文本应保持简短明了。 + +#### 实例描述 + +你可以使用这些字段设置实例的简短和完整描述，并为当前和潜在用户提供实例使用条款。 + +**简短描述** 将显示在实例主页的顶部附近，以及响应 `/api/v1/instance` 查询时显示。 + +可以提供一些精辟的内容，以便访问你的实例的访客对你的实例有一个第一印象。例如： + +> 这是一个 ACG 爱好者的实例！ +> +> 不管磕什么都可以来注册。 + +或者： + +> 这是一个单用户实例，只属于我！ +> +> 这是我的主页：@your_username + +**完整描述** 将显示在你的实例的 /about 页面上，并在响应 `/api/v1/instance` 查询时显示。 + +你可以用它来提供如下信息： + +- 你的实例的历史、理念、态度和氛围 +- 你实例上的居民倾向于发布的内容类型 +- 如何在你的实例上获得账户（如果可能的话） +- 一个拥有账户的用户列表，希望更容易被找到 + +**使用条款** 框也会出现在你的实例的 /about 页面上，并在响应 `/api/v1/instance` 查询时显示。 + +用它来填写如下内容： + +- 法律术语（版权、GDPR 或相关链接） +- 联合政策 +- 数据政策 +- 账户删除/封禁政策 + +以上所有字段都接受 **markdown** 输入，因此你可以编写合适的列表、代码块、水平线、引用块或任何你喜欢的内容。 + +你也可以使用标准 `@user[@domain]` 格式提及账户。 + +查看 [markdown 速查表](https://markdownguide.offshoot.io/cheat-sheet/) 以了解可以做些什么。 + +### 实例联系信息 + +在此部分中，你可以向访问你实例的用户提供一种方便的方法，以联系你的实例管理员。 + +设置好的联系人账户和/或电子邮件地址的链接将出现在实例的每个网页底部、/about 页面的“联系”部分，以及响应 `/api/v1/instance` 查询时显示。 + +选择的 **联系人用户** 必须是实例上的活跃（未封禁）的管理员和/或站务。 + +如果你是在单用户实例上并将管理员权限授予你的主账户，你只需在此处填写自己的用户名即可；无需为此专门创建管理账户。 diff --git a/docs/locales/zh/admin/signups.md b/docs/locales/zh/admin/signups.md new file mode 100644 index 000000000..a0d86f6a9 --- /dev/null +++ b/docs/locales/zh/admin/signups.md @@ -0,0 +1,59 @@ +# 新账户注册 + +如果你希望你的实例不仅限于你自己，还可以让其他人注册账户，你可以开放你的实例供新账户注册。 + +注意，作为实例管理员，无论你是否愿意，你都需对在你的实例上发布的内容负责。如果你的实例用户在联合网上骚扰或烦扰他人，可能会导致你的实例名誉受损，并被其他人屏蔽。妥善管理一个社区需要付出努力。因此，你应仔细考虑是否愿意且有能力进行管理，及是否只接受朋友和你非常信任的人注册账户。 + +!!! warning + 为使注册流程正常运作，你的实例应[配置电子邮件发件服务](../configuration/smtp.md)。 + + 如下所述，在注册流程中，会向你（作为管理员/站务）和申请人发送几封邮件，包括要求对方确认邮箱地址的邮件。 + + 如果他们无法收到此邮件（因为你的实例未配置电子邮件发件服务），你将需要通过[使用 CLI 工具](../admin/cli.md#gotosocial-admin-account-confirm)手动确认账户。 + +## 开放注册 + +你可以通过在[配置文件](../configuration/accounts.md)中将变量 `accounts-registration-open` 修改为 `true`，并重启你的 GoToSocial 实例来开放新账户注册。 + +你的实例将会在 `/signup` 端点提供注册表单。例如，`https://your-instance.example.org/signup`。 + +![注册表单，显示电子邮件、密码、用户名和理由字段。](../../../assets/signup-form.png) + +此外，你的实例主页和“关于”页面将更新，以反映注册现已开放。 + +当有人提交新注册申请时，他们会在提供的电子邮件地址收到一封邮件，其中包含一个链接，用于确认该地址确实属于他们。 + +同时，你实例上的管理员和站务会收到一封邮件和一条通知，告知有新的注册申请提交。 + +## 处理注册 + +实例管理员和版主可以通过管理面板中的“账户” -> “待处理”部分来审批或拒绝新注册。 + +![管理员设置面板打开到“账户” -> “待处理”，显示列表中有一个账户。](../../../assets/signup-pending.png) + +如果没有注册申请，以上列表将为空。如果有待处理的注册申请，你可以点击打开账户详情页： + +![新待处理账户详情，提供批准或拒绝注册的选项。](../../../assets/signup-account.png) + +在底部，你会看到批准或拒绝注册的操作选项。 + +如果你**批准**注册，账户将被标记为“已批准”，并会向申请人发送一封邮件，通知其注册已获批准，并提醒他们确认电子邮件地址（如果尚未确认）。如果已经确认，他们就可以登录并开始使用他们的账户。 + +如果你**拒绝**注册，可以选择通知申请人注册被拒，你可以通过勾选“发送邮件”复选框来实现。这将向申请人发送一封简短邮件，告知其被拒。如果需要，还可以添加自定义消息，该消息将添加在邮件底部。你还可以添加仅供其他管理员查看的私人备注。 + +!!! warning + 你可能希望等申请人确认他们的电子邮件地址后再批准注册，以防申请时输入错误或提供不是他们的电子邮件地址。如果他们不能确认电子邮件地址，将无法登录和使用账户。 + +## 注册限制 + +为了避免注册积压过多使管理员和版主不堪重负，GoToSocial 将待处理注册积压限制为 20 个账户。一旦积压中有 20 个账户等待管理员或版主处理，新注册将不能通过表单提交。 + +如果过去 24 小时内已批准 10 个或以上新账户注册，新的注册也将不能通过表单提交，以避免实例规模快速扩张超出管理能力。 + +在这两种情况下，申请人将看到一条错误信息，解释无法提交表单的原因，并邀请他们稍后再试。 + +为了防止垃圾账户，GoToSocial 的账户注册**始终**需要管理员手动批准，并且申请人**始终**需确认其电子邮件地址后才能登录和发布贴文。 + +## 通过邀请注册 + +尚未实现: 在未来的更新中，管理员和版主将能够创建和发送邀请，即使公共注册关闭时也允许创建账户，并可预先批准通过邀请创建的账户，和/或允许其绕过上述注册限制。 diff --git a/docs/locales/zh/admin/spam.md b/docs/locales/zh/admin/spam.md new file mode 100644 index 000000000..7af7062b3 --- /dev/null +++ b/docs/locales/zh/admin/spam.md @@ -0,0 +1,23 @@ +# 骚扰信息过滤 + +为了让管理员在应对来自开放注册实例的骚扰信息时稍微轻松一些，GoToSocial 提供了一个实验性的骚扰信息过滤选项。 + +如果你或你的用户受到骚扰信息的轰炸，可以尝试在 `config.yaml` 中将选项 `instance-federation-spam-filter` 设置为 true。你可以在[实例配置页面](../configuration/instance.md)了解有关使用的启发算法的更多信息。 + +被认为是骚扰信息的消息将不会存储在你的本站实例上，也不会生成通知。 + +!!! warning + 骚扰信息过滤器必然是不完美的工具，因为它们可能会误判一些合法的信息为垃圾，或者确实未能抓住一些*确实*是垃圾的信息。 + + 启用 `instance-federation-spam-filter` 应被视为当联合网络遭遇骚扰信息攻击时的一种“加固”选项。在正常情况下，你可能希望将其关闭，以避免意外过滤掉合法信息。 + +!!! tip + 如果你想检查骚扰信息过滤器捕获了哪些内容（如果有的话），可以在日志中搜索 `looked like spam`。 + + 如果你[将 GoToSocial 作为 systemd 服务运行](../getting_started/installation/metal.md#optional-enable-the-systemd-service)，可以使用以下命令： + + ```bash + journalctl -u gotosocial --no-pager | grep 'looked like spam' + ``` + + 如果没有输出，说明过滤器中没有捕获到骚扰信息。否则，你将看到一行或多行日志，其中包含已被过滤并丢弃的贴文链接。 diff --git a/docs/locales/zh/admin/themes.md b/docs/locales/zh/admin/themes.md new file mode 100644 index 000000000..baa79ad8a --- /dev/null +++ b/docs/locales/zh/admin/themes.md @@ -0,0 +1,13 @@ +# 主题 + +你在本站的用户可以从 `web/assets/themes` 目录中的任何 CSS 文件中选择一个主题来装饰他们的个人资料。 + +GoToSocial 自带了一些主题文件，但你可以通过以下方式添加更多： + +1. 在 `web/assets/themes` 中创建一个文件，例如 `new-theme.css`。 +2. （可选）在你的主题文件顶部加入以下注释来给你的主题命名和描述： + ```css + /* + theme-title: 新主题 + theme-description: 这是一个示例主题。 + */ diff --git a/docs/locales/zh/advanced/builds/nowasm.md b/docs/locales/zh/advanced/builds/nowasm.md new file mode 100644 index 000000000..33e6fad22 --- /dev/null +++ b/docs/locales/zh/advanced/builds/nowasm.md @@ -0,0 +1,27 @@ +# 无 Wazero / WASM 版构建 + +!!! danger "不受支持" + 我们不提供对使用本节描述的 `nowasm` 标签构建的 GoToSocial 部署的任何支持。这样的构建在任何情况下都应被视为实验性构建，任何运行时出现的问题与我们无关！请不要在存储库中提交寻求 `nowasm` 构建的调试帮助的相关问题。 + +在[支持的平台](../../getting_started/releases.md#支持的平台)上，GoToSocial 使用 WebAssembly 运行时 [Wazero](https://wazero.io/) 对 `ffmpeg`、`ffprobe` 和 `sqlite3` WebAssembly 二进制文件进行沙盒化，使这些应用程序可以被打包并在 GoToSocial 二进制文件中运行，无需管理员安装和管理任何外部依赖。 + +这使得管理员更容易维护他们的 GoToSocial 实例，因为他们的 GtS 二进制文件完全与系统安装的 `ffmpeg`、`ffprobe` 和 `sqlite` 的更改隔离开来。以这种方式运行 `ffmpeg` 也更安全一些，因为 GoToSocial 将 `ffmpeg` 二进制文件封装在一个非常受限的文件系统中，该系统不允许 `ffmpeg` 二进制文件访问除正在解码和重新编码的文件以外的任何文件。换句话说，在受支持的平台上，GoToSocial 提供了 `ffmpeg` 等的大多数功能，而不存在一些麻烦。 + +然而，并不是所有的平台都能在速度更快的“编译器”模式下运行 Wazero，因此必须使用非常慢（且资源占用大的）“解释器”模式。有关符合性的详细信息，请参考 Wazero 的[此表](https://github.com/tetratelabs/wazero?tab=readme-ov-file#conformance)。 + +“解释器”模式的运行性能非常差，以至于在不是 64 位 Linux 或 64 位 FreeBSD 的平台上运行 GoToSocial 实例是不切实际的，因为所有的内存和 CPU 都被媒体处理消耗殆尽。 + +但是！为了让用户能够运行**实验性、不受支持的 GoToSocial 部署**，我们开放了 `nowasm` 构建标签，该标签可用于编译完全不使用 Wazero 或 WASM 的 GoToSocial 构建。 + +使用 `nowasm` 构建的 GoToSocial 二进制文件将使用 [modernc 版本的 SQLite](https://pkg.go.dev/modernc.org/sqlite) 而不是 WASM 版本，并将在系统上使用 `ffmpeg` 和 `ffprobe` 二进制文件进行媒体处理。 + +要使用 `nowasm` 标签构建 GoToSocial，可以像这样将标签传入我们的便利 `build.sh` 脚本： + +```bash +GO_BUILDTAGS=nowasm ./scripts/build.sh +``` + +要运行以此方式构建的 GoToSocial 版本，你必须确保在主机上安装了 `ffmpeg` 和 `ffprobe`。这通常只需运行类似 `doas -u root pkg_add ffmpeg`（OpenBSD）或 `sudo apt install ffmpeg`（Debian 等）的命令即可。 + +!!! danger "确实不受支持" + 再次强调，如果在你的操作系统/架构组合上运行 `nowasm` 构建的 GoToSocial 有效，那很好，但我们不会为这样的构建提供支持，也无法帮助调试为何某些功能不起作用。 diff --git a/docs/locales/zh/advanced/caching/api.md b/docs/locales/zh/advanced/caching/api.md new file mode 100644 index 000000000..56117e5cd --- /dev/null +++ b/docs/locales/zh/advanced/caching/api.md @@ -0,0 +1,84 @@ +# 缓存 API 响应 + +可以缓存某些 API 响应，以减少 GoToSocial 处理所有请求的负担。我们不建议缓存 `/api` 下请求的响应。 + +在使用[分域](../host-account-domain.md)部署方式时，你需要确保在主机域上配置缓存。账号域应仅发出重定向到主机域的指令，客户端会自动记住这些指令。 + +## 端点 + +### Webfinger 和 hostmeta + +对 `/.well-known/webfinger` 和 `/.well-known/host-meta` 的请求可以安全地缓存。注意确保任何缓存策略都考虑到 webfinger 请求的查询参数，因为对该端点的请求形式为 `?resource=acct:@username@domain.tld`。 + +### 公钥 + +许多实现将定期请求用户的公钥，以验证收到消息的签名。这将在消息联合的过程中发生。这些密钥是长期存在的，因此可以用长时间缓存。 + +## 配置代码片段 + +=== "nginx" + +请先在 nginx 中配置一个缓存区。该缓存区必须在 `http` 节内创建，而非 `server` 或 `location` 内。 + +```nginx +http { + ... + proxy_cache_path /var/cache/nginx keys_zone=gotosocial_ap_public_responses:10m inactive=1w; +} +``` + +这配置了一个 10MB 的缓存，其条目将在一周内未被访问时保留。 + +该区域命名为 `gotosocial_ap_public_responses`，你可以自行更改名称。10MB 可以容纳大量缓存键；在小实例上可以使用更小的值。 + +其次，我们需要更新 GoToSocial 的 nginx 配置，以便真正使用我们想要缓存的端点的缓存。 + +```nginx +server { + server_name social.example.org; + + location ~ /.well-known/(webfinger|host-meta)$ { + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; + + proxy_cache gotosocial_ap_public_responses; + proxy_cache_background_update on; + proxy_cache_key $scheme://$host$uri$is_args$query_string; + proxy_cache_valid 200 10m; + proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504 http_429; + proxy_cache_lock on; + add_header X-Cache-Status $upstream_cache_status; + + proxy_pass http://localhost:8080; + } + + location ~ ^\/users\/(?:[a-z0-9_\.]+)\/main-key$ { + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; + + proxy_cache gotosocial_ap_public_responses; + proxy_cache_background_update on; + proxy_cache_key $scheme://$host$uri; + proxy_cache_valid 200 604800s; + proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504 http_429; + proxy_cache_lock on; + add_header X-Cache-Status $upstream_cache_status; + + proxy_pass http://localhost:8080; + } +} +``` + +`proxy_pass` 和 `proxy_set_header` 大致相同，但 `proxy_cache*` 条目需要一些说明： + +- `proxy_cache gotosocial_ap_public_responses` 告诉 nginx 使用我们之前创建的 `gotosocial_ap_public_responses` 缓存区。如果你用的是其他名称，需要更改此值。 +- `proxy_cache_background_update on` 表示 nginx 会尝试在后台刷新即将过期的缓存资源，以确保磁盘上有最新副本。 +- `proxy_cache_key` 的配置确保缓存时考虑到查询字符串。所以请求 `.well-known/webfinger?acct=user1@example.org` 和 `.well-known/webfinger?acct=user2@example.org` 被视为不同请求。 +- `proxy_cache_valid 200 10m;` 意味着我们只缓存来自 GTS 的 200 响应，时间为 10 分钟。你可以添加类似 `proxy_cache_valid 404 1m;` 的其他行，来缓存 404 响应 1 分钟。 +- `proxy_cache_use_stale` 告诉 nginx 允许在某些情况下使用过期的缓存条目（超过 10 分钟）。 +- `proxy_cache_lock on` 表示如果资源未缓存且有多个并发请求，则查询将排队，以便只有一个请求通过，其他请求则从缓存中获取答案。 +- `add_header X-Cache-Status $upstream_cache_status` 将 `X-Cache-Status` 头添加到响应中，以便你可以检查是否正在缓存。你可以删除此项。 + +上述配置将在代理到 GoToSocial 时出错、连接到 GoToSocial 时超时、GoToSocial 返回 `5xx` 状态码或 GoToSocial 返回 429（请求过多）时提供过期响应。`updating` 值表示允许在 nginx 刷新缓存时提供过期的条目。因为我们在 `proxy_cache_path` 指令中配置了 `inactive=1w`，所以如果满足 `proxy_cache_use_stale` 中的条件，nginx 可以提供最长一周的缓存响应。 diff --git a/docs/locales/zh/advanced/caching/assets-media.md b/docs/locales/zh/advanced/caching/assets-media.md new file mode 100644 index 000000000..2ff522897 --- /dev/null +++ b/docs/locales/zh/advanced/caching/assets-media.md @@ -0,0 +1,132 @@ +# 缓存资源与媒体 + +当你配置 GoToSocial 实例使用本地存储媒体时，可以使用你的[反向代理](../../getting_started/reverse_proxy/index.md)直接提供这些文件并进行缓存。这样可以避免频繁请求 GoToSocial，同时反向代理通常能比 GoToSocial 更快地提供资源。 + +你还可以使用反向代理来缓存 GoToSocial Web UI 的资源，比如其使用的 CSS 和图片。 + +当使用[分域](../host-account-domain.md)部署方式时，你需要确保在主机域上配置资源和媒体的缓存。 + +!!! warning "媒体修剪" + 如果你配置了媒体修剪，必须确保当磁盘上找不到媒体时，仍然将请求发送到 GoToSocial。这将保证从外站实例重新获取该媒体，之后的请求将再次由你的反向代理处理。 + +## 端点 + +有两个端点提供可服务和缓存的资源： + +* `/assets` 包含字体、CSS、图像等 Web UI 的资源 +* `/fileserver` 在使用本地存储后端时，服务于贴文的附件 + +`/assets` 的文件系统位置由 [`web-asset-base-dir`](../../configuration/web.md) 配置选项定义。`/fileserver` 下的文件从 [`storage-local-base-path`](../../configuration/storage.md) 获取。 + +## 配置 + +=== "apache2" + + `Cache-Control` 头手动设置，合并配置和 `expires` 指令的值，以避免因为两个头行而导致错误。默认情况下 `Header set` 为 `onsuccess`，因此它也不会添加到错误响应中。 + + 假设你的 GtS 安装在 `/opt/GtS` 根目录下，并有一个 `storage` 子目录，且 Web 服务器已被授予访问权限，可以在 vhost 中添加以下部分： + + ```apacheconf + + Options None + AllowOverride None + Require all granted + ExpiresActive on + ExpiresDefault A300 + Header set Cache-Control "public, max-age=300" + + RewriteRule "^/assets/(.*)$" "/opt/GtS/web/assets/$1" [L] + + + Options None + AllowOverride None + Require all granted + ExpiresActive on + ExpiresDefault A604800 + Header set Cache-Control "private, immutable, max-age=604800" + + RewriteCond "/opt/GtS/storage/$1" -f + RewriteRule "^/fileserver/(.*)$" "/opt/GtS/storage/$1" [L] + ``` + + 这里的技巧是在基于 Apache 2 的反向代理设置中… + + ```apacheconf + RewriteEngine On + + RewriteCond %{HTTP:Upgrade} websocket [NC] + RewriteCond %{HTTP:Connection} upgrade [NC] + RewriteRule ^/?(.*) "ws://localhost:8980/$1" [P,L] + + ProxyIOBufferSize 65536 + ProxyTimeout 120 + + ProxyPreserveHost On + + ProxyPass http://127.0.0.1:8980/ + ProxyPassReverse http://127.0.0.1:8980/ + + ``` + + … 默认情况下所有的请求都是通过代理的，`RewriteRule` 通过指定文件系统路径来绕过代理以重定向到特定 URL 前缀，而 `RewriteCond` 确保只有在文件确实存在时才禁用 `/fileserver/` 代理。 + + 你还需要运行以下命令（假设使用类似 Debian 的设置）来启用使用的模块： + + ``` + $ sudo a2enmod expires + $ sudo a2enmod headers + $ sudo a2enmod rewrite + ``` + + 然后（在测试配置后）重启 Apache。 + +=== "nginx" + + 以下是你需要在现有的 nginx 配置中添加的三个位置块的示例： + + ```nginx + server { + server_name social.example.org; + + location /assets/ { + alias web-asset-base-dir/; + autoindex off; + expires 5m; + add_header Cache-Control "public"; + } + + location @fileserver { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; + } + + location /fileserver/ { + alias storage-local-base-path/; + autoindex off; + expires 1w; + add_header Cache-Control "private, immutable"; + try_files $uri @fileserver; + } + } + ``` + + `/fileserver` 位置有点特殊。当我们无法从磁盘获取媒体时，我们希望将请求代理到 GoToSocial，以便它尝试获取。`try_files` 指令本身不能使用 `proxy_pass`，所以我们创建了命名的 `@fileserver` 位置，在 `try_files` 中最后传递给它。 + + !!! bug "尾部斜杠" + `location` 指令和 `alias` 中的尾部斜杠很重要，不要移除它们。 + + `expires` 指令添加了必要的头信息，以告知客户端可以缓存资源的时间： + + * 对于资源，因为可能在每次发布时更改，所以在此示例中使用了 5 分钟 + * 对于附件，因为一旦创建后永远不会更改，所以当前使用一周 + + 有关其他选项，请参阅 [nginx 的 `expires` 指令](https://nginx.org/en/docs/http/ngx_http_headers_module.html#expires)文档。 + + Nginx 不会为 4xx 或 5xx 响应代码添加缓存头，因此抓取资源失败时不会被客户端缓存。`autoindex off` 指令告诉 nginx 不提供目录列表。这应该是默认设置，但明确设置不会有害。添加的 `add_header` 行为 `Cache-Control` 头设置了额外的选项： + + * `public` 用于指示任何人都可以缓存此资源 + * `immutable` 用于指示该资源在其新鲜期内（在 `expires` 之前）绝不会更改，允许客户端在此期间忽略条件请求以重新验证资源。 diff --git a/docs/locales/zh/advanced/caching/index.md b/docs/locales/zh/advanced/caching/index.md new file mode 100644 index 000000000..85b2292b5 --- /dev/null +++ b/docs/locales/zh/advanced/caching/index.md @@ -0,0 +1,11 @@ +# 缓存 + +本节涵盖了多种缓存技术，这些技术可以提高 GoToSocial 在高流量情况下的稳定性，并减轻 GoToSocial 实例的一部分工作负担。 + +!!! note + 这些指南仅在你运行[反向代理](../../getting_started/reverse_proxy/index.md)时才有意义。 + +## 指南 + +* [缓存 API 响应](api.md) +* [缓存资源与媒体](assets-media.md) diff --git a/docs/locales/zh/advanced/certificates.md b/docs/locales/zh/advanced/certificates.md new file mode 100644 index 000000000..2b2d0fa0c --- /dev/null +++ b/docs/locales/zh/advanced/certificates.md @@ -0,0 +1,108 @@ +# 配置 TLS 证书 + +如[部署注意事项](../getting_started/index.md)中所述，联合需要使用 TLS，因为大多数实例拒绝通过未加密的传输进行联合。 + +GoToSocial 内置了通过 Lets Encrypt 进行 TLS 证书的配置和更新支持。本指南介绍如何独立于 GoToSocial 配置证书。如果你想完全控制证书的配置方式，或者因为你正在使用执行 TLS 终止的[反向代理](../getting_started/reverse_proxy/index.md)，这将很有用。 + +获取 TLS 证书的方式有几种： + +* 从供应商购买，通常有效期为 2 年 +* 从云提供商获取，具体有效期取决于其产品限制 +* 从像 Lets Encrypt 这样的[ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment)兼容提供商处获取，通常有效期为 3 个月 + +在本指南中，我们只讨论第三种，有关 ACME 兼容提供商的选项。 + +## 一般方法 + +通过 Lets Encrypt 配置证书的方法是： + +* 在你的服务器上安装 ACME 客户端 +* 配置 ACME 客户端来配置你的证书 +* 配置一个软件使用这些证书 +* 启用定时器/cron 定期续订证书 +* 通知必要的应用程序重新加载或重启以获取新证书 + +证书是通过[使用质询](https://letsencrypt.org/sv/docs/challenge-types/)来配置的，这是一种验证你为自己控制的域请求证书的方法。你通常会使用以下之一： + +* HTTP 质询 +* DNS 质询 + +HTTP 质询要求在所请求证书的域上的 80 端口下提供某些文件，路径为 `/.well-known/acme/`。这是默认质询类型。 + +DNS 质询完全在服务器外进行，但需要你更新 DNS TXT 记录。此方法只有在你的 DNS 注册商提供 API，使你的 ACME 客户端完成此质询时才可行。 + +## 客户端 + +官方的 Lets Encrypt 客户端是 [certbot](https://certbot.eff.org/)，通常在你选择的[（Linux）发行版](https://repology.org/project/certbot/versions)中打包。某些反向代理如 Caddy 和 Traefik 内置了使用 ACME 协议配置证书的支持。 + +你可以考虑使用的其他一些客户端包括： + +* [acme-client](https://man.openbsd.org/acme-client.1)，适用于 OpenBSD，使用平台的特权分离功能 +* [lacme](https://git.guilhem.org/lacme/about/)，以进程隔离和最低特权为构建目标，类似于 acme-client 但适用于 Linux +* [Lego](https://github.com/go-acme/lego)，用 Go 编写的 ACME 客户端和库 +* [mod_md](https://httpd.apache.org/docs/2.4/mod/mod_md.html)，适用于 Apache 2.4.30+ + +### DNS 质询 + +对于 DNS 质询，你的注册商的 API 需要被你的 ACME 客户端支持。尽管 certbot 对一些流行提供商有一些插件，但你可能想查看 [dns-multi](https://github.com/alexzorin/certbot-dns-multi) 插件。它在幕后使用 [Lego](https://github.com/go-acme/lego)，支持更广泛的供应商。 + +## 配置 + +有三个重要的配置选项： + +* [`letsencrypt-enabled`](../configuration/tls.md) 控制 GoToSocial 是否尝试配置自己的证书 +* [`tls-certificate-chain`](../configuration/tls.md) 文件系统路径，GoToSocial 可以在此找到 TLS 证书链和公钥 +* [`tls-certificate-key`](../configuration/tls.md) 文件系统路径，GoToSocial 可以在此找到关联的 TLS 私钥 + +### 不使用反向代理 + +当直接将 GoToSocial 暴露到互联网，但仍想使用自己的证书时，可以设置以下选项： + +```yaml +letsencrypt-enabled: false +tls-certificate-chain: "/path/to/combined-certificate-chain-public.key" +tls-certificate-key: "/path/to/private.key" +``` + +这将禁用通过 Lets Encrypt 内置的证书配置，并指示 GoToSocial 在磁盘上找到证书。 + +!!! tip + 在续订证书后应重启 GoToSocial。它在这种情况下不会自动监测证书的更换。 + +### 使用反向代理 + +当在执行 TLS 终止的[反向代理](../getting_started/reverse_proxy/index.md)后运行 GoToSocial 时，你需要如下设置： + +```yaml +letsencrypt-enabled: false +tls-certificate-chain: "" +tls-certificate-key: "" +``` + +确保 `tls-certificate-*` 选项未设置或设置为空字符串。否则，GoToSocial 将尝试自行处理 TLS。 + +!!! danger "协议配置选项" + **不要**将 [`protocol`](../configuration/general.md) 配置选项更改为 `http`。此选项仅应在开发环境中设置为 `http`。即使在 TLS 终止的反向代理后运行，也需要设置为 `https`。 + +你还需要更改 GoToSocial 绑定的[`port`](../configuration/general.md)，以便它不再尝试使用 443 端口。 + +要在反向代理中配置 TLS，请参考其文档： + +* [nginx](https://docs.nginx.com/nginx/admin-guide/security-controls/terminating-ssl-http/) +* [apache](https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html) +* [Traefik](https://doc.traefik.io/traefik/https/tls/) +* [Caddy](https://caddyserver.com/docs/caddyfile/directives/tls) + +!!! tip + 在你的反向代理中配置 TLS 时，请确保你配置了一组较现代的兼容版本和加密套件。可以使用 [Mozilla SSL Configuration Generator](https://ssl-config.mozilla.org/) 的“中级”配置。 + + 检查你的反向代理文档，以了解在证书更改后是否需要重新加载或重启它。并非所有的反向代理都会自动检测到这一点。 + +## 指南 + +网上有许多优质资源解释如何设置这些内容。 + +* [ArchWiki 条目](https://wiki.archlinux.org/title/certbot)关于 certbot +* [Gentoo wiki 条目](https://wiki.gentoo.org/wiki/Let%27s_Encrypt)关于 Lets Encrypt +* [Linode 指南](https://www.linode.com/docs/guides/enabling-https-using-certbot-with-nginx-on-fedora/)关于 Fedora、RHEL/CentOS、Debian 和 Ubuntu 上的 certbot +* Digital Ocean 指南关于在 Ubuntu 22.04 上用 [nginx](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-22-04) 或 [apache](https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-ubuntu-22-04)使用 Lets Encrypt diff --git a/docs/locales/zh/advanced/healthchecks.md b/docs/locales/zh/advanced/healthchecks.md new file mode 100644 index 000000000..e3063842a --- /dev/null +++ b/docs/locales/zh/advanced/healthchecks.md @@ -0,0 +1,48 @@ +# 健康检查 + +GoToSocial 提供了两个健康检查 HTTP 端点：`/readyz` 和 `/livez`。 + +这些端点可以用来检查 GoToSocial 是否可访问，并能够进行简单的数据库查询。 + +`/livez` 会始终返回 200 OK 响应且无内容，支持 GET 和 HEAD 请求。这用于检查 GoToSocial 服务是否存活。 + +如果 GoToSocial 能够对配置的数据库后台执行一个非常简单的 SELECT 查询，`/readyz` 会在 GET 和 HEAD 请求下返回 200 OK 响应且无内容。如果执行 SELECT 时发生错误，错误会被记录，并返回 500 Internal Server Error，但无内容。 + +你可以使用上述端点在容器运行时/编排系统中实现健康检查。 + +例如，在 Docker 设置中，你可以在 docker-compose.yaml 中添加以下内容： + +```yaml +healthcheck: + test: wget --no-verbose --tries=1 --spider http://localhost:8080/readyz || exit 1 + interval: 120s + retries: 5 + start_period: 30s + timeout: 10s +``` + +上述健康检查将在 30 秒后开始，每两分钟检查一次服务是否可用，通过对 `/readyz` 进行 HEAD 请求。如果检查连续失败五次，服务将被标记为不健康。你可以在使用的编排系统中利用此功能强制重启容器。 + +!!! warning + 在慢速硬件上进行数据库迁移时，迁移可能会超过上述健康检查所允许的 10 分钟。 + + 在这样的系统上，你可能需要增加健康检查的间隔或重试次数，以确保不会在迁移中途停止 GoToSocial（这会很糟糕！）。 + +!!! tip + 尽管健康检查端点不透露任何敏感信息，并且只运行非常简单的查询，你可能希望避免将它们暴露给外部世界。你可以在 nginx 中通过在 `server` 段中添加以下代码片段来实现： + + ```nginx + location /livez { + return 404; + } + location /readyz { + return 404; + } + ``` + + 这样会导致 nginx 在请求传递给 GoToSocial 之前拦截这些请求，并直接返回 404 Not Found。 + +参考资料： + +- [Dockerfile 参考](https://docs.docker.com/reference/dockerfile/#healthcheck) +- [Compose 文件参考](https://docs.docker.com/compose/compose-file/compose-file-v3/#healthcheck) diff --git a/docs/locales/zh/advanced/host-account-domain.md b/docs/locales/zh/advanced/host-account-domain.md new file mode 100644 index 000000000..5b758a99c --- /dev/null +++ b/docs/locales/zh/advanced/host-account-domain.md @@ -0,0 +1,116 @@ +# 分域部署 + +本指南解释了如何使用 `@me@example.org` 这样的用户名，但将 GoToSocial 实例本身运行在例如 `social.example.org` 这样的子域名的方法。这种部署布局的配置**必须**在第一次启动 GoToSocial 前完成。 + +!!! danger + 一旦与他人联合后就无法更改域名布局。服务器会因此产生混淆，而你需要说服每个与你联合的实例管理员修改其数据库来解决问题。同时，你还需要在本地重新生成数据库，创建一个新的实例账户和加密密钥对。 + +## 背景 + +ActivityPub 实现通过一个称为 [webfinger](https://www.rfc-editor.org/rfc/rfc7033) 的协议来发现如何将你的账户域映射到你的主机域。这种映射通常会被服务器缓存，因此在事后无法更改。 + +它的工作原理是请求 `https://<账户域>/.well-known/webfinger?resource=acct:@me@example.org`。此时，服务器可以返回重定向到实际的 webfinger 端点 `https://<主机域>/.well-known/webfinger?resource=acct:@me@example.org` 或直接响应。返回的 JSON 文档告知应查询的用户端点： + +```json +{ + "subject": "acct:me@example.org", + "aliases": [ + "https://social.example.org/users/me", + "https://social.example.org/@me" + ], + "links": [ + { + "rel": "http://webfinger.net/rel/profile-page", + "type": "text/html", + "href": "https://social.example.org/@me" + }, + { + "rel": "self", + "type": "application/activity+json", + "href": "https://social.example.org/users/me" + } + ] +} +``` + +ActivityPub 客户端和服务器将使用 `links` 数组中 `rel` 为 `self` 和 `type` 为 `application/activity+json` 的条目来查询更多信息，比如在哪里找到 `inbox` 以进行联合消息的传递。 + +## 配置 + +你需要关注两个配置设置： + +* `host`，API 运行的域名，以及客户端和服务器与实例通信时使用的域 +* `account-domain`，用户账户所属的域名 + +为了实现引言中描述的设置，你需要相应地设置这两个配置选项： + +```yaml +host: social.example.org +account-domain: example.org +``` + +!!! info + `host` 必须始终是运行 GoToSocial 实例的 DNS 名称。它不影响 GoToSocial 实例绑定的 IP 地址。该地址由 `bind-address` 控制。 + +## 反向代理 + +使用[反向代理](../getting_started/reverse_proxy/index.md)时，需要确保能够处理这两个域的流量。你需要将一些端点从账户域重定向到主机域。 + +重定向通常用于客户端侧检测域变化。需要从账户域重定向到主机域的端点是： + +* `/.well-known/webfinger` +* `/.well-known/host-meta` +* `/.well-known/nodeinfo` + +!!! tip + 不要将 API 端点 `/api/...` 的请求从账户域代理或重定向到主机域。这会混淆某些客户端用来检测分域部署的启发式方法，导致登录流程中断及其他异常行为。 + +### nginx + +为了配置重定向，你需要在账户域上进行配置。假设账户域为 `example.org`，主机域为 `social.example.org`，以下配置代码展示了如何做到这一点： + +```nginx +server { + server_name example.org; # account-domain + + location /.well-known/webfinger { + rewrite ^.*$ https://social.example.org/.well-known/webfinger permanent; # host + } + + location /.well-known/host-meta { + rewrite ^.*$ https://social.example.org/.well-known/host-meta permanent; # host + } + + location /.well-known/nodeinfo { + rewrite ^.*$ https://social.example.org/.well-known/nodeinfo permanent; # host + } +} +``` + +### Traefik + +如果 `example.org` 运行在 [Traefik](https://doc.traefik.io/traefik/) 上，可以使用类似以下的标签设置重定向。 + +```yaml +myservice: + image: foo + # 其他配置 + labels: + - 'traefik.http.routers.myservice.rule=Host(`example.org`)' # account-domain + - 'traefik.http.middlewares.myservice-gts.redirectregex.permanent=true' + - 'traefik.http.middlewares.myservice-gts.redirectregex.regex=^https://(.*)/.well-known/(webfinger|nodeinfo|host-meta)(\?.*)?' # host + - 'traefik.http.middlewares.myservice-gts.redirectregex.replacement=https://social.${1}/.well-known/${2}${3}' # host + - 'traefik.http.routers.myservice.middlewares=myservice-gts@docker' +``` + +### Caddy 2 + +确保在你的 `Caddyfile` 中在账户域上配置重定向。以下示例假设账户域为 `example.com`，主机域为 `social.example.com`。 + +``` +example.com { # account-domain + redir /.well-known/host-meta* https://social.example.com{uri} permanent # host + redir /.well-known/webfinger* https://social.example.com{uri} permanent # host + redir /.well-known/nodeinfo* https://social.example.com{uri} permanent # host +} +``` diff --git a/docs/locales/zh/advanced/index.md b/docs/locales/zh/advanced/index.md new file mode 100644 index 000000000..73790ac22 --- /dev/null +++ b/docs/locales/zh/advanced/index.md @@ -0,0 +1,19 @@ +# 高级 + +在本节中，我们将讨论多个高级主题，主要涉及 GoToSocial 的构建、部署、操作和调优。 + +我们将这些主题视为高级主题，因为不正确地应用它们可能导致客户端和联合问题。如果你不了解所做的更改，应用其中的任何配置更改也可能使调试你的 GoToSocial 实例问题变得更困难。 + +## 指南 + +* [分域部署（API 与账户域名）](host-account-domain.md) +* [使用 HTTP 代理进行客户端/外部请求](outgoing-proxy.md) +* [配置 TLS 证书](certificates.md) +* [缓存 API 响应](caching/api.md) +* [缓存资源及媒体](caching/assets-media.md) +* [进程沙箱](security/sandboxing.md) +* [配置防火墙](security/firewall.md) +* [追踪](tracing.md) +* [指标](metrics.md) +* [配置 SQLite 副本](replicating-sqlite.md) +* [网络存储上的 SQLite](sqlite-networked-storage.md) diff --git a/docs/locales/zh/advanced/metrics.md b/docs/locales/zh/advanced/metrics.md new file mode 100644 index 000000000..a9110bf91 --- /dev/null +++ b/docs/locales/zh/advanced/metrics.md @@ -0,0 +1,57 @@ +# 指标 + +GoToSocial 提供了基于 [OpenTelemetry][otel] 的指标。这些指标使用 [Prometheus 暴露格式][prom]，通过 `/metrics` 路径展示。配置设置在 [可观察性配置参考][obs] 中有详细说明。 + +当前收集的指标包括： + +* Go 性能和运行时指标 +* Gin (HTTP) 指标 +* Bun (数据库) 指标 + +可以通过以下配置启用指标： + +```yaml +metrics-enabled: true +``` + +虽然指标不包含任何隐私敏感信息，但你可能不希望随便让任何人查看和抓取你的实例的运营指标。 + +## 启用基本身份验证 + +你可以为指标端点启用基本身份验证。在 GoToSocial 上，你需要以下配置： + +```yaml +metrics-auth-enabled: true +metrics-auth-username: some_username +metrics-auth-password: some_password +``` + +你可以使用 Prometheus 实例通过以下 `scrape_configs` 配置抓取该端点： + +```yaml +- job_name: gotosocial + metrics_path: /metrics + scheme: https + basic_auth: + username: some_username + password: some_password + static_configs: + - targets: + - example.org +``` + +## 屏蔽外部抓取 + +当使用反向代理运行时，可以利用它来屏蔽对指标的外部访问。如果你的 Prometheus 抓取器在与 GoToSocial 实例相同的机器上运行，并可以内部访问它，可以使用这种方法。 + +例如使用 nginx，通过返回 404 来屏蔽 `/metrics` 端点： + +```nginx +location /metrics { + return 404; +} +``` + +[otel]: https://opentelemetry.io/ +[prom]: https://prometheus.io/docs/instrumenting/exposition_formats/ +[obs]: ../configuration/observability.md \ No newline at end of file diff --git a/docs/locales/zh/advanced/outgoing-proxy.md b/docs/locales/zh/advanced/outgoing-proxy.md new file mode 100644 index 000000000..86fbfea91 --- /dev/null +++ b/docs/locales/zh/advanced/outgoing-proxy.md @@ -0,0 +1,21 @@ +# 出站 HTTP 代理 + +GoToSocial 支持配置 HTTP 代理使用的标准环境变量，用于出站请求： + +* `HTTP_PROXY` +* `HTTPS_PROXY` +* `NO_PROXY` + +这些环境变量的小写版本也同样被识别。在处理 https 请求时，`HTTPS_PROXY` 的优先级高于 `HTTP_PROXY`。 + +环境变量的值可以是完整的 URL 或 `host[:port]`，在这种情况下默认使用 "http" 协议。支持的协议包括 "http"、"https" 和 "socks5"。 + +## systemd + +使用 systemd 运行时，可以在 `Service` 部分使用 `Environment` 选项添加必要的环境变量。 + +如何操作可以参考 [`systemd.exec` 手册](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Environment)。 + +## 容器运行时 + +可以在 compose 文件的 `environment` 键下设置环境变量。你也可以在命令行中使用 `-e KEY=VALUE` 或 `--env KEY=VALUE` 传递给 Docker 或 Podman 的 `run` 命令。 diff --git a/docs/locales/zh/advanced/replicating-sqlite.md b/docs/locales/zh/advanced/replicating-sqlite.md new file mode 100644 index 000000000..13361fc35 --- /dev/null +++ b/docs/locales/zh/advanced/replicating-sqlite.md @@ -0,0 +1,102 @@ +# 配置 SQLite 副本 + +除了常规的[备份方法](../admin/backup_and_restore.md)之外，你可能还想设置副本功能，以便在发生灾难时恢复到另一个路径或外部主机。 + +为了使其正常工作，SQLite 需要将日志模式配置为 `WAL` 模式，且同步模式设置为 `NORMAL`。这是 GoToSocial 的默认配置。 + +你可以在配置文件中检查你的设置。日志模式在 `db-sqlite-journal-mode` 中设置，同步模式在 `db-sqlite-synchronous` 中设置。 + +## Linux 下的 Litestream + +使用 [Litestream](https://litestream.io) 是设置 SQLite 副本的一种相对轻量且快速的方法。它可以很容易地配置，并支持不同的后端，比如基于文件的副本、兼容 S3 的存储和许多其他设置。 + +你可以通过在 Linux 上使用 deb 文件安装预构建的软件包，或在其他发行版上从源代码构建。 + +在 Linux 上使用 .deb 包： + +转到 [releases page](https://github.com/benbjohnson/litestream/releases/latest)，下载最新版本（确保为下面的 wget 命令选择合适的平台）。 + +```bash +wget https://github.com/benbjohnson/litestream/releases/download/v0.3.13/litestream-v0.3.13-linux-amd64.deb +sudo dpkg -i litestream-*.deb +``` + +## 配置 Litestream + +通过编辑配置文件进行配置。文件位于 /etc/litestream.yml。 + +### 配置基于文件的副本 + +```yaml +dbs: + - path: /gotosocial/sqlite.db + - path: /backup/sqlite.db +``` + +### 配置基于 S3 的副本 + +设置一个用于副本的桶，并确保将其设置为私有。 +确保用你仪表板中的正确值替换示例中的 `access-key-id` 和 `secret-access-key`。 + +```yaml +access-key-id: AKIAJSIE27KKMHXI3BJQ +secret-access-key: 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 + +dbs: + - path: /gotosocial/sqlite.db + - url: s3://my.bucket.com/db +``` + +使用兼容 S3 的存储提供商时，你需要设置一个端点。 +例如，对 minio 可以使用以下配置。 + +```yaml +access-key-id: miniouser +secret-access-key: miniopassword + +dbs: + - path: /gotosocial/sqlite.db + - type: s3 + bucket: mybucket + path: sqlite.db + endpoint: minio:9000 +``` + +## 启用副本 + +你可以通过启用 Litestream 服务在 Linux 上启用副本。 + +```bash +sudo systemctl enable litestream +sudo systemctl start litestream +``` + +使用 `sudo journalctl -u litestream -f` 检查其是否正常运行。 + +如果你需要更改配置文件，请重启 Litestream： + +```bash +sudo systemctl restart litestream +``` + +### 从配置的后端恢复 + +你可以使用以下简单命令从存储的后端拉取恢复文件。 + +```bash +sudo litestream restore +``` + +如果你配置了多个文件备份或有多个副本，请指定你要执行的操作。 + +对于基于文件的副本： + +```bash +sudo litestream restore -o /gotosocial/sqlite.db /backup/sqlite.db +``` + +对于基于 S3 的副本： + +```bash +sudo litestream restore -o /gotosocial/sqlite.db s3://bucketname/db +``` diff --git a/docs/locales/zh/advanced/security/firewall.md b/docs/locales/zh/advanced/security/firewall.md new file mode 100644 index 000000000..bf78cad76 --- /dev/null +++ b/docs/locales/zh/advanced/security/firewall.md @@ -0,0 +1,174 @@ +# 防火墙 + +你应该在你的实例上部署防火墙，以关闭任何开放端口，并提供一个机制来封禁可能行为不端的客户端。许多防火墙前端还会自动安装一些规则来屏蔽明显的恶意数据包。 + +部署工具来监控日志文件中的某些趋势，并自动封禁表现出某种行为的客户端是很有帮助的。这可以用于监控你的 SSH 和 Web 服务器访问日志，以应对如 SSH 暴力破解攻击。 + +## 端口 + +对于 GoToSocial，你需要确保端口 `443` 保持开放。没有它，任何人都无法访问你的实例。联合将失败，客户端应用程序将无法正常工作。 + +如果你使用 ACME 或 GoToSocial 的内置 Lets Encrypt 支持[配置 TLS 证书](../certificates.md)，你还需要开放端口 `80`。 + +为了通过 SSH 访问你的实例，你还需要保持 SSH 守护进程绑定的端口开放。默认情况下，SSH 端口是 `22`。 + +## ICMP + +[ICMP](https://en.wikipedia.org/wiki/Internet_Control_Message_Protocol) 是在机器之间交换数据，以检测某些网络条件或排除故障的协议。许多防火墙倾向于完全屏蔽 ICMP，但这并不理想。应该允许一些 ICMP 类型，你可以使用防火墙为它们配置速率限制。 + +### IPv4 + +为了确保功能可靠，你的防火墙必须允许： + +* ICMP 类型 3："目标不可达"，并有助于路径 MTU 发现 +* ICMP 类型 4："源抑制" + +如果你希望能够 ping 或被 ping，还应允许： + +* ICMP 类型 0："回显应答" +* ICMP 类型 8："回显请求" + +为了 traceroute 能够工作，还可以允许： + +* ICMP 类型 11："时间超限" + +### IPv6 + +IPv6 协议栈的所有部分非常依赖 ICMP，屏蔽它会导致难以调试的问题。[RFC 4890](https://www.rfc-editor.org/rfc/rfc4890) 专门为此而写，值得查看。 + +简单来说，你必须始终允许： + +* ICMP 类型 1："目标不可达" +* ICMP 类型 2："数据包过大" +* ICMP 类型 3，代码 0："时间超限" +* ICMP 类型 4，代码 1, 2："参数问题" + +对于 ping，你应该允许： + +* ICMP 类型 128："回显请求" +* ICMP 类型 129："回显应答" + +## 防火墙配置 + +在 Linux 上，通常使用 [iptables](https://en.wikipedia.org/wiki/Iptables) 或更现代、更快的 [nftables](https://en.wikipedia.org/wiki/Nftables) 作为后端进行防火墙配置。大多数发行版正在转向使用 nftables，许多防火墙前端可以配置为使用 nftables。你需要参考发行版的文档，但通常会有一个 `iptables` 或 `nftables` 服务，可以通过预定义的位置加载防火墙规则。 + +手动使用原始的 iptables 或 nftables 规则提供了最大的控制精度，但如果不熟悉这些系统，这样做可能会有挑战。为了帮助解决这个问题，存在许多配置前端可以使用。 + +在 Debian 和 Ubuntu 以及 openSUSE 系列的发行版中，通常使用 UFW。它是一个简单的防火墙前端，许多针对这些发行版的教程都会使用它。 + +对于 Red Hat/CentOS 系列的发行版，通常使用 firewalld。它是一个更高级的防火墙配置工具，也有桌面 GUI 和 [Cockpit 集成](https://cockpit-project.org/)。 + +尽管发行版有各自偏好，你可以在任何 Linux 发行版中使用 UFW、firewalld 或其他完全不同的工具。 + +* [Ubuntu Wiki](https://wiki.ubuntu.com/UncomplicatedFirewall?action=show&redirect=UbuntuFirewall) 关于 UFW 的介绍 +* [ArchWiki](https://wiki.archlinux.org/title/Uncomplicated_Firewall) 关于 UFW 的介绍 +* DigitalOcean 指南 [在 Ubuntu 22.04 上使用 UFW 建立防火墙](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-firewall-with-ufw-on-ubuntu-22-04) +* [firewalld](https://firewalld.org/) 项目主页及文档 +* [ArchWiki](https://wiki.archlinux.org/title/firewalld) 关于 firewalld 的介绍 +* [使用和配置 firewalld](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/configuring_firewalls_and_packet_filters/using-and-configuring-firewalld_firewall-packet-filters) 的 Red Hat 文档 +* Linode 指南 [如何使用 firewalld](https://www.linode.com/docs/guides/introduction-to-firewalld-on-centos/) + +## 暴力攻击防护 + +[fail2ban](https://www.fail2ban.org) 和 [SSHGuard](https://www.sshguard.net/) 可以配置以监控日志文件中暴力破解登录和其他恶意行为的尝试。它们可以配置为自动插入防火墙规则，以屏蔽恶意 IP 地址，屏蔽可以是暂时的，也可以是永久的。 + +SSHGuard 最初只为 SSH 设计，但现在支持多种服务。Fail2ban 往往支持任何可生成一致日志行的服务，而 SSHGuard 的签名方法可以捕获更复杂或隐蔽的攻击，因为它随着时间的推移计算攻击分数。 + +SSHGuard 和 fail2ban 都带有后端，可以直接针对 iptables 和 nftables，或与你选择的前端如 UFW 或 firewalld 在 Linux 上工作，在 \*BSD 系统上可以使用 pf。确保查看其文档以正确配置。 + +* [ArchWiki](https://wiki.archlinux.org/title/Fail2ban) 关于 fail2ban 的介绍 +* DigitalOcean 指南如何在 Ubuntu 上使用 [fail2ban 保护 SSH](https://www.digitalocean.com/community/tutorial_collections/how-to-protect-ssh-with-fail2ban) +* Linode 指南如何使用 [fail2ban 保护服务器](https://www.linode.com/docs/guides/using-fail2ban-to-secure-your-server-a-tutorial/) +* [ArchWiki](https://wiki.archlinux.org/title/sshguard) 关于 sshguard 的介绍 +* [FreeBSD 手册](https://man.freebsd.org/cgi/man.cgi?query=sshguard&sektion=8&manpath=FreeBSD+13.2-RELEASE+and+Ports) sshguard 的介绍 +* [SSHGuard 设置](https://manpages.ubuntu.com/manpages/lunar/en/man7/sshguard-setup.7.html) 的 Ubuntu 手册 + +对于 fail2ban，可以使用以下正则表达式，该正则表达式在身份验证失败时触发 fail2ban，而不是其他“未经授权”的错误（例如 API）： + +```regex +statusCode=401 path=/auth/sign_in clientIP= .* msg=\"Unauthorized: +``` + +## IP 屏蔽 + +GoToSocial 实现了速率限制，以保护你的实例不被单个主体占用所有处理能力。然而，如果你知道这不是合法流量，或者来自你不想与之联邦的实例，你可以屏蔽流量来源的 IP，以节省 GoToSocial 的处理能力。 + +### Linux + +屏蔽 IP 是通过 iptables 或 nftables 实现的。如果你使用 UFW 或 firewalld 等防火墙前端，请使用其功能来屏蔽 IP。 + +在 iptables 中，人们倾向于在 `filter` 表的 `INPUT` 链中为 IP 添加一个 `DROP` 规则。在 nftables 中，通常在一个具有 `ip` 或 `ip6` 地址族的链的表中完成。在这些情况下，内核已经对传入流量进行了大量不必要的处理，然后再通过 IP 匹配进行屏蔽。 + +使用 iptables 时，可以更有效地使用 `mangle` 表和 `PREROUTING` 链。你可以查看这篇博客文章，[了解它在 iptables 中的工作原理][iptblock]。对于 nftables，你可能会想要使用 [`netdev` family][nftnetdev] 进行屏蔽。 + +[iptblock]: https://javapipe.com/blog/iptables-ddos-protection/ +[nftnetdev]: https://wiki.nftables.org/wiki-nftables/index.php/Nftables_families#netdev + +#### iptables + +使用 `iptables` 屏蔽 IP 的示例： + +``` +iptables -t mangle -A PREROUTING -s 1.0.0.0/8 -j DROP +ip6tables -t mangle -A PREROUTING -s fc00::/7 -j DROP +``` + +当使用 iptables 时，添加许多规则会显著降低速度，包括在添加/删除规则时重新加载防火墙。由于你可能希望屏蔽许多 IP 地址，请使用 [ipset 模块][ipset] 并为集合添加单个屏蔽规则。 + +[ipset]: https://ipset.netfilter.org/ipset.man.html + +首先创建你的集合并添加一些 IP： + +``` +ipset create baddiesv4 hash:ip family inet +ipset create baddiesv6 hash:ip family inet6 + +ipset add baddiesv4 1.0.0.0/8 +ipset add baddiesv6 fc00::/7 +``` + +然后，更新你的 iptables 规则以针对该集合： + +``` +iptables -t mangle -A PREROUTING -m set --match-set baddiesv4 src -j DROP +ip6tables -t mangle -A PREROUTING -m set --match-set baddiesv6 src -j DROP +``` + +#### nftables + +对于 nftables，你可以使用如下配置： + +``` +table netdev filter { + chain ingress { + set baddiesv4 { + type ipv4_addr + flags interval + elements = { \ + 1.0.0.0/8, \ + 2.2.2.2/32 \ + } + } + set baddiesv6 { + type ipv6_addr + flags interval + elements = { \ + 2620:4f:8000::/48, \ + fc00::/7 \ + } + } + + type filter hook ingress device priority -500; + ip saddr @baddiesv4 drop + ip6 saddr @baddiesv6 drop + } +} +``` + +### BSDs + +使用 pf 时，你可以创建一个通常命名为 `` 的持久化表，将需要屏蔽的 IP 地址添加到该表中。表格还可以从其他文件读取，因此可以将 IP 列表保存在主 `pf.conf` 之外。 + +有关如何执行此操作的示例，可以在 [pf 手册][manpf] 中找到。 + +[manpf]: https://man.openbsd.org/pf.conf#TABLES diff --git a/docs/locales/zh/advanced/security/index.md b/docs/locales/zh/advanced/security/index.md new file mode 100644 index 000000000..bdd80b912 --- /dev/null +++ b/docs/locales/zh/advanced/security/index.md @@ -0,0 +1,11 @@ +# 安全加固措施 + +这些指南涵盖如何提高你的 GoToSocial 部署的安全状况。它们不涉及调整 GoToSocial 的设置，而是指出一些你可以做的额外措施，以更好地保护你的实例。 + +!!! note + 这些指南中的任何内容旨在增强你的 GoToSocial 部署的安全性；它们不能替代良好的安全实践，比如保持你的系统定期得到修补和更新。 + +## 指南 + +* [对 GoToSocial 可执行文件进行沙盒处理](sandboxing.md) +* [配置防火墙](firewall.md) diff --git a/docs/locales/zh/advanced/security/sandboxing.md b/docs/locales/zh/advanced/security/sandboxing.md new file mode 100644 index 000000000..ac4b88723 --- /dev/null +++ b/docs/locales/zh/advanced/security/sandboxing.md @@ -0,0 +1,63 @@ +# 对 GoToSocial 可执行文件进行沙盒处理 + +通过对 GoToSocial 二进制文件进行沙盒化，可以控制 GoToSocial 能访问系统的哪些部分，并限制其读写权限。这有助于确保即使在 GoToSocial 出现安全问题时，攻击者也很难提升权限，进而在系统上立足。 + +不同发行版有其偏好的沙盒机制： + +* **AppArmor** 适用于 Debian 或 Ubuntu 系列及 OpenSuSE，包括在 Docker 中的运行时 +* **SELinux** 适用于 Red Hat/Fedora/CentOS 系列或 Gentoo + +## AppArmor + +我们提供了一个 GoToSocial 的 AppArmor 示例策略，你可以按以下步骤获取并安装： + +```sh +$ curl -LO 'https://github.com/superseriousbusiness/gotosocial/raw/main/example/apparmor/gotosocial' +$ sudo install -o root -g root gotosocial /etc/apparmor.d/gotosocial +$ sudo apparmor_parser -Kr /etc/apparmor.d/gotosocial +``` + +安装策略后，你需要配置系统以使用该策略来限制 GoToSocial 的权限。 + +你可以这样禁用该策略： + +```sh +$ sudo apparmor_parser -R /etc/apparmor.d/gotosocial +$ sudo rm -vi /etc/apparmor.d/gotosocial +``` +别忘了回滚你所做的任何加载 AppArmor 策略的配置更改。 + +### systemd + +在 systemd 服务中添加以下内容，或创建一条覆盖规则： + +```ini +[Service] +... +AppArmorProfile=gotosocial +``` + +重载 systemd 并重新启动 GoToSocial： + +```sh +$ systemctl daemon-reload +$ systemctl restart gotosocial +``` + +### 容器 + +使用我们的示例 Compose 文件时，可以通过以下方式告知其加载 AppArmor 策略： + +```yaml +services: + gotosocial: + ... + security_opt: + - apparmor=gotosocial +``` + +在使用 `docker run` 或 `podman run` 启动容器时，需要使用 `--security-opt="apparmor=gotosocial"` 命令行标志。 + +## SELinux + +SELinux 策略由社区在 GitHub 上的 [`lzap/gotosocial-selinux`](https://github.com/lzap/gotosocial-selinux) 仓库维护。请务必阅读其文档，在使用前查看策略，并使用其问题跟踪器获取有关 SELinux 策略的支持请求。 diff --git a/docs/locales/zh/advanced/sqlite-networked-storage.md b/docs/locales/zh/advanced/sqlite-networked-storage.md new file mode 100644 index 000000000..a319aa20a --- /dev/null +++ b/docs/locales/zh/advanced/sqlite-networked-storage.md @@ -0,0 +1,35 @@ +# 网络存储上的 SQLite + +SQLite 的运行模式假定数据库和使用它的进程或应用程序位于同一主机上。在运行 WAL 模式（GoToSocial 的默认模式）时，它依赖于进程之间的共享内存来确保数据库完整性。 + +!!! quote + 所有使用数据库的进程必须在同一台主机计算机上；WAL 不能在网络文件系统上工作。这是因为 WAL 需要所有进程共享少量内存，而在不同主机上的进程显然不能相互共享内存。 + + — SQLite.org [写前日志](https://www.sqlite.org/wal.html) + +这也意味着访问数据库的任何其他进程需要在相同的命名空间或容器上下文中运行。 + +理论上，可以通过 Samba、NFS、iSCSI 或其他形式的网络访问文件系统运行 SQLite。但无论是否使用写前日志模式，SQLite 维护者都不推荐或不支持这样做。这样做会使你的数据库面临损坏的风险。长期以来，网络存储在其锁定原语中存在同步问题，实现的保证也比本地存储更弱。 + +你的云供应商的外部卷，如 Hetzner 云存储卷、AWS EBS、GCP 持久磁盘等，也可能导致问题，并增加不确定的延迟。这往往会严重降低 SQLite 的性能。 + +如果你打算通过网络访问数据库，最好使用具有客户端-服务器架构的数据库。GoToSocial 支持这种用例的 Postgres。 + +如果想要在耐久的长期存储上保留 SQLite 数据库的副本，请参阅 [SQLite 流式副本](replicating-sqlite.md)。请记住，无论是还是副本使用网络文件系统都不能替代[备份](../admin/backup_and_restore.md)。 + +## 设置 + +!!! danger "数据库损坏" + 我们不支持在网络文件系统上使用 SQLite 运行 GoToSocial，如果你因此损坏了数据库，我们将无法帮助你。 + +如果你确实想冒这个风险，你需要调整 SQLite 的 [synchronous][sqlite-sync] 模式和 [journal][sqlite-journal] 模式以适应文件系统的限制。 + +[sqlite-sync]: https://www.sqlite.org/pragma.html#pragma_synchronous +[sqlite-journal]: https://www.sqlite.org/pragma.html#pragma_journal_mode + +你需要更新以下设置： + +* `db-sqlite-journal-mode` +* `db-sqlite-synchronous` + +我们不提供任何建议，因为这将根据你使用的解决方案而有所不同。请参阅 [此问题](https://github.com/superseriousbusiness/gotosocial/issues/3360#issuecomment-2380332027)以了解你可能设置的值。 diff --git a/docs/locales/zh/advanced/tracing.md b/docs/locales/zh/advanced/tracing.md new file mode 100644 index 000000000..82b700d94 --- /dev/null +++ b/docs/locales/zh/advanced/tracing.md @@ -0,0 +1,44 @@ +# 追踪 + +GoToSocial 内置了基于 [OpenTelemetry][otel] 的追踪功能。虽然并没有贯穿每个函数，但我们的 HTTP 处理程序和数据库库会创建跨度。在 [可观测性配置参考][obs] 中解释了如何配置追踪。 + +为了接收这些追踪，你需要一些工具来摄取并可视化它们。有很多选项，包括自托管和商业选项。 + +我们提供了一个示例，说明如何使用 [Grafana Tempo][tempo] 来抓取数据跨度，并使用 [Grafana][grafana] 来检索它们。请注意，我们提供的配置不适合生产环境。可以安全地用于本地开发，并可为设置你自己的追踪基础设施提供一个良好的起点。 + +你需要获取 [`example/tracing`][ext] 中的文件。获取这些文件后，你可以运行 `docker-compose up -d` 来启动 Tempo 和 Grafana。在两个服务运行后，可以将以下内容添加到 GoToSocial 配置中，并重新启动你的实例： + +```yaml +tracing-enabled: true +tracing-transport: "grpc" +tracing-endpoint: "localhost:4317" +tracing-insecure-transport: true +``` + +[otel]: https://opentelemetry.io/ +[obs]: ../configuration/observability.md +[tempo]: https://grafana.com/oss/tempo/ +[grafana]: https://grafana.com/oss/grafana/ +[ext]: https://github.com/superseriousbusiness/gotosocial/tree/main/example/tracing + +## 查询和可视化追踪 + +在对你的实例执行几个查询后，你可以在 Grafana 中找到它们。你可以使用 Explore 选项卡并选择 Tempo 作为数据源。由于我们的 Grafana 示例配置启用了 [TraceQL][traceql]，Explore 选项卡将默认选择 TraceQL 查询类型。你可以改为选择“搜索”，并在“GoToSocial”服务名称下找到所有 GoToSocial 发出的追踪。 + +使用 TraceQL 时，一个简单的查询来查找与 `/api/v1/instance` 请求相关的所有追踪可以这样写： + +``` +{.http.route = "/api/v1/instance"} +``` + +如果你想查看所有 GoToSocial 追踪，可以运行： + +``` +{.service.name = "GoToSocial"} +``` + +选择一个追踪后，将打开第二个面板，显示对应数据跨度的可视化视图。你可以从那里深入浏览，通过点击每个子跨度查看其执行的操作。 + +![Grafana 显示 /api/v1/instance 端点的追踪](../../../assets/tracing.png) + +[traceql]: https://grafana.com/docs/tempo/latest/traceql/ diff --git a/docs/locales/zh/api/authentication.md b/docs/locales/zh/api/authentication.md new file mode 100644 index 000000000..156c11f31 --- /dev/null +++ b/docs/locales/zh/api/authentication.md @@ -0,0 +1,149 @@ +# 使用 API 进行身份验证 + +使用客户端 API 需要进行身份验证。本页记录了如何获取身份验证令牌的通用流程，并提供了使用 `curl` 在命令行界面进行操作的示例。 + +## 创建新应用 + +我们需要注册一个新应用，以便请求 OAuth 令牌。这可以通过向 `/api/v1/apps` 端点发送 `POST` 请求来完成。注意将下面命令中的 `your_app_name` 替换为你想使用的应用名称： + +```bash +curl \ + -X POST \ + -H 'Content-Type:application/json' \ + -d '{ + "client_name": "your_app_name", + "redirect_uris": "urn:ietf:wg:oauth:2.0:oob", + "scopes": "read" + }' \ + 'https://example.org/api/v1/apps' +``` + +字符串 `urn:ietf:wg:oauth:2.0:oob` 表示一种称为带外身份验证的技术，这是一种用于多因素身份验证的技术，旨在减少恶意行为者干扰身份验证过程的途径。在此情况下，它允许我们查看并手动复制生成的令牌以便继续使用。 + +注意，`scopes` 可以是以下任意空格分隔的组合： + +- `read` +- `write` +- `admin` + +!!! warning + GoToSocial 目前不支持范围授权令牌，因此在此过程中获得的任何令牌都可以代表你执行所有操作，包括如果你的账户具有管理员权限时的管理员操作。然而，始终以最低权限授予你的应用是一个好习惯。例如，如果你的应用不会发布贴文，请使用 scope=read。 + + 本着这种精神，上述示例使用了`read`，这意味着当未来支持范围令牌时，应用将仅限于执行`read`操作。 + + 你可以在[此处](https://github.com/superseriousbusiness/gotosocial/issues/2232)阅读更多关于计划中 OAuth 安全功能的信息。 + +成功调用会返回一个带有 `client_id` 和 `client_secret` 的响应，我们将在后续流程中需要使用这些信息。它看起来像这样： + +```json +{ + "id": "01J1CYJ4QRNFZD6WHQMZV7248G", + "name": "your_app_name", + "redirect_uri": "urn:ietf:wg:oauth:2.0:oob", + "client_id": "YOUR_CLIENT_ID", + "client_secret": "YOUR_CLIENT_SECRET" +} +``` + +!!! tip + 确保将 `client_id` 和 `client_secret` 的值保存到某个位置，以便在需要时参考。 + +## 授权你的应用代表你操作 + +我们已经在 GoToSocial 注册了一个新应用，但它尚未与你的账户连接。现在，我们需要告知 GoToSocial 这个新应用将代表你操作。为此，我们需要通过浏览器进行实例认证，以启动登录和权限授予过程。 + +创建一个带查询字符串的 URL，如下所示，将 `YOUR_CLIENT_ID` 替换为你在上一步收到的 `client_id`，然后将 URL 粘贴到浏览器中： + +```text +https://example.org/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&scope=read +``` + +!!! tip + 如果你在注册应用时使用了不同的范围，在上面的 URL 中将 `scope=read` 替换为你注册时使用的加号分隔的范围列表。例如，如果你注册你的应用时使用了 `scopes` 值 `read write`，那么你应该将上面的 `scope=read` 改为 `scope=read+write`。 + +将 URL 粘贴到浏览器后，你会被引导到实例的登录表单，提示你输入邮箱地址和密码以将应用连接到你的账户。 + +提交凭据后，你会到达一个页面，上面写着类似这样的内容： + +``` +嗨嗨，`your_username`! + +应用 `your_app_name` 申请以你的名义执行操作，申请的权限范围是 *`read`*. +如果选择允许，应用将跳转到： urn:ietf:wg:oauth:2.0:oob 继续操作 +``` + +点击 `允许`，你将到达这样一个页面： + +```text +Here's your out-of-band token with scope "read", use it wisely: +YOUR_AUTHORIZATION_TOKEN +``` + +复制带外授权令牌到某个地方，因为你将在下一步中需要它。 + +## 获取访问令牌 + +下一步是用刚刚收到的带外授权令牌交换一个可重用的访问令牌，该令牌可以在以后所有的 API 请求中发送。 + +你可以通过另一个 `POST` 请求来完成这项操作，如下所示： + +```bash +curl \ + -X POST \ + -H 'Content-Type: application/json' \ + -d '{ + "redirect_uri": "urn:ietf:wg:oauth:2.0:oob", + "client_id": "YOUR_CLIENT_ID", + "client_secret": "YOUR_CLIENT_SECRET", + "grant_type": "authorization_code", + "code": "YOUR_AUTHORIZATION_TOKEN" + }' \ + 'https://example.org/oauth/token' +``` + +确保替换： + +- `YOUR_CLIENT_ID` 为第一步中收到的客户端 ID。 +- `YOUR_CLIENT_SECRET` 为第一步中收到的客户端密钥。 +- `YOUR_AUTHORIZATION_TOKEN` 为在第二步中收到的带外授权令牌。 + +你会收到一个包含访问令牌的响应，看起来像这样： + +```json +{ + "access_token": "YOUR_ACCESS_TOKEN", + "created_at": 1719577950, + "scope": "read", + "token_type": "Bearer" +} +``` + +将你的访问令牌复制并安全保存。 + +## 验证 + +为了确保一切正常，尝试查询 `/api/v1/verify_credentials` 端点，在请求头中添加你的访问令牌作为 `Authorization: Bearer YOUR_ACCESS_TOKEN`。 + +请参考以下示例： + +```bash +curl \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ + 'https://example.org/api/v1/accounts/verify_credentials' +``` + +如果一切顺利，你应该会得到用户资料的 JSON 响应。 + +## 最后说明 + +现在你拥有了访问令牌，可以在每次 API 请求中重复使用该令牌进行授权。你不需要每次都执行整个令牌交换过程！ + +例如，你可以使用相同的访问令牌向 API 发送另一个 `GET` 请求以获取通知，如下所示： + +```bash +curl \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ + 'https://example.org/api/v1/notifications' +``` diff --git a/docs/locales/zh/api/ratelimiting.md b/docs/locales/zh/api/ratelimiting.md new file mode 100644 index 000000000..a9533fa01 --- /dev/null +++ b/docs/locales/zh/api/ratelimiting.md @@ -0,0 +1,41 @@ +# 请求速率限制 + +为减轻对你的实例的滥用和抓取，系统使用了基于 IP 的 HTTP 速率限制。 + +不同的端点组有单独的速率限制规则。换句话说，一个部分的 API 被速率限制了，并不意味着其他部分也会被限制。以下列表中的每个项目都有单独的速率限制规则： + +- `/users/*` 和 `/emoji/*` - ActivityPub (s2s) 端点。 +- `/auth/*` 和 `/oauth/*` - 登录和 OAUTH 令牌请求。 +- `/fileserver/*` - 媒体附件、表情符号等。 +- `/nodeinfo/*` - NodeInfo 端点。 +- `/.well-known/*` - webfinger 和 nodeinfo 请求。 + +默认情况下，每个速率限制规则允许在 5 分钟内最多进行 300 次请求：每个客户端 IP 地址每秒 1 次请求。 + +每个响应将包含速率限制的当前状态，具体表现为以下头信息： + +- `X-Ratelimit-Limit`: 每个时间段允许的最大请求数。 +- `X-Ratelimit-Remaining`: 在剩余时间内仍然可以进行的请求数量。 +- `X-Ratelimit-Reset`: 表示速率限制何时重置的 ISO8601 时间戳。 + +如果超过速率限制，将返回 [HTTP 429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) 错误给请求者。 + +## 速率限制常见问题 + +### 我总是超出速率限制！为什么？ + +如果你发现自己的速率限制在正常使用时经常被超出（对于你自己和其他请求者也是如此），这可能是因为 GoToSocial 无法通过 IP 地址区分客户端。你可以通过查看实例的日志来调查这个问题。如果（几乎）所有记录的 IP 地址似乎都是相同的 IP 地址（类似于 `172.x.x.x`），那么速率限制将导致问题。 + +这种情况通常发生在你的服务器运行在 NAT（端口转发）中，或者在没有正确配置的 HTTP 代理之后，导致你的实例将所有传入 IP 地址视为相同的地址：即你的反向代理或网关的 IP 地址。这意味着所有传入请求*共享同一个速率限制*，而不是按 IP 正确分开。 + +如果你正在使用 HTTP 代理，那么很可能你的 `trusted-proxies` 未正确配置。如果是这种情况，尝试将反向代理的 IP 地址添加到 `trusted-proxies` 列表中，并重启你的实例。 + +如果没有使用 HTTP 代理，那么很可能是由 NAT 引起的。在这种情况下，你应该完全禁用速率限制。 + +### 我可以配置速率限制吗？可以关闭吗？ + +可以！在配置中设置 `advanced-rate-limit-requests: 0`。 + +### 我可以将一个或多个 IP 地址排除在速率限制之外，而保持其他的限制吗？ + +可以！在配置中设置 `advanced-rate-limit-exceptions`。 diff --git a/docs/locales/zh/api/swagger.md b/docs/locales/zh/api/swagger.md new file mode 100644 index 000000000..ad069d4d7 --- /dev/null +++ b/docs/locales/zh/api/swagger.md @@ -0,0 +1,21 @@ +# 路由和方法 + +GoToSocial 使用 [go-swagger](https://github.com/go-swagger/go-swagger) 从代码注释生成一个 V2 [OpenAPI 规范](https://swagger.io/specification/v2/)文档。 + +生成的 API 文档如下所示。请注意，本文档仅供参考。你将无法使用以下小部件内置的授权功能实际连接到实例或进行 API 调用。相反，你应该使用像 curl、Postman 等工具。 + +大多数 GoToSocial API 端点需要用户级别的 OAuth 令牌。有关如何使用 OAuth 令牌进行 API 认证的指南，请参阅[认证文档](./authentication.md)。 + +!!! tip + 如果你想更多地使用该规范，还可以直接查看 [swagger.yaml](./swagger.yaml)，然后将其粘贴到 [Swagger Editor](https://editor.swagger.io/) 等工具中。这样你可以尝试自动生成不同语言的 GoToSocial API 客户端（不支持，但可以尝试），或者将文档转换为 JSON 或 OpenAPI v3 规范等。更多信息请参见[这里](https://swagger.io/tools/open-source/getting-started/)。 + +!!! info "注意事项：上传文件" + 当使用涉及提交表单上传文件的 API 端点时（例如，媒体附件端点或表情符号上传端点等），请注意，在表单字段中 `filename` 是必需的，这是由于 GoToSocial 用于解析表单的依赖关系以及 Go 的某些特性导致的。 + + 有关更多背景信息，请参见以下问题： + + - [#1958](https://github.com/superseriousbusiness/gotosocial/issues/1958) + - [#1944](https://github.com/superseriousbusiness/gotosocial/issues/1944) + - [#2641](https://github.com/superseriousbusiness/gotosocial/issues/2641) + + diff --git a/docs/locales/zh/api/swagger.yaml b/docs/locales/zh/api/swagger.yaml new file mode 100644 index 000000000..7751c47e3 --- /dev/null +++ b/docs/locales/zh/api/swagger.yaml @@ -0,0 +1,11393 @@ +basePath: / +definitions: + FilterAction: + title: FilterAction + description: FilterAction 是针对与过滤规则匹配的贴文所执行的操作。 + type: string + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + InstanceConfigurationEmojis: + properties: + emoji_size_limit: + description: 最大自定义表情文件大小（字节）。 + example: 51200 + format: int64 + type: integer + x-go-name: EmojiSizeLimit + title: InstanceConfigurationEmojis + description: InstanceConfigurationEmojis 结构体包含有关自定义表情的配置信息。 + type: object + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + Link: + description: Link 代表针对查询请求返回的链接组中的一个“链接”。详见 https://webfinger.net/ 和 https://www.rfc-editor.org/rfc/rfc6415.html#section-3.1 + properties: + href: + type: string + x-go-name: Href + rel: + type: string + x-go-name: Rel + template: + type: string + x-go-name: Template + type: + type: string + x-go-name: Type + title: Link + type: object + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + Mention: + properties: + acct: + description: |- + 通过webfinger发现的帐户URI。 + 对于本站用户，等于"用户名"，对于外站用户，等于"用户名@域名"。 + example: some_user@example.org + type: string + x-go-name: Acct + id: + description: 被提及的帐户的ID。 + example: 01FBYJHQWQZAVWFRK9PDYTKGMB + type: string + x-go-name: ID + url: + description: 被提及的账户的Web资料页。 + example: https://example.org/@some_user + type: string + x-go-name: URL + username: + description: 被提及账户的用户名。 + example: some_user + type: string + x-go-name: Username + title: Mention + description: Mention 表示对另一个账户的一次提及。 + type: object + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + NodeInfoServices: + properties: + inbound: + items: + type: string + type: array + x-go-name: Inbound + outbound: + items: + type: string + type: array + x-go-name: Outbound + title: NodeInfoServices + description: 表示此节点对入站和出站连接提供的服务。 + type: object + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + NodeInfoSoftware: + properties: + name: + example: gotosocial + type: string + x-go-name: Name + version: + example: 0.1.2 1234567 + type: string + x-go-name: Version + title: NodeInfoSoftware + description: NodeInfoSoftware 表示此节点软件的名称和版本号。 + type: object + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + NodeInfoUsage: + properties: + localPosts: + format: int64 + type: integer + x-go-name: LocalPosts + users: + $ref: '#/definitions/NodeInfoUsers' + title: NodeInfoUsage + description: 表示有关此服务器的使用信息，例如用户数量。 + type: object + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + NodeInfoUsers: + properties: + total: + format: int64 + type: integer + x-go-name: Total + title: NodeInfoUsers + description: NodeInfoUsers 表示有关服务器上用户的聚合信息。 + type: object + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + Source: + description: Source 表示用户自己账户的内容展示或发布偏好。在验证和更新凭据时，作为 Account 的一个属性返回的附加实体。 + properties: + also_known_as_uris: + description: |- + 要设置此值，请调用 `/api/v1/accounts/alias`。 + + 若为空或为设置，将从json中省略。 + items: + type: string + type: array + x-go-name: AlsoKnownAsURIs + fields: + description: 此账户的元数据。 + items: + $ref: '#/definitions/field' + type: array + x-go-name: Fields + follow_requests_count: + description: 待处理的关注请求数量。 + format: int64 + type: integer + x-go-name: FollowRequestsCount + language: + description: 新贴文的默认发布语言。 + type: string + x-go-name: Language + note: + description: 个人资料简介。 + type: string + x-go-name: Note + privacy: + description: |- + 新贴文的默认可见性。 + public = 公开贴文 + unlisted = 未列出/不公开/悄悄公开贴文 + private = 仅粉丝可见的贴文 + direct = 私信贴文 + type: string + x-go-name: Privacy + sensitive: + description: 是否将新贴文默认标记为敏感。 + type: boolean + x-go-name: Sensitive + status_content_type: + description: 新贴文的默认内容格式。 + type: string + x-go-name: StatusContentType + web_visibility: + description: |- + 通过网页端API显示的该账户下贴文的最低可见性。 + "public" = 默认值，此时仅显示公开贴文。 + "unlisted" = 显示公开贴文 *和* 未列出的贴文。 + "none" = 不在网页端显示任何贴文，即使贴文为公开贴文。 + type: string + x-go-name: WebVisibility + title: Source + type: object + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + TimelineMarker: + properties: + last_read_id: + description: 最近查看的内容实体的ID。 + type: string + x-go-name: LastReadID + updated_at: + description: 设定标记时的时间戳 (ISO 8601 Datetime)。 + type: string + x-go-name: UpdatedAt + version: + description: 用于锁定以防止写冲突。 + format: int64 + type: integer + x-go-name: Version + title: TimelineMarker + description: TimelineMarker 包含有关用户在特定时间线上的阅读进度的信息。 + type: object + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + account: + description: Account 是一个 Fediverse 账户的抽象模型。被抽象的账户可以是本站账户，也可以是外站账户。 + properties: + acct: + description: |- + 通过 WebFinger 发现的帐户 URI。 + 对于本站用户，等于“用户名”，对于外站用户，等于“用户名@域名”。 + example: some_user@example.org + type: string + x-go-name: Acct + avatar: + description: 账户头像的网络地址。 + example: https://example.org/media/some_user/avatar/original/avatar.jpeg + type: string + x-go-name: Avatar + avatar_description: + description: 该账户头像的文字描述，用于提供 Alt 文本。 + example: 一只微笑的树懒的可爱图画。 + type: string + x-go-name: AvatarDescription + avatar_media_id: + description: |- + 此账户的头像对应的媒体附件的数据库 ID。 + 如果此账户没有上传头像（即默认头像），则省略。 + example: 01JAJ3XCD66K3T99JZESCR137W + type: string + x-go-name: AvatarMediaID + avatar_static: + description: |- + 该账户头像的静态版本的网络地址。 + 仅在账户的主头像是视频或 gif 时才起实际作用。 + example: https://example.org/media/some_user/avatar/static/avatar.png + type: string + x-go-name: AvatarStatic + bot: + description: 表示账户是一个机器人。 + type: boolean + x-go-name: Bot + created_at: + description: 账户创建时间 (ISO 8601 Datetime)。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: CreatedAt + custom_css: + description: 渲染该账户的资料页或贴文页时要包含的自定义 CSS。 + type: string + x-go-name: CustomCSS + discoverable: + description: 表示账户已选择加入内容发现功能。 + type: boolean + x-go-name: Discoverable + display_name: + description: 该账户的昵称 + example: 树懒一号 + type: string + x-go-name: DisplayName + emojis: + description: |- + 该账户的简介或昵称中使用的自定义表情组成的数组。 + 如果账户被屏蔽，则始终为空。 + items: + $ref: '#/definitions/emoji' + type: array + x-go-name: Emojis + enable_rss: + description: |- + 账户已启用 RSS 订阅。 + 如果为 false，则省略键/值。 + type: boolean + x-go-name: EnableRSS + fields: + description: |- + 账户设置的附加元数据。 + 如果账户被屏蔽，则始终为空。 + items: + $ref: '#/definitions/field' + type: array + x-go-name: Fields + followers_count: + description: 该账户的粉丝数量（数据来源于本站）。 + format: int64 + type: integer + x-go-name: FollowersCount + following_count: + description: 该账户关注的账户数量（数据来源于本站）。 + format: int64 + type: integer + x-go-name: FollowingCount + header: + description: 该账户的资料卡横幅背景图片的网络地址。 + example: https://example.org/media/some_user/header/original/header.jpeg + type: string + x-go-name: Header + header_description: + description: 该账户的资料卡横幅背景图片的文字描述，用于提供 Alt 文本。 + example: 一只树懒和一只小象在一起的可爱图画。 + type: string + x-go-name: HeaderDescription + header_media_id: + description: |- + 此账户的资料卡横幅背景图片对应的媒体附件的数据库 ID。 + 如果此账户没有上传资料卡横幅背景图（即使用默认横幅背景），则省略。 + example: 01JAJ3XCD66K3T99JZESCR137W + type: string + x-go-name: HeaderMediaID + header_static: + description: |- + 该账户的资料卡横幅背景图片的静态版本的网络地址。 + 仅在账户的资料卡横幅背景图片是视频或 gif 时才起实际作用。 + example: https://example.org/media/some_user/header/static/header.png + type: string + x-go-name: HeaderStatic + hide_collections: + description: |- + 账户选择隐藏其粉丝/关注数据。 + 如果为 false，则省略键/值。 + type: boolean + x-go-name: HideCollections + id: + description: 账户的 ID。 + example: 01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: ID + last_status_at: + description: 账户最近一条贴文的发布时间 (ISO 8601 Date)。 + example: "2021-07-30" + type: string + x-go-name: LastStatusAt + locked: + description: 账户选择手动批准关注请求。 + type: boolean + x-go-name: Locked + moved: + $ref: '#/definitions/account' + note: + description: 账户的简介。 + type: string + x-go-name: Note + role: + $ref: '#/definitions/accountRole' + roles: + description: |- + Roles 列出了账户在本站上的公开身份组。 + 与 Role 不同，Roles 始终可用，但从不包含权限细节。 + 对于外站账户，键/值被省略。 + items: + $ref: '#/definitions/accountDisplayRole' + type: array + x-go-name: Roles + source: + $ref: '#/definitions/Source' + statuses_count: + description: Number of statuses posted by this account, according to our instance. 账户发布的贴文数量 (数据来源于本站)。 + format: int64 + type: integer + x-go-name: StatusesCount + suspended: + description: 账户已被本站封禁。 + type: boolean + x-go-name: Suspended + theme: + description: 用户选择的 CSS 主题文件名，用于在渲染此账户的资料页或贴文页时包含。 + type: string + x-go-name: Theme + url: + description: 账户资料页的 Web 地址。 + example: https://example.org/@some_user + type: string + x-go-name: URL + username: + description: 账户的用户名，不包括域名。 + example: some_user + type: string + x-go-name: Username + title: Account + type: object + x-go-name: Account + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + accountDisplayRole: + description: AccountDisplayRole 是账户的公开、可显示身份组的抽象模型。它是 AccountRole 的一个子集。 + properties: + color: + description: |- + Color 是一个带有前导 `#` 的 6 位 CSS 风格十六进制颜色码，如果此身份组没有设置颜色，则为空字符串。 + GotoSocial 不使用身份组颜色，因此我们将其留空。 + type: string + x-go-name: Color + id: + description: |- + 身份组的 ID。 + GotoSocial 不使用该属性，但我们将其设置为身份组名称，以防客户端期望唯一 ID。 + type: string + x-go-name: ID + name: + description: 身份组的名称。 + type: string + x-go-name: Name + title: AccountDisplayRole + type: object + x-go-name: AccountDisplayRole + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + accountExportStats: + description: |- + AccountExportStats 专门用于在 /api/v1/exports/stats 端点上通知有关导出大小的账户统计信息。 + properties: + blocks_count: + description: 被此账户屏蔽的账户数量。 + example: 15 + format: int64 + type: integer + x-go-name: BlocksCount + followers_count: + description: 此账户的粉丝数量。 + example: 50 + format: int64 + type: integer + x-go-name: FollowersCount + following_count: + description: 此账户关注的账户数量。 + example: 50 + format: int64 + type: integer + x-go-name: FollowingCount + lists_count: + description: 此账户创建的列表数量。 + example: 10 + format: int64 + type: integer + x-go-name: ListsCount + media_storage: + description: 'TODO: 此账户使用的媒体存储空间大小的字符串表示。' + example: 500MB + type: string + x-go-name: MediaStorage + mutes_count: + description: 此账户静音/隐藏的账户数量。 + example: 11 + format: int64 + type: integer + x-go-name: MutesCount + statuses_count: + description: 此账户发布的贴文数量。 + example: 81986 + format: int64 + type: integer + x-go-name: StatusesCount + type: object + x-go-name: AccountExportStats + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + accountRelationship: + properties: + blocked_by: + description: 你被此账户屏蔽。 + type: boolean + x-go-name: BlockedBy + blocking: + description: 你屏蔽了此账户。 + type: boolean + x-go-name: Blocking + domain_blocking: + description: 你屏蔽了此账户所在的实例。 + type: boolean + x-go-name: DomainBlocking + endorsed: + description: 你在你的资料页上展示了此账户。 + type: boolean + x-go-name: Endorsed + followed_by: + description: 此账户关注了你。 + type: boolean + x-go-name: FollowedBy + following: + description: 你关注了此账户。 + type: boolean + x-go-name: Following + id: + description: 账户 ID。 + example: 01FBW9XGEP7G6K88VY4S9MPE1R + type: string + x-go-name: ID + muting: + description: 你静音/隐藏了此账户。 + type: boolean + x-go-name: Muting + muting_notifications: + description: 你静音/隐藏了此账户的通知。 + type: boolean + x-go-name: MutingNotifications + note: + description: 你对此账户的备注。 + type: string + x-go-name: Note + notifying: + description: 你在此账户发布贴文时收到通知。 + type: boolean + x-go-name: Notifying + requested: + description: 你向此账户发送了关注请求，请求正在等待对方处理。 + type: boolean + x-go-name: Requested + requested_by: + description: 此账户请求关注你，请求正在等待你处理。 + type: boolean + x-go-name: RequestedBy + showing_reblogs: + description: 你选择在主页时间线上看到此账户转发的贴文。 + type: boolean + x-go-name: ShowingReblogs + title: Relationship + description: Relationship 表示账户之间的关系。 + type: object + x-go-name: Relationship + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + accountRole: + properties: + color: + description: |- + Color 是一个带有 `#` 前缀的 6 位 CSS 风格十六进制颜色码，如果此身份组没有设置颜色，则为空字符串。 + GotoSocial 不使用身份组颜色，因此我们将其留空。 + type: string + x-go-name: Color + highlighted: + description: |- + Highlighted 表示该身份组是否在用户资料页上公开显示。 + 对于 GotoSocial 内置的管理员和站务身份组，此值始终为 true，否则为 false。 + type: boolean + x-go-name: Highlighted + id: + description: |- + 该身份组的 ID。 + GotoSocial 不使用该属性，但我们将其设置为身份组名称，以防客户端期望唯一 ID。 + type: string + x-go-name: ID + name: + description: 身份组的名称。 + type: string + x-go-name: Name + permissions: + description: Permissions 是一个按位序列化的数字字符串，指示用户可以执行哪些管理员/站务操作。 + type: string + x-go-name: Permissions + title: AccountRole + description: AccountRole 是账户的身份组的抽象模型。 + type: object + x-go-name: AccountRole + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + adminAccountInfo: + properties: + account: + $ref: '#/definitions/account' + approved: + description: 账户是否已被批准。 + type: boolean + x-go-name: Approved + confirmed: + description: 账户是否已验证其电子邮件地址。 + type: boolean + x-go-name: Confirmed + created_at: + description: 账户首次被发现的时间 (ISO 8601 Datetime)。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: CreatedAt + created_by_application_id: + description: 创建此账户的应用程序的 ID。 + type: string + x-go-name: CreatedByApplicationID + disabled: + description: 账户目前是否已被停用。 + type: boolean + x-go-name: Disabled + domain: + description: |- + 账户所在实例的域名。 + 对于本站账户，为 null。 + example: example.org + type: string + x-go-name: Domain + email: + description: |- + 与账户关联的电子邮件地址。 + 对于外站账户或没有已知电子邮件地址的账户，为空字符串。 + example: someone@somewhere.com + type: string + x-go-name: Email + id: + description: 该账户在数据库中的 ID。 + example: 01GQ4PHNT622DQ9X95XQX4KKNR + type: string + x-go-name: ID + invite_request: + description: |- + 账户填写的注册理由。 + 如果未提供理由或为外站账户，则为 null。 + example: 快给爷通过a!! + type: string + x-go-name: InviteRequest + invited_by_account_id: + description: 邀请此用户的账户的 ID。 + type: string + x-go-name: InvitedByAccountID + ip: + description: |- + 此账户上次登录的 IP 地址。 + 如果未知，则为 null。 + example: 192.0.2.1 + type: string + x-go-name: IP + ips: + description: |- + 与此账户关联的所有已知 IP 地址。 + 未实现（将始终为空数组）。 + example: [] + items: {} + type: array + x-go-name: IPs + locale: + description: The locale of the account. (ISO 639 Part 1 two-letter language code) 账户的语言偏好。 (ISO 639 Part 1 两字母语言代码) + example: zh + type: string + x-go-name: Locale + role: + $ref: '#/definitions/accountRole' + silenced: + description: 此账户是否被静音/隐藏。 + type: boolean + x-go-name: Silenced + suspended: + description: 账户目前是否已被封禁。 + type: boolean + x-go-name: Suspended + username: + description: 账户的用户名。 + example: dril + type: string + x-go-name: Username + title: AdminAccountInfo + description: AdminAccountInfo 是管理员视图下账户详情的抽象模型。 + type: object + x-go-name: AdminAccountInfo + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + adminActionResponse: + description: |- + AdminActionResponse 是服务器对管理员操作的响应的抽象模型。 + properties: + action_id: + description: 操作的内部 ID。 + example: 01H9QG6TZ9W5P0402VFRVM17TH + type: string + x-go-name: ActionID + type: object + x-go-name: AdminActionResponse + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + adminEmoji: + properties: + category: + description: 于在表情选择器中对自定义表情进行排序。 + example: blobcats + type: string + x-go-name: Category + content_type: + description: 该表情的 MIME 内容类型。 + example: image/png + type: string + x-go-name: ContentType + disabled: + description: 若此表情已被管理员操作禁用，则为 true。 + example: false + type: boolean + x-go-name: Disabled + domain: + description: 该表情的来源实例域名。仅用于外站域名，否则键/值将不会设置。 + example: example.org + type: string + x-go-name: Domain + id: + description: 该表情的 ID。 + example: 01GEM7SFDZ7GZNRXFVZ3X4E4N1 + type: string + x-go-name: ID + shortcode: + description: 自定义表情的名称。 + example: blobcat_uwu + type: string + x-go-name: Shortcode + static_url: + description: 一个指向此自定义表情的静态副本的链接。 + example: https://example.org/fileserver/emojis/blogcat_uwu.png + type: string + x-go-name: StaticURL + total_file_size: + description: 表情占用的总文件大小（字节），包括静态和动画版本。 + example: 69420 + format: int64 + type: integer + x-go-name: TotalFileSize + updated_at: + description: 该表情的最后更新时间。 + example: "2022-10-05T09:21:26.419Z" + type: string + x-go-name: UpdatedAt + uri: + description: 该表情的 ActivityPub URI。 + example: https://example.org/emojis/016T5Q3SQKBT337DAKVSKNXXW1 + type: string + x-go-name: URI + url: + description: 该自定义表情的 Web URL。 + example: https://example.org/fileserver/emojis/blogcat_uwu.gif + type: string + x-go-name: URL + visible_in_picker: + description: 该表情是否在实例的表情选择器中可见。 + example: true + type: boolean + x-go-name: VisibleInPicker + title: AdminEmoji + description: AdminEmoji 是管理员视图下自定义表情的抽象模型。 + type: object + x-go-name: AdminEmoji + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + adminReport: + properties: + account: + $ref: '#/definitions/adminAccountInfo' + action_taken: + description: 管理员是否已对该举报采取行动。 + example: false + type: boolean + x-go-name: ActionTaken + action_taken_at: + description: |- + 若已采取行动，在何时采取的行动？ (ISO 8601 Datetime) + 如果未设置/尚未采取行动，则为null。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: ActionTakenAt + action_taken_by_account: + $ref: '#/definitions/adminAccountInfo' + action_taken_comment: + description: |- + 若已采取行动，管理员对采取的行动做了什么评论？ + 如果未设置/尚未采取行动，则为null。 + example: 账户已被封禁。 + type: string + x-go-name: ActionTakenComment + assigned_account: + $ref: '#/definitions/adminAccountInfo' + category: + description: 该举报的类别是？ + example: spam + type: string + x-go-name: Category + comment: + description: |- + 该举报创建时提交的评论。 + 如果未提交评论，则为空。 + example: 此人一直在骚扰我。 + type: string + x-go-name: Comment + created_at: + description: 举报创建时间 (ISO 8601 Datetime)。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: CreatedAt + forwarded: + description: 用于指示是否应将举报抄送外站实例的布尔值。 + example: true + type: boolean + x-go-name: Forwarded + id: + description: 举报的 ID。 + example: 01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: ID + rules: + description: |- + 该举报中提交的违反的规则数组。 + 如果未提交规则 ID，则为空。 + items: + $ref: '#/definitions/instanceRule' + type: array + x-go-name: Rules + statuses: + description: |- + 该举报中提交的贴文数组。 + 如果未提交贴文 ID，则为空。 + items: + $ref: '#/definitions/status' + type: array + x-go-name: Statuses + target_account: + $ref: '#/definitions/adminAccountInfo' + updated_at: + description: 针对此举报的最后一次操作的操作时间 (ISO 8601 Datetime)。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: UpdatedAt + title: AdminReport + description: AdminReport 是管理员视图下举报的抽象模型。 + type: object + x-go-name: AdminReport + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + application: + properties: + client_id: + description: 应用程序关联的客户端 ID。 + type: string + x-go-name: ClientID + client_secret: + description: 应用程序关联的客户端密钥。 + type: string + x-go-name: ClientSecret + id: + description: 应用程序的 ID。 + example: 01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: ID + name: + description: 应用程序的名称。 + example: Moshidon + type: string + x-go-name: Name + redirect_uri: + description: 授权后重定向 URI，用于应用程序 (OAuth2)。 + example: https://example.org/callback?some=query + type: string + x-go-name: RedirectURI + vapid_key: + description: 用于推送 API 的密钥。 + type: string + x-go-name: VapidKey + website: + description: 与应用程序关联的网站 (url)。 + example: https://tusky.app + type: string + x-go-name: Website + title: Application + description: Application 是对 API 应用程序的抽象模型。 + type: object + x-go-name: Application + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + attachment: + properties: + blurhash: + description: |- + 通过 BlurHash 算法计算的哈希，用于在媒体尚未下载时生成彩色预览缩略图。 + 参见 https://github.com/woltapp/blurhash + type: string + x-go-name: Blurhash + description: + description: 用于描述媒体附件内容的 Alt 文本。 + example: 一只橘猫在阳光下打盹。 + type: string + x-go-name: Description + id: + description: 媒体附件的 ID。 + example: 01FC31DZT1AYWDZ8XTCRWRBYRK + type: string + x-go-name: ID + meta: + $ref: '#/definitions/mediaMeta' + preview_remote_url: + description: |- + 外站服务器上的媒体附件缩略图地址。 + 仅在非本站实例上定义。 + example: https://some-other-server.org/attachments/small/ahhhhh.jpeg + type: string + x-go-name: PreviewRemoteURL + preview_url: + description: 该媒体附件的缩略图地址。 + example: https://example.org/fileserver/some_id/attachments/some_id/small/attachment.jpeg + type: string + x-go-name: PreviewURL + remote_url: + description: |- + 外站服务器上的媒体附件原图地址。 + 仅在非本站实例上定义。 + example: https://some-other-server.org/attachments/original/ahhhhh.jpeg + type: string + x-go-name: RemoteURL + text_url: + description: |- + 该媒体附件的短链接。 + 对于 GoToSocial，该值与 URL 相同，因为我们不创建较短的 URL。 + type: string + x-go-name: TextURL + type: + description: 附件的类型。 + example: image + type: string + x-go-name: Type + url: + description: 附件的原图地址。 + example: https://example.org/fileserver/some_id/attachments/some_id/original/attachment.jpeg + type: string + x-go-name: URL + title: Attachment + description: Attachment 是媒体附件的抽象模型。 + type: object + x-go-name: Attachment + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + card: + properties: + author_name: + description: 原始资源的作者。 + example: weewee@buzzfeed.com + type: string + x-go-name: AuthorName + author_url: + description: 指向原始资源作者的链接。 + example: https://buzzfeed.com/authors/weewee + type: string + x-go-name: AuthorURL + blurhash: + description: 通过 BlurHash 算法计算的哈希，用于在媒体尚未下载时生成彩色预览缩略图。 + type: string + x-go-name: Blurhash + description: + description: 预览的描述。 + example: 水是湿的吗？这很不好说。在这篇文章中，我们请教了一位专家... + type: string + x-go-name: Description + embed_url: + description: 用于照片嵌入，而非自定义 HTML。 + type: string + x-go-name: EmbedURL + height: + description: 预览的高度，以像素为单位。 + format: int64 + type: integer + x-go-name: Height + html: + description: 用于生成预览卡片的 HTML。 + type: string + x-go-name: HTML + image: + description: 预览缩略图。 + example: https://example.org/fileserver/preview/thumb.jpg + type: string + x-go-name: Image + provider_name: + description: 原始资源的提供者。 + example: 惊爆新闻 + type: string + x-go-name: ProviderName + provider_url: + description: 一个指向原始资源提供者的链接。 + example: https://buzzfeed.com + type: string + x-go-name: ProviderURL + title: + description: 链接到的资源的标题。 + example: 惊爆新闻：水是湿的吗？ + type: string + x-go-name: Title + type: + description: 预览卡片的类型。 + example: link + type: string + x-go-name: Type + url: + description: 链接指向的资源的地址。 + example: https://buzzfeed.com/some/fuckin/buzzfeed/article + type: string + x-go-name: URL + width: + description: 预览的宽度，单位为像素。 + format: int64 + type: integer + x-go-name: Width + title: Card + description: Card 表示使用 OpenGraph 标签从 URL 生成的丰富预览卡片。 + type: object + x-go-name: Card + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + conversation: + description: |- + Conversation 表示具有“私信”可见性的对话。 + properties: + accounts: + description: |- + 对话的参与者。 + 如果这是没有目标账户的对话(即仅自己可见的私信)， + 则仅包含请求账户本身。否则，将包括对话中的所有其他账户，但不包括请求账户。 + items: + $ref: '#/definitions/account' + type: array + x-go-name: Accounts + id: + description: 对话在本地数据库中的 ID。 + type: string + x-go-name: ID + last_status: + $ref: '#/definitions/status' + unread: + description: 该对话当前是否被标记为未读？ + type: boolean + x-go-name: Unread + type: object + x-go-name: Conversation + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + debugAPUrlResponse: + description: |- + DebugAPUrlResponse 提供对 AP URL 解引用请求的详细调试信息。 + properties: + request_headers: + additionalProperties: + items: + type: string + type: array + description: 发送请求时使用的 HTTP 标头。 + type: object + x-go-name: RequestHeaders + request_url: + description: 请求的外站 AP URL。 + type: string + x-go-name: RequestURL + response_body: + description: |- + 外站实例返回的 Body。 + 将是字符串化的字节；可能是 JSON，可能是错误文本，也可能同时是以上两者！ + type: string + x-go-name: ResponseBody + response_code: + description: 外站实例返回的 HTTP 状态码。 + format: int64 + type: integer + x-go-name: ResponseCode + response_headers: + additionalProperties: + items: + type: string + type: array + description: 外站实例返回的 HTTP 标头。 + type: object + x-go-name: ResponseHeaders + type: object + x-go-name: DebugAPUrlResponse + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + defaultPolicies: + properties: + direct: + $ref: '#/definitions/interactionPolicy' + private: + $ref: '#/definitions/interactionPolicy' + public: + $ref: '#/definitions/interactionPolicy' + unlisted: + $ref: '#/definitions/interactionPolicy' + title: 发起请求的账户的新贴文的默认互动规则。 + type: object + x-go-name: DefaultPolicies + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + domain: + description: Domain 表示一个外站实例 + properties: + domain: + description: 实例的主机名。 + example: example.org + type: string + x-go-name: Domain + public_comment: + description: 若实例被屏蔽，公开的屏蔽原因是什么。 + example: 它们被骚扰账号攻陷了。 + type: string + x-go-name: PublicComment + silenced_at: + description: 实例被静音/隐藏的时间。对于开放实例，此键将不会存在。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: SilencedAt + suspended_at: + description: 实例被屏蔽的时间。对于开放实例，此键将不会存在。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: SuspendedAt + type: object + x-go-name: Domain + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + domainPermission: + properties: + created_at: + description: 此权限条目创建的时间 (ISO 8601 Datetime)。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: CreatedAt + created_by: + description: 创建此实例权限条目的账户的 ID。 + example: 01FBW2758ZB6PBR200YPDDJK4C + type: string + x-go-name: CreatedBy + domain: + description: 此实例的主机名。 + example: example.org + type: string + x-go-name: Domain + id: + description: 此实例权限条目的 ID。 + example: 01FBW21XJA09XYX51KV5JVBW0F + readOnly: true + type: string + x-go-name: ID + obfuscate: + description: 是否在公开此实例权限条目时对域名进行模糊处理。 + example: false + type: boolean + x-go-name: Obfuscate + private_comment: + description: 对此权限条目的私密评论，仅对本站管理员可见。 + example: 它们管理员都是啥b啊 + type: string + x-go-name: PrivateComment + public_comment: + description: 若实例被屏蔽，公开的屏蔽原因是什么。 + example: 它们被骚扰账号攻陷了。 + type: string + x-go-name: PublicComment + silenced_at: + description: 该实例被静音/隐藏的时间。对于开放实例，此键将不会存在。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: SilencedAt + subscription_id: + description: 如果可用，导致此实例权限条目被创建的订阅的 ID。 + example: 01FBW25TF5J67JW3HFHZCSD23K + type: string + x-go-name: SubscriptionID + suspended_at: + description: 此实例被屏蔽的时间。对于开放实例，此键将不会存在。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: SuspendedAt + title: DomainPermission + description: DomainPermission 表示应用于某个实例的权限（显式阻止/允许）。 + type: object + x-go-name: DomainPermission + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + emoji: + properties: + category: + description: 用于在表情选择器中对自定义表情进行排序。 + example: blobcats + type: string + x-go-name: Category + shortcode: + description: 自定义表情的名称。 + example: blobcat_uwu + type: string + x-go-name: Shortcode + static_url: + description: 该自定义表情的静态副本链接。 + example: https://example.org/fileserver/emojis/blogcat_uwu.png + type: string + x-go-name: StaticURL + url: + description: 该自定义表情的 Web URL。 + example: https://example.org/fileserver/emojis/blogcat_uwu.gif + type: string + x-go-name: URL + visible_in_picker: + description: 该表情是否在实例的表情选择器中可见。 + example: true + type: boolean + x-go-name: VisibleInPicker + title: Emoji + description: Emoji 表示一个自定义表情。 + type: object + x-go-name: Emoji + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + emojiCategory: + properties: + id: + description: 自定义表情类别的 ID。 + type: string + x-go-name: ID + name: + description: 自定义表情类别的名称。 + type: string + x-go-name: Name + title: EmojiCategory + description: EmojiCategory 表示自定义表情的类别。 + type: object + x-go-name: EmojiCategory + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + field: + properties: + name: + description: 该附加字段的键/名称。 + example: 人称代词 + type: string + x-go-name: Name + value: + description: 该附加字段的值。 + example: they/them + type: string + x-go-name: Value + verified_at: + description: 如果此字段已被验证，是何时验证的？ (ISO 8601 Datetime) + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: VerifiedAt + title: Field + description: Field 表示要在账户资料上显示的名称/值对。 + type: object + x-go-name: Field + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + filterContext: + description: FilterContext 表示过滤规则要应用到的上下文。Filter API 的 v1 和 v2 使用相同的上下文集合。 + title: FilterContext + type: string + x-go-name: FilterContext + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + filterKeyword: + properties: + id: + description: 数据库中过滤关键词条目的 ID。 + type: string + x-go-name: ID + keyword: + description: 被过滤的文本。 + example: 挂人 + type: string + x-go-name: Keyword + whole_word: + description: 该过滤关键词是否应考虑单词边界？（整词匹配） + example: true + type: boolean + x-go-name: WholeWord + title: FilterKeyword + description: FilterKeyword 表示 v2 过滤规则中要过滤的关键词文本。 + type: object + x-go-name: FilterKeyword + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + filterResult: + properties: + filter: + $ref: '#/definitions/filterV2' + keyword_matches: + description: 该过滤规则中被匹配到的关键词。 + items: + type: string + type: array + x-go-name: KeywordMatches + status_matches: + description: 命中该过滤规则的贴文 ID。 + items: + type: string + type: array + x-go-name: StatusMatches + title: FilterResult + description: FilterResult 与被过滤的贴文一起返回，以解释为什么被过滤。 + type: object + x-go-name: FilterResult + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + filterStatus: + properties: + id: + description: 数据库中过滤贴文条目的 ID。 + type: string + x-go-name: ID + phrase: + description: 被过滤的贴文 ID。 + type: string + x-go-name: StatusID + title: FilterStatus + description: FilterStatus 表示 v2 过滤规则中被过滤的贴文 ID。 + type: object + x-go-name: FilterStatus + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + filterV1: + description: |- + FilterV1 表示用户定义的过滤规则，用于确定哪些贴文不应显示给用户。 + 注意，v1 过滤规则在内部处理时会映射到 v2 过滤规则和 v2 过滤关键词。 + 若 whole_word 为 true，则客户端应执行： + 为您的应用程序定义“单词组成字符 (word constituent character)”。在官方实现中，它是 [A-Za-z0-9_] (JavaScript) 和 [[:word:]] (Ruby)。 + Ruby 使用 POSIX 字符类 (Letter | Mark | Decimal_Number | Connector_Punctuation)。 + 如果短语以单词字符开头，并且匹配范围之前的前一个字符是单词字符，则应将其匹配范围视为不匹配。 + 如果短语以单词字符结尾，并且匹配范围之后的下一个字符是单词字符，则应将其匹配范围视为不匹配。 + 请查看 Mastodon 源代码中的 app/javascript/mastodon/selectors/index.js 和 app/lib/feed_manager.rb 以获取更多详细信息。 + properties: + context: + description: 该过滤规则被应用到的上下文。 + example: + - home + - public + items: + $ref: '#/definitions/filterContext' + minItems: 1 + type: array + uniqueItems: true + x-go-name: Context + expires_at: + description: 过滤规则不再生效的时间。如果过滤规则不会过期，则为 null。 + example: "2024-02-01T02:57:49Z" + type: string + x-go-name: ExpiresAt + id: + description: 数据库中过滤规则条目的 ID。 + type: string + x-go-name: ID + irreversible: + description: 命中的条目是否应从用户的时间线/视图中移除，而不是隐藏？ + example: false + type: boolean + x-go-name: Irreversible + phrase: + description: 被过滤的文本。 + example: 挂人 + type: string + x-go-name: Phrase + whole_word: + description: 过滤规则是否应考虑单词边界？ + example: true + type: boolean + x-go-name: WholeWord + title: FilterV1 + type: object + x-go-name: FilterV1 + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + filterV2: + description: FilterV2 表示用户定义的过滤规则，用于确定哪些贴文不应显示给用户。v2 过滤规则具有名称，并且可以包含多个短语和贴文 ID 以进行过滤。 + properties: + context: + description: 过滤规则应用的上下文。 + example: + - home + - public + items: + $ref: '#/definitions/filterContext' + minItems: 1 + type: array + uniqueItems: true + x-go-name: Context + expires_at: + description: 过滤规则不再生效的时间。如果过滤规则不会过期，则为 null。 + example: "2024-02-01T02:57:49Z" + type: string + x-go-name: ExpiresAt + filter_action: + $ref: '#/definitions/FilterAction' + id: + description: 数据库中过滤规则条目的 ID。 + type: string + x-go-name: ID + keywords: + description: 此过滤规则下的关键词。 + items: + $ref: '#/definitions/filterKeyword' + type: array + x-go-name: Keywords + statuses: + description: 此过滤规则下的贴文。 + items: + $ref: '#/definitions/filterStatus' + type: array + x-go-name: Statuses + title: + description: 此过滤规则的名称。 + example: Linux 相关 + type: string + x-go-name: Title + title: FilterV2 + type: object + x-go-name: FilterV2 + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + headerFilter: + properties: + created_at: + description: 标头过滤规则创建时间 (ISO 8601 Datetime)。 + example: "2021-07-30T09:20:25+00:00" + readOnly: true + type: string + x-go-name: CreatedAt + created_by: + description: 创建此标头过滤规则的管理员账户的 ID。 + example: 01FBW2758ZB6PBR200YPDDJK4C + readOnly: true + type: string + x-go-name: CreatedBy + header: + description: 此标头过滤规则匹配的 HTTP 标头。 + example: User-Agent + type: string + x-go-name: Header + id: + description: 此标头过滤规则的 ID。 + example: 01FBW21XJA09XYX51KV5JVBW0F + readOnly: true + type: string + x-go-name: ID + regex: + description: 此标头过滤规则的正则表达式。 + example: .*Firefox.* + type: string + x-go-name: Regex + title: HeaderFilter + description: HeaderFilter 表示应用于特定 HTTP 标头的正则过滤规则（允许/阻止）。 + type: object + x-go-name: HeaderFilter + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + hostmeta: + description: 'HostMeta 表示一份 hostmeta 文档。参见: https://www.rfc-editor.org/rfc/rfc6415.html#section-3' + properties: + Link: + items: + $ref: '#/definitions/Link' + type: array + XMLNS: + type: string + XMLName: {} + title: HostMeta + type: object + x-go-name: HostMeta + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceConfigurationAccounts: + properties: + allow_custom_css: + description: 此实例是否允许账户上传用于资料页和贴文页的自定义 CSS。 + example: false + type: boolean + x-go-name: AllowCustomCSS + max_featured_tags: + description: |- + 此实例允许每个账户设置的最大特色标签数。 + format: int64 + type: integer + x-go-name: MaxFeaturedTags + max_profile_fields: + description: |- + 此实例允许每个账户设置的最大附加字段数。 + 目前不可配置，硬编码为 6。详见 (https://github.com/superseriousbusiness/gotosocial/issues/1876) + format: int64 + type: integer + x-go-name: MaxProfileFields + title: InstanceConfigurationAccounts + description: InstanceConfigurationAccounts 是实例账户配置参数的抽象模型。 + type: object + x-go-name: InstanceConfigurationAccounts + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceConfigurationMediaAttachments: + properties: + image_matrix_limit: + description: |- + 图像的最大尺寸，以像素为单位，高度*宽度。 + + GtS 不对此设置限制，但为了保持兼容性，我们在这里给出 Mastodon 的 4096x4096px 值。 + example: 16777216 + format: int64 + type: integer + x-go-name: ImageMatrixLimit + image_size_limit: + description: 图像的最大大小，以字节为单位。 + example: 2097152 + format: int64 + type: integer + x-go-name: ImageSizeLimit + supported_mime_types: + description: 此实例支持上传的 MIME 类型列表。 + example: + - image/jpeg + - image/gif + items: + type: string + type: array + x-go-name: SupportedMimeTypes + video_frame_rate_limit: + description: 此实例支持的最大视频帧率。 + example: 60 + format: int64 + type: integer + x-go-name: VideoFrameRateLimit + video_matrix_limit: + description: |- + 此实例支持的最大视频尺寸，以像素为单位，高度*宽度。 + + GtS 不对此设置限制，但为了保持兼容性，我们在这里给出 Mastodon 的 4096x4096px 值。 + example: 16777216 + format: int64 + type: integer + x-go-name: VideoMatrixLimit + video_size_limit: + description: 视频的最大大小，以字节为单位。 + example: 10485760 + format: int64 + type: integer + x-go-name: VideoSizeLimit + title: InstanceConfigurationMediaAttachments + description: InstanceConfigurationMediaAttachments 是实例媒体附件配置参数的抽象模型。 + type: object + x-go-name: InstanceConfigurationMediaAttachments + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceConfigurationPolls: + properties: + max_characters_per_option: + description: 投票选项中允许的最大字符数。 + example: 50 + format: int64 + type: integer + x-go-name: MaxCharactersPerOption + max_expiration: + description: 投票的最大时长，以秒为单位。 + example: 2629746 + format: int64 + type: integer + x-go-name: MaxExpiration + max_options: + description: 此实例允许的最大投票选项数。 + example: 4 + format: int64 + type: integer + x-go-name: MaxOptions + min_expiration: + description: 投票的最小时长，以秒为单位。 + example: 300 + format: int64 + type: integer + x-go-name: MinExpiration + title: InstanceConfigurationPolls + description: InstanceConfigurationPolls 是实例投票配置参数的抽象模型。 + type: object + x-go-name: InstanceConfigurationPolls + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceConfigurationStatuses: + properties: + characters_reserved_per_url: + description: 客户端应假设 URL 占用的字符数。 + example: 25 + format: int64 + type: integer + x-go-name: CharactersReservedPerURL + max_characters: + description: 此实例允许的最大贴文长度，以字符为单位。 + example: 5000 + format: int64 + type: integer + x-go-name: MaxCharacters + max_media_attachments: + description: 此实例允许的最大媒体附件数。 + example: 4 + format: int64 + type: integer + x-go-name: MaxMediaAttachments + supported_mime_types: + description: 此实例的贴文可用的 MIME 类型列表。 + example: + - text/plain + - text/markdown + items: + type: string + type: array + x-go-name: SupportedMimeTypes + title: InstanceConfigurationStatuses + description: InstanceConfigurationStatuses 是实例贴文配置参数的抽象模型。 + type: object + x-go-name: InstanceConfigurationStatuses + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceRule: + properties: + id: + type: string + x-go-name: ID + text: + type: string + x-go-name: Text + title: InstanceRule + description: InstanceRule 表示一条实例规则。 + type: object + x-go-name: InstanceRule + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceV1: + properties: + account_domain: + description: |- + 此实例上的账户的域名。 + 这不一定与 URI 的 Host 部分相同。 + example: example.org + type: string + x-go-name: AccountDomain + approval_required: + description: 新账户注册需要管理员批准。 + type: boolean + x-go-name: ApprovalRequired + configuration: + $ref: '#/definitions/instanceV1Configuration' + contact_account: + $ref: '#/definitions/account' + debug: + description: 此实例是否在 DEBUG 模式下运行。如果为 false，则省略。 + type: boolean + x-go-name: Debug + description: + description: |- + 此实例的描述。 + + 应为 HTML 格式，但可能是纯文本。 + + 这应该显示在实例的“关于”页面上。 + type: string + x-go-name: Description + description_text: + description: 描述的原始（未解析）版本。 + type: string + x-go-name: DescriptionText + email: + description: 用于咨询的电子邮件地址。 + example: social@example.org + type: string + x-go-name: Email + invites_enabled: + description: 此实例是否允许邀请注册。 + type: boolean + x-go-name: InvitesEnabled + languages: + description: 此实例的主要语言。 + example: + - zh + items: + type: string + type: array + x-go-name: Languages + max_toot_chars: + description: |- + 此实例允许的最大贴文长度，以字符为单位。 + + 这是为了与 Tusky 和其他应用程序兼容而提供的。 + example: 5000 + format: uint64 + type: integer + x-go-name: MaxTootChars + registrations: + description: 此实例上启用了新账户注册。 + type: boolean + x-go-name: Registrations + rules: + description: 此实例的规则的条目化列表。 + items: + $ref: '#/definitions/instanceRule' + type: array + x-go-name: Rules + short_description: + description: |- + 此实例的简要描述。 + + 应为 HTML 格式，但可能是纯文本。 + + 这应该显示在实例的首页上。 + type: string + x-go-name: ShortDescription + short_description_text: + description: 短描述的原始（未解析）版本。 + type: string + x-go-name: ShortDescriptionText + stats: + additionalProperties: + format: int64 + type: integer + description: |- + 此实例的统计信息：贴文数、账户数等。 + 值为指针，因为我们不希望在通过 Web 模板渲染统计信息时跳过 0 值。 + type: object + x-go-name: Stats + terms: + description: 此实例的条款与条件。 + type: string + x-go-name: Terms + terms_text: + description: 条款与条件的原始（未解析）版本。 + type: string + x-go-name: TermsRaw + thumbnail: + description: 此实例的头像/横幅图像的 URL。 + example: https://example.org/files/instance/thumbnail.jpeg + type: string + x-go-name: Thumbnail + thumbnail_description: + description: 此实例的头像描述。 + example: 一张可爱的卡通小懒 + type: string + x-go-name: ThumbnailDescription + thumbnail_static: + description: 此实例头像/横幅图的静态版本的 URL。 + example: https://example.org/files/instance/static/thumbnail.webp + type: string + x-go-name: ThumbnailStatic + thumbnail_static_type: + description: 此实例的头像/横幅图的静态版本的 MIME 类型。 + example: image/webp + type: string + x-go-name: ThumbnailStaticType + thumbnail_type: + description: 此实例头像的 MIME 类型。 + example: image/png + type: string + x-go-name: ThumbnailType + title: + description: 实例的标题。 + example: GoToSocial 演示实例 + type: string + x-go-name: Title + uri: + description: 实例的 URI。 + example: https://gts.example.org + type: string + x-go-name: URI + urls: + $ref: '#/definitions/instanceV1URLs' + version: + description: |- + 此实例部署的 GoToSocial 版本。 + + 至少包含一个语义版本号。 + + 它还可能包含当前软件的 git 提交短 ID。 + example: 0.1.1 cb85f65 + type: string + x-go-name: Version + title: InstanceV1 + description: InstanceV1 是关于此实例的信息的抽象模型。 + type: object + x-go-name: InstanceV1 + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceV1Configuration: + properties: + accounts: + $ref: '#/definitions/instanceConfigurationAccounts' + emojis: + $ref: '#/definitions/InstanceConfigurationEmojis' + media_attachments: + $ref: '#/definitions/instanceConfigurationMediaAttachments' + oidc_enabled: + description: 若实例使用 OIDC 作为身份验证/身份后端，则为 true，否则省略。 + type: boolean + x-go-name: OIDCEnabled + polls: + $ref: '#/definitions/instanceConfigurationPolls' + statuses: + $ref: '#/definitions/instanceConfigurationStatuses' + title: InstanceV1Configuration + description: InstanceV1Configuration 是实例配置参数的抽象模型。 + type: object + x-go-name: InstanceV1Configuration + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceV1URLs: + properties: + streaming_api: + description: 用于贴文和通知的流式传输的 Websockets 地址。 + example: wss://example.org + type: string + x-go-name: StreamingAPI + title: InstanceV1URLs + description: InstanceV1URLs 是客户端应用程序使用的与实例相关的 URL 的抽象模型。 + type: object + x-go-name: InstanceV1URLs + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceV2: + properties: + account_domain: + description: |- + 此实例上的账户的域名。 + 这不一定与 URI 的 Host 部分相同。 + example: example.org + type: string + x-go-name: AccountDomain + configuration: + $ref: '#/definitions/instanceV2Configuration' + contact: + $ref: '#/definitions/instanceV2Contact' + debug: + description: 此实例是否在 DEBUG 模式下运行。如果为 false，则省略。 + type: boolean + x-go-name: Debug + description: + description: |- + 此实例的描述。 + + 应为 HTML 格式，但可能是纯文本。 + + 这应该显示在实例的“关于”页面上。 + type: string + x-go-name: Description + description_text: + description: 描述的原始（未解析）版本。 + type: string + x-go-name: DescriptionText + domain: + description: 实例的域名。 + example: gts.example.org + type: string + x-go-name: Domain + languages: + description: 实例和实例站务/管理员的主要语言。 + example: + - zh + items: + type: string + type: array + x-go-name: Languages + registrations: + $ref: '#/definitions/instanceV2Registrations' + rules: + description: 该实例的规则的条目化列表。 + items: + $ref: '#/definitions/instanceRule' + type: array + x-go-name: Rules + source_url: + description: 本实例部署的软件的源代码 URL，应 AGPL 许可要求提供。 + example: https://github.com/superseriousbusiness/gotosocial + type: string + x-go-name: SourceURL + terms: + description: 本实例的账户条款与条件。 + type: string + x-go-name: Terms + terms_text: + description: 条款与条件的原始（未解析）版本。 + type: string + x-go-name: TermsText + thumbnail: + $ref: '#/definitions/instanceV2Thumbnail' + title: + description: 实例的标题。 + example: GoToSocial 演示实例 + type: string + x-go-name: Title + usage: + $ref: '#/definitions/instanceV2Usage' + version: + description: |- + 此实例部署的 GoToSocial 版本。 + + 至少包含一个语义版本号。 + + 它还可能包含当前软件的 git 提交短 ID。 + example: 0.1.1 cb85f65 + type: string + x-go-name: Version + title: InstanceV2 + description: InstanceV2 是关于此实例的信息的抽象模型。 + type: object + x-go-name: InstanceV2 + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceV2Configuration: + properties: + accounts: + $ref: '#/definitions/instanceConfigurationAccounts' + emojis: + $ref: '#/definitions/InstanceConfigurationEmojis' + media_attachments: + $ref: '#/definitions/instanceConfigurationMediaAttachments' + oidc_enabled: + description: 若实例使用 OIDC 作为身份验证/身份后端，则为 true，否则省略。 + type: boolean + x-go-name: OIDCEnabled + polls: + $ref: '#/definitions/instanceConfigurationPolls' + statuses: + $ref: '#/definitions/instanceConfigurationStatuses' + translation: + $ref: '#/definitions/instanceV2ConfigurationTranslation' + urls: + $ref: '#/definitions/instanceV2URLs' + title: InstanceV2Configuration + description: 此实例的配置值和限制。 + type: object + x-go-name: InstanceV2Configuration + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceV2ConfigurationTranslation: + properties: + enabled: + description: |- + 此实例是否支持翻译 API。 + 由于尚未实现，因此此值始终为 false。 + type: boolean + x-go-name: Enabled + title: InstanceV2ConfigurationTranslation + description: 关于翻译功能的提示。 + type: object + x-go-name: InstanceV2ConfigurationTranslation + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceV2Contact: + properties: + account: + $ref: '#/definitions/account' + email: + description: |- + 可用于咨询和问题反馈的电子邮件地址。 + 如果未设置电子邮件地址，则为空字符串。 + example: someone@example.org + type: string + x-go-name: Email + title: InstanceV2Contact + description: 此实例的联系信息。 + type: object + x-go-name: InstanceV2Contact + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceV2Registrations: + properties: + approval_required: + description: 此实例是否需要管理员批准新账户注册。 + example: true + type: boolean + x-go-name: ApprovalRequired + enabled: + description: 是否开放注册。 + example: false + type: boolean + x-go-name: Enabled + message: + description: |- + 一条自定义消息（HTML 字符串），用于在关闭注册时显示。 + example:

由于骚扰猖獗，example.org 目前关闭了注册，请联系管理员以获取帮助。

+ type: string + x-go-name: Message + title: InstanceV2Registrations + description: 此实例有关注册的信息。 + type: object + x-go-name: InstanceV2Registrations + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceV2Thumbnail: + properties: + blurhash: + description: |- + 通过 BlurHash 算法计算的哈希，用于在媒体尚未下载时生成彩色预览缩略图。 + example: UeKUpFxuo~R%0nW;WCnhF6RjaJt757oJodS$ + type: string + x-go-name: Blurhash + static_url: + description: 缩略图图像的静态版本的 URL。 + example: https://example.org/fileserver/01BPSX2MKCRVMD4YN4D71G9CP5/attachment/static/01H88X0KQ2DFYYDSWYP93VDJZA.webp + type: string + x-go-name: StaticURL + thumbnail_description: + description: |- + 实例缩略图的描述。 + 如果没有描述可用，则不设置键/值。 + example: 一只可爱的小懒 + type: string + x-go-name: Description + thumbnail_static_type: + description: |- + 实例缩略图的静态版本的 MIME 类型。 + 如果类型未知，则不设置键/值。 + example: image/png + type: string + x-go-name: StaticType + thumbnail_type: + description: |- + 实例缩略图的 MIME 类型。 + 如果类型未知，则不设置键/值。 + example: image/png + type: string + x-go-name: Type + url: + description: 缩略图的 URL。 + example: https://example.org/fileserver/01BPSX2MKCRVMD4YN4D71G9CP5/attachment/original/01H88X0KQ2DFYYDSWYP93VDJZA.png + type: string + x-go-name: URL + versions: + $ref: '#/definitions/instanceV2ThumbnailVersions' + title: InstanceV2Thumbnail + description: 代表此实例的图像。 + type: object + x-go-name: InstanceV2Thumbnail + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceV2ThumbnailVersions: + properties: + '@1x': + description: |- + 此缩略图的 1 倍分辨率缩放版本的 URL。 + 如果未提供此缩放版本，则不设置键/值。 + type: string + x-go-name: Size1URL + '@2x': + description: |- + 此缩略图的 2 倍分辨率缩放版本的 URL。 + 如果未提供此缩放版本，则不设置键/值。 + type: string + x-go-name: Size2URL + title: InstanceV2ThumbnailVersions + description: 缩略图的高分辨率版本，用于高 DPI 屏幕。 + type: object + x-go-name: InstanceV2ThumbnailVersions + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceV2URLs: + properties: + streaming: + description: 用于流式传输贴文和通知的 Websockets 地址。 + example: wss://example.org + type: string + x-go-name: Streaming + title: InstanceV2URLs + description: InstanceV2URLs 是客户端应用程序使用的与实例相关的 URL 的抽象模型。 + type: object + x-go-name: InstanceV2URLs + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceV2Usage: + properties: + users: + $ref: '#/definitions/instanceV2Users' + title: InstanceV2Usage + description: InstanceV2Usage 是关于此实例的使用数据的抽象模型。 + type: object + x-go-name: InstanceV2Usage + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + instanceV2Users: + properties: + active_month: + description: |- + 此实例过去 4 周内的活跃用户数。 + 目前未实现：将始终为 0。 + example: 0 + format: int64 + type: integer + x-go-name: ActiveMonth + title: InstanceV2Users + description: 此实例的用户使用数据。 + type: object + x-go-name: InstanceV2Users + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + interactionPolicy: + properties: + can_favourite: + $ref: '#/definitions/interactionPolicyRules' + can_reblog: + $ref: '#/definitions/interactionPolicyRules' + can_reply: + $ref: '#/definitions/interactionPolicyRules' + title: InteractionPolicy + description: 某条贴文的互动规则。 + type: object + x-go-name: InteractionPolicy + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + interactionPolicyRules: + properties: + always: + description: 始终可以执行此类互动的账户的规则条目。 + items: + $ref: '#/definitions/interactionPolicyValue' + type: array + x-go-name: Always + with_approval: + description: 执行此类互动需要批准的账户的规则条目。 + items: + $ref: '#/definitions/interactionPolicyValue' + type: array + x-go-name: WithApproval + title: InteractionPolicyRules + description: 某类互动的规则。 + type: object + x-go-name: PolicyRules + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + interactionPolicyValue: + description: |- + 一条贴文的互动规则条目。 + 可以是以下内部关键字之一，也可以是一个完整的 ActivityPub Actor URI，如 "https://example.org/users/some_user"。 + + 内部关键字： + + public - 公开，即任何可以根据其可见性级别看到此贴文的人。 + followers - 贴文作者的粉丝。 + following - 贴文作者关注的人。 + mutuals - 贴文作者的互相关注（保留，未使用）。 + mentioned - 在贴文中提到的账户，或者在贴文中回复的账户。 + author - 贴文作者本人。 + me - 如果请求是由授权用户发出的，则 "me" 代表发出请求的、现在正在查询此互动策略的用户。 + title: InteractionPolicyValue + type: string + x-go-name: PolicyValue + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + interactionRequest: + properties: + accepted_at: + description: The timestamp that the interaction request was accepted (ISO 8601 Datetime). Field omitted if request not accepted (yet). 互动请求被接受的时间戳 (ISO 8601 Datetime)。如果请求尚未被接受，则省略此字段。 + type: string + x-go-name: AcceptedAt + account: + $ref: '#/definitions/account' + created_at: + description: 互动请求的时间戳 (ISO 8601 Datetime) + type: string + x-go-name: CreatedAt + id: + description: 互动请求在数据库中的 ID。 + type: string + x-go-name: ID + rejected_at: + description: 互动请求被拒绝的时间戳 (ISO 8601 Datetime)。如果请求尚未被拒绝，则省略此字段。 + type: string + x-go-name: RejectedAt + reply: + $ref: '#/definitions/status' + status: + $ref: '#/definitions/status' + type: + description: |- + 该互动请求所涉及的互动类型。 + + `favourite` - 有人点赞了一条贴文。 + `reply` - 有人回复了一条贴文。 + `reblog` - 有人转发了一条贴文。 + type: string + x-go-name: Type + uri: + description: 接受或拒绝的 URI。仅在设置了 accepted_at 或 rejected_at 时设置，否则省略。 + type: string + x-go-name: URI + title: InteractionRequest + description: InteractionRequest 表示待处理、已批准或已拒绝的点赞、回复或转发互动。 + type: object + x-go-name: InteractionRequest + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + list: + properties: + exclusive: + description: |- + 此列表是否为单独列表。 + 如果为 true，则在主页时间线中隐藏此列表的成员的贴文。 + type: boolean + x-go-name: Exclusive + id: + description: 列表的 ID。 + type: string + x-go-name: ID + replies_policy: + description: |- + 此列表的回复显示规则。 + followed = 显示任何对已关注用户的回复 + list = 显示对列表成员的回复 + none = 不显示任何回复 + type: string + x-go-name: RepliesPolicy + title: + description: 用户设定的列表名称。 + type: string + x-go-name: Title + title: List + description: List 表示用户为关注的账户创建的列表。 + type: object + x-go-name: List + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + markers: + properties: + home: + $ref: '#/definitions/TimelineMarker' + notifications: + $ref: '#/definitions/TimelineMarker' + title: Marker + description: Marker 表示用户时间线中的上次阅读位置。 + type: object + x-go-name: Marker + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + mediaDimensions: + properties: + aspect: + description: |- + 媒体附件的宽高比。 + 等于宽度 / 高度。 + example: 1.777777778 + format: float + type: number + x-go-name: Aspect + bitrate: + description: 媒体附件的比特率，以每秒位数为单位。 + example: 1000000 + format: uint64 + type: integer + x-go-name: Bitrate + duration: + description: |- + 媒体的时长（秒）。 + 仅对视频和音频设置。 + example: 5.43 + format: float + type: number + x-go-name: Duration + frame_rate: + description: |- + 媒体的帧率。 + 仅对视频和 GIF 设置。 + example: "30" + type: string + x-go-name: FrameRate + height: + description: |- + 媒体的高度（像素）。 + 对于音频不设置。 + example: 1080 + format: int64 + type: integer + x-go-name: Height + size: + description: |- + 媒体的尺寸，格式为 `[width]x[height]`。 + 对于音频不设置。 + example: 1920x1080 + type: string + x-go-name: Size + width: + description: |- + 媒体的宽度（像素）。 + 对于音频不设置。 + example: 1920 + format: int64 + type: integer + x-go-name: Width + title: MediaDimensions + description: MediaDimensions 是一份媒体附件的详细属性的抽象模型。 + type: object + x-go-name: MediaDimensions + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + mediaFocus: + properties: + x: + description: |- + 焦点的 x 轴位置，应在 -1 和 1 之间 + format: float + type: number + x-go-name: X + "y": + description: |- + 焦点的 y 轴位置，应在 -1 和 1 之间 + format: float + type: number + x-go-name: "Y" + title: MediaFocus + description: MediaFocus 是媒体附件的焦点的抽象模型。 + type: object + x-go-name: MediaFocus + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + mediaMeta: + description: MediaMeta 是媒体附件的元数据的抽象模型。这可以是有关图像、音频文件、视频等的元数据。 + properties: + focus: + $ref: '#/definitions/mediaFocus' + original: + $ref: '#/definitions/mediaDimensions' + small: + $ref: '#/definitions/mediaDimensions' + title: MediaMeta + type: object + x-go-name: MediaMeta + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + mutedAccount: + properties: + acct: + description: |- + 通过 webfinger 发现的账户 URI。 + 对于本地用户，等于用户名；对于远程用户，等于用户名@域名。 + example: some_user@example.org + type: string + x-go-name: Acct + avatar: + description: 该账户的头像的 Web 地址。 + example: https://example.org/media/some_user/avatar/original/avatar.jpeg + type: string + x-go-name: Avatar + avatar_description: + description: 该账户的头像描述，用于 alt 文本。 + example: 一张微笑的树懒的可爱图画。 + type: string + x-go-name: AvatarDescription + avatar_media_id: + description: |- + 此账户的头像对应的媒体附件的数据库 ID。 + 如果此账户没有上传头像（即默认头像），则省略。 + example: 01JAJ3XCD66K3T99JZESCR137W + type: string + x-go-name: AvatarMediaID + avatar_static: + description: |- + 账户头像的静态版本的 Web 地址。 + 仅在账户的主头像是视频或 gif 时才有用。 + example: https://example.org/media/some_user/avatar/static/avatar.png + type: string + x-go-name: AvatarStatic + bot: + description: 账户被标记为机器人。 + type: boolean + x-go-name: Bot + created_at: + description: 该账户创建的时间 (ISO 8601 Datetime)。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: CreatedAt + custom_css: + description: 渲染此账户的资料页或贴文页时包含的自定义 CSS。 + type: string + x-go-name: CustomCSS + discoverable: + description: 账户选择加入发现功能。 + type: boolean + x-go-name: Discoverable + display_name: + description: 账户的昵称。 + example: big jeff (he/him) + type: string + x-go-name: DisplayName + emojis: + description: |- + 账户的简介或显示名称中使用的自定义表情符号的数组。 + 对于被屏蔽的账户为空。 + items: + $ref: '#/definitions/emoji' + type: array + x-go-name: Emojis + enable_rss: + description: |- + 账户已启用 RSS 订阅。 + 如果为 false，则省略键/值。 + type: boolean + x-go-name: EnableRSS + fields: + description: |- + 账户资料中的附加元数据。 + 对于被屏蔽的账户为空。 + items: + $ref: '#/definitions/field' + type: array + x-go-name: Fields + followers_count: + description: 该账户的粉丝数，数据来源于本站实例。 + format: int64 + type: integer + x-go-name: FollowersCount + following_count: + description: 该账户关注的账户数，数据来源于本站实例。 + format: int64 + type: integer + x-go-name: FollowingCount + header: + description: 账户资料卡横幅背景图的 Web 地址。 + example: https://example.org/media/some_user/header/original/header.jpeg + type: string + x-go-name: Header + header_description: + description: 账户资料卡横幅背景图的描述，用于 alt 文本。 + example: 花开富贵。 + type: string + x-go-name: HeaderDescription + header_media_id: + description: |- + 此账户的资料卡横幅背景图片对应的媒体附件的数据库 ID。 + 如果此账户没有上传资料卡横幅背景图（即使用默认横幅背景），则省略。 + example: 01JAJ3XCD66K3T99JZESCR137W + type: string + x-go-name: HeaderMediaID + header_static: + description: |- + 账户资料卡横幅背景图的静态版本的 Web 地址。 + 仅在账户的主横幅是视频或 gif 时才有用。 + example: https://example.org/media/some_user/header/static/header.png + type: string + x-go-name: HeaderStatic + hide_collections: + description: |- + 账户选择隐藏他们的粉丝/关注数据。 + 如果为 false，则省略键/值。 + type: boolean + x-go-name: HideCollections + id: + description: 账户 ID。 + example: 01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: ID + last_status_at: + description: 账户上次发帖的时间 (ISO 8601 Date)。 + example: "2021-07-30" + type: string + x-go-name: LastStatusAt + locked: + description: 账户手动批准关注请求。 + type: boolean + x-go-name: Locked + moved: + $ref: '#/definitions/account' + mute_expires_at: + description: |- + 如果此账户被静音/隐藏，静音/隐藏将在何时到期 (ISO 8601 Datetime)。 + 如果静音/隐藏是永久的，值将为 null。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: MuteExpiresAt + note: + description: 该账户的简介/描述。 + type: string + x-go-name: Note + role: + $ref: '#/definitions/accountRole' + roles: + description: |- + Roles 列出了账户在本实例上的公开身份。 + 与 Role 不同，此属性始终可用的，但从不包含权限细节。 + items: + $ref: '#/definitions/accountDisplayRole' + type: array + x-go-name: Roles + source: + $ref: '#/definitions/Source' + statuses_count: + description: 该账户发布的贴文数，数据来源于本站实例。 + format: int64 + type: integer + x-go-name: StatusesCount + suspended: + description: 账户已被本站实例封禁。 + type: boolean + x-go-name: Suspended + theme: + description: 用户选择的 CSS 主题的文件名，用于在渲染此账户的资料页或贴文页时包含。例如，`blurple-light.css`。 + type: string + x-go-name: Theme + url: + description: 该账户资料页的 Web 地址。 + example: https://example.org/@some_user + type: string + x-go-name: URL + username: + description: 账户的用户名，不包括域名。 + example: some_user + type: string + x-go-name: Username + title: MutedAccount + description: MutedAccount 扩展了 Account，其中包含仅静音/隐藏用户列表使用的字段。 + type: object + x-go-name: MutedAccount + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + nodeinfo: + description: 'NodeInfo 表示版本 2.1 或版本 2.0 的 nodeinfo 数据结构。参见: https://nodeinfo.diaspora.software/schema.html' + properties: + metadata: + additionalProperties: {} + description: 自由形式的键值对，用于软件特定值。客户端不应依赖于任何特定的键存在。 + type: object + x-go-name: Metadata + openRegistrations: + description: 此服务器是否开放自主注册。 + example: false + type: boolean + x-go-name: OpenRegistrations + protocols: + description: 服务器支持的协议。 + items: + type: string + type: array + x-go-name: Protocols + services: + $ref: '#/definitions/NodeInfoServices' + software: + $ref: '#/definitions/NodeInfoSoftware' + usage: + $ref: '#/definitions/NodeInfoUsage' + version: + description: NodeInfo 数据结构版本。 + example: "2.0" + type: string + x-go-name: Version + title: Nodeinfo + type: object + x-go-name: Nodeinfo + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + notification: + properties: + account: + $ref: '#/definitions/account' + created_at: + description: 通知的时间戳 (ISO 8601 Datetime) + type: string + x-go-name: CreatedAt + id: + description: 通知在数据库中的 ID。 + type: string + x-go-name: ID + status: + $ref: '#/definitions/status' + type: + description: |- + 触发通知的事件类型。 + follow = 有人关注了你。`account` 将被设置。 + follow_request = 有人请求关注你。`account` 将被设置。 + mention = 有人在他们的贴文中提到了你。`status` 将被设置。`account` 将被设置。 + reblog = 有人转发了你的一条贴文。`status` 将被设置。`account` 将被设置。 + favourite = 有人点赞了你的一条贴文。`status` 将被设置。`account` 将被设置。 + poll = 你参与或创建的一次投票已结束。`status` 将被设置。`account` 将被设置。 + status = 你设置的接收发帖通知的某个账户发布了一条贴文。`status` 将被设置。`account` 将被设置。 + admin.sign_up = 有人在实例上注册了一个新账户。`account` 将被设置。 + type: string + x-go-name: Type + title: Notification + description: Notification 表示与用户相关的事件的通知。 + type: object + x-go-name: Notification + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + oauthToken: + properties: + access_token: + description: 用于身份验证的访问令牌。 + type: string + x-go-name: AccessToken + created_at: + description: 生成 OAuth 令牌的时间 (UNIX 时间戳格式的秒)。 + example: 1627644520 + format: int64 + type: integer + x-go-name: CreatedAt + scope: + description: 此令牌被授予的 OAuth 作用域，以空格分隔。 + example: read write admin + type: string + x-go-name: Scope + token_type: + description: OAuth 令牌类型。将始终为 'Bearer'。 + example: bearer + type: string + x-go-name: TokenType + title: Token + description: Token 表示用于 GoToSocial API 身份验证和执行操作的 OAuth 令牌。 + type: object + x-go-name: Token + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + poll: + properties: + emojis: + description: 渲染投票选项时使用的自定义表情符号。 + items: + $ref: '#/definitions/emoji' + type: array + x-go-name: Emojis + expired: + description: 投票是否已结束？ + type: boolean + x-go-name: Expired + expires_at: + description: 投票结束时间 (ISO 8601 Datetime)。 + type: string + x-go-name: ExpiresAt + id: + description: 数据库中投票的 ID。 + example: 01FBYKMD1KBMJ0W6JF1YZ3VY5D + type: string + x-go-name: ID + multiple: + description: 投票是否允许多选？ + type: boolean + x-go-name: Multiple + options: + description: 投票的选项。 + items: + $ref: '#/definitions/pollOption' + type: array + x-go-name: Options + own_votes: + description: |- + 当使用用户令牌调用时，令牌关联的授权用户选择了哪些选项？包含选项的索引值数组。 + + 未提供用户令牌时省略。 + items: + format: int64 + type: integer + type: array + x-go-name: OwnVotes + voted: + description: |- + 当使用用户令牌调用时，令牌关联的授权用户是否已投票？ + + 未提供用户令牌时省略。 + type: boolean + x-go-name: Voted + voters_count: + description: 多选投票中有多少个独立账户投票。 + format: int64 + type: integer + x-go-name: VotersCount + votes_count: + description: 收到了多少票。 + format: int64 + type: integer + x-go-name: VotesCount + title: Poll + description: Poll 表示一个附加到贴文的投票。 + type: object + x-go-name: Poll + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + pollOption: + properties: + title: + description: 投票选项的文本值。格式为字符串。 + type: string + x-go-name: Title + votes_count: + description: 该选项收到的票数。 + format: int64 + type: integer + x-go-name: VotesCount + title: PollOption + description: PollOption 表示不同投票选项的当前投票计数。 + type: object + x-go-name: PollOption + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + report: + properties: + action_taken: + description: 管理员是否已对此举报采取行动。 + example: false + type: boolean + x-go-name: ActionTaken + action_taken_at: + description: |- + 若已采取行动，在何时采取行动？(ISO 8601 Datetime) + 如果未设置/尚未采取行动，则为null。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: ActionTakenAt + action_taken_comment: + description: |- + 若已采取行动，管理员在采取行动时发表了什么评论？ + 如果未设置/尚未采取行动，则为null。 + example: 账户已被封禁。 + type: string + x-go-name: ActionTakenComment + category: + description: 此举报是在哪个类别下创建的？ + example: spam + type: string + x-go-name: Category + comment: + description: |- + 提交举报时附带的评论。 + 如果未提交评论，则为空。 + example: 此人一直在骚扰我。 + type: string + x-go-name: Comment + created_at: + description: 举报被创建的时间 (ISO 8601 Datetime)。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: CreatedAt + forwarded: + description: 用于指示是否应将举报抄送到外站实例的布尔值。 + example: true + type: boolean + x-go-name: Forwarded + id: + description: 举报的 ID。 + example: 01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: ID + rule_ids: + description: |- + 与该举报一并提交的实例规则的 ID 数组。 + 如果未提交规则 ID，则为空。 + example: + - 01GPBN5YDY6JKBWE44H7YQBDCQ + - 01GPBN65PDWSBPWVDD0SQCFFY3 + items: + type: string + type: array + x-go-name: RuleIDs + status_ids: + description: |- + 与此举报一起提交的贴文的 ID 数组。 + 如果未提交贴文 ID，则为空。 + example: + - 01GPBN5YDY6JKBWE44H7YQBDCQ + - 01GPBN65PDWSBPWVDD0SQCFFY3 + items: + type: string + type: array + x-go-name: StatusIDs + target_account: + $ref: '#/definitions/account' + title: Report + description: Report 是提交给实例的一份举报的抽象模型，可以通过客户端 API 或联合 API 提交。 + type: object + x-go-name: Report + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + searchResult: + properties: + accounts: + items: + $ref: '#/definitions/account' + type: array + x-go-name: Accounts + hashtags: + description: 若为 API v1，则为字符串切片；若为 API v2，则为话题标签切片。 + items: {} + type: array + x-go-name: Hashtags + statuses: + items: + $ref: '#/definitions/status' + type: array + x-go-name: Statuses + title: SearchResult + description: SearchResult 是一次搜索结果的抽象模型。 + type: object + x-go-name: SearchResult + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + status: + properties: + account: + $ref: '#/definitions/account' + application: + $ref: '#/definitions/application' + bookmarked: + description: 此贴文已被查看的账户收藏。 + type: boolean + x-go-name: Bookmarked + card: + $ref: '#/definitions/card' + content: + description: 此贴文的内容。应为 HTML，但在某些情况下也可能为纯文本。 + example:

你好，我是一条嘟文。

+ type: string + x-go-name: Content + created_at: + description: 此贴文的创建时间 (ISO 8601 Datetime)。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: CreatedAt + emojis: + description: 此贴文内容中使用的自定义表情符号。 + items: + $ref: '#/definitions/emoji' + type: array + x-go-name: Emojis + favourited: + description: 此贴文已被查看它的账户点赞。 + type: boolean + x-go-name: Favourited + favourites_count: + description: 此贴文收到的点赞数，数据来源于本站实例。 + format: int64 + type: integer + x-go-name: FavouritesCount + filtered: + description: 此贴文命中的过滤规则列表，如果有命中的过滤规则，还会包含命中原因。 + items: + $ref: '#/definitions/filterResult' + type: array + x-go-name: Filtered + id: + description: 此贴文的 ID。 + example: 01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: ID + in_reply_to_account_id: + description: 此贴文回复的账户的 ID。 + example: 01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: InReplyToAccountID + in_reply_to_id: + description: 此贴文回复的贴文的 ID。 + example: 01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: InReplyToID + interaction_policy: + $ref: '#/definitions/interactionPolicy' + language: + description: |- + 此贴文的主要语言 (ISO 639 Part 1 两字母语言代码)。当语言未知时将为 null。 + example: en + type: string + x-go-name: Language + local_only: + description: 若贴文不参与联合，则设置为 "true"；否则省略。 + type: boolean + x-go-name: LocalOnly + media_attachments: + description: 附于到此贴文的媒体。 + items: + $ref: '#/definitions/attachment' + type: array + x-go-name: MediaAttachments + mentions: + description: 此贴文内容中提及的用户。 + items: + $ref: '#/definitions/Mention' + type: array + x-go-name: Mentions + muted: + description: 此贴文下的回复已被查看它的账户静音。 + type: boolean + x-go-name: Muted + pinned: + description: 此贴文已被查看它的账户置顶（仅适用于您自己的贴文）。 + type: boolean + x-go-name: Pinned + poll: + $ref: '#/definitions/poll' + reblog: + $ref: '#/definitions/statusReblogged' + reblogged: + description: 此贴文已被查看它的账户转发。 + type: boolean + x-go-name: Reblogged + reblogs_count: + description: 此贴文被转发的次数，数据来源于本站实例。 + format: int64 + type: integer + x-go-name: ReblogsCount + replies_count: + description: 此贴文的回复数，数据来源于本站实例。 + format: int64 + type: integer + x-go-name: RepliesCount + sensitive: + description: 此贴文包含敏感内容。 + example: false + type: boolean + x-go-name: Sensitive + spoiler_text: + description: 此贴文的主题、摘要或内容警告。 + example: NSFW 警告 + type: string + x-go-name: SpoilerText + tags: + description: 贴文内容中使用的话题标签。 + items: + $ref: '#/definitions/tag' + type: array + x-go-name: Tags + text: + description: |- + 贴文的纯文本内容。当贴文被删除时返回，以便用户可以从源文本重新起草，而无需客户端从 HTML 内容中逆向出原始文本。 + type: string + x-go-name: Text + uri: + description: 此贴文的 ActivityPub URI。等同于贴文的 activitypub ID。 + example: https://example.org/users/some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: URI + url: + description: 此贴文的公开 Web URL。仅当贴文的可见性为 'public' 时，此链接才有效。 + example: https://example.org/@some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: URL + visibility: + description: 此贴文的可见性。 + example: unlisted + type: string + x-go-name: Visibility + title: Status + description: Status 表示一条贴文或帖子。 + type: object + x-go-name: Status + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + statusEdit: + description: |- + StatusEdit 表示一条贴文的一个历史修订版本，包含该修订版本的状态的部分信息。 + properties: + account: + $ref: '#/definitions/account' + content: + description: |- + 本次修订的贴文内容。 + 应为 HTML，但在某些情况下也可能为纯文本。 + example:

这是一条嘟文。

+ type: string + x-go-name: Content + created_at: + description: 此修订版本创建的时间 (ISO 8601 Datetime)。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: CreatedAt + emojis: + description: 渲染此贴文时用到的自定义表情符号。 + items: + $ref: '#/definitions/emoji' + type: array + x-go-name: Emojis + media_attachments: + description: 此贴文随附的媒体。 + items: + $ref: '#/definitions/attachment' + type: array + x-go-name: MediaAttachments + poll: + $ref: '#/definitions/poll' + sensitive: + description: 贴文在本次编辑中被标记为敏感。 + example: false + type: boolean + x-go-name: Sensitive + spoiler_text: + description: 本次编辑中设定的贴文主题、摘要或内容警告。 + example: warning nsfw + type: string + x-go-name: SpoilerText + type: object + x-go-name: StatusEdit + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + statusReblogged: + properties: + account: + $ref: '#/definitions/account' + application: + $ref: '#/definitions/application' + bookmarked: + description: 此贴文已被查看它的账户收藏。 + type: boolean + x-go-name: Bookmarked + card: + $ref: '#/definitions/card' + content: + description: 此贴文的内容。应为 HTML，但在某些情况下也可能为纯文本。 + example:

这是一条嘟文。

+ type: string + x-go-name: Content + created_at: + description: 此贴文的创建时间 (ISO 8601 Datetime)。 + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: CreatedAt + emojis: + description: 渲染此贴文时使用的自定义表情符号。 + items: + $ref: '#/definitions/emoji' + type: array + x-go-name: Emojis + favourited: + description: 此贴文已被查看它的账户点赞。 + type: boolean + x-go-name: Favourited + favourites_count: + description: 此贴文收到的点赞数，数据来源于本站实例。 + format: int64 + type: integer + x-go-name: FavouritesCount + filtered: + description: 此贴文命中的过滤规则列表，如果有命中的过滤规则，还会包含命中原因。 + items: + $ref: '#/definitions/filterResult' + type: array + x-go-name: Filtered + id: + description: 贴文的 ID。 + example: 01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: ID + in_reply_to_account_id: + description: 贴文回复的账户的 ID。 + example: 01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: InReplyToAccountID + in_reply_to_id: + description: 此贴文回复的贴文的 ID。 + example: 01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: InReplyToID + interaction_policy: + $ref: '#/definitions/interactionPolicy' + language: + description: |- + 此贴文的主要语言 (ISO 639 Part 1 两字母语言代码)。 + 当语言未知时将为 null。 + example: zh + type: string + x-go-name: Language + local_only: + description: 若贴文不参与联合，则设置为 "true"；否则省略。 + type: boolean + x-go-name: LocalOnly + media_attachments: + description: 随附到此贴文的媒体。 + items: + $ref: '#/definitions/attachment' + type: array + x-go-name: MediaAttachments + mentions: + description: 此贴文内容中提及的用户。 + items: + $ref: '#/definitions/Mention' + type: array + x-go-name: Mentions + muted: + description: 此贴文下的回复已被查看它的账户静音。 + type: boolean + x-go-name: Muted + pinned: + description: 此贴文已被查看它的账户置顶（仅适用于您自己的贴文）。 + type: boolean + x-go-name: Pinned + poll: + $ref: '#/definitions/poll' + reblog: + $ref: '#/definitions/statusReblogged' + reblogged: + description: 此贴文已被查看它的账户转发。 + type: boolean + x-go-name: Reblogged + reblogs_count: + description: 此贴文被转发的次数，数据来源于本站实例。 + format: int64 + type: integer + x-go-name: ReblogsCount + replies_count: + description: 此贴文的回复数，数据来源于本站实例。 + format: int64 + type: integer + x-go-name: RepliesCount + sensitive: + description: 贴文包含敏感内容。 + example: false + type: boolean + x-go-name: Sensitive + spoiler_text: + description: 此贴文的主题、摘要或内容警告。 + example: NSFW + type: string + x-go-name: SpoilerText + tags: + description: 此贴文内容中使用的话题标签。 + items: + $ref: '#/definitions/tag' + type: array + x-go-name: Tags + text: + description: |- + 此贴文的纯文本内容。当贴文被删除时返回，以便用户可以从源文本重新起草，而无需客户端从 HTML 内容中逆向出原始文本。 + type: string + x-go-name: Text + uri: + description: 此贴文的 ActivityPub URI。等同于贴文的 activitypub ID。 + example: https://example.org/users/some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: URI + url: + description: 此贴文的公开 Web URL。仅当贴文的可见性为 'public' 时，此链接才有效。 + example: https://example.org/@some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: URL + visibility: + description: 此贴文的可见性。 + example: unlisted + type: string + x-go-name: Visibility + title: StatusReblogged + description: StatusReblogged 表示一条被转发的贴文。 + type: object + x-go-name: StatusReblogged + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + statusSource: + description: |- + StatusSource 表示创建贴文时提交给 API 的贴文源文本。 + properties: + id: + description: 贴文的 ID。 + example: 01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: ID + spoiler_text: + description: 贴文折叠提示的纯文本版本。 + type: string + x-go-name: SpoilerText + text: + description: 贴文的源文本。 + type: string + x-go-name: Text + type: object + x-go-name: StatusSource + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + swaggerCollection: + properties: + '@context': + description: |- + ActivityStreams JSON-LD 上下文。 + 字符串或字符串数组，或更复杂的嵌套项。 + example: https://www.w3.org/ns/activitystreams + x-go-name: Context + first: + $ref: '#/definitions/swaggerCollectionPage' + id: + description: ActivityStreams ID. + example: https://example.org/users/some_user/statuses/106717595988259568/replies + type: string + x-go-name: ID + last: + $ref: '#/definitions/swaggerCollectionPage' + type: + description: ActivityStreams 类型。 + example: Collection + type: string + x-go-name: Type + title: SwaggerCollection + description: SwaggerCollection 表示一个 ActivityPub 集合。 + type: object + x-go-name: SwaggerCollection + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/activitypub/users + swaggerCollectionPage: + properties: + id: + description: ActivityStreams ID. + example: https://example.org/users/some_user/statuses/106717595988259568/replies?page=true + type: string + x-go-name: ID + items: + description: 此页面上的条目。 + example: + - https://example.org/users/some_other_user/statuses/086417595981111564 + - https://another.example.com/users/another_user/statuses/01FCN8XDV3YG7B4R42QA6YQZ9R + items: + type: string + type: array + x-go-name: Items + next: + description: 指向下一页的链接。 + example: https://example.org/users/some_user/statuses/106717595988259568/replies?only_other_accounts=true&page=true + type: string + x-go-name: Next + partOf: + description: 此页面所属的集合。 + example: https://example.org/users/some_user/statuses/106717595988259568/replies + type: string + x-go-name: PartOf + type: + description: ActivityStreams 类型。 + example: CollectionPage + type: string + x-go-name: Type + title: SwaggerCollectionPage + description: SwaggerCollectionPage 表示一个 ActivityPub 集合的一页。 + type: object + x-go-name: SwaggerCollectionPage + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/activitypub/users + swaggerFeaturedCollection: + properties: + '@context': + description: |- + ActivityStreams JSON-LD 上下文。 + 字符串或字符串数组，或更复杂的嵌套项。 + example: https://www.w3.org/ns/activitystreams + x-go-name: Context + TotalItems: + description: 此集合中的项目数。 + example: 2 + format: int64 + type: integer + id: + description: ActivityStreams ID. + example: https://example.org/users/some_user/collections/featured + type: string + x-go-name: ID + items: + description: 贴文 URI 的列表。 + example: + - https://example.org/users/some_user/statuses/01GSZ0F7Q8SJKNRF777GJD271R + - https://example.org/users/some_user/statuses/01GSZ0G012CBQ7TEKX689S3QRE + items: + type: string + type: array + x-go-name: Items + type: + description: ActivityStreams 类型。 + example: OrderedCollection + type: string + x-go-name: Type + title: SwaggerFeaturedCollection + description: SwaggerFeaturedCollection 表示一个有序 ActivityPub 集合。 + type: object + x-go-name: SwaggerFeaturedCollection + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/activitypub/users + tag: + properties: + following: + description: |- + Following 在当用户关注此标签时为 true，不关注时为 false，如果没有当前认证用户则省略。 + type: boolean + x-go-name: Following + history: + description: |- + 此话题标签的使用历史。 + 目前只是一个存根，如果提供将始终为空数组。 + example: [] + items: {} + type: array + x-go-name: History + name: + description: '此话题标签的名称，不包含 # 符号。' + example: helloworld + type: string + x-go-name: Name + url: + description: 此话题标签的网页链接。 + example: https://example.org/tags/helloworld + type: string + x-go-name: URL + title: Tag + description: Tag 表示贴文内容中使用的某个话题标签。 + type: object + x-go-name: Tag + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + theme: + properties: + description: + description: 此主题面向用户的描述。 + type: string + x-go-name: Description + file_name: + description: 此主题在主题目录中的文件名。 + type: string + x-go-name: FileName + title: + description: 此主题的用户可见标题。 + type: string + x-go-name: Title + title: Theme + description: Theme 表示一个用户可选的预设 CSS 主题。 + type: object + x-go-name: Theme + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + threadContext: + description: |- + ThreadContext 是围绕给定贴文的贴文树/贴文串的抽象模型。 + properties: + ancestors: + description: 此贴文的祖先。 + items: + $ref: '#/definitions/status' + type: array + x-go-name: Ancestors + descendants: + description: 此贴文的后代。 + items: + $ref: '#/definitions/status' + type: array + x-go-name: Descendants + type: object + x-go-name: ThreadContext + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + user: + properties: + admin: + description: 用户为管理员。 + example: false + type: boolean + x-go-name: Admin + approved: + description: 用户已被管理员批准。 + example: true + type: boolean + x-go-name: Approved + confirmation_sent_at: + description: 上次发送“请确认您的电子邮件地址”电子邮件的时间（如果有的话）。 (ISO 8601 Datetime) + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: ConfirmationSentAt + confirmed_at: + description: 用户填写的电子邮件地址被确认的时间，如果有的话。 (ISO 8601 Datetime) + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: ConfirmedAt + created_at: + description: 用户创建时间。 (ISO 8601 Datetime) + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: CreatedAt + disabled: + description: 用户的帐户已被停用。 + example: false + type: boolean + x-go-name: Disabled + email: + description: 用户确认的电子邮件地址（如果用户设置了电子邮件地址）。 + example: someone@example.org + type: string + x-go-name: Email + id: + description: 此用户的数据库 ID。 + example: 01FBVD42CQ3ZEEVMW180SBX03B + type: string + x-go-name: ID + last_emailed_at: + description: 上次给此用户发送电子邮件的时间，如果有的话。 (ISO 8601 Datetime) + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: LastEmailedAt + moderator: + description: 用户为站务/监察员。 + example: false + type: boolean + x-go-name: Moderator + reason: + description: 用户注册原因（如果用户注册时填写了原因)。 + example: Please! Pretty please! + type: string + x-go-name: Reason + reset_password_sent_at: + description: 上次发送“请重置您的密码”电子邮件的时间（如果有的话）。 (ISO 8601 Datetime) + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: ResetPasswordSentAt + unconfirmed_email: + description: 此用户的未确认电子邮件地址（如果用户设置了电子邮件地址）。 + example: someone.else@somewhere.else.example.org + type: string + x-go-name: UnconfirmedEmail + title: User + description: User 是单个用户的相关字段的抽象模型。 + type: object + x-go-name: User + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + wellKnownResponse: + properties: + aliases: + items: + type: string + type: array + x-go-name: Aliases + links: + items: + $ref: '#/definitions/Link' + type: array + x-go-name: Links + subject: + type: string + x-go-name: Subject + title: WellKnownResponse + description: |- + WellKnownResponse 表示对“acct”资源的 webfinger 请求或对 nodeinfo 请求的响应。 + 例如，访问 https://example.org/.well-known/webfinger?resource=acct:some_username@example.org 时将返回一个此类型的响应。 + 参见 https://webfinger.net/ + type: object + x-go-name: WellKnownResponse + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model +host: example.org +info: + contact: + email: admin@gotosocial.org + name: 全体 GotoSocial 开发者 + license: + name: AGPL3 + url: https://www.gnu.org/licenses/agpl-3.0.zh-cn.html + title: GoToSocial Swagger 文档 + version: 0.17.2-SNAPSHOT-8a93300a +paths: + /.well-known/host-meta: + get: + description: '响应 web 主机元数据查询，返回符合规范的 hostmeta 响应。参见: https://www.rfc-editor.org/rfc/rfc6415.html' + operationId: hostMetaGet + produces: + - application/xrd+xml" + responses: + "200": + description: "" + schema: + $ref: '#/definitions/hostmeta' + summary: 获取 host-meta + tags: + - .well-known + /.well-known/nodeinfo: + get: + description: |- + 返回一个 well-known 响应，将调用者重定向到 `/nodeinfo/2.0`。 + 例如: `{"links":[{"rel":"http://nodeinfo.diaspora.software/ns/schema/2.0","href":"http://example.org/nodeinfo/2.0"}]}` + 参见: https://nodeinfo.diaspora.software/protocol.html + operationId: nodeInfoWellKnownGet + produces: + - application/json + responses: + "200": + description: "" + schema: + $ref: '#/definitions/wellKnownResponse' + summary: 获取 nodeinfo + tags: + - .well-known + /.well-known/webfinger: + get: + description: |- + 处理 webfinger 账户查询请求。 + 例如，对 `https://example.org/.well-known/webfinger?resource=acct:admin@example.org` 发送 GET 请求，将返回： + ``` + {"subject":"acct:admin@example.org","aliases":["https://example.org/users/admin","https://example.org/@admin"],"links":[{"rel":"http://webfinger.net/rel/profile-page","type":"text/html","href":"https://example.org/@admin"},{"rel":"self","type":"application/activity+json","href":"https://example.org/users/admin"}]} + ``` + 参见: https://webfinger.net/ + operationId: webfingerGet + produces: + - application/jrd+json + responses: + "200": + description: "" + schema: + $ref: '#/definitions/wellKnownResponse' + summary: Webfinger 账户查询 + tags: + - .well-known + /api/{api_version}/media: + post: + consumes: + - multipart/form-data + operationId: mediaCreate + parameters: + - description: 要使用的 API 版本。必须是 `v1` 或 `v2`。 + in: path + name: api_version + required: true + type: string + - description: 媒体附件的 alt 文本描述。这对于使用屏幕阅读器的用户非常有用！根据您的实例设置，可能需要也可能不需要。 + in: formData + name: description + type: string + - default: 0,0 + description: '媒体附件的焦点。如果存在，它应该是两个介于 -1 和 1 之间的逗号分隔的浮点数。例如：`-0.5,0.25`。' + in: formData + name: focus + type: string + - description: 要上传的媒体附件。 + in: formData + name: file + required: true + type: file + produces: + - application/json + responses: + "200": + description: 新创建的媒体附件。 + schema: + $ref: '#/definitions/attachment' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "422": + description: unprocessable 无法处理 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:media + summary: 上传新附件 + description: 上传新的媒体附件。 + tags: + - media + /api/{api_version}/search: + get: + description: 在本站或其他地方搜索贴文、帐户或话题标签。如果结果中包含贴文，则它们将按时间顺序（最新的在前）返回，带有连续的 ID（更大 = 更新）。 + operationId: searchGet + parameters: + - description: 必须是 `v1` 或 `v2`。如果使用 v1，Hashtag 结果将是字符串切片。如果使用 v2，Hashtag 结果将是 apimodel 标签切片。 + in: path + name: api_version + required: true + type: string + - description: 仅返回 *早于* 给定的 max ID 的项目。当前仅在将 type 设置为特定类型时使用。 + in: query + name: max_id + type: string + - description: 仅返回 *晚于且紧邻* 给定的 min ID 的项目。当前仅在将 type 设置为特定类型时使用。 + in: query + name: min_id + type: string + - default: 20 + description: 要返回的每种项目的数量。 + in: query + maximum: 40 + minimum: 1 + name: limit + type: integer + - default: 0 + description: 要返回的结果的页数（从 0 开始）。该参数目前未使用，请通过选择特定的查询类型并使用 maxID 和 minID 来分页。 + in: query + maximum: 10 + minimum: 0 + name: offset + type: integer + - description: |- + 要搜索的关键词。这可以是以下形式之一： + - `@[username]` -- 搜索任何实例上具有给定用户名的帐户。可以返回多个结果。 + - `@[username]@[domain]` -- 精确匹配给定的用户名和实例域名的外站帐户。最多只会返回 1 个结果。 + - `https://example.org/some/arbitrary/url` -- 搜索具有给定 URL 的账户或贴文。最多只会返回 1 个结果。 + - `#[hashtag_name]` -- 搜索具有给定话题标签名称或以给定话题标签名称开头的话题标签。不区分大小写。可以返回多个结果。 + - 任意字符串 -- 搜索包含给定字符串的帐户或贴文。可以返回多个结果。 + + 任意字符串搜索可以包括以下运算符： + - `from:localuser`，`from:remoteuser@instance.tld`：将结果限制为由指定帐户创建的贴文。 + in: query + name: q + required: true + type: string + - description: |- + 要返回的项目类型。可以是以下之一： + - `` -- 空字符串；返回任何/所有结果。 + - `accounts` -- 仅返回帐户。 + - `statuses` -- 仅返回贴文。 + - `hashtags` -- 仅返回话题标签。 + 如果指定了 `type`，则可以使用 max_id 和 min_id 参数进行分页。 + 如果未指定 `type`，使用 `offset` 参数进行分页。 + in: query + name: type + type: string + - default: false + description: 若搜索关键词是 `@[username]@[domain]` 或 URL，则允许 GoToSocial 实例通过外站调用（webfinger、ActivityPub 等）来解析搜索关键词。 + in: query + name: resolve + type: boolean + - default: false + description: 若搜索类型包括帐户，并且搜索关键词是任意字符串，则仅显示请求帐户关注的帐户。如果设置为 `true`，则 GoToSocial 将在用户名和昵称之外同时检索账户信息来增强搜索。 + in: query + name: following + type: boolean + - default: false + description: 若搜索类型包括话题标签，并且搜索关键词是任意字符串，则排除尚未被实例管理员批准的话题标签。目前此参数未使用。 + in: query + name: exclude_unreviewed + type: boolean + - description: 将搜索范围限制到由指定帐户创建的贴文。 + in: query + name: account_id + type: string + produces: + - application/json + responses: + "200": + description: 搜索结果。 + schema: + $ref: '#/definitions/searchResult' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:search + summary: 搜索 + tags: + - search + /api/v1/accounts: + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + description: |- + 使用应用程序令牌创建新帐户。 + 若 Content-Type 为 `application/json`，则参数也可在请求体中以 JSON 形式给出。 + 若 Content-Type 为 `application/xml`，则参数也可在请求体中以 XML 形式给出。 + operationId: accountCreate + parameters: + - description: 若注册需要手动批准，则此文本将由管理员审核。 + in: query + name: reason + type: string + x-go-name: Reason + - description: 账户设置的用户名。 + in: query + name: username + type: string + x-go-name: Username + - description: 用于登录的电子邮件地址。 + in: query + name: email + type: string + x-go-name: Email + - description: 用于登录的密码。将在存储之前进行哈希处理。 + in: query + name: password + type: string + x-go-name: Password + - description: 用户同意实例的条款、条件和政策。 + in: query + name: agreement + type: boolean + x-go-name: Agreement + - description: 确认邮件的语言。 + in: query + name: locale + type: string + x-go-name: Locale + produces: + - application/json + responses: + "200": + description: 为新创建的帐户提供的 OAuth2 访问令牌。 + schema: + $ref: '#/definitions/oauthToken' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "422": + description: unprocessable 无法处理. 你的帐户创建请求无法处理，因为在过去的 24 小时内在此实例上创建了太多帐户，或者待处理的帐户积压已满。 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Application: + - write:accounts + summary: 创建新帐户 + tags: + - accounts + /api/v1/accounts/{id}: + get: + operationId: accountGet + parameters: + - description: 请求的帐户 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的帐户。 + schema: + $ref: '#/definitions/account' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:accounts + summary: 获取账户详情 + description: 获取具有给定 ID 的帐户的信息。 + tags: + - accounts + /api/v1/accounts/{id}/block: + post: + operationId: accountBlock + parameters: + - description: 要屏蔽的帐户 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 你与帐户的关系(relationship)。 + schema: + $ref: '#/definitions/accountRelationship' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:blocks + summary: 屏蔽帐户 + description: 屏蔽具有给定 ID 的帐户。 + tags: + - accounts + /api/v1/accounts/{id}/follow: + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + description: |- + 关注具有给定 ID 的帐户。 + + 若 Content-Type 为 `application/json`，则参数也可在请求体中以 JSON 形式给出。 + 若 Content-Type 为 `application/xml`，则参数也可在请求体中以 XML 形式给出。 + + 若您已经关注了给定的帐户，则关注(请求)将被更新，不会使用 `reblogs` 和 `notify` 参数。 + operationId: accountFollow + parameters: + - description: 要关注的帐户 ID。 + in: path + name: id + required: true + type: string + - default: true + description: 显示此帐户的转发。 + in: formData + name: reblogs + type: boolean + - default: false + description: 该账户发帖时通知。 + in: formData + name: notify + type: boolean + produces: + - application/json + responses: + "200": + description: 你与此帐户的关系(relationship)。 + schema: + $ref: '#/definitions/accountRelationship' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:follows + summary: 关注帐户 + tags: + - accounts + /api/v1/accounts/{id}/followers: + get: + description: |- + 查看关注此帐户的帐户。 + 下一个/上一个查询可以从返回的 Link 标头中解析。 + 例如： + + ``` + ; rel="next", ; rel="prev" + ``` + 若帐户 `hide_collections` 为 true，且请求帐户 != 目标帐户，则不会返回结果。 + operationId: accountFollowers + parameters: + - description: 帐户 ID。 + in: path + name: id + required: true + type: string + - description: '仅返回早于给定的max ID 的粉丝帐户。具有指定 ID 的粉丝帐户不会包含在响应中。注意：ID 是内部关注的 ID，而不是任何返回的帐户的 ID。' + in: query + name: max_id + type: string + - description: '仅返回晚于给定的 since ID 的粉丝帐户。具有指定 ID 的粉丝帐户不会包含在响应中。注意：ID 是内部关注的 ID，而不是任何返回的帐户的 ID。' + in: query + name: since_id + type: string + - description: '仅返回 *晚于且紧邻* 给定的 min ID 的粉丝帐户。具有指定 ID 的粉丝帐户不会包含在响应中。注意：ID 是内部关注的 ID，而不是任何返回的帐户的 ID。' + in: query + name: min_id + type: string + - default: 40 + description: 要返回的粉丝帐户数量。 + in: query + maximum: 80 + minimum: 1 + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: 一个关注此帐户的帐户的数组。 + headers: + Link: + description: 指向下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/account' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:accounts + summary: 查看粉丝 + tags: + - accounts + /api/v1/accounts/{id}/following: + get: + description: |- + 查询此ID对应的帐户关注的帐户。 + 下一个/上一个查询可以从返回的 Link 标头中解析。 + 示例: + ``` + ; rel="next", ; rel="prev" + ``` + 若帐户 `hide_collections` 为 true，且请求帐户 != 目标帐户，则不会返回结果。 + operationId: accountFollowing + parameters: + - description: Account ID. + in: path + name: id + required: true + type: string + - description: '仅返回早于给定的 max ID 的关注帐户。具有指定 ID 的关注帐户不会包含在响应中。注意：ID 是内部关注的 ID，而不是任何返回的帐户的 ID。' + in: query + name: max_id + type: string + - description: '仅返回晚于给定的 since ID 的关注帐户。具有指定 ID 的关注帐户不会包含在响应中。注意：ID 是内部关注的 ID，而不是任何返回的帐户的 ID。' + in: query + name: since_id + type: string + - description: '仅返回 *晚于且紧邻* 给定的 min ID 的关注帐户。具有指定 ID 的关注帐户不会包含在响应中。注意：ID 是内部关注的 ID，而不是任何返回的帐户的 ID。' + in: query + name: min_id + type: string + - default: 40 + description: 要返回的关注帐户数量。 + in: query + maximum: 80 + minimum: 1 + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: 此账户关注的账户数组。 + headers: + Link: + description: 指向下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/account' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:accounts + summary: 查看关注 + tags: + - accounts + /api/v1/accounts/{id}/lists: + get: + operationId: accountLists + parameters: + - description: 账户 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 一个包含此帐户的所有列表的数组。 + schema: + items: + $ref: '#/definitions/list' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:lists + summary: 查看列表 + description: 查看你的列表中包含此帐户的所有列表。 + tags: + - accounts + /api/v1/accounts/{id}/mute: + post: + description: 根据 ID 静音/隐藏帐户。若此账户已被静音/隐藏，则无论如何都会成功。这可以用来更新静音/隐藏的细节。 + operationId: accountMute + parameters: + - description: 要静音/隐藏的帐户 ID。 + in: path + name: id + required: true + type: string + - default: false + description: 在静音/隐藏贴文的同时也静音/隐藏通知。 + in: formData + name: notifications + type: boolean + - default: 0 + description: 静音/隐藏持续时间，以秒为单位。如果为 0 或未提供，则静音/隐藏持续时间无限。 + in: formData + name: duration + type: number + produces: + - application/json + responses: + "200": + description: 你与此帐户的关系(relationship)。 + schema: + $ref: '#/definitions/accountRelationship' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: 禁止对已迁移的账户设置静音/隐藏 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:mutes + summary: 静音/隐藏帐户 + tags: + - accounts + /api/v1/accounts/{id}/note: + post: + consumes: + - multipart/form-data + operationId: accountNote + parameters: + - description: 备注要添加到的帐户的 ID。 + in: path + name: id + required: true + type: string + - default: "" + description: 备注的文本。省略此参数或发送空字符串以清除备注。 + in: formData + name: comment + type: string + produces: + - application/json + responses: + "200": + description: 你与此账户的关系(relationship)。 + schema: + $ref: '#/definitions/accountRelationship' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:accounts + summary: 设置备注 + description: 为具有给定 ID 的帐户设置私人备注。 + tags: + - accounts + /api/v1/accounts/{id}/statuses: + get: + description: 查看指定账户的贴文。贴文将按时间顺序（最新的在前）返回，带有连续的 ID（更大 = 更新）。 + operationId: accountStatuses + parameters: + - description: 账户 ID。 + in: path + name: id + required: true + type: string + - default: 30 + description: 要返回的贴文数量。 + in: query + name: limit + type: integer + - default: false + description: 排除回复。 + in: query + name: exclude_replies + type: boolean + - default: false + description: 排除转发。 + in: query + name: exclude_reblogs + type: boolean + - description: 仅返回 *早于* 给定的 max status ID 的项目。当前仅在将 type 设置为特定类型时使用。 + in: query + name: max_id + type: string + - description: 仅返回 *晚于* 给定的 min status ID 的项目。当前仅在将 type 设置为特定类型时使用。 + in: query + name: min_id + type: string + - default: false + description: 仅显示置顶的贴文。即排除未置顶到给定帐户 ID 的贴文。 + in: query + name: pinned + type: boolean + - default: false + description: 仅显示带有媒体附件的贴文。 + in: query + name: only_media + type: boolean + - default: false + description: 仅显示具有“公开”可见性的贴文。 + in: query + name: only_public + type: boolean + produces: + - application/json + responses: + "200": + description: 贴文的数组。 + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/status' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:accounts + summary: 查看贴文 + tags: + - accounts + /api/v1/accounts/{id}/unblock: + post: + operationId: accountUnblock + parameters: + - description: 要解除屏蔽的帐户 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 你与此账户的关系(relationship)。 + schema: + $ref: '#/definitions/accountRelationship' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:blocks + summary: 解除屏蔽账户 + description: 解除对给定 ID 的帐户的屏蔽。 + tags: + - accounts + /api/v1/accounts/{id}/unfollow: + post: + operationId: accountUnfollow + parameters: + - description: 要取消关注的帐户 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 你与此账户的关系(relationship)。 + schema: + $ref: '#/definitions/accountRelationship' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:follows + summary: 取关账户 + description: 取消关注具有给定 ID 的帐户。 + tags: + - accounts + /api/v1/accounts/{id}/unmute: + post: + description: 解除对给定 ID 的帐户的静音/隐藏。若账户已被解除静音/隐藏，则无论如何都会成功。 + operationId: accountUnmute + parameters: + - description: 要解除静音/隐藏的帐户 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 你与此账户的关系(relationship)。 + schema: + $ref: '#/definitions/accountRelationship' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:mutes + summary: 取消静音/隐藏账户 + tags: + - accounts + /api/v1/accounts/alias: + post: + consumes: + - multipart/form-data + description: |- + 通过将 alsoKnownAs 设置为给定的 URI，将此账户设置为另一个账户的别名。 + + 在需要将其它账户迁移到此账户时很有用。 + + 在这种情况下，你应该将此账户的 alsoKnownAs 设置为要发起迁移的账户的 URI。 + operationId: accountAlias + parameters: + - description: |- + 要设为别名的账户的 ActivityPub URI/ID。例如，`["https://example.org/users/some_account"]`。 + 使用空数组也可以清除 alsoKnownAs，清除账户别名。 + in: formData + name: also_known_as_uris + required: true + type: string + responses: + "200": + description: 更新后的账户。 + schema: + $ref: '#/definitions/account' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "422": + description: unprocessable 无法处理。请查看响应正文以获取更多详细信息。 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:accounts + summary: 设置账户别名 + tags: + - accounts + /api/v1/accounts/delete: + post: + consumes: + - multipart/form-data + operationId: accountDelete + parameters: + - description: 账户的密码，用于确认。 + in: formData + name: password + required: true + type: string + responses: + "202": + description: 账户删除请求已被接受，账户将被删除。 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:accounts + summary: 删除账户 + tags: + - accounts + /api/v1/accounts/lookup: + get: + operationId: accountLookupGet + parameters: + - description: 要查询的用户名或 Webfinger 地址。 + in: query + name: acct + required: true + type: string + produces: + - application/json + responses: + "200": + description: 查询结果。 + schema: + $ref: '#/definitions/account' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:accounts + summary: 快速查找账户 + description: 快速查找用户名以查看其是否可用，跳过 WebFinger 解析。 + tags: + - accounts + /api/v1/accounts/move: + post: + consumes: + - multipart/form-data + operationId: accountMove + parameters: + - description: 账户的密码，用于确认。 + in: formData + name: password + required: true + type: string + - description: 目标账户的 ActivityPub URI/ID。例如，`https://example.org/users/some_account`。目标账户必须也是请求账户的 alsoKnownAs，才能成功迁移。 + in: formData + name: moved_to_uri + required: true + type: string + responses: + "202": + description: 账户迁移请求已被接受，账户将被迁移。 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "422": + description: unprocessable 无法处理。请查看响应正文以获取更多详细信息。 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:accounts + summary: 迁出账户 + description: 将此账户迁移到另一个账户。 + tags: + - accounts + /api/v1/accounts/relationships: + get: + operationId: accountRelationships + parameters: + - collectionFormat: multi + description: 账户 ID。 + in: query + items: + type: string + name: id[] + required: true + type: array + produces: + - application/json + responses: + "200": + description: 账户关系(relationship)的数组。 + schema: + items: + $ref: '#/definitions/accountRelationship' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:accounts + summary: 查询账户关系 + description: 查看你的账户与给定账户 ID 的关系。 + tags: + - accounts + /api/v1/accounts/search: + get: + operationId: accountSearchGet + parameters: + - default: 40 + description: 要返回的结果数量。 + in: query + maximum: 80 + minimum: 1 + name: limit + type: integer + - default: 0 + description: 要返回的结果所在的页数（从 0 开始）。此参数目前未使用，偏移量大于 0 将始终返回 0 个结果。 + in: query + maximum: 10 + minimum: 0 + name: offset + type: integer + - description: |- + 要查找的关键词。可以是以下形式之一： + - `@[username]` -- 在任何实例上搜索具有给定用户名的帐户。可以返回多个结果。 + - `@[username]@[domain]` -- 搜索确切的用户名和域名的外站帐户。最多只返回 1 个结果。 + - 任意字符串 -- 搜索用户名或昵称中包含给定字符串的帐户。可以返回多个结果。 + in: query + name: q + required: true + type: string + - default: false + description: 若关键词为 `@[username]@[domain]` 或 URL，允许 GoToSocial 实例通过调用外站实例（webfinger、ActivityPub 等）来解析搜索。 + in: query + name: resolve + type: boolean + - default: false + description: 只显示发起请求的账户关注的账户。如果设置为 `true`，则 GoToSocial 实例将在用户名和昵称之外，同时在账户信息中发起搜索，来增强搜索结果。 + in: query + name: following + type: boolean + produces: + - application/json + responses: + "200": + description: 搜索结果。 + schema: + items: + $ref: '#/definitions/account' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:accounts + summary: 搜索账户 + description: 搜索具有给定用户名或昵称的帐户。 + tags: + - accounts + /api/v1/accounts/themes: + get: + operationId: accountThemes + produces: + - application/json + responses: + "200": + description: 主题的数组。 + schema: + items: + $ref: '#/definitions/theme' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:accounts + summary: 查看主题 + description: 查看此实例上可用于账户的预设 CSS 主题。 + tags: + - accounts + /api/v1/accounts/update_credentials: + patch: + consumes: + - multipart/form-data + - application/x-www-form-urlencoded + - application/json + operationId: accountUpdate + parameters: + - description: 账户是否可被发现，并在用户名录中显示。 + in: formData + name: discoverable + type: boolean + - description: 账户被标记为机器人。 + in: formData + name: bot + type: boolean + - allowEmptyValue: true + description: 账户的昵称。 + in: formData + name: display_name + type: string + - allowEmptyValue: true + description: 账户的简介。 + in: formData + name: note + type: string + - description: 账户的头像。 + in: formData + name: avatar + type: file + - allowEmptyValue: true + description: 账户的头像描述，用于 alt 文本。 + in: formData + name: avatar_description + type: string + - description: 用户的资料页横幅背景。 + in: formData + name: header + type: file + - allowEmptyValue: true + description: 用户资料页横幅背景的描述，用于 alt 文本。 + in: formData + name: header_description + type: string + - description: 关注请求需要手动批准。 + in: formData + name: locked + type: boolean + - description: 撰写的贴文的默认可见性。 + in: formData + name: source[privacy] + type: string + - description: 将撰写的贴文默认标记为敏感。 + in: formData + name: source[sensitive] + type: boolean + - description: 撰写的贴文的默认语言 (ISO 6391)。 + in: formData + name: source[language] + type: string + - description: 撰写的贴文的默认内容类型 (text/plain 或 text/markdown)。 + in: formData + name: source[status_content_type] + type: string + - description: 渲染此帐户的资料页或贴文时要使用的主题的文件名。主题必须存在于此服务器上，如 /api/v1/accounts/themes 所示。空字符串意味着取消主题偏好并回退到 GoToSocial 默认主题。 + in: formData + name: theme + type: string + - description: 渲染此帐户的资料页或贴文时要使用的自定义 CSS。字符串长度不能超过 5,000 个字符（~5kb）。 + in: formData + name: custom_css + type: string + - description: 为此帐户的公开贴文启用 RSS 订阅，端点为 `/[username]/feed.rss`。 + in: formData + name: enable_rss + type: boolean + - description: 隐藏此帐户的关注/粉丝信息。 + in: formData + name: hide_collections + type: boolean + - description: |- + Posts to show on the web view of the account. + "public": default, show only Public visibility posts on the web. + "unlisted": show Public *和* Unlisted visibility posts on the web. + "none": show no posts on the web, not even Public ones. + 要在网页端展示的贴文范围。 + "public": 默认，只在网页上显示公开的贴文。 + "unlisted": 在网页上显示可见性为公开 *和* 不列出的贴文。 + "none": 在网页上不显示任何贴文，甚至不显示公开的贴文。 + in: formData + name: web_visibility + type: string + - description: 要添加到此帐户的资料页的第一个资料字段的名称。 （索引可以是任何字符串；添加更多索引以发送更多字段。） + in: formData + name: fields_attributes[0][name] + type: string + - description: 要添加到此帐户的资料页的第一个资料字段的值。 （索引可以是任何字符串；添加更多索引以发送更多字段。） + in: formData + name: fields_attributes[0][value] + type: string + - description: 要添加到此帐户的资料页的第二个资料字段的名称。 + in: formData + name: fields_attributes[1][name] + type: string + - description: 要添加到此帐户的资料页的第二个资料字段的值。 + in: formData + name: fields_attributes[1][value] + type: string + - description: 要添加到此帐户的资料页的第三个资料字段的名称。 + in: formData + name: fields_attributes[2][name] + type: string + - description: 要添加到此帐户的资料页的第三个资料字段的值。 + in: formData + name: fields_attributes[2][value] + type: string + - description: 要添加到此帐户的资料页的第四个资料字段的名称。 + in: formData + name: fields_attributes[3][name] + type: string + - description: 要添加到此帐户的资料页的第四个资料字段的值。 + in: formData + name: fields_attributes[3][value] + type: string + - description: 要添加到此帐户的资料页的第五个资料字段的名称。 + in: formData + name: fields_attributes[4][name] + type: string + - description: 要添加到此帐户的资料页的第五个资料字段的值。 + in: formData + name: fields_attributes[4][value] + type: string + - description: 要添加到此帐户的资料页的第六个资料字段的名称。 + in: formData + name: fields_attributes[5][name] + type: string + - description: 要添加到此帐户的资料页的第六个资料字段的值。 + in: formData + name: fields_attributes[5][value] + type: string + produces: + - application/json + responses: + "200": + description: 更新后的账户。 + schema: + $ref: '#/definitions/account' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:accounts + summary: 更新账户信息 + description: 更新你的账户信息。 + tags: + - accounts + /api/v1/accounts/verify_credentials: + get: + operationId: accountVerify + produces: + - application/json + responses: + "200": + description: "" + schema: + $ref: '#/definitions/account' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:accounts + summary: 验证令牌 + description: 验证令牌并返回与之相关的账户详细信息。 + tags: + - accounts + /api/v1/admin/accounts: + get: + description: |- + 使用特定的过滤规则查看 + 分页浏览已知的账户。 + + 返回的账户将按域名 + 用户名的字母顺序（a-z）排序。 + + 下一个和上一个查询可以从返回的 Link 标头中解析出来。 + 例如： + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: adminAccountsGetV1 + parameters: + - default: false + description: 只显示本站账户的过滤规则。 + in: query + name: local + type: boolean + - default: false + description: 只显示外站账户的过滤规则。 + in: query + name: remote + type: boolean + - default: false + description: 只显示当前活跃的账户的过滤规则。 + in: query + name: active + type: boolean + - default: false + description: 只显示当前待处理的账户的过滤规则。 + in: query + name: pending + type: boolean + - default: false + description: 只显示当前被禁用的账户的过滤规则。 + in: query + name: disabled + type: boolean + - default: false + description: 只显示当前被静音的账户的过滤规则。 + in: query + name: silenced + type: boolean + - default: false + description: 只显示当前被封禁的账户的过滤规则。 + in: query + name: suspended + type: boolean + - default: false + description: 只显示当前被强制标记为敏感的账户的过滤规则。 + in: query + name: sensitized + type: boolean + - description: 搜索给定的用户名。 + in: query + name: username + type: string + - description: 搜索给定的昵称。 + in: query + name: display_name + type: string + - description: 搜索给定的域名。 + in: query + name: by_domain + type: string + - description: 搜索具有给定电子邮箱的用户。 + in: query + name: email + type: string + - description: 搜索具有给定 IP 地址的用户。 + in: query + name: ip + type: string + - default: false + description: 搜索工作人员账户。 + in: query + name: staff + type: boolean + - description: "`[domain]/@[username]` 中的 `max_id`。返回的所有结果都将在 `[domain]/@[username]` 之后的字母顺序中。例如，如果 `max_id` = `example.org/@someone`，则返回的条目可能包含 `example.org/@someone_else`、`later.example.org/@someone` 等。在此形式中，本站帐户 ID 使用空字符串作为 `[domain]` 部分，例如具有用户名 `someone` 的本地帐户将是 `/@someone`。" + in: query + name: max_id + type: string + - description: "`[domain]/@[username]` 中的 `min_id`。返回的所有结果都将在 `[domain]/@[username]` 之前的字母顺序中。例如，如果 `min_id` = `example.org/@someone`，则返回的条目可能包含 `example.org/@earlier_account`、`earlier.example.org/@someone` 等。在此形式中，本站帐户 ID 使用空字符串作为 `[domain]` 部分，例如具有用户名 `someone` 的本地帐户将是 `/@someone`。" + in: query + name: min_id + type: string + - default: 50 + description: 要返回的最大结果数。 + in: query + maximum: 200 + minimum: 1 + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: "" + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/adminAccountInfo' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 查看账户 + tags: + - admin + /api/v1/admin/accounts/{id}: + get: + operationId: adminAccountGet + parameters: + - description: 账户的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/adminAccountInfo' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 查看单个账户 + description: 查看一个账户。 + tags: + - admin + /api/v1/admin/accounts/{id}/action: + post: + consumes: + - multipart/form-data + operationId: adminAccountAction + parameters: + - description: 账户的 ID。 + in: path + name: id + required: true + type: string + - description: 要执行的操作类型，目前仅支持 `suspend`。 + in: formData + name: type + required: true + type: string + - description: 描述执行此操作的原因的文本，可不填。 + in: formData + name: text + type: string + produces: + - application/json + responses: + "200": + description: OK + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "409": + description: '冲突: 已经有一个与此操作冲突的管理员操作正在执行。查看响应正文中的错误消息以获取更多信息。这是一个临时错误; 如果稍后再试一次，应该可以处理此操作。' + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 执行管理操作 + description: 对某个账户执行管理员操作。 + tags: + - admin + /api/v1/admin/accounts/{id}/approve: + post: + operationId: adminAccountApprove + parameters: + - description: 账户的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 被批准后的账户。 + schema: + $ref: '#/definitions/adminAccountInfo' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 批准账户 + description: 批准待处理的账户。 + tags: + - admin + /api/v1/admin/accounts/{id}/reject: + post: + operationId: adminAccountReject + parameters: + - description: 账户的 ID。 + in: path + name: id + required: true + type: string + - description: 用于说明为什么拒绝此账户的评论。评论仅对管理员可见。 + in: formData + name: private_comment + type: string + - description: 要包含在发送给申请人的电子邮件中的消息。仅在 send_email 为 true 时包含。 + in: formData + name: message + type: string + - description: 向申请人发送一封电子邮件，告知他们的注册已被拒绝。 + in: formData + name: send_email + type: boolean + produces: + - application/json + responses: + "200": + description: 被拒绝的账户。 + schema: + $ref: '#/definitions/adminAccountInfo' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 拒绝账户 + description: 拒绝待处理的账户。 + tags: + - admin + /api/v1/admin/custom_emojis: + get: + description: |- + 下一个/上一个查询可以从返回的 Link 标头中解析。 + 例如： + + `; rel="next", ; rel="prev"` + operationId: emojisGet + parameters: + - default: domain:all + description: |- + 查看本站表情和已知的外站表情。 + + 要应用到结果中的过滤规则列表，以逗号分隔。可被识别的过滤规则有： + + `domain:[domain]` -- 显示给定域名下的表情，例如 `?filter=domain:example.org` 将只显示 `example.org` 的表情。 + 除了给定特定域名外，还可以给出关键字 `local` 或 `all`，以仅显示本站表情 (`domain:local`) 或显示所有实例的所有表情 (`domain:all`)。 + 注意：`domain:*` 等同于 `domain:all`（包括本站）。 + 如果未提供域名过滤规则，则将假定 `domain:all`。 + + `disabled` -- 包括已禁用的表情。 + + `enabled` -- 包括已启用的表情。 + + `shortcode:[shortcode]` -- 仅显示给定的表情代码，例如 `?filter=shortcode:blob_cat_uwu` 将仅显示表情代码为 `blob_cat_uwu` 的表情（区分大小写）。 + + 如果未提供 `disabled` 或 `enabled`，则将同时显示已禁用和已启用的表情。 + + 如果未提供过滤规则，则将使用默认的 `domain:all`，它将显示所有实例的所有表情。 + in: query + name: filter + type: string + - default: 50 + description: 要返回的表情数量。小于 1 或未设置表示无限制（所有表情）。 + in: query + maximum: 200 + minimum: 0 + name: limit + type: integer + - description: |- + 只返回比给定 `[shortcode]@[domain]` *更低*（按字母顺序）的表情。例如，如果 `max_shortcode_domain=beep@example.org`，则返回的值可能包括 `[shortcode]@[domain]` 为 `car@example.org`, `debian@aaa.com`, `test@` (本站表情) 等。 + 具有给定 `[shortcode]@[domain]` 的表情将不包含在结果集中。 + in: query + name: max_shortcode_domain + type: string + - description: |- + 只返回比给定 `[shortcode]@[domain]` *更高*（按字母顺序）的表情。例如，如果 `max_shortcode_domain=beep@example.org`, 则返回的值可能包括 `[shortcode]@[domain]` 为 `arse@test.com`, `0101_binary@hackers.net`, `bee@` (本站表情) 等。 + 具有给定 `[shortcode]@[domain]` 的表情将不包含在结果集中。 + in: query + name: min_shortcode_domain + type: string + produces: + - application/json + responses: + "200": + description: 表情数组，按表情代码和域名字母顺序排列。 + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/adminEmoji' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + summary: 查看表情 + tags: + - admin + post: + consumes: + - multipart/form-data + operationId: emojiCreate + parameters: + - description: 此表情的代码，将被实例居民用于选定对应表情。此代码在实例上必须是唯一的。 + in: formData + name: shortcode + pattern: \w{2,30} + required: true + type: string + - description: 此表情的 png 或 gif 图像。动画 png 也可以！为了确保与其他 fedi 实现的兼容性，默认情况下表情大小限制为 50kb。 + in: formData + name: image + required: true + type: file + - description: 此表情所属的类别。如果留空，表情将不属于任何类别。如果给定的类别名称尚不存在，则将创建该类别。 + in: formData + name: category + type: string + produces: + - application/json + responses: + "200": + description: 新创建的表情。 + schema: + $ref: '#/definitions/emoji' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "409": + description: 冲突 -- 此表情的代码已被使用 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 创建表情 + description: 上传和创建一个新的实例表情。 + tags: + - admin + /api/v1/admin/custom_emojis/{id}: + delete: + description: |- + 在此实例删除一个 **本地** 表情。 + + 给定 ID 的表情将不再在此实例上可用。 + + 如果您只想更新表情图像，请使用 `/api/v1/admin/custom_emojis/{id}` PATCH 路由。 + + 要禁用 **外站** 实例的表情，请使用 `/api/v1/admin/custom_emojis/{id}` PATCH 路由。 + operationId: emojiDelete + parameters: + - description: 表情的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 被删除的表情将被返回给调用者，以便进一步处理。 + schema: + $ref: '#/definitions/adminEmoji' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 删除表情 + tags: + - admin + get: + operationId: emojiGet + parameters: + - description: 表情的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 单个表情。 + schema: + $ref: '#/definitions/adminEmoji' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + summary: 查看表情 + description: 在管理视图中查看单个表情。 + tags: + - admin + patch: + consumes: + - multipart/form-data + description: |- + 对一个 **本站** 或 **外站** 表情执行管理操作。 + + 要执行的操作取决于提供的操作类型 `type` 参数。 + + `disable`: 禁用一个 **外站** 表情，使其无法在此实例上使用/显示。不适用于本站表情。 + + `copy`: 将 **外站** 表情复制到此实例。执行此操作时，必须提供一个表情代码，并且它必须在此实例上已有的表情中是唯一的。可以提供一个类别，然后复制的表情将被放入提供的类别中。 + + `modify`: 修改一个 **本站** 表情。您可以为表情提供一个新的图像和/或更新类别。 + + 本站表情不能使用此端点删除。要删除本站表情，请查看 DELETE /api/v1/admin/custom_emojis/{id}。 + operationId: emojiUpdate + parameters: + - description: 表情的 ID。 + in: path + name: id + required: true + type: string + - description: |- + 要执行的操作类型。需为下列其中之一：(`disable`, `copy`, `modify`)。 + 对于 **外站** 表情，支持 `copy` 或 `disable`。 + 对于 **本站** 表情，仅支持 `modify`。 + enum: + - copy + - disable + - modify + in: formData + name: type + required: true + type: string + - description: 用于表情的代码，将被实例居民用于选定表情。此代码在实例上必须是唯一的。仅适用于 `copy` 操作类型。 + in: formData + name: shortcode + pattern: \w{2,30} + type: string + - description: 此表情的新 png 或 gif 图像。动画 png 也可以！为了确保与其他 fedi 实现的兼容性，默认情况下表情大小限制为 50kb。仅适用于 **本站** 表情。 + in: formData + name: image + type: file + - description: 表情所属的类别。如果尚不存在具有给定名称的类别，则将创建该类别。仅适用于 `copy` 和 `modify` 操作类型。 + in: formData + name: category + type: string + produces: + - application/json + responses: + "200": + description: 更新后的表情。 + schema: + $ref: '#/definitions/adminEmoji' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 修改表情 + tags: + - admin + /api/v1/admin/custom_emojis/categories: + get: + operationId: emojiCategoriesGet + produces: + - application/json + responses: + "200": + description: 现有表情类别的数组。 + schema: + items: + $ref: '#/definitions/emojiCategory' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + summary: 查看表情类别 + description: 获取现有表情类别的列表。 + tags: + - admin + /api/v1/admin/debug/apurl: + get: + description: 对指定的 ActivityPub URL 执行 GET 请求，并返回详细的调试信息。仅当 GoToSocial 使用 DEBUG=1 标志构建和运行时才启用/公开。 + operationId: debugAPUrl + parameters: + - description: 要解析的 URL 或 ActivityPub ID。 如 `https://example.org/users/someone` + in: query + name: url + required: true + type: string + produces: + - application/json + responses: + "200": + description: "" + schema: + $ref: '#/definitions/debugAPUrlResponse' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 解析 ActivityPub URL + tags: + - debug + /api/v1/admin/debug/caches/clear: + post: + description: 清除所有内存中的缓存。仅当 GoToSocial 使用 DEBUG=1 标志构建和运行时才启用/公开。 + operationId: debugClearCaches + produces: + - application/json + responses: + "200": + description: 所有缓存都已清除。 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 清除缓存 + tags: + - debug + /api/v1/admin/domain_allows: + get: + operationId: domainAllowsGet + parameters: + - description: 如果设为 `true`，则返回的实例白名单列表中的每个条目将仅包含字段 `domain` 和 `public_comment`。这对于当您想要保存和共享您实例上允许的所有域名的列表时非常有用，以便其他人可以轻松导入它们，但您不希望他们看到您的允许的数据库 ID，或私人评论等。 + in: query + name: export + type: boolean + produces: + - application/json + responses: + "200": + description: 目前所有被允许的域名。 + schema: + items: + $ref: '#/definitions/domainPermission' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 查看实例白名单 + description: 查看当前所有被允许联合的域名。 + tags: + - admin + post: + consumes: + - multipart/form-data + description: |- + 从字符串或文件中创建一个或多个实例白名单。 + + 在使用此端点时，您有两个选项：要么将 `import` 设置为 `true` 并上传一个包含多个要允许的域名的 JSON 文件，要么将 `import` 设置为 `false`，并添加一条要允许的域名。 + + JSON 文件的格式应该类似于：`[{"domain":"example.org"},{"domain":"whatever.com","public_comment":"它们是我的好厚米"}]` + operationId: domainAllowCreate + parameters: + - default: false + description: 表示正在导入一个包含多个要允许的域名的文件。如果设置为 `true`，则 `domains` 必须作为 JSON 格式的文件存在。如果设置为 `false`，则 `domains` 将被忽略，`domain` 必须存在。 + in: query + name: import + type: boolean + - description: JSON 格式的实例白名单列表。仅在 `import` 设置为 `true` 时使用。 + in: formData + name: domains + type: file + - description: 要允许的单个域名。仅在 `import` 不是 `true` 时使用。 + in: formData + name: domain + type: string + - description: 在公开时对域名的名称进行混淆。例如，`example.org` 变成类似于 `ex***e.org`。仅在 `import` 不是 `true` 时使用。 + in: formData + name: obfuscate + type: boolean + - description: 有关此实例白名单的公共评论。如果选择共享允许，则此评论将显示在实例白名单旁边。仅在 `import` 不是 `true` 时使用。 + in: formData + name: public_comment + type: string + - description: 有关此实例白名单的私人评论。仅显示给其他管理员，因此这是一个有用的内部方法，用于跟踪为什么某个域名最终被允许。仅在 `import` 不是 `true` 时使用。 + in: formData + name: private_comment + type: string + produces: + - application/json + responses: + "200": + description: 如果 `import` != `true`，则返回新创建的实例白名单。如果导入了列表，则将返回新创建的实例白名单的 `array` (数组)。 + schema: + $ref: '#/definitions/domainPermission' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "409": + description: '冲突: 已经有一个与此操作冲突的管理员操作正在执行。查看响应正文中的错误消息以获取更多信息。这是一个临时错误; 如果稍后再试一次，应该可以处理此操作。' + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 创建实例白名单 + tags: + - admin + /api/v1/admin/domain_allows/{id}: + delete: + operationId: domainAllowDelete + parameters: + - description: 实例白名单条目的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 刚刚删除的实例白名单条目。 + schema: + $ref: '#/definitions/domainPermission' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "409": + description: '冲突: 已经有一个与此操作冲突的管理员操作正在执行。查看响应正文中的错误消息以获取更多信息。这是一个临时错误; 如果稍后再试一次，应该可以处理此操作。' + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 删除实例白名单条目 + description: 删除具有给定 ID 的实例白名单条目。 + tags: + - admin + get: + operationId: domainAllowGet + parameters: + - description: 实例白名单条目的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的实例白名单条目。 + schema: + $ref: '#/definitions/domainPermission' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 查看实例白名单条目 + description: 查看具有给定 ID 的实例白名单条目。 + tags: + - admin + /api/v1/admin/domain_blocks: + get: + operationId: domainBlocksGet + parameters: + - description: 如果设为 `true`，则返回的实例黑名单的每个条目将仅包含字段 `domain` 和 `public_comment`。这对于当您想要保存和共享您实例上阻止的所有实例的列表时非常有用，以便其他人可以轻松导入它们，但您不希望他们看到您的黑名单的数据库 ID，或私人评论等。 + in: query + name: export + type: boolean + produces: + - application/json + responses: + "200": + description: 目前所有的实例黑名单。 + schema: + items: + $ref: '#/definitions/domainPermission' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 查看实例黑名单 + description: 查看当前所有实例黑名单。 + tags: + - admin + post: + consumes: + - multipart/form-data + description: |- + 从字符串或文件中创建一个或多个实例黑名单条目。 + + 使用此端点时，您有两个选项：要么将 `import` 设置为 `true` 并上传一个包含多个要阻止联合的实例的 JSON 文件，要么将 `import` 设置为 `false`，并添加一个要阻止的实例。 + + JSON 文件的格式应该类似于：`[{"domain":"example.org"},{"domain":"whatever.com","public_comment":"它们不是我的好厚米"}]` + operationId: domainBlockCreate + parameters: + - default: false + description: 表示正在导入一个包含多个要阻止联合的实例的文件。如果设置为 `true`，则 `domains` 必须作为 JSON 格式的文件存在。如果设置为 `false`，则 `domains` 将被忽略，`domain` 必须存在。 + in: query + name: import + type: boolean + - description: 要导入的 JSON 格式的实例黑名单。仅在 `import` 设置为 `true` 时使用。 + in: formData + name: domains + type: file + - description: 单个要阻止联合的实例。仅在 `import` 不是 `true` 时使用。 + in: formData + name: domain + type: string + - description: 对外公开时对域名进行混淆。例如，`example.org` 变成类似于 `ex***e.org`。仅在 `import` 不是 `true` 时使用。 + in: formData + name: obfuscate + type: boolean + - description: 对此实例黑名单条目的公开评论。如果选择共享阻止，此评论将显示在实例黑名单条目旁边。仅在 `import` 不是 `true` 时使用。 + in: formData + name: public_comment + type: string + - description: 对此实例黑名单条目的私人评论。仅显示给其他管理员，因此这是一个有用的内部方法，用于跟踪为什么某个域名最终被阻止。仅在 `import` 不是 `true` 时使用。 + in: formData + name: private_comment + type: string + produces: + - application/json + responses: + "200": + description: 如果 `import` != `true`，则返回新创建的实例黑名单条目。如果导入了列表，则将返回新创建的实例黑名单的 `array` (数组)。 + schema: + $ref: '#/definitions/domainPermission' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "409": + description: '冲突: 已经有一个与此操作冲突的管理员操作正在执行。查看响应正文中的错误消息以获取更多信息。这是一个临时错误; 如果稍后再试一次，应该可以处理此操作。' + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 创建实例黑名单 + tags: + - admin + /api/v1/admin/domain_blocks/{id}: + delete: + operationId: domainBlockDelete + parameters: + - description: 实例黑名单条目的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 刚刚删除的实例黑名单条目。 + schema: + $ref: '#/definitions/domainPermission' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "409": + description: '冲突: 已经有一个与此操作冲突的管理员操作正在执行。查看响应正文中的错误消息以获取更多信息。这是一个临时错误; 如果稍后再试一次，应该可以处理此操作。' + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 删除实例黑名单条目 + description: 删除具有给定 ID 的实例黑名单条目。 + tags: + - admin + get: + operationId: domainBlockGet + parameters: + - description: 实例黑名单条目的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的实例黑名单条目。 + schema: + $ref: '#/definitions/domainPermission' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 查看实例黑名单条目 + description: 查看具有给定 ID 的实例黑名单条目。 + tags: + - admin + /api/v1/admin/domain_keys_expire: + post: + consumes: + - multipart/form-data + description: |- + 将指定域名的所有帐户的缓存公钥强制吊销，这些公钥存储在您的数据库中。 + + 当外站实例不得不轮转其密钥时（出于安全问题、数据泄漏、例行安全程序等原因），此功能非常有用，您的实例无法使用缓存的密钥与其正常通信。以这种方式标记为过期的密钥将在下次由该密钥所有者签名的请求发送到您的实例时进行懒惰重新获取，因此不需要进一步操作即可重新建立与该域的通信。 + + 此端点务必不能用于轮转您自己的密钥，它仅适用于外站实例。 + + 使用此端点来吊销尚未轮转所有密钥的实例的密钥既不会有害，也不会破坏联合，但是毫无意义，会导致不必要的请求执行。 + operationId: domainKeysExpire + parameters: + - description: |- + 要吊销密钥的实例域名。 + 例如：example.org + in: formData + name: domain + type: string + x-go-name: Domain + produces: + - application/json + responses: + "202": + description: 请求已接受并将被处理。检查日志以查看进度/错误。 + schema: + $ref: '#/definitions/adminActionResponse' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "409": + description: '冲突: 已经有一个与此操作冲突的管理员操作正在执行。查看响应正文中的错误消息以获取更多信息。这是一个临时错误; 如果稍后再试一次，应该可以处理此操作。' + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 吊销实例密钥 + tags: + - admin + /api/v1/admin/email/test: + post: + consumes: + - multipart/form-data + description: |- + 向指定的电子邮件地址发送一封通用的测试电子邮件。 + + 这可以用来验证实例的 SMTP 配置，并调试任何潜在问题。 + + 如果 SMTP 连接返回错误，此处理程序将返回代码 422，以指示请求无法处理，并将 SMTP 错误返回给调用者。 + operationId: testEmailSend + parameters: + - description: 要发送测试电子邮件的电子邮件地址。 + in: formData + name: email + required: true + type: string + - description: 要包含在电子邮件中的消息，可不填。 + in: formData + name: message + type: string + produces: + - application/json + responses: + "202": + description: 测试邮件已发送。 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "422": + description: 尝试发件时发生了一个 smtp 错误。检查返回的 json 以获取更多信息。将包含 smtp 错误，以帮助您调试与 smtp 服务器的通信。 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 测试电子邮件 + tags: + - admin + /api/v1/admin/header_allows: + get: + operationId: headerFilterAllowsGet + responses: + "200": + description: 目前所有的标头 "allow" (放行) 过滤规则。 + schema: + items: + $ref: '#/definitions/headerFilter' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 查看标头放行规则 + description: 查看当前所有 "allow" (放行) 过滤规则。 + tags: + - admin + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + description: |- + 创建一条新的 "allow" (放行) HTTP 请求标头过滤规则。 + 若 Content-Type 为 'application/json'，则参数也可以在请求体中以 JSON 形式给出。 + 若 Content-Type 为 'application/xml'，则参数也可以在请求体中以 XML 形式给出。 + operationId: headerFilterAllowCreate + parameters: + - description: 要匹配的 HTTP 标头 (例如 User-Agent)。 + in: formData + name: header + required: true + type: string + x-go-name: Header + - description: 要匹配的标头值的正则表达式。 + in: formData + name: regex + required: true + type: string + x-go-name: Regex + produces: + - application/json + responses: + "200": + description: 新创建的 "allow" (放行) 标头过滤规则。 + schema: + $ref: '#/definitions/headerFilter' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 创建标头放行规则 + tags: + - admin + /api/v1/admin/header_allows/{id}: + delete: + operationId: headerFilterAllowDelete + parameters: + - description: 目标标头过滤规则 ID。 + in: path + name: id + required: true + type: string + responses: + "202": + description: Accepted 已接受 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 删除标头放行规则 + description: 删除具有给定 ID 的 "allow" (放行) 标头过滤规则。 + tags: + - admin + get: + operationId: headerFilterAllowGet + parameters: + - description: 目标标头过滤规则 ID。 + in: path + name: id + required: true + type: string + responses: + "200": + description: 请求的 "allow" (放行) 标头过滤规则。 + schema: + $ref: '#/definitions/headerFilter' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 获取单个标头放行规则 + description: 获取具有给定 ID 的 "allow" (放行) 标头过滤规则。 + tags: + - admin + /api/v1/admin/header_blocks: + get: + operationId: headerFilterBlocksGet + responses: + "200": + description: 目前所有的 "block" (阻止) 标头过滤规则。 + schema: + items: + $ref: '#/definitions/headerFilter' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 查看标头阻止规则 + description: 获取目前所有的 "block" (阻止) 标头过滤规则。 + tags: + - admin + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + description: |- + 创建一条新的 "block" (阻止) HTTP 请求标头过滤规则。 + 若 Content-Type 为 'application/json'，则参数也可以在请求体中以 JSON 形式给出。 + 若 Content-Type 为 'application/xml'，则参数也可以在请求体中以 XML 形式给出。 + operationId: headerFilterBlockCreate + parameters: + - description: 要匹配的 HTTP 标头 (例如 User-Agent)。 + in: formData + name: header + required: true + type: string + x-go-name: Header + - description: 要匹配的标头值的正则表达式。 + in: formData + name: regex + required: true + type: string + x-go-name: Regex + produces: + - application/json + responses: + "200": + description: 新创建的 "block" (阻止) 标头过滤规则。 + schema: + $ref: '#/definitions/headerFilter' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 创建标头阻止规则 + tags: + - admin + /api/v1/admin/header_blocks/{id}: + delete: + operationId: headerFilterBlockDelete + parameters: + - description: 目标标头过滤规则 ID。 + in: path + name: id + required: true + type: string + responses: + "202": + description: Accepted 已接受 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 删除标头阻止规则 + description: 删除具有给定 ID 的 "block" (阻止) 标头过滤规则。 + tags: + - admin + get: + operationId: headerFilterBlockGet + parameters: + - description: 目标标头过滤规则 ID。 + in: path + name: id + required: true + type: string + responses: + "200": + description: 请求的 "block" (阻止) 标头过滤规则。 + schema: + $ref: '#/definitions/headerFilter' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 获取单个标头阻止规则 + description: 获取具有给定 ID 的 "block" (阻止) 标头过滤规则。 + tags: + - admin + /api/v1/admin/instance/rules: + post: + consumes: + - multipart/form-data + operationId: ruleCreate + parameters: + - description: 实例规则的文本内容，纯文本。 + in: formData + name: text + required: true + type: string + x-go-name: Text + produces: + - application/json + responses: + "200": + description: 新创建的实例规则。 + schema: + $ref: '#/definitions/instanceRule' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 创建实例规则 + description: 创建一条新的实例规则。 + tags: + - admin + /api/v1/admin/instance/rules/{id}: + delete: + consumes: + - multipart/form-data + operationId: ruleDelete + parameters: + - description: 要删除的规则的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 被删除的实例规则。 + schema: + $ref: '#/definitions/instanceRule' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 删除实例规则 + description: 删除一条现有的实例规则。 + tags: + - admin + patch: + consumes: + - multipart/form-data + operationId: ruleUpdate + parameters: + - description: 要更新的规则的 ID。 + in: path + name: id + required: true + type: string + x-go-name: ID + - description: 更新的实例规则的文本内容，纯文本。 + in: formData + name: text + required: true + type: string + x-go-name: Text + produces: + - application/json + responses: + "200": + description: 更新后的实例规则。 + schema: + $ref: '#/definitions/instanceRule' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 更新实例规则 + description: 更新一条现有的实例规则。 + tags: + - admin + /api/v1/admin/media_cleanup: + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + description: 删除早于给定日期的外站媒体。也会清理未使用的头像和横幅背景头图，并从存储中删除孤立的项目。 + operationId: mediaCleanup + parameters: + - description: |- + 要保留的外站媒体的天数。本地(Native)值将被视为 0。 + 若未指定值，则将使用服务器配置中的 media-remote-cache-days 的值。 + format: int64 + in: query + name: remote_cache_days + type: integer + x-go-name: RemoteCacheDays + produces: + - application/json + responses: + "200": + description: 返回请求的天数。清理将在请求完成后异步执行。 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 清理媒体 + tags: + - admin + /api/v1/admin/media_refetch: + post: + description: |- + 重新获取数据库中指定但在存储中丢失的媒体。 + 当前，仅包括外站表情。 + 当数据丢失时，您可以使用此端点尝试恢复到工作状态。 + operationId: mediaRefetch + parameters: + - description: 要重新获取媒体的实例。如果为空，则将重新获取所有实例的媒体。 + in: query + name: domain + type: string + produces: + - application/json + responses: + "202": + description: 请求已接受并将被处理。检查日志以查看进度/错误。 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 重新获取媒体 + tags: + - admin + /api/v1/admin/reports: + get: + description: |- + 查看发给管理员的用户举报。 + + 举报将按时间顺序（最新的在前）返回，带有连续的 ID（更大 = 更新）。 + + 下一个和上一个查询可以从返回的Link标头中解析。 + + 例子： + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: adminReports + parameters: + - description: 如果设为 true，则只返回已解决的举报。如果设为 false，则只返回未解决的举报。如果未设置，则不会根据其解决状态过滤举报。 + in: query + name: resolved + type: boolean + - description: 只返回由给定 ID 的账户创建的举报。 + in: query + name: account_id + type: string + - description: 只返回针对给定 ID 的账户的举报。 + in: query + name: target_account_id + type: string + - description: 只返回比给定的 max ID *旧* 的举报（用于向下翻页）。具有指定 ID 的举报不会包含在响应中。 + in: query + name: max_id + type: string + - description: 只返回比给定的 since ID *新* 的举报。具有指定 ID 的举报不会包含在响应中。 + in: query + name: since_id + type: string + - description: 只返回比给定的 min ID 相邻且*更新* 的举报（用于向上翻页）。具有指定 ID 的举报不会包含在响应中。 + in: query + name: min_id + type: string + - default: 20 + description: 要返回的举报数量。 + in: query + maximum: 100 + minimum: 1 + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: 举报数组。 + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/adminReport' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 查看用户举报 + tags: + - admin + /api/v1/admin/reports/{id}: + get: + operationId: adminReportGet + parameters: + - description: 举报的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的举报。 + schema: + $ref: '#/definitions/adminReport' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 查看单个用户举报 + description: 查看具有给定 ID 的用户举报。 + tags: + - admin + /api/v1/admin/reports/{id}/resolve: + post: + consumes: + - application/json + - application/xml + - multipart/form-data + operationId: adminReportResolve + parameters: + - description: 举报的 ID。 + in: path + name: id + required: true + type: string + - description: |- + 管理员对此举报采取的行动的评论，可不填。在将举报标记为已处理之前，提供关于采取的行动（如果有）的解释非常有用。这将对创建举报的用户可见！ + in: formData + name: action_taken_comment + type: string + produces: + - application/json + responses: + "200": + description: 已处理的举报。 + schema: + $ref: '#/definitions/adminReport' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 处理用户举报 + description: 将具有给定 ID 的用户举报标记为已处理。 + tags: + - admin + /api/v1/admin/rules: + get: + description: 查看实例规则及其 ID。实例规则将按顺序返回（按 Order 升序排序）。 + operationId: adminsRuleGet + produces: + - application/json + responses: + "200": + description: 本站实例的所有规则组成的数组。 + schema: + items: + $ref: '#/definitions/instanceRule' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 查看实例规则 + tags: + - admin + /api/v1/admin/rules/{id}: + get: + operationId: adminRuleGet + parameters: + - description: 实例规则的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的规则。 + schema: + $ref: '#/definitions/instanceRule' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 查看单个实例规则 + description: 查看具有给定 ID 的实例规则。 + tags: + - admin + /api/v1/apps: + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + description: |- + 在本实例注册一个新的应用程序。 + 注册的应用程序可用于获取应用程序令牌。 + 然后可以使用此令牌注册新帐户，或（通过用户身份验证）获取访问令牌。 + + 若 Content-Type 为 'application/json'，则参数也可以在请求体中以 JSON 形式给出。 + 若 Content-Type 为 'application/xml'，则参数也可以在请求体中以 XML 形式给出。 + operationId: appCreate + parameters: + - description: 应用程序的名称。 + in: formData + name: client_name + required: true + type: string + x-go-name: ClientName + - description: |- + 用户在授权后应重定向到何处。 + + 若要向用户显示授权代码而不是重定向到网页，请在此参数中使用 `urn:ietf:wg:oauth:2.0:oob`。 + in: formData + name: redirect_uris + required: true + type: string + x-go-name: RedirectURIs + - description: |- + 授权范围，以空格分隔的列表。 + + 如果未提供范围，则默认为 `read`。 + in: formData + name: scopes + type: string + x-go-name: Scopes + - description: 此应用程序的网页 URL（可选）。 + in: formData + name: website + type: string + x-go-name: Website + produces: + - application/json + responses: + "200": + description: 新创建的应用程序。 + schema: + $ref: '#/definitions/application' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + summary: 创建应用程序 + tags: + - apps + /api/v1/blocks: + get: + description: |- + 获取发起请求的账户已屏蔽的账户数组。 + 下一个和上一个查询可以从返回的Link标头中解析。 + 示例： + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: blocksGet + parameters: + - description: '仅返回早于给定的 max ID 的已屏蔽账户。具有指定 ID 的已屏蔽账户不会包含在响应中。注意：ID 是内部屏蔽的 ID，而不是任何返回的账户的 ID。' + in: query + name: max_id + type: string + - description: '仅返回晚于给定的 since ID 的已屏蔽账户。具有指定 ID 的已屏蔽账户不会包含在响应中。注意：ID 是内部屏蔽的 ID，而不是任何返回的账户的 ID。' + in: query + name: since_id + type: string + - description: '仅返回比给定的 min ID *相邻且更新* 的已屏蔽账户。具有指定 ID 的已屏蔽账户不会包含在响应中。注意：ID 是内部屏蔽的 ID，而不是任何返回的账户的 ID。' + in: query + name: min_id + type: string + - default: 40 + description: 要返回的已屏蔽账户数量。 + in: query + maximum: 80 + minimum: 1 + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: "" + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/account' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:blocks + summary: 获取已屏蔽账户 + tags: + - blocks + /api/v1/bookmarks: + get: + description: 获取在本站收藏的贴文的数组。 + operationId: bookmarksGet + parameters: + - default: 30 + description: 要返回的贴文数量。 + in: query + name: limit + type: integer + - description: 仅返回早于给定的收藏 ID 的已收藏贴文。具有相应收藏 ID 的贴文不会包含在响应中。 + in: query + name: max_id + type: string + - description: 仅返回比给定的收藏 ID *新* 的已收藏贴文。具有相应收藏 ID 的贴文不会包含在响应中。 + in: query + name: min_id + type: string + produces: + - application/json + responses: + "200": + description: 已收藏贴文的数组。 + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/status' + type: array + "401": + description: unauthorized 未授权 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:bookmarks + summary: 获取收藏列表 + tags: + - bookmarks + /api/v1/conversation/{id}/read: + post: + operationId: conversationRead + parameters: + - description: 对话的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 更新后的对话。 + schema: + $ref: '#/definitions/conversation' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "422": + description: unprocessable 无法处理 content + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:conversations + summary: 标记对话为已读 + description: 将具有给定 ID 的对话标记为已读。 + tags: + - conversations + /api/v1/conversations: + get: + description: |- + 获取发起请求的账户参与的对话（私信）数组。 + 下一个和上一个查询可以从返回的Link标头中解析。 + 示例： + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: conversationsGet + parameters: + - description: '仅返回最后贴文早于给定的 max ID 的对话。具有相应贴文 ID 的对话不会包含在响应中。注意：ID 是贴文 ID。使用Link标头进行分页。' + in: query + name: max_id + type: string + - description: '仅返回最后贴文晚于给定的 since ID 的对话。具有相应贴文 ID 的对话不会包含在响应中。注意：ID 是贴文 ID。使用Link标头进行分页。' + in: query + name: since_id + type: string + - description: '仅返回最后贴文 **相邻且晚于** 给定的 since ID 的对话。具有相应贴文 ID 的对话不会包含在响应中。注意：ID 是贴文 ID。使用Link标头进行分页。' + in: query + name: min_id + type: string + - default: 40 + description: 要返回的对话数量。 + in: query + maximum: 80 + minimum: 1 + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: "" + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/conversation' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:statuses + summary: 获取对话列表 + tags: + - conversations + /api/v1/conversations/{id}: + delete: + description: |- + 删除具有给定 ID 的单个对话。 + 这不会删除对话包含的实际贴文，也不会阻止参与者稍后从相同的贴文串和参与者创建新对话。 + operationId: conversationDelete + parameters: + - description: 对话的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 对话已删除 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:conversations + summary: 删除对话 + tags: + - conversations + /api/v1/custom_emojis: + get: + operationId: customEmojisGet + produces: + - application/json + responses: + "200": + description: 自定义表情数组。 + schema: + items: + $ref: '#/definitions/emoji' + type: array + "401": + description: unauthorized 未授权 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:custom_emojis + summary: 获取自定义表情 + description: 获取本实例可用的自定义表情数组。 + tags: + - custom_emojis + /api/v1/exports/blocks.csv: + get: + operationId: exportBlocks + produces: + - text/csv + responses: + "200": + description: 你屏蔽的账户的 CSV 文件。 + "401": + description: unauthorized 未授权 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:blocks + summary: 导出屏蔽列表 + description: 导出你屏蔽的账户的 CSV 文件。 + tags: + - import-export + /api/v1/exports/followers.csv: + get: + operationId: exportFollowers + produces: + - text/csv + responses: + "200": + description: 你的粉丝的 CSV 文件。 + "401": + description: unauthorized 未授权 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:follows + summary: 导出粉丝列表 + description: 导出你的粉丝的 CSV 文件。 + tags: + - import-export + /api/v1/exports/following.csv: + get: + operationId: exportFollowing + produces: + - text/csv + responses: + "200": + description: 你关注的账户的 CSV 文件。 + "401": + description: unauthorized 未授权 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:follows + summary: 导出关注列表 + description: 导出你关注的账户的 CSV 文件。 + tags: + - import-export + /api/v1/exports/lists.csv: + get: + operationId: exportLists + produces: + - text/csv + responses: + "200": + description: 列表的 CSV 文件。 + "401": + description: unauthorized 未授权 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:lists + summary: 导出所有列表 + description: 导出你创建的列表的 CSV 文件。 + tags: + - import-export + /api/v1/exports/mutes.csv: + get: + operationId: exportMutes + produces: + - text/csv + responses: + "200": + description: 你屏蔽的账户的 CSV 文件。 + "401": + description: unauthorized 未授权 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:mutes + summary: 导出静音列表 + description: 导出你静音/隐藏的账户的 CSV 文件。 + tags: + - import-export + /api/v1/exports/stats: + get: + operationId: exportStats + produces: + - application/json + responses: + "200": + description: 导出统计信息 + schema: + $ref: '#/definitions/accountExportStats' + "401": + description: unauthorized 未授权 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:account + summary: 查看导出统计信息 + description: 返回对应账户有关可以导出的项目数量的统计信息。 + tags: + - import-export + /api/v1/favourites: + get: + description: |- + 查看发起请求的账户已点赞的贴文数组。 + 下一个和上一个查询可以从返回的Link标头中解析。 + 示例: + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: favouritesGet + parameters: + - default: 20 + description: 要返回的贴文数量。 + in: query + name: limit + type: integer + - description: 仅返回比给定的点赞 ID *旧* 的贴文。具有相应点赞 ID 的贴文不会包含在响应中。 + in: query + name: max_id + type: string + - description: 仅返回比给定的点赞 ID *新* 的贴文。具有相应点赞 ID 的贴文不会包含在响应中。 + in: query + name: min_id + type: string + produces: + - application/json + responses: + "200": + description: "" + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/status' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:favourites + summary: 查看点赞贴文 + tags: + - favourites + /api/v1/featured_tags: + get: + description: '获取你当前在个人资料上展示的所有话题标签的数组。**此端点尚未完全实现**：它将始终返回一个空数组。' + operationId: getFeaturedTags + produces: + - application/json + responses: + "200": + description: "" + schema: + items: + type: object + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:accounts + summary: 获取精选话题标签 + tags: + - tags + /api/v1/filters: + get: + operationId: filtersV1Get + produces: + - application/json + responses: + "200": + description: 请求的过滤规则。 + schema: + items: + $ref: '#/definitions/filterV1' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:filters + summary: 获取V1过滤规则 + description: 获取发起请求的账户的所有过滤规则。 + tags: + - filters + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + operationId: filterV1Post + parameters: + - description: |- + 要过滤的文本。 + + 示例：挂人 + in: formData + maxLength: 40 + minLength: 1 + name: phrase + required: true + type: string + - collectionFormat: multi + description: |- + 此过滤规则要应用的上下文。 + + 示例: home, public + enum: + - home + - notifications + - public + - thread + - account + in: formData + items: + type: string + minItems: 1 + name: context[] + required: true + type: array + uniqueItems: true + - description: |- + 此过滤规则的过期时间（秒）。如果省略，则过滤规则永不过期。 + + 示例：86400 + in: formData + name: expires_in + type: number + - default: false + description: |- + 被命中的条目是否应该从用户的时间线/视图中移除，而不是隐藏？目前不支持。 + + 示例：false + in: formData + name: irreversible + type: boolean + - default: false + description: |- + 此过滤规则是否应考虑单词边界（整词匹配）？ + + 示例：true + in: formData + name: whole_word + type: boolean + produces: + - application/json + responses: + "200": + description: 新过滤规则。 + schema: + $ref: '#/definitions/filterV1' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: 禁止对已迁移的账户执行此操作 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "409": + description: conflict (duplicate keyword) + "422": + description: unprocessable 无法处理 content + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:filters + summary: 创建V1过滤规则 + description: 创建一条新的V1过滤规则。 + tags: + - filters + /api/v1/filters/{id}: + delete: + operationId: filterV1Delete + parameters: + - description: 过滤规则的 ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 过滤规则已删除 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:filters + summary: 删除V1过滤规则 + description: 删除具有给定 ID 的单个过滤规则。 + tags: + - filters + get: + operationId: filterV1Get + parameters: + - description: 过滤规则的 ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的过滤规则。 + schema: + $ref: '#/definitions/filterV1' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:filters + summary: 获取单个V1过滤规则 + description: 获取具有给定 ID 的单个V1过滤规则。 + tags: + - filters + put: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + operationId: filterV1Put + parameters: + - description: 过滤规则的 ID. + in: path + name: id + required: true + type: string + - description: |- + 要过滤的文本。 + + 示例: 挂人 + in: formData + maxLength: 40 + minLength: 1 + name: phrase + required: true + type: string + - collectionFormat: multi + description: |- + 此过滤规则要应用的上下文。 + + 示例: home, public + enum: + - home + - notifications + - public + - thread + - account + in: formData + items: + type: string + minItems: 1 + name: context[] + required: true + type: array + uniqueItems: true + - description: |- + 此过滤规则的过期时间（秒）。如果省略，则过滤规则永不过期。 + + 示例: 86400 + in: formData + name: expires_in + type: number + - default: false + description: |- + 被命中的条目是否应该从用户的时间线/视图中移除，而不是隐藏？目前不支持。 + + 示例: false + in: formData + name: irreversible + type: boolean + - default: false + description: |- + 此过滤规则是否应考虑单词边界（整词匹配）？ + + 示例: true + in: formData + name: whole_word + type: boolean + produces: + - application/json + responses: + "200": + description: 更新后的过滤规则。 + schema: + $ref: '#/definitions/filterV1' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: 禁止对已迁移的账户执行此操作 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "409": + description: conflict (duplicate keyword) + "422": + description: unprocessable 无法处理 content + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:filters + summary: 更新单个V1过滤规则 + description: 更新具有给定 ID 的单个过滤规则。 + tags: + - filters + /api/v1/follow_requests: + get: + description: |- + 获取向你发起关注请求的账户数组。 + 下一个和上一个查询可以从返回的Link标头中解析。 + 示例: + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: getFollowRequests + parameters: + - description: '仅返回比给定的 max ID *旧* 的关注请求账户。具有指定 ID 的关注请求账户不会包含在响应中。注意：ID 是内部关注请求的 ID，而不是任何返回的账户的 ID。' + in: query + name: max_id + type: string + - description: '仅返回比给定的 since ID *新* 的关注请求账户。具有指定 ID 的关注请求账户不会包含在响应中。注意：ID 是内部关注请求的 ID，而不是任何返回的账户的 ID。' + in: query + name: since_id + type: string + - description: '仅返回比给定的 min ID *相邻且更新* 的关注请求账户。具有指定 ID 的关注请求账户不会包含在响应中。注意：ID 是内部关注请求的 ID，而不是任何返回的账户的 ID。' + in: query + name: min_id + type: string + - default: 40 + description: 要返回的关注请求账户数量。 + in: query + maximum: 80 + minimum: 1 + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: "" + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/account' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:follows + summary: 获取关注请求列表 + tags: + - follow_requests + /api/v1/follow_requests/{account_id}/authorize: + post: + description: 接受/批准来自给定账户 ID 的关注请求，并将请求账户放入你的“粉丝”列表。 + operationId: authorizeFollowRequest + parameters: + - description: 要接受的账户的 ID。 + in: path + name: account_id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 你与此账户的关系(relationship)。 + schema: + $ref: '#/definitions/accountRelationship' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:follows + summary: 接受关注请求 + tags: + - follow_requests + /api/v1/follow_requests/{account_id}/reject: + post: + operationId: rejectFollowRequest + parameters: + - description: 要拒绝的账户的 ID。 + in: path + name: account_id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 你与此账户的关系(relationship)。 + schema: + $ref: '#/definitions/accountRelationship' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:follows + summary: 拒绝关注请求 + description: 拒绝来自给定账户 ID 的关注请求。 + tags: + - follow_requests + /api/v1/followed_tags: + get: + operationId: getFollowedTags + parameters: + - description: '仅返回比给定的 max ID *旧* 的已关注话题标签。具有相应 max ID 的已关注话题标签不会包含在响应中。注意：ID 是已关注话题标签的内部 ID，而不是任何返回的话题标签的 ID。' + in: query + name: max_id + type: string + - description: '仅返回比给定的 since ID *新* 的已关注话题标签。具有相应 since ID 的已关注话题标签不会包含在响应中。注意：ID 是已关注话题标签的内部 ID，而不是任何返回的话题标签的 ID。' + in: query + name: since_id + type: string + - description: '仅返回比给定的 min ID *相邻且更新* 的已关注话题标签。具有相应 min ID 的已关注话题标签不会包含在响应中。注意：ID 是已关注话题标签的内部 ID，而不是任何返回的话题标签的 ID。' + in: query + name: min_id + type: string + - default: 100 + description: 要返回的已关注话题标签数量。 + in: query + maximum: 200 + minimum: 1 + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: "" + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/tag' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:follows + summary: 获取已关注话题标签 + description: 获取你当前关注的所有话题标签的数组。 + tags: + - tags + /api/v1/import: + post: + consumes: + - multipart/form-data + description: |- + 将 CSV 数据文件上传到你的账户。 + 这可以用于从 Mastodon 兼容的 CSV 文件迁移数据到 GoToSocial 账户。 + + 上传的数据将异步处理，并且可能不会处理所有条目，具体取决于实例屏蔽、用户级屏蔽、引用账户和状态的网络可用性等。 + operationId: importData + parameters: + - description: 要上传的 CSV 数据文件。 + in: formData + name: data + required: true + type: file + - description: |- + 此数据文件中包含的条目类型： + - `following` - 要关注的账户。 - `blocks` - 要屏蔽的账户。 + in: formData + name: type + required: true + type: string + - default: merge + description: |- + 根据数据文件创建对应的条目时使用的模式： + - `merge` 将数据文件中的条目与现有条目合并。 - `overwrite` 用数据文件中的条目替换现有条目。 + in: formData + name: mode + type: string + produces: + - application/json + responses: + "202": + description: 上传的数据文件已被接受。 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:accounts + summary: 导入数据 + tags: + - import-export + /api/v1/instance: + get: + operationId: instanceGetV1 + produces: + - application/json + responses: + "200": + description: 实例信息 + schema: + $ref: '#/definitions/instanceV1' + "406": + description: not acceptable 不可接受 + "500": + description: internal error + summary: 查看实例信息 + tags: + - instance + patch: + consumes: + - multipart/form-data + description: 更新实例信息和/或上传新的头像/横幅头图。此端点需要实例管理员权限。 + operationId: instanceUpdate + parameters: + - allowEmptyValue: true + description: 实例的标题。 + in: formData + maxLength: 40 + name: title + type: string + - allowEmptyValue: true + description: 联系账户的用户名。这必须是实例管理员的用户名。 + in: formData + name: contact_username + type: string + - allowEmptyValue: true + description: 实例联系邮箱。 + in: formData + name: contact_email + type: string + - allowEmptyValue: true + description: 实例的简短描述。 + in: formData + maxLength: 500 + name: short_description + type: string + - allowEmptyValue: true + description: 实例的详细描述。 + in: formData + maxLength: 5000 + name: description + type: string + - allowEmptyValue: true + description: 实例的条款和条件。 + in: formData + maxLength: 5000 + name: terms + type: string + - description: 实例的缩略图。 + in: formData + name: thumbnail + type: file + - description: 提交的实例缩略图的图像描述。 + in: formData + name: thumbnail_description + type: string + - description: 实例的头部背景横幅。 + in: formData + name: header + type: file + produces: + - application/json + responses: + "200": + description: 更新后的实例信息。 + schema: + $ref: '#/definitions/instanceV1' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 更新实例信息 + tags: + - instance + /api/v1/instance/peers: + get: + operationId: instancePeersGet + parameters: + - default: open + description: |- + 要应用于结果的过滤规则列表，以逗号分隔。可被识别的过滤规则包括： + - `open` -- 包括未被禁止或静音的同伴实例 + - `suspended` -- 包括已被禁止的同伴实例。 + + 如果过滤规则是 `open`，则只会返回未被禁止或静音的实例。 + + 如果过滤规则是 `suspended`，则只会显示已被禁止的实例。 + + 如果过滤规则是 `open,suspended`，则将返回所有已知实例。 + + 如果过滤规则是空字符串或未设置，则将默认为 `open`。 + in: query + name: filter + type: string + produces: + - application/json + responses: + "200": + description: |- + 如果未提供 filter 参数，或 filter 为空，则将返回一个遗留的、与 Mastodon-API 兼容的响应。这将仅包含一个类似 `["example.com", "example.org"]` 的字符串数组，对应于此实例的同伴实例的域名。 + + 如果提供了 filter 参数，则将返回一个对象数组，每个对象都至少包含一个 `domain` 键。 + + 被静音或被禁止的域名还将有一个包含 iso8601 date 格式字符串的 `suspended_at` 或 `silenced_at` 键。如果域名对象不包含这两个键，则它是开放的。在某些情况下，已被禁止的实例可能会被混淆，这意味着它们的一些字母将被 `*` 替换，以使恶意用户更难以针对实例进行骚扰。 + + 无论返回的是扁平响应还是更详细的响应，域名都将按主机名字母顺序排序。 + schema: + items: + $ref: '#/definitions/domain' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + tags: + - instance + /api/v1/instance/rules: + get: + description: 实例规则将按顺序返回（按 Order 升序排序）。 + operationId: rules + produces: + - application/json + responses: + "200": + description: 本站实例的所有规则组成的数组。 + schema: + items: + $ref: '#/definitions/instanceRule' + type: array + "400": + description: bad request 无效请求 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + summary: 查看实例规则(公开) + tags: + - instance + /api/v1/interaction_policies/defaults: + get: + operationId: policiesDefaultsGet + produces: + - application/json + responses: + "200": + description: 一个默认的策略对象，包含每种贴文可见性的互动规则。 + schema: + $ref: '#/definitions/defaultPolicies' + "401": + description: unauthorized 未授权 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:accounts + summary: 获取默认互动规则 + description: 获取你创建的新贴文的默认互动规则。 + tags: + - interaction_policies + patch: + consumes: + - multipart/form-data + - application/x-www-form-urlencoded + - application/json + description: |- + 为你创建的不同可见性级别的新贴文更新默认互动策略。 + + 如果使用表单数据提交，请使用以下范式： + + `VISIBILITY[INTERACTION_TYPE][CONDITION][INDEX]=Value` + + 例如：`public[can_reply][always][0]=author` + + 使用 `curl` 调用时可以为如下形式： + + `curl -F 'public[can_reply][always][0]=author' -F 'public[can_reply][always][1]=followers'` + + 其 JSON 等效形式为： + + `curl -H 'Content-Type: application/json' -d '{"public":{"can_reply":{"always":["author","followers"]}}}'` + + 请求体中未指定的任何可见性级别将被重置为默认值。 + + 例如，在上面的示例中，“public” 将被更新，但“unlisted”、“private” 和“direct” 将被重置为默认值。 + + 服务器将对提交的策略执行一些规范化，以免您提交完全无效的策略。 + operationId: policiesDefaultsUpdate + parameters: + - description: public.can_favourite.always 的第 N 个条目。 + in: formData + name: public[can_favourite][always][0] + type: string + - description: public.can_favourite.with_approval 的第 N 个条目。 + in: formData + name: public[can_favourite][with_approval][0] + type: string + - description: public.can_reply.always 的第 N 个条目。 + in: formData + name: public[can_reply][always][0] + type: string + - description: public.can_reply.with_approval 的第 N 个条目。 + in: formData + name: public[can_reply][with_approval][0] + type: string + - description: public.can_reblog.always 的第 N 个条目。 + in: formData + name: public[can_reblog][always][0] + type: string + - description: public.can_reblog.with_approval 的第 N 个条目。 + in: formData + name: public[can_reblog][with_approval][0] + type: string + - description: unlisted.can_favourite.always 的第 N 个条目。 + in: formData + name: unlisted[can_favourite][always][0] + type: string + - description: unlisted.can_favourite.with_approval 的第 N 个条目。 + in: formData + name: unlisted[can_favourite][with_approval][0] + type: string + - description: unlisted.can_reply.always 的第 N 个条目。 + in: formData + name: unlisted[can_reply][always][0] + type: string + - description: unlisted.can_reply.with_approval 的第 N 个条目。 + in: formData + name: unlisted[can_reply][with_approval][0] + type: string + - description: unlisted.can_reblog.always 的第 N 个条目。 + in: formData + name: unlisted[can_reblog][always][0] + type: string + - description: unlisted.can_reblog.with_approval 的第 N 个条目。 + in: formData + name: unlisted[can_reblog][with_approval][0] + type: string + - description: private.can_favourite.always 的第 N 个条目。 + in: formData + name: private[can_favourite][always][0] + type: string + - description: private.can_favourite.with_approval 的第 N 个条目。 + in: formData + name: private[can_favourite][with_approval][0] + type: string + - description: private.can_reply.always 的第 N 个条目。 + in: formData + name: private[can_reply][always][0] + type: string + - description: private.can_reply.with_approval 的第 N 个条目。 + in: formData + name: private[can_reply][with_approval][0] + type: string + - description: private.can_reblog.always 的第 N 个条目。 + in: formData + name: private[can_reblog][always][0] + type: string + - description: private.can_reblog.with_approval 的第 N 个条目。 + in: formData + name: private[can_reblog][with_approval][0] + type: string + - description: direct.can_favourite.always 的第 N 个条目。 + in: formData + name: direct[can_favourite][always][0] + type: string + - description: direct.can_favourite.with_approval 的第 N 个条目。 + in: formData + name: direct[can_favourite][with_approval][0] + type: string + - description: direct.can_reply.always 的第 N 个条目。 + in: formData + name: direct[can_reply][always][0] + type: string + - description: direct.can_reply.with_approval 的第 N 个条目。 + in: formData + name: direct[can_reply][with_approval][0] + type: string + - description: direct.can_reblog.always 的第 N 个条目。 + in: formData + name: direct[can_reblog][always][0] + type: string + - description: direct.can_reblog.with_approval 的第 N 个条目。 + in: formData + name: direct[can_reblog][with_approval][0] + type: string + produces: + - application/json + responses: + "200": + description: 更新后的默认策略对象，包含每种贴文可见性的互动规则。 + schema: + $ref: '#/definitions/defaultPolicies' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "406": + description: not acceptable 不可接受 + "422": + description: unprocessable 无法处理 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:accounts + summary: 更新默认互动规则 + tags: + - interaction_policies + /api/v1/interaction_requests: + get: + description: |- + 获取其他账户对你的贴文发起的，等待你批准的互动请求的数组。 + ``` + ; rel="next", ; rel="prev" + ```` + operationId: getInteractionRequests + parameters: + - description: 若设置，则只有针对给定 status_id 的互动请求将包含在结果中。 + in: query + name: status_id + type: string + - default: true + description: 如果为 true 或未设置，则将在结果中包含待批准的点赞。favourites, replies 和 reblogs 中至少有一个必须为 true。 + in: query + name: favourites + type: boolean + - default: true + description: 如果为 true 或未设置，则将在结果中包含待批准的回复。favourites, replies 和 reblogs 中至少有一个必须为 true。 + in: query + name: replies + type: boolean + - default: true + description: 如果为 true 或未设置，则将在结果中包含待批准的转发。favourites, replies 和 reblogs 中至少有一个必须为 true。 + in: query + name: reblogs + type: boolean + - description: 仅返回比给定的 max ID *旧* 的互动请求。具有指定 ID 的互动请求不会包含在响应中。 + in: query + name: max_id + type: string + - description: 仅返回比给定的 since ID *新* 的互动请求。具有指定 ID 的互动请求不会包含在响应中。 + in: query + name: since_id + type: string + - description: 仅返回比给定的 min ID *相邻且更新* 的互动请求。具有指定 ID 的互动请求不会包含在响应中。 + in: query + name: min_id + type: string + - default: 40 + description: 要返回的互动请求数量。 + in: query + maximum: 80 + minimum: 1 + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: "" + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/interactionRequest' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:notifications + summary: 获取互动请求列表 + tags: + - interaction_requests + /api/v1/interaction_requests/{id}: + get: + operationId: getInteractionRequest + parameters: + - description: 对你发出的互动请求的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 互动请求。 + schema: + $ref: '#/definitions/interactionRequest' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:notifications + summary: 获取单个互动请求 + description: 获取具有给定 ID 的互动请求。 + tags: + - interaction_requests + /api/v1/interaction_requests/{id}/authorize: + post: + operationId: authorizeInteractionRequest + parameters: + - description: 对你发出的互动请求的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 被批准后的互动请求。 + schema: + $ref: '#/definitions/interactionRequest' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:statuses + summary: 接受互动请求 + description: 接受/授权/批准具有给定 ID 的互动请求。 + tags: + - interaction_requests + /api/v1/interaction_requests/{id}/reject: + post: + operationId: rejectInteractionRequest + parameters: + - description: 对你发出的互动请求的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 被拒绝的互动请求。 + schema: + $ref: '#/definitions/interactionRequest' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:statuses + summary: 拒绝互动请求 + description: 拒绝具有给定 ID 的互动请求。 + tags: + - interaction_requests + /api/v1/lists: + get: + operationId: lists + produces: + - application/json + responses: + "200": + description: 发起请求的用户拥有的所有列表的数组。 + schema: + items: + $ref: '#/definitions/list' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:lists + summary: 获取所有列表 + description: 获取授权用户拥有的所有列表。 + tags: + - lists + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + operationId: listCreate + parameters: + - description: |- + 列表的标题。 + 示例: 大佬 + in: formData + name: title + required: true + type: string + x-go-name: Title + - default: list + description: |- + 此列表的回复策略。 + followed = 显示对任何关注的用户的回复 + list = 显示对列表成员的回复 + none = 不显示回复 + 示例: list + enum: + - followed + - list + - none + in: formData + name: replies_policy + type: string + x-go-name: RepliesPolicy + - default: false + description: 将此列表的成员的贴文从你的主页时间线中隐藏。 + in: formData + name: exclusive + type: boolean + x-go-name: Exclusive + produces: + - application/json + responses: + "200": + description: 新创建的列表。 + schema: + $ref: '#/definitions/list' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:lists + summary: 创建列表 + tags: + - lists + /api/v1/lists/{id}: + delete: + operationId: listDelete + parameters: + - description: 列表的 ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 列表已删除 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:lists + summary: 删除列表 + description: 删除具有给定 ID 的列表。 + tags: + - lists + get: + operationId: list + parameters: + - description: 列表的 ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的列表。 + schema: + $ref: '#/definitions/list' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:lists + summary: 获取列表 + description: 获取具有给定 ID 的列表。 + tags: + - lists + put: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + operationId: listUpdate + parameters: + - description: 列表的 ID + in: path + name: id + required: true + type: string + - description: |- + 列表的标题。 + 示例: 大佬 + in: formData + name: title + type: string + - description: |- + 列表的回复展示规则。 + followed = 显示对任何关注的用户的回复 + list = 显示对列表成员的回复 + none = 不显示回复 + 示例: list + enum: + - followed + - list + - none + in: formData + name: replies_policy + type: string + - description: 将此列表的成员的贴文从你的主页时间线中隐藏。 + in: formData + name: exclusive + type: boolean + produces: + - application/json + responses: + "200": + description: 更新后的列表。 + schema: + $ref: '#/definitions/list' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:lists + summary: 更新列表 + tags: + - lists + /api/v1/lists/{id}/accounts: + delete: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + operationId: removeListAccounts + parameters: + - description: 列表的 ID + in: path + name: id + required: true + type: string + - collectionFormat: multi + description: 要编辑的账户 ID 数组。每个账户 ID 必须对应于一个发起请求的账户关注的账户。 + in: formData + items: + type: string + name: account_ids[] + required: true + type: array + produces: + - application/json + responses: + "200": + description: 列表账户已更新 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:lists + summary: 从列表删除账户 + description: 从给定列表中删除一个或多个账户。 + tags: + - lists + get: + description: |- + 分页浏览给定列表中的账户。 + 返回的 Link 标头可用于在时间线向上或向下滚动时生成上一个和下一个查询。 + + 示例: + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: listAccounts + parameters: + - description: 列表的 ID + in: path + name: id + required: true + type: string + - description: 仅返回比给定的 max ID *旧* 的列表条目。具有指定 ID 的列表条目对应的账户不会包含在响应中。 + in: query + name: max_id + type: string + - description: 仅返回比给定的 since ID *新* 的列表条目。具有指定 ID 的列表条目对应的账户不会包含在响应中。 + in: query + name: since_id + type: string + - description: 仅返回比给定的 min ID *相邻且更新* 的列表条目。具有指定 ID 的列表条目对应的账户不会包含在响应中。 + in: query + name: min_id + type: string + - default: 40 + description: '要返回的账户数量。如果显式设置为 0，则列表中的所有账户将被返回，并且不会使用分页标头。这是针对 Mastodon API 的一个特殊情况的解决方法：https://docs.joinmastodon.org/methods/lists/#query-parameters。' + in: query + maximum: 80 + minimum: 0 + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: 账户数组。 + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/account' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:lists + summary: 查看列表中的账户 + tags: + - lists + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + operationId: addListAccounts + parameters: + - description: 列表的 ID + in: path + name: id + required: true + type: string + - collectionFormat: multi + description: 要编辑的账户 ID 数组。每个账户 ID 必须对应于一个发起请求的账户关注的账户。 + in: formData + items: + type: string + name: account_ids[] + required: true + type: array + produces: + - application/json + responses: + "200": + description: 列表账户已更新 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:lists + summary: 向列表添加账户 + description: 向给定列表中添加一个或多个账户。 + tags: + - lists + /api/v1/markers: + get: + description: 根据名称获取时间线标记 + operationId: markersGet + parameters: + - description: 要检索的时间线。 + in: query + items: + enum: + - home + - notifications + type: string + name: timeline + type: array + produces: + - application/json + responses: + "200": + description: 请求的标记 + schema: + $ref: '#/definitions/markers' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:statuses + tags: + - markers + post: + consumes: + - multipart/form-data + description: 根据名称更新时间线标记 + operationId: markersPost + parameters: + - description: 在主页时间线上最后阅读的贴文 ID。 + in: formData + name: home[last_read_id] + type: string + - description: 在通知时间线上最后阅读的通知 ID。 + in: formData + name: notifications[last_read_id] + type: string + produces: + - application/json + responses: + "200": + description: 请求的标记 + schema: + $ref: '#/definitions/markers' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "409": + description: 冲突（当两个客户端尝试同时更新同一时间线时） + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:statuses + tags: + - markers + /api/v1/media/{id}: + get: + operationId: mediaGet + parameters: + - description: 附件的 ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的媒体附件。 + schema: + $ref: '#/definitions/attachment' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:media + summary: 获取单个媒体附件 + description: 获取一个你拥有的媒体附件。 + tags: + - media + put: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + description: |- + 你必须拥有这个媒体附件，并且这个附件还没有被附加到任何贴文上。 + + 若 Content-Type 为 'application/json'，则参数也可以在请求体中以 JSON 形式给出。 + 若 Content-Type 为 'application/xml'，则参数也可以在请求体中以 XML 形式给出。 + operationId: mediaUpdate + parameters: + - description: 要更新的附件的 ID + in: path + name: id + required: true + type: string + - allowEmptyValue: true + description: 图片或媒体描述，用作附件的 alt 文本。这对于使用屏幕阅读器的用户非常有用！根据实例设置，可能必填，也可能选填。 + in: formData + name: description + type: string + - allowEmptyValue: true + default: 0,0 + description: '媒体文件的焦点。如果存在，它应该是两个介于 -1 和 1 之间的逗号分隔的浮点数。例如：`-0.5,0.25`。' + in: formData + name: focus + type: string + produces: + - application/json + responses: + "200": + description: 更新后的媒体附件。 + schema: + $ref: '#/definitions/attachment' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:media + summary: 更新单个媒体附件 + tags: + - media + /api/v1/mutes: + get: + description: |- + 获取发起请求的账户静音的账户列表。 + 下一个和上一个查询可以从返回的Link标头中解析。 + 示例: + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: mutesGet + parameters: + - description: '仅返回比给定的 max ID *旧* 的被静音账户。具有指定 ID 的被静音账户不会包含在响应中。' + in: query + name: max_id + type: string + - description: '仅返回比给定的 since ID *新* 的被静音账户。具有指定 ID 的被静音账户不会包含在响应中。' + in: query + name: since_id + type: string + - description: '仅返回比给定的 min ID *相邻且更新* 的被静音账户。具有指定 ID 的被静音账户不会包含在响应中。' + in: query + name: min_id + type: string + - default: 40 + description: 要返回的被静音账户数量。 + in: query + maximum: 80 + minimum: 1 + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: 被静音账户的列表，包括他们的静音到期时间（如果适用）。 + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/mutedAccount' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:mutes + summary: 获取静音账户列表 + tags: + - mutes + /api/v1/notification/{id}: + get: + operationId: notification + parameters: + - description: 通知的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的通知。 + schema: + $ref: '#/definitions/notification' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:notifications + summary: 获取单个通知 + description: 获取单个具有给定 ID 的通知。 + tags: + - notifications + /api/v1/notifications: + get: + description: |- + 获取当前授权用户的通知。 + 通知将按照时间顺序（最新的在前）返回，具有连续的 ID（更大 = 更新）。 + + 下一个和上一个查询可以从返回的Link标头中解析。 + 示例: + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: notifications + parameters: + - description: 仅返回比给定的 max ID *旧* 的通知。具有指定 ID 的通知不会包含在响应中。 + in: query + name: max_id + type: string + - description: 仅返回比给定的 since ID *新* 的通知。具有指定 ID 的通知不会包含在响应中。 + in: query + name: since_id + type: string + - description: 仅返回比给定的 since ID *相邻且更新* 的通知。具有指定 ID 的通知不会包含在响应中。 + in: query + name: min_id + type: string + - default: 20 + description: 要返回的通知数量。 + in: query + name: limit + type: integer + - description: 要包含的通知类型。如果未提供，则将包含所有通知类型。 + in: query + items: + enum: + - follow + - follow_request + - mention + - reblog + - favourite + - poll + - status + - admin.sign_up + type: string + name: types[] + type: array + - description: 要排除的通知类型。 + in: query + items: + enum: + - follow + - follow_request + - mention + - reblog + - favourite + - poll + - status + - admin.sign_up + type: string + name: exclude_types[] + type: array + produces: + - application/json + responses: + "200": + description: 通知数组。 + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/notification' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:notifications + summary: 获取通知列表 + tags: + - notifications + /api/v1/notifications/clear: + post: + description: 清空/删除当前授权用户的所有通知。如果成功，将返回一个空对象 `{}`。 + operationId: clearNotifications + produces: + - application/json + responses: + "200": + description: "" + schema: + type: object + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:notifications + summary: 清空通知 + tags: + - notifications + /api/v1/polls/{id}: + get: + operationId: poll + parameters: + - description: 目标投票 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的投票。 + schema: + $ref: '#/definitions/poll' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:statuses + summary: 获取投票 + description: 获取具有给定 ID 的投票。 + tags: + - polls + /api/v1/polls/{id}/votes: + post: + operationId: pollVote + parameters: + - description: 目标投票 ID。 + in: path + name: id + required: true + type: string + - description: 用户选择的投票项索引。 + in: formData + items: + type: integer + name: choices + required: true + type: array + produces: + - application/json + responses: + "200": + description: 更新后的投票和用户投票选择。 + schema: + $ref: '#/definitions/poll' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "422": + description: unprocessable 无法处理 entity + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:statuses + summary: 参与投票 + description: 对给定投票进行投票。 + tags: + - polls + /api/v1/preferences: + get: + description: |- + 返回包含用户偏好设置的对象。 + 示例: + + ``` + + { + "posting:default:visibility": "public", + "posting:default:sensitive": false, + "posting:default:language": "en", + "reading:expand:media": "default", + "reading:expand:spoilers": false, + "reading:autoplay:gifs": false + } + + ```` + operationId: preferencesGet + produces: + - application/json + responses: + "200": + description: "" + schema: + type: object + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:accounts + summary: 获取用户偏好设置 + tags: + - preferences + /api/v1/profile/avatar: + delete: + description: 删除当前认证账户的头像。如果账户没有头像，调用也会成功。 + operationId: accountAvatarDelete + produces: + - application/json + responses: + "200": + description: 更新后的账户，包括个人资料源信息。 + schema: + $ref: '#/definitions/account' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 删除头像 + tags: + - accounts + /api/v1/profile/header: + delete: + description: 删除当前认证账户的横幅背景头图。如果账户没有横幅背景头图，调用也会成功。 + operationId: accountHeaderDelete + produces: + - application/json + responses: + "200": + description: 更新后的账户，包括个人资料源信息。 + schema: + $ref: '#/definitions/account' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 删除横幅背景 + tags: + - accounts + /api/v1/reports: + get: + description: |- + 查看发起请求的账户创建的举报。 + + 举报将按时间顺序（最新的在前）返回，具有连续的 ID（更大 = 更新）。 + + 下一个和上一个查询可以从返回的Link标头中解析。 + + 示例: + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: reports + parameters: + - description: 如果设置为 true，只返回已解决的举报。如果设置为 false，只返回未解决的举报。如果未设置，举报将不会根据其解决状态进行过滤。 + in: query + name: resolved + type: boolean + - description: 仅返回针对目标账户 ID 的举报。 + in: query + name: target_account_id + type: string + - description: 仅返回比给定的 max ID *旧* 的举报。具有指定 ID 的举报不会包含在响应中。 + in: query + name: max_id + type: string + - description: 仅返回比给定的 since ID *新* 的举报。具有指定 ID 的举报不会包含在响应中。 + in: query + name: since_id + type: string + - description: 仅返回比给定的 min ID *相邻且更新* 的举报。具有指定 ID 的举报不会包含在响应中。 + in: query + name: min_id + type: string + - default: 20 + description: 要返回的举报数量。 + in: query + maximum: 100 + minimum: 1 + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: 举报的数组。 + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/report' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:reports + summary: 获取举报列表 + tags: + - reports + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + operationId: reportCreate + parameters: + - description: |- + 要举报的账户 ID。 + 示例: 01GPE75FXSH2EGFBF85NXPH3KP + in: formData + name: account_id + required: true + type: string + x-go-name: AccountID + - description: |- + 要附加到举报中以提供额外上下文的贴文的 ID。 + 示例: ["01GPE76N4SBVRZ8K24TW51ZZQ4","01GPE76WN9JZE62EPT3Q9FRRD4"] + in: formData + items: + type: string + name: status_ids + type: array + x-go-name: StatusIDs + - description: |- + 举报的原因。默认最大 1000 个字符。 + 示例: 未经允许公开他人隐私信息 + in: formData + name: comment + type: string + x-go-name: Comment + - default: false + description: |- + 如果账户为外站账户，是否应将举报转发给外站管理员？ + 示例: true + in: formData + name: forward + type: boolean + x-go-name: Forward + - default: other + description: |- + 指定举报属于骚扰、违反特定实例规则还是其他原因。 + 目前仅支持 'other'。 + 示例: other + in: formData + name: category + type: string + x-go-name: Category + - description: |- + 举报人提供的被违反的实例规则的 ID。 + 示例: ["01GPBN5YDY6JKBWE44H7YQBDCQ","01GPBN65PDWSBPWVDD0SQCFFY3"] + in: formData + items: + type: string + name: rule_ids + type: array + x-go-name: RuleIDs + produces: + - application/json + responses: + "200": + description: 创建的举报。 + schema: + $ref: '#/definitions/report' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:reports + summary: 创建举报 + description: 根据给定参数创建一个新的用户举报。 + tags: + - reports + /api/v1/reports/{id}: + get: + operationId: reportGet + parameters: + - description: 举报的 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的举报。 + schema: + $ref: '#/definitions/report' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:reports + summary: 获取单条举报 + description: 获取具有给定 ID 的举报。 + tags: + - reports + /api/v1/statuses: + post: + consumes: + - application/json + - application/x-www-form-urlencoded + description: |- + 按给定的表单字段参数创建一个新的贴文。 + 若 Content-Type 为 'application/json'，则参数也可以在请求体中以 JSON 形式给出。 + + `interaction_policy` 字段可用于为此贴文设置交互策略。 + + 如果使用表单数据提交，请使用以下模式设置交互策略： + + `interaction_policy[INTERACTION_TYPE][CONDITION][INDEX]=Value` + + 例如：`interaction_policy[can_reply][always][0]=author` + + 使用 `curl` 可以按如下所示： + + `curl -F 'interaction_policy[can_reply][always][0]=author' -F 'interaction_policy[can_reply][always][1]=followers' [... other form fields ...]` + + JSON 等效形式为： + + `curl -H 'Content-Type: application/json' -d '{"interaction_policy":{"can_reply":{"always":["author","followers"]}} [... other json fields ...]}'` + + 服务器将对提交的策略执行一些规范化处理，以确保您无法提交完全无效的内容。 + operationId: statusCreate + parameters: + - description: |- + 贴文的文字内容。 + 如果提供了 media_ids，此项变为可选。 + 当提供贴文时，附加投票将变为可选。 + in: formData + name: status + type: string + x-go-name: Status + - description: |- + 要附加的媒体附件 ID 数组。 + 如果提供了 media_ids，status 将变为可选，poll 不能使用。 + + 如果贴文以表单形式提交，应使用的键为 'media_ids[]'，但如果是 JSON 或 XML，则键为 'media_ids'。 + in: formData + items: + type: string + name: media_ids + type: array + x-go-name: MediaIDs + - description: |- + 投票选项的数组。 + 如果提供了投票选项，media_ids 将不能使用，poll[expires_in] 必须提供。 + in: formData + items: + type: string + name: poll[options][] + type: array + x-go-name: PollOptions + - description: |- + 投票的开放时长，单位为秒。 + 如果提供了此项，media_ids 不能使用，poll[options] 必须提供。 + format: int64 + in: formData + name: poll[expires_in] + type: integer + x-go-name: PollExpiresIn + - default: false + description: 在此投票上允许多选。 + in: formData + name: poll[multiple] + type: boolean + x-go-name: PollMultiple + - default: true + description: 在投票结束前隐藏投票计数。 + in: formData + name: poll[hide_totals] + type: boolean + x-go-name: PollHideTotals + - description: 被回复的贴文 ID（如果要发送的贴文是回复）。 + in: formData + name: in_reply_to_id + type: string + x-go-name: InReplyToID + - description: 贴文和附加媒体应标记为敏感。 + in: formData + name: sensitive + type: boolean + x-go-name: Sensitive + - description: |- + 在贴文内容之前显示的警告或主题文本。 + 贴文通常被折叠在此字段身后。 + in: formData + name: spoiler_text + type: string + x-go-name: SpoilerText + - description: 贴文的可见性。 + enum: + - public + - unlisted + - private + - mutuals_only + - direct + in: formData + name: visibility + type: string + x-go-name: Visibility + - default: false + description: 如果设置为 true，此状态将仅在本站可见，不会传播到本站以外的时间线。如果设置为 false（默认），此状态将传播到您的所有关注者，以及本站时间线外的时间线。 + in: formData + name: local_only + type: boolean + x-go-name: LocalOnly + - description: '***已弃用***。仅用于后向兼容。仅在 local_only 尚未设置且此字段被明确设置时使用。如果设置为 true，此贴文将在本站时间线之外传播。如果设置为 false，此贴文将不会在本站时间线之外传播。' + in: formData + name: federated + type: boolean + x-go-name: Federated + - description: |- + 此贴文的计划发布时间，格式为 ISO 8601 Datetime。 + 提供此参数将导致返回 ScheduledStatus 而不是 Status。 + 必须至少在未来 5 分钟之后。 + + 此功能尚未实现；尝试设置它将返回 501 Not Implemented。 + in: formData + name: scheduled_at + type: string + x-go-name: ScheduledAt + - description: 此贴文的 ISO 639 语言代码。 + in: formData + name: language + type: string + x-go-name: Language + - description: 解析此贴文时使用的内容类型。 + enum: + - text/plain + - text/markdown + in: formData + name: content_type + type: string + x-go-name: ContentType + - description: interaction_policy.can_favourite.always 的第 N 个条目。 + in: formData + name: interaction_policy[can_favourite][always][0] + type: string + - description: interaction_policy.can_favourite.with_approval 的第 N 个条目。 + in: formData + name: interaction_policy[can_favourite][with_approval][0] + type: string + - description: interaction_policy.can_reply.always 的第 N 个条目。 + in: formData + name: interaction_policy[can_reply][always][0] + type: string + - description: interaction_policy.can_reply.with_approval 的第 N 个条目。 + in: formData + name: interaction_policy[can_reply][with_approval][0] + type: string + - description: interaction_policy.can_reblog.always 的第 N 个条目。 + in: formData + name: interaction_policy[can_reblog][always][0] + type: string + - description: interaction_policy.can_reblog.with_approval 的第 N 个条目。 + in: formData + name: interaction_policy[can_reblog][with_approval][0] + type: string + produces: + - application/json + responses: + "200": + description: 新创建的贴文。 + schema: + $ref: '#/definitions/status' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + "501": + description: scheduled_at 被设置，但此功能尚未实现 + security: + - OAuth2 Bearer: + - write:statuses + summary: 创建新贴文 + tags: + - statuses + /api/v1/statuses/{id}: + delete: + description: |- + 删除给定 ID 的贴文。贴文必须属于您。 + 删除的贴文将在响应中返回。`text` 字段将包含贴文的原始文本，就像它被提交时一样。这在执行“删除并重新撰写”类型操作时很有用。 + operationId: statusDelete + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 刚刚被删除的贴文。 + schema: + $ref: '#/definitions/status' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:statuses + summary: 删除贴文 + tags: + - statuses + get: + operationId: statusGet + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的贴文。 + schema: + $ref: '#/definitions/status' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:statuses + summary: 查看贴文 + description: 查看具有给定 ID 的贴文。 + tags: + - statuses + /api/v1/statuses/{id}/bookmark: + post: + operationId: statusBookmark + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 对应的贴文。 + schema: + $ref: '#/definitions/status' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:statuses + summary: 收藏贴文 + description: 收藏具有给定 ID 的贴文。 + tags: + - statuses + /api/v1/statuses/{id}/context: + get: + description: 返回给定贴文的祖先和后代。返回的贴文将按贴文串结构排序，因此它们适合按返回顺序显示。 + operationId: threadContext + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 贴文串上下文对象。 + schema: + $ref: '#/definitions/threadContext' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:statuses + summary: 查看贴文串上下文 + tags: + - statuses + /api/v1/statuses/{id}/favourite: + post: + operationId: statusFave + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 被点赞的贴文。 + schema: + $ref: '#/definitions/status' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:statuses + summary: 点赞贴文 + description: 点赞给定 ID 的贴文（如果允许）。 + tags: + - statuses + /api/v1/statuses/{id}/favourited_by: + get: + operationId: statusFavedBy + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: "" + schema: + items: + $ref: '#/definitions/account' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:accounts + summary: 查看贴文点赞列表 + description: 查看点赞给定 ID 的贴文的账户。 + tags: + - statuses + /api/v1/statuses/{id}/history: + get: + description: '查看给定 ID 的贴文的编辑历史。 **未实现**：当前此端点将始终返回一个长度为 1 的数组，仅包含贴文的最新/当前版本。' + operationId: statusHistoryGet + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: "" + schema: + items: + $ref: '#/definitions/statusEdit' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:statuses + summary: 查看贴文编辑历史 + tags: + - statuses + /api/v1/statuses/{id}/mute: + post: + description: |- + 静音某条贴文的贴文串，防止未来串中的回复、点赞、转发等行为产生通知。 + + 目标贴文必须属于您或提及了您。 + + 贴文串静音和取消静音是幂等的。如果您已经静音了一个串，再次静音它只是意味着它保持静音，您将得到 200 OK 返回。 + operationId: statusMute + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 被静音的贴文。 + schema: + $ref: '#/definitions/status' + "400": + description: bad request 无效请求; 你不是目标贴文串的参与者 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:mutes + summary: 静音贴文串 + tags: + - statuses + /api/v1/statuses/{id}/pin: + post: + description: |- + 将贴文在个人资料页置顶，并将其添加到你的特色 ActivityPub 集合中。 + + 你只能将原创贴文（非转发）固定到自己的个人资料上。 + + 支持的固定贴文的隐私级别有 public、unlisted 和 private/followers-only， + 但只有公开贴文会出现在您个人资料的网页版本上。 + operationId: statusPin + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 被固定的贴文。 + schema: + $ref: '#/definitions/status' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:accounts + summary: 置顶贴文 + tags: + - statuses + /api/v1/statuses/{id}/reblog: + post: + description: |- + 转发给定 ID 的贴文。 + 如果目标贴文是可转发的，它将被分享给您的粉丝。 + 这相当于一个 ActivityPub 'Announce' 活动。 + operationId: statusReblog + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 被转发的贴文。 + schema: + $ref: '#/definitions/status' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:statuses + summary: 转发贴文 + tags: + - statuses + /api/v1/statuses/{id}/reblogged_by: + get: + operationId: statusBoostedBy + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: "" + schema: + items: + $ref: '#/definitions/account' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + security: + - OAuth2 Bearer: + - read:accounts + summary: 查看贴文转发列表 + description: 查看转发给定 ID 的贴文的账户。 + tags: + - statuses + /api/v1/statuses/{id}/source: + get: + operationId: statusSourceGet + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: "" + schema: + items: + $ref: '#/definitions/statusSource' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:statuses + summary: 查看贴文源文本 + description: 查看给定 ID 的贴文的源文本。请求者必须拥有该贴文。 + tags: + - statuses + /api/v1/statuses/{id}/unbookmark: + post: + operationId: statusUnbookmark + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 对应的贴文。 + schema: + $ref: '#/definitions/status' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:statuses + summary: 取消收藏贴文 + description: 取消收藏给定 ID 的贴文。 + tags: + - statuses + /api/v1/statuses/{id}/unfavourite: + post: + operationId: statusUnfave + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 被取消点赞的贴文。 + schema: + $ref: '#/definitions/status' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:statuses + summary: 取消点赞贴文 + description: 取消点赞给定 ID 的贴文。 + tags: + - statuses + /api/v1/statuses/{id}/unmute: + post: + description: |- + 取消静音某条贴文的贴文串。这将重新启用串中未来回复、点赞、转发等行为的通知。 + + 目标贴文必须属于您或提及了您。 + + 贴文串静音和取消静音是幂等的。如果您已经取消静音了一个串，再次取消静音它只是意味着它保持取消静音，您将得到 200 OK 的返回状态。 + operationId: statusUnmute + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 被取消静音的贴文。 + schema: + $ref: '#/definitions/status' + "400": + description: bad request 无效请求; 你不是目标贴文串的参与者 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:mutes + summary: 取消静音贴文串 + tags: + - statuses + /api/v1/statuses/{id}/unpin: + post: + operationId: statusUnpin + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 贴文。 + schema: + $ref: '#/definitions/status' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:accounts + summary: 取消置顶贴文 + description: 取消置顶某条已经置顶的贴文。 + tags: + - statuses + /api/v1/statuses/{id}/unreblog: + post: + operationId: statusUnreblog + parameters: + - description: 目标贴文 ID。 + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 被取消转发的贴文。 + schema: + $ref: '#/definitions/status' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:statuses + summary: 取消转发贴文 + description: 取消转发给定 ID 的贴文。 + tags: + - statuses + /api/v1/streaming: + get: + description: |- + 发起一个用于实时流式传输贴文和通知的 websocket 连接。 + 使用的协议应始终为 `wss`。流式传输根路径可以在 `/api/v1/instance` 查看。 + + 在成功连接时，将返回代码 `101`，表示正在将连接升级为安全的 websocket 连接。 + + 只要连接保持打开状态，就会将各种消息类型流式传输到其中。 + + GoToSocial 将每 30 秒对连接进行 ping，以检查客户端是否仍在接收。 + + 如果 ping 失败，或者在传输过程中发生其他问题，则连接将被断开，并且客户端将被要求重新启动。 + operationId: streamGet + parameters: + - description: 发起请求的账户的访问令牌。 + in: query + name: access_token + required: true + type: string + - description: |- + 请求的流类型。 + + 可用选项有： + + `user`: 接收账户的主页时间线更新。 + `public`: 接收公共时间线更新。 + `public:local`: 接收本站时间线更新。 + `hashtag`: 接收给定话题标签的更新。 + `hashtag:local`: 接收给定话题标签的本站更新。 + `list`: 接收一个列表中的账户的更新。 + `direct`: 接收私信的更新。 + in: query + name: stream + required: true + type: string + - description: |- + 要订阅的列表的 ID。 + 仅在流类型为 'list' 时使用。 + in: query + name: list + type: string + - description: |- + 要订阅的话题标签的名称。 + 仅在流类型为 'hashtag' 或 'hashtag:local' 时使用。 + in: query + name: tag + type: string + produces: + - application/json + responses: + "101": + description: "" + schema: + properties: + event: + description: |- + 要接收的事件类型。 + + `update`：收到新贴文。 + `notification`：收到新通知。 + `delete`：贴文已被删除。 + `filters_changed`：过滤规则（包括关键字和贴文）已更改。 + enum: + - update + - notification + - delete + - filters_changed + type: string + payload: + description: |- + 流式传输消息的有效负载。 + 根据 `event` 类型不同而不同。 + + 如果存在，应解析为字符串。 + + 如果 `event` = `update`，则负载将是一个贴文的 JSON 字符串。 + 如果 `event` = `notification`，则负载将是一个通知的 JSON 字符串。 + 如果 `event` = `delete`，则负载将是一个贴文 ID。 + 如果 `event` = `filters_changed`，则没有负载。 + example: '{"id":"01FC3TZ5CFG6H65GCKCJRKA669","created_at":"2021-08-02T16:25:52Z","sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://gts.superseriousbusiness.org/users/dumpsterqueer/statuses/01FC3TZ5CFG6H65GCKCJRKA669","url":"https://gts.superseriousbusiness.org/@dumpsterqueer/statuses/01FC3TZ5CFG6H65GCKCJRKA669","replies_count":0,"reblogs_count":0,"favourites_count":0,"favourited":false,"reblogged":false,"muted":false,"bookmarked":fals…//gts.superseriousbusiness.org/fileserver/01JNN207W98SGG3CBJ76R5MVDN/header/original/019036W043D8FXPJKSKCX7G965.png","header_static":"https://gts.superseriousbusiness.org/fileserver/01JNN207W98SGG3CBJ76R5MVDN/header/small/019036W043D8FXPJKSKCX7G965.png","followers_count":33,"following_count":28,"statuses_count":126,"last_status_at":"2021-08-02T16:25:52Z","emojis":[],"fields":[]},"media_attachments":[],"mentions":[],"tags":[],"emojis":[],"card":null,"poll":null,"text":"a"}' + type: string + stream: + items: + enum: + - user + - public + - public:local + - hashtag + - hashtag:local + - list + - direct + type: string + type: array + type: object + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + schemes: + - wss + security: + - OAuth2 Bearer: + - read:streaming + summary: 流式传输 + tags: + - streaming + /api/v1/tags/{tag_name}: + get: + description: 获取话题标签详情，包括您当前是否关注它。如果话题不存在，此方法不会在数据库中创建它。 + operationId: getTag + parameters: + - description: 话题标签的名称（不包含 `#`）。 + in: path + name: tag_name + required: true + type: string + produces: + - application/json + responses: + "200": + description: 话题标签详情。 + schema: + $ref: '#/definitions/tag' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:follows + summary: 获取话题标签 + tags: + - tags + /api/v1/tags/{tag_name}/follow: + post: + description: '此端点是幂等的：如果您已经关注了话题标签，此调用仍将成功。' + operationId: followTag + parameters: + - description: 话题标签的名称（不包含 `#`）。 + in: path + name: tag_name + required: true + type: string + produces: + - application/json + responses: + "200": + description: 话题标签详情。 + schema: + $ref: '#/definitions/tag' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:follows + summary: 关注话题标签 + tags: + - tags + /api/v1/tags/{tag_name}/unfollow: + post: + description: '此端点是幂等的：如果您没有关注话题标签，此调用仍将成功。' + operationId: unfollowTag + parameters: + - description: 话题标签的名称（不包含 `#`）。 + in: path + name: tag_name + required: true + type: string + produces: + - application/json + responses: + "200": + description: 话题标签详情。 + schema: + $ref: '#/definitions/tag' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: unauthorized 未授权 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:follows + summary: 取消关注话题标签 + tags: + - tags + /api/v1/timelines/home: + get: + description: |- + 查看你关注的账户发布的贴文。 + 贴文将按时间顺序（最新的在前）返回，带有连续的 ID（较大 = 较新）。 + + 返回的 Link 标头可用于在时间线向上或向下滚动时生成上一个和下一个查询。 + + 示例: + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: homeTimeline + parameters: + - description: 只返回早于给定的最大贴文 ID 的贴文。具有指定 ID 的贴文不会包含在响应中。 + in: query + name: max_id + type: string + - description: 只返回新于给定的最小贴文 ID 的贴文。具有指定 ID 的贴文不会包含在响应中。 + in: query + name: since_id + type: string + - description: 只返回比给定的最小贴文 ID **相邻且更新** 的贴文。具有指定 ID 的贴文不会包含在响应中。 + in: query + name: min_id + type: string + - default: 20 + description: 要返回的贴文数量。 + in: query + name: limit + type: integer + - default: false + description: 仅显示本站账户发布的贴文。 + in: query + name: local + type: boolean + produces: + - application/json + responses: + "200": + description: 贴文数组。 + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/status' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + security: + - OAuth2 Bearer: + - read:statuses + summary: 查看主页时间线 + tags: + - timelines + /api/v1/timelines/list/{id}: + get: + description: |- + 查看给定列表的时间线贴文。 + + 贴文将按时间顺序（最新的在前）返回，带有连续的 ID（较大 = 较新）。 + + 返回的 Link 标头可用于在时间线向上或向下滚动时生成上一个和下一个查询。 + + 示例: + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: listTimeline + parameters: + - description: 列表的 ID + in: path + name: id + required: true + type: string + - description: 只返回早于给定的最大贴文 ID 的贴文。具有指定 ID 的贴文不会包含在响应中。 + in: query + name: max_id + type: string + - description: 只返回新于给定的最小贴文 ID 的贴文。具有指定 ID 的贴文不会包含在响应中。 + in: query + name: since_id + type: string + - description: 只返回比给定的最小贴文 ID **相邻且更新** 的贴文。具有指定 ID 的贴文不会包含在响应中。 + in: query + name: min_id + type: string + - default: 20 + description: 要返回的贴文数量。 + in: query + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: 贴文数组。 + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/status' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + security: + - OAuth2 Bearer: + - read:lists + summary: 查看列表时间线 + tags: + - timelines + /api/v1/timelines/public: + get: + description: |- + 查看你所在的实例已知的公开贴文。 + + 贴文将按时间顺序（最新的在前）返回，带有连续的 ID（较大 = 较新）。 + + 返回的 Link 标头可用于在时间线向上或向下滚动时生成上一个和下一个查询。 + + 示例: + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: publicTimeline + parameters: + - description: 只返回早于给定的最大贴文 ID 的贴文。具有指定 ID 的贴文不会包含在响应中。 + in: query + name: max_id + type: string + - description: 只返回新于给定的最小贴文 ID 的贴文。具有指定 ID 的贴文不会包含在响应中。 + in: query + name: since_id + type: string + - description: 只返回比给定的最小贴文 ID **相邻且更新** 的贴文。具有指定 ID 的贴文不会包含在响应中。 + in: query + name: min_id + type: string + - default: 20 + description: 要返回的贴文数量。 + in: query + name: limit + type: integer + - default: false + description: 仅显示本站账户发布的贴文。 + in: query + name: local + type: boolean + produces: + - application/json + responses: + "200": + description: 贴文数组。 + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/status' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + security: + - OAuth2 Bearer: + - read:statuses + summary: 查看跨站时间线 + tags: + - timelines + /api/v1/timelines/tag/{tag_name}: + get: + description: |- + 查看给定话题标签的公开贴文 (不区分大小写) + + 贴文将按时间顺序（最新的在前）返回，带有连续的 ID（较大 = 较新）。 + + 返回的 Link 标头可用于在时间线向上或向下滚动时生成上一个和下一个查询。 + + 示例: + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: tagTimeline + parameters: + - description: Name of the tag + in: path + name: tag_name + required: true + type: string + - description: 只返回早于给定的最大贴文 ID 的贴文。具有指定 ID 的贴文不会包含在响应中。 + in: query + name: max_id + type: string + - description: 只返回新于给定的最小贴文 ID 的贴文。具有指定 ID 的贴文不会包含在响应中。 + in: query + name: since_id + type: string + - description: 只返回比给定的最小贴文 ID **相邻且更新** 的贴文。具有指定 ID 的贴文不会包含在响应中。 + in: query + name: min_id + type: string + - default: 20 + description: 要返回的贴文数量。 + in: query + maximum: 40 + minimum: 1 + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: 贴文数组。 + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/status' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + security: + - OAuth2 Bearer: + - read:statuses + summary: 查看话题标签时间线 + tags: + - timelines + /api/v1/user: + get: + operationId: getUser + produces: + - application/json + responses: + "200": + description: 请求的用户。 + schema: + $ref: '#/definitions/user' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "406": + description: not acceptable 不可接受 + "500": + description: internal error + security: + - OAuth2 Bearer: + - read:user + summary: 获取当前用户 + description: 获取自己的用户模型。 + tags: + - user + /api/v1/user/email_change: + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + operationId: userEmailChange + parameters: + - description: 用户当前密码，用于验证。 + in: formData + name: password + required: true + type: string + x-go-name: Password + - description: 新邮箱地址。 + in: formData + name: new_email + required: true + type: string + x-go-name: NewEmail + produces: + - application/json + responses: + "202": + description: '已接受：正在处理邮箱更改；请检查您的收件箱以确认新地址。' + schema: + $ref: '#/definitions/user' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "406": + description: not acceptable 不可接受 + "409": + description: '冲突: 提供的邮箱地址已被使用' + "500": + description: internal error + security: + - OAuth2 Bearer: + - write:user + summary: 更改邮箱地址 + description: 请求更改当前用户的邮箱地址。 + tags: + - user + /api/v1/user/password_change: + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + description: |- + 修改当前用户的密码。 + 若 Content-Type 为 'application/json'，则参数也可以在请求体中以 JSON 形式给出。 + 若 Content-Type 为 'application/xml'，则参数也可以在请求体中以 XML 形式给出。 + operationId: userPasswordChange + parameters: + - description: 用户的旧密码。 + in: formData + name: old_password + required: true + type: string + x-go-name: OldPassword + - description: |- + 用户提供的新密码。 + 如果密码的熵不够高，将被拒绝。 + 参见 https://github.com/wagslane/go-password-validator + in: formData + name: new_password + required: true + type: string + x-go-name: NewPassword + produces: + - application/json + responses: + "200": + description: 密码更改成功 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "406": + description: not acceptable 不可接受 + "422": + description: 无法处理请求，因为实例正在使用 OIDC 后端 + "500": + description: internal error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:user + summary: 更改密码 + tags: + - user + /api/v2/admin/accounts: + get: + description: |- + 按给定过滤规则查看并按页浏览已知账户。 + + 返回的账户将按域名 + 用户名的字母顺序（a-z）排序。 + + 下一个和上一个查询可以从返回的Link标头中解析。 + 示例: + + ``` + ; rel="next", ; rel="prev" + ```` + operationId: adminAccountsGetV2 + parameters: + - description: 针对 `local` 或 `remote` 类型的账户进行过滤。 + in: query + name: origin + type: string + - description: 针对 `active`, `pending`, `disabled`, `silenced`, 或 `suspended` 类型的账户进行过滤。 + in: query + name: status + type: string + - description: 针对具有站务权限（可以管理举报）的账户进行过滤。 + in: query + name: permissions + type: string + - description: 针对具有对应身份组的账户进行过滤。 + in: query + items: + type: string + name: role_ids[] + type: array + - description: 查找被对应 ID 的账户邀请的用户。 + in: query + name: invited_by + type: string + - description: 搜索给定用户名。 + in: query + name: username + type: string + - description: 搜索给定昵称。 + in: query + name: display_name + type: string + - description: 针对给定实例域名进行过滤。 + in: query + name: by_domain + type: string + - description: 查找具有给定电子邮箱的用户。 + in: query + name: email + type: string + - description: 查找具有此 IP 地址的用户。 + in: query + name: ip + type: string + - description: "`[domain]/@[username]` 形式的 max_id。返回的所有结果都将在 `[domain]/@[username]` 之后的字母顺序中。例如，如果 max_id = `example.org/@someone`，则返回的条目可能包含 `example.org/@someone_else`，`later.example.org/@someone` 等。本站账户 ID 使用空字符串作为 `[domain]` 部分，例如具有用户名 `someone` 的本站账户将是 `/@someone`。" + in: query + name: max_id + type: string + - description: "`[domain]/@[username]` 形式的 min_id。返回的所有结果都将在 `[domain]/@[username]` 之前的字母顺序中。例如，如果 min_id = `example.org/@someone`，则返回的条目可能包含 `example.org/@earlier_account`，`earlier.example.org/@someone` 等。本站账户 ID 使用空字符串作为 `[domain]` 部分，例如具有用户名 `someone` 的本站账户将是 `/@someone`。" + in: query + name: min_id + type: string + - default: 50 + description: 返回的最大结果数量。 + in: query + maximum: 200 + minimum: 1 + name: limit + type: integer + produces: + - application/json + responses: + "200": + description: "" + headers: + Link: + description: 下一/上一查询的链接。 + type: string + schema: + items: + $ref: '#/definitions/adminAccountInfo' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - admin + summary: 查看账户列表 + tags: + - admin + /api/v2/filters: + get: + operationId: filtersV2Get + produces: + - application/json + responses: + "200": + description: 请求的过滤规则。 + schema: + items: + $ref: '#/definitions/filterV2' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:filters + summary: 获取V2过滤规则 + description: 获取当前账户的所有V2过滤规则。 + tags: + - filters + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + operationId: filterV2Post + parameters: + - description: |- + 过滤规则的名称。 + + 示例： 挂人 + in: formData + maxLength: 200 + minLength: 1 + name: title + required: true + type: string + - collectionFormat: multi + description: |- + 此过滤规则要应用的上下文。 + + 示例: home, public + enum: + - home + - notifications + - public + - thread + - account + in: formData + items: + type: string + minItems: 1 + name: context[] + required: true + type: array + uniqueItems: true + - description: |- + 此过滤规则的持续时间（以秒为单位）。若省略，则过滤规则永不过期。 + + 示例：86400 + in: formData + name: expires_in + type: number + - default: warn + description: |- + 贴文命中过滤规则时的操作。 + + 示例: warn + enum: + - warn + - hide + in: formData + name: filter_action + type: string + - collectionFormat: multi + description: 要添加 (如果不使用 id 参数) 或更新 (如果使用 id 参数) 的关键词。 + in: formData + items: + type: string + name: keywords_attributes[][keyword] + type: array + - collectionFormat: multi + description: 匹配关键词时是否考虑单词边界 (整词匹配)？ + in: formData + items: + type: boolean + name: keywords_attributes[][whole_word] + type: array + - collectionFormat: multi + description: 要添加到过滤规则的贴文（status）。 + in: formData + items: + type: string + name: statuses_attributes[][status_id] + type: array + produces: + - application/json + responses: + "200": + description: 新过滤规则。 + schema: + $ref: '#/definitions/filterV2' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: 禁止对已迁移的账户执行此操作 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "409": + description: conflict 冲突（重复的标题、关键词或贴文） + "422": + description: 无法处理的内容 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:filters + summary: 创建V2过滤规则 + tags: + - filters + /api/v2/filters/{id}: + delete: + operationId: filterV2Delete + parameters: + - description: 过滤规则的 ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 过滤规则已删除 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:filters + summary: 删除V2过滤规则 + description: 删除给定 ID 的单个V2过滤规则。 + tags: + - filters + get: + operationId: filterV2Get + parameters: + - description: 过滤规则的 ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的过滤规则。 + schema: + $ref: '#/definitions/filterV2' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:filters + summary: 获取单个V2过滤规则 + description: 获取给定 ID 的单个V2过滤规则。 + tags: + - filters + put: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + description: |- + 更新具有给定 ID 的单个V2过滤规则。 + 注意，这实际上更接近于 PATCH 操作：只有提供的字段将被更新，而省略的字段将保持为以前的值。 + operationId: filterV2Put + parameters: + - description: 过滤规则的 ID. + in: path + name: id + required: true + type: string + - description: |- + 过滤规则的标题。 + + 示例: 挂人 + in: formData + maxLength: 200 + minLength: 1 + name: title + required: true + type: string + - collectionFormat: multi + description: 要添加到此过滤规则的关键词。 + in: formData + items: + type: string + name: keywords_attributes[][keyword] + type: array + - collectionFormat: multi + description: 匹配关键词时是否考虑单词边界 (整词匹配)？ + in: formData + items: + type: boolean + name: keywords_attributes[][whole_word] + type: array + - collectionFormat: multi + description: 要添加到过滤规则的贴文。 + in: formData + items: + type: string + name: statuses_attributes[][status_id] + type: array + - collectionFormat: multi + description: |- + 此过滤规则要应用的上下文。 + + 示例: home, public + enum: + - home + - notifications + - public + - thread + - account + in: formData + items: + type: string + minItems: 1 + name: context[] + required: true + type: array + uniqueItems: true + - description: |- + 此过滤规则的持续时间（以秒为单位）。若省略，则过滤规则永不过期。 + + 示例: 86400 + in: formData + name: expires_in + type: number + - description: |- + 贴文命中过滤规则时的操作。 + + 示例: warn + enum: + - warn + - hide + in: formData + name: filter_action + type: string + produces: + - application/json + responses: + "200": + description: 更新后的过滤规则。 + schema: + $ref: '#/definitions/filterV2' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: 禁止对已迁移的账户执行此操作 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "409": + description: conflict 冲突（重复的标题、关键词或贴文） + "422": + description: unprocessable 无法处理的内容 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:filters + summary: 更新V2过滤规则 + tags: + - filters + /api/v2/filters/{id}/keywords: + get: + operationId: filterKeywordsGet + parameters: + - description: 过滤规则的 ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的过滤规则关键词 + schema: + items: + $ref: '#/definitions/filterKeyword' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:filters + summary: 获取过滤规则关键词 + description: 获取给定 ID 的过滤规则的所有关键词。 + tags: + - filters + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + operationId: filterKeywordPost + parameters: + - description: 要将贴文添加到的过滤规则的 ID。 + in: path + name: id + required: true + type: string + - description: |- + 要被过滤的文本 + + 示例：挂人 + in: formData + maxLength: 40 + minLength: 1 + name: keyword + required: true + type: string + - default: false + description: |- + 此过滤规则是否应考虑单词边界（整词匹配）？ + + 示例：true + in: formData + name: whole_word + type: boolean + produces: + - application/json + responses: + "200": + description: 新的过滤规则关键词。 + schema: + $ref: '#/definitions/filterKeyword' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: 禁止对已迁移的账户执行此操作 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "409": + description: conflict 冲突（重复的关键词） + "422": + description: unprocessable 无法处理的内容 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:filters + summary: 添加关键词 + description: 向给定 ID 的过滤规则添加关键词。 + tags: + - filters + /api/v2/filters/{id}/statuses: + get: + operationId: filterStatusesGet + parameters: + - description: 过滤规则的 ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的过滤规则贴文。 + schema: + items: + $ref: '#/definitions/filterStatus' + type: array + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:filters + summary: 获取过滤规则贴文 + description: 获取给定过滤规则下的所有贴文。 + tags: + - filters + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + operationId: filterStatusPost + parameters: + - description: 要将贴文添加到的过滤规则的 ID。 + in: path + name: id + required: true + type: string + - description: |- + 要过滤的贴文的 ID。 + + 示例：01HXA2NE0K8T1C70K90E74GYD0 + in: formData + name: status_id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 新的过滤规则贴文。 + schema: + $ref: '#/definitions/filterStatus' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: 禁止对已迁移的账户执行此操作 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "409": + description: conflict 冲突（重复的贴文） + "422": + description: unprocessable 无法处理的内容 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:filters + summary: 添加贴文 + description: 向已有过滤规则添加一条贴文。 + tags: + - filters + /api/v2/filters/keywords/{id}: + delete: + operationId: filterKeywordDelete + parameters: + - description: 过滤规则关键词的 ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 过滤规则关键词已删除 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:filters + summary: 删除过滤规则关键词 + description: 通过指定 ID 删除某个过滤规则关键词。 + tags: + - filters + get: + operationId: filterKeywordGet + parameters: + - description: 过滤规则关键词的 ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的过滤规则关键词。 + schema: + $ref: '#/definitions/filterKeyword' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:filters + summary: 获取过滤规则关键词 + description: 获取具有给定 ID 的单个过滤规则关键词。 + tags: + - filters + /api/v2/filters/keywords{id}: + put: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + operationId: filterKeywordPut + parameters: + - description: 要更新的过滤规则关键词的 ID。 + in: path + name: id + required: true + type: string + - description: |- + 要过滤的文本 + + 示例：挂人 + in: formData + maxLength: 40 + minLength: 1 + name: keyword + required: true + type: string + - description: |- + 过滤时是否考虑单词边界（整词匹配）？ + + 示例：true + in: formData + name: whole_word + type: boolean + produces: + - application/json + responses: + "200": + description: 更新后的过滤关键词。 + schema: + $ref: '#/definitions/filterKeyword' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: 禁止对已迁移的账户执行此操作 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "409": + description: conflict 冲突（重复的关键词） + "422": + description: unprocessable 无法处理 content + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:filters + summary: 更新过滤规则关键词 + description: 更新具有给定 ID 的单个过滤规则关键词。 + tags: + - filters + /api/v2/filters/statuses/{id}: + delete: + operationId: filterStatusDelete + parameters: + - description: 过滤规则贴文的 ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 过滤规则贴文已删除 + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - write:filters + summary: 删除过滤规则贴文 + description: 删除具有给定 ID 的单个过滤规则贴文。 + tags: + - filters + get: + operationId: filterStatusGet + parameters: + - description: 过滤规则贴文的 ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: 请求的过滤规则贴文。 + schema: + $ref: '#/definitions/filterStatus' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "404": + description: not found 未找到 + "406": + description: not acceptable 不可接受 + "500": + description: internal server error 服务器内部错误 + security: + - OAuth2 Bearer: + - read:filters + summary: 获取过滤规则贴文 + description: 获取具有给定 ID 的单个过滤规则贴文。 + tags: + - filters + /api/v2/instance: + get: + operationId: instanceGetV2 + produces: + - application/json + responses: + "200": + description: 实例信息。 + schema: + $ref: '#/definitions/instanceV2' + "406": + description: not acceptable 不可接受 + "500": + description: internal error + summary: 查看实例信息 + tags: + - instance + /livez: + get: + operationId: liveGet + responses: + "200": + description: OK + summary: 服务在线检测 + description: 若 GoToSocial 服务“在线” (即能够响应HTTP请求)，则返回无响应体的 200 状态码。 + tags: + - health + head: + operationId: liveHead + responses: + "200": + description: OK + summary: 服务在线检测 + description: 若 GoToSocial 服务“在线” (即能够响应HTTP请求)，则返回 200 状态码。 + tags: + - health + /nodeinfo/2.0: + get: + description: '对 nodeinfo 查询返回符合规范的 nodeinfo 响应。参见: https://nodeinfo.diaspora.software/schema.html' + operationId: nodeInfoGet + produces: + - application/json; profile="http://nodeinfo.diaspora.software/ns/schema/2.0#" + responses: + "200": + description: "" + schema: + $ref: '#/definitions/nodeinfo' + summary: NodeInfo 2.0 + tags: + - nodeinfo + /readyz: + get: + description: 若 GoToSocial 服务“就绪” (即能够连接到数据库后端并执行简单的 SELECT)，则返回无响应体的 200 状态码。若 GtS 尚未准备就绪，则在日志中记录错误（但不返回给调用方，以避免泄露内部信息）。 + operationId: readyGet + responses: + "200": + description: OK + "500": + description: 尚未就绪。查看日志以获取错误信息。 + summary: 服务就绪检测 + tags: + - health + head: + description: 若 GoToSocial 服务“就绪” (即能够连接到数据库后端并执行简单的 SELECT)，则返回无响应体的 200 状态码。若 GtS 尚未准备就绪，则在日志中记录错误（但不返回给调用方，以避免泄露内部信息）。 + operationId: readyHead + responses: + "200": + description: OK + summary: 服务就绪检测 + tags: + - health + /users/{username}/collections/featured: + get: + description: |- + 获取某个用户的精选集合（置顶贴文）。 + 响应将包含 `items` 属性中的 Note URI 的有序集合。 + + 由调用方决定是否解析提供的 Note URIs（如果它们已经缓存，则不解析）。 + + 请求需要 HTTP 签名。 + operationId: s2sFeaturedCollectionGet + parameters: + - description: 用户的账户名 + in: path + name: username + required: true + type: string + produces: + - application/activity+json + responses: + "200": + description: "" + schema: + $ref: '#/definitions/swaggerFeaturedCollection' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + summary: 获取用户精选集合 + tags: + - s2s/federation + /users/{username}/outbox: + get: + description: |- + 获取用户的公开发件箱集合。 + + 注意，如果 `page` 为 `false`，则响应将是一个带有 `first` 页的 Collection，如下所示。 + + 如果 `page` 为 `true`，则响应将是一个不带 `Collection` 包装的单个 `CollectionPage`。 + + 请求需要 HTTP 签名。 + operationId: s2sOutboxGet + parameters: + - description: 账户的用户名。 + in: path + name: username + required: true + type: string + - default: false + description: 按 CollectionPage 返回响应。 + in: query + name: page + type: boolean + - description: 下一贴文的最小 ID，用于分页。 + in: query + name: min_id + type: string + - description: 下一贴文的最大 ID，用于分页。 + in: query + name: max_id + type: string + produces: + - application/activity+json + responses: + "200": + description: "" + schema: + $ref: '#/definitions/swaggerCollection' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + summary: 获取用户发件箱 + tags: + - s2s/federation + /users/{username}/statuses/{status}/replies: + get: + description: |- + 获取贴文的回复集合。 + + 注意，如果 `page` 为 `false`，则响应将是一个带有 `first` 页的 Collection，如下所示。 + + 如果 `page` 为 `true`，则响应将是一个不带 `Collection` 包装的单个 `CollectionPage`。 + + 请求需要 HTTP 签名。 + operationId: s2sRepliesGet + parameters: + - description: 账户的用户名。 + in: path + name: username + required: true + type: string + - description: 贴文的 ID。 + in: path + name: status + required: true + type: string + - default: false + description: 按 CollectionPage 返回响应。 + in: query + name: page + type: boolean + - default: false + description: 返回仅来自贴文所有者以外的账户的回复。 + in: query + name: only_other_accounts + type: boolean + - description: 下一贴文的最小 ID，用于分页。 + in: query + name: min_id + type: string + produces: + - application/activity+json + responses: + "200": + description: "" + schema: + $ref: '#/definitions/swaggerCollection' + "400": + description: bad request 无效请求 + "401": + description: unauthorized 未授权 + "403": + description: forbidden 禁止 + "404": + description: not found 未找到 + summary: 获取贴文回复 + tags: + - s2s/federation +schemes: + - https + - http +securityDefinitions: + OAuth2 Application: + flow: application + scopes: + write:accounts: grants write access to accounts 授予对账户的写入权限 + tokenUrl: https://example.org/oauth/token + type: oauth2 + OAuth2 Bearer: + authorizationUrl: https://example.org/oauth/authorize + flow: accessCode + scopes: + admin: 授予对所有内容的管理权限 + admin:accounts: 授予对账户的管理权限 + read: 授予对所有内容的读取权限 + read:accounts: 授予对账户的读取权限 + read:blocks: 授予对屏蔽的读取权限 + read:custom_emojis: 授予对自定义表情的读取权限 + read:favourites: 授予对点赞的读取权限 + read:filters: 授予对过滤规则的读取权限 + read:follows: 授予对关注的读取权限 + read:lists: 授予对列表的读取权限 + read:media: 授予对媒体的读取权限 + read:mutes: 授予对静音的读取权限 + read:notifications: 授予对通知的读取权限 + read:search: 授予对搜索的读取权限 + read:statuses: 授予对贴文的读取权限 + read:streaming: 授予对流式 API 的读取权限 + read:user: 授予对用户级信息的读取权限 + write: 授予对所有内容的写入权限 + write:accounts: 授予对账户的写入权限 + write:blocks: 授予对屏蔽的写入权限 + write:filters: 授予对过滤规则的写入权限 + write:follows: 授予对关注的写入权限 + write:lists: 授予对列表的写入权限 + write:media: 授予对媒体的写入权限 + write:mutes: 授予对静音的写入权限 + write:statuses: 授予对贴文的写入权限 + write:user: 授予对用户级信息的写入权限 + tokenUrl: https://example.org/oauth/token + type: oauth2 +swagger: "2.0" diff --git a/docs/locales/zh/api/throttling.md b/docs/locales/zh/api/throttling.md new file mode 100644 index 000000000..ec1485f96 --- /dev/null +++ b/docs/locales/zh/api/throttling.md @@ -0,0 +1,35 @@ +# 请求限流 + +GoToSocial 使用请求限流来限制与你的实例 API 的开放连接数。这是为了防止在一个账户含有成千上万粉丝的情况下，贴文被转发或回复时，避免你的实例意外被 DDOS 攻击（即所谓的[死亡之拥](https://en.wikipedia.org/wiki/Slashdot_effect)）。 + +限流意味着只有有限数量的 HTTP 请求可同时处理，以便为每个请求提供快速响应，迅速完成。其原理是，快速处理较少的请求比同时尝试处理所有传入请求并每个用时多秒要好。 + +限流应用于不同的路由组，类似于[速率限制](./ratelimiting.md)的组织方式，因此，如果 API 的某个部分正处于限流状态，并不意味着所有部分都如此。 + +限流限制基于 GoToSocial 可用的 CPU 数量和配置值 `advanced-throttling-multiplier` 来计算。其计算方式如下： + +- 处理中的队列限制 = CPU 数量 * CPU 乘数。 +- 待处理队列限制 = 处理中的队列限制 * CPU 乘数。 + +对于默认乘数（8），得出以下值： + +```text +1 个 CPU = 08 处理中，064 待处理 +2 个 CPU = 16 处理中，128 待处理 +4 个 CPU = 32 处理中，256 待处理 +8 个 CPU = 64 处理中，512 待处理 +``` + +新请求如果超过处理中的限制将被放入待处理队列，并在有空位时进行处理（即当前处理中的请求完成时）。无法处理且无法放入待处理队列的请求将收到 HTTP 代码 [503 - 服务不可用](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503)，并设置 `Retry-After` 头为 `30`（秒），以表示调用者稍后重试。 + +请求不会无限期地保留在待处理队列中：如果待处理中的请求无法在 30 秒内处理，它们也将收到 503 代码和 30 秒的重试等待。 + +## 限流常见问题 + +### 我可以调节请求限流吗？ + +可以。只需根据你的 CPU 性能更改 `advanced-throttling-multiplier` 的值，CPU 性能强可调高，性能相对较弱可调低。 + +### 我可以禁用请求限流吗？ + +可以。只需将 `advanced-throttling-multiplier` 设置为 `0` 或更小。这样将完全禁用 HTTP 请求限流，并尝试同时处理所有传入请求。如果你想使用外部服务或反向代理进行请求限流，并且不希望 GoToSocial 干扰你的设置，这是很有用的。 diff --git a/docs/locales/zh/configuration/accounts.md b/docs/locales/zh/configuration/accounts.md new file mode 100644 index 000000000..8e80d511b --- /dev/null +++ b/docs/locales/zh/configuration/accounts.md @@ -0,0 +1,44 @@ +# 账户 + +## 设置 + +```yaml +########################### +##### 账户配置 ##### +########################### + +# 服务器上账户创建与维护的配置，以及新账户的默认设置。 + +# 布尔值。允许人们通过 /signup 表单提交新的注册请求。 +# +# 选项: [true, false] +# 默认: false +accounts-registration-open: false + +# 布尔值。注册请求是否需要提交请求理由（例如，解释他们为何想加入此实例）？ +# 选项: [true, false] +# 默认: true +accounts-reason-required: true + +# 布尔值。允许此实例上的账户为其个人资料页面和贴文设置自定义 CSS。 +# 启用此设置将允许账户通过 /user 设置页面上传自定义 CSS， +# 然后这些 CSS 将在账户的个人资料和贴文的网页视图中呈现。 +# +# 对于允许公开注册的实例，**强烈建议**将此设置保持为 'false'， +# 因为设置为 true 允许恶意账户使其个人资料页面具有误导性、不可用 +# 或对访问者甚至危险。换句话说，只有在你信任实例上的用户不会产生有害 CSS 时， +# 才应启用此设置。 +# +# 无论此值设置为何，任何上传的 CSS 都不会联合到其他实例，仅在*本*实例上的个人资料和贴文中显示。 +# +# 选项: [true, false] +# 默认: false +accounts-allow-custom-css: false + +# 整数值。如果 accounts-allow-custom-css 为 true，则为此实例上账户上传的 +# CSS 允许的字符长度。如果 accounts-allow-custom-css 为 false，则无效。 +# +# 示例: [500, 5000, 9999] +# 默认: 10000 +accounts-custom-css-length: 10000 +``` diff --git a/docs/locales/zh/configuration/advanced.md b/docs/locales/zh/configuration/advanced.md new file mode 100644 index 000000000..4e0741196 --- /dev/null +++ b/docs/locales/zh/configuration/advanced.md @@ -0,0 +1,152 @@ +# 高级设置 + +提供高级设置选项是为了让管理员能够根据自己的喜好调整实例。 + +这些设置已设置为合理的默认值，所以大多数服务器管理员不需要更改或考虑它们。 + +**如果你不知道自己在做什么，修改这些设置可能会导致实例出错**。 + +## 设置 + +```yaml +############################# +##### 高级设置 ##### +############################# + +# 与HTTP超时、安全性、Cookie等相关的高级设置。 +# +# 只有在你了解自己在做什么的情况下才调整这些设置！ +# +# 大多数用户不需要（也不应该）修改这些设置，因为它们被设为合理的默认值，改变可能导致问题。 +# +# 不过，这些设置提供给服务器管理员用于性能或安全原因的调整。 + +# 字符串。GoToSocial设置的Cookie的SameSite属性值。 +# 默认设置为 'lax' 以确保OIDC流程不会中断，这通常是可以的。 +# 如果你希望加强实例对抗CSRF攻击，并且不介意某些登录相关操作可能中断，可以将其设置为 'strict'。 +# +# 关于此设置的概述，请参见： +# https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite +# +# 选项: ["lax", "strict"] +# 默认: "lax" +advanced-cookies-samesite: "lax" + +# 整数。允许单个IP地址在5分钟内对每个路由分组的请求数量。 +# 如果超出此数量，将返回429 HTTP错误代码。 +# +# 如果你发现需要调整此限制，是因为它经常被超出，你应首先验证 `trusted-proxies` 配置是否正确。 +# 在许多情况下，超出速率限制是因为你的实例将所有传入请求视为来自*相同的IP地址*（你可以通过查看实例日志中的客户端IP来验证）。 +# 如果是这种情况，尝试在调整此速率限制设置*之前*将该IP地址添加到你的`trusted-proxies`中！ +# +# 如果将此设置为0或更少，则完全禁用速率限制。 +# +# 示例: [1000, 500, 0] +# 默认: 300 +advanced-rate-limit-requests: 300 + +# 字符串数组。要从速率限制中排除的CIDR范围。 +# CIDR范围内的任何IP的请求将不受速率限制，并且这些请求不会设置速率限制头。 +# +# 对于IPv6，我们只考虑到/64的子网。如果你想开放更大的前缀，你需要列出多个前缀。 +# +# 在以下示例情况下（可能还有很多其他情况），这可能很有用： +# +# 1. 你已设置使用API的自动化服务，但它频繁被限速，你信任它没有滥用实例。资源 +# +# 2. 你和多人共用同一路由器/NAT登录同一实例，所以你们都有相同的IP地址，并且不断相互限速。 +# +# 3. 你主要使用自己的家庭网络访问实例，并希望豁免家庭网络的速率限制。 +# +# 调整此设置时需要小心，因为如果设置范围过宽，可能会使速率限制变得无用。如果不确定，建议宁少勿多，并根据需要调整。 +# +# 示例: ["192.168.0.0/16", "2001:DB8:FACE:CAFE::/64"] +# 默认: [] +advanced-rate-limit-exceptions: [] + +# 整数。每个CPU、每个路由分组允许的开放请求数量，以应用HTTP请求限制。 +# 超出计算限制的请求将被保留在一个等待队列中，最长30秒然后处理或超时。 +# 不在等待队列中的请求将返回状态503，并设置“Retry-After”头为30秒。 +# +# 开放请求限制为可用CPU * 乘数；等待队列限制为限制 * 乘数。 +# +# 乘数为8的示例值： +# +# 1 cpu = 08 开放, 064 等待 +# 2 cpu = 16 开放, 128 等待 +# 4 cpu = 32 开放, 256 等待 +# +# 乘数为4的示例值： +# +# 1 cpu = 04 开放, 016 等待 +# 2 cpu = 08 开放, 032 等待 +# 4 cpu = 16 开放, 064 等待 +# +# 乘数为8是合理的默认值，但对于运行在性能非常高的硬件上的实例，你可能希望增加它；对于使用非常慢的CPU的实例，你可能希望减少它。 +# +# 如果将此设置为0或更少，将完全禁用HTTP请求限制。 +# +# 示例: [8, 4, 9, 0] +# 默认: 8 +advanced-throttling-multiplier: 8 + +# 持续时间。用于响应限速请求的“retry-after”头值的时间段。 +# 最小分辨率为1秒。 +# +# 示例: [30s, 10s, 5s, 1m] +# 默认: "30s" +advanced-throttling-retry-after: "30s" + +# 整数。用于通过ActivityPub发送消息的固定协程数量的CPU倍数。 +# 消息将被批量处理并推送到单一队列，倍数 * CPU数的协程将提取对垒中的消息并尝试发送。 +# 这可以用于限制对外站收件箱的并发发布，防止当有很多关注者的账户发布贴文时实例CPU使用率激增。 +# +# 如果将此设置为0或更少，无论CPU数量如何，都只会使用1个发送者。这可能在你有非常严格的网络或CPU限制时有用。 +# +# 乘数为2的示例值（默认）： +# +# 1 cpu = 2 个并发发送者 +# 2 cpu = 4 个并发发送者 +# 4 cpu = 8 个并发发送者 +# +# 乘数为4的示例值： +# +# 1 cpu = 4 个并发发送者 +# 2 cpu = 8 个并发发送者 +# 4 cpu = 16 个并发发送者 +# +# 乘数<1的示例值： +# +# 1 cpu = 1 个并发发送者 +# 2 cpu = 1 个并发发送者 +# 4 cpu = 1 个并发发送者 +advanced-sender-multiplier: 2 + +# 字符串数组。为实例设置Content-Security-Policy头时，要添加到'img-src'和'media-src'中的额外URI。 +# +# 这可以用于在浏览器中查看实例页面和个人资料时，允许加载来自额外来源（如S3桶等）的资源。 +# +# 由于非代理的S3存储将在实例启动时被探测以生成正确的Content-Security-Policy，你可能永远都不需要修改此设置，但把它包括在内是因为“可配置项（通常）越多越好”。 +# +# 参见: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP +# +# 示例: ["s3.example.org", "some-bucket-name.s3.example.org"] +# 默认: [] +advanced-csp-extra-uris: [] + +# 字符串。用于此实例的HTTP请求头过滤模式。 +# +# "block" -- 只有明确被请求头过滤规则阻止的请求会被拒绝（除非它们被明确允许）。 +# +# "allow" -- 只有明确被请求头过滤规则允许的请求会被接受（除非它们被明确阻止）。 +# 此模式被视为实验性功能，并且几乎肯定会破坏对你实例的访问，除非非常小心。 +# +# "" -- 请求头过滤禁用。 +# +# 有关阻止和允许模式的更多详细信息，请查看文档： +# https://docs.gotosocial.org/zh-cn/latest/admin/request_filtering_modes +# +# 选项: ["block", "allow", ""] +# 默认: "" +advanced-header-filter-mode: "" +``` \ No newline at end of file diff --git a/docs/locales/zh/configuration/database.md b/docs/locales/zh/configuration/database.md new file mode 100644 index 000000000..cddd1d186 --- /dev/null +++ b/docs/locales/zh/configuration/database.md @@ -0,0 +1,192 @@ +# 数据库 + +GoToSocial 将贴文、账号等存储在数据库中。可以选择使用 [SQLite](https://sqlite.org/index.html) 或 [Postgres](https://www.postgresql.org/)。 + +默认情况下，GoToSocial 使用 Postgres，但可以轻松更改。 + +## SQLite + +顾名思义，SQLite 是 GoToSocial 可用的最轻量级的数据库类型。它以简单的文件格式存储条目，通常与 GoToSocial 二进制文件位于同一目录。SQLite 非常适合小规模实例和单板计算机，使用专用数据库对它们来说过于复杂。 + +要配置 GoToSocial 使用 SQLite，将 `db-type` 更改为 `sqlite`。此时 `address` 设置将是一个文件名而不是地址，所以你需要将其更改为 `sqlite.db` 或类似名称。 + +注意，`:memory:` 设置将使用 *内存数据库*，当你的 GoToSocial 实例停止运行时，内存将被清除。这仅用于测试，绝不适用于运行正式实例，因此*不要这样做*。 + +## Postgres + +Postgres 是较重的数据库格式，适用于需要扩展性能的大型实例，或者需要在 GoToSocial 实例之外的专用计算机上运行数据库的情况（或运行数据库集群等复杂应用）。 + +你可以使用 Unix 套接字连接或 TCP 连接到 Postgres，这取决于你设置的 `db-address` 值。 + +GoToSocial 还支持使用 SSL/TLS 通过 TCP 连接到 Postgres。如果你在不同的计算机上运行 Postgres，并通过 IP 地址或主机名连接它（而不是仅在本地运行），那么 SSL/TLS **至关重要**，以防止数据泄露！ + +使用 Postgres 时，GoToSocial 期望你已经在数据库中创建了 `db-user` 并拥有 `db-database` 的所有权。 + +例如，如果你设置了： + +```text +db: + [...] + user: "gotosocial" + password: "some_really_good_password" + database: "gotosocial" +``` + +那么你应该已经在 Postgres 中创建了数据库 `gotosocial`，并将其所有权授予 `gotosocial` 用户。 + +执行这些操作的 psql 命令如下： + +```psql +create database gotosocial with locale 'C.UTF-8' template template0; +create user gotosocial with password 'some_really_good_password'; +grant all privileges on database gotosocial to gotosocial; +``` + +GoToSocial 使用 ULIDs（全局唯一且按字典顺序可排序的标识符），这在非英文排序环境中不起作用。因此，创建数据库时使用 `C.UTF-8` 地区设置很重要。在已经使用非 C 地区初始化的系统上，必须使用 `template0` 原始数据库模板才能进行。 + +如果你希望使用特定选项连接到 Postgres，可以使用 `db-postgres-connection-string` 定义连接字符串。如果 `db-postgres-connection-string` 已定义，则所有其他与数据库相关的配置字段将被忽略。例如，可以使用 `db-postgres-connection-string` 连接到 `mySchema`，用户名为 `myUser`，密码为 `myPass`，在 `localhost` 上，数据库名称为 `db`： + +```yaml +db-postgres-connection-string: 'postgres://myUser:myPass@localhost/db?search_path=mySchema' +``` + +## 设置 + +```yaml +############################ +##### 数据库配置 ###### +############################ + +# GoToSocial 数据库连接的相关配置 + +# 字符串。数据库类型。 +# 选项: ["postgres","sqlite"] +# 默认: "postgres" +db-type: "postgres" + +# 字符串。数据库地址或参数。 +# +# 对于 Postgres，这应该是数据库可以访问的地址或套接字。 +# +# 对于 Sqlite，这应该是你的 sqlite 数据库文件的路径。比如，/opt/gotosocial/sqlite.db。 +# 如果在指定路径不存在该文件，会自动创建。 +# 如果只提供了文件名（没有目录），那么数据库将创建在 GoToSocial 二进制文件的同一目录中。 +# 如果 `address` 设置为 :memory:，将使用内存数据库（没有文件）。 +# 警告: :memory: 应该仅用于测试目的，不应在其他情况下使用。 +# +# 示例: ["localhost","my.db.host","127.0.0.1","192.111.39.110",":memory:", "sqlite.db"] +# 默认: "" +db-address: "" + +# 整数。数据库连接的端口。 +# 示例: [5432, 1234, 6969] +# 默认: 5432 +db-port: 5432 + +# 字符串。数据库连接的用户名。 +# 示例: ["mydbuser","postgres","gotosocial"] +# 默认: "" +db-user: "" + +# 字符串。数据库连接使用的密码 +# 示例: ["password123","verysafepassword","postgres"] +# 默认: "" +db-password: "" + +# 字符串。要在提供的数据库类型中使用的数据库名称。 +# 示例: ["mydb","postgres","gotosocial"] +# 默认: "gotosocial" +db-database: "gotosocial" + +# 字符串。禁用、启用或要求数据库的 SSL/TLS 连接。 +# 如果为 "disable"，则不会尝试 TLS 连接。 +# 如果为 "enable"，则会尝试 TLS，但不会检查数据库证书（适用于自签名证书）。 +# 如果为 "require"，则需要 TLS 进行连接，并且必须提供有效证书。 +# 选项: ["disable", "enable", "require"] +# 默认: "disable" +db-tls-mode: "disable" + +# 字符串。用于数据库证书验证的主机的 CA 证书路径。 +# 如果留空，仅使用主机证书。 +# 如果填写，则会加载证书并添加到主机证书中。 +# 示例: ["/path/to/some/cert.crt"] +# 默认: "" +db-tls-ca-cert: "" + +# 整数。乘以 CPU 数量以设置允许总数的打开数据库连接（使用和空闲）。 +# 你可以使用此设置来调整你的数据库连接行为，但大多数管理员不需要更改它。 +# +# 乘数 8 的示例值： +# +# 1 cpu = 08 打开的连接 +# 2 cpu = 16 打开的连接 +# 4 cpu = 32 打开的连接 +# +# 乘数 4 的示例值： +# +# 1 cpu = 04 打开的连接 +# 2 cpu = 08 打开的连接 +# 4 cpu = 16 打开的连接 +# +# 乘数 8 是一个合理的默认值，但你可能希望为在非常高性能硬件上运行的实例增加此值，或为使用非常慢的 CPU 的实例减少此值。 +# +# 请注意！！：此设置目前仅适用于 Postgres。SQLite 将始终使用 1 个连接，无论此处设置为何。这种行为将在实现更好的 SQLITE_BUSY 处理时更改。 +# 更多详情请参见 https://github.com/superseriousbusiness/gotosocial/issues/1407。 +# +# 示例: [16, 8, 10, 2] +# 默认: 8 +db-max-open-conns-multiplier: 8 + +# 字符串。SQLite 日志模式。 +# 仅适用于 SQLite -- 否则不使用。 +# 如果设置为空字符串，则使用 sqlite 默认值。 +# 参见: https://www.sqlite.org/pragma.html#pragma_journal_mode +# 示例: ["DELETE", "TRUNCATE", "PERSIST", "MEMORY", "WAL", "OFF"] +# 默认: "WAL" +db-sqlite-journal-mode: "WAL" + +# 字符串。SQLite 同步模式。 +# 仅适用于 SQLite -- 否则不使用。 +# 如果设置为空字符串，则使用 sqlite 默认值。 +# 参见: https://www.sqlite.org/pragma.html#pragma_synchronous +# 示例: ["OFF", "NORMAL", "FULL", "EXTRA"] +# 默认: "NORMAL" +db-sqlite-synchronous: "NORMAL" + +# 字节大小。SQlite 缓存大小。 +# 仅适用于 SQLite -- 否则不使用。 +# 如果设置为空字符串或零，则使用 sqlite 默认值（2MiB）。 +# 参见: https://www.sqlite.org/pragma.html#pragma_cache_size +# +# 缓存并非越大越好。它们需要针对工作负载进行调整。默认设置对于大多数实例应该已足够，不应该更改。 +# 如果你确实更改它，请确保在 GoToSocial 帮助频道求助时提到这一点。 +# +# 示例: ["0", "2MiB", "8MiB", "64MiB"] +# 默认: "8MiB" +db-sqlite-cache-size: "8MiB" + +# 持续时间。SQlite 忙等待时间。 +# 仅适用于 SQLite -- 否则不使用。 +# 如果设置为空字符串或零，则使用 sqlite 默认值。 +# 参见: https://www.sqlite.org/pragma.html#pragma_busy_timeout +# 示例: ["0s", "1s", "30s", "1m", "5m"] +# 默认: "30m" +db-sqlite-busy-timeout: "30m" + +# 字符串。完整的数据库连接字符串 +# +# 此连接字符串仅适用于 Postgres。当定义此字段时，所有其他与数据库相关的配置字段将被忽略。 +# 此字段允许你微调与 Postgres 的连接。 +# +# 示例: ["postgres://user:pass@localhost/db?search_path=gotosocial", "postgres://user:pass@localhost:9999/db"] +# 默认: "" +db-postgres-connection-string: "" + +cache: + # cache.memory-target 设置一个目标限制， + # 应用程序将尝试将其缓存保持在此限制内。 + # 这是基于内存对象的估计大小，因此绝对不精确。 + # 示例: ["100MiB", "200MiB", "500MiB", "1GiB"] + # 默认: "100MiB" + memory-target: "100MiB" +``` \ No newline at end of file diff --git a/docs/locales/zh/configuration/general.md b/docs/locales/zh/configuration/general.md new file mode 100644 index 000000000..56b1388d4 --- /dev/null +++ b/docs/locales/zh/configuration/general.md @@ -0,0 +1,121 @@ +# 基础配置 + +GoToSocial 的基础配置，包括域名、端口、绑定地址和传输协议等基本内容。 + +这里*真正*需要设置的只有 `host`，也就是你实例可以访问的域名，可能还需要设置 `port`。 + +## 设置 + +```yaml +########################### +##### 通用配置 ###### +########################### + +# 字符串。应用程序使用的日志级别，必须是小写。 +# 选项: ["trace","debug","info","warn","error","fatal"] +# 默认: "info" +log-level: "info" + +# 布尔值。当日志级别设置为 debug 或 trace 时记录数据库查询。 +# 这一设置会产生详细的日志，因此最好在你尝试定位问题时才启用。 +# 选项: [true, false] +# 默认: false +log-db-queries: false + +# 布尔值。在日志行中包含客户端 IP。 +# 选项: [true, false] +# 默认: true +log-client-ip: true + +# 字符串。日志行中时间戳的格式。 +# 如果设置为空字符串，则时间戳将完全从日志中省略。 +# +# 该格式必须符合 Go 的 time.Layout 规定， +# 详见 https://pkg.go.dev/time#pkg-constants。 +# +# 示例: ["2006-01-02T15:04:05.000Z07:00", ""] +# 默认: "02/01/2006 15:04:05.000" +log-timestamp-format: "02/01/2006 15:04:05.000" + +# 字符串。内部使用的应用程序名称。 +# 示例: ["My Application","gotosocial"] +# 默认: "gotosocial" +application-name: "gotosocial" + +# 字符串。在首页显示的用户。如果没有设置用户，将显示默认的首页。 +# 示例: "admin" +# 默认: "" +landing-page-user: "" + +# 字符串。可以访问到本实例的主机名。默认值为用于本地测试的 localhost， +# 但在实际运行时你*绝对*应该更改此设置，否则你的服务器将无法正常工作。 +# 在你的实例已经运行过一次后，请不要更改此项，否则会导致问题！ +# 示例: ["gts.example.org","some.server.com"] +# 默认: "localhost" +host: "localhost" + +# 字符串。在交换账户信息时使用的域名。当你希望服务器位于 +# "gts.example.org"，但希望账户域名为 "example.org" 时，这会更好看， +# 或更加简短易记。 +# +# 为使此设置正常工作，你需要将 "example.org/.well-known/webfinger" 的请求 +# 重定向到 "gts.example.org/.well-known/webfinger"，以便 GtS 正常处理它们。 +# +# 你还应该以同样的方式重定向 "example.org/.well-known/nodeinfo" 的请求。 +# +# 你还应该以同样的方式重定向 "example.org/.well-known/host-meta" 的请求。 +# 这个端点被许多客户端用于在主机名和账户域名不同时发现 API 端点。 +# +# 空字符串（即，未设置）表示将使用 'host' 的相同值。 +# +# 在你的服务器已经运行过一次后请不要更改此项，否则会导致问题！ +# +# 在更改此设置前，请阅读安装指南的相应部分： +# https://docs.gotosocial.org/zh-cn/latest/advanced/host-account-domain/ +# +# 示例: ["example.org","server.com"] +# 默认: "" +account-domain: "" + +# 字符串。服务器从外界可访问的协议。 +# +# 仅在本地测试时，才需将其更改为 HTTP！在 99.99% 的情况下你不应该更改此项！ +# +# 这应该是你的服务器实际可以访问的 URI 的协议部分。 +# 因此，即使你在处理 SSL 证书的反向代理之后运行 GoToSocial， +# 而不是使用内置的 letsencrypt，它仍然应该是 https，而不是 http。 +# +# 再次强调，仅在本地测试时才需将其更改为 HTTP！如果你将其设置为 `http`，启动实例， +# 然后再更改为 `https`，你的实例上已有的用户的 URI 生成过程将被破坏。在 100% 知道自己在做什么时才更改此设置。 +# +# 选项: ["http","https"] +# 默认: "https" +protocol: "https" + +# 字符串。GoToSocial 服务器绑定的地址。 +# 可以是 IPv4 地址或 IPv6 地址（用方括号括起来），或者是主机名。 +# 默认值为绑定到所有接口，使服务器可以被其他机器访问。在大多数场景中无需更改此项。 +# 如果你在与代理同一台机器上使用反向代理设置 GoToSocial， +# 建议将其设置为 "localhost" 或等效值，以防止代理被绕过。 +# 示例: ["0.0.0.0", "172.128.0.16", "localhost", "[::]", "[2001:db8::fed1]"] +# 默认: "0.0.0.0" +bind-address: "0.0.0.0" + +# 整数。GoToSocial 网页服务器和 API 的监听端口。如果你在反向代理和/或 Docker 容器中运行， +# 请将其设置为任意值（或保留默认值），并确保正确转发。 +# 如果你启用了内建 letsencrypt 并在本机直接运行 GoToSocial， +# 可能希望将其设置为 443（标准 https 端口），除非你有其他服务正在使用该端口。 +# 此项*不得*与下面指定的 letsencrypt 端口相同，除非禁用 letsencrypt。 +# 示例: [443, 6666, 8080] +# 默认: 8080 +port: 8080 + +# 字符串数组。用于通过反向代理确定真实客户端 IP 的受信任代理的 CIDR 或 IP 地址。 +# 如果你的实例在 Docker 容器中运行，且位于 Traefik 或 Nginx 后，请添加你的 Docker 网络的子网， +# 或 Docker 网络的网关，和/或反向代理的地址（如果不是运行在本机上）。 +# 示例: ["127.0.0.1/32", "172.20.0.1"] +# 默认: ["127.0.0.1/32", "::1"] (本地主机 ipv4 + ipv6) +trusted-proxies: + - "127.0.0.1/32" + - "::1" +``` \ No newline at end of file diff --git a/docs/locales/zh/configuration/httpclient.md b/docs/locales/zh/configuration/httpclient.md new file mode 100644 index 000000000..b04cfa487 --- /dev/null +++ b/docs/locales/zh/configuration/httpclient.md @@ -0,0 +1,67 @@ +# HTTP 客户端 + +## 设置 + +```yaml +################################ +##### HTTP 客户端设置 ##### +################################ + +# GoToSocial 用于向外站资源发送请求的 HTTP 客户端连接设置 +# （如贴文获取、媒体获取、向对方收件箱发信等）。 + +http-client: + + # 持续时间。对外 HTTP 请求的超时时长。 + # 如果超时，连接到外站服务器的请求将被中断。 + # 设置为 0s 表示没有超时：不建议这样做！ + # 示例: ["5s", "10s", "0s"] + # 默认: "10s" + timeout: "10s" + + ######################################## + #### 保留的例外 IP 范围 ###### + ######################################## + # + # 在提供的 IPv4/v6 CIDR 范围内显式允许或屏蔽出站连接。 + # + # 默认情况下，作为基本的安全预防措施，GoToSocial 屏蔽大多数“特殊用途” + # IP 范围内的出站连接。然而，具有更复杂设置（代理、特殊 NAT 环境等）的管理员 + # 可能希望显式覆盖一个或多个被屏蔽的范围。 + # + # 以下每个允许/屏蔽配置选项接受一个 IPv4 和/或 IPv6 CIDR 字符串数组。 + # 例如，要覆盖本地站的 IPv4 和 IPv6 建立连接的硬编码屏蔽，请设置： + # + # allow-ips: ["127.0.0.1/32", "::1/128"]. + # + # 你也可以使用 YAML 多行数组来定义这些，但要注意缩进。 + # + # 建立连接时，GoToSocial 将首先检查目标是否在显式允许的 IP 范围内， + # 然后检查显式屏蔽的 IP 范围，再检查默认（硬编码）屏蔽的 IP 范围， + # 首次命中允许匹配项时返回 OK，首次命中屏蔽匹配项时返回不 OK， + # 或如果没有命中，则默认返回 OK。 + # + # 和所有安全设置一样，最好从最严格的配置开始，根据用例放宽， + # 而不是从最宽松的配置开始，然后再试图亡羊补牢。记住这一点： + # - 除非你有充分的理由，否则不要修改这些设置，只在你知道自己在做什么的情况下修改。 + # - 添加显式允许的例外 IP 段时，尽可能使用最小 CIDR。 + # + # 有关保留/特殊范围，请参阅： + # - https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml + # - https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml + # + # allow-ips 和 block-ips 默认都是空数组。 + allow-ips: [] + block-ips: [] + + # 布尔值。禁用对外站服务器 TLS 证书的验证。 + # 设置为 'true' 时，当外站服务器提供无效或自签名证书时， + # GoToSocial 不会报错。 + # + # 该设置仅用于测试！如果你在生产环境中启用， + # 就会让你的服务器容易受到中间人攻击！不要更改此设置， + # 除非你非常清楚自己在做什么以及为什么这么做。 + # + # 默认: false + tls-insecure-skip-verify: false +``` diff --git a/docs/locales/zh/configuration/index.md b/docs/locales/zh/configuration/index.md new file mode 100644 index 000000000..7eba92186 --- /dev/null +++ b/docs/locales/zh/configuration/index.md @@ -0,0 +1,138 @@ +# 配置概述 + +GoToSocial 力求尽可能让所有属性可配置，以适应多种不同的使用场景。 + +我们尽量提供合理的默认值，但在运行 GoToSocial 实例时，你需要进行*一些*配置管理。 + +## 配置方法 + +配置 GoToSocial 实例有三种不同的方法，这些方法可以根据你的设置进行组合。 + +### 配置文件 + +配置 GoToSocial 最简单的方法是将配置文件传递给 `gotosocial server start` 命令，例如： + +```bash +gotosocial --config-path ./config.yaml server start +``` + +该命令需要一个 [YAML](https://en.wikipedia.org/wiki/YAML) 或 [JSON](https://en.wikipedia.org/wiki/JSON) 格式的文件。 + +可以在[这里](https://github.com/superseriousbusiness/gotosocial/blob/main/example/config.yaml)找到示例配置文件，其中包含每个配置字段的解释、默认值和示例值。此示例文件也包含在每个发行版的下载资源中。 + +建议创建你自己的配置文件，只更改你需要改变的设置。这可以确保在每次发布时，你不必合并默认值的更改或者增删未从默认值更改的配置设置。 + +#### 在容器中挂载 + +你可能需要在容器中挂载一个 `config.yaml`，因为某些设置不容易通过环境变量或命令行标志管理。 + +为此，请在主机上创建一个 `config.yaml`，将其挂载到容器中，然后告诉 GoToSocial 读取该配置文件。可以通过将容器的运行命令设置为 `--config-path /path/inside/container/to/config.yaml` 或使用 `GTS_CONFIG_PATH` 环境变量来实现这一点。 + +对于 docker compose，可以这样修改配置： + +```yaml +services: + gotosocial: + command: ["--config-path", "/gotosocial/config.yaml"] + volumes: + - type: bind + source: /path/on/the/host/to/config.yaml + target: /gotosocial/config.yaml + read_only: true +``` + +或者，通过环境变量来修改配置： + +```yaml +services: + gotosocial: + environment: + GTS_CONFIG_PATH: /gotosocial/config.yaml + volumes: + - type: bind + source: /path/on/the/host/to/config.yaml + target: /gotosocial/config.yaml + read_only: true +``` + +对于 Docker 或 Podman 命令行，需要传递一个 [符合规范的挂载参数](https://docs.podman.io/en/latest/markdown/podman-run.1.html#mount-type-type-type-specific-option)。 + +在使用 `docker run` 或 `podman run` 时，传递 `--config-path /gotosocial/config.yaml` 作为命令，例如： + +```sh +podman run \ + --mount type=bind,source=/path/on/the/host/to/config.yaml,destination=/gotosocial/config.yaml,readonly \ + docker.io/superseriousbusiness/gotosocial:latest \ + --config-path /gotosocial/config.yaml +``` + +使用 `GTS_CONFIG_PATH` 环境变量： + +```sh +podman run \ + --mount type=bind,source=/path/on/the/host/to/config.yaml,destination=/gotosocial/config.yaml,readonly \ + --env 'GTS_CONFIG_PATH=/gotosocial/config.yaml' \ + docker.io/superseriousbusiness/gotosocial:latest +``` + +### 环境变量 + +你也可以通过设置[环境变量](https://en.wikipedia.org/wiki/Environment_variable)来配置 GoToSocial。这些环境变量遵循的格式为： + +1. 在配置标志前加上 `GTS_`。 +2. 全部使用大写。 +3. 将短横线（`-`）替换为下划线（`_`）。 + +例如，如果不想在 config.yaml 中设置 `media-image-max-size` 为 `2097152`，你可以改为设置环境变量： + +```text +GTS_MEDIA_IMAGE_MAX_SIZE=2097152 +``` + +如果对于环境变量名称有疑问，只需查看你正在使用的子命令的 `--help`。 + +### 命令行标志 + +最后，你可以使用命令行标志来设置配置值，这些标志是在运行 `gotosocial` 命令时直接传递的。例如，不在 config.yaml 或环境变量中设置 `media-image-max-size`，你可以直接通过命令行传递值： + +```bash +gotosocial server start --media-image-max-size 2097152 +``` + +如果不确定哪些标志可用，请检查 `gotosocial --help`。 + +## 优先级 + +上述配置方法按列出的顺序相互覆盖。 + +```text +命令行标志 > 环境变量 > 配置文件 +``` + +也就是说，如果你在配置文件中将 `media-image-max-size` 设置为 `2097152`，但*也*设置了环境变量 `GTS_MEDIA_MAX_IMAGE_SIZE=9999999`，则最终值将为 `9999999`，因为环境变量比 config.yaml 中设置的值具有*更高的优先级*。 + +命令行标志具有最高优先级，因此如果你设置了 `--media-image-max-size 13121312`，无论你在其他地方设置了什么，最终值都将为 `13121312`。 + +这意味着在你只想尝试改变一件事，但不想编辑配置文件的情况下，可以临时使用环境变量或命令行标志来设置那个东西。 + +## 默认值 + +*大多数*配置参数都提供了合理的默认值，除了必须自定义值的情况。 + +请查看[示例配置文件](https://github.com/superseriousbusiness/gotosocial/blob/main/example/config.yaml)以获取默认值，或运行 `gotosocial --help`。 + +## `GTS_WAZERO_COMPILATION_CACHE` + +启动时，GoToSocial 会将嵌入的 WebAssembly `ffmpeg` 和 `ffprobe` 二进制文件编译为 [Wazero](https://wazero.io/) 兼容模块，这些模块用于媒体处理，无需任何外部依赖。 + +为了加快 GoToSocial 的启动时间，你可以在首次启动时缓存已编译的模块，这样 GoToSocial 就不必在每次启动时从头开始编译它们。 + +你可以通过将环境变量 `GTS_WAZERO_COMPILATION_CACHE` 设置为一个目录来指示 GoToSocial 存储 Wazero 工件，该目录将由 GtS 用于存储两个大小约为 ~50MiB 的小型工件（总计约 ~100MiB）。 + +要了解此方法的示例，请参见 [docker-compose.yaml](https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/example/docker-compose/docker-compose.yaml) 和 [gotosocial.service](https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/example/gotosocial.service) 示例文件。 + +如果你希望在 systemd 或 Docker 之外为 GtS 提供此值，可以在启动 GtS 服务器时通过以下方式进行： + +```bash +GTS_WAZERO_COMPILATION_CACHE=~/gotosocial/.cache ./gotosocial --config-path ./config.yaml server start +``` diff --git a/docs/locales/zh/configuration/instance.md b/docs/locales/zh/configuration/instance.md new file mode 100644 index 000000000..e1c8c8251 --- /dev/null +++ b/docs/locales/zh/configuration/instance.md @@ -0,0 +1,115 @@ +# 站点 + +## 设置 + +```yaml +########################### +##### 站点配置 ##### +########################### + +# 与实例间联合、隐藏/显示页面等相关的配置。 + +# 字符串数组。BCP47 语言标签，用于指示本站用户的首选语言。 +# +# 如果你提供了这些标签，请按照从最优先到最次优先的顺序提供。 +# 但请注意，从此数组中省略某种语言并不意味着该语言不能在本站使用， +# 而只是表示不会将其作为为本站的首选语言展示。 +# +# 这里可以不提供任何条目；这样的话，你的站点将没有特定的首选语言。 +# +# 常用标签参考此处：https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags +# 所有当前标签参考此处：https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry +# +# 示例: ["zh", "zh-Hans", "zh-Hans-CN", "zh-Hant", "zh-Hant-TW", "en"] +# 默认值: [] +instance-languages: [] + +# 字符串。用于本站的联合模式。 +# +# "blocklist" -- 默认开放联合。只有被明确屏蔽的站点会被拒绝（除非它们被另外明确设定的允许规则放行）。 +# +# "allowlist" -- 默认关闭联合。只有被明确允许的站点才能与本站互动。 +# +# 关于屏蔽列表和允许列表模式的更多详细信息，请查阅文档： +# https://docs.gotosocial.org/zh-cn/latest/admin/federation_modes +# +# 选项: ["blocklist", "allowlist"] +# 默认值: "blocklist" +instance-federation-mode: "blocklist" + +# 布尔值。启用针对通过联合 API 进入本站的消息的启发式垃圾过滤。无论你在此处设置什么， +# 都仍将执行基本的相关性检查，但如果你被其他站点的垃圾信息骚扰，并希望更严格地过滤掉垃圾信息， +# 可以尝试启用此设置。 +# +# 这是一个实验性设置，可能会过滤掉合法信息，或未能过滤掉垃圾信息。建议仅在 +# Fediverse 出现垃圾信息潮时启用此设置，以保持站点的可用性。 +# +# 判断消息是否为垃圾信息的决策基于以下启发规则，依次进行，接收者 = 收到消息的账户，发送者 = 发送消息的外站账户。 +# +# 首先执行基本相关性检查 +# +# 1. 接收者关注了发送者。返回 OK。 +# 2. 贴文未提及接收者。返回 NotRelevant。 +# +# 如果 instance-federation-spam-filter = false，则现在返回 OK。 +# 否则进一步检查： +# +# 3. 接收者已锁定账号并被发送者关注。返回 OK。 +# 4. 提及五人或以上。返回 Spam。 +# 5. 接收者关注（请求关注）一个被提及账户。返回 OK。 +# 6. 贴文有媒体附件。返回 Spam。 +# 7. 贴文包含非提及、非话题标签的链接。返回 Spam。 +# +# 被识别为垃圾的信息将从本站删除，不会插入数据库或主页时间线或通知中。 +# +# 选项: [true, false] +# 默认值: false +instance-federation-spam-filter: false + +# 布尔值。允许未经认证的用户查询 /api/v1/instance/peers?filter=open 以查看与本站联合的站点列表。 +# 即使设置为 'false'，认证用户（本站成员）仍然可以查询该端点。 +# 选项: [true, false] +# 默认值: false +instance-expose-peers: false + +# 布尔值。允许未经认证的用户查询 /api/v1/instance/peers?filter=suspended 以查看被本站屏蔽/封禁的站点列表。 +# 即使设置为 'false'，认证用户（本站成员）仍然可以查询该端点。 +# +# 警告：将此变量设置为 'true' 可能导致你的站点被屏蔽列表爬虫攻击。 +# 参考: https://docs.gotosocial.org/zh-cn/latest/admin/domain_blocks/#block-announce-bots +# +# 选项: [true, false] +# 默认值: false +instance-expose-suspended: false + +# 布尔值。允许未经认证的用户查看 /about/suspended， +# 显示本站屏蔽/封禁站点的 HTML 渲染列表。 +# 选项: [true, false] +# 默认值: false +instance-expose-suspended-web: false + +# 布尔值。允许未经认证的用户查询 /api/v1/timelines/public 以查看本站的公共贴文列表。 +# 即使设置为 'false'，认证用户（本站成员）仍然可以查询该端点。 +# 选项: [true, false] +# 默认值: false +instance-expose-public-timeline: false + +# 布尔值。此标志是否将 GoToSocial 的 ActivityPub 消息发送到收件人的共享收件箱（如果可用）， +# 而不是将每条消息分别发送给应接收消息的每个主体。 +# +# 当发送给共享收件箱的多个收件人时，共享收件箱传递能显著减少网络负载（例如，大型 Mastodon 实例）。 +# +# 参考: https://www.w3.org/TR/activitypub/#shared-inbox-delivery +# +# 选项: [true, false] +# 默认值: true +instance-deliver-to-shared-inboxes: true + +# 布尔值。此标志将在 /api/v1/instance 中包含的版本字段中注入一个 Mastodon 版本。 +# 这个版本通常被 Mastodon 客户端用于 API 功能检测。通过注入一个与 Mastodon 兼容的版本， +# 可以促使那些客户端在 GoToSocial 上正常运行。 +# +# 选项: [true, false] +# 默认值: false +instance-inject-mastodon-version: false +``` diff --git a/docs/locales/zh/configuration/media.md b/docs/locales/zh/configuration/media.md new file mode 100644 index 000000000..399a13f44 --- /dev/null +++ b/docs/locales/zh/configuration/media.md @@ -0,0 +1,87 @@ +# 媒体 + +## 设置 + +```yaml +######################## +##### 媒体配置 ###### +######################## + +# 关于媒体上传（媒体，图片描述，表情符号）的配置。 + +# 大小。通过 API 上传的媒体最大大小（字节）。 +# +# 增大此限制可能导致其他服务器无法获取贴文中的媒体。 +# +# 示例: [2097152, 10485760, 40MB, 40MiB] +# 默认: 40MiB (41943040 字节) +media-local-max-size: 40MiB + +# 大小。从其他实例下载媒体的最大大小（字节）。 +# +# 降低此限制可能导致你的实例无法获取贴文中的媒体。 +# +# 示例: [2097152, 10485760, 40MB, 40MiB] +# 默认: 40MiB (41943040 字节) +media-remote-max-size: 40MiB + +# 整数。图像或视频描述所需的最小字符数。 +# 示例: [500, 1000, 1500] +# 默认: 0 （无要求） +media-description-min-chars: 0 + +# 整数。图像或视频描述允许的最大字符数。 +# 示例: [1000, 1500, 3000] +# 默认: 1500 +media-description-max-chars: 1500 + +# 大小。通过管理员 API 上传到本站的表情最大大小（字节）。 +# +# 默认值与 Mastodon 表情大小限制相同（50kb），这有助于实现良好的互操作性。提高此限制可能会影响表情在其他实例间的联合，需谨慎。 +# +# 示例: [51200, 102400, 50KB, 50KiB] +# 默认: 50KiB (51200 字节) +media-emoji-local-max-size: 50KiB + +# 大小。从其他实例下载表情的最大大小（字节）。 +# +# 默认值为 100kb，是 media-emoji-local-max-size 默认值的两倍。这在较高表情大小限制的实例间保持良好的互操作性，并且不会占用太多存储空间。 +# +# 示例: [51200, 102400, 100KB, 100KiB] +# 默认: 100KiB (102400 字节) +media-emoji-remote-max-size: 100KiB + +# 整数。添加到媒体处理池中的 ffmpeg+ffprobe 实例数量。 +# +# 增加此数量会加快并发媒体处理速度，但每增加一个实例将消耗约 250MB 的（峰值）内存。 +# +# 如果你有多余的 RAM，并且/或者你为超过 50 人提供服务（他们发布/查看大量媒体），你可以增加这个数值，但单用户实例或在受限（低内存）环境中运行 GoToSocial 时应保持为 1。 +# +# 如果将此数值设为 0 或更少，则会根据 GOMAXPROCS x 1 进行缩放，通常会在主机的每个 CPU 核上生成一个 ffmpeg 实例和一个 ffprobe 实例。 +# +# 示例: [1, 2, -1, 8] +# 默认: 1 +media-ffmpeg-pool-size: 1 + +# 以下媒体清理设置允许管理员自定义什么时候运行媒体清理 + 修剪作业及执行相关作业的频率，默认设置为相对合理（每晚午夜）。有关这些设置的具体操作及一些自定义示例，请参见文档: +# https://docs.gotosocial.org/zh-cn/latest/admin/media_caching#cleanup + +# 整数。从外站实例缓存媒体的天数，到期之后它们将从缓存中移除。当外站媒体从缓存中移除时，它会从存储中删除，但媒体的数据库条目将保留，以便用户请求时可以重新获取。 +# +# 如果设置为 0，外站实例的媒体将无限期缓存。 +# +# 示例: [30, 60, 7, 0] +# 默认: 7 +media-remote-cache-days: 7 + +# 字符串。24 小时格式的时间，格式为 hh:mm。 +# 示例: ["14:30", "00:00", "04:00"] +# 默认: "00:00" (午夜)。 +media-cleanup-from: "00:00" + +# 时长。媒体清理运行之间的间隔。 +# 每 24 小时多次清理不推荐并且可能是不必要的。将此值设置得过低（如每 10 分钟一次）可能会导致队列滞后并可能产生其他问题。 +# 示例: ["24h", "72h", "12h"] +# 默认: "24h"（每天一次）。 +media-cleanup-every: "24h" +``` diff --git a/docs/locales/zh/configuration/observability.md b/docs/locales/zh/configuration/observability.md new file mode 100644 index 000000000..c26b2b351 --- /dev/null +++ b/docs/locales/zh/configuration/observability.md @@ -0,0 +1,53 @@ +# 可观测性 + +这些设置允许你调整和配置某些与可观测性相关的行为。 + +## 指标 + +在启用指标之前，[请阅读指南](../advanced/metrics.md)，并确保你已为设置采取适当的安全措施。 + +## 设置 + +```yaml +################################## +##### 可观测性设置 ##### +################################## + +# 字符串。用于提取请求或跟踪ID的请求头名称。通常由负载均衡器或代理设置。 +# 默认值: "X-Request-Id" +request-id-header: "X-Request-Id" + +# 布尔值。启用基于OpenTelemetry的跟踪支持。 +# 默认值: false +tracing-enabled: false + +# 字符串。设置跟踪系统的传输协议。可以是 "grpc" 表示OTLP gRPC，或 "http" 表示OTLP HTTP。 +# 选项: ["grpc", "http"] +# 默认值: "grpc" +tracing-transport: "grpc" + +# 字符串。跟踪收集器的端点。使用gRPC或HTTP传输时，应提供不含协议方案的地址/端口组合。 +# 示例: ["localhost:4317"] +# 默认值: "" +tracing-endpoint: "" + +# 布尔值。禁用gRPC和HTTP传输协议的TLS。 +# 默认值: false +tracing-insecure-transport: false + +# 布尔值。启用基于OpenTelemetry的指标支持。 +# 默认值: false +metrics-enabled: false + +# 布尔值。为Prometheus指标端点启用HTTP基本认证。 +# 默认值: false +metrics-auth-enabled: false + +# 字符串。Prometheus指标端点的用户名。 +# 默认值: "" +metrics-auth-username: "" + +# 字符串。Prometheus指标端点的密码。 +# 默认值: "" +metrics-auth-password: "" +``` diff --git a/docs/locales/zh/configuration/oidc.md b/docs/locales/zh/configuration/oidc.md new file mode 100644 index 000000000..f4c6ef9bf --- /dev/null +++ b/docs/locales/zh/configuration/oidc.md @@ -0,0 +1,156 @@ +# OpenID Connect (OIDC) + +GoToSocial 支持 [OpenID Connect](https://openid.net/connect/)，这是一种基于 [OAuth 2.0](https://oauth.net/2/) 构建的身份验证协议，OAuth 2.0 是授权协议的行业标准协议之一。 + +这意味着你可以将 GoToSocial 连接到外部 OIDC 提供商，如 [Gitlab](https://docs.gitlab.com/ee/integration/openid_connect_provider.html)、[Google](https://cloud.google.com/identity-platform/docs/web/oidc)、[Keycloak](https://www.keycloak.org/) 或 [Dex](https://dexidp.io/)，并允许用户使用其凭据登录 GoToSocial。 + +在以下情况下，这非常方便： + +- 你在一个平台上运行多个服务（Matrix、Peertube、GoToSocial），并希望用户可以使用相同的登录页面登录所有服务。 +- 你希望将用户、账户、密码等的管理委托给外部服务，以简化管理。 +- 你已经在外部系统中有很多用户，不想在 GoToSocial 中手动重新创建他们。 + +!!! tip + 如果用户尚不存在，且你的 IdP 没有返回非空的 `email` 作为 claims 的一部分，登录将会失败。这个 email 需要在此实例中是唯一的。尽管我们使用 `sub` claim 将外部身份与 GtS 用户关联，但创建用户时需要一个与之关联的 email。 + +## 设置 + +GoToSocial 为 OIDC 提供以下配置设置，以下显示的是其默认值。 + +```yaml +####################### +##### OIDC CONFIG ##### +####################### + +# 配置与外部 OIDC 提供商（如 Dex、Google、Auth0 等）的身份验证。 + +# 布尔值。启用与外部 OIDC 提供商的身份验证。如果设置为 true，则其他 OIDC 选项也必须设置。 +# 如果设置为 false，则使用标准的内部 OAuth 流程，用户使用用户名/密码登录 GtS。 +# 选项: [true, false] +# 默认值: false +oidc-enabled: false + +# 字符串。oidc idp（身份提供商）的名称。这将在用户登录时显示。 +# 示例: ["Google", "Dex", "Auth0"] +# 默认值: "" +oidc-idp-name: "" + +# 布尔值。跳过对从 OIDC 提供商返回的令牌的正常验证流程，即不检查过期或签名。 +# 这应仅用于调试或测试，绝对不要在生产环境中使用，因为这极其不安全！ +# 选项: [true, false] +# 默认值: false +oidc-skip-verification: false + +# 字符串。OIDC 提供商 URI。这是 GtS 将用户重定向到的登录地址。 +# 通常这看起来像是一个标准的网页 URL。 +# 示例: ["https://auth.example.org", "https://example.org/auth"] +# 默认值: "" +oidc-issuer: "" + +# 字符串。在 OIDC 提供商处注册的此客户端的 ID。 +# 示例: ["some-client-id", "fda3772a-ad35-41c9-9a59-f1943ad18f54"] +# 默认值: "" +oidc-client-id: "" + +# 字符串。在 OIDC 提供商处注册的此客户端的密钥。 +# 示例: ["super-secret-business", "79379cf5-8057-426d-bb83-af504d98a7b0"] +# 默认值: "" +oidc-client-secret: "" + +# 字符串数组。向 OIDC 提供商请求的范围。返回的值将用于填充在 GtS 中创建的用户。 +# 'openid' 和 'email' 是必需的。 +# 'profile' 用于提取新创建用户的用户名。 +# 'groups' 是可选的，可以用于根据 oidc-admin-groups 确定用户是否为管理员。 +# 示例: 见 eg., https://auth0.com/docs/scopes/openid-connect-scopes +# 默认值: ["openid", "email", "profile", "groups"] +oidc-scopes: + - "openid" + - "email" + - "profile" + - "groups" + +# 布尔值。将通过 OIDC 进行身份验证的用户与现有用户基于其电子邮件地址进行关联。 +# 这主要用于迁移目的，即从使用不稳定 `email` claim 进行唯一用户标识的旧版 GtS 迁移。对于大多数用例，应设置为 false。 +# 选项: [true, false] +# 默认值: false +oidc-link-existing: false + +# 字符串数组。如果返回的 ID 令牌包含与 oidc-allowed-groups 中的某个组匹配的 'groups' claim，则该用户将在 GtS 实例上被授予访问权限。 +# 如果数组为空，则授予所有组权限。 +# 默认值: [] +oidc-allowed-groups: [] + +# 字符串数组。如果返回的 ID 令牌包含与 oidc-admin-groups 中的某个组匹配的 'groups' claim，则该用户将在 GtS 实例上被授予管理员权限。 +# 默认值: [] +oidc-admin-groups: [] +``` + +## 行为 + +在 GoToSocial 上启用 OIDC 后，默认登录页面会自动重定向到 OIDC 提供商的登录页面。 + +这意味着 OIDC 本质上 *替代* 了正常的 GtS 邮箱/密码登录流程。 + +由于 ActivityPub 标准的工作方式，你 _不能_ 在设置用户名后更改它。这与 OIDC 规范冲突，该规范不保证 `preferred_username` 字段是稳定的。 + +为了解决这个问题，我们要求用户在首次登录尝试时提供用户名。此字段预先填入 `preferred_username` claim 的值。 + +在认证后，GtS 存储由 OIDC 提供商提供的 `sub` claim。在后续的身份验证尝试中，这个 claim 被用作唯一的用户查找方式。 + +这使你可以在提供商级别更改用户名而不丢失对 GtS 账户的访问。 + +### 群组成员身份 + +大多数 OIDC 提供商允许在返回的 claims 中包含群组和群组成员身份的概念。GoToSocial 可以使用群组成员身份来确定从 OIDC 流中返回的用户是否应创建为管理员账户。 + +如果返回的 OIDC 群组信息中包含配置在 `oidc-admin-groups` 中的群组成员身份，则该用户将被创建/登录为管理员。 + +## 从旧版本迁移 + +如果你从使用不稳定 `email` claim 进行唯一用户标识的旧版 GtS 迁移过来，可以将 `oidc-link-existing` 配置设置为 `true`。如果无法为提供商返回的 ID 找到用户，则会根据 `email` claim 进行查找。如果成功，稳定 ID 将被添加到匹配的用户数据库中。 + +你应仅在有限时间内使用此功能，以避免恶意账户盗取。 + +## 提供商示例 + +### Dex + +[Dex](https://dexidp.io/) 是一个可以自行托管的开源 OIDC 提供商。安装 Dex 的过程不在本文档范围内，你可以在 [这里](https://dexidp.io/docs/) 查看 Dex 文档。 + +Dex 的优势在于它也用 Go 编写，像 GoToSocial 一样，这意味着它体积小、运行快，在低功耗系统上也能很好地运行。 + +要配置 Dex 和 GoToSocial 一起工作，在 Dex 配置的 `staticClients` 部分创建以下客户端： + +```yaml +staticClients: + - id: 'gotosocial_client' + redirectURIs: + - 'https://gotosocial.example.org/auth/callback' + name: 'GoToSocial' + secret: 'some-client-secret' +``` + +确保将 `gotosocial_client` 替换为你想要的客户端 ID，并将 `secret` 替换为一个合理长且安全的密钥（例如 UUID）。你还应该将 `gotosocial.example.org` 替换为 GtS 实例的 `host`，但保留 `/auth/callback` 不变。 + +然后，编辑 GoToSocial config.yaml 中的 `oidc` 部分如下： + +```yaml +oidc: + enabled: true + idpName: "Dex" + skipVerification: false + issuer: "https://auth.example.org" + clientID: "gotosocial_client" + clientSecret: "some-client-secret" + scopes: + - "openid" + - "email" + - "profile" + - "groups" +``` + +确保将 `issuer` 变量替换为你的 Dex 提供商设置。这应该是你的 Dex 实例的可访问到的确切 URI。 + +现在，重启 GoToSocial 和 Dex，以便新设置生效。 + +当你下次登录 GtS 时，你应该会被重定向到 Dex 的登录页面。登录成功后，你将返回到 GoToSocial。 diff --git a/docs/locales/zh/configuration/smtp.md b/docs/locales/zh/configuration/smtp.md new file mode 100644 index 000000000..0b8062a09 --- /dev/null +++ b/docs/locales/zh/configuration/smtp.md @@ -0,0 +1,78 @@ +# 邮件配置 (smtp) + +GoToSocial 支持通过[简单邮件传输协议](https://wikipedia.org/wiki/Simple_Mail_Transfer_Protocol)（即 **smtp**）向用户发送邮件。 + +配置 GoToSocial 发送邮件不是必需的，但它在发送确认邮件、通知以及处理密码重置请求等方面非常有用。 + +要使 GoToSocial 可以发送邮件，你需要一项支持 smtp 的邮件服务，可以在 GoToSocial 所运行的同一台机器上运行SMTP服务器，也可以使用像 [Mailgun](https://mailgun.com) 这样的外部服务。如果你的邮件提供商支持 smtp（请咨询他们—大多数都支持），也可能使用免费的个人电子邮件地址发送邮件，但如果发送大量邮件，可能会遇到问题。 + +要验证你的配置，你可以使用设置面板中的“管理 -> 操作 -> 邮件”部分来发送测试邮件。 + +## 设置 + +以下是 smtp 的配置选项： + +```yaml +####################### +##### SMTP 配置 ##### +####################### + +# 配置通过 smtp 服务器发送邮件。详情请见 https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol + +# 字符串。你想使用的 smtp 服务器的主机名。 +# 如果未设置，将不使用 smtp 发送邮件，你可以忽略其他设置。 +# 示例: ["mail.example.org", "localhost"] +# 默认值: "" +smtp-host: "" + +# 整数。用于连接 smtp 服务器的端口。 +# 在大多数情况下，你应使用端口 587。 +# 示例: [] +# 默认值: 0 +smtp-port: 0 + +# 字符串。与 smtp 服务器进行身份验证时使用的用户名。 +# 你的 smtp 服务应已提供给你。 +# 这通常是（但不总是）一个电子邮件地址。 +# 示例: ["maillord@example.org"] +# 默认值: "" +smtp-username: "" + +# 字符串。与 smtp 服务器进行身份验证时使用的密码。 +# 你的 smtp 服务应已提供给你。 +# 示例: ["1234", "password"] +# 默认值: "" +smtp-password: "" + +# 字符串。发送邮件的‘发件人’地址。 +# 示例: ["mail@example.org"] +# 默认值: "" +smtp-from: "" + +# 布尔值。如果为 true，当一封邮件有多个收件人时，每个收件人都将包含在收件人字段中，以便每个收件人可以看到其他谁收到了邮件，并且如果他们愿意，可以“回复所有人”。 +# +# 如果为 false，邮件将发送给未公开的收件人，并且每个收件人将看不到其他收件人。 +# +# 如果你希望通过“回复所有人”来讨论新的举报，可能需要将此设置更改为 'true'。 +# 默认值: false +smtp-disclose-recipients: false +``` + +请注意，如果你没有设置 `Host`，则 smtp 发送邮件将被禁用，其他设置将被忽略。GoToSocial 仍会记录（跟踪级别）如果启用 smtp 本可以发送的邮件。 + +## 什么时候发送电子邮件？ + +目前，电子邮件在以下场景中发送： + +- 向新用户通过注册页面或 API 创建新账户时，向其提交的电子邮件地址发送确认请求。 +- 当新账户通过上述渠道创建账户时，向实例管理员发送通知。 +- 当收到新的举报时，向所有活跃的实例管理员+站务发送通知。默认情况下，收件地址将位于密送列表中，但你可以通过设置 `smtp-disclose-recipients` 更改此行为。 +- 当举报被管理员关闭时，向举报创建者（若为本站用户）发送邮件。 + +## HTML 与纯文本 + +默认情况下，邮件以纯文本形式发送。目前，没有选项可以发送 html 格式的邮件，但如果有足够的需求，这可能会在以后添加。 + +## 自定义 + +如果你愿意，可以自定义用于生成邮件的模板。请按照 `web/templates` 中的示例进行操作。 diff --git a/docs/locales/zh/configuration/statuses.md b/docs/locales/zh/configuration/statuses.md new file mode 100644 index 000000000..c16abcc04 --- /dev/null +++ b/docs/locales/zh/configuration/statuses.md @@ -0,0 +1,38 @@ +# 贴文 + +## 设置 + +```yaml +########################### +##### 贴文配置 ##### +########################### + +# 有关创建贴文的配置和允许的限制。 + +# 整数值。新贴文允许的最大字符数， +# 包括内容警告（如果设置）。 +# +# 请注意，大幅高于默认值可能会影响联合。 +# +# 示例: [140, 500, 5000] +# 默认: 5000 +statuses-max-chars: 5000 + +# 整数值。创建新投票时允许的最大选项数量。 +# 请注意，大幅高于默认值可能会影响联合。 +# 示例: [4, 6, 10] +# 默认: 6 +statuses-poll-max-options: 6 + +# 整数值。创建新投票时每个选项允许的最大字符数。 +# 请注意，大幅高于默认值可能会影响联合。 +# 示例: [50, 100, 150] +# 默认: 50 +statuses-poll-option-max-chars: 50 + +# 整数值。新贴文可以附加的最大媒体文件数量。 +# 请注意，大幅高于默认值可能会影响联合。 +# 示例: [4, 6, 10] +# 默认: 6 +statuses-media-max-files: 6 +``` diff --git a/docs/locales/zh/configuration/storage.md b/docs/locales/zh/configuration/storage.md new file mode 100644 index 000000000..24bb40d45 --- /dev/null +++ b/docs/locales/zh/configuration/storage.md @@ -0,0 +1,189 @@ +# 存储 + +## 设置 + +```yaml +########################## +##### 存储配置指南 ##### +########################## + +# 用户创建上传内容（如视频、图片等）的存储配置。 + +# 字符串。要使用的存储后端类型。 +# 示例: ["local", "s3"] +# 默认: "local"（存储在本地磁盘上） +storage-backend: "local" + +# 字符串。用于存储文件的根目录。 +# 确保运行 GoToSocial 的用户/组有权限访问此目录，并能在其中创建新的子目录和文件。 +# 仅在使用本地存储后端时需要。 +# 示例: ["/home/gotosocial/storage", "/opt/gotosocial/datastorage"] +# 默认: "/gotosocial/storage" +storage-local-base-path: "/gotosocial/storage" + +# 字符串。S3 兼容服务的 API 端点。 +# 仅在使用 s3 存储后端时需要。 +# 示例: ["minio:9000", "s3.nl-ams.scw.cloud", "s3.us-west-002.backblazeb2.com"] +# GoToSocial 使用“DNS 风格”访问桶。 +# 如果你使用 Scaleways 对象存储，请移除端点地址中的“桶名称” +# 默认: "" +storage-s3-endpoint: "" + +# 布尔值。如果 S3 中存储的数据应通过 GoToSocial 代理而不是转发到预签名 URL，请将其设置为 true。 +# +# 在大多数情况下，你无需更改此设置，但如果你的桶提供商无法生成预签名 URL， +# 或者你的桶无法暴露给更广泛的互联网，这可能有用。 +# +# 默认: false +storage-s3-proxy: false + +# 字符串。用于重定向传入媒体请求的基本 URL。 +# +# 必须以“http://”或“https://”开头，并以无尾斜杠结尾。 +# +# 除非有正当理由，否则不要设置此值！对“常规”s3 使用没有必要，大多数管理员可以忽略此设置。 +# +# 如果设置，那么对实例的媒体文件服务器请求将被重定向到此 URL 而不是你的桶 URL，保留相关路径部分。 +# +# 如果你在 S3 桶前使用 CDN 代理，并希望通过 CDN 提供媒体，而不是直接从 S3 桶提供媒体，这会很有用。 +# +# 例如，如果你的 storage-s3-endpoint 值设置为“s3.my-storage.example.org”， +# 并且你设置了一个 CDN 以代理你的桶，从“cdn.some-fancy-host.org”提供服务， +# 那么你应该将 storage-s3-redirect-url 设置为“https://cdn.some-fancy-host.org”。 +# +# 这将允许你的 GoToSocial 实例*上传*数据到“s3.my-storage.example.org”， +# 但引导调用者从“https://cdn.some-fancy-host.org” *下载* 这些数据。 +# +# 如果 storage-backend 不是 s3，或者 storage-s3-proxy 为 true，则忽略此值。 +# +# 示例: ["https://cdn.some-fancy-host.org"] +# 默认: "" +storage-s3-redirect-url: "" + +# 布尔值。使用 SSL 进行 S3 连接。 +# +# 仅在本地测试时将此设置为 'false'。 +# +# 默认: true +storage-s3-use-ssl: true + +# 字符串。S3 凭证的访问密钥部分。 +# 请考虑使用环境变量设置此值，以避免通过配置文件泄露 +# 仅在使用 s3 存储后端时需要。 +# 示例: ["AKIAJSIE27KKMHXI3BJQ","miniouser"] +# 默认: "" +storage-s3-access-key: "" + +# 字符串。S3 凭证的秘密密钥部分。 +# 请考虑使用环境变量设置此值，以避免通过配置文件泄露 +# 仅在使用 s3 存储后端时需要。 +# 示例: ["5bEYu26084qjSFyclM/f2pz4gviSfoOg+mFwBH39","miniopassword"] +# 默认: "" +storage-s3-secret-key: "" + +# 字符串。存储桶的名称。 +# +# 如果你已经在 storage-s3-endpoint 中包含了你的桶名称， +# 此值将用作包含你数据的目录。 +# +# 存储桶必须在启动 GoToSocial 之前就已存在 +# +# 仅在使用 s3 存储后端时需要。 +# 示例: ["gts","cool-instance"] +# 默认: "" +storage-s3-bucket: "" +``` + +## AWS S3 配置 + +### 创建一个桶 + +GoToSocial 默认创建签名 URL，这意味着我们不需要在桶的策略上做重大更改。 + +1. 登录 AWS -> 选择 S3 作为服务。 +2. 点击创建桶 +3. 提供一个唯一名称，避免在名称中添加`.` +4. 不要更改公开访问设置（保持“屏蔽公开访问”模式） + +### IAM 配置 + +1. 创建一个具有程序化 API 访问权限的[新用户](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) +2. 在此用户上添加在线政策，将 `` 替换为你的桶名称 + ```json + { + "Statement": [ + { + "Effect": "Allow", + "Action": "s3:ListAllMyBuckets", + "Resource": "arn:aws:s3:::*" + }, + { + "Effect": "Allow", + "Action": "s3:*", + "Resource": [ + "arn:aws:s3:::", + "arn:aws:s3:::/*" + ] + } + ] + } + ``` +3. 为此用户创建一个[访问密钥](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) +4. 在上方配置中提供值 + * `storage-s3-endpoint` -> 你所在区域的 S3 API 端点，例如: `s3.ap-southeast-1.amazonaws.com` + * `storage-s3-access-key` -> 你为上面创建的用户获取的访问密钥 ID + * `storage-s3-secret-key` -> 你为上面创建的用户获取的秘密密钥 + * `storage-s3-bucket` -> 你刚刚创建的 `` + +### `storage-s3-redirect-url` + +如果你在 S3 桶前使用 CDN，并希望通过 CDN 提供媒体，而不是直接从 S3 桶提供媒体，你应将 `storage-s3-redirect-url` 设置为 CDN URL。 + +例如，如果你的 `storage-s3-endpoint` 值设置为 `s3.my-storage.example.org`，并且你设置了一个 CDN 来代理你的桶，从 `cdn.some-fancy-host.org` 提供服务，那么你应该将 `storage-s3-redirect-url` 设置为 `https://cdn.some-fancy-host.org`。 + +这将允许你的 GoToSocial 实例*上传*数据到 `s3.my-storage.example.org`，但引导调用者从 `https://cdn.some-fancy-host.org` *下载* 那些数据。 + +## 存储迁移 + +可以自由地在后端之间迁移。要做到这一点，你只需在不同的实现之间移动目录（及其内容）。 + +从一个后端迁移到另一个后端时，数据库中的外站账户的头像和资料卡横幅背景引用仍然指向旧存储后端，这可能导致它们在客户端中无法正确加载。这将在一段时间后自行解决，但你可以在下一次与外站账户交互时强制 GoToSocial 重新获取头像和封面。当 GoToSocial 不运行时，你可以在数据库上执行以下指令（执行后重启实例也可）。这将确保缓存被清除。 + +```sql +UPDATE accounts SET (avatar_media_attachment_id, avatar_remote_url, header_media_attachment_id, header_remote_url, fetched_at) = (null, null, null, null, null) WHERE domain IS NOT null; +``` + +### 从本地到 AWS S3 + +有多种工具可帮助你将数据从文件系统复制到 AWS S3 桶。 + +#### AWS CLI + +使用官方 [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide) + +```sh +aws s3 sync s3:// +``` + +#### s3cmd + +使用 [s3cmd](https://github.com/s3tools/s3cmd)，可以使用以下命令： + +```sh +s3cmd sync --add-header="Cache-Control:public, max-age=315576000, immutable" s3:// +``` + +### 从本地到 S3 兼容存储 + +这适用于任何 S3 兼容的存储，包括 AWS S3 本身。 + +#### Minio CLI + +你可以使用 [MinIO 客户端](https://docs.min.io/docs/minio-client-complete-guide.html)。要执行迁移，你需要使用客户端注册你的 S3 兼容后端，然后让它复制文件： + +```sh +mc alias set scw https://s3.nl-ams.scw.cloud +mc mirror scw/example-bucket/ +``` + +如果你想迁移回来，请交换 `mc mirror` 命令的参数顺序。 diff --git a/docs/locales/zh/configuration/syslog.md b/docs/locales/zh/configuration/syslog.md new file mode 100644 index 000000000..4e0ef75ae --- /dev/null +++ b/docs/locales/zh/configuration/syslog.md @@ -0,0 +1,40 @@ +# Syslog + +GoToSocial 可以将日志镜像到 [syslog](https://en.wikipedia.org/wiki/Syslog)，支持通过 udp/tcp 协议传输日志，或者直接连接到本地 syslog（例如，`/var/log/syslog`）。 + +如果你希望通过守护进程管理 GtS 并不想自行处理日志轮转等工作，使用此功能是非常有用的，因为它依赖于经过验证的实现。 + +在 syslog 中的日志看起来会像这样： + +```text +Dec 12 17:44:03 dilettante ./gotosocial[246860]: time=2021-12-12T17:44:03+01:00 level=info msg=connected to SQLITE database +Dec 12 17:44:03 dilettante ./gotosocial[246860]: time=2021-12-12T17:44:03+01:00 level=info msg=there are no new migrations to run func=doMigration +``` + +## 设置 + +```yaml +######################### +##### SYSLOG CONFIG ##### +######################### + +# 额外的 syslog 日志钩子的配置。请参阅 https://en.wikipedia.org/wiki/Syslog， +# 和 https://github.com/sirupsen/logrus/tree/master/hooks/syslog。 +# +# 当需要通过守护进程管理 GtS 并将日志发送到特定位置时(无论是发送到本地位置还是 syslog 服务器)，这些设置都很有用。 +# 大多数用户不需要修改这些设置。 + +# 布尔值。启用 syslog 日志钩子。日志将被镜像到配置的目标。 +# 选项: [true, false] +# 默认值: false +syslog-enabled: false + +# 字符串。指定将日志发送到 syslog 时使用的协议。留空以连接到本地 syslog。 +# 选项: ["udp", "tcp", ""] +# 默认值: "udp" +syslog-protocol: "udp" + +# 字符串。发送 syslog 日志的目标地址和端口。留空以连接到本地 syslog。 +# 默认值: "localhost:514" +syslog-address: "localhost:514" +``` diff --git a/docs/locales/zh/configuration/tls.md b/docs/locales/zh/configuration/tls.md new file mode 100644 index 000000000..5d92c9c5d --- /dev/null +++ b/docs/locales/zh/configuration/tls.md @@ -0,0 +1,64 @@ +# TLS + +你可以通过以下两种方式配置 TLS 支持： +* 内置支持 Lets Encrypt / ACME 兼容供应商 +* 从磁盘加载 TLS 文件 + +不能同时启用这两种方法。 + +注意，当使用从磁盘加载的 TLS 文件时，你需要在文件更改时重新启动实例。文件不会自动重新加载。 + +## 设置 + +```yaml +############################## +##### LETSENCRYPT 配置 ##### +############################## + +# 与自动获取和使用 LetsEncrypt HTTPS 证书相关的配置。 + +# 布尔值。是否为服务器启用 letsencrypt。 +# 如果为 false，这里的其余设置将被忽略。 +# 如果你的 GoToSocial 服务部署在 nginx 或 traefik 这样的反向代理后，请保持关闭状态。 +# 如果没有，请开启以便可以使用 https。 +# 选项：[true, false] +# 默认值：false +letsencrypt-enabled: false + +# 整数。监听 letsencrypt 证书挑战的端口。 +# 如果启用了 letsencrypt，则该端口必须可达，否则你将无法获取证书。 +# 如果没有启用 letsencrypt，则该端口将不会使用。 +# 这 *不能* 与上面指定的 webserver/API 端口相同。 +# 例子：[80, 8000, 1312] +# 默认值：80 +letsencrypt-port: 80 + +# 字符串。存储 LetsEncrypt 证书的目录。 +# 最好将其设置为存储目录中的子路径，以便于备份， +# 但如果其他服务也需要访问这些证书，你可能希望将它们移到别的地方。 +# 无论如何，请确保 GoToSocial 有权限写入/读取此目录。 +# 例子：["/home/gotosocial/storage/certs", "/acmecerts"] +# 默认值："/gotosocial/storage/certs" +letsencrypt-cert-dir: "/gotosocial/storage/certs" + +# 字符串。注册 LetsEncrypt 证书时使用的电子邮件地址。 +# 此电子邮件地址很可能是实例管理员的地址。 +# LetsEncrypt 将发送关于证书到期等的通知到此地址。 +# 例子：["admin@example.org"] +# 默认值："" +letsencrypt-email-address: "" + +############################## +##### 手动 TLS 配置 ##### +############################## + +# 字符串。磁盘上 PEM 编码文件的路径，包含证书链和公钥。 +# 例子：["/gotosocial/storage/certs/chain.pem"] +# 默认值："" +tls-certificate-chain: "" + +# 字符串。磁盘上 PEM 编码文件的路径，包含与 tls-certificate-chain 相关的私钥。 +# 例子：["/gotosocial/storage/certs/private.pem"] +# 默认值："" +tls-certificate-key: "" +``` diff --git a/docs/locales/zh/configuration/web.md b/docs/locales/zh/configuration/web.md new file mode 100644 index 000000000..553e511bb --- /dev/null +++ b/docs/locales/zh/configuration/web.md @@ -0,0 +1,21 @@ +# Web + +## 设置 + +```yaml +###################### +##### WEB CONFIG ##### +###################### + +# 与网页模板和发送邮件通知等相关的配置 + +# 字符串。GoToSocial 尝试加载 HTML 模板 (.tmpl 文件) 的目录。 +# 示例: ["/some/absolute/path/", "./relative/path/", "../../some/weird/path/"] +# 默认值: "./web/template/" +web-template-base-dir: "./web/template/" + +# 字符串。GoToSocial 试图提供静态网页资源（图片，脚本）的目录。 +# 示例: ["/some/absolute/path/", "./relative/path/", "../../some/weird/path/"] +# 默认值: "./web/assets/" +web-asset-base-dir: "./web/assets/" +``` diff --git a/docs/locales/zh/faq.md b/docs/locales/zh/faq.md new file mode 100644 index 000000000..555f0737d --- /dev/null +++ b/docs/locales/zh/faq.md @@ -0,0 +1,41 @@ +# 常见问题 + +## 用户界面在哪？ + +GoToSocial 的大部分内容只是一个裸服务端，用于通过第三方应用程序进行使用。可通过 [Semaphore](https://semaphore.social/) 在浏览器使用，可通过 [Tusky](https://tusky.app/) 在 Android 使用，可通过 [Feditext](https://github.com/feditext/feditext) 在 iOS、iPadOS 和 macOS 使用。这些应用程序兼容性最好。任何由 Mastodon API 提供的实例功能都应该可以工作，除非它们是 GoToSocial 尚不具备的功能。永久链接和个账户页是通过 GoToSocial 直接提供的，设置面板也是如此，但大多数交互都是通过应用程序完成的。 + +## 为什么我的贴文没有显示在我的账户页面上？ + +与 Mastodon 不同，GoToSocial 的默认贴文可见性是“不列出”。如果你希望某个内容在个人资料页面上可见，贴文必须设为公开可见。 + +## 为什么我的贴文没有在其他实例上显示？ + +首先检查上面提到的可见性。TODO: 解释如何调试常见的联合问题 + +## 为什么我频繁收到 HTTP 429 错误响应？ + +GoToSocial 默认配置了基于 IP 的[限流规则](./api/ratelimiting.md)，但在某些情况下无法准确识别外部 IP，会将所有连接视为来自相同位置。在这些情况下，需要禁用或重新配置限流。 + +## 为什么我频繁收到 HTTP 503 错误响应？ + +当你的实例负载过重且请求被限制时，会返回代码 503。可以根据需要调整此行为，或完全关闭，请参见[此处](./api/throttling.md)。 + +## 我总是收到 400 Bad Request 错误，且已经按照错误信息中的建议操作。该怎么办？ + +请确认 `host` 配置与 GoToSocial 所服务的域名（用户用来访问服务器的域名）匹配。 + +## 我在服务器日志中不断看到 'dial within blocked / reserved IP range'，无法从我的实例连接到一些实例，我该怎么办？ + +外站实例的 IP 地址可能位于 GoToSocial 出于安全原因而硬编码屏蔽的“特殊用途”IP 范围内。如果需要，你可以在配置文件中覆盖此设置。查看[HTTP 客户端文档](./configuration/httpclient.md)，并仔细阅读其中的警告！如果添加了明确的 IP 允许条目，需要重启 GoToSocial 实例以使配置生效。 + +## 我已部署实例并登录到客户端，但时间线为空，这是怎么回事？ + +要查看贴文，你需要开始关注其他人！一旦你关注了几个人，并且他们发布或转发了内容，你就会在时间线上看到这些内容。目前，GoToSocial 没有“回填”贴文的方法，即尚不能从其他实例获取之前的贴文，所以你只能看到你关注的人的新贴文。如果你想与他们的旧贴文互动，可以从他们的账户页中复制贴文链接，并将其粘贴到客户端的搜索栏中。 + +## 如何在某个实例上注册？ + +我们在 v0.16.0 中引入了注册流程。你想注册的实例必须手动启用注册功能，具体详见[此处](./admin/signups.md)。 + +## 为什么还在 Beta 阶段？ + +查看[当前 bug 列表](https://github.com/superseriousbusiness/gotosocial/issues?q=is%3Aissue+is%3Aopen+label%3Abug)和[路线图](https://github.com/superseriousbusiness/gotosocial/blob/main/ROADMAP.md)以获取更详细的信息。 diff --git a/docs/locales/zh/federation/access_control.md b/docs/locales/zh/federation/access_control.md new file mode 100644 index 000000000..6d5439b30 --- /dev/null +++ b/docs/locales/zh/federation/access_control.md @@ -0,0 +1,11 @@ +# 访问控制 + +GoToSocial 使用访问控制限制来保护用户和资源免受外站账户和实例的不必要互动。 + +如[HTTP 签名](#http-signatures)部分所示，GoToSocial 要求所有来自外站服务器的传入 `GET` 和 `POST` 请求必须签名。未签名的请求将被拒绝，并返回 http 代码 `401 Unauthorized`。 + +访问控制限制通过检查签名的 `keyId` （即谁拥有发出请求的公钥/私钥对）来实现。 + +首先，会将 `keyId` URI 的主机值与 GoToSocial 实例的已屏蔽（取消联合）的域列表进行检查。如果域名被检测到位于屏蔽列表，则 http 请求将立即以 http 代码 `403 Forbidden` 中止。 + +接下来，GoToSocial 将检查发出 http 请求的公钥所有者与请求目标资源的所有者之间是否存在（任一方向的）屏蔽。如果 GoToSocial 用户屏蔽了发出请求的外站账户，则请求将以 http 代码 `403 Forbidden` 中止。 diff --git a/docs/locales/zh/federation/actors.md b/docs/locales/zh/federation/actors.md new file mode 100644 index 000000000..b801a262f --- /dev/null +++ b/docs/locales/zh/federation/actors.md @@ -0,0 +1,368 @@ +# 行为体与行为体属性 + +## 收件箱 + +GoToSocial 按照 [ActivityPub 规范](https://www.w3.org/TR/activitypub/#inbox)，为行为体实现了收件箱。 + +如规范所述，[外站](https://www.w3.org/TR/activitypub/#delivery) 应通过向活动目标受众的每个收件箱发送 HTTP POST 请求，将活动传送到 GoToSocial 服务器。 + +GoToSocial 帐号目前没有实现 [共享收件箱](https://www.w3.org/TR/activitypub/#shared-inbox-delivery) 端点，但这可能会有所改变。当 GoToSocial 服务器上有多个行为体是活动受众时，对已传送活动的去重由 GoToSocial 处理。 + +对 GoToSocial 行为体收件箱的 POST 请求必须由发起活动的行为体进行正确地 [HTTP 签名](#http-signatures)。 + +可被接受的收件箱 POST `Content-Type` 头为： + +- `application/activity+json` +- `application/activity+json; charset=utf-8` +- `application/ld+json; profile="https://www.w3.org/ns/activitystreams"` + +未使用上述 `Content-Type` 头之一的收件箱 POST 请求将被拒绝，并返回 HTTP 状态码 [406 - Not Acceptable](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/406)。 + +有关可接受内容类型的更多信息，请参阅 ActivityPub 协议的 [服务器间交互](https://www.w3.org/TR/activitypub/#server-to-server-interactions) 部分。 + +对格式正确且已签名的收件箱 POST 请求，GoToSocial 将返回 HTTP 状态码 [202 - Accepted](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202)。 + +对格式错误的收件箱 POST 请求，将返回 HTTP 状态码 [400 - Bad Request](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400)。响应正文可能包含有关 GoToSocial 服务器为何认为请求内容格式错误的更多信息。对于代码 `400` 的回应，其他服务器不应重试交付活动。 + +即使 GoToSocial 返回 `202` 状态码，也可能不继续处理已传送的活动，具体取决于活动的发起者、目标和活动类型。ActivityPub 是一个广泛的协议，GoToSocial 并未涵盖每种活动和对象的组合。 + +## 发件箱 + +GoToSocial 按照 [ActivityPub 规范](https://www.w3.org/TR/activitypub/#outbox)，为行为体（即实例账户）实现了发件箱。 + +要获取某行为体最近发布的活动 [OrderedCollection](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-orderedcollection)，外站可以对用户的发件箱进行 `GET` 请求。其地址类似于 `https://example.org/users/whatever/outbox`。 + +服务器将返回以下结构的 OrderedCollection： + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "id": "https://example.org/users/whatever/outbox", + "type": "OrderedCollection", + "first": "https://example.org/users/whatever/outbox?page=true" +} +``` + +请注意，`OrderedCollection` 本身不包含项目。调用者必须解引用 `first` 页面以开始获取项目。例如，对 `https://example.org/users/whatever/outbox?page=true` 的 `GET` 请求将生成如下内容： + +```json +{ + "id": "https://example.org/users/whatever/outbox?page=true", + "type": "OrderedCollectionPage", + "next": "https://example.org/users/whatever/outbox?max_id=01FJC1Q0E3SSQR59TD2M1KP4V8&page=true", + "prev": "https://example.org/users/whatever/outbox?min_id=01FJC1Q0E3SSQR59TD2M1KP4V8&page=true", + "partOf": "https://example.org/users/whatever/outbox", + "orderedItems": [ + { + "id": "https://example.org/users/whatever/statuses/01FJC1MKPVX2VMWP2ST93Q90K7/activity", + "type": "Create", + "actor": "https://example.org/users/whatever", + "published": "2021-10-18T20:06:18Z", + "to": [ + "https://www.w3.org/ns/activitystreams#Public" + ], + "cc": [ + "https://example.org/users/whatever/followers" + ], + "object": "https://example.org/users/whatever/statuses/01FJC1MKPVX2VMWP2ST93Q90K7" + } + ] +} +``` + +`orderedItems` 数组最多包含 30 个条目。要获取超过此数量的条目，调用者可以使用响应中提供的 `next` 链接。 + +请注意，在返回的 `orderedItems` 中，所有活动类型都将是 `Create`。在每个活动中，`object` 字段将是由拥有发件箱的行为体创建的原始公共贴文的 AP URI（即 `Note`，`to` 字段中包含 `https://www.w3.org/ns/activitystreams#Public`，且不是对另一个贴文的回复）。调用者可以使用返回的 AP URI 来解引用这些 `Note` 的内容。 + +## 粉丝与关注集合 + +GoToSocial 将粉丝和关注的集合实现为 `OrderedCollection`。例如，对行为体的关注集合进行正确签名的 `GET` 请求将返回如下内容： + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "first": "https://example.org/users/someone/following?limit=40", + "id": "https://example.org/users/someone/following", + "totalItems": 397, + "type": "OrderedCollection" +} +``` + +从这里开始，你可以使用 `first` 页面开始获取项目。例如，对 `https://example.org/users/someone/following?limit=40` 的 `GET` 请求将产生如下内容： + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "id": "https://example.org/users/someone/following?limit=40", + "next": "https://example.org/users/someone/following?limit=40&max_id=01V1AY4ZJT4JK1NT271SH2WMGH", + "orderedItems": [ + "https://example.org/users/someone_else", + "https://somewhere.else.example.org/users/another_account", + [... 38 more entries here ...] + ], + "partOf": "https://example.org/users/someone/following", + "prev": "https://example.org/users/someone/following?limit=40&since_id=021HKBY346X7BPFYANPPJN493P", + "totalItems": 397, + "type": "OrderedCollectionPage" +} +``` + +然后，你可以使用 `next` 和 `prev` 端点在 OrderedCollection 中向下和向上翻页。 + +## 个人资料字段 + +与 Mastodon 和其他联邦宇宙软件类似，GoToSocial 允许用户在其个人资料上设置键/值对；这对于传达简短的信息如链接、代词、年龄等很有用。 + +为了与其他实现兼容，GoToSocial 使用与 Mastodon 相同的 schema.org PropertyValue 扩展，作为设置字段的行为体上的 `attachment` 数组值。例如，以下 JSON 显示了两个 PropertyValue 字段的账户： + +```json +{ + "@context": [ + "http://joinmastodon.org/ns", + "https://w3id.org/security/v1", + "https://www.w3.org/ns/activitystreams", + "http://schema.org" + ], + "attachment": [ + { + "name": "接受关注", + "type": "PropertyValue", + "value": "纯看个人心情" + }, + { + "name": "年龄", + "type": "PropertyValue", + "value": "120" + } + ], + "discoverable": false, + "featured": "http://example.org/users/flyingsloth/collections/featured", + "followers": "http://example.org/users/flyingsloth/followers", + "following": "http://example.org/users/flyingsloth/following", + "id": "http://example.org/users/flyingsloth", + "inbox": "http://example.org/users/flyingsloth/inbox", + "manuallyApprovesFollowers": true, + "name": "飞翔的树懒 :3", + "outbox": "http://example.org/users/flyingsloth/outbox", + "preferredUsername": "flyingsloth", + "publicKey": { + "id": "http://example.org/users/flyingsloth#main-key", + "owner": "http://example.org/users/flyingsloth", + "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtTc6Jpg6LrRPhVQG4KLz\n2+YqEUUtZPd4YR+TKXuCnwEG9ZNGhgP046xa9h3EWzrZXaOhXvkUQgJuRqPrAcfN\nvc8jBHV2xrUeD8pu/MWKEabAsA/tgCv3nUC47HQ3/c12aHfYoPz3ufWsGGnrkhci\nv8PaveJ3LohO5vjCn1yZ00v6osMJMViEZvZQaazyE9A8FwraIexXabDpoy7tkHRg\nA1fvSkg4FeSG1XMcIz2NN7xyUuFACD+XkuOk7UqzRd4cjPUPLxiDwIsTlcgGOd3E\nUFMWVlPxSGjY2hIKa3lEHytaYK9IMYdSuyCsJshd3/yYC9LqxZY2KdlKJ80VOVyh\nyQIDAQAB\n-----END PUBLIC KEY-----\n" + }, + "summary": "\u003cp\u003e只是一只普通树懒\u003c/p\u003e", + "tag": [], + "type": "Person", + "url": "http://example.org/@flyingsloth" +} +``` + +对于没有 `PropertyValue` 字段的行为体，`attachment` 属性将不设置。即，`attachment` 键值不会在行为体中出现（即使是空数组或 null 值也不会）。 + +尽管 `attachment` 在规范上不是一个有序集合，GoToSocial（还是为了与其他实现保持一致）仍会按应显示的顺序呈现 `attachment` 的 `PropertyValue` 字段。 + +GoToSocial 还将解析 GoToSocial 实例发现的外站行为体的 PropertyValue 字段，以便可以把它们展示给 GoToSocial 实例上的用户。 + +GoToSocial 默认允许设置最多 6 个 `PropertyValue` 字段，而 Mastodon 的默认值为 4 个。 + +## 置顶/特色贴文 + +GoToSocial 允许用户在他们的个人资料上置顶贴文。 + +在 ActivityPub 术语中，GoToSocial 在行为体的 [featured](https://docs.joinmastodon.org/spec/activitypub/#featured) 字段中指定的端点提供这些置顶贴文，格式为 [OrderedCollection](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-orderedcollection) 。该字段的值将被设置为类似 `https://example.org/users/some_user/collections/featured`。 + +通过向此端点发送经过签名的 GET 请求，外站实例可以解引用特色贴文集合，这将返回带有 `orderedItems` 字段，其中包含贴文 URI 列表的 `OrderedCollection`。 + +置顶多条 `Note` 的用户的 featured collection 示例： + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "id": "https://example.org/users/some_user/collections/featured", + "orderedItems": [ + "https://example.org/users/some_user/statuses/01GS7VTYH0S77NNXTP6W4G9EAG", + "https://example.org/users/some_user/statuses/01GSFY2SZK9TPCJFQ1WCCPGDRT", + "https://example.org/users/some_user/statuses/01GSCXY70MZCBFMH5EKJW9ENC8" + ], + "totalItems": 3, + "type": "OrderedCollection" +} +``` + +置顶单条 `Note` 的用户的 featured collection 示例： + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "id": "https://example.org/users/some_user/collections/featured", + "orderedItems": [ + "https://example.org/users/some_user/statuses/01GS7VTYH0S77NNXTP6W4G9EAG" + ], + "totalItems": 1, + "type": "OrderedCollection" +} +``` + +没有置顶 `Note` 的示例： + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "id": "https://example.org/users/some_user/collections/featured", + "orderedItems": [], + "totalItems": 0, + "type": "OrderedCollection" +} +``` + +与 Mastodon 和一些其他实现不同，GoToSocial 不会将在 `orderedItems` 的值中提供完整的 `Note` 表示。相反，它仅提供每个 `Note` 的 URI，外站服务器可以自行进一步解引用（如果它们已经在本地缓存了该 `Note` 则可以不执行此操作）。 + +作为集合一部分提供的一些 URI 可能指向仅限粉丝可见性的贴文，请求的 `Actor` 不一定有权限查看。外站服务器应确保进行适当的过滤（与其他任何类型的贴文一样），以确保这些贴文仅显示给有权查看的用户。 + +GoToSocial 和其他服务器实现之间的另一个区别是，当用户置顶或取消置顶贴文时，GoToSocial 不会向外站服务器发送更新。Mastodon 会通过发送 [Add](https://www.w3.org/TR/activitypub/#add-activity-inbox) 和 [Remove](https://www.w3.org/TR/activitypub/#remove-activity-inbox) 活动类型来进行，`object` 是被置顶或取消置顶的贴文，`target` 是发送 `Actor` 的 `featured` 集合。尽管在概念上这很合理，但这与 ActivityPub 协议建议不一致，因为活动的 `target`“不属于接收服务器，因此他们不能更新它”。 + +相反，建议外站仅定期轮询 GoToSocial 行为体的 `featured` 集合，并根据需要在其缓存表示中添加/删除贴文，以构建和更新 GoToSocial 用户置顶贴文的视图。 + +## 行为体迁移 / 别名 + +GoToSocial 支持通过 `Move` 活动以及行为体对象属性 `alsoKnownAs` 和 `movedTo` 从一个实例/服务器迁移到另一个。 + +### `alsoKnownAs` + +GoToSocial 支持使用 `alsoKnownAs` 行为体属性进行帐户别名，这是一个 [公认的 ActivityPub 扩展](https://www.w3.org/wiki/Activity_Streams_extensions#as:alsoKnownAs_property)。 + +#### 传入 + +在传入的 AP 消息中，GoToSocial 将查找行为体上的 `alsoKnownAs` 属性，该属性是行为体也可以通过的其他活动 IDs/URIs 构成的数组。 + +例如： + +```json +{ + "@context": [ + "http://joinmastodon.org/ns", + "https://w3id.org/security/v1", + "https://www.w3.org/ns/activitystreams", + "http://schema.org" + ], + "featured": "http://example.org/users/flyingsloth/collections/featured", + "followers": "http://example.org/users/flyingsloth/followers", + "following": "http://example.org/users/flyingsloth/following", + "id": "http://example.org/users/flyingsloth", + "inbox": "http://example.org/users/flyingsloth/inbox", + "manuallyApprovesFollowers": true, + "name": "飞翔的树懒 :3", + "outbox": "http://example.org/users/flyingsloth/outbox", + "preferredUsername": "flyingsloth", + "publicKey": {...}, + "summary": "\u003cp\u003e只是一只普通树懒\u003c/p\u003e", + "type": "Person", + "url": "http://example.org/@flyingsloth", + "alsoKnownAs": [ + "https://another-server.com/users/flyingsloth", + "https://somewhere-else.org/users/originalsloth" + ] +} +``` + +在上述 AP JSON 中，行为体 `http://example.org/users/flyingsloth` 已设置别名为其他行为体 `https://another-server.com/users/flyingsloth` 和 `https://somewhere-else.org/users/originalsloth`。 + +GoToSocial 将传入的 `alsoKnownAs` URI 存储在数据库中，但（当前）不会使用它们，除非用于验证 `Move` 活动（见下文）。 + +#### 传出 + +GoToSocial 用户可以通过 GoToSocial 客户端 API 在其账户上设置多个 `alsoKnownAs` URI。GoToSocial 会在存入数据库并在传出 AP 消息序列化之前验证这些 `alsoKnownAs` 别名是否为有效的行为体 URI。 + +然而，GoToSocial 并不验证用户在设置别名之前对那些 `alsoKnownAs` URI 的*所有权*；它期望外站自行进行验证，然后再采信任何传入的 `alsoKnownAs` 值。 + +例如，GoToSocial 实例中的用户 `http://example.org/users/flyingsloth` 可能会在他们的账户上设置 `alsoKnownAs: [ "https://unrelated-server.com/users/someone_else" ]`，GoToSocial 会如实传输此别名到其他服务器。 + +在这种情况下，`https://unrelated-server.com/users/someone_else` 或许不是 `flyingsloth`。`flyingsloth` 可能无意或恶意地设置了此别名。为了正确验证 `someone_else` 的所有权，外站应检查行为体 `https://unrelated-server.com/users/someone_else` 的 `alsoKnownAs` 属性是否包含 `http://example.org/users/flyingsloth` 条目。 + +换句话说，外站不应默认信任 `alsoKnownAs` 别名，而应确保在将别名视为有效之前，行为体之间存在**双向别名**。 + +### `movedTo` + +GoToSocial 使用 `movedTo` 属性标记账户已迁移。与 `alsoKnownAs` 不同，这不是一个被接受的 ActivityPub 扩展，但它已被 Mastodon 广泛推广，也在 `Move` 活动中使用。[参见 Mastodon 文档获取更多信息](https://documentation.sig.gy/spec/activitypub/#namespaces)。 + +#### 传入 + +对于传入的 AP 消息，GoToSocial 查找行为体上的 `movedTo` 属性，该属性设置为单个 ActivityPub 行为体 URI/ID。 + +例如： + +```json +{ + "@context": [ + "http://joinmastodon.org/ns", + "https://w3id.org/security/v1", + "https://www.w3.org/ns/activitystreams", + "http://schema.org" + ], + "featured": "http://example.org/users/flyingsloth/collections/featured", + "followers": "http://example.org/users/flyingsloth/followers", + "following": "http://example.org/users/flyingsloth/following", + "id": "http://example.org/users/flyingsloth", + "inbox": "http://example.org/users/flyingsloth/inbox", + "manuallyApprovesFollowers": true, + "name": "飞翔的树懒 :3", + "outbox": "http://example.org/users/flyingsloth/outbox", + "preferredUsername": "flyingsloth", + "publicKey": {...}, + "summary": "\u003cp\u003e只是一只普通树懒\u003c/p\u003e", + "type": "Person", + "url": "http://example.org/@flyingsloth", + "alsoKnownAs": [ + "https://another-server.com/users/flyingsloth" + ], + "movedTo": "https://another-server.com/users/flyingsloth" +} +``` + +在上述 JSON 中，行为体 `http://example.org/users/flyingsloth` 已设置别名为行为体 `https://another-server.com/users/flyingsloth` 并已迁移/转向该账户。 + +GoToSocial 将传入的 `movedTo` 值存储在数据库中，但除非行为体在进行移动之前发送了一个 `Move` 活动，否则不会认为帐户迁移已处理（见下文）。 + +### `Move` 活动 + +为了实际触发账户迁移，GoToSocial 使用 `Move` 活动，并将行为体 URI 作为对象和目标，例如： + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "id": "https://example.org/users/flyingsloth/moves/01HR9FDFCAGM7JYPMWNTFRDQE9", + "actor": "https://example.org/users/flyingsloth", + "type": "Move", + "object": "https://example.org/users/flyingsloth", + "target": "https://another-server.com/users/my_new_account_hurray", + "to": "https://example.org/users/flyingsloth/followers" +} +``` + +在上述 `Move` 中，行为体 `https://example.org/users/flyingsloth` 指示其账户正在迁移到 URI `https://another-server.com/users/my_new_account_hurray`。 + +### 迁入 + +在收到行为体收件箱中的 `Move` 活动时，GoToSocial 将首先通过以下检查验证 `Move`： + +1. 请求由 `actor` 签名。 +2. `actor` 和 `object` 字段相同（你不能迁移其他人的账户）。 +3. `actor` 尚未迁移到其他地方。 +4. `target` 是有效的行为体 URI：可检索、未封禁、未迁移，且不在接收到此 `Move` 的 GoToSocial 实例屏蔽的实例上。 +5. `target` 将 `alsoKnownAs` 设置为发送 `Move` 的 `actor`。在此示例中，`https://another-server.com/users/my_new_account_hurray` 必须具有 `alsoKnownAs` 值，其中包括 `https://example.org/users/flyingsloth`。 + +如果检查通过，则 GoToSocial 将通过将粉丝重定向到新账户来处理 `Move`： + +1. 选择此 GoToSocial 实例上执行 `Move` 的 `actor` 的所有粉丝。 +2. 对于以这种方式选择的每个本站粉丝，从该粉丝的账户发送关注请求到 `Move` 的 `target`。 +3. 删除针对“旧” `actor` 的所有关注。 + +这样做的最终结果是，在接收实例上 `https://example.org/users/flyingsloth` 的所有粉丝现在将关注 `https://another-server.com/users/my_new_account_hurray`。 + +GoToSocial 还会删除由执行 `Move` 的 `actor` 拥有的所有关注和待关注请求；由 `target` 帐户再次发送关注请求。 + +为了防止潜在的 DoS 向量，GoToSocial 对 `Move` 强制进行 7 天冷却期。一旦帐户成功转移，GoToSocial 将在上次迁移后的 7 天内不处理来自新帐户的进一步迁移活动。 + +#### 迁出 + +发送帐户迁移时，GoToSocial 以类似方式使用 `Move` 活动。当 GoToSocial 实例上的行为体想要执行 `Move` 时，GoToSocial 将首先检查和验证 `Move` 目标，并确保它具有等于执行 `Move` 的行为体的 `alsoKnownAs` 条目。在成功验证后，将向所有发起迁移的行为体的粉丝发送 `Move` 活动，为其指示 `Move` 的 `target`。GoToSocial 期望外站将相应的追随者迁移到 `target` 名下。 diff --git a/docs/locales/zh/federation/glossary.md b/docs/locales/zh/federation/glossary.md new file mode 100644 index 000000000..5214b0745 --- /dev/null +++ b/docs/locales/zh/federation/glossary.md @@ -0,0 +1,73 @@ +# 术语表 + +本文档描述了有关联合的一些常用术语。 + +## `ActivityPub` + +一种基于 ActivityStreams 数据格式的去中心化社交网络协议。参见 [这里](https://www.w3.org/TR/activitypub/)。 + +GoToSocial 在 与其它 GtS 服务器和其它联邦宇宙服务器（如 Mastodon, Pixelfed 等）通信时使用 ActivityPub 协议。 + +## `ActivityStreams` + +使用 JSON 表示潜在活动和已完成活动的模型/数据格式。参见 [这里](https://www.w3.org/TR/activitystreams-core/)。 + +GoToSocial 使用 ActivityStreams 数据模型与其他服务器进行 ActivityPub 通信。 + +## `Actor` (行为体) + +Actor 是一个可以执行某些活动（例如关注、点赞、创建贴文、转发等）的 ActivityStreams 对象。参见 [这里](https://www.w3.org/TR/activitypub/#actors)。 + +在 GoToSocial 中，每个账号/用户都是一个 actor。 + +## `Dereference` (解引用) + +“解引用”一个贴文或账户意味着向托管该贴文或账户的服务器发出 HTTP 请求，以获取其 ActivityStreams 表示。 + +GoToSocial 对外站服务器解引用贴文和账户，以将它们转换为 GoToSocial 可以理解和处理的模型。 + +以下是一些示例的详细说明： + +假设有人在 ActivityPub 服务器上搜索用户名 `@tobi@goblin.technology`。 + +他们的服务器会在 `goblin.technology` 上通过以下 URL 进行 webfinger 查询： + +```text +https://goblin.technology/.well-known/webfinger?resource=acct:tobi@goblin.technology +``` + +`goblin.technology` 服务器会返回一些 JSON 作为响应，类似于： + +```json +{ + "subject": "acct:tobi@goblin.technology", + "aliases": [ + "https://goblin.technology/users/tobi", + "https://goblin.technology/@tobi" + ], + "links": [ + { + "rel": "http://webfinger.net/rel/profile-page", + "type": "text/html", + "href": "https://goblin.technology/@tobi" + }, + { + "rel": "self", + "type": "application/activity+json", + "href": "https://goblin.technology/users/tobi" + } + ] +} +``` + +在链接部分，请求服务器会寻找类型为 `application/activity+json` 的链接，这表示用户的 ActivityStreams 表示。在此情况下，URL 是： + +```text +https://goblin.technology/users/tobi +``` + +上述 URL 是 `tobi` 在 `goblin.technology` 实例上的 用户/行为体 的 activitypub 表示的*引用*。它之所以被称为引用，是因为它不包含关于该用户的所有信息，只是信息所在位置的参考点。 + +现在，请求服务器将向该 URL 发送请求，以获得 `@tobi@goblin.technology` 的更完整表示，以符合 ActivityPub 规范。换句话说，服务器现在通过一个*引用*来获取它所引用的内容。这使得它*不再是一个引用*，因此称为*解引用*。 + +作为类比，考虑在书的目录中查找某些内容时的情况：首先你获得你感兴趣的材料所在的页码，这是一个引用。然后你翻到引用的页面查看内容，这就是解引用。 diff --git a/docs/locales/zh/federation/http_signatures.md b/docs/locales/zh/federation/http_signatures.md new file mode 100644 index 000000000..b4f2a17e9 --- /dev/null +++ b/docs/locales/zh/federation/http_signatures.md @@ -0,0 +1,85 @@ +# HTTP 签名 + +GoToSocial 要求所有发送到 ActivityPub 服务器的 `GET` 和 `POST` 请求都必须附带有效的 HTTP 签名。 + +GoToSocial 也会为其向其他服务器发送的所有 `GET` 和 `POST` 请求签名。 + +这种行为与 Mastodon 的 [AUTHORIZED_FETCH / "安全模式"](https://docs.joinmastodon.org/admin/config/#authorized_fetch) 等效。 + +GoToSocial 使用 [superseriousbusiness/httpsig](https://github.com/superseriousbusiness/httpsig) 库（从 go-fed 派生）来为发出的请求签名，并解析和验证传入请求的签名。该库严格遵循 [Cavage HTTP Signature RFC](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12)，这是其他实现（如 Mastodon、Pixelfed、Akkoma/Pleroma 等）使用的同一份 RFC。（此 RFC 后来被 [httpbis HTTP Signature RFC](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures) 取代，但尚未广泛实施。） + +## 查询参数 + +关于是否应该在用于生成和验证签名的 URL 中包含查询参数，HTTP 签名规范并无明确规定。 + +在历史上，GoToSocial 在签名中包含了查询参数，而大多数其他实现则没有。这导致在对 Collection 端点进行签名 GET 请求或验证签名的 GET 请求时（通常使用查询参数进行分页），出现了兼容性问题。 + +从 0.14 开始，GoToSocial 尝试同时签署和验证携带和不携带查询参数请求，以确保与其他实现更好的兼容性。 + +发送请求时，GtS 将首先尝试包含查询参数的情况。当收到外站服务器的 `401` 响应时，它将尝试在不包含查询参数的情况下重新发送请求。 + +接收请求时，GtS 将首先尝试验证包含查询参数的签名。如果签名验证失败，它将尝试在不包含查询参数的情况下重新验证签名。 + +详细信息请参见 [#894](https://github.com/superseriousbusiness/gotosocial/issues/894)。 + +## 传入请求 + +GoToSocial 的请求签名验证在 [internal/federation](https://github.com/superseriousbusiness/gotosocial/blob/main/internal/federation/authenticate.go) 中实现。 + +GoToSocial 将尝试按以下算法顺序解析签名，成功后将停止： + +```text +RSA_SHA256 +RSA_SHA512 +ED25519 +``` + +## 发出请求 + +GoToSocial 的请求签名在 [internal/transport](https://github.com/superseriousbusiness/gotosocial/blob/main/internal/transport/signing.go) 中实现。 + +一旦解决了 https://github.com/superseriousbusiness/gotosocial/issues/2991 ，GoToSocial 将使用 `(created)` 伪标头代替 `date`。 + +然而，目前在组装签名时： + +- 发出的 `GET` 请求使用 `(request-target) host date` +- 发出的 `POST` 请求使用 `(request-target) host date digest` + +GoToSocial 在签名中将 `algorithm` 字段设置为 `hs2019`，这一般意味着“从与 keyId 关联的元数据中导出算法”。生成签名时使用的实际算法是 `RSA_SHA256`，这与其他 ActivityPub 实现一致。在验证 GoToSocial 的 HTTP 签名时，外站服务器可以安全地假设该签名是使用 `sha256` 生成的。 + +## 特点 + +GoToSocial 在 `Signature` 标头中使用的 `keyId` 格式如下所示： + +```text +https://example.org/users/example_user/main-key +``` + +这不同于大多数其他实现，它们通常在 `keyId` URI 中使用片段 (`#`)。例如，在 Mastodon 上，用户的密钥会这样表示： + +```text +https://example.org/users/example_user#main-key +``` + +对于 Mastodon，用户的公钥作为该用户的 Actor 表示的一部分提供。GoToSocial 在提供用户的公钥时模仿了这种行为，但并不在 `main-key` 端点返回完整的 Actor（这可能包含敏感字段），而是仅返回 Actor 的部分存根。它如下所示： + +```json +{ + "@context": [ + "https://w3id.org/security/v1", + "https://www.w3.org/ns/activitystreams" + ], + "id": "https://example.org/users/example_user", + "preferredUsername": "example_user", + "publicKey": { + "id": "https://example.org/users/example_user/main-key", + "owner": "https://example.org/users/example_user", + "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzGB3yDvMl+8p+ViutVRG\nVDl9FO7ZURYXnwB3TedSfG13jyskoiMDNvsbLoUQM9ajZPB0zxJPZUlB/W3BWHRC\nNFQglE5DkB30GjTClNZoOrx64vLRT5wAEwIOjklKVNk9GJi1hFFxrgj931WtxyML\nBvo+TdEblBcoru6MKAov8IU4JjQj5KUmjnW12Rox8dj/rfGtdaH8uJ14vLgvlrAb\neQbN5Ghaxh9DGTo1337O9a9qOsir8YQqazl8ahzS2gvYleV+ou09RDhS75q9hdF2\nLI+1IvFEQ2ZO2tLk3umUP1ioa+5CWKsWD0GAXbQu9uunAV0VoExP4+/9WYOuP0ei\nKwIDAQAB\n-----END PUBLIC KEY-----\n" + }, + "type": "Person" +} +``` + +与 GoToSocial 联合的外站服务器应从 `publicKey` 字段提取公钥。然后，它们应该使用公钥的 `owner` 字段签名 `GET` 请求，进一步解引用 Actor 的完整版本。 + +这种行为是为了避免外站服务器对完整 Actor 端点进行未签名的 `GET` 请求引入的。然而，由于不合规且引发问题，此行为可能会在未来发生变化。在 [此问题](https://github.com/superseriousbusiness/gotosocial/issues/1186) 中进行跟踪。 diff --git a/docs/locales/zh/federation/index.md b/docs/locales/zh/federation/index.md new file mode 100644 index 000000000..1f1afde9d --- /dev/null +++ b/docs/locales/zh/federation/index.md @@ -0,0 +1,7 @@ +# 概述 + +本节文档包含与 GoToSocial 联合所需的各个 (ActivityPub/ActivityStreams) 元素的信息。 + +!!! info "Post 与 Status 的区别" + + 在文档中，post 与 status 这两个术语可以互换使用，指的是由用户创建的相同内容：一个（微型）博客条目，可能包含文本、媒体附件等。在中文文档中，我们统一使用“贴文”一词来指代这种内容。 diff --git a/docs/locales/zh/federation/moderation.md b/docs/locales/zh/federation/moderation.md new file mode 100644 index 000000000..ce506568a --- /dev/null +++ b/docs/locales/zh/federation/moderation.md @@ -0,0 +1,41 @@ +# 管理 + +## 举报 / 标记 + +与其他微博 ActivityPub 实现类似，GoToSocial 使用 [Flag](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-flag) 活动类型来向其他服务器传达用户举报信息。 + +### 发送举报 + +发送的 GoToSocial `Flag` 的 JSON 格式如下: + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "actor": "http://example.org/users/example.org", + "content": "此用户频繁骚扰其它用户", + "id": "http://example.org/reports/01GP3AWY4CRDVRNZKW0TEAMB5R", + "object": [ + "http://fossbros-anonymous.io/users/foss_satan", + "http://fossbros-anonymous.io/users/foss_satan/statuses/01FVW7JHQFSFK166WWKR8CBA6M" + ], + "type": "Flag" +} +``` + +`Flag` 的 `actor` 始终是创建该 `Flag` 的 GoToSocial 实例的实例行为体。这样做是为了保护创建举报的用户，实现部分的匿名性，以防止他们成为骚扰目标。 + +`Flag` 的 `content` 是由创建 `Flag` 的用户提交的一段文本，该文本应该向外站管理员提供创建举报的理由。如果用户没有提交理由，`content` 可能是空字符串，也可能不存在于 JSON 中。 + +`Flag` 的 `object` 字段的值可以是一个字符串（被举报用户的 ActivityPub `id`），或者是一个字符串数组，其中数组的第一个条目是被举报用户的 `id`，后续条目是一个或多个被举报的 `Note` / 贴文的 `id`。 + +`Flag` 活动会原样发送到被举报用户的 `inbox`（或共享收件箱）。它不会被包装在 `Create` 活动中。 + +### 接收举报 + +GoToSocial 假设接收到的举报会作为 `Flag` 活动发送到被举报用户的 `inbox`。它将按照创建发送 `Flag` 的相同方式解析接收到的 `Flag`，但有一个不同之处：它会尝试从 `object` 字段和 Misskey/Calckey 格式的 `content` 值中解析贴文的 URL，这些值包含内联的贴文 URL。 + +GoToSocial 不会假设接收到的 `Flag` 活动中会设置 `to` 字段。相反，它假定外站使用 `bto` 将 `Flag` 发送给其接收者。 + +接收到的有效 `Flag` 活动将作为举报提供给接收到举报的 GoToSocial 实例管理员，以便他们对被举报用户采取必要的管理措施。 + +除非 GtS 管理员选择通过其他渠道与被举报用户分享此信息，被举报用户本人不会看到举报信息，也不会收到被举报的通知。 diff --git a/docs/locales/zh/federation/posts.md b/docs/locales/zh/federation/posts.md new file mode 100644 index 000000000..a23081ed0 --- /dev/null +++ b/docs/locales/zh/federation/posts.md @@ -0,0 +1,924 @@ +# 帖文及其属性 + +## 话题标签 + +GoToSocial 用户可以在贴文中包含话题标签，用于向其他实例表明该用户希望将其贴文与其他使用相同话题标签的贴文加入同一分组，以便于发现。 + +GoToSocial 默认期望只有公开地址的贴文会按话题标签分组，这与其他 ActivityPub 服务器实现一致。 + +为了实现话题标签的联合，GoToSocial 在对象的 `tag` 属性中使用被广泛采用的 [ActivityStreams `Hashtag` 类型扩展](https://www.w3.org/wiki/Activity_Streams_extensions#as:Hashtag_type)。 + +以下是一条外发信息中的 `tag` 属性示例，包含自定义表情和一个话题标签： + +```json +"tag": [ + { + "icon": { + "mediaType": "image/png", + "type": "Image", + "url": "https://example.org/fileserver/01AY6P665V14JJR0AFVRT7311Y/emoji/original/01F8MH9H8E4VG3KDYJR9EGPXCQ.png" + }, + "id": "https://example.org/emoji/01F8MH9H8E4VG3KDYJR9EGPXCQ", + "name": ":rainbow:", + "type": "Emoji", + "updated": "2021-09-20T10:40:37Z" + }, + { + "href": "https://example.org/tags/welcome", + "name": "#welcome", + "type": "Hashtag" + } +] +``` + +当仅有一个话题标签时，`tag` 属性将是一个对象而非数组，如下所示： + +```json +"tag": { + "href": "https://example.org/tags/welcome", + "name": "#welcome", + "type": "Hashtag" +} +``` + +### 话题标签的 `href` 属性 + +GoToSocial 外发话题标签提供的 `href` URL 指向一个提供 `text/html` 的网页。 + +GoToSocial 对给定 `text/html` 的内容不做任何保证，外站不应该将 URL 解释为规范的 ActivityPub ID/URI 属性。`href` URL 仅作为可能包含该话题标签更多信息的一个端点。 + +## 提及 + +GoToSocial 用户可以在贴文中使用 `@[用户名]@[域名]` 格式提及其他用户。例如，如果一个 GoToSocial 用户想提及实例 `example.org` 上的用户 `someone`，可以在贴文中包含 `@someone@example.org`。 + +!!! info "提及与活动地址" + + 提及的表示不仅仅是美观问题，它们也会影响活动的地址。 + + 如果 GoToSocial 用户在 Note 中明确提及另一个用户，该用户的 URI 将始终包含在 Note 的 Create 活动的 `To` 或 `Cc` 属性中。 + + 如果 Note 的可见性为私信（即，不发送给公众或粉丝），每个提及的目标 URI 将位于活动包装的 `To` 属性中。 + + 在所有其他情况下，提及将包含在活动包装的 `Cc` 属性中。 + +### 外发 + +当 GoToSocial 用户提及另一个账户时，提及会作为 `tag` 属性中的一个条目包含在外发的联合消息中。 + +例如，一个 GoToSocial 实例上的用户提及 `@someone@example.org`，外发 Note 的 `tag` 属性可能如下： + +```json +"tag": { + "href": "http://example.org/users/someone", + "name": "@someone@example.org", + "type": "Mention" +} +``` + +如果用户提及同一实例内的本站用户，他们的完整 `name` 仍会被包含。 + +例如，一个 GoToSocial 用户在域 `some.gotosocial.instance` 上提及同一实例内的用户 `user2`。他们还提及了 `@someone@example.org`。外发 Note 的 `tag` 属性如下： + +```json +"tag": [ + { + "href": "http://example.org/users/someone", + "name": "@someone@example.org", + "type": "Mention" + }, + { + "href": "http://some.gotosocial.instance/users/user2", + "name": "@user2@some.gotosocial.instance", + "type": "Mention" + } +] +``` + +为了方便外站，GoToSocial 始终在外发的提及中提供 `href` 和 `name` 属性。GoToSocial 使用的 `href` 属性始终是目标账户的 ActivityPub ID/URI，而不是网页 URL。 + +### 传入 + +GoToSocial 尝试以与发送出相同的方式解析传入提及：作为 `tag` 属性中的 `Mention` 类型条目。然而，解析传入提及时，对于必须设置哪些属性的要求会更宽松些。 + +GoToSocial 更偏好 `href` 属性，它可以是目标的 ActivityPub ID/URI 或网页 URL；如果 `href` 不存在，将使用 `name` 属性作为回退。如果两个属性都不存在，提及将被视为无效并被丢弃。 + +## 内容、内容映射和语言 + +与其他 ActivityPub 实现一致，GoToSocial 在 `Objects` 中使用 `content` 和 `contentMap` 字段来推断传入贴文的内容和语言，并在外发贴文中设置内容和语言。 + +### 外发 + +如果一个外发 `Object`（通常是 `Note`）有内容，它将以在 `content` 字段中以被字符串化的 HTML 形式给出。 + +如果 `content` 关联特定用户选择的语言，那么 `Object` 还将设置 `contentMap` 属性为单条目键/值映射，其中键是 BCP47 语言话题标签，值是与 `content` 字段相同的内容。 + +例如，一篇用英语 (`en`) 写的贴文将如下所示： + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "type": "Note", + "attributedTo": "http://example.org/users/i_p_freely", + "to": "https://www.w3.org/ns/activitystreams#Public", + "cc": "http://example.org/users/i_p_freely/followers", + "id": "http://example.org/users/i_p_freely/statuses/01FF25D5Q0DH7CHD57CTRS6WK0", + "url": "http://example.org/@i_p_freely/statuses/01FF25D5Q0DH7CHD57CTRS6WK0", + "published": "2021-11-20T13:32:16Z", + "content": "

This is an example note.

", + "contentMap": { + "en": "

This is an example note.

" + }, + "attachment": [], + "replies": {...}, + "sensitive": false, + "summary": "", + "tag": {...} +} +``` + +如果贴文有内容，GoToSocial 会始终设置 `content` 字段，但是如果使用的 GoToSocial 版本较旧、用户未设置语言，或设置的语言不是公认的 BCP47 语言标签，则可能不会始终设置 `contentMap` 字段。 + +### 传入 + +GoToSocial 在解析传入的 `Object` 时使用 `content` 和 `contentMap` 属性来确定内容并推断该内容的主要语言。它使用以下算法： + +#### 仅设置 `content` + +仅采用该内容并将语言标记为未知。 + +#### 同时设置 `content` 和 `contentMap` + +在 `contentMap` 中查找键，作为语言标签，要查找的键的值与 `content` 中的 HTML 字符串匹配。 + +如果找到匹配项，将其用作贴文的语言。 + +如果未找到匹配项，则保留 `content` 中的内容并将语言标记为未知。 + +#### 仅设置 `contentMap` + +如果 `contentMap` 只有一个条目，则将语言标签和内容(值)作为“主要”语言和内容。 + +如果 `contentMap` 有多个条目，则无法确定贴文的意图内容和语言，因为映射顺序不可预测。在这种情况下，尝试从 GoToSocial 实例的[配置语言](../configuration/instance.md)中选择与其中一种语言匹配的语言和内容条目。如果无法通过这种方式匹配语言，则从 `contentMap` 中随机选择一个语言和内容条目作为“主要”语言和内容。 + +!!! Note + 在上述所有情况下，如果推断的语言无法解析为有效的 BCP47 语言话题标签，则语言将回退为未知。 + +## 互动规则 + +GoToSocial 使用 `interactionPolicy` 属性告知外站给定帖文允许的互动类型（有前提）。 + +!!! danger + + 互动规则旨在限制用户贴文上用户不希望的回复和其他互动的有害影响（例如，“回复家(reply guys)” —— 不请自来地发表冒失回复的人）。 + + 然而，这远远不能满足这一目的，因为仍然有许多“额外”方式可以分发或回复贴文，进而超出用户的初衷或意图。 + + 例如，用户可能创建一个附有非常严格互动规则的贴文，却发现其他服务器软件不尊重该规则，而其他实例上的用户从他们的实例视角进行讨论并回复该贴文。原始发布者的实例将自动从视图中删除这些用户不想要的互动，但外站实例可能仍会显示它们。 + + 另一个例子：有人可能会看到一个指定没人可以回复的贴文，但截屏该贴文，将截屏作为新帖文发布，并将提及原作者或只是附上原贴文的 URL。在这种情况下，他们成功通过新创建的贴文串来达到“回复”该贴文的目的。 + + 无论好坏，GoToSocial 只能为这一部分问题提供尽最大努力的部分技术解决方案，这更多的是一个社会行为和边界的问题。 + +### 概述 + +`interactionPolicy` 是贴文类 `Object`（如 `Note`、`Article`、`Question` 等）附带的一个属性，其格式如下： + +```json +{ + [...], + "interactionPolicy": { + "canLike": { + "always": [ "始终可进行此操作的零个或多个 URI" ], + "approvalRequired": [ "需要批准才能进行此操作的零个或多个 URI" ] + }, + "canReply": { + "always": [ "始终可进行此操作的零个或多个 URI" ], + "approvalRequired": [ "需要批准才能进行此操作的零个或多个 URI" ] + }, + "canAnnounce": { + "always": [ "始终可进行此操作的零个或多个 URI" ], + "approvalRequired": [ "需要批准才能进行此操作的零个或多个 URI" ] + } + }, + [...] +} +``` + +在此对象中： + +- `canLike` 指定可创建 `Like` 并将帖文 URI 作为 `Like` 的 `Object` 的人。 +- `canReply` 指定可创建 `inReplyTo` 设置为帖文 URI 的帖文的人。 +- `canAnnounce` 指定可创建 `Announce` 并将帖文 URI 作为 `Announce` 的 `Object` 的人。 + +并且： + +- `always` 是一个 ActivityPub URI/ID 的 `Actor` 或 `Actor` 的 `Collection`，无需 `Accept` 即可进行互动分发到其粉丝。 +- `approvalRequired` 是一个 ActivityPub URI/ID 的 `Actor` 或 `Actor` 的 `Collection`，可以互动，但在将互动分发给其粉丝之前需要获得 `Accept`。 + +`always` 和 `approvalRequired` 的有效 URI 条目包括 magic ActivityStreams 公共 URI `https://www.w3.org/ns/activitystreams#Public`，贴文创建者的 `Following` 和/或 `Followers` 集合的 URI，以及个人请求体的 URI。例如： + +```json +[ + "https://www.w3.org/ns/activitystreams#Public", + "https://example.org/users/someone/followers", + "https://example.org/users/someone/following", + "https://example.org/users/someone_else", + "https://somewhere.else.example.org/users/someone_on_a_different_instance" +] +``` + +### 指定无人能进行的操作 + +!!! note + 即使规则指定无人可互动，GoToSocial 仍做出默认假设。参见[默认假设](#默认假设)。 + +空数组或缺少/空的键表示无人能进行此互动。 + +例如，以下 `canLike` 指定无人能 `Like` 该贴文： + +```json +"canLike": { + "always": [], + "approvalRequired": [] +}, +``` + +类似的，`canLike` 值为 `null` 也表示无人能 `Like` 该帖： + +```json +"canLike": null +``` + +或 + +```json +"canLike": { + "always": null, + "approvalRequired": null +} +``` + +缺失的 `canLike` 值同样表达了相同的意思： + +```json +{ + [...], + "interactionPolicy": { + "canReply": { + "always": [ "始终可进行此操作的零个或多个 URI" ], + "approvalRequired": [ "需要批准才能进行此操作的零个或多个 URI" ] + }, + "canAnnounce": { + "always": [ "始终可进行此操作的零个或多个 URI" ], + "approvalRequired": [ "需要批准才能进行此操作的零个或多个 URI" ] + } + }, + [...] +} +``` + +### 冲突/重复值 + +在用户位于集合 URI 中, 且也通过 URI 被显式指定的情况下，**更具体的值**优先。 + +例如： + +```json +[...], +"canReply": { + "always": [ + "https://example.org/users/someone" + ], + "approvalRequired": [ + "https://www.w3.org/ns/activitystreams#Public" + ] +}, +[...] +``` + +在此情形下，`@someone@example.org` 位于 `always` 数组中，并且也存在于 `approvalRequired` 数组中的 magic ActivityStreams 公共集合中。在这种情况下，他们可以始终回复，因为 `always` 值更为明确。 + +另一个例子： + +```json +[...], +"canReply": { + "always": [ + "https://www.w3.org/ns/activitystreams#Public" + ], + "approvalRequired": [ + "https://example.org/users/someone" + ] +}, +[...] +``` + +在此，`@someone@example.org` 位于 `approvalRequired` 数组中，但也隐含地存在于 `always` 数组中的 magic ActivityStreams 公共集合中。在这种情况下，除了 `@someone@example.org` 需要批准外，其他人都可以无需批准进行回复。 + +在相同 URI 存在于 `always` 和 `approvalRequired` 两者中时，**最高级别的权限**优先（即 `always` 中的 URI 优先于 `approvalRequired` 中的相同 URI）。 + +### 默认假设 + +GoToSocial 对 `interactionPolicy` 做出若干默认假设。 + +**首先**，无论贴文的可见性和 `interactionPolicy` 如何，被[提及](#提及)或回复的用户应**始终**能够回复该贴而无需批准，**除非**提及或回复他们的贴文本身正在等待批准。 + +这是为了防止潜在的骚扰者在辱骂贴文中提及某人，并不给被提及的用户任何回复的机会。 + +因此，当发送互动规则时，GoToSocial 始终将提及用户的 URI 添加到 `canReply.always` 数组中，除非它们已被 magic ActivityStreams 公共 URI 覆盖。 + +同样，在执行接收到的互动规则时，即使用户 URI 不存在于 `canReply.always` 数组中，GoToSocial 也将被提及用户的 URI 视作已存在。 + +**其次**，用户应**始终**能够回复自己的贴文，点赞自己的贴文，并转发自己的贴文而无需批准，**除非**该贴文本身正在等待批准。 + +因此，当发送互动规则时，GoToSocial 始终将贴文作者的 URI 添加到 `canLike.always`、`canReply.always` 和 `canAnnounce.always` 数组中，除非它们已被 magic ActivityStreams 公共 URI 覆盖。 + +同样，在执行接收到的互动规则时，即使贴文作者 URI 不存在于这些 `always` 数组中，GoToSocial 也始终将贴文作者 URI 视为已存在。 + +### 默认值 + +当贴文上没有 `interactionPolicy` 属性时，GoToSocial 会根据贴文可见级别和发帖作者为该帖假定默认的 `interactionPolicy`。 + +对于 `@someone@example.org` 的**公开**或**未列出**贴文，默认 `interactionPolicy` 为： + +```json +{ + [...], + "interactionPolicy": { + "canLike": { + "always": [ + "https://www.w3.org/ns/activitystreams#Public" + ], + "approvalRequired": [] + }, + "canReply": { + "always": [ + "https://www.w3.org/ns/activitystreams#Public" + ], + "approvalRequired": [] + }, + "canAnnounce": { + "always": [ + "https://www.w3.org/ns/activitystreams#Public" + ], + "approvalRequired": [] + } + }, + [...] +} +``` + +对于 `@someone@example.org` 的**仅限粉丝**贴文，假定的 `interactionPolicy` 为： + +```json +{ + [...], + "interactionPolicy": { + "canLike": { + "always": [ + "https://example.org/users/someone", + "https://example.org/users/someone/followers", + [...提及的用户的 URI...] + ], + "approvalRequired": [] + }, + "canReply": { + "always": [ + "https://example.org/users/someone", + "https://example.org/users/someone/followers", + [...提及的用户的 URI...] + ], + "approvalRequired": [] + }, + "canAnnounce": { + "always": [ + "https://example.org/users/someone" + ], + "approvalRequired": [] + } + }, + [...] +} +``` + +对于 `@someone@example.org` 的**私信**贴文，假定的 `interactionPolicy` 为： + +```json +{ + [...], + "interactionPolicy": { + "canLike": { + "always": [ + "https://example.org/users/someone", + [...提及的用户的 URI...] + ], + "approvalRequired": [] + }, + "canReply": { + "always": [ + "https://example.org/users/someone", + [...提及的用户的 URI...] + ], + "approvalRequired": [] + }, + "canAnnounce": { + "always": [ + "https://example.org/users/someone" + ], + "approvalRequired": [] + } + }, + [...] +} +``` + +### 示例 1 - 限制对话范围 + +在此示例中，用户 `@the_mighty_zork` 想开始与用户 `@booblover6969` 和 `@hodor` 之间的对话。 + +为了避免讨论被他人打断，他们希望来自三名参与者以外的用户的回复仅在获得 `@the_mighty_zork` 批准后才被允许。 + +此外，他们希望将贴文转发/`Announce` 的权利限制为仅限于他们自己的粉丝和三个对话参与者。 + +然而，任何人都可以 `Like` `@the_mighty_zork` 的贴文。 + +这可以通过以下 `interactionPolicy` 来实现，它附加在可见性为公开的帖文上： + +```json +{ + [...], + "interactionPolicy": { + "canLike": { + "always": [ + "https://www.w3.org/ns/activitystreams#Public" + ], + "approvalRequired": [] + }, + "canReply": { + "always": [ + "https://example.org/users/the_mighty_zork", + "https://example.org/users/booblover6969", + "https://example.org/users/hodor" + ], + "approvalRequired": [ + "https://www.w3.org/ns/activitystreams#Public" + ] + }, + "canAnnounce": { + "always": [ + "https://example.org/users/the_mighty_zork", + "https://example.org/users/the_mighty_zork/followers", + "https://example.org/users/booblover6969", + "https://example.org/users/hodor" + ], + "approvalRequired": [] + } + }, + [...] +} +``` + +### 示例 2 - 长独白贴文串 + +在此示例中，用户 `@the_mighty_zork` 想写一个长篇独白。 + +他们不介意别人转发和点赞贴文，但不想收到任何回复，因为他们没有精力去管理讨论；他们只是想通过发泄自己的想法去表达自我。 + +这可以通过在贴文串中的每个贴文上设置以下 `interactionPolicy` 来实现： + +```json +{ + [...], + "interactionPolicy": { + "canLike": { + "always": [ + "https://www.w3.org/ns/activitystreams#Public" + ], + "approvalRequired": [] + }, + "canReply": { + "always": [ + "https://example.org/users/the_mighty_zork" + ], + "approvalRequired": [] + }, + "canAnnounce": { + "always": [ + "https://www.w3.org/ns/activitystreams#Public" + ], + "approvalRequired": [] + } + }, + [...] +} +``` + +在这里，任何人都可以点赞或转发，但无人能够回复（除了 `@the_mighty_zork` 自己）。 + +### 示例 3 - 完全开放 + +在此示例中，`@the_mighty_zork` 想写一篇完全开放的贴文，任何能看到此帖的人都可以进行回复、转发或点赞（即解锁和公开贴文默认行为）： + +```json +{ + [...], + "interactionPolicy": { + "canLike": { + "always": [ + "https://www.w3.org/ns/activitystreams#Public" + ], + "approvalRequired": [] + }, + "canReply": { + "always": [ + "https://www.w3.org/ns/activitystreams#Public" + ], + "approvalRequired": [] + }, + "canAnnounce": { + "always": [ + "https://www.w3.org/ns/activitystreams#Public" + ], + "approvalRequired": [] + } + }, + [...] +} +``` + +### 请求、获得和验证批准 + +当用户的 URI 在需要获得批准的互动的 `approvalRequired` 数组中时，如果他们希望获得批准以分发互动，应该执行以下步骤： + +1. 像往常一样撰写互动 `Activity`（即 `Like`、`Create` （回复）或 `Announce`）。 +2. 像往常一样将 `Activity` 的 `to` 和 `cc` 地址设为预期的收件人。 +3. 将 `Activity` **仅**发送到要互动帖的作者的 `Inbox`（或 `sharedInbox`）。 +4. **此时不要进一步分发 `Activity`**。 + +此时，互动可视为等待批准，并不应该显示在被互动的贴文的回复或点赞集合等中。 + +可以向发送互动的用户显示“互动待批准”状态，但理想情况下不应该向与该用户共享实例的其他用户显示。 + +从这里开始，可能会出现以下三种情况之一： + +#### 拒绝 + +在这种情况下，互动目标贴文的作者发回一个 `Reject` `Activity`，该活动的 `Object` 属性带有待拒绝互动活动的 URI/ID。 + +例如，以下 JSON 对象 `Reject` 了 `@someone@somewhere.else.example.org` 回复 `@post_author@example.org` 贴文的尝试： + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "actor": "https://example.org/users/post_author", + "to": "https://somewhere.else.example.org/users/someone", + "id": "https://example.org/users/post_author/activities/reject/01J0K2YXP9QCT5BE1JWQSAM3B6", + "object": "https://somewhere.else.example.org/users/someone/statuses/01J17XY2VXGMNNPH1XR7BG2524", + "type": "Reject" +} +``` + +如果发生这种情况，`@someone@somewhere.else.example.org`（及其实例）应视交互为被拒绝。该实例应从其内部存储（即数据库）中删除该活动，或以其他方式表明它已被拒绝，并且不应进一步分发该 `Activity` 或重试该交互。 + +#### 无响应 + +在这种情况下，正在互动的贴文的作者从不发送 `Reject` 或 `Accept` `Activity`。在这种情况下，交互被视为永久“待处理”。实例可能希望实现某种清理功能，达到一定时间期限的已发送且待处理交互应被视为过期，然后按照上述方式被处理为 `Rejected` 并删除。 + +#### 接受 + +在这种情况下，正在互动的贴文的作者发回一个`Accept` `Activity`，该活动的 `Object` 属性带有待批准互动活动的 URI/ID。 + +例如，以下 JSON 对象 `Accept` 了 `@someone@somewhere.else.example.org` 回复 `@post_author@example.org` 贴文的尝试： + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "actor": "https://example.org/users/post_author", + "cc": [ + "https://www.w3.org/ns/activitystreams#Public", + "https://example.org/users/post_author/followers" + ], + "to": "https://somewhere.else.example.org/users/someone", + "id": "https://example.org/users/post_author/activities/accept/01J0K2YXP9QCT5BE1JWQSAM3B6", + "object": "https://somewhere.else.example.org/users/someone/statuses/01J17XY2VXGMNNPH1XR7BG2524", + "type": "Accept" +} +``` + +如果发生这种情况，`@someone@somewhere.else.example.org`（及其实例）应视为交互已被批准/接受。然后，该实例可以自由地将此交互 `Activity` 分发给所有由 `to`、`cc` 等目标的接收者，并附加属性 `approvedBy`。 + +### 验证在粉丝/关注中是否存在 + +如果一个 `Actor` 在其互动规则的 `always` 字段中因为存在于 `Followers` 或 `Following` 集合中而被允许进行交互（例如 `Like`、`inReplyTo` 或 `Announce`），则其服务器仍应等待来自目标帐户服务器的 `Accept`，然后才更广泛地分发交互，并将 `approvedBy` 属性设置为 `Accept` 的 URI。 + +这样可以防止第三方服务器被迫以某种方式验证互动的 `Actor` 是否存在于接收互动的用户的 `Followers` 或 `Following` 集合中。让目标服务器进行验证，并采信其 `Accept` ，将其视为交互 `Actor` 存在于相关集合中的证明，更为简单。 + +同样，当接收到一个具有匹配 `Following` 或 `Followers` 集合的 `Actor` 的互动请求时，接收互动的 `Actor` 的服务器应确保尽快发送出 `Accept`，以便交互 `Actor` 服务器可以带着适当的接受证明发送出 `Activity`。 + +这个过程应绕过通常的“待批准”阶段，因此没有必要通知 `Actor` 待批准的交互，因为他们已明确同意。在 GoToSocial 代码库中，这被称为“预批准”。 + +### `approvedBy` + +`approvedBy` 是一个附加属性，添加到 `Like` 和 `Announce` 活动以及任何被视为“贴文”的 `Object`（如 `Note`、`Article`）中。 + +`approvedBy` 的存在表明贴文的作者接受了由 `Activity` 作为目标或由 `Object` 所回复的互动，并现在可以分发给其预期观众。 + +`approvedBy` 的值应为创建 `Accept` `Activity` 的接收交互贴文作者的 URI。 + +例如，以下 `Announce` `Activity` 的 `approvedBy` 表示它已被 `@post_author@example.org` `Accept`： + +```json +{ + "actor": "https://somewhere.else.example.org/users/someone", + "to": [ + "https://somewhere.else.example.org/users/someone/followers" + ], + "cc": [ + "https://example.org/users/post_author" + ], + "id": "https://somewhere.else.example.org/users/someone/activities/announce/01J0K2YXP9QCT5BE1JWQSAM3B6", + "object": "https://example.org/users/post_author/statuses/01J17ZZFK6W82K9MJ9SYQ33Y3D", + "approvedBy": "https://example.org/users/post_author/activities/accept/01J18043HGECBDZQPT09CP6F2X", + "type": "Announce" +} +``` + +接收到一个带有 `approvedBy` 值的 `Activity` 时，外站实例应解引用字段的 URI 值以获取 `Accept` `Activity`。 + +然后，他们应验证 `Accept` `Activity` 的 `object` 值是否等于交互 `Activity` 或 `Object` 的 `id`，并验证 `actor` 值是否等于接收交互的贴文的作者。 + +此外，他们应确保解引用的 `Accept` 的 URL 域名等于接收交互贴文的作者的 URL 域名。 + +如果无法解引用 `Accept` 或未通过有效性检查，则交互应被视为无效并丢弃。 + +由于这种验证机制，实例应确保他们对涉及 `interactionPolicy` 的 `Accept` URI 的解引用响应提供一个有效的 ActivityPub 对象。如果不这样做，他们会无意中限制外站实例分发其贴文的能力。 + +### 后续回复/范围扩展 + +对话中的每个后续回复将有其自己的互动规则，由创建回复的用户选择。换句话说，整个*对话*或*贴文串*并不由一个 `interactionPolicy` 控制，而是贴文串中的每个后续贴文可以由贴文作者设置不同的规则。 + +不幸的是，这意味着即使有 `interactionPolicy`，贴文串的范围也可能不小心超出第一个贴文作者的意图。 + +例如，在上述[示例 1](#示例-1---限制对话范围)中，`@the_mighty_zork` 在第一个贴文中指定了 `canReply.always` 值为 + +```json +[ + "https://example.org/users/the_mighty_zork", + "https://example.org/users/booblover6969", + "https://example.org/users/hodor" +] +``` + +在后续回复中，`@booblover6969` 无意或有意地将 `canReply.always` 值设为： + +```json +[ + "https://www.w3.org/ns/activitystreams#Public" +] +``` + +这扩大了对话的范围，因为现在任何人都可以回复 `@booblover6969` 的贴文，并可能也在该回复中标记 `@the_mighty_zork`。 + +为了避免这个问题，建议外站实例防止用户能够扩大范围（具体机制待定）。 + +同时，实例应将任何与仍处于待批准状态的贴文或贴文类似的 `Object` 的交互视作待批准。 + +换句话说，只要某条贴文处于待批准状态，实例应将该贴文下的所有互动标记为待批准，无论此贴文的互动规则通常允许什么。 + +这可避免有用户回复贴文，且在回复尚未得到批准的情况下继续回复*他们自己的回复*并将其标记为允许（作为贴文回复的作者，他们默认拥有对贴文回复的[回复权限](#默认假设)）。 + +## 投票 + +为了联合投票状态，GoToSocial 使用广泛采用的 [ActivityStreams `Question` 类型](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-question)。然而，第一个由 Mastodon 引入和推广的这个类型略微偏离 ActivityStreams 规范。在规范中，Question 类型被标记为 `IntransitiveActivity` 的扩展，此扩展是一个应当不带 `Object` 且所有详细信息应被默认包含的 `Activity` 扩展。但在具体实现中，它作为 `Object` 通过 `Create` 或 `Update` 活动传递。 + +值得注意的是，虽然 GoToSocial 内部可能将投票视作贴文附件的一种类型，但 ActivityStreams 表示法将贴文和带投票的贴文视为两种不同的 `Object` 类型。贴文以 `Note` 类型联合，投票以 `Question` 类型联合。 + +GoToSocial 传输（和期望接收）的 `Question` 类型包含所有常见的 `Note` 属性，外加一些附加内容。它们期望以下附加的（伪）JSON： + +```json +{ + "@context":[ + { + // toot:votersCount 扩展，用于添加 votersCount 属性。 + "toot":"http://joinmastodon.org/ns#", + "votersCount":"toot:votersCount" + } + ], + + // oneOf / anyOf 包含投票选项 + // 本身。只有其中之一会被设置， + // 其中 "oneOf" 表示单选投票， + // "anyOf" 表示多选投票。 + // + // 任一属性都包含一个 “Notes” 数组， + // 特殊的是它们包含一个 “name” 且未设置 + // “content”，其中 “name” 代表实际 + // 投票选项字符串。此外，它们包含 + // 一个 “Collection” 类型的 “replies” 属性， + // 通过 “totalItems” 表示每个投票选项当前已知的投票数。 + "oneOf": [ // 或 "anyOf" + { + "type": "Note", + "name": "选项 1", + "replies": { + "type": "Collection", + "totalItems": 0 + } + }, + { + "type": "Note", + "name": "选项 2", + "replies": { + "type": "Collection", + "totalItems": 0 + } + } + ], + + // endTime 指示此投票将何时结束。 + // 某些服务器实现支持永不结束的投票， + // 或使用 “closed” 来暗示 “endTime”，因此该项可能不会总是被设置。 + "endTime": "2023-01-01T20:04:45Z", + + // closed 指示此投票结束的时间。 + // 在来到此时间之前，该项将不会被设置。 + "closed": "2023-01-01T20:04:45Z", + + // votersCount 表示参与者的总数， + // 这在多选投票的情况下很有用。 + "votersCount": 10 +} +``` + +### 外发 + +你可以期望从 GoToSocial 接收到一个 `Question` 形式的投票，投票在 `Create` 或 `Update` 活动中作为对象属性传递。在 `Update` 活动的情形下，如果投票中除了 `votersCount`、`replies.totalItems` 或 `closed` 之外的任何内容发生了变化，那么就表明包裹的贴文以需要重新创建的方式进行了编辑，因此需要重置。你可以期望在以下时间收到这些活动： + +- "Create"：刚刚创建了带有附加投票的贴文 + +- "Update"：投票/投票人数发生了变化，或者投票刚刚结束 + +你可以期望的，由 GoToSocial 生成的 `Question` 可以在上面的伪 JSON 中看到。在此 JSON 中，"endTime" 字段将始终被设置（因为我们不支持创建无尽投票），而 "closed" 字段只有在投票结束时才会设置。 + +### 传入 + +GoToSocial 期望以与发出投票几乎相同的方式接收投票，在解析 `Question` 对象时采用略显宽容的规则。 + +- 如果提供 "closed" 而不提供 "endTime"，那么这也将被视为 "endTime" 的值 + +- 如果既没有提供 "closed" 也没有 "endTime"，则认为投票是永不结束的投票 + +- 任何情况下，若一个带有 `Question` 的 `Update` 活动提供了一个 `closed` 时间，而之前的活动没有提供，则假定投票刚刚关闭。这将在本站参与投票的用户的客户端触发通知 + +## 投票行动 + +为了联合投状态票，GoToSocial 使用特殊格式化 [ActivityStreams "Note" 类型](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-note)。这被 ActivityPub 服务器广泛接受为联合投票的方式，仅将投票作为 "Create" 活动的 "Object" 附加对象。 + +GoToSocial 传输的 "Note" 类型（以及期望接收到的）包含内容有： +- "name": [确切的投票选项文本] +- "content": [未设置] +- "inReplyTo": [指向 AS Question 的 IRI] +- "attributedTo": [投票作者的 IRI] +- "to": [投票作者的 IRI] + +例如： + +```json +{ + "type": "Note", + "name": "选项 1", + "inReplyTo": "https://example.org/users/bobby_tables/statuses/123456", + "attributedTo": "https://sample.com/users/willy_nilly", + "to": "https://example.org/users/bobby_tables" +} +``` + +### 外发 + +你可以期望以上面特定描述形式接收到来自 GoToSocial 的投票。投票仅作为附属于 "Create" 活动的对象发送。 + +特别地，如上节所述，GoToSocial 会在 `name` 字段中提供选项文本，不设置 `content` 字段，在 `inReplyTo` 字段提供一个 IRI，指向你的实例上的带投票贴文。 + +以下是一个 `Create` 示例，其中用户 `https://sample.com/users/willy_nilly` 在用户 `https://example.org/users/bobby_tables` 创建的多选投票中投票： + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "actor": "https://sample.com/users/willy_nilly", + "id": "https://sample.com/users/willy_nilly/activity#vote/https://example.org/users/bobby_tables/statuses/123456", + "object": [ + { + "attributedTo": "https://sample.com/users/willy_nilly", + "id": "https://sample.com/users/willy_nilly#01HEN2R65468ZG657C4ZPHJ4EX/votes/1", + "inReplyTo": "https://example.org/users/bobby_tables/statuses/123456", + "name": "纸巾", + "to": "https://example.org/users/bobby_tables", + "type": "Note" + }, + { + "attributedTo": "https://sample.com/users/willy_nilly", + "id": "https://sample.com/users/willy_nilly#01HEN2R65468ZG657C4ZPHJ4EX/votes/2", + "inReplyTo": "https://example.org/users/bobby_tables/statuses/123456", + "name": "金融时报", + "to": "https://example.org/users/bobby_tables", + "type": "Note" + } + ], + "published": "2021-09-11T11:45:37+02:00", + "to": "https://example.org/users/bobby_tables", + "type": "Create" +} +``` + +### 传入 + +GoToSocial 期望以与发送投票的几乎相同形式接收投票。即只会期望把投票作为 "Create" 活动的一部分接收。 + +特别地，GoToSocial 将 votes 识别为不同于其他 "Note" 对象，因为其包含一个 "name" 字段，省略 "content" 字段，且 "inReplyTo" 字段是指向带附有投票的贴文的 URI。 如果满足这些条件，GoToSocial 将把提供的 "Note" 视为格式不正确的贴文对象。 + +## 贴文删除 + +GoToSocial 允许用户删除他们创建的贴文。这些删除操作将会向其他实例进行联合，其他实例也应删除其缓存的贴文。 + +### 外发 + +当 GoToSocial 用户删除贴文时，服务器会向其他实例发送一个 `Delete` 活动。 + +`Delete` 活动的 `Object` 条目会设置为该贴文的 ActivityPub URI。 + +`to` 和 `cc` 将根据原始贴文的可见性以及任何被提及/回复的用户进行设置。 + +如果原始贴文不是私信，ActivityPub `Public` URI 将在 `to` 中注明。否则，只会涉及被提及和回复的用户。 + +在以下示例中，'admin' 用户删除了一篇公开贴文，其中提到了 'foss_satan' 用户： + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "actor": "http://example.org/users/admin", + "cc": [ + "http://example.org/users/admin/followers", + "http://fossbros-anonymous.io/users/foss_satan" + ], + "object": "http://example.org/users/admin/statuses/01FF25D5Q0DH7CHD57CTRS6WK0", + "to": "https://www.w3.org/ns/activitystreams#Public", + "type": "Delete" +} +``` + +在下一个示例中，'1happyturtle' 用户删除了一条原本发给 'the_mighty_zork' 用户的直接消息。 + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "actor": "http://example.org/users/1happyturtle", + "cc": [], + "object": "http://example.org/users/1happyturtle/statuses/01FN3VJGFH10KR7S2PB0GFJZYG", + "to": "http://somewhere.com/users/the_mighty_zork", + "type": "Delete" +} +``` + +要处理从 GoToSocial 实例发出的 `Delete` 活动，外站实例应检查其是否根据提供的 URI 存储了 `Object`。如果有，它们应从本站缓存中删除该对象。如果没有，那么无需执行任何操作，因为它们从未存储过现在被删除的贴文。 + +### 接收 + +GoToSocial 尽可能彻底地处理来自外站实例的 `Delete` 活动，以尊重其他用户的隐私。 + +当 GoToSocial 实例收到 `Delete` 时，它会尝试从 `Object` 字段中提取被删除的贴文 URI。如果 `Object` 仅是一个 URI，则使用该 URI。如果 `Object` 是一个 `Note` 或其他常用于表示贴文的类型，则会从中提取 URI。 + +然后，GoToSocial 将检查其是否存储了具有给定 URI 的贴文。如果有，它将在数据库和所有用户时间线上完全删除。 + +GoToSocial 仅在确认原帖是被 `Delete` 所属的 `actor` 所拥有的情况下才会删除对应贴文。 + +## 贴文串 + +由于去中心化和联合的特性，Fediverse 上的任何一个服务器几乎不可能知道给定贴文串中的每篇贴文。 + +即便如此，也可以尽力对贴文串进行解引用，从不同的外站实例拉取回复，以更充分地展现整个对话。 + +GoToSocial 通过在对话贴文串上下迭代，尽可能获取外站贴文，来实现这一点。 + +假设我们有两个账户：`local_account` 在 `our.server` 上，`remote_1` 在 `remote.1` 上。 + +在这种情况下，`local_account` 关注了 `remote_1`，所以 `remote_1` 的贴文会出现在 `local_account` 的主页时间线上。 + +现在，`remote_1` 转发/转贴了来自第三方账户 `remote_2` 的一篇贴文，该账户在服务器 `remote.2` 上。 + +`local_account` 未关注 `remote_2`，`our.server` 上也没有其他人关注，因此 `our.server` 未曾见过 `remote_2` 的这篇贴文。 + +![贴文串的示意图，展示了来自 remote_2 的贴文，以及可能的祖先和后代贴文](../../../assets/diagrams/conversation_thread.png) + +此时，GoToSocial 会对 `remote_2` 的贴文进行“解引用”，检查其是否属于某个贴文串，以及贴文串的其他部分是否可以获取。 + +GtS 首先检查贴文的 `inReplyTo` 属性，该属性在贴文回复其他贴文时设置。[见此处](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-inreplyto)。如果设置了 `inReplyTo`，GoToSocial 会解引用被回复的贴文。如果 *这篇* 贴文也设置了 `inReplyTo`，那么 GoToSocial 也会对此进行解引用，如此反复。 + +一旦获取到贴文的所有 **祖先** 后，GtS 将开始处理贴文的 **后代**。 + +这种情况下通过检查解引用贴文的 `replies` 属性，依次处理回复及回复的回复。[见此处](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-replies)。 + +这个贴文串解引用的过程可能需要进行多次 HTTP 请求到不同的服务器，尤其是在贴文串长且复杂的情况下。 + +解引用的最终结果是，假设由 `remote_2` 转发的贴文属于一个贴文串，那么 `local_account` 在主页时间线上打开贴文时，现在应该能够看到贴文串中的贴文。换句话说，他们将看到来自其他服务器账户的回复（他们可能尚未相遇），以及由 `remote_2` 发布的贴文串之前和之后的贴文。 + +这为 `local_account` 提供更完整的对话视图，而不仅仅是孤立和断章取义地看到被转发的贴文。此外，这还为 `local_account` 提供了根据对 `remote_2` 的回复发现新账户以进行关注的机会。 diff --git a/docs/locales/zh/federation/ratelimiting.md b/docs/locales/zh/federation/ratelimiting.md new file mode 100644 index 000000000..f724b0c18 --- /dev/null +++ b/docs/locales/zh/federation/ratelimiting.md @@ -0,0 +1,7 @@ +# 请求限流与速率限制 + +GoToSocial 对 ActivityPub API 端点（收件箱、用户端点、表情符号等）应用了 HTTP 请求限流和速率限制。 + +这可确保外站服务器不能用虚假请求淹没 GoToSocial 实例。外站服务器在对 ActivityPub API 端点进行 GET 或 POST 请求时，应尊重 429 和 503 HTTP 状态码，并考虑 `retry-after` HTTP 响应头。 + +有关请求限流和速率限制行为的更多详细信息，请参阅 [限流](../api/throttling.md) 和 [速率限制](../api/ratelimiting.md) 文档。 diff --git a/docs/locales/zh/getting_started/index.md b/docs/locales/zh/getting_started/index.md new file mode 100644 index 000000000..68c948f11 --- /dev/null +++ b/docs/locales/zh/getting_started/index.md @@ -0,0 +1,185 @@ +# 部署注意事项 + +在部署 GoToSocial 之前，有几个关键点需要你仔细考虑，因为这些选择将影响你如何运行和管理 GoToSocial。 + +!!! danger + + 在同一域名上切换不同实现是不被 Fediverse 支持的。这意味着如果你在 example.org 上运行 GoToSocial，而尝试切换到其他实现如 Pleroma/Akkoma、Misskey/Calckey 等，你会遇到联合问题。 + + 同理，如果你已经在 example.org 上运行了其他 ActivityPub 实现，就不应该尝试在那个域名上切换到 GoToSocial。 + +## 服务器 / VPS 系统要求 + +GoToSocial 致力于为在小型设备上运行的使用场景优化，因此我们尽量确保系统需求处于合理低位，同时仍提供人们期望的社交媒体服务器功能。 + +下面是系统需求的详细信息，但简而言之，你应该选择至少有 **1 个 CPU 核心**、大约 **1GB 内存**（可能会因操作系统而异），和 **15GB-20GB 的存储空间**（一般可满足前几年的使用）。 + +### 内存 + +**简短结论：系统上总共 1GB 的 RAM 应该足够，但你可能降至 512MB 也能运行。** + +对于小型站点（1-20 个活跃用户），GoToSocial 在内部缓存被填满的情况下，大约会占用 250MB 到 350MB 的 RAM： + +在上图中，你可以看到 RAM 的使用会在负载期间突增。这种情况会在例如某个贴文被一个拥有众多粉丝的人转发时，或嵌入的 `ffmpeg` 二进制文件在解码或重新编码媒体文件为缩略图时（特别是较大视频文件）出现。 + +你应该在这种情况下预留一些余量，若有需要，可以[配置一些交换内存](#交换内存)。 + +!!! tip + 在内存受限的环境中，你可以将 `cache.memory-target` 设置为低于默认的 100MB （查看数据库配置选项[这里](../configuration/database.md#settings)）。设置为 50MB 已被证明可以正常运行。 + + 这将使总内存使用稍微降低，但代价是某些请求的延迟略高，因为 GtS 需要更频繁地访问数据库。 + +!!! info "为什么 `htop` 显示的内存使用比图中高？" + 如果你在服务器上运行 `top` 或 `htop` 或其他系统资源监测工具，GoToSocial 显示的保留内存可能比图中高。然而，这并不总是反映 GoToSocial 实际*使用*的内存。这种差异是由于 Go 运行时会比较保守地将内存释放回操作系统，因为与立即释放并在稍后需要时重新请求相比，保留空闲内存通常更划算。 + +### CPU + +**简短结论：1 个不错的 CPU 核心应该足够。** + +CPU 负载主要在处理媒体时（尤其是编码 blurhash）和/或同时处理大量联合请求时较高。只要不在同一台机器上运行其他 CPU 密集型任务，1 个 CPU 核心就能胜任。 + +### 存储 + +**简短结论：15GB-20GB 可用存储空间应足够使用几年。** + +GoToSocial 使用存储来保存其数据库文件，以及存储和服务媒体文件，例如头像和附件等。你可以[配置 GtS 使用 S3 存储桶来存储媒体](../configuration/storage.md)。 + +对于媒体存储，以及[缓存的外站媒体文件存储](../admin/media_caching.md)，你应该预算大约 5GB-10GB 的空间。GoToSocial 会自动执行自我清理，在一段时间后从缓存中删除未使用的外站媒体。如果存储空间是个问题，你可以[调整媒体清理行为](../admin/media_caching.md#清理)以更频繁地清理和/或减少外站媒体的缓存时间。 + +!!! info + 如果你的 sqlite.db 文件或 Postgres 容量在一开始增长很快，请不要惊慌，这是正常的。当你首次部署实例并开始联合时，你的实例会迅速发现并存储来自其他实例的账号和贴文。然而，随着实例的长期部署，这种增长会逐渐减缓，因为你会自然而然地看到更少的新账号（即，你的实例尚未见过并因此尚未在数据库中存储的账号）。 + +### 单板计算机 + +GoToSocial 的轻量系统要求意味着它在配置良好的单板计算机上运行良好。如果在单板计算机上运行，你应该确保 GoToSocial 使用 USB 驱动器（最好是 SSD）来存储其数据库文件和媒体，而不是 SD 卡存储，因为后者通常太慢，不适合运行数据库。 + +### VPS + +如果你决定使用 VPS，可以为自己建立一个便宜的运行 Linux 的服务器。大多数每月 €2-€5 的 VPS 能够为个人 GoToSocial 实例提供出色的性能。 + +[Hostwinds](https://www.hostwinds.com/) 是一个不错的选择：价格便宜，而且他们免费提供静态 IP 地址。 + +[Greenhost](https://greenhost.net) 也是一个好选择：它完全无 CO2 排放，但价格稍高。他们的 1GB、1 个 CPU 的 VPS 对于单个用户或小型实例来说效果很好。 + +!!! warning "云存储卷" + 并非所有的云 VPS 存储都相同，声称基于 SSD 的存储并不一定适合作为 GoToSocial 实例的运行环境。 + + [Hetzner 云卷的性能](https://github.com/superseriousbusiness/gotosocial/issues/2471#issuecomment-1891098323)没有保证，且延迟波动较大。这会导致你的 GoToSocial 实例表现不佳。 + +!!! danger "Oracle 免费套餐" + 如果你打算与多个其他实例和用户联合，[Oracle 云免费套餐](https://www.oracle.com/cloud/free/) 服务器不适合用于 GoToSocial 部署。 + + 在 Oracle 云免费套餐上运行的 GoToSocial 管理员报告说，他们的实例在中等负载期间非常慢或无响应。这很可能是由于内存或存储延迟，导致即使是简单的数据库查询也要很长时间才能运行。 + +### 发行版系统要求 + +请务必检查你的发行版的系统需求，特别是内存。许多发行版有基线要求，在不满足它们的系统上运行会造成问题，除非你进行进一步的调整和优化。 + +Linux: + +* [Arch Linux][archreq]: `512MB` RAM +* [Debian][debreq]: `786MB` RAM +* [Ubuntu][ubireq]: `1GB` RAM +* [RHEL 8+][rhelreq] 及其衍生版本: `1.5GB` RAM +* [Fedora][fedorareq]: `2GB` RAM + +BSD 家族的发行版在内存要求方面记录较少，但普遍预期 `128MB` 以上就足够。 + +[archreq]: https://wiki.archlinux.org/title/installation_guide +[debreq]: https://www.debian.org/releases/stable/amd64/ch02s05.en.html +[ubireq]: https://ubuntu.com/server/docs/installation +[rhelreq]: https://access.redhat.com/articles/rhel-limits#minimum-required-memory-3 +[fedorareq]: https://docs.fedoraproject.org/en-US/fedora/latest/release-notes/welcome/Hardware_Overview/#hardware_overview-specs + +## 数据库 + +GoToSocial 支持 SQLite 和 Postgres 作为数据库驱动。尽管理论上可以在 SQLite 和 Postgres 之间切换，但我们目前没有工具支持这项操作，因此你在开始时应慎重考虑数据库的选择。 + +SQLite 是默认的驱动，并已被证明在 1-30 用户范围内的实例表现出色。 + +!!! danger "网络存储上的 SQLite" + 不要将你的 SQLite 数据库放在外部存储上，无论是 NFS/Samba、iSCSI 卷，如 Ceph/Gluster，或者你的云供应商的网络卷存储解决方案。 + + 更多信息参见[网络存储上的 SQLite](../advanced/sqlite-networked-storage.md)。 + +如果你计划在一个实例上托管更多用户，你可能希望改用 Postgres，因为它提供了数据库集群和冗余的可能性，尽管这会增加一些复杂性。 + +无论你选择哪种数据库驱动，为了获得良好的性能，它们都应在快速、稳定的低延迟存储上运行。虽然可以在网络附加存储上运行数据库，但这会增加可变延迟和网络拥堵，还有源存储上的潜在 I/O 争用。 + +!!! tip + 请[备份你的数据库](../admin/backup_and_restore.md)。数据库包含实例和任何用户账户的加密密钥。如果丢失这些密钥，你将无法再次从同一域进行联合！ + +## 域名 + +为了和其他实例进行联合，你需要一个域名，如 `example.org`。你可以通过任何域名注册商注册域名，例如 [Namecheap](https://www.namecheap.com/)。确保你选择的注册商也允许你管理 DNS 条目，以便将你的域指向运行 GoToSocial 实例的服务器 IP。 + +用户通常会出现在顶级域下，例如 `@me@example.org`，但这不是必须的。完全可以在 `@me@social.example.org` 下创建用户。很多人更喜欢在顶级域下创建用户，因为输入起来更短，但你可以使用任何你控制的（子域）。 + +可以拥有形如 `@me@example.org` 的用户名，但让 GoToSocial 运行在 `social.example.org`。这通过区分 API 域（称为“实例域名”）和用户名用的域（称为“账号域名”）来实现。 + +如果你打算这样部署 GoToSocial 实例，请阅读[分域部署](../advanced/host-account-domain.md)文档以了解详细信息。 + +!!! danger + 无法在联合已经事实发生后安全地更改实例域名和账号域名。这需要重新生成数据库，并在任何已联合的服务器造成混乱情况。一旦你的实例域名和账号域名设置好，便不可更改。 + +## TLS + +为了实现联合，你必须使用 TLS。大多数实现，包括 GoToSocial，通常会拒绝通过未加密的传输进行联合。 + +GoToSocial 内置 Lets Encrypt 证书配置支持。它也可以从磁盘加载证书。如果你有连接到 GoToSocial 的反向代理，可以在代理层处理 TLS。 + +!!! tip + 请确保配置使用现代版本的 TLS，TLSv1.2 及更高版本，以确保服务器和客户端之间的通信安全。当 GoToSocial 处理 TLS 终端时，这会自动为你配置。如果使用反向代理，请使用 [Mozilla SSL 配置生成器](https://ssl-config.mozilla.org/)。 + +## 端口 + +GoToSocial 需要开放端口 `80` 和 `443`。 + +* `80` 用于 Lets Encrypt。因此，如果不使用内置的 Lets Encrypt 配置，则不需要开放。 +* `443` 用于通过 TLS 服务 API，并且是与其联合的任何实例尝试连接的端口。 + +如果你无法在机器上开放 `443` 和 `80` 端口，不要担心！你可以在 GoToSocial 中配置这些端口，但还需要配置端口转发，以将 `443` 和 `80` 上的流量准确转发到你选择的端口。 + +!!! tip + 你应该在机器上配置防火墙，并配置一些防范暴力 SSH 登录尝试的保护措施。参阅我们的[防火墙文档](../advanced/security/firewall.md)以获取配置建议和可帮助你的工具。 + +## 集群 / 多节点部署 + +GoToSocial 不支持[集群或任何形式的多节点部署](https://github.com/superseriousbusiness/gotosocial/issues/1749)。 + +尽管多个 GtS 实例可以使用相同的 Postgres 数据库和共享的本地存储或相同的对象桶，但 GtS 依赖于大量的内部缓存以保持高效。没有同步这些实例缓存的机制。没有它，你会得到各种奇怪和不一致的行为。不要这样做！ + +## 调优 + +除了[示例配置文件](https://github.com/superseriousbusiness/gotosocial/blob/main/example/config.yaml)中的众多实例调优选项之外，你还可以对运行 GoToSocial 实例的机器进行额外的调优。 + +### 交换内存 + +除非你在进行这种调优并处理由不使用交换内存可能产生的问题方面有经验，否则你应该按照你的发行版本或主机供应商的建议配置适量的交换内存。如果你的发行版本或主机供应商没有提供指导，你可以使用以下经验法则为服务器配置交换内存： + +* 小于 2GB 的 RAM：交换内存 = RAM × 2 +* 大于 2GB 的 RAM：交换内存 = RAM，最高可达 8G + +!!! tip "配置交换内存活跃度" + Linux 的内存交换得很早。这在服务器上通常是不必要的，并且在数据库的情况下可能导致不必要的延迟。虽然在需要时让系统进行交换是好的，但可以通过告诉它在早期交换时保守一些来帮助提升性能。这个在 Linux 上的配置是通过更改 `vm.swappiness` [sysctl][sysctl] 值完成的。 + + 默认值是 `60`。你可以将其降低到 `10` 作为起点并留意观察。运行更低的值也是可能的，但这可能没有必要。要使该值持久化，你需要在 `/etc/sysctl.d/` 中放置一个配置文件。 + +虽然可以在没有交换内存的情况下运行系统，但为了安全地做到这一点并确保一致的性能和服务可用性，你需要相应调整内核、系统和工作负载。这需要对内核的内存管理系统及你所运行的工作负载的内存使用模式有良好的理解。 + +!!! tip + 交换内存用于确保内核可以高效地回收内存。这在系统没有经历内存争用时也很有用，比如在进程启动时仅使用过的内存腾出。这允许更多活跃使用的东西被缓存于内存中。内存交换不是让你的程序变慢的原因。内存争用才是造成缓慢的原因。 + +[sysctl]: https://man7.org/linux/man-pages/man8/sysctl.8.html + +### 内存和 CPU 限制 + +可以限制 GoToSocial 实例可以消耗的内存或 CPU 的数量。在 Linux 上可以使用 [CGroups v2 资源控制器][cgv2] 来做到这一点。 + +你可以使用 [systemd 资源控制设置][systemdcgv2]、[OpenRC cgroup 支持][openrccgv2] 或 [libcgroup CLI][libcg] 为进程配置限制。如果你想在系统经历内存压力时保护 GoToSocial，可以查看 [`memory.low`][cgv2mem]。 + +[cgv2]: https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html +[systemdcgv2]: https://www.freedesktop.org/software/systemd/man/latest/systemd.resource-control.html +[openrccgv2]: https://wiki.gentoo.org/wiki/OpenRC/CGroups +[libcg]: https://github.com/libcgroup/libcgroup/ +[cgv2mem]: https://docs.kernel.org/admin-guide/cgroup-v2.html#memory-interface-files diff --git a/docs/locales/zh/getting_started/installation/container.md b/docs/locales/zh/getting_started/installation/container.md new file mode 100644 index 000000000..43c526896 --- /dev/null +++ b/docs/locales/zh/getting_started/installation/container.md @@ -0,0 +1,164 @@ +# 容器 + +本指南将指引你通过我们发布的官方容器镜像运行 GoToSocial。在本例中，我们将直接使用 [Docker Compose](https://docs.docker.com/compose) 和 SQLite 作为数据库。 + +你也可以使用容器编排系统（如 [Kubernetes](https://kubernetes.io/) 或 [Nomad](https://www.nomadproject.io/)）运行 GoToSocial，但这超出了本指南的范围。 + +## 创建工作目录 + +你需要一个工作目录来存放你的 docker-compose 文件，以及一个目录来存储 GoToSocial 的数据。请使用以下命令创建这些目录： + +```bash +mkdir -p ~/gotosocial/data +``` + +现在切换到你创建的工作目录： + +```bash +cd ~/gotosocial +``` + +## 获取最新的 docker-compose.yaml + +使用 `wget` 下载最新的 [docker-compose.yaml](https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/example/docker-compose/docker-compose.yaml) 示例，我们将根据需要进行自定义： + +```bash +wget https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/example/docker-compose/docker-compose.yaml +``` + +## 编辑 docker-compose.yaml + +由于 GoToSocial 可以使用[环境变量](../../configuration/index.md#环境变量)进行配置，我们可以跳过在容器中挂载 config.yaml 文件，使配置更为简单。只需编辑 docker-compose.yaml 文件以更改一些内容。 + +首先在你的编辑器中打开 docker-compose.yaml 文件。例如： + +```bash +nano docker-compose.yaml +``` + +### 版本 + +如果需要，更新 GoToSocial Docker 镜像标签到你想要使用的 GtS 版本： + +* `latest`：默认值。这指向最新的稳定版本的 GoToSocial。 +* `snapshot`：指向当前在主分支上的代码。不保证稳定，可能经常出错。谨慎使用。 +* `vX.Y.Z`：发布标签。这指向 GoToSocial 的特定、稳定的版本。 + +!!! tip + `latest` 和 `snapshot` 标签是动态标签，而 `vX.Y.Z` 标签是固定的。拉取动态标签的结果可能每天都会变化。同一系统上的 `latest` 可能与不同系统上的 `latest` 不同。建议使用 `vX.Y.Z` 标签，以便你始终确切知道运行的是 GoToSocial 的哪个版本。发布列表可以在[这里](https://github.com/superseriousbusiness/gotosocial/releases)找到，最新的发布在顶部。 + +### 主机 + +更改 `GTS_HOST` 环境变量为你运行 GoToSocial 的域名。 + +### 服务器时区（可选但推荐） + +为确保你的 GoToSocial 服务器在贴文和日志中显示正确的时间，你可以通过编辑 `TZ` 环境变量设置服务器的时区。 + +1. 删除环境部分中 `TZ: UTC` 前面的 `#`。 +2. 将 `UTC` 部分更改为你的时区标识符。有关这些标识符的列表，请参阅 https://en.wikipedia.org/wiki/List_of_tz_database_time_zones。 + +例如，如果你在明斯克运行服务器，你可以设置 `TZ: Europe/Minsk`，日本设置为 `TZ: Japan`，迪拜设置为 `TZ: Asia/Dubai`，等等。 + +如果不设置，将使用默认的 `UTC`。 + +### 用户（可选/可能不必要） + +默认情况下，Docker 化的 GoToSocial 以 Linux 用户/组 `1000:1000` 运行，这在大多数情况下是可以的。如果你想以不同的用户/组运行，应相应地更改 docker-compose.yaml 中的 `user` 字段。 + +例如，假设你为 id 为 `1001` 的用户和组创建了 `~/gotosocial/data` 目录。如果现在不更改 `user` 字段就尝试运行 GoToSocial，将会遇到权限错误，无法在目录中打开数据库文件。在这种情况下，你需要将 docker compose 文件的 `user` 字段更改为 `1001:1001`。 + +### LetsEncrypt（可选） + +如果你想为 TLS 证书（https）使用 [LetsEncrypt](../../configuration/tls.md)，你还应该： + +1. 将 `GTS_LETSENCRYPT_ENABLED` 的值更改为 `"true"`。 +2. 删除 `ports` 部分中 `- "80:80"` 前面的 `#`。 +3. （可选）将 `GTS_LETSENCRYPT_EMAIL_ADDRESS` 设置为有效的电子邮件地址，以接收证书过期警告等。 + +!!! info "可选配置" + + config.yaml 文件中记录了许多其他配置选项，你可以使用这些选项进一步自定义你的 GoToSocial 实例的行为。尽可能使用合理的默认设置，因此不一定需要立即对它们进行更改，但以下几个可能会感兴趣： + + - `GTS_INSTANCE_LANGUAGES`：确定你实例首选语言的 [BCP47 语言标签](https://en.wikipedia.org/wiki/IETF_language_tag)数组。 + - `GTS_MEDIA_REMOTE_CACHE_DAYS`：在存储中保持外站媒体缓存的天数。 + - `GTS_SMTP_*`：允许你的 GoToSocial 实例连接到电子邮件服务器并发送通知电子邮件的设置。 + + 如果你决定稍后设置/更改这些变量，请确保在更改后重新创建 GoToSocial 实例容器。 + + +!!! tip + + 有关将 config.yaml 文件中的变量名称转换为环境变量的帮助，请参阅[配置部分](../../configuration/index.md#environment-variables)。 + +### Wazero 编译缓存（可选） + +启动时，GoToSocial 会将嵌入的 WebAssembly `ffmpeg` 和 `ffprobe` 二进制文件编译为 [Wazero](https://wazero.io/) 兼容模块，用于媒体处理而无需任何外部依赖。 + +要加快 GoToSocial 的启动时间，你可以在重启之间缓存已编译的模块，这样 GoToSocial 就不必在每次启动时从头编译它们。 + +如果你希望在 Docker 容器中进行此操作，首先在工作文件夹中创建一个 `.cache` 目录以存储模块： + +```bash +mkdir -p ~/gotosocial/.cache +``` + +然后，取消注释 docker-compose.yaml 文件中第二个卷的前面的 `#` 符号，使其从 + +```yaml +#- ~/gotosocial/.cache:/gotosocial/.cache +``` + +变为 + +```yaml +- ~/gotosocial/.cache:/gotosocial/.cache +``` + +这将指示 Docker 在 Docker 容器中将 `~/gotosocial/.cache` 目录挂载到 `/gotosocial/.cache`。 + +## 启动 GoToSocial + +完成这些小改动后，您现在可以使用以下命令启动 GoToSocial： + +```shell +docker-compose up -d +``` + +运行此命令后，你应该会看到如下输出： + +```text +Creating network "gotosocial_gotosocial" with the default driver +Creating gotosocial ... done +``` + +如果你想跟踪 GoToSocial 的日志，可以使用： + +```bash +docker logs -f gotosocial +``` + +如果一切正常，你应该会看到类似以下的内容： + +```text +time=2022-04-19T09:48:35Z level=info msg=connected to SQLITE database +time=2022-04-19T09:48:35Z level=info msg=MIGRATED DATABASE TO group #1 (20211113114307, 20220214175650, 20220305130328, 20220315160814) func=doMigration +time=2022-04-19T09:48:36Z level=info msg=instance account example.org CREATED with id 01EXX0TJ9PPPXF2C4N2MMMVK50 +time=2022-04-19T09:48:36Z level=info msg=created instance instance example.org with id 01PQT31C7BZJ1Q2Z4BMEV90ZCV +time=2022-04-19T09:48:36Z level=info msg=media manager cron logger: start[] +time=2022-04-19T09:48:36Z level=info msg=media manager cron logger: schedule[now 2022-04-19 09:48:36.096127852 +0000 UTC entry 1 next 2022-04-20 00:00:00 +0000 UTC] +time=2022-04-19T09:48:36Z level=info msg=started media manager remote cache cleanup job: will run next at 2022-04-20 00:00:00 +0000 UTC +time=2022-04-19T09:48:36Z level=info msg=listening on 0.0.0.0:8080 +``` + +## 创建你的第一个用户 + +现在 GoToSocial 已在运行，你应该至少为自己创建一个用户。如何创建用户可以在我们的[创建用户](../user_creation.md)指南中找到。 + +### 完成 + +GoToSocial 现在应该在你的机器上运行！要验证这一点，打开浏览器，导航到你设置的 `GTS_HOST` 值。你应该会看到 GoToSocial 的登陆页面。干得不错！ + +## （可选）反向代理 + +如果你想在 443 端口上运行其他网络服务器或想增加额外的安全层，你可能需要使用[反向代理](../reverse_proxy/index.md)。我们为几个流行的开源选项提供了指南，并乐意接受更多的拉取请求以增加新的指南。 diff --git a/docs/locales/zh/getting_started/installation/index.md b/docs/locales/zh/getting_started/installation/index.md new file mode 100644 index 000000000..d1160f3b8 --- /dev/null +++ b/docs/locales/zh/getting_started/installation/index.md @@ -0,0 +1,14 @@ +# 安装 + +正如我们在[版本发布](../releases.md)中提到的那样，我们发布了官方的二进制版本和容器版本。我们提供了一些指南，用于说明如何以这种方式部署你自己的 GoToSocial 实例。 + +在继续安装之前，请确保你已阅读[部署注意事项](../index.md)，并准备好了域名和服务器。 + +另外，花一点时间熟悉[如何配置](../../configuration/index.md)GoToSocial。 + +## 指南 + +对于第三方发布版本，我们不提供使用指南。需要参考他们自己的文档。我们的指南可能仍然有助于你熟悉需要设置和调整哪些配置选项。 + +* [裸机](metal.md) +* [容器](container.md) diff --git a/docs/locales/zh/getting_started/installation/metal.md b/docs/locales/zh/getting_started/installation/metal.md new file mode 100644 index 000000000..0419e8cc4 --- /dev/null +++ b/docs/locales/zh/getting_started/installation/metal.md @@ -0,0 +1,164 @@ +# 裸机 + +本指南将引导你在裸机上使用官方二进制发行版来运行 GoToSocial。 + +## 准备 VPS + +在 VPS 或你的家庭服务器终端中，创建 GoToSocial 运行的目录，它将用作存储的目录，以及存放 LetsEncrypt 证书的目录。 + +这意味着我们需要以下目录结构： + +``` +. +└── gotosocial + └── storage + └── certs +``` + +你可以通过以下命令一步创建所有目录： + +```bash +mkdir -p /gotosocial/storage/certs +``` + +如果你在机器上没有 root 权限，请使用类似 `~/gotosocial` 的路径。 + +## 下载发行版 + +在 VPS 或你的家庭服务器终端中，进入你刚创建的 GoToSocial 根目录： + +```bash +cd /gotosocial +``` + +现在，下载与你运行的操作系统和架构相对应的最新 GoToSocial 发行版压缩包。 + +!!! tip + 你可以在[这里](https://github.com/superseriousbusiness/gotosocial/releases)找到按发布时间排列的发布列表，最新的发行版位于最上面。 + +例如，下载适用于 64 位 Linux 的版本： + +```bash +GTS_VERSION=X.Y.Z # 替换此处 +GTS_TARGET=linux_amd64 +wget https://github.com/superseriousbusiness/gotosocial/releases/download/v${GTS_VERSION}/gotosocial_${GTS_VERSION}_${GTS_TARGET}.tar.gz +``` + +然后解压： + +```bash +tar -xzf gotosocial_${GTS_VERSION}_${GTS_TARGET}.tar.gz +``` + +这将在你的当前目录放置 `gotosocial` 二进制文件，以及包含网页前端资源的 `web` 文件夹和包含示例配置文件的 `example` 文件夹。 + +!!! danger + 如果你想使用基于当前主分支代码的 GoToSocial 快照构建，可以从[这里](https://minio.s3.superseriousbusiness.org/browser/gotosocial-snapshots)下载最近的二进制 .tar.gz 文件（基于提交哈希）。仅在你很清楚自己的操作时使用，否则请使用稳定版。 + +## 编辑配置文件 + +基于 `example` 文件夹中的 `config.yaml` 创建一个新的配置文件。你可以复制整个文件，但请确保仅保留已更改的设置。这让检查发布升级时的配置变化更加容易。 + +你可能需要更改以下设置： + +- 设置 `host` 为你要运行服务器的域名（例如 `example.org`）。 +- 设置 `port` 为 `443`。 +- 设置 `db-type` 为 `sqlite`。 +- 设置 `db-address` 为 `sqlite.db`。 +- 设置 `storage-local-base-path` 为你上面创建的存储目录（例如 `/gotosocial/storage`）。 +- 设置 `letsencrypt-enabled` 为 `true`。 +- 设置 `letsencrypt-cert-dir` 为你上面创建的证书存储目录（例如 `/gotosocial/storage/certs`）。 + +上述选项假设你使用 SQLite 作为数据库。如果你想使用 Postgres，请参阅[这里](../../configuration/database.md)获取配置选项。 + +!!! info "可选配置" + + `config.yaml` 文件中记录了许多其他配置选项，可以进一步自定义你的 GoToSocial 实例的行为。这些选项在可能的情况下使用合理的默认值，因此现在不必对此进行任何更改，但以下是一些你可能感兴趣的选项： + + - `instance-languages`: 确定实例首选语言的 [BCP47 语言标签](https://en.wikipedia.org/wiki/IETF_language_tag)数组。 + - `media-remote-cache-days`: 保存在存储中外站媒体的缓存天数。 + - `smtp-*`: 允许你的 GoToSocial 实例连接到邮件服务器并发送通知邮件的设置。 + + 如果你决定稍后设置/更改这些变量，请确保在进行更改后重新启动你的 GoToSocial 实例。 + +## 运行二进制文件 + +你现在可以运行二进制文件了。 + +使用以下命令启动 GoToSocial 服务器： + +```bash +./gotosocial --config-path ./config.yaml server start +``` + +服务器应该现在启动，并且你应该能通过浏览器访问你的域名的启动页面。请注意，首次创建 LetsEncrypt 证书可能需要最多一分钟的时间，因此如有必要请多次刷新页面。 + +注意在本例中我们假设可以运行在端口 443（标准 HTTPS 端口），并且没有其他进程运行在该端口。 + +## 创建你的用户 + +你可以使用 GoToSocial 二进制文件来创建并提权你的用户账户。所有这些过程在我们的[创建用户](../user_creation.md)指南中均有记录。 + +## 登录 + +你现在应该可以使用刚创建的账户的电子邮件地址和密码登录到你的实例。 + +## （可选）启用 systemd 服务 + +如果你不喜欢每次启动时手动启动 GoToSocial，你可能希望创建一个 systemd 服务为你启动。 + +首先，停止你的 GoToSocial 实例。 + +然后为你的 GoToSocial 安装创建一个新用户和用户组： + +```bash +sudo useradd -r gotosocial +sudo groupadd gotosocial +sudo usermod -a -G gotosocial gotosocial +``` + +然后使其成为你的 GoToSocial 安装目录的所有者，因为它们需要在其中进行读写： + +```bash +sudo chown -R gotosocial:gotosocial /gotosocial +``` + +你可以在 [GitHub](https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/example/gotosocial.service) 或你的安装文件夹中的 `example` 文件夹中找到一个 `gotosocial.service` 文件。 + +将它复制到 `/etc/systemd/system/gotosocial.service`： + +```bash +sudo cp /gotosocial/example/gotosocial.service /etc/systemd/system/ +``` + +然后使用 `sudoedit /etc/systemd/system/gotosocial.service` 在编辑器中打开文件。如果你在与本指南中使用的 `/gotosocial` 路径不同的目录中安装了 GoToSocial，请根据你的安装修改 `ExecStart=` 和 `WorkingDirectory=` 行。 + +!!! info "运行在端口 80 和 443" + + 如果你完全遵循本指南，你的 GoToSocial 实例将配置为绑定到端口 443 和 80，它们是已知的特权端口。要允许 GoToSocial 用户绑定到这些端口，你需要通过删除前导 `#` 来取消注释服务文件中的 `CAP_NET_BIND_SERVICE` 行。 + + 修改前： + + ``` + #AmbientCapabilities=CAP_NET_BIND_SERVICE + ``` + + 修改后： + + ``` + AmbientCapabilities=CAP_NET_BIND_SERVICE + ``` + + 如果你以后决定使用反向代理运行 GoToSocial（见下文），你可能希望重新注释此行以移除权限，因为反向代理将绑定到特权端口。 + +编辑完成后，保存并关闭文件，运行以下命令以启用服务： + +```bash +sudo systemctl enable --now gotosocial.service +``` + +GoToSocial 现在应该已启动并运行。 + +## （可选）反向代理 + +如果你想在端口 443 上运行其他网络服务器或想添加额外的安全层，你可能希望使用[反向代理](../reverse_proxy/index.md)。我们提供了几个流行开源选项的指南，并非常欢迎提供更多指南的 pull requests。 diff --git a/docs/locales/zh/getting_started/releases.md b/docs/locales/zh/getting_started/releases.md new file mode 100644 index 000000000..ba7bcd5a6 --- /dev/null +++ b/docs/locales/zh/getting_started/releases.md @@ -0,0 +1,11 @@ +# 发行版 + +GoToSocial 可以通过多种方式进行安装。我们发布官方的二进制文件以及容器镜像。 + +有许多第三方软件包由不同的发行版维护，一些用户还创建了额外的部署工具，以便你可以轻松地自行部署 GoToSocial。 + +{% + include "../../../../README.zh.md" + start='' + end='' +%} \ No newline at end of file diff --git a/docs/locales/zh/getting_started/reverse_proxy/apache-httpd.md b/docs/locales/zh/getting_started/reverse_proxy/apache-httpd.md new file mode 100644 index 000000000..f371178bc --- /dev/null +++ b/docs/locales/zh/getting_started/reverse_proxy/apache-httpd.md @@ -0,0 +1,261 @@ +# Apache HTTP 服务器 + +要将 Apache 用作 GoToSocial 的反向代理，你需要在服务器上安装它。如果你还希望 Apache 处理 TLS，就需要[配置 TLS 证书](../../advanced/certificates.md)。 + +Apache 已被[打包用于许多发行版](https://repology.org/project/apache/versions)。你很可能可以使用发行版的包管理器来安装它。你还可以使用发布到 Docker Hub 的[官方 Apache 镜像](https://hub.docker.com/_/httpd)通过容器运行 Apache。 + +本指南还将展示如何使用 certbot 来配置 TLS 证书。它同样被[打包在许多发行版](https://repology.org/project/certbot/versions)中，但许多发行版往往附带较旧版本的 certbot。如果遇到问题，可以考虑使用[容器镜像](https://hub.docker.com/r/certbot/certbot)。 + +## 配置 GoToSocial + +我们将让 Apache 处理 LetsEncrypt 证书，所以你需要在 GoToSocial 配置中关闭内置的 LetsEncrypt 支持。 + +首先在文本编辑器中打开文件： + +```bash +sudoedit /gotosocial/config.yaml +``` + +然后设置 `letsencrypt-enabled: false`。 + +如果反向代理将在同一台机器上运行，请将 `bind-address` 设置为 `"localhost"`，这样 GoToSocial 服务器仅通过环回才可以访问。否则可能会直接连接到 GoToSocial 以绕过你的代理，这是我们不希望的。 + +如果 GoToSocial 已经在运行，请重启它。 + +```bash +sudo systemctl restart gotosocial.service +``` + +或者，如果你没有配置 systemd 服务，只需手动重启。 + +## 设置 Apache + +### 所需的 Apache 模块 + +你需要确保安装并启用了多个 Apache 模块。这些模块应该都在你的发行版的 Apache 包中，但可能被拆分成单独的包。 + +你可以通过 `apachectl -M` 查看已安装哪些模块。 + +你需要加载以下模块： + +* `proxy_http` 来代理 HTTP 请求到 GoToSocial +* `ssl` 来处理 SSL/TLS +* `headers` 来操作 HTTP 请求和响应头 +* `rewrite` 来重写 HTTP 请求 +* `md` 用于 Lets Encrypt，自 2.4.30 开始可用 + +在 Debian、Ubuntu 和 openSUSE 中，可以使用 [`a2enmod`](https://manpages.debian.org/bookworm/apache2/a2enmod.8.en.html) 工具加载任何额外的模块。对于 Red Hat/CentOS 系列发行版，你需要在 Apache 配置中添加 [`LoadModule` 指令](https://httpd.apache.org/docs/2.4/mod/mod_so.html#loadmodule)。 + +### 使用 mod_md 启用 TLS + +!!! note + `mod_md` 自 Apache 2.4.30 开始可用，仍被视为实验性的。实际上，它在实践中表现良好，是最便捷的方法。 + +现在我们将配置 Apache HTTP 服务器来处理 GoToSocial 请求。 + +首先，我们将在 `/etc/apache2/sites-available` 中为 Apache HTTP 服务器编写配置： + +```bash +sudo mkdir -p /etc/apache2/sites-available/ +sudoedit /etc/apache2/sites-available/example.com.conf +``` + +在上述 `sudoedit` 命令中，将 `example.com` 替换为你的 GoToSocial 服务器的域名。 + +你将创建的文件应如下所示： + +=== "2.4.47+" + ```apache + MDomain example.com auto + MDCertificateAgreement accepted + + + ServerName example.com + + + + ServerName example.com + + SSLEngine On + ProxyPreserveHost On + # 设置为 127.0.0.1 而不是 localhost 以解决 https://stackoverflow.com/a/52550758 + ProxyPass / http://127.0.0.1:8080/ upgrade=websocket + ProxyPassReverse / http://127.0.0.1:8080/ + + RequestHeader set "X-Forwarded-Proto" expr=https + + ``` + +=== "旧版本" + ```apache + MDomain example.com auto + MDCertificateAgreement accepted + + + ServerName example.com + + + + ServerName example.com + + RewriteEngine On + RewriteCond %{HTTP:Upgrade} websocket [NC] + RewriteCond %{HTTP:Connection} upgrade [NC] + # 设置为 127.0.0.1 而不是 localhost 以解决 https://stackoverflow.com/a/52550758 + RewriteRule ^/?(.*) "ws://127.0.0.1:8080/$1" [P,L] + + SSLEngine On + ProxyPreserveHost On + # 设置为 127.0.0.1 而不是 localhost 以解决 https://stackoverflow.com/a/52550758 + ProxyPass / http://127.0.0.1:8080/ + ProxyPassReverse / http://127.0.0.1:8080/ + + RequestHeader set "X-Forwarded-Proto" expr=https + + ``` + +同样，将上述配置文件中的 `example.com` 替换为你的 GoToSocial 服务器的域名。如果你的域名是 `gotosocial.example.com`，那么用 `gotosocial.example.com` 作为正确的值。 + +你还应该将 `http://127.0.0.1:8080` 更改为 GoToSocial 服务器的正确地址和端口（如果它不在 `127.0.0.1:8080` 上）。例如，如果你在另一台机器上以 `192.168.178.69` 的本地 IP 运行 GoToSocial，并且端口为 `8080`，那么 `http://192.168.178.69:8080/` 就是正确的值。 + +需要 `Rewrite*` 指令以确保 Websocket 流连接正常工作。有关更多信息，请参阅 [websocket](./websocket.md) 文档。 + +`ProxyPreserveHost On` 是必要的：它保证代理和 GoToSocial 使用相同的服务器名称。否则，GoToSocial 会构建错误的身份验证标头，所有联合尝试将被拒绝并返回 401 未授权。 + +默认情况下，Apache 会在转发的请求中设置 `X-Forwarded-For`。为了使这个设置和限速工作，设置 `trusted-proxies` 配置变量。请参阅[限速](../../api/ratelimiting.md)和[基础配置](../../configuration/general.md)文档。 + +保存并关闭配置文件。 + +现在，我们需要将刚创建的文件链接到 Apache HTTP 服务器读取已激活站点配置的文件夹中。 + +```bash +sudo mkdir /etc/apache2/sites-enabled +sudo ln -s /etc/apache2/sites-available/example.com.conf /etc/apache2/sites-enabled/ +``` + +在上述 `ln` 命令中，将 `example.com` 替换为你的 GoToSocial 服务器的域名。 + +现在检查配置错误。 + +```bash +sudo apachectl -t +``` + +如果一切正常，你应该看到以下输出： + +```text +Syntax OK +``` + +一切正常？太好了！然后重启 Apache HTTP 服务器以加载新的配置文件。 + +```bash +sudo systemctl restart apache2 +``` + +现在，观测日志以查看新 LetsEncrypt 证书何时送达（`tail -F /var/log/apache2/error.log`），然后使用上述 `systemctl restart` 命令再次重载 Apache。之后，你应该就可以开始了！ + +每当 `mod_md` 获取新证书时，需要重启（或重载）Apache HTTP 服务器；请参阅该模块的文档以了解[更多信息](https://github.com/icing/mod_md#how-to-manage-server-reloads)。 + +根据你使用的 Apache HTTP 服务器版本，可能会看到以下错误：`error (specific information not available): acme problem urn:ietf:params:acme:error:invalidEmail: Error creating new account :: contact email "webmaster@localhost" has invalid domain : Domain name needs at least one dot` + +如果发生这种情况，你需要进行以下操作之一（或全部）： + +1. 更新 `/etc/apache2/sites-enabled/000-default.conf` 并将 `ServerAdmin` 值更改为有效的电子邮件地址（然后重载 Apache HTTP 服务器）。 +2. 在 `/etc/apache2/sites-available/example.com.conf` 的 `MDomain` 行下添加行 `MDContactEmail your.email.address@whatever.com`，将 `your.email.address@whatever.com` 替换为有效的电子邮件地址，并将 `example.com` 替换为你的 GoToSocial 域名。 + +### 使用外部管理证书启用 TLS + +!!! note + 我们有关于如何[配置 TLS 证书](../../advanced/certificates.md)的额外文档，其中还提供了不同发行版的其他内容和教程链接，可能值得查看。 + +如果你更喜欢手动设置或使用不同服务（如 Certbot）来管理 SSL，可以为你的 Apache HTTP 服务器使用更简单的设置。 + +首先，我们将在 `/etc/apache2/sites-available` 中为 Apache HTTP 服务器编写配置： + +```bash +sudo mkdir -p /etc/apache2/sites-available/ +sudoedit /etc/apache2/sites-available/example.com.conf +``` + +在上述 `sudoedit` 命令中，将 `example.com` 替换为你的 GoToSocial 服务器的域名。 + +你将创建的文件最初应如下所示，针对 80（必需）和 443 端口（可选）： + +=== "2.4.47+" + ```apache + + ServerName example.com + + ProxyPreserveHost On + # 设置为 127.0.0.1 而不是 localhost 以解决 https://stackoverflow.com/a/52550758 + ProxyPass / http://127.0.0.1:8080/ upgrade=websocket + ProxyPassReverse / http://127.0.0.1:8080/ + + ``` + +=== "旧版本" + ```apache + + ServerName example.com + + RewriteEngine On + RewriteCond %{HTTP:Upgrade} websocket [NC] + RewriteCond %{HTTP:Connection} upgrade [NC] + # 设置为 127.0.0.1 而不是 localhost 以解决 https://stackoverflow.com/a/52550758 + RewriteRule ^/?(.*) "ws://127.0.0.1:8080/$1" [P,L] + + ProxyPreserveHost On + # 设置为 127.0.0.1 而不是 localhost 以解决 https://stackoverflow.com/a/52550758 + ProxyPass / http://127.0.0.1:8080/ + ProxyPassReverse / http://127.0.0.1:8080/ + + + ``` + +同样，将上述配置文件中的 `example.com` 替换为你的 GoToSocial 服务器的域名。如果你的域名是 `gotosocial.example.com`，那么用 `gotosocial.example.com` 作为正确的值。 + +你还应该将 `http://127.0.0.1:8080` 更改为 GoToSocial 服务器的正确地址和端口（如果它不在 `127.0.0.1:8080` 上）。例如，如果你在另一台机器上以 `192.168.178.69` 的本地 IP 运行 GoToSocial，并且端口为 `8080`，那么 `http://192.168.178.69:8080/` 就是正确的值。 + +需要 `Rewrite*` 指令以确保 Websocket 流连接正常工作。有关更多信息，请参阅 [websocket](websocket.md) 文档。 + +`ProxyPreserveHost On` 是必需的：它保证代理和 GoToSocial 使用相同的服务器名称。否则，GoToSocial 会构建错误的身份验证头，所有联合尝试将被拒绝并返回 401 未授权。 + +在443端口提供初始设置以供外部工具进行附加管理时，你可以使用服务器提供的默认证书，你可以在 `/etc/apache2/sites-available/` 的 `default-ssl.conf` 文件中找到引用。 + +保存并关闭配置文件。 + +现在，我们需要将刚创建的文件链接到 Apache HTTP 服务器读取已激活站点配置的文件夹中。 + +```bash +sudo mkdir /etc/apache2/sites-enabled +sudo ln -s /etc/apache2/sites-available/example.com.conf /etc/apache2/sites-enabled/ +``` + +在上述 `ln` 命令中，将 `example.com` 替换为你的 GoToSocial 服务器的域名。 + +现在检查配置错误。 + +```bash +sudo apachectl -t +``` + +如果一切正常，你应该看到以下输出： + +```text +Syntax OK +``` + +一切正常？太好了！然后重启 Apache HTTP 服务器以加载新的配置文件。 + +```bash +sudo systemctl restart apache2 +``` + +## 故障排除 + +如果无法在浏览器中连接到站点，则反向代理设置不起作用。比较 Apache 日志文件（`tail -F /var/log/apache2/access.log`）和 GoToSocial 日志文件。发出的请求必须在两个地方中都显示出来。仔细检查 `ProxyPass` 设置。 + +如果可以连接，但贴文未能联合且账户无法从其他地方找到，请检查日志。如果你看到尝试读取你的个人资料(比如 `level=INFO … method=GET statusCode=401 path=/users/your_username msg="Unauthorized: …"`)或向你的收件箱发送贴文的信息（比如 `level=INFO … method=POST statusCode=404 path=/your_username/inbox msg="Not Found: …"`），则联合已被中断。仔细检查 `ProxyPreserveHost` 设置。 + +如果可以连接但无法在 Mastodon 客户端应用中授权账户，请确保从正确的域名启动登录。当使用[分域](../../advanced/host-account-domain.md)设置时，必须从 `host` 域启动登录，而不是 `account-domain`。GoToSocial 设置了 `Content-Security-Policy` 头，以抵御 XSS 和数据注入攻击。该头应保持不变，确保你的反向代理没有修改、覆盖或取消设置它。 diff --git a/docs/locales/zh/getting_started/reverse_proxy/caddy.md b/docs/locales/zh/getting_started/reverse_proxy/caddy.md new file mode 100644 index 000000000..44511a0b4 --- /dev/null +++ b/docs/locales/zh/getting_started/reverse_proxy/caddy.md @@ -0,0 +1,110 @@ +# Caddy 2 + +## 要求 + +在此指南中，你需要使用 [Caddy 2](https://caddyserver.com/)，无需其他依赖。Caddy 管理 Lets Encrypt 证书及其续订。 + +Caddy 可以通过大多数流行的包管理器获取，或者你可以获取一个静态二进制文件。最新的安装指南请参考[他们的手册](https://caddyserver.com/docs/install)。 + +### Debian, Ubuntu, Raspbian + +```bash +# 为其自定义仓库添加密钥环。 +sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https +curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg +curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list + +# 更新软件包并安装 +sudo apt update +sudo apt install caddy +``` + +### Fedora, Redhat, Centos + +```bash +dnf install 'dnf-command(copr)' +dnf copr enable @caddy/caddy +dnf install caddy +``` + +### Arch + +```bash +pacman -Syu caddy +``` + +### FreeBSD + +```bash +sudo pkg install caddy +``` + +## 配置 GoToSocial + +如果 GoToSocial 已经在运行，先停止它。 + +```bash +sudo systemctl stop gotosocial +``` + +在你的 GoToSocial 配置中，通过将 `letsencrypt-enabled` 设置为 `false` 来关闭 Lets Encrypt。 + +如果你之前在 443 端口运行 GoToSocial，需将 `port` 值改回默认的 `8080`。 + +如果反向代理将在同一台机器上运行，将 `bind-address` 设置为 `"localhost"`，这样 GoToSocial 服务器只能通过回环地址访问。否则可能会有人直接连接到 GoToSocial 以绕过你的代理，这是不安全的。 + +## 设置 Caddy + +我们将配置 Caddy 2 来在主域名 example.org 上使用 GoToSocial。由于 Caddy 负责获取 Lets Encrypt 证书，我们只需正确配置它一次。 + +在最简单的使用场景中，Caddy 默认使用名为 Caddyfile 的文件。它可以在更改时重新加载，或者通过 HTTP API 配置以实现零停机，但这超出了我们当前的讨论范围。 + +```bash +sudo mkdir -p /etc/caddy +sudo vim /etc/caddy/Caddyfile +``` + +在编辑上述文件时，你应将 'example.org' 替换为你的域名。你的域名应在当前配置中出现两次。如果你为 GoToSocial 选择了端口号 8080 以外的端口，请在反向代理行中更改端口号以匹配它。 + +你即将创建的文件应如下所示： + +```Caddyfile +example.org { + # 可选，但推荐，使用适当的协议压缩流量 + encode zstd gzip + + # 实际的代理配置为端口 8080（除非你选择了其他端口号） + reverse_proxy * http://127.0.0.1:8080 { + # 立即刷新，以防止缓冲响应给客户端 + flush_interval -1 + } +} +``` + +默认情况下，caddy 在转发请求中设置 `X-Forwarded-For`。为了使其与速率限制配合使用，请设置 `trusted-proxies` 配置变量。详见[速率限制](../../api/ratelimiting.md)和[通用配置](../../configuration/general.md)文档。 + +有关高级配置，请查看 Caddy 文档中的[反向代理指令](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy)。 + +现在检查配置错误。 + +```bash +sudo caddy validate +``` + +如果一切正常，你将看到一些信息行作为输出。除非前面标有 *[err]* 的行，否则你就准备好了。 + +一切正常吗？太好了！然后重启 caddy 以加载你的新配置文件。 + +```bash +sudo systemctl restart caddy +``` + +如果一切顺利，你现在就可以享受你的 GoToSocial 实例，所以我们将再次启动它。 + +```bash +sudo systemctl start gotosocial +``` + +## 结果 + +你现在应该能够在浏览器中打开你的实例的启动页面，并会看到它在 HTTPS 下运行！ diff --git a/docs/locales/zh/getting_started/reverse_proxy/index.md b/docs/locales/zh/getting_started/reverse_proxy/index.md new file mode 100644 index 000000000..40bafc6a7 --- /dev/null +++ b/docs/locales/zh/getting_started/reverse_proxy/index.md @@ -0,0 +1,43 @@ +# 反向代理 + +GoToSocial 可以直接暴露到互联网上。不过，许多人更愿意使用反向代理来处理外部连接。这也可以使你对 TLS 配置有更大的控制权，并启用一些更高级的场景，比如资源缓存。 + +## 一般步骤 + +要使用反向代理，通常需要做以下几件事： + +* 配置某种方式获取主机域名的 TLS 证书 +* 将 GoToSocial 绑定到一个本地 IP 而不是公网 IP，并使用非特权端口。调整 `bind-address` 和 `port` 配置选项 +* 如果你使用了 Lets Encrypt，在 GoToSocial 中禁用它。将 `letsencrypt-enabled` 设置为 `false` +* 配置反向代理以处理 TLS 并将请求代理到 GoToSocial + +!!! warning + 不要更改 `host` 配置选项的值。这必须保持为其他实例在互联网上看到的实际域名。相反，改变 `bind-address` 并更新 `port` 和 `trusted-proxies`。 + +### 容器 + +当你使用我们的[Docker Compose 示例指南](../installation/container.md)部署 GoToSocial 时，它默认绑定到端口 `443`，假设你希望直接将其暴露到互联网上。要在反向代理后运行它，你需要更改这些设置。 + +在 Compose 文件中： + +* 注释掉 `ports` 定义中的 `- "443:8080"` 行 +* 如果你启用了 Lets Encrypt 支持： + * 注释掉 `ports` 定义中的 `- "80:80"` 行 + * 将 `GTS_LETSENCRYPT_ENABLED` 设置回 `"false"` 或注释掉 +* 改为取消注释 `- "127.0.0.1:8080:8080"` 行 + +这将导致 Docker 仅在 `127.0.0.1` 的端口 `8080` 上转发连接到容器，有效地将其与外界隔离。你现在可以指示反向代理将请求发送到那里。 + +## 指南 + +我们为以下服务器提供了指南： + +* [nginx](nginx.md) +* [Apache httpd](apache-httpd.md) +* [Caddy 2](caddy.md) + +## WebSockets + +使用反向代理时，必须特别注意允许 WebSockets 正常工作。因为许多客户端应用程序使用 WebSockets 来流式传输你的时间线。WebSockets 不用于联合。 + +请确保阅读 [WebSocket](websocket.md) 文档，并相应地配置你的反向代理。 diff --git a/docs/locales/zh/getting_started/reverse_proxy/nginx.md b/docs/locales/zh/getting_started/reverse_proxy/nginx.md new file mode 100644 index 000000000..76c5054e4 --- /dev/null +++ b/docs/locales/zh/getting_started/reverse_proxy/nginx.md @@ -0,0 +1,186 @@ +# NGINX + +要使用 NGINX 作为 GoToSocial 的反向代理，你需要在服务器上安装它。如果你打算让 NGINX 处理 TLS，你还需要[配置 TLS 证书](../../advanced/certificates.md)。 + +!!! tip + 通过在 `server` 块中包含 `http2 on;` 来启用 NGINX 的 HTTP/2。这样可以加快客户端的体验。请参阅 [ngx_http_v2_module 文档](https://nginx.org/en/docs/http/ngx_http_v2_module.html#example)。 + +NGINX 已为[多个发行版打包](https://repology.org/project/nginx/versions)。你很可能可以使用发行版的包管理器来安装它。你也可以使用 Docker Hub 上发布的[官方 NGINX 镜像](https://hub.docker.com/_/nginx)通过容器运行 NGINX。 + +在本指南中，我们还将展示如何使用 certbot 配置 TLS 证书。它也在[许多发行版中打包](https://repology.org/project/certbot/versions)，但许多发行版往往提供的 certbot 版本较旧。如果遇到问题，可以考虑使用[容器镜像](https://hub.docker.com/r/certbot/certbot)。 + +## 配置 GoToSocial + +如果 GoToSocial 已在运行，先停止它。 + +```bash +sudo systemctl stop gotosocial +``` + +或者如果你没有 systemd 服务，只需手动停止它。 + +这样调整你的 GoToSocial 配置： + +```yaml +letsencrypt-enabled: false +port: 8080 +bind-address: 127.0.0.1 +``` + +第一个设置禁用了内置的 TLS 证书配置。由于 NGINX 现在将处理这些流量，GoToSocial 不再需要绑定到 443 端口或任何特权端口。 + +通过将 `bind-address` 设置为 `127.0.0.1`，GoToSocial 将不再能直接从外部访问。如果你的 NGINX 和 GoToSocial 实例不在同一台服务器上，你需要绑定一个允许你的反向代理访问你的 GoToSocial 实例的 IP 地址。绑定到私有 IP 地址可以确保只有通过 NGINX 才能访问 GoToSocial。 + +## 设置 NGINX + +我们首先设置 NGINX 为 GoToSocial 提供不安全的 http 服务，然后使用 Certbot 自动升级为 https 服务。 + +请勿在此完成之前尝试使用，否则你将有泄露密码的风险，或破坏联合。 + +首先，我们将为 NGINX 编写一个配置文件，并将其放入 `/etc/nginx/sites-available` 中。 + +```bash +sudo mkdir -p /etc/nginx/sites-available +sudoedit /etc/nginx/sites-available/yourgotosocial.url.conf +``` + +在上述命令中，将 `yourgotosocial.url` 替换为你的实际 GoToSocial 主机值。所以如果你的 `host` 设置为 `example.org`，那么文件应该命名为 `/etc/nginx/sites-available/example.org.conf` + +你要创建的文件应该如下所示： + +```nginx +server { + listen 80; + listen [::]:80; + server_name example.org; + location / { + # 设置为 127.0.0.1 而不是 localhost 以解决 https://stackoverflow.com/a/52550758 + proxy_pass http://127.0.0.1:8080; + proxy_set_header Host $host; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; + } + client_max_body_size 40M; +} +``` + +将 `proxy_pass` 改为你实际运行 GoToSocial 的 IP 和端口（如果不是 `127.0.0.1:8080`），并将 `server_name` 改为你自己的域名。 + +如果你的域名是 `example.org`，那么 `server_name example.org;` 就是正确的值。 + +如果你在另一台本地 IP 为 192.168.178.69 的机器上运行 GoToSocial，并在端口 8080 上，那么 `proxy_pass http://192.168.178.69:8080;` 就是正确的值。 + +**注意**：如果你的服务器不支持 IPv6，可以删除 `listen [::]:80;` 这一行。 + +**注意**：`proxy_set_header Host $host;` 必不可少。它确保代理和 GoToSocial 使用相同的服务器名称。如果没有，GoToSocial 将构建错误的身份验证标头，导致所有的联合尝试以 401 被拒绝。 + +**注意**：`Connection` 和 `Upgrade` 头用于 WebSocket 连接。请参阅 [WebSocket 文档](websocket.md)。 + +**注意**：本例中 `client_max_body_size` 设置为 40M，这是 GoToSocial 的默认视频上传大小。根据需要你可以将此值设置得更大或更小。nginx 的默认值仅为 1M，太小了。 + +**注意**：为了使 `X-Forwarded-For` 和限流生效，请设置 `trusted-proxies` 配置变量。请参阅[限流](../../api/ratelimiting.md)和[通用配置](../../configuration/general.md)文档。 + +接下来我们需要将刚创建的文件链接到 nginx 从中读取活动站点配置的文件夹中。 + +```bash +sudo mkdir -p /etc/nginx/sites-enabled +sudo ln -s /etc/nginx/sites-available/yourgotosocial.url.conf /etc/nginx/sites-enabled/ +``` + +再次将 `yourgotosocial.url` 替换为你的实际 GoToSocial 主机值。 + +现在检查配置错误。 + +```bash +sudo nginx -t +``` + +如果一切正常，你应该会看到以下输出： + +```text +nginx: the configuration file /etc/nginx/nginx.conf syntax is ok +nginx: configuration file /etc/nginx/nginx.conf test is successful +``` + +一切正常吗？太好了！然后重启 nginx 以加载新的配置文件。 + +```bash +sudo systemctl restart nginx +``` + +## 设置 TLS + +!!! warning + 我们有关于如何[配置 TLS 证书](../../advanced/certificates.md)的附加文档，还提供了有关不同发行版的附加内容和教程链接，值得一看。 + +你现在可以运行 certbot，它将引导你完成启用 https 的步骤。 + +```bash +sudo certbot --nginx +``` + +完成后，它应该自动编辑你的配置文件以启用 https。 + +最后再次重新加载 NGINX： + +```bash +sudo systemctl restart nginx +``` + +现在重新启动 GoToSocial： + +```bash +sudo systemctl start gotosocial +``` + +## 安全加固 + +如果你想通过高级配置选项加强 NGINX 部署，网上有很多指南（[例如这个](https://beaglesecurity.com/blog/article/nginx-server-security.html)）。请尝试找到最新的指南。Mozilla 还[在此处](https://ssl-config.mozilla.org/)发布了最佳实践 SSL 配置。 + +## 结果 + +你现在应该可以在浏览器中打开实例的启动页面，并看到它运行在 https 下！ + +如果你再次打开 NGINX 配置，你会发现 Certbot 添加了一些额外的行。 + +!!! warning + 根据你设置 Certbot 时选择的选项，以及使用的 NGINX 版本，可能会有所不同。 + +```nginx +server { + server_name example.org; + location / { + # 设置为 127.0.0.1 而不是 localhost 以解决 https://stackoverflow.com/a/52550758 + proxy_pass http://127.0.0.1:8080; + proxy_set_header Host $host; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; + } + client_max_body_size 40M; + + listen [::]:443 ssl; # 由 Certbot 管理 + listen 443 ssl; # 由 Certbot 管理 + http2 on; # 由 Certbot 管理 + ssl_certificate /etc/letsencrypt/live/example.org/fullchain.pem; # 由 Certbot 管理 + ssl_certificate_key /etc/letsencrypt/live/example.org/privkey.pem; # 由 Certbot 管理 + include /etc/letsencrypt/options-ssl-nginx.conf; # 由 Certbot 管理 + ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # 由 Certbot 管理 +} + +server { + if ($host = example.org) { + return 301 https://$host$request_uri; + } # 由 Certbot 管理 + + listen 80; + listen [::]:80; + server_name example.org; + return 404; # 由 Certbot 管理 +} +``` + +关于 nginx 的其他配置选项（包括静态资源服务和缓存），请参阅文档的[高级部分](../../advanced/index.md)。 diff --git a/docs/locales/zh/getting_started/reverse_proxy/websocket.md b/docs/locales/zh/getting_started/reverse_proxy/websocket.md new file mode 100644 index 000000000..e1391ec45 --- /dev/null +++ b/docs/locales/zh/getting_started/reverse_proxy/websocket.md @@ -0,0 +1,43 @@ +# WebSocket + +GoToSocial 使用安全的 [WebSocket 协议](https://en.wikipedia.org/wiki/WebSocket)（即 `wss`）来通过客户端应用程序（如 Semaphore）实现贴文和通知的实时更新。 + +为了使用此功能，你需要确保配置 GoToSocial 所在的代理允许 WebSocket 连接通过。 + +WebSocket 端点位于 `wss://example.org/api/v1/streaming`，其中 `example.org` 是你的 GoToSocial 实例的域名。 + +WebSocket 端点使用在[通用配置](../../configuration/general.md)的 `port` 部分中配置的相同端口。 + +典型的 WebSocket **请求**头，如 Pinafore 所发送的如下所示： + +```text +Host: example.org +User-Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:99.0) Gecko/20100101 Firefox/99.0 +Accept: */* +Accept-Language: en-US,en;q=0.5 +Accept-Encoding: gzip, deflate, br +Sec-WebSocket-Version: 13 +Origin: https://pinafore.social +Sec-WebSocket-Protocol: null +Sec-WebSocket-Extensions: permessage-deflate +Sec-WebSocket-Key: YWFhYWFhYm9vYmllcwo= +DNT: 1 +Connection: keep-alive, Upgrade +Sec-Fetch-Dest: websocket +Sec-Fetch-Mode: websocket +Sec-Fetch-Site: cross-site +Pragma: no-cache +Cache-Control: no-cache +Upgrade: websocket +``` + +典型的 WebSocket **响应**头，如 GoToSocial 返回的如下所示： + +```text +HTTP/1.1 101 Switching Protocols +Upgrade: websocket +Connection: Upgrade +Sec-WebSocket-Accept: WVdGaFlXRmhZbTl2WW1sbGN3bz0K +``` + +无论你的设置如何，你都需要确保这些头在你的反向代理中被允许，这可能需要根据所使用的具体反向代理进行额外配置。 diff --git a/docs/locales/zh/getting_started/user_creation.md b/docs/locales/zh/getting_started/user_creation.md new file mode 100644 index 000000000..6b2479adc --- /dev/null +++ b/docs/locales/zh/getting_started/user_creation.md @@ -0,0 +1,49 @@ +# 创建用户 + +无论使用哪种安装方法，你都需要创建一些用户。GoToSocial 目前还没有通过网页 UI 创建用户或让人们通过网页 UI 注册的功能。 + +在此期间，你可以使用 CLI 创建用户： + +```sh +./gotosocial --config-path /path/to/config.yaml \ + admin account create \ + --username some_username \ + --email some_email@whatever.org \ + --password 'SOME_PASSWORD' +``` + +在上述命令中，将 `some_username` 替换为你想要的用户名，将 `some_email@whatever.org` 替换为你想关联到用户的电子邮件地址，将 `SOME_PASSWORD` 替换为一个安全的密码。 + +如果你想让用户拥有管理员权限，可以使用类似的命令提升他们： + +```sh +./gotosocial --config-path /path/to/config.yaml \ + admin account promote --username some_username +``` + +将 `some_username` 替换为你刚创建的账户的用户名。 + +!!! warning "提权需要重启服务器" + + 由于 GoToSocial 的缓存机制，某些管理员 CLI 命令在执行后需要重启服务器才能使更改生效。 + + 例如，将用户提升为管理员后，你需要重启 GoToSocial 服务器，以便从数据库加载新值。 + +!!! tip + + 要查看其他可用的 CLI 命令，请点击[这里](../admin/cli.md)。 + +## 容器 + +当从容器运行 GoToSocial 时，你需要在容器中执行上述命令。如何操作取决于你的容器运行时，但对于 Docker 来说，应该像这样： + +```sh +docker exec -it CONTAINER_NAME_OR_ID \ + /gotosocial/gotosocial \ + admin account create \ + --username some_username \ + --email someone@example.org \ + --password 'some_very_good_password' +``` + +如果你遵循我们的 Docker 指南，容器名应该为 `gotosocial`。你可以通过 `docker ps` 获取名称或 ID。 diff --git a/docs/locales/zh/index.md b/docs/locales/zh/index.md new file mode 100644 index 000000000..48466ef4c --- /dev/null +++ b/docs/locales/zh/index.md @@ -0,0 +1,17 @@ +{% + include "../../../README.zh.md" + start='' + end='' +%} + +{% + include "../../../README.zh.md" + start='' + end='' +%} + +{% + include "../../../README.zh.md" + start='' + end='' +%} diff --git a/docs/locales/zh/mkdocs.yml b/docs/locales/zh/mkdocs.yml new file mode 100644 index 000000000..7b434702d --- /dev/null +++ b/docs/locales/zh/mkdocs.yml @@ -0,0 +1,98 @@ +INHERIT: ../../../mkdocs.yml +site_name: "GoToSocial 文档" +theme: + language: zh +docs_dir: . +edit_uri: edit/main/docs/locales/zh-cn/ +copyright: GoToSocial 以 GNU AGPL v3 许可授权。版权所有 (C) 全体 GoToSocial 开发者 admin@gotosocial.org + +nav: + - "主页": "index.md" + - "FAQ": "faq.md" + - "使用指南": + - "user_guide/settings.md" + - "user_guide/posts.md" + - "user_guide/search.md" + - "user_guide/custom_css.md" + - "user_guide/password_management.md" + - "user_guide/rss.md" + - "user_guide/migration.md" + - "开始部署": + - "getting_started/index.md" + - "getting_started/releases.md" + - "安装": + - "getting_started/installation/index.md" + - "getting_started/installation/metal.md" + - "getting_started/installation/container.md" + - "反向代理": + - "getting_started/reverse_proxy/index.md" + - "getting_started/reverse_proxy/nginx.md" + - "getting_started/reverse_proxy/apache-httpd.md" + - "getting_started/reverse_proxy/caddy.md" + - "getting_started/reverse_proxy/websocket.md" + - "getting_started/user_creation.md" + - "配置": + - "configuration/index.md" + - "configuration/general.md" + - "configuration/database.md" + - "configuration/web.md" + - "configuration/instance.md" + - "configuration/accounts.md" + - "configuration/media.md" + - "configuration/storage.md" + - "configuration/statuses.md" + - "configuration/tls.md" + - "configuration/oidc.md" + - "configuration/smtp.md" + - "configuration/syslog.md" + - "configuration/httpclient.md" + - "configuration/advanced.md" + - "configuration/observability.md" + - "进阶": + - "概述": "advanced/index.md" + - "advanced/host-account-domain.md" + - "advanced/outgoing-proxy.md" + - "缓存": + - "advanced/caching/index.md" + - "advanced/caching/api.md" + - "advanced/caching/assets-media.md" + - "advanced/certificates.md" + - "安全加固": + - "advanced/security/index.md" + - "advanced/security/sandboxing.md" + - "advanced/security/firewall.md" + - "advanced/healthchecks.md" + - "advanced/tracing.md" + - "advanced/metrics.md" + - "advanced/replicating-sqlite.md" + - "advanced/sqlite-networked-storage.md" + - "Advanced builds": + - "advanced/builds/nowasm.md" + + - "管理": + - "admin/settings.md" + - "admin/signups.md" + - "admin/federation_modes.md" + - "admin/domain_blocks.md" + - "admin/request_filtering_modes.md" + - "admin/robots.md" + - "admin/cli.md" + - "admin/backup_and_restore.md" + - "admin/media_caching.md" + - "admin/spam.md" + - "admin/database_maintenance.md" + - "admin/themes.md" + - "联合": + - "federation/index.md" + - "federation/http_signatures.md" + - "federation/access_control.md" + - "federation/ratelimiting.md" + - "federation/actors.md" + - "federation/posts.md" + - "federation/moderation.md" + - "federation/glossary.md" + - "客户端 API 文档": + - "api/authentication.md" + - "api/swagger.md" + - "api/ratelimiting.md" + - "api/throttling.md" diff --git a/docs/locales/zh/user_guide/custom_css.md b/docs/locales/zh/user_guide/custom_css.md new file mode 100644 index 000000000..4f2195930 --- /dev/null +++ b/docs/locales/zh/user_guide/custom_css.md @@ -0,0 +1,73 @@ +# 自定义 CSS（高级） + +CSS（级联样式表）是一种与 HTML 一起使用的编码语言，它决定了网页在浏览器中的外观： + +> HTML 用于定义内容的结构和语义，CSS 用于对其进行样式化和布局。例如，你可以使用 CSS 来更改内容的字体、颜色、大小和间距，分成多列，或添加动画和其他装饰功能。 +> +> -- [学习 CSS (Mozilla)](https://developer.mozilla.org/zh-CN/docs/Learn/CSS) + +根据你的 GoToSocial 实例管理员配置的设置，你可以通过用户设置面板上传自定义 CSS 到你的账户。 + +这允许你为使用网络浏览器访问你的 GoToSocial 账户页的用户自定义页面外观。 + +## 示例 - 更改背景颜色 + +这是一个标准的 GoToSocial 账户页面： + +![一个 GoToSocial 测试账户页面。标准配色方案是灰色、蓝色和橙色。](./../../../assets/cssstandard.png) + +假设我们想将背景颜色改为黑色而不是灰色。 + +在用户设置面板中，我们在自定义 CSS 字段中输入以下 CSS 代码： + +```css +.page { + background: black; +} +``` + +然后我们点击保存账户信息。 + +如果我们返回到账户页面并刷新页面，现在它看起来是这样的： + +![同一个 GoToSocial 测试账户页面。背景现在是黑色。](./../../../assets/cssblack.png) + +如果我们想要更炫一点，可以使用下面的 CSS 代码为背景添加渐变效果： + +```css +.page { + background: linear-gradient(crimson, purple); +} +``` + +保存 CSS 并刷新账户页面后，页面现在看起来是这样的： + +![同一个 GoToSocial 测试账户页面。背景现在从深红色开始，向下渐变为紫色。](./../../../assets/cssgradient.png) + +## 可访问性 + +可访问的 HTML 和 CSS 的重要性不容忽视。以下节选自 W3： + +> 网络的基本设计理念是为所有人服务，无论他们的硬件、软件、语言、位置或能力如何。当网络达到这一目标时，它对具有不同的听力、行动、视力和认知能力的人来说都是可访问的。 +> +> 因此，残疾带来的影响在网络上有根本性的不同，因为网络消除了许多人在物理世界中面临的交流和互动障碍。然而，当网站、应用程序、技术或工具设计不佳时，它们可能会带来把人排除在网络之外的新障碍。 +> +> 对于希望创建高质量网站和网络工具，而不希望把使用其产品和服务的部分人群排除在外的开发者和组织来说，可访问性是必不可少的。 +> +> -- [网络可访问性介绍](https://www.w3.org/WAI/fundamentals/accessibility-intro/) + +标准的 GoToSocial 主题在设计中考虑了网络可访问性，特别是在布局、颜色对比、字体大小等方面。 + +如果你为账户编写自定义 CSS，非常重要的一点是确保它保持可读，并按预期运行。按钮应看起来像按钮，链接应看起来像链接，文本应以可读的字体呈现，元素不应在页面上跳动等。网页可以做到漂亮且令人兴奋，而不必牺牲可读性或让事情过于复杂。 + +如果你更改你的配色方案，最好验证新颜色，以确保它们具有足够的对比度以便视觉障碍（如色盲）的人可以阅读。一旦更新了 CSS，试着将你的账户 URL 输入对比度检查工具中，如[颜色对比度可访问性验证器](https://color.a11y.com/Contrast)。你还可以使用网络浏览器的“可访问性”选项卡检查是否存在任何问题。 + +以可访问性为中心进行样式设置可以让网络对所有人更友好！查看下面的链接以获取更多信息。 + +## 有用链接 + +- [学习 CSS (Mozilla)](https://developer.mozilla.org/zh-CN/docs/Learn/CSS) +- [CSS 教程 (W3 Schools)](https://www.w3schools.com/Css/default.asp) +- [CSS 和 JavaScript 可访问性最佳实践 (Mozilla)](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/CSS_and_JavaScript#css) +- [WAVE 网页可访问性评估工具](https://wave.webaim.org/) +- [颜色对比度可访问性验证器](https://color.a11y.com/Contrast) diff --git a/docs/locales/zh/user_guide/migration.md b/docs/locales/zh/user_guide/migration.md new file mode 100644 index 000000000..743da6b3c --- /dev/null +++ b/docs/locales/zh/user_guide/migration.md @@ -0,0 +1,78 @@ +# 迁移 + +GoToSocial 支持使用 `Move` 活动进行账号迁移。 + +这允许你将账号迁移到你的 GoToSocial 账号，或者将你的 GoToSocial 账号迁移到其他账号。 + +迁移是软件无关的，因此你可以将账号迁移到其它软件或从任何支持 `Move` 活动的软件发起迁移，无论具体的软件是什么。例如，你可以将 GoToSocial 账号迁移到 Mastodon 账号，将 Mastodon 账号迁移到 GoToSocial 账号，将 GoToSocial 账号迁移到或从 Akkoma、Misskey、GoToSocial 等。 + +!!! tip + 根据目标账号所在软件的不同，目标账号的 URI（用于别名和迁移）应该类似于 `https://mastodon.example.org/users/account_you_are_moving_to`。如果你不确定使用哪种格式，请咨询你要迁移或设置别名的实例管理员。 + +!!! warning + GoToSocial 要求 7 天的账号迁移冷却期，以防止过度切换实例（以及潜在的屏蔽规避风险）。 + + 如果任何一个发起新迁移尝试的账号在最近七天内已迁移，GoToSocial 将拒绝进行迁移，直到上一次迁移过去七天位置。 + +## 将你的 GoToSocial 账号迁移到其他账号（从 GoToSocial 迁移） + +使用迁移账号设置，你可以将你的 GoToSocial 账号迁移到给定的目标账号 URI。 + +为使迁移成功： + +1. 目标账号（你要迁移到的账号）必须反向别名到你当前的账号（你要从中迁移的账号）。 +2. 目标账号必须可从你当前账号访问，即不被你屏蔽，不屏蔽你，未被封禁，不在你当前实例的屏蔽列表中。 + +迁移你的账号将从你当前账号向粉丝发送一条消息，指示他们关注目标账号。根据你的粉丝使用的服务器软件，他们可能会自动向目标账号发送关注请求，并取消关注你当前账号。 + +目前，**只有你的粉丝会转移到新账号**。其他如关注列表、贴文、媒体、书签、点赞、屏蔽等不会转移。 + +一旦你的账号迁移完成，你当前的（旧的）账号的网页视图将显示已迁移的信息，以及迁移的目标账号。 + +除非手动删除，否则旧账号的贴文和媒体仍可在这个已迁移的账号的网页视图中看到。如果你愿意，可以请求你迁出的实例管理员在迁移完成后封禁/删除你的账号。 + +如有必要，你可以使用相同的目标账号 URI 重试账号迁移。这将再次发送迁移消息。这在你的粉丝由于网络问题或其他临时故障未收到迁移消息的情况下很有用。 + +!!! danger "账号迁移是不可逆的永久操作！" + + 从 GoToSocial 触发账号迁移的那一刻起，你将仅对已迁移的账号拥有基本读取和删除权限。 + + 你仍然可以登录旧账号，查看自己的贴文、点赞、收藏、屏蔽和列表。 + + 你也可以编辑个人资料，删除和/或取消置顶自己的贴文，以及取消转发、取消点赞和取消收藏。 + + 但是，你将无法执行任何涉及创建内容的操作，如创建贴文、转发、添加收藏或点赞、关注他人、上传媒体、创建列表等。 + + 此外，你将无法查看任何时间线（主页标签、公共列表），或使用搜索功能。 + +## 将账号迁移到你的 GoToSocial 账号（迁移到 GoToSocial） + +要成功从其他账号向你的 GoToSocial 账号触发迁移，你必须首先创建一个**别名**，将你的 GoToSocial 账号链接回你要发起迁移的账号，以表明你也拥有要迁移到的 GoToSocial 账号。 + +为此，你必须首先使用你的 GoToSocial 账号登录 GoToSocial 设置面板。例如，如果你的 GoToSocial 实例位于 `https://example.org`，你应登录设置面板 `https://example.org/settings`。 + +然后，进入“迁移”部分，查看“别名账号”子部分： + +![展示已填写账号别名的别名账号子部分。](../../../assets/migration-aliasing.png) + +在第一个还未填写账号别名框中，输入你希望**发起迁移**的账号的 URL。这表示你要发起迁移的账号属于你，即你“也被称为”该账号。 + +例如，如果你要从实例 `ondergrond.org` 上的账号 `@dumpsterqueer` 迁移，应输入 `https://ondergrond.org/@dumpsterqueer` 或 `https://ondergrond.org/users/dumpsterqueer` 作为账号别名，如上图所示。 + +输入别名后，点击“保存账号别名”按钮。如果一切顺利，按钮上会显示一个勾。如果不行，会显示一个错误帮助你判断出错的原因。 + +一旦你从 GoToSocial 账号创建了指向要发起迁移的账号的别名，你可以在另一账号所在实例的设置面板发起到你的 GoToSocial 账号的迁移。 + +在 Mastodon 上，“账号迁移”设置部分看起来如下： + +![Mastodon “账号迁移”设置页面。](../../../assets/migration-mastodon.png) + +如果你正在从 Mastodon 账号迁移到 GoToSocial 账号，你会在“新账号代号”字段中填写 GoToSocial 账号的 `@[username]@[domain]` 值。例如，如果你的 GoToSocial 账号用户名是 `@someone`，并且在实例 `example.org` 上，那么在此处输入 `@someone@example.org`。 + +一旦触发从其他账号到 GoToSocial 账号的迁移，你唯一需要做的就是在新（GoToSocial）账号上接受来自旧账号粉丝的关注请求。 + +!!! tip + 为了省去麻烦，可以考虑在触发迁移前将 GoToSocial 账号设置为不需要批准新的关注请求。迁移完成后再开启关注请求审核。否则，你将需要手动批准每个从旧账号迁移的粉丝。 + +!!! tip + 迁移账号后，可能需要将之前账号的关注列表导入 GoToSocial 账号。[在此查看](./settings.md#import)如何通过设置面板完成此操作的详细信息。 diff --git a/docs/locales/zh/user_guide/password_management.md b/docs/locales/zh/user_guide/password_management.md new file mode 100644 index 000000000..0f72e1bfe --- /dev/null +++ b/docs/locales/zh/user_guide/password_management.md @@ -0,0 +1,19 @@ +# 密码管理 + +## 更改你的密码 + +你可以使用[用户设置面板](./settings.md)来更改密码。只需登录用户设置面板，滑动到页面底部，输入你的旧密码和想要的新密码即可。 + +如果你提供的新密码不够长或不够复杂，设置面板会报错并提示你尝试其他密码。 + +如果你的实例使用 OIDC（即通过 Google 或其他外部提供商登录），你需要通过 OIDC 提供商，而不是通过用户设置面板更改密码。 + +## 密码存储 + +GoToSocial 使用安全的 [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) 函数，通过 [Go 标准库](https://pkg.go.dev/golang.org/x/crypto/bcrypt)在数据库中存储用户密码的哈希值。 + +这意味着，即使你的 GoToSocial 实例数据库遭到破坏，你的密码明文也是安全的。这也意味着你的实例管理员无法访问你的密码。 + +为了在接受前检查密码是否足够安全，GoToSocial 使用[这个库](https://github.com/wagslane/go-password-validator)，其熵值设置为 60。这意味着像 `password` 这样的密码会被拒绝，但像 `verylongandsecurepasswordhahaha` 这样的密码会被接受，即使没有特殊字符/大写和小写字母等。 + +我们建议遵循 EFF 关于[创建强密码](https://ssd.eff.org/en/module/creating-strong-passwords)的指南。 diff --git a/docs/locales/zh/user_guide/posts.md b/docs/locales/zh/user_guide/posts.md new file mode 100644 index 000000000..8c41dcd77 --- /dev/null +++ b/docs/locales/zh/user_guide/posts.md @@ -0,0 +1,300 @@ +# 贴文 + +## 隐私设置 + +GoToSocial 为贴文提供 Mastodon 风格的隐私设置。从最私密到最不私密的顺序是： + +* 私信 +* 互关可见 +* 私密/仅粉丝可见 +* 不列出 +* 公开 + +无论为贴文选择哪种隐私设置，GoToSocial 都会尽力确保你的贴文不会出现在你已屏蔽的实例或你直接屏蔽的用户面前。 + +与一些其他联邦宇宙服务端实现不同，GoToSocial 对新账户使用 `不列出` 作为默认的贴文设置，而不是使用 `公开`。我们的理念是，将某条贴文公开始终应该是一个明确作出的决定，而不是默认选择。 + +请注意，尽管 GoToSocial 非常严格地遵循这些隐私设置，但其他服务端实现不一定可靠：联合网络中存在不良行为者。与任何社交媒体一样，你应该仔细考虑你发布的内容及其受众。 + +### 私信 + +`私信` 可见性的贴文只会显示给贴文作者和贴文中提到的用户。以下是一个示例： + +```text +嘿 @whoever@example.org，这是一条私信！只有咱们能看到！ +``` + +如果这条消息是由 `@someone@server.com` 写的，那么只有 `@whoever@example.org` 和 `@someone@server.com` 能看到。 + +顾名思义，`私信` 贴文用于你希望与一个或多个特定人交流的情况。 + +然而，`私信` 贴文并不是替代端到端加密消息（如 [Signal](https://signal.org/) 和 [Matrix](https://matrix.org/)）的合适选择。如果你要直接交流，但不是传递敏感信息，那么 `私信` 贴文是可以胜任的。如果你需要进行敏感且安全的交流，请使用其他工具！ + +私信贴文可以被点赞，但不能被转发。 + +私信贴文在你的 GoToSocial 实例上无法通过网页 URL 访问。 + +### 互关可见 + +`互关可见` 的贴文只会显示给贴文作者和与作者*互相关注*的人。换句话说，只有在满足两个条件时，其他人才能看到： + +1. 其他账户关注贴文作者。 +2. 贴文作者也关注其他账户。 + +这在你希望只有朋友能看到某些内容时很有用。 + +互关可见贴文可以被点赞，但不能被转发。 + +互关可见贴文在你的 GoToSocial 实例上无法通过网页 URL 访问。 + +### 私密/仅粉丝可见 + +`仅粉丝` 贴文只对贴文作者和关注贴文作者的人可见。与 `互关可见` 类似，但只需满足第一个条件；贴文作者不需要回关其他账户。 + +这在你想向粉丝发布公告，或分享一些比 `互关可见` 稍微不那么私密的内容时很有用。 + +私密/仅粉丝可见贴文可以被点赞，但不能被转发。 + +私密/仅粉丝可见贴文在你的 GoToSocial 实例上无法通过网页 URL 访问。 + +### 不列出 + +`不列出`（有时称为 `未锁定/悄悄公开`）的贴文是半公开的。它们会被发送给关注你的人，并可以转发到未关注你的人的时间线中，但不会出现在跨站或本站时间线上，也不会出现在你的公开资料页中。 + +不列出贴文适用于你希望某个贴文传播，但不想被所有人立即看到的情况。也可以用于发布相对公开的贴文，同时不让跨站/本站时间线被占用。 + +不列出贴文可以被点赞，也可以被转发。 + +与 Mastodon 不同，不列出贴文在你的 GoToSocial 实例上无法通过网页 URL 访问！ + +### 公开 + +`公开` 可见性的贴文是*完全*公开的。它们可以通过网络看到，出现在本地和联合时间线上，并且完全可以被转发。`公开` 是将贴文广泛传播和易于分发的终极设置，适用于你希望某些内容可被广泛访问的情况。 + +公开贴文可以被点赞，也可以被转发。 + +**公开贴文可以在你的 GoToSocial 实例上通过网页 URL 访问！** + +## 输入类型 + +GoToSocial 当前接受两种不同类型的贴文（以及用户简介）输入。你可以在[用户设置页面](./settings.md)在这两种类型之间进行选择。它们分别是： + +* `plain` +* `Markdown` + +纯文本(`plain`)是默认的发帖方式：GtS 接受一些简单的文本，通过解析链接和提及等将其转化为优雅的 HTML。如果你习惯于使用 Mastodon 或 Twitter 或大多数其他社交媒体平台，这种发帖方式会让你一见如故。 + +Markdown 是一种更复杂的组织文本的方式，在如何解析和格式化文本方面给你更多的控制权。 + +GoToSocial 支持[基本 Markdown 语法](https://www.markdownguide.org/basic-syntax)，以及部分[扩展 Markdown 语法](https://www.markdownguide.org/extended-syntax/)，包括独立代码块、脚注、删除线、下标、上标和自动 URL 链接。 + +你还可以在你的 markdown 中包含基本 HTML 片段！ + +关于 Markdown 的更多信息，请参阅[Markdown 指南](https://www.markdownguide.org/)。 + +关于 Markdown 语法的速查表，请参阅[Markdown 速查表](https://www.markdownguide.org/cheat-sheet)。 + +## 媒体附件 + +GoToSocial 允许你在贴文中附加媒体文件，大多数客户端会在贴文底部以画廊视图呈现这些文件。默认情况下，你可以向贴文附加 6 个媒体文件，但这可能会根据你使用的客户端和实例配置而有所不同。 + +目前支持以下文件类型： + +- image/jpeg +- image/gif +- image/png +- image/webp +- video/mp4（大多数类型） + +默认情况下，上传媒体的大小限制为 40MB，但这可能会因实例配置而有所不同。 + +### 图片描述（alt 文本） + +当你在贴文中附加图片或视频等媒体时，大多数客户端会提供选项，让你为图片或视频的内容撰写描述。这个描述将作为所有用户查看媒体时的 alt 文本出现。这对所有人，尤其是对盲人或视力部分受损的人来说有用。如果没有图片描述，对方可能难以理解媒体中包含的内容以及为何你将其附加到特定贴文中。 + +撰写好的图片描述可能很难，但这样做非常值得！ + +> 图片描述是一种表示关心的行为，也是无障碍的基本组成部分。没有它们，内容对盲人/视力低下的人来说将完全不可用。通过撰写图片描述，我们展现了对跨残疾团结及运动团结的支持。 + +-- Alex Chen，[如何撰写图片描述](https://uxdesign.cc/how-to-write-an-image-description-2f30d3bf5546)。 + +### Exif 数据 + +当照片或视频拍摄时，大多数传统相机和手机相机会将 [Exif 数据标签](https://en.wikipedia.org/wiki/Exif) 编码为结果媒体的元数据。此 Exif 数据包含如下内容： + +- 相机的品牌和型号。 +- 图片或视频的颜色和像素信息。 +- 图片或视频的尺寸和方向。 +- 日期和时间信息。 +- 位置信息（如果启用）。 + +一般来说，这些 Exif 数据点用于摄影师帮助整理他们自己的图片。然而，遗憾的是，它们也带来了[隐私和安全影响](https://en.wikipedia.org/wiki/Exif#Privacy_and_security)，特别是在涉及位置信息时。如果你曾在网上平台（如 Facebook）发布图片，你可能会想知道 Facebook 是如何知道图片的拍摄地点和时间的；这很大程度上归因于 Exif 数据中嵌入的位置信息和时间戳，Facebook 从中读取图片信息，以组装一条“你曾去过的地方”的时间线。 + +为了避免泄漏你的位置信息，GoToSocial 努力在上传媒体时通过清零 Exif 数据点移除 Exif 信息。 + +!!! danger + 为了方便和保护隐私，GoToSocial 在上传图片文件时会自动移除 Exif 标签。然而，**无法自动移除 mp4 视频的 Exif 数据**（参见 [#2577](https://github.com/superseriousbusiness/gotosocial/issues/2577)）。 + + 在你将视频上传至 GoToSocial 之前，建议确保该视频的 Exif 数据标签已经被移除。你可以在线找到多种工具和服务来做到这一点。 + + 为防止 Exif 位置信息在一开始被写入图片或视频中，你还可以关闭设备摄像头应用中的位置标记（通常称为地理标记）。 + +!!! tip + 即使你在上传图片或视频之前已完全移除所有 Exif 元数据，恶意用户仍然可以通过媒体本身的内容推断出你的位置信息。 + + 如果你属于在生产中有保密需要的组织，或正在被跟踪或监视，你可能需要考虑不要发布任何可能含有你位置线索的媒体。 + +## 格式化 + +当贴文以 `plain`(纯文本) 格式提交时，GoToSocial 会自动进行一些整理和格式化，将其转换为 HTML，如下所述。 + +### 空格 + +任何开头或结尾的空格和换行都会从贴文中去除。因此，例如： + +```text + + +这个贴文以换行开头 +``` + +将变为： + +```text +这个贴文以换行开头 +``` + +### 包裹 + +整个贴文将被 `

` 包裹。 + +因此以下文本： + +```text +你好，这是一条很短的贴文！ +``` + +将变为： + +```html +

你好，这是一条很短的贴文！

+``` + +### 换行 + +任何换行符都将被替换为 `
` + +继续上述示例： + +```text +你好，这是一条很短的贴文！ + +这是另一行。 +``` + +将变为： + +```html +

你好，这是一条很短的贴文！

这是另一行。

+``` + +### 链接 + +任何可识别的链接将在文本中被缩短并转换为适当的超链接，还会添加一些其他属性。 + +例如： + +```text +这里是某个链接：https://example.org/some/link/address +``` + +将变为： + +```html +这里是某个链接：example.org/some/link/address +``` + +呈现为： + +> 这里是某个链接：[example.org/some/link/address](https://example.org/some/link/address) + +注意这仅对 `http` 和 `https` 链接有效；其他协议不支持。 + +### 提及 + +你可以通过以下方式提及其他账户： + +> @some_account@example.org + +在这个例子中，`some_account` 是你要提及的账户的用户名，`example.org` 是托管他们账户的域名。 + +被提及的账户将收到你提到他们的通知，并能够看到提及他们的贴文。 + +提及的格式类似于链接，所以： + +```text +嗨 @some_account@example.org 最近怎么样？ +``` + +将变为： + +```html +嗨 @some_account 最近怎么样？ +``` + +呈现为： + +> 嗨 @some_account 最近怎么样？ + +当提及本站账户（即你的实例上的账户）时，提及第二部分是不必要的。如果在你的实例上有一个名为 `local_account_person` 的账户，你可以通过写： + +```text +嘿 @local_account_person 你是我的网上邻居 +``` + +变为： + +```html +嘿 @local_account_person 你是我的网上邻居 +``` + +呈现为： + +> 嘿 @local_account_person 你是我的网上邻居 + +### 话题标签 + +你可以在贴文中使用一个或多个话题标签来指示贴文主题，并允许贴文与其他使用相同话题标签的贴文被归入同一分组，以帮助你的贴文被他人发现。 + +大多数 ActivityPub 服务端实现，如 Mastodon 等，只会通过它们使用的话题标签对**公开**贴文进行分组，但这并不是绝对的。一般来说，最好只对那些你希望能比其他情况下更广泛传播的公开可见贴文使用话题标签。这方面的一个好例子是 `#introduction` 话题标签，通常用于新账户想要向联邦宇宙介绍自己时使用！ + +在贴文中包含话题标签的方式类似于大多数其他社交媒体软件：只需在你想用作话题标签的词前加上 `#` 符号。 + +一些示例： + +* `#introduction` +* `#Mosstodon` +* `#LichenSubscribe` + +在 GoToSocial 中，话题标签不区分大小写，因此无论你在书写话题标签时使用大写、小写或两者混合，都会被视为相同的话题标签。例如，`#Introduction` 和 `#introduction` 会被视为完全相同。 + +出于可访问性原因，在书写话题标签时，考虑使用大驼峰式（即每个单词的首字母大写）是更好的。换句话说：要把 `#thisisahashtag` 替换为 `#ThisIsAHashtag`。这样不仅视觉上更易读，屏幕阅读器也更容易朗读。 + +你可以在 GoToSocial 贴文中包含任意数量的话题标签，而且每个话题标签的长度限制为 100 个字符。 + +## 输入净化 + +为了不传播脚本、漏洞以及不稳定的 HTML，GoToSocial 执行以下类型的输入净化： + +`plain` 输入类型： + +* 在解析前，会完全移除贴文正文和内容警告字段中的已有 HTML。 +* 在解析后，所有生成的 HTML 都会通过清理器处理以移除有害元素。 + +`Markdown` 输入类型： + +* 在解析前，会完全移除内容警告字段中的已有 HTML。 +* 在解析前，贴文正文中的现有 HTML 会通过清理器处理以移除有害元素。 +* 在解析后，所有生成的 HTML 都会通过清理器处理以移除有害元素。 + +GoToSocial 使用 [bluemonday](https://github.com/microcosm-cc/bluemonday) 进行 HTML 清理。 diff --git a/docs/locales/zh/user_guide/rss.md b/docs/locales/zh/user_guide/rss.md new file mode 100644 index 000000000..6bfe46343 --- /dev/null +++ b/docs/locales/zh/user_guide/rss.md @@ -0,0 +1,15 @@ +# RSS + +RSS 是[简易信息聚合](https://en.wikipedia.org/wiki/RSS)的缩写。这是一种在网络上共享内容的非常成熟的标准。你可能在你喜欢的新闻网站和博客上看到过这个活泼的橙色 RSS 标志： + +![橙色 RSS 图标](../../../assets/rss.svg) + +如果你愿意，可以配置你的 GoToSocial 账户，以将你的贴文以 RSS 订阅源的形式发布到网上。这让没有 Fediverse 账户的人也能定期获取你的贴文更新。这非常适合使用 GoToSocial 发布长篇博客形式的贴文，并希望任何人都能轻松阅读它们的情况。 + +GoToSocial 账户的 RSS 源默认是关闭的。你可以通过[用户设置](./settings.md)在 `https://[你的实例域名]/settings` 启用它。 + +启用后，你的账户的 RSS 订阅将可在 `https://[你的实例域名]/@[你的用户名]/feed.rss` 获取。如果你使用 RSS 阅读器，可以用其打开这个地址以检查 RSS 是否正常工作。 + +## 哪些贴文会通过 RSS 分享？ + +只有你最近的 20 篇公开贴文会通过 RSS 分享。回复和转发不包括在内。不列出的贴文也不包括在内。换句话说，通过 RSS 可见的贴文将仅是通过浏览器打开你的账户页时可见的贴文。 diff --git a/docs/locales/zh/user_guide/search.md b/docs/locales/zh/user_guide/search.md new file mode 100644 index 000000000..b9d4d2bc5 --- /dev/null +++ b/docs/locales/zh/user_guide/search.md @@ -0,0 +1,20 @@ +# 搜索 + +## 查询格式 + +GoToSocial 接受多种搜索查询格式： + +- `@用户名`：在所有已知实例中搜索给定用户名的账户。可能返回多个结果。 +- `@用户名@域`：搜索具有特定用户名和域名的外站账户。最多只会返回1个结果。 +- `https://example.org/some/arbitrary/url`：搜索具有给定 URL 的账户或贴文。如果账户或贴文尚未联合到 GoToSocial，将尝试获取它。最多只会返回1个结果。 +- `#标签名`：搜索具有给定标签名或以其开头的话题标签。大小写不敏感。可能返回多个结果。 +- `任意文本`：搜索包含该文本的贴文、包含该文本的话题标签，以及用户名、显示名或简介中含有该文本的账户。将搜索由你撰写的贴文以及回复你的贴文。仅在你关注的账户中搜索账户简介。可能返回多个结果。 + +## 搜索运算符 + +搜索关键词可以包含以下搜索运算符： + +- `from:用户名`：将结果限制为由指定**本站**账户创建的贴文。 +- `from:用户名@域`：将结果限制为由指定外站账户创建的贴文。 + +例如，你可以搜索 `sloth from:你的用户名` 来查找你关于树懒的贴文。 diff --git a/docs/locales/zh/user_guide/settings.md b/docs/locales/zh/user_guide/settings.md new file mode 100644 index 000000000..9679c6cab --- /dev/null +++ b/docs/locales/zh/user_guide/settings.md @@ -0,0 +1,268 @@ +# 设置 + +GoToSocial 提供了一个设置界面，你可以在这里更新你的贴文和账户设置，添加头像和横幅背景图，为你的账户撰写简介等。 + +你可以通过访问自己 GoToSocial 实例的 `https://my-instance.example.com/settings` 来访问设置。设置面板同样使用 OAuth 机制进行身份验证。 + +在提供实例 URL 后，你会看到提示，要求你使用电子邮件地址和密码登录。 + +## 账户 + +![用户设置界面的账户部分截图，显示头像、横幅背景图和昵称的预览，并提供更改它们的表单字段](../../../assets/user-settings-profile-info.png) + +在账户部分，你可以更改昵称、头像和横幅背景图。你还可以选择启用手动批准关注请求，并选择提供公开的贴文 RSS 源。 + +### 设置头像/横幅背景图 + +要设置头像或横幅背景图，请在相应部分点击 `浏览` 按钮，并使用文件浏览器选择图像。 + +当前支持的图像格式有 `gif`、`png`、`webp` 和 `jpeg`/`jpg`。 + +页面底部会显示图像在你的账户中的预览。如果你对选择满意，点击页面底部的 `保存账户信息` 按钮。 + +如果你转到自己的账户页并刷新页面，页面将会显示新的头像/横幅背景图。这个更新可能需要一些时间才能传播到其他外站实例。 + +### 选择主题 + +GoToSocial 提供主题供你选择，以更改账户的外观和氛围。 + +要选择主题，只需在账户设置页面中选择，然后点击页面底部的 `保存账户信息`。用浏览器查看账户页（可能需要刷新页面），你会看到新主题已被应用，访问你账户的其他人也会看到。 + +!!! tip "添加更多主题" + 实例管理员可以通过将 CSS 文件放入 `web/assets/themes` 文件夹中来添加更多主题。有关详细信息，请参阅管理员文档中的[主题](../admin/themes.md)部分。 + +### 基本信息 + +#### 昵称 + +昵称是与你的用户名一起显示在账户上的简短标识。 + +尽管创建后无法更改用户名，但昵称可以更改。 + +昵称可以包含空格、大写字母、表情符号等。 + +这是放网名或全名的好地方。例如，如果你的用户名是 `@miranda`，昵称可以是 `Miranda Priestly`。 + +#### 简介 + +你的简介是介绍你的账户和自己的较长文本。适合用于： + +- 提示你贴文的内容。 +- 提及大致年龄/位置。 +- 链接到你的其他账户或账户。 +- 说明与他人互动时的边界和偏好。 +- 链接你经常使用的标签。 + +简介支持 `纯文本` 或 `markdown` 格式。默认贴文格式设置如[贴文设置](#贴文设置)中所述。 + +#### 资料字段 + +资料字段是一系列名称/值对，将显示在账户上，并传播到其他外站实例。 + +此处适合放置的信息包括： + +- 你的网站链接 +- 众筹/捐助页面的链接 +- 你的年龄 +- 人称代词 + +一些示例： + +- 别名：汉德尔·沃尔特 +- 我的网站：https://example.org +- 年龄：99 +- 代词：she/her/她 +- 我的其他账户：@someone@somewhere.com + +### 可见性和隐私 + +#### 个人资料上显示的贴文可见性级别 + +使用此下拉菜单，你可以选择在你的网页版账户页、贴文以及 RSS 源（如果你已启用 RSS）上显示的贴文可见性级别。 + +**默认情况下，GoToSocial 仅在网页版账户页上显示公开可见的贴文，而不显示不列出的贴文。** 你可以调整此设置，以显示不列出的贴文，这类似于其他 ActivityPub 软件如 Mastodon 的默认设置。 + +你还可以选择在 GoToSocial 的网页视图上完全不显示任何贴文。这样，你可以安心发表贴文，而无需担心有人通过网页浏览你的个人资料并查看你的贴文。 + +此设置仅适用于你自己的贴文的可见性。其他用户的“不列出”贴文永远不会显示。 + +此设置不会影响你的贴文在 ActivityPub 协议和客户端中的可见性，因此即便你选择不在网页版账户页显示任何贴文，只要他人是你的粉丝、你的贴文被转发到他们的时间线，或使用链接搜索你的某个贴文，他们仍然可以看到的贴文。 + +!!! warning + 请注意，此设置的更改也会应用于之前的贴文。 + + 也就是说，如果你之前发布了一条“不列出”可见性的贴文，而当时你的网页版账户页被设置为仅显示公开贴文，此时如果你更改此设置为一并显示公开和不列出，那你之前发布的“不列出”贴文将会与公开贴文一起显示在你的网页版账户页上。 + + 同样地，如果你选择不显示任何贴文，那么所有贴文将从你的网页版账户页中隐藏，无论它们是在何时创建，也无论当时此选项被设置为什么。这种情况将持续直到你再次更改此设置。 + +!!! tip + 结合（域名）屏蔽，如果有人通过公开贴文骚扰你，这是一种很好的“紧急”设置。虽然它不会阻止在 ActivityPub 客户端中可以看到你的贴文的人，但至少会防止他们无需身份验证就通过浏览器点击查看你的贴文，并通过 URL 轻松与他人分享。 + +#### 手动批准关注请求（即锁定帐户） + +此复选框允许你决定是否希望手动审核账户的关注请求。 + +当此选项**未勾选**时，新关注请求会被自动批准，无需你的干预。对于更面向公众的账户或不怎么发布敏感信息的情况而言，这很有用。 + +当其**已勾选**时，你必须手动批准新关注请求，并可以拒绝你不想被关注的账号的关注请求。这对仅向粉丝发布私人内容的私人账户很有用。 + +在联邦宇宙中，一般将此选项称为“锁定”账户。 + +勾选或取消勾选复选框后，务必点击底部的 `保存账户信息` 按钮以保存新设置。 + +#### 将账户标记为可被搜索引擎和目录发现 + +此设置用于更新账户上的“可发现”标记。 + +选中账户的可发现性框可执行以下操作： + +- 更新账户的 robots 元信息标记，允许其被搜索引擎索引并出现在搜索引擎结果中。 +- 向外站指示账户可包含在公共目录和索引中。 + +将可发现性标记打开可能需要一周或更长时间才会生效，账户不会立即出现在搜索引擎结果中。 + +!!! tip + 为了避免暴露给爬虫，新帐户的可发现性默认为 false。但对于希望被抓取的面向公众的帐户，将其设置为 true 是有用的。 + +!!! info + 可发现性设置是关于**账户的可发现性**，而不是贴文的可被搜索性。这与 Mastodon 实例或其他使用全文搜索的实例的贴文索引无关！ + +#### 启用公开贴文的 RSS 源 + +用户的 RSS 源默认情况下是禁用的，但可以通过此复选框选择。有关更多信息，请参阅 [RSS](./rss.md)。 + +此源仅包括设置为“公开”的贴文（参见 [隐私设置](./posts.md#隐私设置)）。 + +!!! warning + 公开您的 RSS 源允许*任何人*匿名订阅您公开贴文的更新，绕过关注和关注请求。 + +#### 隐藏你关注/被关注的人 + +默认情况下，GoToSocial 会在你的公开网络资料上显示你的关注/粉丝数量，并允许其他人查看你关注的和关注你的人。这对于账户发现可能很有用。然而，出于隐私和安全原因，你可能希望隐藏这些信息，并隐藏其他账户的关注/粉丝清单。你可以通过勾选此框来做到这一点。 + +勾选此框后，你的关注/粉丝数量将从你的公开网络资料中隐藏，其他人将无法浏览你的关注/粉丝清单。 + +### 高级 + +#### 自定义 CSS + +如果实例管理员允许，自定义 CSS 可以让你进一步自定义账户在浏览器中的外观。 + +如果此设置未被实例管理员启用，文本输入框将为只读状态，自定义 CSS 将不会应用。 + +请参阅 [自定义 CSS](./custom_css.md) 页面，了解有关为账户编写自定义 CSS 的一些提示。 + +!!! tip + 你在此框中添加的任何自定义 CSS 都将在*选择主题之后*应用，因此你可以选择一个喜欢的预设主题，然后进行自己的调整！ + +## 贴文 + +### 贴文设置 + +默认贴文语言设置允许你向其他用户声明你的贴文通常使用哪种语言。这对说其它语言（例如韩语）并希望过滤掉其他语言的贴文的用户很有帮助。 + +默认贴文可见性设置允许你设置新贴文的默认可见性。当你通常发布公开或只对粉丝可见的贴文，但不想每次发贴时都设置隐私时会很有用。请记住，这只是默认设置：无论你在此处设置什么，仍然可以根据需要单独设置新贴文的隐私。有关贴文隐私设置的更多信息，请参阅[贴文页面](./posts.md)。 + +默认贴文格式设置允许你选择在解析贴文时使用哪个文本解释器。 + +plain（默认）设置提供标准贴文格式，类似于许多其他联邦宇宙服务端使用的格式。这非常适合一般目的的发布：你可以写简短的推特风格的贴文，或多段文章，插入链接，并使用用户名提及其他账户。 + +markdown 设置表示你的贴文应被按 Markdown 格式解析，这是一种标记语言，提供更多选项来自定义贴文的布局和外观。有关 plain 和 markdown 贴文格式之间差异的更多信息，请参阅 [贴文页面](posts.md)。 + +更新贴文设置后，请记得点击该部分底部的 `保存设置` 按钮以保存更改。 + +### 默认互动规则 + +通过此部分，你可以为新贴文设置每个可见级别的默认互动规则。这允许你精确控制他人如何与你的贴文互动。 + +这使你能够做以下事情： + +- 创建只有你自己可以互动的贴文。 +- 创建仅粉丝/你关注的人可以互动的贴文。 +- 创建任何人都可以点赞或转发，但只有特定人可以回复的贴文。 +- 等等。 + +例如，下图显示了一个公开可见性贴文的默认互动规则，允许任何人点赞或转发，但仅允许粉丝和你关注的人回复。 + +![互动规则，图中显示“谁可以点赞” = “任何人”，“谁可以回复” = “粉丝”和“关注的人”，“谁可以转发” = “任何人”。](../../../assets/user-settings-interaction-policy-1.png) + +请记住，互动规则不具备前向可追溯性。应用默认互动规则之后创建的贴文将默认使用新设置的规则，但在此之前创建的任何贴文将使用创建时的默认规则。 + +无论在贴文上设置了什么规则，首先被考虑的仍是可见性设置和账户屏蔽情况。例如，如果你将某种类型的互动范围设置为“任何人”，这仍然会排除你屏蔽的账户，或你实例屏蔽的域名域下的账户。“任何人”在这种情况下基本上意味着“任何通常能看到贴文的人”。 + +最后，请注意，无论为贴文设置了什么规则，贴文中提到的任何账户将**始终**能够回复该贴文。 + +更新互动规则设置后，请记得点击该部分底部的 `保存规则` 按钮以保存更改。 + +如果你想将所有规则重置为初始默认值，可以点击 `重置为默认值` 按钮。 + +!!! danger + 虽然 GoToSocial 尊重互动规则，但不能保证其他服务端软件也会这样做，即使你的实例禁止某些互动，其他服务器上的账户可能仍会向其粉丝发送（被禁止的）贴文回复和转发。 + + 随着更多 ActivityPub 服务端推出互动规则支持，这个问题有望减少，但在此期间，GoToSocial 只能在“尽力而为”范围内进行尝试，以根据你设定的规则限制与贴文的互动。 + +## 电子邮箱和密码 + +### 更改电子邮箱 + +你可以使用面板的更改电子邮箱部分更改账户的电子邮箱地址。出于安全原因，你必须提供当前密码以验证更改。 + +输入新电子邮箱地址，并点击“更改电子邮箱地址”后，必须打开新电子邮件地址的收件箱，并通过提供的链接确认地址。完成后，你的电子邮箱地址更改将被确认。 + +!!! info + 如果你的实例使用 OIDC 作为授权/身份提供商，你可以通过设置面板更改电子邮箱地址，但只会影响 GoToSocial 用于联系你的电子邮箱地址，而不会更改用于登录账户的电子邮箱地址。要更改此项，应联系你的 OIDC 提供商。 + +### 更改密码 + +你可以使用面板的更改密码部分为账户设置新密码。出于安全原因，你必须提供当前密码以验证更改。 + +!!! info + 如果你的实例使用 OIDC 作为授权/身份提供商，你将无法通过 GoToSocial 设置面板更改密码，此时应联系你的 OIDC 提供商。 + +有关 GoToSocial 如何管理密码的更多信息，请参阅[密码管理文档](./password_management.md)。 + +## 迁移 + +在迁移部分，你可以管理与与账户别名、迁移到其他账户或从其他账户迁移相关的设置。 + +有关移动账户的更多信息，请参阅[迁移文档](./migration.md)。 + +## 导出和导入 + +在导出和导入部分，你可以从 GoToSocial 账户导出数据或将数据导入账户。 + +![导出/导入页面。](../../../assets/user-settings-export-import.png) + +### 导出 + +要导出你的关注、粉丝、账户列表、账户屏蔽列表或账户静音列表，你可以使用此页面上的按钮。 + +所有导出都将以 Mastodon 导出格式兼容的 CSV 格式提供，因此如果有需要，可以将其导入 Mastodon 或另一个 GoToSocial 实例。 + +### 导入 + +你可以使用导入部分，将其他账户的数据导入到 GoToSocial 账户中，使用从其他账户导出的 CSV 文件。 + +这在你已将账户[迁移](./migration.md)到 GoToSocial 账户，并希望保留在以前的账户上的关注列表和屏蔽列表时很有用。 + +要将数据导入账户，首先点击“浏览”并选择从 Mastodon 或其他兼容实例导出的与 Mastodon 导出格式兼容的 CSV 文件。 + +然后，使用下拉菜单选择通过 CSV 文件上传的数据类型。 + +!!! warning + 在选择“类型”时要小心，否则可能会意外封禁你计划关注的一堆账户，反之亦然！ + +然后，选择是要**合并**新数据到 GoToSocial 账户中该类型的现有数据，还是要用 CSV 文件中包含的数据**覆盖**现有数据。 + +如果选择**合并**，则 CSV 文件中包含的任何数据都将添加到现有数据中，而不会删除任何现有数据。 + +例如，如果你的 GoToSocial 账户关注 `account1` 和 `account2`，并且正在上传一个包含 `account3` 和 `account4` 的关注 CSV 文件，并使用模式 **合并**，那么在导入结束时，你将关注 `account1`、`account2`、`account3` 和 `account4`。 + +如果选择**覆盖**，则 CSV 文件中包含的任何数据将*替换*现有数据，删除 CSV 文件中未包含的条目。 + +例如，如果你的 GoToSocial 账户关注 `account1` 和 `account2`，并上传一个包含 `account3` 和 `account4` 的关注 CSV 文件，并使用模式 **覆盖**，那么导入结束时，你将关注 `account3` 和 `account4`。你对 `account1` 和 `account2` 的关注将被移除。 + +合并和覆盖操作都是幂等的，这通常意味着现有数据和 CSV 文件中的重复条目不会产生问题，如果需要重试导入，可以多次导入相同的数据。 + +!!! info + 由于各种原因，通过导入不可能一定会重新创建上传的 CSV 文件中的每个条目。例如，假设你试图导入包含 `example_account` 的关注 CSV，但 `example_account` 的实例已下线，或者它们的实例封禁了你的实例，或你的实例封禁了它们的实例等。在这种情况下，将无法创建对 `example_account` 的关注。