---
title: "Caddy 反向代理认证方案"
created: 2026-05-01
updated: 2026-05-01
type: article
tags: []
sources: []
---

# 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]] — 外部委托认证模式