57 lines
2.2 KiB
Markdown
57 lines
2.2 KiB
Markdown
---
|
||
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]] — 外部委托认证模式
|