约定

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 地址，地址必须用方括号 [] 包裹。zone 标识符（以 % 起始）是可选的（通常用于链路本地地址）。

端口可以是单一值（: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}	当前时间，采用 Common Log Format
{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 配置 中，时长值也可以是表示纳秒数的整数。