[docs] add zh docs (#3507)

* [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
2025-11-18 13:07:35 -06:00 · 2024-11-05 13:36:43 +00:00 · 2024-11-05 13:36:43 +00:00 · 38a08cd25a
commit 38a08cd25a
parent e953d80dff
139 changed files with 20407 additions and 24 deletions
--- a/docs/locales/zh/advanced/caching/api.md
+++ 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 可以提供最长一周的缓存响应。
--- a/docs/locales/zh/advanced/caching/assets-media.md
+++ 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
+	<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` 之前）绝不会更改，允许客户端在此期间忽略条件请求以重新验证资源。
--- a/docs/locales/zh/advanced/caching/index.md
+++ 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)