openJiuwen 一键安装部署全流程指南（Windows 环境适配）

长安店店小二

23429人浏览 · 2026-03-02 15:25:00

长安店店小二 · 2026-03-02 15:25:00 发布

前言

openJiuwen 作为一款高效实用的工具，其部署过程的便捷性直接影响用户体验。为解决传统部署中环境配置复杂、版本冲突频发、步骤繁琐等问题，本文提供一套 标准化、可复用的一键安装部署方案，涵盖安装包说明、环境配置、脚本运行、版本验证等全流程操作。方案适配 Windows 系统，通过预设脚本自动化完成依赖检查、代码拉取、服务部署等关键步骤，同时针对 Node.js、Python 版本要求及代理、镜像源配置提供详细指引，无论是技术新手还是资深开发者，均可按步骤快速完成部署，大幅降低部署门槛与时间成本。

1.安装包脚本

下载安装包脚本，脚本内包含以下核心文件，各文件功能明确如下：

setup.ps1：主安装脚本，串联整个安装部署流程
check_git.ps1：检查系统中Git是否已安装
check_nodejs.ps1：检查系统中Node.js是否已安装
check_python.ps1：检查系统中Python是否已安装
check_mysql.ps1：检查系统中MySQL是否已安装
fetch_codes.ps1：克隆agent-studio代码仓库
user_config.ps1：用户配置文件（可选），包含代理、pip源、npm源相关配置

2. 配置代理、pip源和npm源（可选）

若你的网络环境需要通过代理访问外网，或需使用自定义的pip源、npm源，可在user_config.ps1文件中修改对应变量完成配置，配置项如下：

# 用户填写的代理配置
$HTTP_PROXY=""  # HTTP 代理地址，例如 http://127.0.0.1:7890
$HTTPS_PROXY=""  # HTTPS 代理地址，例如 http://127.0.0.1:7890
$SSL_VERIFY=""  # 可选：true/false（对应 git http.sslVerify）

# pip 源配置（可选）
$PIP_INDEX_URL=""      # pip 源地址，例如 https://pypi.tuna.tsinghua.edu.cn/simple
$PIP_TRUSTED_HOST=""   # 信任的主机地址，例如 pypi.tuna.tsinghua.edu.cn

# npm 源配置（可选）
$NPM_REGISTRY=""       # npm 源地址，例如 https://registry.npmmirror.com

代理配置说明

不需要代理：保持变量为空即可（脚本会自动跳过代理配置）
需要代理：填写完整代理地址，例如 http://127.0.0.1:7890
带认证的代理：支持用户名密码配置，例如 http://user:pass@proxy.example.com:8080
SSL 验证：$SSL_VERIFY 设置为 true 或 false，true表示开启Git的SSL证书验证，false为不开启

pip 源配置说明

不需要配置 pip 源：保持 $PIP_INDEX_URL 和 $PIP_TRUSTED_HOST 为空即可（脚本会自动跳过 pip 源配置，使用默认源）
需要配置 pip 源：必须同时设置 $PIP_INDEX_URL 和 $PIP_TRUSTED_HOST 两个参数
常用国内镜像源示例：
- 清华大学：https://pypi.tuna.tsinghua.edu.cn/simple，信任主机：pypi.tuna.tsinghua.edu.cn
- 阿里云：https://mirrors.aliyun.com/pypi/simple/，信任主机：mirrors.aliyun.com
- 中科大：https://pypi.mirrors.ustc.edu.cn/simple/，信任主机：pypi.mirrors.ustc.edu.cn

npm 源配置说明

不需要配置 npm 源：保持 $NPM_REGISTRY 为空即可（脚本会自动跳过 npm 源配置，使用默认源）
需要配置 npm 源：设置 $NPM_REGISTRY 为所需的 npm 源地址
常用国内镜像源示例：
- 淘宝镜像：https://registry.npmmirror.com
- 腾讯云：https://mirrors.cloud.tencent.com/npm/
- 华为云：https://repo.huaweicloud.com/repository/npm/

3. 运行安装脚本

3.1 配置PowerShell执行策略

以管理员身份运行 PowerShell，执行以下命令设置执行策略，解除脚本运行限制：

Set-ExecutionPolicy Unrestricted -Scope CurrentUser

执行后会弹出确认提示，输入Y确认即可，修改后当前用户的PowerShell执行策略将改为Unrestricted，后续运行PS1脚本不会再因执行策略限制被拦截。

3.2 执行主安装脚本

进入安装包脚本所在目录，执行对应命令运行主安装脚本，支持指定数据库类型：

# 进入脚本目录
cd setup_scripts_windows
# 默认使用 MySQL 数据库运行
.\setup.ps1
# 或指定使用 SQLite 数据库运行
.\setup.ps1 -DbType sqlite

3.3 Node.js版本验证

执行以下命令验证Node.js版本，确保版本为V22即可兼容脚本需求，同时可保留v24版本：

node -v

3.4 脚本自动执行步骤

运行主脚本后，程序会自动完成以下部署步骤，无需手动干预：

检查系统版本和 PowerShell 版本
检查基础工具（git、nodejs、python），如未安装会给出安装提示
拉取 agent-studio 代码仓库
生成 AES 密钥
配置 .env 文件（根据 -DbType 参数自动设置数据库类型）
部署后端服务（创建虚拟环境、安装依赖、启动服务）
部署前端服务（安装依赖、启动服务）

3.5 部署成功验证

脚本执行完成后，会自动输出后端和前端服务的PID、日志文件路径、前端页面访问地址，在浏览器中访问输出的地址即可进入openJiuwen界面。

出现公网地址即表示部署成功！

4. Node.js v22 环境配置与验证

Node.js 版本需为V22，版本不匹配会导致安装失败，v2脚本编译前端依赖需依赖该版本，以下是详细配置与验证步骤。

4.1 Node.js v22 安装验证

方式1：精准验证（指定路径，不受系统版本干扰）

替换为你的Node.js v22实际安装路径，执行命令验证，示例如下：

# 示例路径：C:\Program Files\nodejs-v22\node.exe
你的Node.js v22安装路径\node.exe -v

方式2：通用验证（环境变量配置成功后）

node -v
npm -v7

✅ 成功输出：node版本显示v22.x.x、npm版本显示10.x.x+

4.2一键安装Node.js v22.11.0 64 位 msi

推荐使用nvm管理多版本Node.js，避免版本冲突，步骤如下：

下载并安装nvm-windows（Node.js 版本管理器）；
安装后以管理员身份运行Powershell，执行以下命令安装并切换版本：

nvm install 22.11.0  # 安装v22版本
nvm use 22.11.0      # 切换到v22版本

4.3 基于v22版本运行部署脚本

# 验证当前目录node版本
.\node.exe -v
# 用当前目录的v22 node，直接运行部署脚本（带sqlite参数）
cmd /c "set PATH=%cd%;%PATH% && powershell .\setup.ps1 -DbType sqlite"

4.4 Node.js v22 配置关键要点

需将Node.js v22的路径置顶到环境变量（用户/系统变量均可），配置后重启终端刷新缓存，否则终端无法识别v22版本；
验证逻辑与Python指定路径验证一致，可通过node.exe绝对路径精准验证v22是否安装成功，不受系统其他Node版本干扰。

5. Python 3.11.4 环境配置与验证

Python版本必须≥3.11.4，且版本为python3.14时会因版本过高提示安装失败，以下是详细升级、验证与使用步骤。

5.1 核心注意事项

Python多版本冲突：系统变量Path优先级＞用户变量，终端会缓存环境变量，python -V显示系统版本不影响指定路径使用，v2脚本通过PYTHON_EXE_PATH指定3.11路径即可无感调用；
Python小版本升级：pip无法升级Python本体，3.11.0升级至3.11.4需通过官方安装包覆盖安装（安装时选择Modify/Upgrade Now），保留原路径无需卸载，为Windows官方推荐方式。

5.2 Python3.11.4 升级+验证

# 1. 升级3.11专属pip/setuptools（解决依赖安装兼容问题）
C:\Users\AppData\Local\Programs\Python\Python311\python.exe -m pip install --upgrade pip setuptools --no-cache-dir
# 2. 精准验证Python3.11.4安装成功（绕开系统版本，最权威）
C:\Users\AppData\Local\Programs\Python\Python311\python.exe -V

✅ 成功输出：Python 3.11.4

5.3 一键安装python 3.11.4

安装完成后，可通过以下命令强制用311版本运行脚本（仅本次终端会话生效）：

$env:PYTHON_EXE_PATH = "C:\Users\AppData\Local\Programs\Python\Python311\python.exe" ; .\setup.ps1 -DbType sqlite ; .\setup.ps1 -DbType sqlite

6. setup_scripts_windows_v2（v2脚本）核心部署（全程核心）

6.1 v2脚本前置要求

必须同时满足以下两个条件，否则会出现后端依赖安装失败/前端编译报错：

Python≥3.11.4（且已完成pip/setuptools升级）
Node.js v22可正常调用

6.2 v2脚本运行核心要点

所有命令必须在setup_scripts_windows_v2根目录执行，进入子目录（如backend）会导致运行失败；
脚本支持断点续跑，弹出步骤确认提示时输入y即可跳过已完成步骤，无需重新执行。

6.3 环境配置通用原则

临时运行脚本无需修改系统核心配置，通过绝对路径指定程序版本是最安全的方式，关闭终端后即恢复系统默认配置，无任何副作用。

6.4 v2脚本核心运行命令

# 1. 切到v2脚本根目录（**必做**，所有v2命令均在此执行）
R
# 2. 强制指定Python3.11.4运行v2脚本（适配sqlite数据库，核心命令）
$env:PYTHON_EXE_PATH = "C:\Users\AppData\Local\Programs\Python\Python311\python.exe" ; .\setup.ps1 -DbType sqlite
# 3. 脚本断点续跑确认（弹出提示时直接输入，跳过已完成步骤）
y

7. 脚本常用参数说明

v2脚本支持多种参数，可实现服务状态查看、启停、重启等操作，常用命令如下：

# 查看前后端服务状态和访问地址
.\setup.ps1 -Status

# 停止后端和前端服务
.\setup.ps1 -Stop

# 启动后端和前端服务
.\setup.ps1 -Start

# 重启后端和前端服务
.\setup.ps1 -Restart

# 查看脚本支持的所有参数
.\setup.ps1 -Help

总结

本文围绕 openJiuwen 一键安装部署展开，核心聚焦 “简化流程、规避踩坑”，从安装包文件解析、环境个性化配置（代理 / 镜像源），到脚本执行、核心依赖（Node.js v22、Python ≥3.11.4）版本适配，再到 v2 脚本核心部署命令与常用参数说明，形成了完整的部署闭环。通过 “自动化脚本 + 精准版本控制 + 断点续跑支持”，有效解决了部署中的版本冲突、环境不兼容、步骤遗漏等常见问题。用户只需严格遵循文中路径配置、命令执行、版本验证步骤，即可快速完成 openJiuwen 前后端服务部署，最终通过浏览器访问输出地址实现工具使用。整套方案兼顾实用性与灵活性，既满足新手的标准化操作需求，也支持开发者根据实际环境调整配置，为 openJiuwen 的快速落地提供了可靠保障。