部署指南

Linux 部署指南

杰诺AI 一体化平台 · 全新安装与初始化。命令可直接复制执行,按章节顺序操作即可。

杰诺AI 一体化平台适用于当前及后续 Linux x64 版本Linux更新于 2026-11-08阅读约 29 分钟
项目说明
适用对象客户实施人员 / 系统管理员
文档性质全新安装(首次部署);升级与卸载见第九节
适用范围不绑定具体版本,适用于当前及后续 Linux x64 版本
最近更新2026-11-08
文中出现的版本号、文件名仅作格式示例,实际取值请以官网「产品更新」页的当前发布信息为准。

〇、使用本文档前请先读这三件事

  1. 1文中所有 `<尖括号>` 都是占位符,必须替换成实际值再执行。

每个占位符的来源见下表,首次出现处也会单独提示。

占位符含义从哪里获取
<X.Y.Z>产品版本号官网「产品更新」页
<安装包文件名>Linux 安装包完整文件名同上(示例:JienorAI-Setup-X.Y.Z-linux-x64.rar)
<SHA256>该包官方公布的校验值同上
<NODE_VERSION>安装包要求的 Node.js 版本解压后 MANIFEST.json 的 nodeVersion
<解压口令>加密包解压口令向服务顾问申请
<服务器IP>部署服务器地址自行确认
<MySQL口令> / <管理员口令>数据库口令 / 管理中心登录口令自行设定
  1. 1Linux 版是命令行安装,没有图形向导。

Windows 版是"下一步"式安装器;Linux 版通过一组环境变量把参数传给安装程序。请按本文命令逐条执行,不要等待图形界面出现。

  1. 1装完不等于能用,还要做"数据中心初始化"。

数据中心未初始化时,JWork 智能引擎会处于"停止待命",业务端的 AI 对话不会启动——这是正常设计,不是安装失败。见第五节。

关于示例:文中标注「示例」的命令,其版本号、文件名、端口等取值仅用于说明格式,执行前必须替换为实际值。

一、部署流程总览

shell
① 环境准备  →  ② 下载校验  →  ③ 解压  →  ④ 执行安装
                                              ↓
⑥ 业务验证  ←  ⑤ 数据中心初始化(含启动 AI 引擎、配模型 Key)
阶段预计耗时关键产出
环境准备10–20 分钟Node.js、MySQL、解压工具就绪
安装5–15 分钟十余个后台服务启动
初始化5–10 分钟首个数据中心可用、AI 引擎在线

二、环境要求

2.1 服务器

项目最低推荐
操作系统Ubuntu 24.04 LTS(x86_64)同左
CPU4 核8 核
内存4 GB8 GB 以上
磁盘20 GB 可用50 GB 以上(随业务数据增长)
网络能访问数据库与大模型服务同左
其他主流 x86_64 Linux 发行版一般可用,但本文的验证与命令示例以 Ubuntu 24.04 为准。

2.2 依赖软件

软件版本要求说明
Node.js以安装包 `MANIFEST.json` 的 `nodeVersion` 为准安装前必须装好;安装程序会自动装 PM2,但不会装 Node
MySQL8.0 及以上8.0 / 8.4 / 9.x 均可;机器上已有可用实例时无需再装,安装时把连接指向它即可
解压工具unrar 或 7-Zip安装包为加密 RAR,需输入解压口令
curl任意用于下载与校验

如何确认本包要求的 Node 版本(解压后执行,避免凭经验装错):

bash
# 在解压目录中执行
python3 -c "import json;print(json.load(open('MANIFEST.json'))['nodeVersion'])"
⚠️ MySQL 9.x 兼容性提醒:MySQL 9.0 起已移除 mysql_native_password 认证插件。 若后续对接的应用或驱动较老(仍使用该插件),连接会直接报 Plugin 'mysql_native_password' is not loaded,且无法通过配置开关恢复。 老系统请选用 MySQL 8.4 LTS,或在 8.x 上完成驱动升级后再迁移。

已有 MySQL 的机器怎么装

不需要重复安装数据库。安装时把数据库连接指向现有实例即可,安装程序会自行创建平台所需的库:

安装参数填法
JIENOR_DB_HOST / JIENOR_DB_PORT现有实例地址(同机一般 127.0.0.1 / 3306)
JIENOR_DB_USER / JIENOR_DB_PASSWORD需具备建库、建表、建用户权限的账号(如 root,或事先授权的专用账号)
管理员口令自行设定,用于管理中心登录
若数据库只允许本机登录(root@localhost),安装必须在数据库所在机器上执行,或先为该机授权可远程的专用账号。

关于“安装根”(下文路径的基准)

安装目录由安装器决定,3.1.32 起默认为 `/opt/jienor-ai`,此前的版本为 /opt/jienor/jienor-ai。

  • 确认方法:安装日志首行会打印 安装目录: …;也可执行 ls -d /opt/jienor* 查看;
  • 本文后续出现的 /opt/jienor/jienor-ai/… 均指实际安装根,请按本机实际路径替换。

2.3 端口规划

端口用途是否对外
3003平台统一入口(业务端 + 管理中心)✅ 仅此一个需要对外
22SSH 运维按需
3306MySQL(同机安装时)建议仅本机
3002管理中心服务❌ 内部
3009 / 3010 / 3013 / 3015系统集成 / AI 服务 / 基础平台 / 工作流❌ 内部
4014 / 4016 / 4017 / 4018 / 4019人事 / 客户 / 项目 / 财务 / 数据分析❌ 内部
8788JWork 引擎 API❌ 仅回环(127.0.0.1)
3081JWork 引擎 Web GUI❌ 仅回环(127.0.0.1)
5173开发用 Web Shell❌ 请勿对外暴露
端口可能随版本增减。若与上文不一致,以安装后生成的 <实际安装根>/ecosystem.config.cjs(如 /opt/jienor-ai/ecosystem.config.cjs)为准。 5173 是给开发调试用的壳服务,会绕过网关直连各子系统,生产环境只使用 3003。

2.4 本文实测环境(选型参考)

本文的全部步骤在下列环境组合上完整验证通过。产品版本随发布迭代,故不在此标注; 本表记录的是"环境组合",供你选择服务器与数据库版本时参考。

项目实测值说明
操作系统Ubuntu 24.04.5 LTS(内核 6.8,x86_64)推荐 24.04 LTS 或更高的 LTS 版本
Node.js24.15.0与当次安装包 MANIFEST.json 的 nodeVersion 一致
MySQL9.7.48.0 及以上均可;9.x 的认证插件变化见 2.2 提醒
解压工具unrar 7.00 / 7-Zip 23.01二者任选,均验证可用
服务器规格4 vCPU / 8 GB 内存 / 80 GB 磁盘对应 2.1 的推荐配置
注意:Node.js 必须与当次安装包要求的版本一致。上表 24.15.0 只是本次实测组合中的取值, 不要直接照抄——请按 2.2 的方法从安装包 MANIFEST.json 中读取实际要求。

三、安装前准备

3.1 获取安装包与解压口令

  1. 1在官网「产品更新」页下载 Linux 安装包,记录文件名;
  2. 2记录该版本页面上公布的 SHA-256;
  3. 3通过页面「获取解压口令」向服务顾问申请口令(同版本多平台包通用)。

3.2 校验安装包完整性

bash
# 示例:<安装包文件名> 需替换为实际文件名
sha256sum <安装包文件名>
# 例:sha256sum JienorAI-Setup-X.Y.Z-linux-x64.rar

将输出与官网公布值逐字符比对,不一致请重新下载,不要使用。

3.3 安装依赖

bash
# 解压工具
sudo apt update
sudo apt install -y unrar curl

# Node.js:版本以 MANIFEST.json 的 nodeVersion 为准
# 示例中 NODE_VERSION="24.15.0",请替换为实际值
NODE_VERSION="<NODE_VERSION>"

curl -fsSL -o /tmp/node.tar.xz \
  "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
sudo tar -xJf /tmp/node.tar.xz -C /usr/local --strip-components=1
rm -f /tmp/node.tar.xz

# 验证(输出应为刚才设定的版本)
node -v && npm -v
若访问 nodejs.org 较慢,可换成国内镜像,同样用变量拼接,避免写死版本: https://npmmirror.com/mirrors/node/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz

3.4 准备 MySQL

安装器会自动创建 jienor_admin 库并建表,无需手工建库。 请准备一个具备建库/建表权限的账号(可用 root,或权限等价的专用账号)。

bash
mysql -h 127.0.0.1 -P 3306 -u root -p -e "SELECT VERSION();"
  • 版本需 ≥ 8.0;
  • 字符集建议 utf8mb4;
  • 注意:MySQL 的 root 默认只允许本机登录。安装时数据库地址请填 127.0.0.1,不要填服务器公网/局域网 IP。

3.5 解压安装包

bash
# 示例:<安装包文件名> 与 <解压口令> 均需替换
sudo mkdir -p /opt/jienor-setup
sudo chown $USER:$USER /opt/jienor-setup
cd /opt/jienor-setup
unrar x -p'<解压口令>' <安装包文件名>

解压后目录结构:

shell
/opt/jienor-setup/
├── MANIFEST.json          # 安装清单、校验和、依赖的 Node 版本
├── payload/               # 待安装产品载荷
│   ├── install-wizard/    # 安装程序
│   ├── backend/ frontend/ gateway/ …
│   └── version.json
└── devkit/                # 子系统开发工具包(普通部署用不到)
以上是解压目录,里面只有待安装的载荷。`start.sh` / `stop.sh` 等启停脚本不在这里, 它们由安装程序在安装时生成到安装根目录,见 7.1。

3.6 创建安装目录

bash
sudo mkdir -p /opt/jienor
sudo chown -R $USER:$USER /opt/jienor
重要:请用普通用户(如 ubuntu)执行安装,不要用 `sudo node ...`。 以 root 运行会使进程与文件归属变为 root,后续运维需全程 sudo,容易出错。

四、执行安装

4.1 安装命令

bash
cd /opt/jienor-setup/payload/install-wizard

JIENOR_PRODUCT=jienor-ai \
JIENOR_INSTALL_DIR=/opt/jienor/jienor-ai \
JIENOR_PACKAGE_PATH=/opt/jienor-setup/payload \
JIENOR_RESOURCE_ROOT=/opt/jienor-setup \
JIENOR_DB_HOST=127.0.0.1 \
JIENOR_DB_PORT=3306 \
JIENOR_DB_USER=root \
JIENOR_DB_PASSWORD='<MySQL口令>' \
JIENOR_DB_NAME=jienor_admin \
JIENOR_ADMIN_USER=admin \
JIENOR_ADMIN_PASSWORD='<管理员口令>' \
node run-cli.js 2>&1 | tee /opt/jienor-setup/install.log
上面只有口令是占位符;路径、库名、账号为固定值,可直接照抄。 管理员口令请自行设定并妥善保存,装完后平台不会再次显示。

4.2 参数说明

参数必填说明
JIENOR_INSTALL_DIR✅安装根目录,建议 /opt/jienor/jienor-ai
JIENOR_PACKAGE_PATH✅指向解压目录下的 payload
JIENOR_RESOURCE_ROOT✅指向解压目录根
JIENOR_DB_HOST / PORT✅数据库地址与端口,同机填 127.0.0.1
JIENOR_DB_USER / PASSWORD✅数据库账号(需建库建表权限)
JIENOR_DB_NAME✅平台管理库名,默认 jienor_admin
JIENOR_ADMIN_USER / PASSWORD✅管理中心登录账号与口令
JIENOR_PRODUCT建议固定 jienor-ai

4.3 安装过程

安装程序依次执行 8 个步骤:

shell
1/8 前置条件检查 → 2/8 创建目录结构 → 3/8 解压服务产物 → 4/8 链接内部依赖
→ 5/8 配置环境变量 → 6/8 初始化数据库 → 7/8 启动系统服务 → 8/8 健康检查验证

成功标志:末尾输出 === 安装完成 ===,退出码 0。

首次安装会自动安装 PM2,日志中出现 [runtime-bootstrap] 自动安装:PM2 属正常。

安装程序不会配置开机自启,结尾也不会打印启停命令。装完请记下第七节的 start.sh / stop.sh 用法;需要服务器重启后自动拉起,按 7.3 配置。

五、安装后初始化(关键步骤,务必执行)

安装完成时尚未创建数据中心,需按下述顺序完成初始化,平台才真正可用。

第一步:登录管理中心

shell
管理中心:http://<服务器IP>:3003/admin
登录页:  http://<服务器IP>:3003/admin-login

账号口令即第 4 节 JIENOR_ADMIN_USER / JIENOR_ADMIN_PASSWORD 所设。

第二步:创建数据中心

进入「数据中心」页 → 新建,按下表填写:

字段填写内容
名称 / 代码按企业命名,如 总部 / HQ
主机127.0.0.1(数据库与平台同机时)
端口3306
数据库新的库名,如 jienor_dc_hq(不要填 jienor_admin)
用户名 / 密码数据库账号(同上)
该库由平台在初始化时自动创建,无需手工建库。 表单的「测试连接」只验证账号能否登录,不校验库名是否存在,库名请自行确认无误。

第三步:初始化数据中心

保存后在列表中对新数据中心执行「初始化」。初始化会创建业务库与库表,需等待完成, 最终状态应显示为「已初始化」。

第四步:启动 JWork 智能引擎

初始化完成后需手动启动一次(安装阶段它处于"停止待命",避免无数据中心时反复崩溃):

  • 方式一:管理中心 →「运行维护」→「服务进程」→ 找到 JWork智能引擎 → 点「启动」;
  • 方式二:服务器上执行
bash
PM2_HOME=/opt/jienor/jienor-ai/.pm2 pm2 restart jienor-jwork-bridge
服务名以 pm2 list 中的实际名称为准,不同版本可能略有差异。

启动成功的标志:该行状态显示「运行中」,业务端右侧对话面板不再显示"正在启动"。

第五步:配置大模型 API Key

安装包不包含任何大模型密钥。请在 管理中心 → 模型(AI 资产)→ 填写 API Key。

保存后约 60 秒内自动生效,无需重启引擎。

第六步:业务端验证

shell
业务端:http://<服务器IP>:3003/login
  1. 1数据中心下拉应出现刚创建的数据中心;
  2. 2使用管理员账号登录;
  3. 3首页应显示各应用入口,右侧 AI 对话可正常问答。

六、安装结果核对

bash
# 进程状态(注意必须带 PM2_HOME)
PM2_HOME=/opt/jienor/jienor-ai/.pm2 pm2 list

期望:绝大多数服务 online;jienor-jwork-bridge 在初始化数据中心前为 stopped(正常),启动后为 online。 服务数量随版本变化,以实际清单为准,不必强求某个固定条数。

bash
# 端口监听
ss -tlnp | grep -E ':3003|:8788|:3081'

期望:3003、8788、3081 均在监听(8788/3081 仅绑 127.0.0.1)。

bash
# 数据库
mysql -h 127.0.0.1 -u root -p -e "SHOW DATABASES;" | grep jienor

期望:jienor_admin 与数据中心业务库存在。

bash
# 启停脚本已生成(安装时按本机路径生成,**不在解压包内**,见 7.1)
ls -l /opt/jienor/jienor-ai/{start.sh,stop.sh,restart.sh,install-systemd.sh}

期望:四个文件都存在,且权限位含 x(可执行)。


七、服务管理

本节命令都以安装根目录为工作目录。示例写作 /opt/jienor/jienor-ai, 实际以第四节 JIENOR_INSTALL_DIR 填的值为准。

7.1 启动脚本在哪里(装完先看这一节)

安装包里没有 `start.sh` 这类文件——在解压出来的 payload/ 中搜索是搜不到的。 它们由安装程序在安装时按本机的安装路径与端口现场生成到安装根目录, 所以"在安装包里找启动脚本"找不到,是正常现象,不代表包残缺。

真正决定"启动什么、怎么启动"的是安装根下的 `ecosystem.config.cjs`(PM2 进程清单: 每个服务的入口文件、工作目录、端口、运行环境变量都写在这里)。不需要、也不建议 手工执行 node <某个文件> 去启动服务——那样会绕过 PM2 托管与统一的环境注入, 常见表现是"进程在跑,但平台功能异常 / 端口不符"。

文件(均位于安装根)作用什么时候用
start.sh一键启动全部服务,交给 PM2 托管服务器重启后、服务全停后
stop.sh停止本平台自己的服务升级、备份、迁移前
restart.sh逐个具名重启本平台的服务改过配置、单个服务卡死
start-dev.sh开发模式在前台起服务仅开发调试,生产请勿使用
install-systemd.sh把服务注册为 systemd 单元需要用 systemd 托管时(见 7.3,与 PM2 二选一)
ecosystem.config.cjs进程清单 + 运行时环境变量核对服务名、端口、env
systemd/*.servicesystemd 单元模板供 install-systemd.sh 使用
bash
# 必须在安装根目录执行:脚本内部用相对路径定位 ecosystem.config.cjs
cd /opt/jienor/jienor-ai
./start.sh      # 启动(已在运行时等价于重启)
./stop.sh       # 停止
./restart.sh    # 重启
用绝对路径调用时也请先 cd 到安装根,否则会提示找不到 ecosystem.config.cjs。 执行脚本的用户应为安装时使用的账号,不要用 sudo 跑(会让文件归属变成 root)。

7.2 常用命令

bash
export PM2_HOME=/opt/jienor/jienor-ai/.pm2     # 建议写入 ~/.bashrc

pm2 list                                  # 查看全部服务
pm2 restart <服务名>                       # 重启单个服务,如 jienor-gateway
pm2 logs <服务名> --lines 100              # 查看日志
pm2 stop all                              # 停止全部
pm2 resurrect                             # 按上次保存的清单恢复
pm2 save                                  # 保存当前进程清单
为什么必须带 `PM2_HOME`:平台按安装根隔离 PM2 实例。不带该变量时 pm2 list 看到的是空列表, 会误判为"服务没起来"。

7.3 开机自启(按需配置,二选一)

安装程序不会自动配置开机自启。 服务器重启后服务不会自己起来,需要手工执行 ./start.sh。要长期无人值守,请在下面两种方式中只选一种——两套同时启用会争抢 同一批端口:先起来的那套正常,后起来的那套反复重启。

方式适合场景需要接受的代价
A. PM2 自启(推荐)与安装程序的托管方式完全一致,服务名、环境变量、日志路径都不变无
B. systemd 托管客户运维规范要求统一用 systemctl 纳管必须先停用 PM2 自启;单元文件里写死了安装时的密钥与运行用户

方式 A:PM2 自启(推荐)

bash
export PM2_HOME=/opt/jienor/jienor-ai/.pm2

pm2 startup
# ↑ 该命令会打印一条以 sudo 开头的命令,复制并执行它(需 root 写 systemd 单元)

pm2 save
# ↑ 保存当前进程清单,开机按此清单恢复

验证:

bash
# 应能查到 pm2-<用户名> 单元,且为 enabled
systemctl list-unit-files | grep -i pm2
bash
# 重启服务器后确认(重启前请确认业务空闲)
sudo reboot

PM2_HOME=/opt/jienor/jienor-ai/.pm2 pm2 list
只在"服务已全部正常"时执行 pm2 save。若保存时引擎处于停止态,开机后它也保持停止, 按第五节第四步启动即可。 不同 PM2 版本提示文案略有差异,按其输出执行;若提示找不到 pm2,用 npx pm2 代替。

方式 B:systemd 托管(备选,切换前请先评估)

安装根已自带 install-systemd.sh 与 systemd/*.service,可把服务注册成 systemd 单元:

bash
cd /opt/jienor/jienor-ai

# 1) 先停掉 PM2 托管,避免两套同时抢同一批端口
export PM2_HOME=/opt/jienor/jienor-ai/.pm2
pm2 save
pm2 stop all

# 2) 安装并启用 systemd 单元(脚本内部会用 sudo)
sudo ./install-systemd.sh

切换前请知悉以下几点(均由单元文件内容决定,不是配置项):

事项说明
与 PM2 互斥单元启动的是同一批服务、同一批端口。已启用 PM2 自启的机器必须先 pm2 unstartup(或删除该单元),否则重启后两套互抢
密钥明文单元内以 Environment= 明文写着数据库口令、JWT_SECRET、INTERNAL_CALL_SECRET、AES_KEY,文件权限需自行收紧(建议 600)
运行用户固定单元里的 User= 是安装时使用的账号;换账号运行或迁移机器后需手工修改
改配置不生效运行环境取自单元文件,而非 config/env;后者改了不会同步过去
状态查询换命令切到 systemd 后,./start.sh / ./stop.sh 与 pm2 list 不再反映真实状态,要看 systemctl status

验证:

bash
systemctl list-units 'jienor-*' --all
ss -tlnp | grep ':3003'
除非现场明确要求用 systemd 统一纳管,否则请用方式 A。 采用方式 B 前,建议先在 与生产同版本的测试环境上把"启停"和"升级"各走一遍。

7.4 日志与配置位置

内容路径
各服务输出/错误/opt/jienor/jienor-ai/.pm2/logs/
安装日志安装时 tee 指定的文件(见 4.1)
应用配置(含密钥,保密)/opt/jienor/jienor-ai/current/config/env
进程清单/opt/jienor/jienor-ai/ecosystem.config.cjs
启停脚本/opt/jienor/jienor-ai/*.sh(安装时生成,见 7.1)
current 是指向 versions/<实际版本目录> 的软链接,配置随版本目录走, 所以 config/env 在 current/config/ 下,而不是安装根直接一层。

八、备份

bash
# 1) 数据库(管理库 + 各数据中心业务库)
mysqldump -h 127.0.0.1 -u root -p --single-transaction --routines --triggers \
  --databases jienor_admin <数据中心业务库名> > /backup/jienor_$(date +%F).sql

# 2) 应用配置(含密钥、连接串,务必保密)
tar czf /backup/jienor-config_$(date +%F).tgz -C /opt/jienor/jienor-ai/current config
current/config/env 内含平台加密密钥,丢失将导致已加密数据无法解密,请与数据库备份一并保存。

九、升级与卸载

9.1 升级(覆盖安装)

  1. 1先备份(见第八节);
  2. 2停止服务:PM2_HOME=/opt/jienor/jienor-ai/.pm2 pm2 stop all
  3. 3下载并解压新版本安装包(步骤同第三节),保留原数据库不动;
  4. 4用新版安装程序执行安装,`JIENOR_INSTALL_DIR` 指向原安装目录(覆盖安装,不要删旧目录、不要删库);
  5. 5安装完成后在管理中心「系统更新」核对版本;
  6. 6按第五节第四步检查 JWork 引擎是否在线。
升级不需要卸载,也不要重新初始化数据中心。 若发布说明要求"全新安装",请以发布说明为准,不要套用本节。

9.2 卸载

bash
# 1) 停止并清理 PM2
PM2_HOME=/opt/jienor/jienor-ai/.pm2 pm2 kill

# 2) 删除安装目录
sudo rm -rf /opt/jienor

# 3) 删除数据库(谨慎,数据不可恢复)
mysql -h 127.0.0.1 -u root -p -e "DROP DATABASE jienor_admin;"
mysql -h 127.0.0.1 -u root -p -e "DROP DATABASE <数据中心业务库名>;"

十、反向代理与 HTTPS(生产推荐)

10.1 什么时候需要

出现以下任一情况时,建议在平台前加一层反向代理:

  • 客户要求用域名访问,而不是 IP:3003;
  • 需要 HTTPS(浏览器安全策略、单点登录、企业合规);
  • 希望只对外开放 80/443,把 3003 收进内网;
  • 前面已有统一的负载均衡 / API 网关。
原则:只代理 3003 一个端口。 不要代理 3002、5173、8788、3081 等内部端口—— 它们要么仅供本机使用,要么会绕过统一鉴权。

10.2 必须做对的五件事

平台除普通 HTTP 请求外,还有一条事件流(SSE)通道 `/api/remote.mux`,用于向浏览器推送对话过程。 反代若按普通请求处理,会表现为「页面能打开、AI 对话一直转圈」。因此必须:

#要求配错的后果
1关闭响应缓冲(proxy_buffering off)事件流被攒住,对话不出字
2读写超时放长(≥ 300 秒)长回答中途断开
3使用 HTTP/1.1(proxy_http_version 1.1)连接复用异常、流被截断
4透传 Host 与 X-Forwarded-*管理中心生成的链接指向 localhost,分机点不开
5放开上传大小(client_max_body_size)上传附件/知识库报 413

10.3 nginx 配置示例

nginx
server {
    listen 80;
    server_name <域名>;

    # 附件、知识库上传(按需调整)
    client_max_body_size 200m;

    location / {
        proxy_pass http://127.0.0.1:3003;
        proxy_http_version 1.1;

        # 身份与来源透传(第 4 条要求,缺了会导致链接生成 localhost)
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host  $host;

        # 事件流:关闭缓冲、放长超时(第 1、2 条要求)
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        add_header X-Accel-Buffering no;
    }

    # 事件流通道(显式声明更稳妥;路径以安装日志的"事件流自检"为准)
    location /api/remote.mux {
        proxy_pass http://127.0.0.1:3003;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Connection '';
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
        add_header X-Accel-Buffering no;
        add_header Cache-Control no-cache;
    }
}
事件流路径可能随版本调整。安装日志末尾会打印"事件流自检"结果与所需路径, 请以当次安装日志为准;若与上文不同,按日志提示修改 location。

10.4 启用 HTTPS

bash
sudo apt install -y nginx certbot python3-certbot-nginx
sudo certbot --nginx -d <域名>

证书续期由 certbot 自动处理(systemctl status certbot.timer 可查)。

重要:启用 HTTPS 后,平台会依据 X-Forwarded-Proto 判断是否给会话 Cookie 加 Secure 标记。 因此第 4 条要求里的 X-Forwarded-Proto $scheme 不能省,否则会出现"登录成功但立刻掉线"。

10.5 验证

bash
# 1) 页面可访问(应返回 200 与 HTML)
curl -I -H "Accept: text/html" https://<域名>/login

# 2) 事件流可用(应保持连接、持续输出,而不是立即结束)
curl -N -H "Accept: text/event-stream" https://<域名>/api/remote.mux

浏览器侧:按 F12 → Network,remote.mux 请求应处于 pending(长连接); 若很快变成 200 并结束,说明缓冲未关闭。

10.6 常见错误对照

现象通常原因
页面正常,AI 对话一直"正在启动"/转圈事件流被缓冲,或 /api/remote.mux 未转发
管理中心里的链接指向 localhost未透传 Host / X-Forwarded-Host
登录成功但立刻掉线HTTPS 下 Cookie 带 Secure,但未透传 X-Forwarded-Proto
上传附件报 413client_max_body_size 太小
502 Bad Gatewayproxy_pass 地址不对,应为 127.0.0.1:3003
启用反代后,仍建议把 3003 限制在内网,只对反代所在主机放行。

十一、常见问题

Q1:解压时提示需要口令 / 口令错误? 安装包为加密压缩包(含文件名加密),需向服务顾问申请口令,同一版本多个平台包通用。 请使用 unrar 或 7-Zip,Windows 资源管理器无法直接打开。

Q2:Linux 上没有图形安装界面? 是的。Linux 版仅提供命令行安装(见第四节)。图形向导仅在 Windows 版提供,两者底层安装逻辑一致。

Q3:装完了,但业务端 AI 对话一直显示"正在启动"? 绝大多数是数据中心未初始化或引擎未启动:

  1. 1管理中心 →「数据中心」,确认存在「已初始化」的数据中心;
  2. 2「运行维护」→「服务进程」,确认 JWork智能引擎 为「运行中」,否则点「启动」;
  3. 3仍不行则看 .pm2/logs/jienor-jwork-bridge-error.log 的首个错误。

Q4:系统概览显示"基础平台 / 工作流 / AI服务端 / 系统集成 不可达"? 这是状态判定偏严导致的提示,不影响登录、数据中心与业务功能。这 4 个服务的进程与端口均正常, 可用以下命令确认:

bash
curl -s http://127.0.0.1:3013/health | head -c 200

只要返回内容含 "status":"degraded" 而非连接失败,即说明服务在运行。

Q5:`pm2 list` 显示没有进程,但页面能正常访问? 忘了带 PM2_HOME,请用: PM2_HOME=/opt/jienor/jienor-ai/.pm2 pm2 list

Q6:管理中心 / 业务端打不开?

  1. 1确认服务在跑(Q5 的命令);
  2. 2确认防火墙放行 3003:sudo ufw allow 3003/tcp;
  3. 3确认访问 http://<IP>:3003,不要用 5173(开发端口)。

Q7:数据中心表单「测试连接」成功,但初始化失败? 「测试连接」只验证账号登录,不校验库名。请确认「数据库」填的是新的库名 (不能是 jienor_admin,也不能与已有库重名)。

Q8:安装时提示 MySQL 版本过低? 需 8.0 及以上,请升级数据库或改指向已升级实例。

Q9:忘记管理员口令? 请联系服务顾问协助重置;不要直接改数据库表,以免破坏口令加密格式。

Q10:启动日志提示 Node 版本不符 / 模块加载失败? 先核对第 2.2 节的方法查到的 nodeVersion 与实际 node -v 是否一致。 Node 版本不匹配会导致依赖解析异常,这类报错不要按业务缺陷排查。

Q11:安装包里找不到启动脚本,也不知道 Node 该指向哪个文件? start.sh / stop.sh / restart.sh 这些脚本不在安装包里,由安装程序在安装时 生成到安装根目录(JIENOR_INSTALL_DIR)。装完后 cd 到安装根即可看到。 启动入口是 ecosystem.config.cjs,由 PM2 读取;不需要手工指定某个 node xxx.js。 详见 7.1。

Q12:服务器重启后平台打不开了? 安装程序不配置开机自启。重启后先执行:

bash
cd /opt/jienor/jienor-ai
./start.sh

若希望重启后自动拉起,按 7.3 选一种方式配置(推荐方式 A)。

Q13:用 systemctl 起服务后,有的服务反复重启 / 日志报端口被占用? 说明 PM2 与 systemd 同时在托管同一批服务。两者只能选一个:先 pm2 stop all 并 pm2 unstartup,再启用 systemd;或反过来。见 7.3。


附录 A:安装参数速查

bash
JIENOR_PRODUCT=jienor-ai                 # 产品标识
JIENOR_INSTALL_DIR=/opt/jienor/jienor-ai # 安装根目录
JIENOR_PACKAGE_PATH=<解压目录>/payload    # 载荷目录
JIENOR_RESOURCE_ROOT=<解压目录>           # 资源根
JIENOR_DB_HOST=127.0.0.1                 # 数据库地址
JIENOR_DB_PORT=3306                      # 数据库端口
JIENOR_DB_USER=root                      # 数据库账号
JIENOR_DB_PASSWORD=<口令>                 # 数据库口令
JIENOR_DB_NAME=jienor_admin              # 平台管理库
JIENOR_ADMIN_USER=admin                  # 管理中心账号
JIENOR_ADMIN_PASSWORD=<口令>              # 管理中心口令

附录 B:安装后的目录结构

shell
/opt/jienor/jienor-ai/
├── current -> versions/<ver>/      # 当前版本(软链接)
│   └── config/
│       ├── env                     # 平台环境变量(含密钥,保密)
│       └── jwt-rsa-*.pem           # 签名密钥对(随版本目录走)
├── versions/                       # 历次安装版本
├── config/
│   └── ports.json                  # 本次安装解析出的端口清单
├── ecosystem.config.cjs            # PM2 进程清单(启动入口)
├── start.sh / stop.sh / restart.sh  # 启停脚本(安装时生成)
├── start-dev.sh                    # 开发模式启动(生产不用)
├── install-systemd.sh + systemd/   # systemd 托管(可选,见 7.3)
├── scripts/                        # 运维脚本(升级、状态自检等)
├── .pm2/                           # 本安装根专属的 PM2 实例与日志
└── logs/

附录 C:部署检查清单

检查项完成
安装包 SHA-256 与官网公布值一致☐
Node.js 版本与 MANIFEST.json 的 nodeVersion 一致☐
MySQL ≥ 8.0,且可用账号验证通过☐
安装日志出现 === 安装完成 ===☐
服务状态无异常(pm2 list 全部 online,除待命中的引擎)☐
启动脚本已生成且有执行位(start.sh / stop.sh / restart.sh)☐
管理中心可登录☐
数据中心已创建并「已初始化」☐
JWork 智能引擎「运行中」☐
大模型 API Key 已配置☐
业务端可登录、AI 对话可问答☐
防火墙仅对公网放行 3003☐
需要无人值守时,已按 7.3 配置一种开机自启方式☐
数据库与 config 已做首次备份☐

若使用反向代理(见第十节):

检查项完成
仅代理 3003,未暴露 3002 / 5173 / 8788 / 3081☐
已关闭响应缓冲(proxy_buffering off)并放长超时☐
已按安装日志配置事件流路径(如 /api/remote.mux)☐
已透传 Host、X-Forwarded-Proto、X-Forwarded-Host☐
浏览器 Network 中事件流请求为 pending 长连接☐
HTTPS 证书有效且自动续期☐

*本文档如与产品实际行为不符,请以官网最新发布说明为准;如有疑问,请联系服务顾问。*

部署过程中遇到问题?

安装包解压口令、数据库连接、数据中心初始化等环节,都可以直接联系杰诺服务团队协助。