约定

Caddy 生态系统遵循一些约定，以使整个平台保持一致性和直观性。

• 网络地址
• 占位符
• 文件位置
  • 数据目录
  • 配置目录
• 持续时间

网络地址

当指定要拨号或绑定的网络地址时，Caddy 接受以下格式的字符串

network/address

网络部分是可选的（默认为 tcp），并且是 Go 的 net.Dial 函数 可以识别的任何内容。如果指定了网络，则必须使用单个正斜杠 / 分隔网络和地址部分。

网络可以是以下任何一种；后缀为 4 或 6 的分别是仅 IPv4 或仅 IPv6

• TCP: tcp, tcp4, tcp6
• UDP: udp, udp4, udp6
• IP: ip, ip4, ip6
• Unix: unix, unixgram, unixpacket

地址部分可以是以下任何形式

• 主机名
• 主机名:端口
• :端口
• [ipv6%zone]:端口
• /path/to/unix/socket
• /path/to/unix/socket|0200

主机可以是任何主机名、可解析的域名或 IP 地址。

在 IPv6 地址的情况下，地址必须用方括号 [] 括起来。区域标识符（以 % 开头）是可选的（通常用于链路本地地址）。

端口可以是单个值（:8080）或包含范围（:8080-8085）。端口范围将倍增为单个地址。并非所有配置字段都接受端口范围。特殊端口 :0 表示任何可用端口。

仅当使用 unix* 网络类型时，unix 套接字路径才是可接受的。分隔网络和地址的正斜杠不被视为路径的一部分。

当 unix 套接字用作绑定地址时，您可以选择在路径后指定文件权限模式，用管道符 | 分隔。默认值为 0200（八进制），即 u=w,g=,o=（符号）。前导 0 是可选的。

有效示例

:8080
127.0.0.1:8080
localhost:8080
localhost:8080-8085
tcp/localhost:8080
tcp/localhost:8080-8085
udp/localhost:9005
[::1]:8080
tcp6/[fe80::1%eth0]:8080
unix//path/to/socket
unix//path/to/socket|0200

占位符

Caddy 的配置支持使用占位符。使用占位符是将动态值注入静态配置的简单方法。

占位符的两侧用花括号 { } 括起来，并在内部包含标识符，例如：{foo.bar}。可以转义开头的占位符花括号 \{like.this} 以防止替换。占位符标识符通常用点命名空间，以避免跨模块的冲突。

哪些占位符可用取决于上下文。并非所有占位符在配置的所有部分都可用。例如，HTTP 应用程序设置的占位符仅在与处理 HTTP 请求相关的配置区域中可用。

以下占位符始终可用（全局）

占位符	描述
{env.*}	环境变量；示例：{env.HOME}
{file.*}	来自文件的内容；示例：{file./path/to/secret.txt}
{system.hostname}	系统的本地主机名
{system.slash}	系统的文件路径分隔符
{system.os}	系统的操作系统
{system.arch}	系统的架构
{system.wd}	当前工作目录
{time.now}	当前时间，作为 Go Time 结构体
{time.now.http}	HTTP 标头中使用的格式的当前时间
{time.now.unix}	当前时间，以秒为单位的 Unix 时间戳
{time.now.unix_ms}	当前时间，以毫秒为单位的 Unix 时间戳
{time.now.common_log}	通用日志格式的当前时间
{time.now.year}	当前年份，YYYY 格式

并非所有配置字段都支持占位符，但大多数您期望的地方都支持。对占位符的支持需要显式添加到这些字段中。插件作者可以阅读本文，了解如何在他们自己的模块中添加对占位符的支持。

文件位置

本节包含有关在何处查找各种文件的信息。此处描述的文件和目录路径充其量是默认值；有些可以被覆盖。

您的配置文件

没有一个单一的、约定俗成的地方来放置您的配置文件。将它们放在对您来说最有意义的地方。

随附默认配置文件的发行版应记录此配置文件的位置，即使对于软件包/发行版维护者来说这可能是显而易见的。对于大多数 Linux 安装，Caddyfile 将位于 /etc/caddy/Caddyfile。

数据目录

Caddy 将 TLS 证书和其他重要资产存储在数据目录中，该目录由 配置的存储模块（默认值：本地文件系统）支持。

如果设置了 XDG_DATA_HOME 环境变量，则为 $XDG_DATA_HOME/caddy。

否则，其路径因平台而异，并遵循操作系统约定

所有其他操作系统都使用 Linux/BSD 目录路径。

数据目录不得被视为缓存。 其内容不是临时的，也不仅仅是为了提高性能。Caddy 将 TLS 证书、私钥、OCSP 订书钉和其他必要信息存储到数据目录中。不了解其含义不应清除它。

至关重要的是，此目录是持久的并且可由 Caddy 写入。

配置目录

这是 Caddy 可能会将某些配置存储到磁盘的位置。最值得注意的是，它会将最后一个活动配置（默认情况下）持久化到此文件夹中，以便以后使用 caddy run --resume 轻松恢复。

如果设置了 XDG_CONFIG_HOME 环境变量，则为 $XDG_CONFIG_HOME/caddy。

否则，其路径因平台而异，并遵循操作系统约定

所有其他操作系统都使用 Linux/BSD 目录路径。

至关重要的是，此目录是持久的并且可由 Caddy 写入。

持续时间

持续时间字符串在 Caddy 的配置中很常用。它们采用与 Go 的 time.ParseDuration 语法 相同的格式，除了您还可以使用 d 表示天（为简单起见，我们假设 1 天 = 24 小时）。有效单位为

• ns (纳秒)
• us/µs (微秒)
• ms (毫秒)
• s (秒)
• m (分钟)
• h (小时)
• d (天)

示例

• 250ms
• 5s
• 1.5h
• 2h45m
• 90d

在 JSON 配置 中，持续时间值也可以是表示纳秒的整数。