mirrors/gotosocial
1
0
Fork 0
mirror of https://github.com/superseriousbusiness/gotosocial.git synced 2025-10-29 17:52:24 -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

185
docs/locales/zh/getting_started/index.md Normal file
View file

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

164
docs/locales/zh/getting_started/installation/container.md Normal file
View file

@ -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)。我们为几个流行的开源选项提供了指南，并乐意接受更多的拉取请求以增加新的指南。

14
docs/locales/zh/getting_started/installation/index.md Normal file
View file

@ -0,0 +1,14 @@
# 安装
正如我们在[版本发布](../releases.md)中提到的那样，我们发布了官方的二进制版本和容器版本。我们提供了一些指南，用于说明如何以这种方式部署你自己的 GoToSocial 实例。
在继续安装之前，请确保你已阅读[部署注意事项](../index.md)，并准备好了域名和服务器。
另外，花一点时间熟悉[如何配置](../../configuration/index.md)GoToSocial。
## 指南
对于第三方发布版本，我们不提供使用指南。需要参考他们自己的文档。我们的指南可能仍然有助于你熟悉需要设置和调整哪些配置选项。
* [裸机](metal.md)
* [容器](container.md)

164
docs/locales/zh/getting_started/installation/metal.md Normal file
View file

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

11
docs/locales/zh/getting_started/releases.md Normal file
View file

@ -0,0 +1,11 @@
# 发行版
GoToSocial 可以通过多种方式进行安装。我们发布官方的二进制文件以及容器镜像。
有许多第三方软件包由不同的发行版维护，一些用户还创建了额外的部署工具，以便你可以轻松地自行部署 GoToSocial。
{%
include "../repo/README.md"
start='<!--releases-start-->'
end='<!--releases-end-->'
%}

261
docs/locales/zh/getting_started/reverse_proxy/apache-httpd.md Normal file
View file

@ -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
<VirtualHost *:80 >
ServerName example.com
</VirtualHost>
<VirtualHost *:443>
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
</VirtualHost>
```
=== "旧版本"
```apache
MDomain example.com auto
MDCertificateAgreement accepted
<VirtualHost *:80 >
ServerName example.com
</VirtualHost>
<VirtualHost *:443>
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
</VirtualHost>
```
同样，将上述配置文件中的 `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
<VirtualHost *:80>
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/
</VirtualHost>
```
=== "旧版本"
```apache
<VirtualHost *:80>
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/
</VirtualHost>
```
同样，将上述配置文件中的 `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 和数据注入攻击。该头应保持不变，确保你的反向代理没有修改、覆盖或取消设置它。

110
docs/locales/zh/getting_started/reverse_proxy/caddy.md Normal file
View file

@ -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 下运行！

43
docs/locales/zh/getting_started/reverse_proxy/index.md Normal file
View file

@ -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) 文档，并相应地配置你的反向代理。

186
docs/locales/zh/getting_started/reverse_proxy/nginx.md Normal file
View file

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

43
docs/locales/zh/getting_started/reverse_proxy/websocket.md Normal file
View file

@ -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
```
无论你的设置如何，你都需要确保这些头在你的反向代理中被允许，这可能需要根据所使用的具体反向代理进行额外配置。

49
docs/locales/zh/getting_started/user_creation.md Normal file
View file

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