企业官网建设流程全解析

1. 项目整体设计与思路拆解

1.1 为什么选择 Vue + Node + MongoDB 这套组合

这套技术栈在中小型 Web 应用里出现频率极高，原因很直接：前端 Vue 负责交互体验，Node 层做业务逻辑和接口聚合，MongoDB 存业务数据。三者都是 JavaScript 生态，前后端可以共享部分工具链和类型定义，团队人手少的时候一个人能从头写到尾。

但真正把这三个东西塞进 Docker 里跑起来，和本地开发完全是两码事。本地开发时，前端npm run dev起个热更新服务，后端node app.js跑在 3000 端口，数据库直接连本机localhost:27017，一切都很自然。一旦容器化，网络隔离、端口映射、数据持久化、镜像体积、启动顺序这些问题会集中爆发。

我见过太多人第一次 Docker 化时踩的坑：前端构建产物里写死了localhost:3000，容器里根本连不上后端；MongoDB 容器重启后数据全丢；Node 容器启动时数据库还没就绪直接崩溃退出。这些问题不是 Docker 本身的缺陷，而是对容器网络和生命周期理解不到位导致的。

1.2 容器编排方案选型：单容器 vs Docker Compose

有人会问，为什么不把三个服务打包进一个容器？技术上可行，但违背了容器“一个进程一个容器”的基本原则。把 Vue 构建产物、Node 运行时、MongoDB 塞进同一个镜像，会导致镜像体积臃肿、日志混杂、无法独立扩缩容，任何一个组件升级都要重新构建整个镜像。

所以标准做法是用Docker Compose编排三个独立容器：

Compose 帮我们解决了三件事：自定义网络让容器间用服务名互相访问、depends_on控制启动顺序、volumes做数据持久化。这套方案在单机部署场景下足够用，迁移到多机时再考虑更重的编排工具也不迟。

1.3 网络通信的核心逻辑

容器间的通信靠的是 Docker 自定义 bridge 网络。Compose 默认会创建一个网络，所有服务加入后可以用服务名当主机名互相解析。也就是说，Node 容器里连数据库不需要写 IP，直接写mongodb://mongo:27017/mydb就行，mongo就是 Compose 里定义的服务名。

前端这边有个关键点：Vue 打包后的静态文件是纯浏览器端执行的，浏览器不认识 Docker 内部的服务名。所以前端不能直接请求http://backend:3000，必须走 Nginx 反向代理，让浏览器请求同源的/api路径，Nginx 再转发到后端容器。这个设计同时解决了跨域问题，一举两得。

注意：前端代码里所有 API 地址必须用相对路径（如/api/users），绝对不能在构建时写死容器名或 IP，否则浏览器端无法解析。

2. 核心细节解析与实操要点

2.1 前端镜像的多阶段构建

Vue 项目的 Dockerfile 推荐用多阶段构建，第一阶段用 Node 镜像编译，第二阶段只把dist目录拷进 Nginx 镜像。这样最终镜像里没有node_modules、没有源码、没有构建工具，体积能从 1GB 压到 30MB 左右。

# 阶段一：构建 FROM node:18-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci --registry=https://registry.npmmirror.com COPY . . RUN npm run build # 阶段二：运行 FROM nginx:alpine COPY --from=builder /app/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80 CMD ["nginx", "-g", "daemon off;"]

这里有几个细节值得说。npm ci比npm install更适合 CI/CD 场景，它严格按照package-lock.json安装，保证每次构建依赖版本一致。先 COPYpackage*.json再 COPY 源码，是为了利用 Docker 层缓存——只要依赖没变，重新构建时这层直接复用，省掉几分钟的安装时间。

2.2 Nginx 反向代理配置

Nginx 的配置文件是整个前端容器的灵魂，它要同时处理静态资源托管和 API 转发两件事：

server { listen 80; server_name _; root /usr/share/nginx/html; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://backend:3000/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }

try_files那行是给 Vue Router 的 history 模式用的。用户直接访问/user/profile这种前端路由时，Nginx 找不到对应文件会返回 404，加上这行后统一回退到index.html，由前端路由接管。

proxy_pass末尾的斜杠很关键。写成http://backend:3000/时，请求/api/users会被转发成http://backend:3000/users，/api前缀被剥掉。如果后端路由本身就带/api前缀，那proxy_pass后面就不要加斜杠。这个细节搞错会导致 404，排查起来很费时间。

2.3 后端镜像的构建与优化

Node 后端的 Dockerfile 相对简单，但生产环境要注意用--production只装运行时依赖：

FROM node:18-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --production --registry=https://registry.npmmirror.com COPY . . EXPOSE 3000 CMD ["node", "server.js"]

用node:18-alpine而不是node:18，镜像体积能小一半以上。Alpine 用的是 musl libc，极少数依赖原生模块的包可能编译不过，但纯 JS 项目完全没问题。如果遇到bcrypt、sharp这类含原生代码的包报错，换成node:18-slim即可。

后端连接数据库的地址必须从环境变量读取，不能硬编码：

const mongoUri = process.env.MONGO_URI || 'mongodb://mongo:27017/mydb'; mongoose.connect(mongoUri);

这样本地开发时用localhost，容器里用服务名mongo，同一份代码两种环境都能跑。

2.4 MongoDB 数据持久化

MongoDB 容器最大的坑就是数据丢失。容器删除后，容器内的文件系统随之消失，数据库文件自然也没了。必须用 volume 把数据目录挂载到宿主机：

volumes: - mongo-data:/data/db

/data/db是 MongoDB 默认的数据存储路径。用命名 volume（mongo-data）比用宿主机目录绑定更省心，Docker 会自动管理存储位置和权限，避免宿主机目录权限不对导致容器启动失败。

提示：生产环境务必给 MongoDB 设置认证。默认的 mongo 镜像不开启认证，任何能访问到 27017 端口的人都能读写数据。通过MONGO_INITDB_ROOT_USERNAME和MONGO_INITDB_ROOT_PASSWORD环境变量可以初始化管理员账号。

3. 实操过程与核心环节实现

3.1 项目目录结构规划

动手之前先把目录结构定好，三个服务各占一个子目录，Compose 文件放在根目录：

project/ ├── docker-compose.yml ├── frontend/ │ ├── Dockerfile │ ├── nginx.conf │ ├── package.json │ └── src/ ├── backend/ │ ├── Dockerfile │ ├── package.json │ └── server.js └── .env

这种结构清晰，每个服务的构建上下文独立，不会出现前端构建时把后端node_modules也拷进去的尴尬情况。

3.2 docker-compose.yml 完整配置

这是整个部署的核心文件，我把它拆开逐段说明：

version: '3.8' services: mongo: image: mongo:6 restart: unless-stopped environment: MONGO_INITDB_ROOT_USERNAME: admin MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD} volumes: - mongo-data:/data/db networks: - app-net backend: build: ./backend restart: unless-stopped environment: MONGO_URI: mongodb://admin:${MONGO_PASSWORD}@mongo:27017/mydb?authSource=admin NODE_ENV: production depends_on: - mongo networks: - app-net frontend: build: ./frontend restart: unless-stopped ports: - "80:80" depends_on: - backend networks: - app-net volumes: mongo-data: networks: app-net: driver: bridge

几个关键点展开说。restart: unless-stopped保证容器异常退出后自动重启，服务器重启后服务也能自动拉起。depends_on只控制启动顺序，不保证依赖服务已经“就绪”——MongoDB 启动到能接受连接有几秒延迟，Node 如果启动太快会连接失败。后面会讲怎么处理这个问题。

MONGO_PASSWORD从.env文件读取，不写死在 Compose 文件里，避免密码进版本库。.env文件要加进.gitignore。

3.3 启动顺序与健康检查

前面提到的启动顺序问题，标准解法是给 MongoDB 加健康检查，让 backend 等 mongo 真正就绪后再启动：

mongo: # ... 其他配置 healthcheck: test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"] interval: 10s timeout: 5s retries: 5 start_period: 20s backend: # ... 其他配置 depends_on: mongo: condition: service_healthy

start_period给 MongoDB 留出初始化时间，这段时间内的健康检查失败不计入重试次数。condition: service_healthy让 backend 等到 mongo 健康检查通过后才启动，从根本上避免连接失败。

如果不想用健康检查，也可以在 Node 代码里做重试逻辑，用mongoose.connect的serverSelectionTimeoutMS配合循环重试。但健康检查是更干净的做法，把启动顺序的控制权交给编排工具。

3.4 构建与启动的完整命令

配置写好后，启动流程就三条命令：

# 构建所有镜像 docker compose build # 后台启动所有服务 docker compose up -d # 查看服务状态 docker compose ps

第一次构建会下载基础镜像和依赖，视网络情况需要几分钟。构建完成后docker compose ps应该看到三个容器都是Up状态。前端容器的PORTS列会显示0.0.0.0:80->80/tcp，说明端口映射成功。

验证部署是否成功，按这个顺序排查：先docker compose logs mongo看数据库有没有正常启动，再docker compose logs backend看 Node 有没有连上数据库，最后浏览器访问服务器 IP 看前端页面能不能加载。如果页面能打开但接口报错，多半是 Nginx 代理配置或后端路由的问题。

3.5 环境变量与配置分离

生产环境和开发环境的配置差异，全部通过环境变量注入，代码里不出现任何硬编码。后端需要的环境变量：

前端这边，Vue CLI 或 Vite 在构建时会把VITE_开头的环境变量注入代码。但要注意，前端环境变量是构建时生效的，不是运行时。也就是说，改了.env后必须重新docker compose build frontend才生效。这也是为什么推荐前端 API 地址用相对路径/api，这样根本不需要环境变量区分环境。

4. 常见问题与排查技巧实录

4.1 容器启动失败排查速查表

4.2 后端监听地址的隐藏坑

Node 服务默认可能监听127.0.0.1，在容器里这意味着只接受容器内部的连接，Nginx 从另一个容器发来的请求会被拒绝。必须显式监听0.0.0.0：

app.listen(3000, '0.0.0.0', () => { console.log('Server running on port 3000'); });

这个问题在本地开发时完全不会暴露，因为本地 Nginx 和 Node 都在同一台机器上，127.0.0.1能通。一进容器就 502，很多人会误以为是 Nginx 配置问题，其实是后端监听地址的锅。

4.3 镜像体积优化实战

第一次构建出来的镜像往往大得离谱，我记录过一次优化前后的对比：

前端优化效果最明显，因为构建工具和源码全被隔离在 builder 阶段。后端用--production能去掉 devDependencies，但如果项目里有nodemon、eslint这类开发依赖，效果会很明显。

提示：用docker images查看镜像体积，用docker history <镜像名>查看每一层的大小，找出体积异常的层针对性优化。

4.4 日志查看与调试技巧

容器化后不能直接看控制台输出，得用日志命令：

# 查看所有服务日志 docker compose logs -f # 只看后端日志 docker compose logs -f backend # 进入容器内部调试 docker compose exec backend sh # 在容器内测试网络连通性 docker compose exec backend ping mongo

docker compose exec进容器调试是排查问题的利器。比如怀疑后端连不上数据库，进 backend 容器执行ping mongo看网络通不通，用nc -zv mongo 27017看端口通不通，逐步缩小问题范围。

4.5 数据备份与恢复

MongoDB 数据虽然在 volume 里，但 volume 本身也可能因为误操作被删除。定期备份是必须的：

# 备份 docker compose exec mongo mongodump --username admin --password 密码 --authenticationDatabase admin --out /tmp/backup docker compose cp mongo:/tmp/backup ./backup # 恢复 docker compose cp ./backup mongo:/tmp/backup docker compose exec mongo mongorestore --username admin --password 密码 --authenticationDatabase admin /tmp/backup

备份文件一定要拷出容器存到宿主机或其他存储上，只留在容器里等于没备份。

4.6 生产环境的安全加固

开发环境跑通不代表能直接上生产。几个必须做的安全措施：MongoDB 端口不要映射到宿主机，只在 Docker 内网暴露；Nginx 加上安全响应头；Node 服务用非 root 用户运行；敏感配置全部走环境变量。

Nginx 安全头配置：

add_header X-Content-Type-Options nosniff; add_header X-Frame-Options SAMEORIGIN; add_header X-XSS-Protection "1; mode=block";

Node 容器用非 root 用户：

RUN addgroup -S appgroup && adduser -S appuser -G appgroup USER appuser

这些措施单独看都不复杂，但组合起来能挡掉大部分常见的自动化扫描攻击。

4.7 我踩过的几个真实坑

第一个坑是前端构建时的 API 地址。早期我在 Vue 代码里写了axios.defaults.baseURL = 'http://localhost:3000'，本地开发没问题，打包进容器后浏览器请求的是用户自己电脑的 3000 端口，当然连不上。改成/api走 Nginx 代理后彻底解决。

第二个坑是 MongoDB 认证。加了MONGO_INITDB_ROOT_USERNAME后，连接字符串必须带authSource=admin，否则认证会失败。这个参数很容易漏，报错信息也不直观，排查了好一阵。

第三个坑是 volume 权限。有次用宿主机目录绑定挂载，MongoDB 容器启动时报权限错误。原因是容器内 MongoDB 以特定 UID 运行，宿主机目录属主不匹配。换成命名 volume 后问题消失，Docker 会自动处理权限。

第四个坑是构建缓存失效。改了前端源码后重新构建，发现依赖又重新安装了一遍。原因是COPY . .这行把源码和package.json一起拷了，源码一变这层缓存就失效。把COPY package*.json单独提前后，依赖层缓存稳定复用，构建时间从 3 分钟降到 20 秒。

这套部署方案我在几个中小型项目里反复用过，稳定性和可维护性都经得起考验。真正花时间的不是写配置文件，而是理解容器间的网络关系和数据流向。把这三个容器的通信链路在脑子里画清楚，遇到问题基本都能定位到具体环节。