FrankenPHP后台Basic认证必须由PHP层实现，因Caddy不解析传统Auth指令且认证逻辑透传至PHP；需在入口文件校验$_SERVER["PHP_AUTH_USER"]和$_SERVER["PHP_AUTH_PW"]，并强制HTTPS。
FrankenPHP 后台路径加 Basic 认证，不能直接套用 Apache 的 .htaccess 或 Nginx 的 auth_basic 指令——它不走传统 Web 服务器的认证模块，得靠 PHP 层拦截 + HTTP 头响应实现。
为什么不能用 Apache/Nginx 那套配置
FrankenPHP 默认用 Caddy 作前端，但它的认证逻辑是“透传到 PHP”的：Caddy 不解析 AuthType、不读 AuthUserFile，所有 Basic Auth 必须由 PHP 脚本自己检查 $_SERVER["PHP_AUTH_USER"] 和 $_SERVER["PHP_AUTH_PW"]。如果你在 Caddyfile 里写 basicauth，那只是 Caddy 自己的认证（会拦截在 PHP 执行前），和你的后台逻辑脱节，容易导致登录态不一致或跳过权限校验。
- Caddy 的
basicauth是独立于应用的网关层认证，无法感知 Laravel/ThinkPHP 的 session 或 RBAC - FrankenPHP 的
php-server模式下，Caddy 只负责路由转发，不介入业务认证流程 - 想让后台路径（如
/admin或/manage_panel.php）受控，就得在 PHP 入口或中间件里做判断
PHP 层实现 Basic Auth 的最小可行代码
在后台入口文件（比如 manage_panel.php）最开头插入以下逻辑，不用额外依赖：
// 检查是否已提供凭证
if (!isset($_SERVER["PHP_AUTH_USER"], $_SERVER["PHP_AUTH_PW"])) {
header("WWW-Authenticate: Basic realm=\"后台管理\"");
http_response_code(401);
exit("Unauthorized");
}
// 从 JSON 文件读用户（比 htpasswd 更轻量，FrankenPHP 无须额外工具）
$users = json_decode(file_get_contents("/app/config/auth.json"), true);
$valid = false;
foreach ($users as $user) {
if ($user["user"] === $_SERVER["PHP_AUTH_USER"] &&
$user["password"] === $_SERVER["PHP_AUTH_PW"]) {
$valid = true;
break;
}
}
if (!$valid) {
header("WWW-Authenticate: Basic realm=\"后台管理\"");
http_response_code(401);
exit("Unauthorized");
}
-
/app/config/auth.json必须是合法 JSON 数组（不是多个对象拼接），参考格式：[{"user":"admin","password":"p@ssw0rd"}] - 密码明文存 JSON 是临时方案；生产环境应改用
password_hash()+password_verify() - 不要把这段代码放
index.php全局入口，否则整个站都被锁；只挂到后台专属入口
配合 FrankenPHP Worker 模式要注意的坑
Worker 模式下，PHP 生命周期变长，$_SERVER 变量可能被复用或缓存，导致认证状态错乱：
立即学习“PHP免费学习笔记（深入）”；
- 每次请求都必须重新检查
PHP_AUTH_USER，不能靠static $authed缓存结果 - 避免在
frankenphp_handle_request()外围做一次性认证初始化——它可能跨请求生效 - 如果用了 Laravel，别在
AppServiceProvider::boot()里注册 Basic Auth 中间件；应在app/Http/Middleware里单独写一个，并只对admin/*路由启用 - Caddy 的
reverse_proxy到 FrankenPHP 时，要确保header_up Authorization {http.request.header.Authorization}显式透传，否则$_SERVER["PHP_AUTH_*"]为空
HTTPS 是硬性前提，否则认证形同虚设
FrankenPHP 的 Docker 镜像默认启用 HTTPS（Caddy 自动签发 localhost 证书），但你挂载自定义域名时容易漏配：
- 用
-e SERVER_NAME=yourdomain.com启动容器，Caddy 才会去申请 Let's Encrypt 证书 - 若本地开发用
https://localhost，浏览器会警告证书无效，但 Basic Auth 仍可工作；线上必须用有效证书 - HTTP 下浏览器可能直接屏蔽
Authorization头（尤其 Chrome 80+），导致永远 401 - FrankenPHP 不会自动重定向 HTTP → HTTPS，得在 Caddyfile 里加
redir https://{host}{uri} permanent
真正卡住人的地方，往往不是怎么写认证逻辑，而是没意识到 FrankenPHP 的认证必须“自己动手”，且 HTTPS 不只是建议——它是 Basic Auth 能跑起来的底线。
