Agate虚拟主机配置：多域名站点部署与证书管理技巧

Agate虚拟主机配置：多域名站点部署与证书管理技巧

【免费下载链接】agateVery simple server for the Gemini hypertext protocol项目地址: https://gitcode.com/gh_mirrors/aga/agate

Agate作为一款轻量级Gemini协议服务器，支持通过虚拟主机配置实现多域名站点部署，并提供灵活的证书管理功能。本文将详细介绍如何在Agate中配置虚拟主机、管理多域名证书，以及优化站点访问体验的实用技巧。

快速上手：虚拟主机基础配置

启用多域名支持的核心步骤

要在Agate中启用虚拟主机功能，只需在启动命令中指定多个--hostname参数：

agate --content ./content \ --hostname example.com \ --hostname example.org \ --addr 0.0.0.0:1965

当指定多个主机名后，Agate会自动启用虚拟主机模式。此时服务器会在内容根目录下创建与域名对应的子目录，例如./content/example.com和./content/example.org，分别存储不同域名的站点内容。

目录结构规范

虚拟主机模式下的推荐目录结构：

./content/ ├── example.com/ │ ├── index.gmi │ └── posts/ └── example.org/ ├── index.gmi └── about.gmi

当访问gemini://example.com/posts/hello.gmi时，Agate会自动定位到./content/example.com/posts/hello.gmi文件。如果请求的路径是目录，服务器会默认查找该目录下的index.gmi文件。

证书管理：从自动生成到手动配置

自动证书生成机制

Agate采用Gemini协议推荐的TOFU（Trust on First Use）原则，支持自动为指定主机名生成自签名证书：

• 首次启动时，若.certificates目录不存在或没有对应域名的证书，Agate会自动生成有效期至4096年的ECDSA证书
• 生成的证书包含正确的Subject Alternative Name，确保客户端验证通过
• 证书和私钥默认存储在.certificates目录，采用DER格式存储

手动配置多域名证书

对于需要使用自定义证书的场景，可通过以下步骤配置：

1. 创建证书目录结构：

.certificates/ ├── cert.der # 默认证书（可选） ├── key.der # 默认私钥（可选） ├── example.com/ │ ├── cert.der │ └── key.der └── example.org/ ├── cert.der └── key.der

2. 证书文件要求：

   • 证书必须是X.509格式的DER文件（cert.der）
   • 私钥必须是RSA、ECDSA或Ed25519格式的DER文件（key.der）
   • 证书必须包含对应域名的Subject Alternative Name

3. PEM格式转换为DER：

如果已有PEM格式证书，可使用OpenSSL转换：

# 转换证书 openssl x509 -in cert.pem -out cert.der -outform der # 转换私钥 openssl pkcs8 -topk8 -inform PEM -outform DER -in key.pem -out key.der -nocrypt

高级配置：优化多站点管理

集中配置模式（Central Config）

通过-C或--central-conf标志启用集中配置模式，所有设置将统一由内容根目录下的.meta文件管理：

agate --content ./content \ --hostname example.com \ --hostname example.org \ -C

集中配置文件（./content/.meta）示例：

# 设置默认MIME类型 [mime] .gmi=text/gemini; charset=utf-8 .txt=text/plain; charset=utf-8 # 自定义目录列表样式 directory-listing-style=gemini directory-listing-preamble=./preamble.gmi # 设置缓存控制 cache-control=public, max-age=3600

证书目录自定义

使用--certs参数指定自定义证书目录位置：

agate --content ./content \ --hostname example.com \ --certs /etc/agate/certificates \ --addr 0.0.0.0:1965

这在服务器迁移或多实例部署时特别有用，确保证书文件集中管理且不会意外暴露。

常见问题与解决方案

证书不匹配错误

若客户端提示证书与域名不匹配，可能原因：

1. 证书缺少Subject Alternative Name字段
2. 证书文件放置位置错误
3. 域名大小写不匹配（Agate对域名进行小写处理）

解决方法：将旧证书移至.certificates目录顶层，或重新生成包含正确SAN的证书。

虚拟主机不生效

当虚拟主机配置未按预期工作时，检查：

1. 是否指定了多个--hostname参数
2. 内容目录下是否创建了与域名对应的子目录
3. 启动命令中是否使用了--skip-port-check（当服务器在代理后运行时）

证书更新与重载

Agate在启动时加载证书，证书更新后需重启服务器才能生效：

# 停止当前实例 pkill agate # 启动更新后的实例 agate --content ./content --hostname example.com --hostname example.org

总结

Agate通过--hostname参数和目录结构实现了轻量级虚拟主机功能，结合灵活的证书管理机制，为Gemini协议多站点部署提供了简单而强大的解决方案。无论是个人博客还是小型社区，都能通过本文介绍的方法快速搭建安全、高效的Gemini服务。

通过合理配置证书目录结构和利用集中配置模式，可以显著简化多域名站点的管理复杂度，同时遵循Gemini协议的TOFU原则，确保通信安全与用户体验的平衡。

【免费下载链接】agateVery simple server for the Gemini hypertext protocol项目地址: https://gitcode.com/gh_mirrors/aga/agate