企业官网建设流程全解析

• 后端
• Web框架

Egg.js 框架为开发者提供了从本地开发到生产部署的完整链路。本文基于 site/docs/zh-CN/core/deployment.md 展开，系统讲解生产环境的构建打包、使用egg-scripts启停应用、集群启动参数与配置项，以及接入 Node.js 性能平台进行线上监控的完整方案。读完本文，你将掌握一套可直接落地执行的"一次构建、多次部署"发布流程，并能结合框架源码理解 Master/Worker 集群模型在生产环境下的行为机制。

在本地开发时，我们使用egg-bin dev来启动服务，但在部署应用时不可以这样使用。因为egg-bin dev会针对本地开发做很多处理（如热重载、调试端口等），而生产环境需要一个更加简单稳定的方式。一般从源码到运行，会分为构建和部署两步，实现一次构建、多次部署。

构建：产出可重复部署的发布包

JavaScript 语言本身不需要编译，构建过程主要是下载依赖。如果使用 TypeScript 或 Babel 支持 ES6 及以上特性，则必须构建。

一般安装依赖时，会指定NODE_ENV=production或npm install --production仅安装核心依赖。因为开发依赖包体积大，在生产环境不必要，且可能导致问题。

$ cd baseDir $ npm install --production $ tar -zcvf ../release.tgz .

构建后，将其打包为 tgz 文件。部署时解压启动即可。

增加构建环节，能实现真正的一次构建、多次部署。理论上，代码未变更时，无需重构，可用原包部署，带来诸多好处：

• 构建环境与运行环境差异，避免污染运行环境。
• 缩短发布时间，便于回滚，只需重启原包即可。

部署：框架内置集群能力，无需外部进程守护

服务器需要预装 Node.js，框架支持 Node 版本>= 14.20.0。

框架内置 egg-cluster 启动 Master 进程，Master 稳定，不需 pm2 等进程守护模块。从当前仓库的源码结构可以看到，该能力沉淀在 packages/cluster 包中，入口文件为 src/index.ts，核心的 Master 实现位于 src/master.ts。

框架同时提供 egg-scripts 支持线上运行和停止。

首先，将egg-scripts模块引入dependencies：

$ npm i egg-scripts --save

package.json添加npm scripts：

{ "scripts": { "start": "egg-scripts start --daemon", "stop": "egg-scripts stop" } }

现在，可以通过npm start和npm stop启停应用。

注意：Windows 系统下egg-scripts支持有限。

Master 进程为什么稳定

在 packages/cluster/src/master.ts 中可以看到 Master 进程的关键职责：它先 fork Agent Worker，等 Agent 就绪后再 fork 出与 CPU 核数等量的 App Worker（对应源码中once('agent-start', this.forkAppWorkers.bind(this))的逻辑）。生产模式下，Master 会对 worker 进行守护与自动重启：

• App Worker 异常退出时，Master 记录AppWorkerDiedError日志，并通过cfork的 refork 机制自动拉起新 worker。该行为只在生产模式启用，对应 src/utils/mode/impl/process/app.ts 中cfork({ refork: this.isProduction })的实现；
• 启动期 worker 失败会直接process.exit(1)，避免带病运行；
• Master 收到SIGINT/SIGQUIT/SIGTERM信号后，按EGG_APP_CLOSE_TIMEOUT（默认 5000ms）与EGG_AGENT_CLOSE_TIMEOUT（默认继承前者）优雅关闭 App Worker 与 Agent Worker，详见 src/master.ts。

生产环境判断逻辑也值得注意（src/master.ts）：当显式指定了env且不为local、unittest时即视为生产，否则回退为NODE_ENV === 'production'。

启动命令

$ egg-scripts start --port=7001 --daemon --title=egg-server-showcase

示例支持参数如下：

• --port=7001：端口号，默认读取process.env.PORT，未传递则使用内置端口7001。
• --daemon：启用后台模式，不需nohup，使用 Docker 时建议前台运行。
• --env=prod：运行环境，默认读取process.env.EGG_SERVER_ENV，未传递则使用内置prod。
• --workers=2：worker 数，默认创建与 CPU 核数等量的 app worker，利用 CPU 资源。
• --title=egg-server-showcase：便于 ps 进程时 grep，未设置默认为egg-server-${appname}。
• --framework=yadan：使用自定义框架时，配置package.json的egg.framework或指定该参数。
• --ignore-stderr：忽略启动期错误。
• --https.key：HTTPS 密钥路径。
• --https.cert：HTTPS 证书路径。

egg-cluster 的所有 Options 支持透传，如--port等。在 packages/cluster/src/utils/options.ts 中可以看到这些 Option 的解析逻辑与更多可用项：

• workers：默认取os.cpus().length（源码options.workers = os.cpus().length）；
• env：默认取process.env.EGG_SERVER_ENV；
• https：开启后默认端口变为8443，且会校验key/cert（字符串路径时还会校验文件存在）对应的文件；
• baseDir：默认为process.cwd()；
• pidFile：将 Master PID 写入指定文件，Master 退出时会自动清理（见 src/master.ts）；
• require：注入到 worker / agent 进程的模块；
• startMode：默认process，可切换为worker_threads以 worker 线程方式启动 App 与 Agent Worker，配合ports指定每个 worker 的启动端口。

注意：--workers默认由process.env.EGG_WORKERS或os.cpus().length设置，Docker 中os.cpus().length可能大于核数，值较大可能导致失败，需手动设置--workers。

启动配置项

config.{env}.js中可指定启动配置。

// config/config.default.js exports.cluster = { listen: { port: 7001, hostname: '127.0.0.1', // 不建议设置为 '0.0.0.0'，可能导致外部连接风险，请了解后使用 // path: '/var/run/egg.sock', }, };

path、port、hostname见 Node.js 官方文档server.listen参数。egg-scripts和egg.startCluster传入的 port 优先级高于此配置。

框架对cluster.listen的默认值定义在 packages/egg/src/config/config.default.ts：{ path: '', port: 7001, hostname: '', reusePort: false }。在底层 App Worker 启动时（packages/cluster/src/app_worker.ts），实际监听端口通过options.port || listenConfig.port计算得出——这正体现了"命令行参数优先于配置文件"的优先级规则。源码中的监听逻辑还包含：

• 若配置了listen.path（Unix Socket），则直接server.listen(listenConfig.path)；
• 若配置了listen.hostname，会作为监听地址传给server.listen(port, hostname)；
• reusePort（仅 Linux 3.9+ 等平台可用）会改用 options 对象方式监听，以启用SO_REUSEPORT；
• 配置了https时，clusterConfig.https与options.https会合并，用于创建 HTTPS 服务器。

停止命令

$ egg-scripts stop [--title=egg-server]

该命令杀死 master 进程，并优雅退出 worker 和 agent。

支持参数：

• --title=egg-server：杀死指定 Egg 应用，未设置则终止所有 Egg 应用。

也可通过ps -eo "pid,command" | grep -- "--title=egg-server"查找 master 进程，并kill掉，不需kill -9。如 2.2 节所述，Master 捕获到信号后会走完整的优雅关闭流程（_doClose），依次以超时保护关闭 App Worker 与 Agent Worker，因此普通kill足以保证进程干净退出。

监控：线上性能监控与故障排查

我们还需要对服务进行性能监控、内存泄露分析、故障排除等。业界常用的有：

• Node.js 性能平台（Alinode）
• NSolid

其中 Alinode 与 Egg 的集成在官方文档与社区实践中最为成熟，下面重点展开。

Node.js 性能平台（Alinode）

注意：Node.js 性能平台（Alinode）目前仅支持 macOS 和 Linux，不支持 Windows。

Node.js 性能平台是面向所有 Node.js 应用提供性能监控、安全提醒、故障排查、性能优化等服务的整体性解决方案。它提供完善的工具链和服务，协助开发者快速发现和定位线上问题。

从当前仓库的 packages/cluster/src/master.ts 可以看到框架对 Alinode 的原生兼容：Master 启动时会打印[master] node version ${process.version}，并在检测到'alinode' in process时额外打印[master] alinode version ${process.alinode}，这正是下面"启动应用"一节日志输出的来源。

安装 Runtime

Alinode Runtime 可以直接替换掉 Node.js Runtime，对应版本参见其官方文档。

全局安装方式参见其官方文档。有时候，同时部署多个项目，期望多版本共存时，则可以把 Runtime 安装到当前项目：

$ npm i nodeinstall -g $ nodeinstall --install-alinode ^3

nodeinstall 会把对应版本的alinode安装到项目的node_modules目录下。

注意：打包机的操作系统和线上系统需保持一致，否则对应的 Runtime 不一定能正常运行。

安装及配置

我们提供了 egg-alinode 插件来快速接入，无需安装agenthub等额外的常驻服务。

安装依赖：

$ npm i egg-alinode --save

开启插件：

// config/plugin.js exports.alinode = { enable: true, package: 'egg-alinode', };

配置：

// config/config.default.js exports.alinode = { // 从 `Node.js 性能平台` 获取对应的接入参数 appid: '<YOUR_APPID>', secret: '<YOUR_SECRET>', };

启动应用

npm scripts配置的start指令无需改变，通过egg-scripts即可。

启动命令需使用npm start，因为npm scripts执行时会把node_module/.bin目录加入PATH，故会优先使用当前项目执行的 Node 版本。

启动后会看到 master 日志包含以下内容：

$ [master] node version v8.9.4 $ [master] alinode version v3.8.4 $ [Tue Aug 06 2019 15:54:25 GMT+0800 (China Standard Time)] Connecting to wss://agentserver.node.aliyun.com:8080... $ [Tue Aug 06 2019 15:54:26 GMT+0800 (China Standard Time)] agent register ok.

其中agent register ok.表示配置的 egg-alinode 正确连接上了 Node.js 性能平台服务器。node version与alinode version两行则与 packages/cluster/src/master.ts 中 Master 启动日志逻辑一一对应，可作为接入是否生效的快速判断依据。

访问控制台

接入完成后，可在 Node.js 性能平台控制台查看 CPU、内存、GC、慢日志等监控指标，进行内存泄露分析（Heap Profiling）与故障排查。

部署流程小结

一条完整的生产发布路径可以归纳为：

1. 构建：npm install --production安装核心依赖（TypeScript/Babel 项目先执行编译），打包为release.tgz；
2. 发布：服务器预装 Node.js（>= 14.20.0），解压发布包；
3. 启动：通过npm start（即egg-scripts start --daemon）拉起应用，Master 自动按 CPU 核数创建 worker 并守护进程；Docker 场景手动指定--workers并建议前台运行；
4. 停止：npm stop（即egg-scripts stop）优雅退出；
5. 监控：按需接入 Alinode（egg-alinode插件 + 控制台参数）实现线上性能监控与故障排查。

• 后端
• Web框架