Midway 3 接入阿里云 Node.js 性能平台（Alinode）实现应用监控实战指南-平芜编程栈

后端
微服务
云原生

【免费下载链接】midway

🍔 A Node.js Serverless Framework for front-end/full-stack developers. Build the application for next decade. Works on AWS, Alibaba Cloud, Tencent Cloud and traditional VM/Container. Super easy integrate with React and Vue. 🌈

项目地址：https://gitcode.com/gh_mirrors/mi/midway

点击查看免费下载

Midway 是基于 IoC 的 Node.js 服务端框架，而阿里云 Node.js 性能平台（Alinode）是面向 Node.js 应用的内存、CPU、GC 与性能瓶颈分析的一站式监控服务。本文将以 Midway 3 项目为背景，完整讲解如何将部署在独立云服务器上的 Midway 应用接入 Alinode：从开通服务、创建应用获取凭证，到安装 alinode 运行时与 agenthub 采集器、配置并启动服务，最后结合仓库中packages/web的默认配置源码，解释 Midway 侧对 Alinode 日志目录等参数的预置逻辑。读完本文，你将能够在自己的 Midway 生产环境中独立完成 Alinode 监控接入，并在性能平台上查看应用运行指标与错误日志。

接入前的准备工作

在开始接入之前，需要确认目标应用满足以下条件：

应用需要部署在独立的服务器或云环境（ECS 等），而不是本地开发机或无法访问公网的受限环境；
服务器需要能够接入互联网，因为 alinode 运行时与 agenthub 采集器需要与阿里云 Node.js 性能平台的服务端进行通信，上报采集到的运行数据。

简单说：一台可以上网的独立服务器，是 Alinode 监控能够正常工作的前提。

第一步：在阿里云创建性能平台服务与应用

开通 Node.js 性能平台服务

使用阿里云账号登录控制台，找到并开通「阿里云 Node.js 性能平台」服务。开通后，该服务会为你的账号提供应用创建、数据上报与监控看板能力。

创建应用并获取凭证

开通服务后，在性能平台控制台中创建新应用。创建完成后，平台会为每个应用分配一组唯一的凭证：

App ID（应用 ID）：标识你的应用；
App Secret（应用密钥）：用于采集器（agenthub）向平台服务端认证与上报数据。

这两项凭证是后续配置yourconfig.json的核心参数，请妥善保存，避免泄露。凭证属于敏感信息，建议在服务器环境中通过环境变量或受限权限的配置文件管理，不要提交到代码仓库。

第二步：在服务器上安装监控依赖

要在服务器上运行 Alinode 监控，需要安装三部分组件，这也是官方安装脚本的核心内容：

安装 tnvm（alinode 版本管理工具）：用于下载和管理 alinode 运行时；
使用 tnvm 安装 alinode 运行时：alinode 是内置了性能采集能力的 Node.js 运行时，用于替代默认的node启动应用；
安装 agenthub 数据采集器：负责把 alinode 运行时产生的日志与指标上报到性能平台。

# 安装版本管理工具 tnvm（若安装过程出错，可参考 aliyun-node/tnvm 项目说明） $ wget -O- https://raw.githubusercontent.com/aliyun-node/tnvm/master/install.sh | bash $ source ~/.bashrc # tnvm ls-remote alinode # 查看可用的 alinode 版本 $ tnvm install alinode-v6.5.0 # 安装需要的版本 $ tnvm use alinode-v6.5.0 # 切换使用该版本 $ npm install @alicloud/agenthub -g # 全局安装 agenthub

安装完成后，务必进行自检，确认当前 shell 环境中node与agenthub指向的都是.tnvm路径下的 alinode 版本：

$ which node /root/.tnvm/versions/alinode/v3.11.4/bin/node $ which agenthub /root/.tnvm/versions/alinode/v3.11.4/bin/agenthub

只要which node和which agenthub的输出路径中包含.tnvm，即说明 alinode 运行时与采集器已正确生效。如果node仍然指向系统自带的 Node.js 路径，说明 tnvm 的use切换未生效，需要重新检查~/.bashrc的加载情况。

第三步：配置凭证并启动 agenthub 采集器

将上一步创建的App ID和App Secret保存为一个 JSON 配置文件（例如放在项目根目录，命名为yourconfig.json）：

{ "appid": "****", "secret": "****" }

然后使用 agenthub 读取该配置并启动采集器：

agenthub start yourconfig.json

agenthub 启动后，会持续采集 alinode 运行时产生的日志，并将其上报到阿里云 Node.js 性能平台。可以检查 agenthub 的进程状态与日志输出，确认它已正常连接到平台。

第四步：以 alinode 运行时启动 Midway 服务

关键一步：必须使用 alinode 运行时（而非系统默认 node）来启动你的 Midway 应用，并且启动时需要设置ENABLE_NODE_LOG=YES环境变量，让 alinode 运行时开始记录性能日志。

对于 Midway 3 项目，生产环境通常以bootstrap.js作为启动入口（该入口由@midwayjs/bootstrap提供，见 packages/bootstrap/src/bootstrap.ts），启动命令示例如下：

$ NODE_ENV=production ENABLE_NODE_LOG=YES node bootstrap.js

命令说明：

NODE_ENV=production：以生产环境模式启动，Midway 会加载对应的config.prod.ts配置；
ENABLE_NODE_LOG=YES：开启 alinode 运行时的日志采集开关，是数据能否被采集的关键；
node bootstrap.js：这里的node必须是上一步 tnvm 切换后的 alinode 运行时。

启动后，Midway 应用正常对外提供服务，alinode 运行时在后台记录性能数据，agenthub 负责将数据上报，随后即可在阿里云 Node.js 性能平台的控制台中查看 CPU、内存、GC、堆快照、慢日志与错误日志等监控信息。

Midway 侧对 Alinode 的默认配置实现

除了运行环境层面的接入，Midway 3 在框架侧也对 Alinode 做了配置预置，方便在性能平台上定位应用日志。在 packages/web/src/config/config.default.ts 中可以找到 Alinode 相关默认配置：

// alinode runtime 写入的日志策略是: 如果 NODE_LOG_DIR 有设置，写入 NODE_LOG_DIR 设置的目录；否则为 /tmp let alinodeLogdir = fs.existsSync('/tmp') ? '/tmp' : os.tmpdir(); // try to use NODE_LOG_DIR first if (process.env.NODE_LOG_DIR) { alinodeLogdir = process.env.NODE_LOG_DIR; } mkdirp.sync(alinodeLogdir); exports.alinode = { logdir: alinodeLogdir, error_log: [ path.join(appInfo.root, `logs/${appInfo.pkg.name}/common-error.log`), path.join(appInfo.root, 'logs/stderr.log'), ], packages: [path.join(appInfo.appDir, 'package.json')], };

这段代码透露了几个重要的实现细节：

日志目录策略：alinode 运行时的日志写入目录遵循「优先使用NODE_LOG_DIR环境变量、否则回退到/tmp」的规则。Midway 在启动时读取该逻辑，并确保日志目录存在（mkdirp.sync）；
logdir：默认指向/tmp或NODE_LOG_DIR指定的目录，供性能平台日志采集使用；
error_log：预置了应用自身的错误日志路径，包括logs/${包名}/common-error.log与logs/stderr.log，方便 Alinode 将框架错误日志一并纳入监控；
packages：记录了应用package.json的路径，用于向平台上报应用依赖信息。

同时，仓库的测试代码也印证了NODE_LOG_DIR的作用，见 packages/web/test/utils.ts：测试环境中通过process.env.NODE_LOG_DIR = logDir;指定 alinode 日志目录，确保日志写入可预期的位置。

因此，在生产部署时，除了官方步骤中的ENABLE_NODE_LOG=YES，你还可以通过NODE_LOG_DIR显式指定日志落盘目录，例如：

$ NODE_ENV=production ENABLE_NODE_LOG=YES NODE_LOG_DIR=/data/logs/alinode node bootstrap.js

这样日志会集中写入指定目录，便于日志清理与磁盘管理。

Docker 容器中的接入方式

如果你的 Midway 应用通过 Docker 容器部署，接入 Alinode 的步骤与之类似，但需要额外注意：

在构建镜像时，同样需要安装 tnvm、alinode 运行时与 agenthub；
容器启动命令（或 Dockerfile 的CMD/ 编排平台的启动参数）中需要带上ENABLE_NODE_LOG=YES环境变量；
如果使用NODE_LOG_DIR指定日志目录，建议将该目录挂载到宿主机或日志采集路径，避免容器重启导致日志丢失；
agenthub 采集器需要在容器内以独立进程或同一启动流程中运行，保证其能访问 alinode 运行时产生的日志。

Docker 场景下的具体镜像配置与平台侧的参数细节，可参考阿里云官方帮助中心中关于 Node.js 性能平台在容器环境接入的文档说明。

常见问题与注意事项

which node不是.tnvm路径：说明 alinode 运行时没有切换成功，重新执行tnvm use <版本>并确认source ~/.bashrc生效；
采集器无法上报：检查yourconfig.json中的appid/secret是否与平台创建的应用一致，同时确认服务器可以访问公网；
日志目录权限：/tmp或NODE_LOG_DIR指定目录需要具备写权限，Midway 默认会在启动时创建该目录；
凭证安全：appid与secret属于敏感信息，建议通过环境变量或 KMS 等方式注入，不要硬编码进镜像或提交到 Git 仓库；
版本选择：tnvm install alinode-v6.5.0中的版本号可以根据tnvm ls-remote alinode的实际输出调整，选择与你的 Node.js 应用兼容的版本。

小结

接入阿里云 Node.js 性能平台的核心链路可以概括为四步：开通服务并创建应用获取凭证 → 通过 tnvm 安装 alinode 运行时与 agenthub → 配置yourconfig.json并启动 agenthub → 用 alinode 运行时配合ENABLE_NODE_LOG=YES启动 Midway 服务。在此基础上，Midway 3 框架在 packages/web/src/config/config.default.ts 中已预置了alinode.logdir、error_log等默认配置，并遵循NODE_LOG_DIR优先的日志目录策略，你只需按上文步骤完成运行环境接入，即可在性能平台看板上获得 Midway 应用的运行诊断能力。