Caddy 旧版收到 bcrypt 却报 illegal base64 data：核对哈希格式与版本

Caddyfile 中已经填入以 $2a$ 或类似前缀开头的 bcrypt 哈希，旧 Caddy 加载认证模块时仍报 base64-decoding password: illegal base64 data at input byte 0。这不一定表示密码生成错了：Caddy 2.4.6 的认证模块会先按 Base64 解码配置值，直接收到当前常用的 bcrypt 字符串就会失败。

先核对实际运行版本和哈希的生成方式。当前 Caddy 接收相应的密码哈希格式，不能把新版文档中的输出直接当成所有旧版本都支持。错误发生在配置加载时，尚未到浏览器提交用户名、密码的阶段。

看运行中的版本，不只看镜像标签

使用实际服务的二进制，或在实际容器中查看 caddy version。构建镜像时用的版本、宿主机上的另一份 Caddy、Compose 文件中的新标签，都不能替代运行实例的版本。

容器名为 caddy、镜像包含 Caddy 命令时，可以只读检查：

docker exec caddy caddy version

版本仍是 2.4.6，而哈希为未经额外 Base64 编码的 bcrypt 字符串时，符合这里的格式兼容分支。不能从 illegal base64 data 一句话就推断所有版本的根因相同；新版也可能因为实际加载的值不完整、环境变量缺失或格式错误而失败。

查看配置时只核对值的格式和来源，不把真实哈希、明文密码或展开后的环境变量贴到公开日志。认证模块读取的是最终配置，挂载了另一份 Caddyfile、容器没有重建，都会让本地改动与运行状态不同。

让密码生成工具与运行版本配套

准备当前受支持且经过项目验证的 Caddy 版本，保留原镜像、模块列表、配置和证书存储，再按已有部署流程更新。需要额外 DNS 等模块的构建，应确认新版本仍包含它们，不仅替换成一张名字相近的镜像。

用目标版本的密码工具生成哈希，以下在受控交互终端中使用：

caddy hash-password --algorithm bcrypt

不提供 plaintext 参数时，工具从标准输入读取密码；连接到终端时不会回显输入。将生成结果按该版本支持的格式保存到受保护的配置或秘密管理入口，不把密码写进命令行或提交到版本库。

不要只对明文密码做 Base64 编码。Base64 是编码，不是密码哈希；旧版本要求额外编码的对象也是哈希值，而非把明文换一种表示就完成认证配置。必须暂时保留旧版本时，按那一版自带工具和文档生成匹配的格式，并明确后续升级安排，不随手混用两套输出。

指令名称也要符合版本

当前 Caddyfile 指令是 basic_auth，2.8.0 以前名为 basicauth。升级后核对目标版本的语法。下面是当前 Caddy 的结构示例；环境变量必须提供已生成的 bcrypt 哈希，域名和上游均为占位值：

private.example.com {
    basic_auth {
        reader {$BASIC_AUTH_HASH}
    }
    reverse_proxy 127.0.0.1:8080
}

这段示例保护整个站点，保留实际服务的 TLS 与代理要求后再合并。不要为了让加载通过先删掉认证，或将站点改为明文 HTTP。HTTP Basic Authentication 的凭据需要通过 HTTPS 传输；哈希配置正确不会替代传输保护。

环境变量由真正运行或加载配置的进程取得。交互 shell 中定义过，不证明服务管理器或容器也能读取。检查时应确认变量是否存在及哈希格式，不打印其内容；由 Compose、脚本等多层传递时，还要核对最终值是否被改写。

转换通过后还要验证认证行为

单纯 caddy adapt 成功，不保证认证模块 provision 成功。候选配置可以按部署方式进行更深入的 validate 检查；它会实际 provision 模块，部分模块会占用独占资源，应在受控候选环境或既有发布流程中检查，不把它当成纯文本检查。

配置与镜像更新后，确认实际实例接受新配置，未登录和错误密码请求返回预期的 401，正确凭据能访问所保护的资源，HTTPS 与上游业务仍正常。浏览器可能缓存认证信息，验收应区分请求是否已经带了凭据，不能只看到页面打开就认定认证失效。

若需回退，恢复配套的版本、模块、配置与哈希格式，保留原证书存储。只切回旧镜像而继续使用新版配置值，可能再次导致加载失败；如果密码也已轮换，应按凭据管理记录恢复或重新分发，不从旧日志找明文。