mirrors/gotosocial
1
0
Fork 0
mirror of https://github.com/superseriousbusiness/gotosocial.git synced 2025-10-29 06:52:25 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

[docs] add zh docs (#3507)

Browse source 
* [docs] add zh docs

* [docs] add lang dropdown

* [docs] update mkdocs zh config

* [docs] migrate assets

* [docs] update overrides dir in mkdocs zh config

* [docs] exclude locales director in main mkdocs config

* [docs] rename assets to public to avoid conflicting with template

* [docs] extra_css change followup

* [docs] add theme.palette.toggle.icon back into mkdocs zh config

* [docs] fix zh readme reference + migrate language-specific repo markdown to docs

* [docs] translate remaining repo docs + update reference

* [docs] update zh index.md reference

* [docs/zh] wording alignment
This commit is contained in:
CDN 2024-11-05 13:36:43 +00:00 • committed by GitHub
commit 38a08cd25a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
139 changed files with 20407 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

44
docs/locales/zh/configuration/accounts.md Normal file
View file

@ -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
```

152
docs/locales/zh/configuration/advanced.md Normal file
View file

@ -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: ""
```

192
docs/locales/zh/configuration/database.md Normal file
View file

@ -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"
```

121
docs/locales/zh/configuration/general.md Normal file
View file

@ -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"
```

67
docs/locales/zh/configuration/httpclient.md Normal file
View file

@ -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
```

138
docs/locales/zh/configuration/index.md Normal file
View file

@ -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
```

115
docs/locales/zh/configuration/instance.md Normal file
View file

@ -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
```

87
docs/locales/zh/configuration/media.md Normal file
View file

@ -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"
```

53
docs/locales/zh/configuration/observability.md Normal file
View file

@ -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: ""
```

156
docs/locales/zh/configuration/oidc.md Normal file
View file

@ -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。

78
docs/locales/zh/configuration/smtp.md Normal file
View file

@ -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` 中的示例进行操作。

38
docs/locales/zh/configuration/statuses.md Normal file
View file

@ -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
```

189
docs/locales/zh/configuration/storage.md Normal file
View file

@ -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. 在此用户上添加在线政策，将 `<bucketname>` 替换为你的桶名称
```json
{
"Statement": [
{
"Effect": "Allow",
"Action": "s3:ListAllMyBuckets",
"Resource": "arn:aws:s3:::*"
},
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": [
"arn:aws:s3:::<bucket_name>",
"arn:aws:s3:::<bucket_name>/*"
]
}
]
}
```
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` -> 你刚刚创建的 `<bucketname>`
### `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 <storage-local-base-path> s3://<bucket name>
```
#### s3cmd
使用 [s3cmd](https://github.com/s3tools/s3cmd)，可以使用以下命令：
```sh
s3cmd sync --add-header="Cache-Control:public, max-age=315576000, immutable" <storage-local-base-path> s3://<bucket name>
```
### 从本地到 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 <storage-local-base-path> scw/example-bucket/
```
如果你想迁移回来，请交换 `mc mirror` 命令的参数顺序。

40
docs/locales/zh/configuration/syslog.md Normal file
View file

@ -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"
```

64
docs/locales/zh/configuration/tls.md Normal file
View file

@ -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: ""
```

21
docs/locales/zh/configuration/web.md Normal file
View file

@ -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/"
```