Node.js + Stagehand + Python 部署

适用场景：跨语言自动化项目部署（Node.js 调度 + Stagehand 自动化 + Python 逻辑处理）

支持系统：Linux（Ubuntu 20.04+/CentOS 7+）、Windows 10/11、macOS 12+

1. 环境概述

1.1 核心组件及作用

Node.js：作为主服务，负责 API 提供、Stagehand 自动化调度、Python 脚本调用。
Stagehand：基于 Playwright 的自动化测试工具，专注 UI 自动化流程编排，支持浏览器模拟操作。
Python：处理复杂逻辑，包括 AI 模型调用（如通义千问）、数据处理、第三方工具集成。

1.2 核心架构流程

|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| graph TD A[用户/外部系统] --> B[Node.js 主服务] B --> C[Stagehand 自动化工具] B --> D[Python 脚本] C --> E[目标 Web 系统] D --> F[AI 模型/数据处理] C --> B D --> B B --> A[返回结果] |

2. 前置依赖准备

2.1 通用要求

网络：服务器需能访问外网（用于下载依赖、调用外部 API）。
权限：Linux/macOS 需 sudo 权限，Windows 需管理员身份操作。
基础工具：Git（版本控制，可选）、对应系统包管理器（apt/yum/Chocolatey/Homebrew）。

2.2 系统专属依赖安装

Linux（以 Ubuntu 为例）

|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| # 更新系统包 sudo apt update && sudo apt upgrade -y # 安装基础依赖（Python 编译、Node.js 运行依赖） sudo apt install -y python3 python3-pip python3-venv build-essential libssl-dev curl |

Windows

安装 Python 3.8+，勾选 "Add Python to PATH"。
安装 Node.js 16+，勾选 "Automatically install the necessary tools"。

macOS

|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| # 安装 Homebrew（未安装时执行） /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 安装 Python 和 Node.js brew install python node |

3. 部署步骤（分模块）

3.1 Python 环境部署

3.1.1 版本验证

|--------------------------------------------------------------------------------------------------------------------------------|
| # 验证版本（要求 Python ≥3.8，pip ≥20.0） python3 --version # Windows 直接执行 python --version pip3 --version # Windows 直接执行 pip --version |

3.1.2 虚拟环境配置（推荐）

|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| # 项目根目录创建虚拟环境 python3 -m venv venv # Windows：python -m venv venv # 激活虚拟环境 # Linux/macOS source venv/bin/activate # Windows（命令提示符） venv\Scripts\activate.bat # Windows（PowerShell） venv\Scripts\Activate.ps1 |

3.1.3 依赖包安装

项目根目录创建 requirements.txt 文件，内容如下：

|-----------------------------------------------------------------------------------------------------------------------------------------|
| openai>=1.0.0 # 大模型调用（通义千问 OpenAI 兼容） python-dotenv>=1.0.0 # 环境变量加载 playwright>=1.40.0 # 浏览器自动化依赖（可选） json5>=0.9.14 # JSON 解析增强（可选） |

执行安装命令：

|----------------------------------------------------------------------------|
| pip3 install -r requirements.txt # Windows：pip install -r requirements.txt |

3.1.4 环境变量配置

创建 .env 文件（Python 脚本目录下），配置敏感信息：

|---------------------------------------------------------------------------------------------------------------------|
| OPENAI_API_KEY=你的通义千问API密钥 OPENAI_BASE_URL= 通义千问url MODEL_NAME= 使用大模型 PYTHONPATH=./python_scripts # Python 脚本目录（可选） |

3.2 Node.js 环境部署

3.2.1 版本验证

|--------------------------------------------------------------|
| # 验证版本（要求 Node.js ≥16，npm ≥7.0） node --version npm --version |

3.2.2 项目初始化（新项目）

|-----------------------------------------------------------------------------------------------------------|
| # 创建项目目录并初始化 mkdir node-stagehand-project && cd node-stagehand-project npm init -y # 生成 package.json 文件 |

3.2.3 依赖包安装

|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| # 安装开发依赖（Stagehand 及 Playwright） npm install --save-dev @playwright/test stagehand-cli # 安装生产依赖（环境变量、HTTP 请求、Python 调用） npm install --save dotenv axios child_process # 安装 Playwright 浏览器二进制文件 npx playwright install |

3.2.4 项目配置

编辑 package.json，添加启动脚本：

创建 Node.js 环境变量文件 .env（项目根目录）：

|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| PORT=3000 # 服务端口 NODE_ENV=production # 环境（development/production） PYTHON_SCRIPT_PATH=./python_scripts/login_test.py # Python 脚本路径 HEADFUL=False # 生产环境建议关闭浏览器界面 |

3.3 Stagehand 工具部署与配置

3.3.1 初始化配置

|------------------------------------------|
| # 项目根目录执行，生成配置文件和测试目录 npx stagehand init |

执行后生成 stagehand.config.js（配置文件）和 tests/（自动化脚本目录）。

3.3.2 核心配置（stagehand.config.js）

|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| const { test } = require('@playwright/test'); const { execSync } = require('child_process'); require('dotenv').config(); test('登录自动化（Stagehand + Python 协作）', async ({ page }) => { // 1. 导航到目标登录页面 const loginUrl = 'http://192.*****'; await page.goto(loginUrl, { waitUntil: 'networkidle' }); // 2. 调用 Python 脚本处理核心逻辑 console.log('调用 Python 脚本执行登录逻辑...'); try { const result = execSync(`python3 ${process.env.PYTHON_SCRIPT_PATH}`, { encoding: 'utf-8', env: { ...process.env } // 传递环境变量给 Python }); console.log('Python 脚本执行结果：', result); } catch (error) { console.error('Python 脚本执行失败：', error.message); throw error; } // 3. 验证登录结果 await page.waitForLoadState('networkidle'); const isLoginSuccess = await page.textContent('body').then(text => text.includes('欢迎进入系统') || text.includes('退出登录') ); if (!isLoginSuccess) throw new Error('登录失败：未找到目标文本'); console.log('✅ 登录自动化执行成功！'); }); |

3.4 跨语言协作配置

Node.js 通过 child_process 模块调用 Python 脚本，支持同步 / 异步模式，以下是核心实现：

3.4.1 Node.js 主服务（server.js）

|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| require('dotenv').config(); const express = require('express'); const { execSync } = require('child_process'); const app = express(); const PORT = process.env.PORT || 3000; // 解析 JSON 请求体 app.use(express.json()); // API 接口：触发自动化登录 app.post('/api/run-login', (req, res) => { try { console.log('收到自动化登录请求，调用 Python 脚本...'); // 调用 Python 脚本（传递动态参数） const pythonResult = execSync(`python3 ${process.env.PYTHON_SCRIPT_PATH}\`, { encoding: 'utf-8', env: { ...process.env, USERNAME: req.body.username \|\| '1234', // 动态用户名 PASSWORD: req.body.password \|\| '1234' // 动态密码 } }); // 返回成功响应 res.status(200).json({ success: true, message: '自动化登录执行完成', result: pythonResult }); } catch (error) { console.error('自动化登录失败：', error.message); res.status(500).json({ success: false, message: '自动化登录执行失败', error: error.message }); } }); // 启动服务 app.listen(PORT, () =\> { console.log(\`Node.js 服务已启动，端口：$ {PORT}`); console.log(`环境：${process.env.NODE_ENV}`); }); |

3.4.2 Python 脚本接收参数（python_scripts/login_test.py）

修改 Python 脚本，支持从环境变量读取动态参数：

4. 启动与验证

4.1 启动顺序

激活 Python 虚拟环境（若使用）
启动 Node.js 主服务
执行 Stagehand 自动化任务（或通过 API 触发）

4.2 启动命令（项目根目录）

|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| # 1. 激活 Python 虚拟环境（Linux/macOS） source venv/bin/activate # Windows：venv\Scripts\activate.bat # 2. 启动 Node.js 服务 npm start # 3. （可选）直接执行 Stagehand 任务 npm run stagehand:run |

4.3 验证方式

方式 1：API 调用验证（推荐）

使用 curl 或 Postman 调用接口：

|----------------------------------------------------------------------------------------------------------------------|
| curl -X POST http://localhost\ -H "Content-Type: application/json" \ -d '{"username": "1234", "password": "1234"}' |

成功响应示例：

|--------------------------------------------------------------------------|
| { "success": true, "message": "自动化登录执行完成", "result": "✅ 内网登录测试流程全部完成！" } |

方式 2：直接执行 Python 脚本

|------------------------------------------------------------------------------------|
| python3 python_scripts/login_test.py # Windows：python python_scripts/login_test.py |

方式 3：直接执行 Stagehand 任务

|-----------------------|
| npm run stagehand:run |

5. 常见问题排查

5.1 Python 相关问题

问题：ModuleNotFoundError: No module named 'openai'
- 解决方案：确保激活虚拟环境，重新执行 pip3 install -r requirements.txt。
问题：大模型调用超时 / 失败
- 解决方案：检查 API 密钥和网关地址是否正确，确认服务器能访问外网。
问题：Playwright 浏览器启动失败
- 解决方案：执行 playwright install 重新安装浏览器；Linux 需补充依赖：sudo apt install -y libgtk-3-0 libnotify-dev。

5.2 Node.js 相关问题

问题：Error: Cannot find module 'stagehand-cli'
- 解决方案：重新执行 npm install，确保依赖安装完整。
问题：调用 Python 脚本失败（execSync 报错）
- 解决方案：检查 PYTHON_SCRIPT_PATH 路径是否正确；Linux/macOS 给脚本添加执行权限：chmod +x python_scripts/login_test.py。

5.3 Stagehand 相关问题

问题：无头模式（headless: true）自动化失败，可视化模式正常
- 解决方案：添加元素等待逻辑（page.waitForSelector），避免元素未加载完成就操作。
问题：内网服务无法访问
- 解决方案：检查服务器防火墙端口是否开放；Stagehand 配置中启用 ignoreHTTPSErrors: true。

6. 运维与优化建议

6.1 生产环境优化

Python 进程管理：使用 Supervisor 确保脚本稳定运行

|------------------------------------------------------------------------------------------------|
| sudo apt install -y supervisor # Linux 安装 # 配置文件：/etc/supervisor/conf.d/python-automation.conf |

Node.js 进程管理：使用 PM2 实现自动重启和日志记录

|----------------------------------------------------------------------------------------------|
| npm install -g pm2 pm2 start server.js --name "node-automation-service" pm2 startup # 设置开机自启 |

Stagehand 优化：生产环境启用无头模式，减少资源占用；合理设置并行 workers 数量。

6.2 日志与监控

Python 日志：添加文件日志输出

|----------------------------------------------------------------------------------------------------------------------|
| import logging logging.basicConfig(filename='python_automation.log', level=logging.INFO) logging.info('登录自动化任务开始执行') |

Node.js 日志：安装 winston 工具管理日志

|---------------------|
| npm install winston |

监控方案：使用 Prometheus + Grafana 监控服务状态；配置告警机制（邮件 / 钉钉）。

6.3 安全建议

敏感信息（API 密钥、密码）统一存储在 .env 文件，禁止硬编码。
限制 .env 文件权限：Linux/macOS 执行 chmod 600 .env。
定期更新依赖包：pip3 install --upgrade -r requirements.txt、npm update。

7. 附录

7.1 关键依赖版本参考

|------------|-----------|--------------------|
| 组件 | 推荐版本 | 备注 |
| Node.js | 16.x/18.x | 稳定版即可 |
| Python | 3.8+/3.9+ | 避免 3.7 及以下版本 |
| Stagehand | ≥0.5.0 | 需与 Playwright 版本兼容 |
| Playwright | ≥1.40.0 | 匹配浏览器版本 |

7.2 常用命令汇总

|-----------------|---------------------------------------|
| 操作 | 命令 |
| 安装 Python 依赖 | pip3 install -r requirements.txt |
| 安装 Node.js 依赖 | npm install |
| 启动 Node.js 服务 | npm start |
| 执行 Stagehand 任务 | npm run stagehand:run |
| PM2 重启 Node 服务 | pm2 restart node-automation-service |
| 查看 Python 虚拟环境 | source venv/bin/activate（Linux/macOS） |