NocoBase nb proxy 反向代理命令组详解Nginx 与 Caddy Provider 的生成、运行与排查【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobasenb proxy是 NocoBase CLI 中反向代理相关命令的统一入口负责为 CLI 托管的 envlocal或docker两种运行形态生成并管理 Nginx 或 Caddy 站点入口。读完本篇你将掌握 provider 与 driver 的选择逻辑、generate/start/reload等子命令的完整工作流并能从源码层面理解 CLI 如何安全地改写宿主机主配置、渲染路由规则以及在验证失败时回滚。nb proxy 的定位env 与入口层解耦在 NocoBase CLI 的设计中“env 配置”和“入口层管理”被刻意拆开了nb env负责保存和维护应用 env端口、路径、版本等运行参数nb proxy负责为这些 CLI 托管 env 生成并管理 Nginx 或 Caddy 入口只要应用已经保存成 CLI 托管 env并且这个 env 属于local或docker通常直接选择一个 provider 子命令就够了。nb proxy自身不携带任何 flags直接执行nb proxy只会打印帮助信息——这在源码中可以确认proxy 命令入口 的run()只做了两件事解析空参数、调用 oclif 的Help.showHelp([proxy, ...argv])。用法与完整命令树nb proxy provider command两个 providernginx与caddy的子命令完全对称nb proxy nginx use local|docker nb proxy nginx current nb proxy nginx generate --env name [--host domain] [--port port] nb proxy nginx start nb proxy nginx restart nb proxy nginx reload nb proxy nginx stop nb proxy nginx status nb proxy nginx info nb proxy caddy use local|docker nb proxy caddy current nb proxy caddy generate --env name [--host domain] [--port port] nb proxy caddy start nb proxy caddy restart nb proxy caddy reload nb proxy caddy stop nb proxy caddy status nb proxy caddy info各子命令的独立参考文档位于 nginx 命令组 与 caddy 命令组。如何选 Provider我想要……去哪里看沿用 Nginx 管理站点、证书、缓存或访问控制nb proxy nginx尽快把 HTTPS 跑通少维护一点 TLS 细节nb proxy caddy先调整可能影响代理结果的 env 配置比如app-port、app-public-pathnb env update从源码结构看provider 的选择贯穿整个渲染管线env-proxy.ts 中通过resolveProxyProviderName解析 provider未指定时回落到DEFAULT_PROXY_PROVIDER再由同一套渲染状态分支输出 Nginx 的location模板或 Caddy 的handle模板——两者的路由语义上传目录直读、dist 静态加速、API/WebSocket 回源、SPA fallback是一致的只是配置语法不同。子命令行为一览命令作用use切换当前 provider 默认使用的 drivercurrent输出当前 provider 的 driver例如local或dockergenerate生成或刷新指定 env 的代理入口文件start按当前 driver 启动代理reload在不停止服务的情况下重载配置restart先停止再启动stop停止代理status查看运行状态info查看 driver、配置文件路径、运行根路径、回源主机等信息需要记住的关键规则nb proxy自己没有独立 flags实际生成和管理入口时使用nb proxy nginx或nb proxy caddy两个 provider 都只适用于当前机器上可访问运行态的托管 env也就是local或docker两个 provider 都支持两类 driverlocal和dockeruse会写入默认 drivercurrent会直接输出当前 drivergenerate负责生成或刷新入口配置文件不会自动启动代理进程start、restart、reload、stop、status、info都基于当前 provider 的当前 driver 工作如果你用nb env update修改了app-port、app-public-path这类会影响入口路径、资源地址或回源结果的配置改完后通常还要重新执行对应的generate如果一个 env 只有远程 API 连接或者是 SSH env那么这组命令暂时不能用典型流程Nginx 流程# 1. 选择 provider 和运行方式 nb proxy nginx use docker # 2. 为某个 CLI 托管 env 生成入口配置 nb proxy nginx generate --env app1 --host app1.example.com # 3. 启动代理 nb proxy nginx start # 4. 查看当前状态和路径信息 nb proxy nginx status nb proxy nginx info # 5. 配置更新后重载 nb proxy nginx reload如果你选择的是 Caddy把命令中的nginx替换成caddy即可# 为指定 env 生成 Nginx 配置并启动 nb proxy nginx use docker nb proxy nginx generate --env demo --host demo.local.nocobase.com nb proxy nginx start # 为指定 env 生成 Caddy 配置并启动 nb proxy caddy use local nb proxy caddy generate --env demo --host demo.local.nocobase.com nb proxy caddy startDriver 选择local 与 docker 的差异use命令把 driver 持久化到 CLI 配置中。以 Nginx 为例use 命令实现 校验参数必须落在NGINX_PROXY_DRIVER_OPTIONS即local/docker之内然后调用setNginxProxyDriver写入配置键proxy.nginx-driverCaddy 对应proxy.caddy-drivercurrent则读取该键缺省时回落到默认值local见 getNginxProxyDriver。两种 driver 的实际行为差异在 proxy-nginx.ts 中定义得很清楚维度local driverdocker driver可执行文件 / 镜像bin.nginx配置指向的可执行文件默认nginxnginx:latest镜像容器名不适用docker.container-prefix-nginx-proxy回源主机127.0.0.1host.docker.internal通过--add-host host.docker.internal:host-gateway注入运行根路径宿主机 CLI 根目录NB_CLI_ROOT容器内/apps宿主机NB_CLI_ROOT挂载而来运行态检测从nginx -V解析--pid-path读 PID 文件并用kill(pid, 0)探活检查容器是否在运行回源主机的区分见 resolveNginxProxyUpstreamHost它决定了生成配置中proxy_pass的目标主机是理解 local/docker 两种形态下回源路径差异的关键。Docker driver 启动容器时的完整参数可参考 ensureDockerNginxProxyContainer默认发布 80、443 端口并自动并入各 env 代理配置中出现的自定义端口将宿主机 CLI 根目录挂载到容器/apps再把主配置文件只读挂载到/etc/nginx/conf.d/default.conf。generate 的生成机制从 env 到入口文件generate是整组命令中最重的一个。从 env-proxy.ts 的实现看它的流程可以概括为四步1. 读取 env 运行参数并计算路径loadEnvProxySettings从托管 env 中读取一组带默认值的路径参数见 env-proxy.ts#L31-L38参数默认值说明APP_PUBLIC_PATH/应用根路径决定整个站点的挂载前缀API_BASE_PATH/api/API 前缀会拼接到APP_PUBLIC_PATH之后WS_PATH/wsWebSocket 入口路径PLUGIN_STATICS_PATH/static/plugins/插件静态资源路径APP_MODERN_CLIENT_PREFIXv现代客户端v2路径前缀最终 v2 路径为appPublicPathv/CDN_BASE_URL按appPublicPath 版本推导静态资源 CDN 前缀这里还有一个硬性前置条件env 必须已经设置app-port。resolveRuntimeNginxBundleSource中如果没有端口会直接报错“Missing appPort for env ... Save or update the app port before generating proxy config”这也是文档中“改完app-port后要重新generate”的底层原因——回源地址http://upstreamHost:appPort完全由它推导。2. 渲染各层配置文件两个 provider 的文件布局是固定的ENV_PROXY_FILE_SPECS文件nginxcaddy作用应用入口配置app.confapp.caddy每个 env 一份包含listen/站点地址 托管配置块生成路由generated.confgenerated.caddyCLI 全权管理的路由规则主配置nocobase.confnocobase.caddy汇总所有 env被宿主主配置 include/import生成的 Nginx 路由块覆盖了几类典型流量上传目录storage/uploads/直接 alias 到本地 uploads 目录并带文件鉴权子请求、dist/静态资源 alias 到前端构建产物、.well-knownOAuth/OpenID 端点重写后回源、API 前缀回源proxy_http_version 1.1、600 秒超时、WebSocket 路径带Upgrade头回源、以及两条 SPA fallbackv2 前缀回退index-v2.html应用根回退index-v1.html。除配置外generate还会从前端构建产物读取当前活跃版本的index.html注入一段运行配置脚本__nocobase_public_path__、__nocobase_api_base_url__、__nocobase_ws_url__等全局变量并重写其中的资源前缀最终写出public/index-v1.html与public/index-v2.html。这解释了为什么代理入口能正确地把 CDN 前缀、API 地址下发给浏览器。3. 托管块标记CLI 只改自己标记的区域为避免和用户手写的配置冲突CLI 用成对标记圈定自己的领地env-proxy.ts#L40-L45# BEGIN NocoBase proxy/# END NocoBase proxy宿主主配置nginx 主配置的 http 块、Caddyfile 末尾里 include/import 行所在的块# BEGIN NocoBase managed config/# END NocoBase managed configapp 配置里 CLI 渲染的路由块# BEGIN NocoBase generated routes/# END NocoBase generated routes引用generated.*文件的块再次generate时CLI 只会替换标记之间的内容replaceManagedNginxConfigBlock等函数标记之外的定制比如你手加的限流、缓存规则会被保留如果 app 配置文件被手动删掉了托管块generate会拒绝覆盖并提示恢复托管块或删除文件重新生成见 writeResolvedNginxProxyBundle。4. 注入宿主主配置Nginx 的主配置路径通过执行nginx -V解析--conf-path得到Caddy 则优先读CADDY_CONFIG环境变量否则依次尝试/etc/caddy/Caddyfile、/usr/local/etc/Caddyfile、/opt/homebrew/etc/Caddyfile等常见位置resolveCaddyMainConfigPath。CLI 会把 include/import 行插入 http 块末尾或 Caddyfile 末尾如果配置里已有托管块则原位替换。start / reload 的校验与回滚机制start不只是启动进程它的执行链是写出主配置 → 把 include/import 注入宿主主配置 → 校验 → 启动。校验环节validateEnvProxyProvider对 Nginx 执行nginx -t对 Caddy 执行caddy validate --adapter caddyfile --config path一旦校验失败CLI 会把被修改的主配置恢复为注入前的原始内容再抛出错误installEnvProxyProvider避免把宿主机代理改坏。reload的语义是“先校验再热重载”Nginx local 形态执行nginx -s reloadCaddy 执行caddy reload --adapter caddyfile --config pathDocker 形态则通过docker exec container nginx -s reload在容器内重载若代理当前没有运行reload会退化为直接启动reloadNginxProxy 及相关分支。status输出的字段driver、运行状态、主配置文件路径、运行根路径、回源主机、容器名/镜像或 nginx 可执行文件路径与info的输出结构一致对应 formatNginxProxyInfoLines。命令行为的正确性还有测试用例兜底proxy-nginx-command.test.ts 与 proxy-caddy-command.test.ts 覆盖了命令解析与执行路径。边界与注意事项适用前提local/docker形态的托管 env仅有远程 API 连接或 SSH 形态的 env 暂不支持这组命令改配置后必须重新 generateapp-port、app-public-path等变更不会自动反映到入口文件generate才是刷新的唯一入口generate本身不启动进程driver 是 per-provider 的nginx与caddy各自保存 driverproxy.nginx-driver/proxy.caddy-driver切换一个不影响另一个端口参数有校验--port必须是 165535 的整数否则按缺省处理Nginx 入口默认listen 80见 resolveAppEntryPort--host会改写server_nameNginx或站点地址Caddy只改 host 不动 port 时会保留原有非 80 端口local 形态依赖宿主机代理可用local driver 直接调用宿主机上的nginx/caddy可执行文件并修改其主配置因此要确保本机代理可执行且主配置结构可被解析Nginx 需要存在http { ... }块相关命令nb proxy nginxnb proxy caddynb env updatenb env infonb config【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考