Caddy 配置密码访问与配置文件管理笔记

1. Caddy 配置密码访问

1.1 生成密码哈希值

Caddy 要求配置文件中使用哈希值而非明文密码。使用以下命令生成哈希：

caddy hash-password --plaintext '你的密码'

默认使用 bcrypt 算法，输出示例：

$2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG

如需使用 argon2id 算法：

caddy hash-password --algorithm argon2id --plaintext '你的密码'

1.2 Caddyfile 配置示例

保护整个网站：

example.com {
    basic_auth {
        Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
    }
    reverse_proxy localhost:8080
}

保护特定路径：

example.com {
    basic_auth /secret/* {
        Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
    }
    file_server
}

更简洁的单行写法：

example.com {
    basic_auth Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
}

多用户配置：

example.com {
    basic_auth Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
    basic_auth Alice $2a$14$3Vx6LmPzJqR5kNzBcXk7bO8uYQvX4kMpLmNnQpRsTuVwXyZ
}

1.3 验证与重载配置

caddy validate --config /路径/Caddyfile
caddy reload

2. Caddyfile 缩进规则

2.1 基本规则

Caddyfile 对缩进的要求很简单：

• 指令和它的参数必须在同一行
• 子块必须比父块多缩进（具体缩进几个空格或 Tab 无所谓）
• 不能在同一文件中混用 Tab 和空格作为缩进

2.2 有效缩进示例

以下所有写法都是有效的：

使用 2 个空格：

example.com {
  basic_auth {
    Bob $2a$14$xxx
  }
}

使用 4 个空格（社区最常见）：

example.com {
    basic_auth {
        Bob $2a$14$xxx
    }
}

使用 8 个空格：

example.com {
        basic_auth {
                Bob $2a$14$xxx
        }
}

使用 Tab（Caddy 官方标准）：

example.com {
    basic_auth {
        Bob $2a$14$xxx
    }
}

2.3 常见陷阱

不要在同一文件中混用 Tab 和空格作为同一层的缩进，这会导致解析错误。

3. Caddy 配置验证与格式化命令

3.1 验证配置

caddy validate --config /路径/Caddyfile

配置正确时输出：Valid configuration

配置错误时会显示错误行号和问题描述。

3.2 自动格式化

caddy fmt --overwrite /路径/Caddyfile

caddy fmt 的格式化规则：

• 每级缩进使用 1 个 Tab 字符（这是 Caddy 官方标准格式）
• 会覆盖用户原有的缩进风格

3.3 检查缩进类型

使用以下命令查看文件实际使用的缩进字符：

cat -A 你的Caddyfile | head -20

输出对照：

• ^I 表示 Tab 字符
• $ 表示换行符
• 普通空格直接显示为空格

4. Tab 与空格的技术说明

4.1 Tab 的本质

• Tab 是 1 个字符（ASCII 码 9）
• 在文件中占用 1 个字节的存储空间
• 用 cat -A 看到的是 ^I

4.2 Tab 的显示宽度

编辑器的 Tab 显示宽度是可以配置的：

• 常见设置：2、4、8 个空格的宽度
• 这只是视觉效果，不改变文件内容
• 改变显示宽度不会影响文件存储的内容

4.3 区分两个概念

5. Vim 中处理 Tab 和空格

5.1 只改变显示（不改变文件内容）

:set tabstop=4

这只会让 Tab 字符显示为 4 个空格的宽度，文件内容仍然是 ^I。

5.2 将 Tab 转换为空格

:set expandtab
:retab
:w

这些命令会将文件中的 Tab 字符真正转换为空格。

5.3 查看文件中实际使用的字符

cat -A 文件名

6. 为什么某些配置文件使用 Tab 会报错

不同配置文件格式对 Tab 的处理规则不同：

对于 Caddyfile，Tab 本身不是问题，"不一致"才是问题的根源。

7. 推荐的工作流程

1. 编辑 Caddyfile
2. 运行 caddy validate 验证语法
3. 可选：运行 caddy fmt --overwrite 统一格式
4. 运行 caddy reload 使配置生效

如果希望使用空格而非 Tab，可以创建 .caddyfmt 配置文件：

{
    "use_spaces": true,
    "indent": 4
}

但建议接受 Caddy 官方格式（Tab），仅在编辑器中调整 tabstop=4 以满足视觉偏好。