#Nginx

如果你已经在服务器上用 Nginx 管理站点，或者后面还要自己接证书、缓存、访问控制，那么 nb proxy nginx 是默认推荐路径。

如果你只是想尽快把 HTTPS 配好，不想自己维护太多代理细节，那么 Caddy 会更省心。不过只要你本来就在用 Nginx，这篇文档就是默认路径。

#什么时候更适合用 Nginx

通常来说，下面几种情况优先继续使用 Nginx：

• 你已经在服务器上统一用 Nginx 管理多个站点
• 你后面还需要自己维护证书、缓存、访问控制或更多自定义规则
• 你希望入口层继续沿用现有的 Nginx 运维方式

如果你的目标只是尽快把 HTTPS 跑通，另外不想自己维护太多 TLS 细节，那么 Caddy 会更省心。

#先按这三条命令操作

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

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

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

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

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

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

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

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

使用 Docker 版 Nginx：

nb proxy nginx use docker

使用本地安装的 Nginx：

nb proxy nginx use local

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

nb proxy nginx current

#第二步：执行 generate

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

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

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

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

这里的参数含义是：

• --env：指定为哪个 CLI env 生成配置
• --host：指定对外访问域名
• --port：指定代理入口端口，不是 NocoBase 应用本身的 appPort

上游应用端口来自这个 env 已保存的 appPort。如果命令提示 env 缺少 appPort，先执行：

nb env update test2 --app-port 56575

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

#第三步：执行 reload

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

nb proxy nginx reload

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

#CLI 会维护哪些文件

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

其中：

• NB_CLI_ROOT/.nocobase/proxy/nginx/... 下面的是 CLI 维护的代理辅助文件
• NB_CLI_ROOT/test2/storage/... 下面的是应用自己的静态资源和上传目录
• app.conf 可以改，不过要保留 NocoBase 托管区块
• index-v1.html 和 index-v2.html 会按当前 env 的子路径、active client 版本，以及 CDN_BASE_URL 自动重写资源地址

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

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

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

以 test2 为例，和 Nginx 相关的关键文件与目录通常包括：

• Nginx snippets：NB_CLI_ROOT/.nocobase/proxy/nginx/snippets
• 可编辑入口配置：NB_CLI_ROOT/.nocobase/proxy/nginx/test2/app.conf
• SPA 回退页（v1）：NB_CLI_ROOT/.nocobase/proxy/nginx/test2/public/index-v1.html
• SPA 回退页（v2）：NB_CLI_ROOT/.nocobase/proxy/nginx/test2/public/index-v2.html
• 前端构建产物目录：NB_CLI_ROOT/test2/storage/dist-client
• 上传目录：NB_CLI_ROOT/test2/storage/uploads

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

• uploads：通过 alias 暴露上传目录
• dist：通过 alias 暴露前端构建产物目录
• well-known：处理 OAuth / OpenID 相关发现路径
• api：转发 /api/ 请求到后端应用
• ws：转发 WebSocket 请求到后端应用
• spa：为 / 和 /v/ 提供前端入口及 try_files 回退

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

location / {
    proxy_pass http://127.0.0.1:13000;
}

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

server {
    listen 80;
    server_name c.local.nocobase.com;

    # Add custom directives or locations above the managed block as needed.

    client_max_body_size 0;

    include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/mime-types.conf;
    include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/gzip.conf;

    location /storage/uploads/ {
        alias NB_CLI_ROOT/test2/storage/uploads/;
        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/uploads-location.conf;
    }

    location ^~ /dist/ {
        alias NB_CLI_ROOT/test2/storage/dist-client/;
        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/dist-location.conf;
    }

    location ~ ^/\\.well-known/(?<well_known>oauth-authorization-server|openid-configuration)/(?<resource_path>.+)$ {
        rewrite ^ /$resource_path/.well-known/$well_known break;
        proxy_pass http://127.0.0.1:56575;
        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/proxy-location.conf;
    }

    location ^~ /api/ {
        proxy_pass http://127.0.0.1:56575;
        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/proxy-location.conf;
    }

    location = /ws {
        proxy_pass http://127.0.0.1:56575;
        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/proxy-location.conf;
    }

    location = /v {
        return 302 /v/$is_args$args;
    }

    location ^~ /v/ {
        alias NB_CLI_ROOT/.nocobase/proxy/nginx/test2/public/;
        try_files $uri /index-v2.html =404;
        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/spa-location.conf;
    }

    location ^~ / {
        alias NB_CLI_ROOT/.nocobase/proxy/nginx/test2/public/;
        try_files $uri /index-v1.html =404;
        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/spa-location.conf;
    }

    # Add custom directives or locations below the managed block as needed.
}

这里有两个关键点：

• NB_CLI_ROOT/.nocobase/proxy/nginx/... 下面的是 CLI 维护的代理辅助文件
• NB_CLI_ROOT/test2/storage/... 下面的是应用自己的产物目录和上传目录

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

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

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

更稳妥的做法通常是：

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

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

#HTTPS 怎么处理

如果你已经决定继续用 Nginx，那么 HTTPS 也可以继续在 Nginx 里配。常见做法是把 listen 80 扩成 80/443 双入口，再补证书路径和 TLS 配置。

不过如果你只是想尽快拿到可用的 HTTPS，另外不想自己处理证书申请和续期，那么直接改用 Caddy 会更省心。

#常见说明

• nb proxy nginx generate 适用于 nb init 安装的应用
• 如果你后续改了 app-port、app-public-path 这类会影响代理结果的配置，记得重新执行 generate

#相关链接

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