mirrors/gotosocial
1
0
Fork 0
mirror of https://github.com/superseriousbusiness/gotosocial.git synced 2025-11-02 04:32:24 -06: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

27
docs/locales/zh/advanced/builds/nowasm.md Normal file
View file

@ -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 有效，那很好，但我们不会为这样的构建提供支持，也无法帮助调试为何某些功能不起作用。

84
docs/locales/zh/advanced/caching/api.md Normal file
View file

@ -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 可以提供最长一周的缓存响应。

132
docs/locales/zh/advanced/caching/assets-media.md Normal file
View file

@ -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
<Directory /opt/GtS/web/assets>
Options None
AllowOverride None
Require all granted
ExpiresActive on
ExpiresDefault A300
Header set Cache-Control "public, max-age=300"
</Directory>
RewriteRule "^/assets/(.*)$" "/opt/GtS/web/assets/$1" [L]
<Directory /opt/GtS/storage>
Options None
AllowOverride None
Require all granted
ExpiresActive on
ExpiresDefault A604800
Header set Cache-Control "private, immutable, max-age=604800"
</Directory>
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
<Location "/">
ProxyPass http://127.0.0.1:8980/
ProxyPassReverse http://127.0.0.1:8980/
</Location>
```
… 默认情况下所有的请求都是通过代理的，`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` 之前）绝不会更改，允许客户端在此期间忽略条件请求以重新验证资源。

11
docs/locales/zh/advanced/caching/index.md Normal file
View file

@ -0,0 +1,11 @@
# 缓存
本节涵盖了多种缓存技术，这些技术可以提高 GoToSocial 在高流量情况下的稳定性，并减轻 GoToSocial 实例的一部分工作负担。
!!! note
这些指南仅在你运行[反向代理](../../getting_started/reverse_proxy/index.md)时才有意义。
## 指南
* [缓存 API 响应](api.md)
* [缓存资源与媒体](assets-media.md)

108
docs/locales/zh/advanced/certificates.md Normal file
View file

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

48
docs/locales/zh/advanced/healthchecks.md Normal file
View file

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

116
docs/locales/zh/advanced/host-account-domain.md Normal file
View file

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

19
docs/locales/zh/advanced/index.md Normal file
View file

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

57
docs/locales/zh/advanced/metrics.md Normal file
View file

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

21
docs/locales/zh/advanced/outgoing-proxy.md Normal file
View file

@ -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` 命令。

102
docs/locales/zh/advanced/replicating-sqlite.md Normal file
View file

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

174
docs/locales/zh/advanced/security/firewall.md Normal file
View file

@ -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=<HOST> .* 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 <interface name> priority -500;
ip saddr @baddiesv4 drop
ip6 saddr @baddiesv6 drop
}
}
```
### BSDs
使用 pf 时，你可以创建一个通常命名为 `<badhosts>` 的持久化表，将需要屏蔽的 IP 地址添加到该表中。表格还可以从其他文件读取，因此可以将 IP 列表保存在主 `pf.conf` 之外。
有关如何执行此操作的示例，可以在 [pf 手册][manpf] 中找到。
[manpf]: https://man.openbsd.org/pf.conf#TABLES

11
docs/locales/zh/advanced/security/index.md Normal file
View file

@ -0,0 +1,11 @@
# 安全加固措施
这些指南涵盖如何提高你的 GoToSocial 部署的安全状况。它们不涉及调整 GoToSocial 的设置，而是指出一些你可以做的额外措施，以更好地保护你的实例。
!!! note
这些指南中的任何内容旨在增强你的 GoToSocial 部署的安全性；它们不能替代良好的安全实践，比如保持你的系统定期得到修补和更新。
## 指南
* [对 GoToSocial 可执行文件进行沙盒处理](sandboxing.md)
* [配置防火墙](firewall.md)

63
docs/locales/zh/advanced/security/sandboxing.md Normal file
View file

@ -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 策略的支持请求。

35
docs/locales/zh/advanced/sqlite-networked-storage.md Normal file
View file

@ -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)以了解你可能设置的值。

44
docs/locales/zh/advanced/tracing.md Normal file
View file

@ -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 端点的追踪](../public/tracing.png)
[traceql]: https://grafana.com/docs/tempo/latest/traceql/