#Caddy

如果你已经有域名，并且希望尽快把 HTTPS 一起配好，那么 nb proxy caddy 通常是最省心的入口方式。

比起自己维护 Nginx 的证书配置，Caddy 更像是“先把入口层跑通”的默认捷径。

#什么时候更适合用 Caddy

通常来说，下面几种情况优先考虑 Caddy：

• 你已经有域名，希望尽快接入 HTTPS
• 你不想自己维护太多证书和 TLS 细节
• 你只需要一个简单稳定的入口层

如果你已经在服务器上统一用 Nginx 管理很多站点，或者后面还要做比较重的缓存、访问控制和定制规则，那么继续看 Nginx 会更顺。

#先按这三条命令操作

如果你只想先把 Caddy 入口层跑起来，默认记住这三条命令就够了：

nb proxy caddy use docker
nb proxy caddy generate --env test2 --host c.local.nocobase.com
nb proxy caddy reload

如果本地已经安装好了 Caddy，把第一条改成 nb proxy caddy use local 就行。

多数场景下，先执行 use，再执行 generate，最后执行 reload 就够了。其他细节和更多命令，直接看后面的章节或 CLI 参考。

#第一步：先选 Caddy 自己怎么运行

如果当前机器上已经安装好了 Caddy，直接用 use local 就行。

如果你想用 Docker 版的 Caddy，就用 use docker。

这里的 local / docker 指的是 Caddy 本身的运行方式。

使用 Docker 版 Caddy：

nb proxy caddy use docker

使用本地安装的 Caddy：

nb proxy caddy use local

如果你后面忘了当前选的是哪一种方式，可以执行：

nb proxy caddy current

#第二步：执行 generate

generate 用来按指定 env 生成 Caddy 配置。最常见的写法是：

nb proxy caddy generate --env test2 --host c.local.nocobase.com

如果你还想指定入口端口，也可以一起写：

nb proxy caddy generate --env test2 --host c.local.nocobase.com --port 8080

这里的参数含义是：

• --env：指定为哪个 CLI env 生成配置
• --host：指定对外访问域名
• --port：指定代理入口端口

对于 Caddy 来说，--host 尤其重要。正式环境里，默认尽量传一个已经解析到当前服务器的域名，这样 HTTPS 的接入会更自然。

如果命令提示 env 缺少 appPort，先执行：

nb env update test2 --app-port 56575

如果你后续又改了 app-port、app-public-path 这类会影响代理结果的配置，记得重新执行 generate。

#第三步：执行 reload

生成配置之后，直接执行：

nb proxy caddy reload

多数场景下都直接用这条命令就行。如果当前还没跑起来，内部会先处理启动；如果已经在运行，则会按最新配置重载。

#CLI 会维护哪些文件

以 test2 为例，Caddy 相关命令通常会维护这些文件与目录：

其中：

• NB_CLI_ROOT/.nocobase/proxy/caddy/... 下面的是 CLI 维护的代理辅助文件
• NB_CLI_ROOT/test2/storage/... 下面的是应用自己的静态资源和上传目录
• nocobase.caddy 是 provider 级入口文件，通常不需要手动改
• app.caddy 是某个 env 的完整 Caddy 站点配置，重新执行 generate 会整体覆盖

#手写配置：不通过 CLI 时怎么做

如果你的应用不是 CLI 托管的，或者你明确要自己维护完整的 Caddy 配置，也可以手写。

不过对于 NocoBase 来说，生产环境入口通常不只是一个简单的 reverse_proxy。除了把 API 请求转发到后端应用之外，一份完整可用的 Caddy 配置通常还需要同时处理上传目录、前端静态资源、文件访问入口 /files/、.well-known 路由、WebSocket，以及 SPA 回退页。

以 test2 为例，和 Caddy 相关的关键目录通常包括：

• SPA 回退页目录：NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public
• 前端构建产物目录：NB_CLI_ROOT/test2/storage/dist-client
• 上传目录：NB_CLI_ROOT/test2/storage/uploads

也就是说，手写配置时通常至少要覆盖下面这几类入口：

• v：把 /v 重定向到 /v/
• uploads：暴露上传目录
• dist：暴露前端构建产物目录
• oauth well-known：处理 OAuth 发现路径
• openid well-known：处理 OpenID 发现路径
• files：把 /files/ 下的文件访问请求转发到后端应用
• api：转发 /api/ 请求到后端应用
• ws：转发 WebSocket 请求到后端应用
• spa v2：为 /v/ 提供前端入口及回退页
• spa v1：为 / 提供前端入口及回退页

所以一份完整的 Caddy 配置，通常并不只是下面这种通用写法：

your-domain.com {
  reverse_proxy 127.0.0.1:13000
}

对 test2 这类 CLI 托管应用来说，更接近真实部署情况的结构通常会像下面这样：

c.local.nocobase.com {
    encode zstd gzip

    handle /v {
        redir * /v/ 302
    }

    handle_path /storage/uploads/* {
        root * NB_CLI_ROOT/test2/storage/uploads
        header Cache-Control public
        header X-Content-Type-Options nosniff
        file_server
    }

    handle_path /dist/* {
        root * NB_CLI_ROOT/test2/storage/dist-client
        header Cache-Control public
        file_server
    }

    @oauth path_regexp oauth ^/\\.well-known/oauth-authorization-server/(.+)$
    handle @oauth {
        rewrite * /{re.oauth.1}/.well-known/oauth-authorization-server
        reverse_proxy host.docker.internal:56575
    }

    @openid path_regexp openid ^/\\.well-known/openid-configuration/(.+)$
    handle @openid {
        rewrite * /{re.openid.1}/.well-known/openid-configuration
        reverse_proxy host.docker.internal:56575
    }

    handle /files/* {
        reverse_proxy host.docker.internal:56575
    }

    handle /api/* {
        reverse_proxy host.docker.internal:56575
    }

    handle /ws {
        reverse_proxy host.docker.internal:56575
    }

    handle_path /v/* {
        root * NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public
        header Cache-Control "no-store, no-cache, must-revalidate"
        header X-Robots-Tag "noindex, nofollow"
        try_files {path} /index-v2.html
        file_server
    }

    handle_path /* {
        root * NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public
        header Cache-Control "no-store, no-cache, must-revalidate"
        header X-Robots-Tag "noindex, nofollow"
        try_files {path} /index-v1.html
        file_server
    }
}

这里也有两个关键点：

• NB_CLI_ROOT/.nocobase/proxy/caddy/... 下面的是 CLI 维护的 SPA 回退页目录
• NB_CLI_ROOT/test2/storage/... 下面的是应用自己的构建产物目录和上传目录

如果你的应用使用了子路径部署，或者前端资源、上传目录和入口层不在同一个路径视角里，那么手写配置会更容易出错。这种场景下，通常更推荐先执行：

nb proxy caddy generate --env test2 --host c.local.nocobase.com

然后再以生成结果为基准做调整。

如果你希望先让 CLI 帮你把路径和路由都跑通，那么生成后的结构通常会是：

NB_CLI_ROOT/.nocobase/proxy/caddy/nocobase.caddy
NB_CLI_ROOT/.nocobase/proxy/caddy/test2/app.caddy
NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public/index-v1.html
NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public/index-v2.html
NB_CLI_ROOT/test2/storage/dist-client
NB_CLI_ROOT/test2/storage/uploads

其中：

• nocobase.caddy 负责统一 import */app.caddy
• test2/app.caddy 是 test2 这个 env 的完整站点配置
• public/index-v1.html 和 public/index-v2.html 是 CLI 生成的 SPA 回退页

更稳妥的做法通常是：

1. 先让 CLI 生成 Caddy 配置
2. 以生成结果作为基准确认路由结构和实际路径
3. 再根据你的域名、运行方式和挂载路径做手工调整

这样通常比从零手写一份配置更不容易漏掉 /files/、WebSocket、静态资源、上传目录、.well-known 路由或 SPA 回退页相关的细节。

#检查并重载配置

如果你是手写或手工调整 Caddy 配置，改完后先校验，再重载：

caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy

如果你不是用 systemd 管理 Caddy，也可以改用你自己的启动和重载方式。

如果你是通过 nb proxy caddy 管理入口层，那么通常优先使用：

nb proxy caddy reload

如果你想看当前 driver、总入口文件路径、运行时根目录和容器或本地二进制信息，可以执行：

nb proxy caddy info

如果你只想快速确认当前是否已经跑起来，可以执行：

nb proxy caddy status

#常见说明

• nb proxy caddy generate 适用于 nb init 安装的应用
• 如果你已经有能正常解析到服务器的域名，Caddy 往往是最快拿到 HTTPS 的方式
• 如果你后续改了 app-port、app-public-path 这类会影响代理结果的配置，记得重新执行 generate

#相关链接

• 生产环境反向代理
• Nginx
• 使用 CLI 安装应用
• 应用配置与 .env
• nb proxy caddy 命令参考