高级 NGINX 配置
-
CapRover 允许在服务器设置中修改 NGINX 基础配置和 dashboard 路由模板,也可以从应用的 HTTP 设置修改对应应用的 NGINX 模板。
-
如果只有单个应用需要调整超时、大小限制或路由规则,优先使用应用级配置。
-
/captain/generated/nginx下的文件反映了最终生成的配置,但 CapRover 可能覆盖它们。 -
请通过 dashboard 中对应的模板保存修改。
-
宿主机目录
/captain/data/nginx-shared会以/nginx-shared路径挂载到 NGINX 容器中,可用于共享自定义证书等文件。 -
如果希望对新创建的应用使用默认模板,可以让 CapRover 从
/captain/data/server-block-conf-override.ejs加载覆盖文件。 -
以对应的源码模板为基础,先备份,写入 override 后重启 CapRover service。
-
在测试应用上验证配置后再广泛使用。
-
无效的全局模板可能影响 dashboard 和多个应用。
NGINX 配置错误导致 dashboard 无法打开时
- 如果自定义 NGINX 配置导致 dashboard 无法访问,先备份
/captain/data/config-captain.json和任何/captain/data/server-block-conf-override.ejs文件。 - 如果是后一个文件导致故障,先将它移出该目录,再重启 CapRover。
- 如果仍无法恢复,下面的操作会清除 NGINX 基础配置、dashboard 配置及所有应用的自定义 NGINX 配置。务必保留原始备份,以便之后逐项恢复。
- 在已安装
jq的 manager 节点执行:
sudo cp -a /captain/data/config-captain.json /captain/data/config-captain.json.before-nginx-reset
sudo jq '.nginxBaseConfig = "" | .nginxCaptainConfig = "" | .appDefinitions |= with_entries(.value.customNginxConfig = "")' \
/captain/data/config-captain.json | sudo tee /captain/data/config-captain.json.new >/dev/null
sudo jq empty /captain/data/config-captain.json.new
sudo docker service scale captain-captain=0
sudo install -m 600 /captain/data/config-captain.json.new /captain/data/config-captain.json
sudo docker service scale captain-captain=1
- 等待
docker service ps captain-captain和docker service ps captain-nginx显示正常运行的任务。 - 如果问题仍然存在,请查看日志并恢复备份,避免继续修改扩大影响。
NGINX 请求路由
-
对公网 Web 请求,DNS 首先将 hostname 指向 CapRover 服务器。
-
CapRover NGINX 接收 80 或 443 端口的流量,根据 hostname 选择 dashboard 或应用域名,再转发到应用 Docker service 的 HTTP 容器端口。
-
部署成功后仍出现 502,通常意味着 NGINX 无法通过对应端口访问健康的容器。
-
确认应用监听
0.0.0.0、Container HTTP Port 设置正确,且 Docker service 任务正常运行。 -
DNS 故障发生在请求到达该路由之前;证书错误可能在 HTTPS 流量到达应用前出现。
应用专用 NGINX 配置应在其 Custom NGINX 设置中调整。全局模板影响更多路由,请谨慎使用高级 NGINX 配置。
Custom NGINX
- CapRover 为每个 Web 应用生成 NGINX 配置。
- 如果需要针对某个应用调整 timeout、上传大小限制等高级行为,可以在 HTTP Settings 中编辑对应模板。
- 编辑前先备份当前模板。
- 只修改必要的指令,并通过 dashboard 保存。
- 验证 NGINX 配置已被接受,然后测试应用关联的全部域名是否都能通过 HTTP 和 HTTPS 访问。同一应用的模板会影响其所有域名。
- 错误的配置可能导致请求路由中断。
- CapRover 会尝试校验并回退无效配置,但仍应保存最后一份可用的模板。
/captain/generated/nginx下的文件是生成结果,CapRover 可能随时覆盖,不应直接编辑。
如果必须修改全局 NGINX 或 dashboard 模板,参阅高级 NGINX 配置。只有应用级模板无法满足需求时,才使用全局配置。