约定

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

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

网络地址

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

network/address

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

网络可以是以下任意一种；带有 4 或 6 后缀的分别表示仅 IPv4 或 IPv6：

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

地址部分可以是以下形式：

• host
• host:port
• :port
• [ipv6%zone]:port
• /path/to/unix/socket
• /path/to/unix/socket|0200

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

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

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

Unix socket 路径仅在网络类型为 unix* 时可用。分隔网络和地址的正斜杠不被视为路径的一部分。

当 Unix socket 用作绑定地址时，您可以选择在路径后指定文件权限模式，用管道符 | 分隔。默认为 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 配置 中，时间间隔值也可以是表示纳秒的整数。