20260514:增加新内容

articles/caddy-reverse-proxy-auth.md

@@ -0,0 +1,56 @@
+---
+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]] — 外部委托认证模式