2.2 KiB
2.2 KiB
title, created, updated, type, tags, sources
| title | created | updated | type | tags | sources |
|---|---|---|---|---|---|
| Caddy 反向代理认证方案 | 2026-05-01 | 2026-05-01 | article |
Caddy 反向代理认证方案
- 类型: 技术教程/配置指南
- 标签: #caddy #reverse-proxy #authentication
概述
Caddy 本身没有内置 X-API-Key 或 Bearer Token 的直接校验指令，但利用命名匹配器（Named Matcher） + respond/abort 指令可以干净利落地实现。本文涵盖 5 种认证方案，从零依赖纯内置到完整 JWT 生态。
方案总览
方案一：Header 匹配器（纯内置，推荐）
利用 Caddy 的 header 匹配器检查请求头，不匹配则返回 401。
核心逻辑：@unauthorized { not header X-API-Key "..." } → respond @unauthorized "Unauthorized" 401
- 支持
X-API-Key和Authorization: Bearer两种头格式 - 可通过命名匹配器组合实现多 Key 白名单
方案二：Route + Handle（路径级别控制）
同一站点下，/public/* 不需要认证，/api/* 需要 Bearer Token —— 用 route + handle 块做路径级别精细控制。
方案三：Basic Auth（用户名密码）
Caddy 内置 basicauth 指令，使用 caddy hash-password 生成 bcrypt 哈希。
方案四：Forward Auth（外部认证委托）
将认证逻辑委托给外部服务（查数据库、第三方鉴权），外部服务返回 200 通过，401/403 拒绝。Caddy 原生支持 forward_auth 指令。
方案五：JWT 插件（完整 JWT 生态）
通过社区插件 caddy-auth-jwt 实现 JWT 签发、验证、claim 提取，需重新编译 Caddy。
方案选择指南
| 场景 | 推荐方案 |
|---|---|
| 简单固定 API Key / Bearer Token | [[reverse-proxy-authentication |
| 部分路径需要认证 | 方案二（route + handle） |
| 用户名密码即可 | 方案三（basicauth） |
| 认证逻辑复杂，需外部服务 | [[forward-authentication |
| 需要完整的 JWT 生态 | 方案五（JWT 插件） |
相关概念
- caddy-web-server — Caddy Web 服务器
- reverse-proxy-authentication — 反向代理层认证模式
- api-key-authentication — API Key / Token 认证
- forward-authentication — 外部委托认证模式