Agate

用于静态文件的简单Gemini服务器

Agate是一个基于Rust编程语言构建的Gemini网络协议服务器。Agate功能非常简单，只能提供静态文件服务。它使用异步I/O，即使在低端硬件上运行并处理大量并发请求时也能保持高效。

了解更多

安装和设置

获取Agate二进制文件。你可以使用以下任何方式：

预编译版本

下载并解压预编译二进制文件。

NixOS/Nix

使用nix包管理器运行nix-env -i agate

Guix系统

通过将agate-service-type添加到系统服务中，使用GNU Guix系统部署 Agate。

Arch Linux

安装agate-bin^AUR包以获取预编译二进制文件。或者安装agate^AUR包以从源代码编译Agate。

Cargo

如果已安装Rust工具链，运行cargo install agate从crates.io安装Agate。

源代码

下载源代码并在源代码仓库中运行cargo build --release，然后在target/release/agate找到二进制文件。

对于剩余步骤，如果tools目录中有适用于你系统的安装脚本，你可以使用它。如果没有，请考虑贡献一个，以便为不太懂技术的用户提供便利！

运行服务器。你可以使用以下参数指定内容目录的位置、要监听的IP地址和端口、请求URL中预期的主机名以及要包含在text/gemini文件MIME类型中的默认语言代码：（将主机名example.com替换为你的Gemini服务器地址。）如果你没有自己生成，Agate将在首次运行时使用指定的主机名为你生成私钥和证书。有关更多信息，请参阅下面的证书部分。

agate --content path/to/content/ \
      --addr [::]:1965 \
      --addr 0.0.0.0:1965 \
      --hostname example.com \
      --lang en-US

所有命令行参数都是可选的。运行agate --help可以查看省略参数时使用的默认值。

当客户端请求URL gemini://example.com/foo/bar时，Agate将响应path/to/content/foo/bar处的文件。如果请求路径的任何段以点开头，无论文件是否存在，Agate都会响应状态码52。可以使用--serve-secret或通过.meta配置文件中特定文件的条目来禁用此行为（参见元预设）。如果该路径是一个目录，Agate将在该目录中查找名为index.gmi的文件。

配置

自动证书生成

如果使用了--hostname参数，Agate将为每个指定的主机名生成密钥和自签名证书。对于Gemini，规范建议使用自签名证书，因为Gemini对证书使用TOFU（首次使用时信任）原则。因此，生成的证书也会有很长的过期时间，为4096-01-01。

有关手动配置密钥和证书，请参阅下面的证书部分。

TLS版本

Agate默认支持TLSv1.2和TLSv1.3。你可以使用--only-tls13标志（或其简短版本-3）禁用对TLSv1.2的支持。但不建议这样做，因为它可能会破坏与某些客户端的兼容性。Gemini规范要求"暂时"保持与TLSv1.2的兼容性，因为并非所有平台都对TLSv1.3有良好支持（参见规范的§4.1）。

目录列表

你可以通过在目录中放置一个名为.directory-listing-ok的文件来为该目录启用基本的目录列表。这不会影响子目录。此文件必须是UTF-8编码的文本；它可以为空。文件中的任何文本都会被添加到目录列表的前面。目录列表将隐藏名称以点开头的文件和目录（例如.directory-listing-ok文件本身、.meta配置文件或..目录）。

名为index.gmi的文件始终优先于目录列表。

元预设

你可以在任何内容目录中放置一个名为.meta的文件。这个文件存储了关于相邻文件的一些元数据，Agate在提供这些文件服务时会使用这些元数据。.meta文件必须是UTF-8编码的。你还可以使用-C标志（或长版本--central-conf）启用中央配置文件。在这种情况下，Agate将始终在内容根目录中查找.meta配置文件，并忽略其他目录中的.meta文件。

.meta文件的格式如下（*1）：

空行将被忽略。
同一行中#后面的所有内容都是注释，将被忽略。
所有其他行必须采用<path>:<metadata>的形式，即以文件路径开头，后跟冒号，然后是元数据。

<path>是区分大小写的文件路径，可能存在也可能不存在于磁盘上。如果指向一个目录，它将被忽略。如果不使用中央配置文件模式，使用不在当前目录中的文件路径是未定义的行为（例如，../index.gmi将是未定义的行为）。你可以在现有路径中使用Unix风格的模式。例如，content/*将匹配content中的任何文件，而content/**还将匹配content子目录中的任何文件。但是，由于它们的特殊含义，单独的*和**默认不会匹配以点开头的文件或目录。可以使用--serve-secret禁用此行为，或者通过例如content/.*或content/**/.*显式匹配以点开头的文件。有关可以使用的模式的更多信息，请参阅glob::Pattern的文档。规则可以覆盖其他规则，因此如果一个文件被多个规则匹配，最后一个规则适用。

<metadata>可以采用以下四种形式之一：

空
Agate不会发送默认语言参数，即使在命令行上指定了。
以分号开头，后跟MIME参数
如果找到文件，Agate将把指定的字符串附加到MIME类型上。
以Gemini状态码（即1-6之间的数字，后跟另一个数字）和空格开头
无论文件是否存在，Agate都会发送元数据。文件不会被发送或访问。
MIME类型，可能包含参数
如果找到文件，Agate将使用此MIME类型而不是它猜测的类型。即使在命令行上指定了，也不会使用默认语言参数。

如果一行违反格式或看起来像情况3但不正确，它可能会被忽略。你应该检查你的日志。请注意，只有在访问相应目录中的文件时才会首次读取此配置文件。因此，启动后没有日志消息并不意味着.meta文件没有问题。

这样的配置文件可能如下所示：

# 这行将被忽略。
**/*.de.gmi: ;lang=de
nl/**/*.gmi: ;lang=nl
index.gmi: ;lang=en-GB
LICENSE: text/plain;charset=UTF-8
gone.gmi: 52 This file is no longer here, sorry.

如果这是内容根目录中的.meta文件，并且使用了-C标志，将导致以下响应头：

/或/index.gmi -> 20 text/gemini;lang=en-GB
/LICENSE -> 20 text/plain;charset=UTF-8
/gone.gmi -> 52 This file is no longer here, sorry.
任何以.de.gmi结尾的非隐藏文件（包括在非隐藏子目录中） -> 20 text/gemini;lang=de
nl目录中任何以.gmi结尾的非隐藏文件（包括在非隐藏子目录中） -> 20 text/gemini;lang=nl

（*1）理论上，语法是典型的INI类文件的语法，也允许使用[section]进行分节（解析器中默认部分设置为mime），由于所有其他部分都被忽略，这不会有任何区别。这也意味着理论上你也可以使用=代替:。有关更多信息，你可以访问configparser的文档。

日志详细程度

Agate使用env_loggercrate，允许你通过设置RUST_LOG环境变量来设置日志详细程度。要关闭所有日志记录，请使用RUST_LOG=off。有关更多信息，请参阅[env_logger的文档]。

虚拟主机

Agate对虚拟主机有基本支持。如果你指定了多个--hostname，Agate将在内容根目录内查找相应主机名的目录。例如，如果其中一个主机名是example.com，内容根目录设置为默认的./content，并且请求了gemini://example.com/file.gmi，那么Agate将查找./content/example.com/file.gmi。此行为仅在指定多个--hostname时启用。 Agate还支持不同主机名使用不同的证书，请参阅下面的证书部分。如果您想为多个域名提供相同的内容，可以通过不指定--hostname来禁用主机名检查。在这种情况下，Agate 将忽略请求的主机名，只检查是否存在主机名。

当指定一个或多个--hostname时，Agate 会检查请求 URL 中的主机名和端口是否与指定的主机名和监听端口匹配。如果 Agate 位于另一个端口的代理后面，并收到一个指定代理端口的 URL 请求，这个端口可能与 Agate 的监听端口不匹配，请求将被拒绝：可以使用--skip-port-check禁用端口检查。

证书

Agate 支持通过--certs选项使用多个证书。因此，Agate 总是要求客户端使用 SNI，这不应该是问题，因为 Gemini 规范也要求使用 SNI。

证书默认存储在.certificates目录中。这是一个隐藏目录，目的是防止不谨慎的人将内容根目录设置为当前目录，而当前目录可能也包含证书目录。在这种情况下，证书和私钥仍然会被隐藏。证书只在 Agate 启动时加载，运行时不会重新加载。证书目录可以直接包含一对密钥和证书，如果没有其他匹配的密钥，这是使用的默认对。证书目录还可以包含特定域名的子目录，例如example.org和portal.example.org的文件夹。注意，子域名（如portal.example.org）的子文件夹不应该在其他子文件夹内，而应直接在证书目录中。Agate 将选择名称最匹配的证书/密钥对。例如，以下目录结构：

.certificates
|-- cert.der     (1)
|-- key.der      (1)
|-- example.org
|   |-- cert.der (2)
|   `-- key.der  (2)
`-- portal.example.org
    |-- cert.der (3)
    `-- key.der  (3)

这将被理解为：

证书/密钥对(1)将用于整个域名树（下面有例外）。
证书/密钥对(2)将用于example.org的整个域名树，包括像secret.example.org这样的子域名。它覆盖了这个子树的对(1)（下面有例外）。
证书/密钥对(3)将用于portal.example.org的整个域名树，包括像test.portal.example.org这样的子域名。它覆盖了这个子树的对(1)和(2)。

使用名为.的目录会导致未定义的行为，因为这与顶级证书/密钥对（上例中的对(1)）具有相同的含义。

证书/密钥对的文件必须分别命名为cert.der和key.der。证书必须是 DER 格式的 X.509 证书，并且必须包含域名的主题备用名称。私钥必须是 DER 格式，且必须是 RSA、ECDSA 或 Ed25519 密钥。

日志记录

所有通过 TCP 套接字的请求将使用以下格式记录：

<本地 IP>:<本地端口> <远程 IP 或破折号> "<请求>" <响应状态> "<响应元数据>"[ 错误:<错误>]

所有通过 Unix 套接字的请求将使用以下格式记录：

unix:[<Unix 套接字名称>] - "<请求>" <响应状态> "<响应元数据>"[ 错误:<错误>]

方括号表示可选部分。

"错误:"部分只有在发生错误时才会记录。这应该只用于提供信息，因为状态码应该提供发生错误的信息。如果错误在于连接未建立（例如因为 TLS 错误），可能会使用下面列出的特殊状态码。

默认情况下，Agate 不会记录远程 IP 地址，因为根据欧盟的 GDPR，IP 地址被视为私人数据，这可能会引起问题。要启用 IP 地址记录，可以使用--log-ip选项。请注意，在这种情况下，某些错误条件可能仍然会强制 Agate 记录破折号而不是 IP 地址。对于通过 Unix 套接字的连接，也无法记录 IP 地址。

根据选择的日志级别，日志中可能会出现一些除这些之外的行。例如初始的"Listening on..."行或关于列出特定目录的信息。

Agate 在记录错误时使用一些不是有效 Gemini 状态码的状态码：

00 - 建立 TLS 连接时出错
01 - 获取对等方 IP 地址时出错

安全考虑

如果您想在多用户系统上运行 agate，您应该意识到所有证书和密钥数据都会被加载到内存中，并存储在那里直到服务器停止。由于内存在使用后也不会被显式覆盖或清零，敏感数据可能在服务器终止后仍留在内存中。