Docker部署Node.js应用教程

Docker

类型：虚拟化技术

简介：基于操作系统层级的虚拟化技术，将软件与其依赖项打包为容器。

Docker部署Node.js应用是站长在内容建设、工具选型或服务器运维中经常遇到的具体问题。处理这类问题时，关键不是套用固定答案，而是先明确使用场景、风险边界和验证方法，再把配置、排查或选择步骤落实到可检查的动作上。

一、部署前确认Node.js应用运行方式

Docker部署Node.js应用应同时处理镜像构建、依赖安装、环境变量、端口映射、日志和反向代理。部署前要先确认应用是纯后端API、静态构建产物还是带WebSocket的服务。不同类型对应的启动命令、端口、构建步骤和反向代理配置不同。不要直接把本地开发命令搬到生产环境，尤其不要在生产容器里使用热更新开发模式。

二、编写Dockerfile时控制镜像体积

Node.js项目常用多阶段构建。

第一阶段安装依赖并构建，第二阶段只复制运行所需文件和生产依赖。

这样可以减少镜像体积，也降低泄露源码和临时文件的风险。依赖安装建议使用锁文件，确保构建结果稳定。镜像中不要写入.env、密钥、测试数据和本地缓存。

三、环境变量和端口要分清楚

容器内应用监听的端口和宿主机映射端口是两回事。应用通常监听0.0.0.0和内部端口，例如3000；Compose再把它映射到宿主机或只暴露给反向代理。数据库地址、Redis地址、API密钥和运行模式应通过环境变量注入。敏感变量不要提交到公开仓库，可以使用服务器环境文件、CI/CD密钥或面板变量。

四、反向代理上线要检查HTTPS和WebSocket

如果通过Nginx、Caddy或面板反向代理访问Node.js容器，要确认域名、HTTPS证书、代理地址、Host头、X-Forwarded-For和超时设置。带WebSocket的应用还要配置Upgrade头。上线前用浏览器、curl和日志一起验证，确认静态资源、接口、登录状态和长连接都正常。

五、回滚与日志保留

部署Node.js应用时应保留上一版镜像标签，出问题可以快速回滚。日志建议输出到标准输出，由Docker统一收集；如果应用写文件日志，要挂载目录并设置轮转。发布后观察启动日志、接口错误、内存占用和重启次数。只有容器状态为Up并不代表应用可用，必须用真实页面或健康检查确认。

六、生产镜像不要依赖本地状态

Node.js应用在本地能跑，不代表容器里能跑。生产镜像应包含明确的构建步骤、锁定依赖和启动命令，不应依赖开发电脑上的node_modules、全局包或本地配置文件。构建时如果需要私有包令牌，应使用构建密钥或CI变量，避免写入镜像层。

七、静态资源和API路径要一起验证

很多Node.js应用上线后，首页能打开但静态资源404，或者接口路径被反向代理改写。验证时应打开浏览器开发者工具，检查JS、CSS、图片、API请求、登录回调和上传接口。

八、健康检查接口要轻量可靠

健康检查不宜访问复杂业务接口，也不要依赖第三方服务。可以提供一个轻量接口，检查应用进程、基础配置和必要依赖是否可用。反向代理、负载均衡和监控系统都可以使用这个接口判断服务状态。健康检查失败时，应返回明确状态码，方便自动化系统识别。

九、依赖安装阶段要关注可重复构建

Node.js生态依赖更新频繁，如果不使用锁文件，今天构建和明天构建可能得到不同依赖版本。生产镜像应使用npm ci、pnpm install –frozen-lockfile或对应包管理器的锁定安装方式。这样能减少“本地正常、服务器异常”的问题。构建失败时，也更容易定位是依赖源、锁文件还是Node版本不一致。

十、反向代理超时和上传限制

Node.js应用如果涉及文件上传、长任务或接口聚合，反向代理默认超时可能不够。上线前要测试上传大小、接口响应时间、WebSocket连接和大页面加载。代理层的client_max_body_size、proxy_read_timeout等参数要与应用需求匹配。否则用户看到的是502或504，应用日志里却未必有明显错误。