企业官网建设流程全解析

• 后端
• 前端
• 运维
• MCP 服务

导读

本文基于 Nginx UI 仓库的 docs/guide/devcontainer.md 与 .devcontainer 目录下的真实配置，完整讲解如何通过 Visual Studio Code（或 Cursor）的 Dev Containers 能力，在 Docker 中一键拉起 Nginx UI 的完整开发环境。你将掌握从打开容器、启动全部服务，到使用内置的 ACME 测试服务器（Pebble）、Casdoor 认证、多节点集群联调的整套实操方法，为后续开发前端、后端或参与 Cluster 功能贡献代码提供可直接落地的环境基线。

为什么 Nginx UI 需要专门的开发容器

Nginx UI 是一个前后端一体的 Web 管理界面，后端为 Go 语言（API 服务），前端为 Vue 3 + Vite 的 Web 应用，同时还深度依赖 nginx 本身以及证书签发（ACME）、DNS、集群同步等外围组件。在本机直接开发时，需要同时满足 Go 工具链、Node.js/Bun 运行时、nginx 及其大量扩展模块、Pebble 测试 CA、Casdoor 单点登录服务等多项依赖，环境搭建成本高且容易互相污染。

为此仓库在根目录提供了完整的 Devcontainer 定义（.devcontainer/devcontainer.json、.devcontainer/docker-compose.yml、.devcontainer/Dockerfile），把上述所有依赖封装进一个可复现的容器编排中。开发者只需本机装有 Docker、VSCode（或 Cursor）与 Git，即可获得与 CI 一致、可随时销毁重建的开发环境。

从 devcontainer.json 可以看到容器内置的关键运行时：

• common-utils（含 Oh My Zsh）；
• Node.js（用于前端工具链）；
• Bun1.3.14（Nginx UI 前端包管理与构建脚本统一使用 Bun，见 app/package.json 中的bun test、bun ci等脚本）。

后端 Go 工具链则在 .devcontainer/Dockerfile 中通过golang.org/dl/?mode=json自动获取最新稳定版 Go 并按amd64/arm64架构下载安装，同时设置了PATH包含 Go 与go install二进制目录，并显式声明NGINX_UI_WORKING_DIR=/var/run/作为运行工作目录。

环境前提与初始化步骤

1. 前置要求

2. 一键启动开发容器

按 docs/guide/devcontainer.md 的步骤操作：

1. 打开 VSCode（或 Cursor）命令面板：
   • Mac：Cmd+Shift+P
   • Windows：Ctrl+Shift+P
2. 搜索并点击Dev Containers: Rebuild and Reopen in Container
3. 等待容器构建并启动完成
4. 再次打开命令面板，选择Tasks: Run Task→Start all services
5. 等待所有服务就绪

容器启动过程由 devcontainer.json 中的postStartCommand触发 .devcontainer/start.sh，该脚本会自动完成：

• 为 Git 配置 SSH 签名（gpg.format ssh+commit.gpgsign true），便于在容器内直接以 SSH key 提交；
• 安装热重载工具air（go install github.com/air-verse/air@latest）；
• 安装并启用zsh-autosuggestions插件；
• 调用 .devcontainer/init-nginx.sh 初始化 nginx 配置目录；
• 执行bun ci安装前端 workspace 依赖。

此外 devcontainer.json 会把宿主机的~/.ssh以 bind mount 方式挂载进容器/root/.ssh，保证容器内可以直接复用宿主机 SSH 密钥；remoteUser为root，方便在容器内执行系统级操作。

3. nginx 初始化与扩展模块

.devcontainer/init-nginx.sh 承担 nginx 环境的初始化：

• 首次启动时把镜像内保存的原始配置/etc/nginx.orig（见 .devcontainer/Dockerfile 的cp -rp /etc/nginx /etc/nginx.orig）复制到挂载卷/etc/nginx，避免宿主数据目录为空导致 nginx 无法启动；
• 遍历modules-available中的 20 余个扩展模块配置，按权重（10/50/70）在modules-enabled下创建符号链接，涵盖mod-http-ndk、mod-http-lua、mod-http-geoip2、mod-stream、mod-mail、mod-nchan等，为 Nginx UI 的站点/流/日志分析等功能提供完整的模块能力；
• 最后直接前台启动nginx。

这套设计使容器内 nginx 尽可能接近生产发行版的能力集合，避免开发时遇到“本地可以、容器不行”的模块缺失问题。

端口与服务拓扑

端口映射

其中前端开发服务器端口在 app/vite.config.ts 中定义：默认监听3002，并将/api请求（含 WebSocket）代理到后端地址（默认http://localhost:9001，可通过环境变量VITE_PROXY_TARGET覆盖），同时保持浏览器 Origin 头以保证 WebSocket 鉴权在前后端端口不同时仍能正常工作。因此开发时前端访问3002、后端调试可关注对应代理目标端口。

容器编排中的服务

docs/guide/devcontainer.md 列出的核心服务，对应 .devcontainer/docker-compose.yml 中的编排定义：

主节点通过环境变量NGINX_UI_CERT_CA_DIR=https://pebble:14000/dir（见 .devcontainer/docker-compose.yml）把 Nginx UI 的证书签发 CA 指向容器内的 Pebble 测试实例，配合PEBBLE_VA_NOSLEEP=1、PEBBLE_VA_ALWAYS_VALID=1等环境变量（.devcontainer/docker-compose.yml），可以在毫秒级完成证书签发测试而无需等待真实 CA 校验。Pebble 的测试证书与配置位于 .devcontainer/pebble-test 目录（含pebble-config.json、pebble-config-external-account-bindings.json及本地 CA 证书）。

主节点还设置了NGINX_UI_DEV_SECURE_SESSION_MINUTES=1440，该变量对应后端 internal/user/secure_session_dev.go 中的SecureSessionDurationEnv，用于在开发模式下延长安全会话有效期，避免频繁登录打断调试。

多节点集群开发

Nginx UI 支持以 Cluster 模式管理多台主机的 nginx。Devcontainer 已为此内置了nginx-ui-2（以及编排文件中的nginx-ui-3）节点，实现“一个 Compose 内模拟多主机”的联调环境。

按 docs/guide/devcontainer.md 的说明，在主节点中添加以下环境信息即可把第二节点纳入集群：

name: nginx-ui-2 url: http://nginx-ui-2 token: nginx-ui-2

三个字段分别对应节点名称、节点在 Compose 网络内的访问地址（nginx-ui自定义网络，见 .devcontainer/docker-compose.yml）以及节点鉴权 token。保存后即可在主节点的节点管理页面看到并连接nginx-ui-2。

从节点的自动重载机制

与主节点不同，nginx-ui-2/nginx-ui-3等从节点运行的是 .devcontainer/node-supervisor.sh，这是一个基于inotifywait的自研“热重载监督器”：

1. 等待/workspaces/nginx-ui/tmp/main（Go 编译产物）出现；
2. 将可执行文件复制到/usr/local/bin/nginx-ui并以-config /etc/nginx-ui/app.ini启动；
3. 持续监听tmp目录的close_write/moved_to/create/delete事件，兼容原子保存产生的*-tmp-umask中间文件；
4. 对编译产物做“可执行文件”稳定性校验（最多重试 5 次），确认有效后复制、杀掉旧进程并重启新进程。

这意味着从节点可以随主节点代码改动自动更新二进制并重启，无需手动进入每个容器操作，多节点集群调试与单机开发几乎同样流畅。该机制与仓库内 Cluster 同步、节点鉴权等能力（对应 internal/clustersync 与 internal/nodeauth 等目录）配合，覆盖从“开发环境自举”到“配置下发”的完整链路。

开发过程中的常用验证路径

• 前端：修改app/src下代码后，Vite HMR 会自动生效，浏览器访问3002即可看到实时效果；bun test、bun run typecheck、bun run lint分别对应测试、类型检查与代码规范校验（见 app/package.json）。
• 后端：air负责 Go 代码热重载，主节点后端变更会即时重建；从节点由node-supervisor.sh监听tmp/main自动滚动更新。
• 证书签发：在证书管理页面申请证书时，签发请求会打到容器内 Pebble（https://pebble:14000/dir），由于PEBBLE_VA_ALWAYS_VALID=1，校验结果恒为有效，可反复验证签发/续期流程而不污染真实 CA 配额。
• 单点登录：通过casdoor服务（映射8001）验证 OIDC/Casdoor 登录集成。

常见问题与排查要点

• 首次启动较慢：容器需要拉取 Ubuntu base 镜像、下载 Go 最新稳定版并执行bun ci，属正常现象；依赖已通过go-modules命名卷（.devcontainer/docker-compose.yml）与工作区缓存复用，重建后明显加快。
• 端口冲突：3002/3003/9000/14000/15000/8001/8055等端口若与本机服务冲突，可调整 .devcontainer/docker-compose.yml 中的ports映射后重新Rebuild and Reopen in Container。
• nginx 配置目录为空：删除本地data/nginx数据目录后重建，init-nginx.sh 会从/etc/nginx.orig重新初始化。
• SSH 无法提交：确认宿主机~/.ssh存在且包含id_ed25519.pub（start.sh 中的 Git 签名配置依赖该公钥）。

结语

通过 .devcontainer 提供的容器化方案，Nginx UI 把“Go + Vue + Bun + nginx + Pebble + Casdoor + 多节点”这一复杂开发矩阵收敛为两次命令面板操作。无论你是初次接触该项目的新贡献者，还是需要验证集群同步、ACME 签发等深层能力的资深开发者，都可以基于本文所述的环境基线快速进入开发状态，并把精力集中在 app/src（前端）与 internal（后端）的实际业务代码上。

• 后端
• 前端
• 运维
• MCP 服务