部署指南

Linux 部署指南

杰诺代码工厂JCode · 全新安装与初始化。命令可直接复制执行,按章节顺序操作即可。

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

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

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

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

占位符含义从哪里获取
<X.Y.Z>产品版本号官网「产品更新」页
<安装包文件名>Linux 安装包完整文件名同上(示例:JCode-Setup-X.Y.Z-linux-x64.rar)
<SHA256>该包官方公布的校验值同上
<NODE_VERSION>安装包要求的 Node.js 版本解压后 MANIFEST.json 的 nodeVersion
<解压口令>加密包解压口令向服务顾问申请
<服务器IP>部署服务器地址自行确认
<管理中心地址>平台「管理中心服务」的直连地址同机单机部署固定为 http://127.0.0.1:3002
<MySQL口令>数据库账号口令自行设定
  1. 1JCode 不是独立系统,它依赖「杰诺AI 一体化平台」。

登录鉴权、可用模型、AI 配额都由平台的管理中心提供。因此部署顺序是: 先装平台 → 完成数据中心初始化 → 再装 JCode。 平台尚未就绪就装 JCode,会表现为"服务在线但登录不上 / 模型列表为空",这不是 JCode 安装失败。

  1. 1JCode 引擎只监听本机回环(`127.0.0.1`),这是安全设计,不是故障。

装完在本机 curl 127.0.0.1:3012 是通的,但从其他电脑直接打开 http://<服务器IP>:3012 会"拒绝连接"。 要让同网段同事访问,需按第五节第三步做一次端口转发(安装器已生成现成模板)。

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

一、部署流程总览

shell
① 平台已就绪(含数据中心初始化)
        ↓
② 环境准备 → ③ 下载校验 → ④ 解压 → ⑤ 执行安装
                                        ↓
                        ⑦ 业务验证 ← ⑥ 登录 + 分机访问配置
阶段预计耗时关键产出
环境准备10–20 分钟(可与平台共用)Node.js、MySQL、解压工具就绪
安装1–3 分钟jienor-jcode 服务在线,jcode_db 建库完成
登录与访问配置5–15 分钟能登录、分机能打开、模型可选

二、环境要求

2.1 服务器

项目最低推荐
操作系统Ubuntu 24.04 LTS(x86_64)同左
CPU4 核8 核(代码生成与构建较吃 CPU)
内存4 GB8 GB 以上(JCode 引擎常驻约 0.8–1 GB)
磁盘20 GB 可用50 GB 以上(工作区产物增长较快,见 8.2)
网络能访问平台管理中心与数据库同左
JCode 可与平台装在同一台服务器(推荐,省去跨机配置),也可分机部署。 分机部署时,JCode 所在机器必须能访问平台的管理中心端口(默认 3002)。

2.2 依赖软件

软件版本要求说明
Node.js以安装包 `MANIFEST.json` 的 `nodeVersion` 为准与平台要求通常一致;安装程序会自动装 PM2,但不会装 Node
MySQL8.0 及以上与平台共用同一实例即可
解压工具unrar 或 7-Zip安装包为加密 RAR,需输入解压口令
curl任意用于下载、校验与自检
杰诺AI 平台已安装且数据中心已初始化提供登录鉴权、模型目录、AI 配额

如何确认本包要求的 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。

2.3 端口规划

端口用途是否对外
3012JCode 引擎(Web + API)❌ 默认仅本机;分机访问需转发,见第五节第三步
3002平台管理中心服务(JCode 登录、取钥、取模型目录)❌ 内部,但 JCode 必须能访问
3003平台统一入口(网关)由平台负责,JCode 不直接用
22SSH 运维按需
3306MySQL建议仅本机
9000–9099代码执行内核端口段❌ 仅本机
30900–30999内核图形界面端口段❌ 仅本机
两个端口段请勿与同机其它产品重叠。 实际取值见安装后 /opt/jcode/current/config/env 中的 JW_USER_HOST_PORT_FROM / JW_USER_HOST_PORT_TO。 同机已有平台时,请确认两边的内核端口段不交叉,否则会出现"随机某个会话连不上内核"。

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 磁盘与平台同机部署(平台 + JCode 同时运行)

2.5 JCode 与平台的对应关系(便于排查)

JCode 需要的能力由平台的哪个服务提供默认地址
账号登录校验管理中心登录接口http://<平台IP>:3002/api/admin/login
登录令牌验签公钥管理中心公钥接口http://<平台IP>:3002/api/admin/auth/public-key
可用模型 / 供应商管理中心「模型(AI 资产)」同上域名
AI 用量与配额平台 AI 服务同上域名
打开代码工厂入口平台网关 /jcode/openhttp://<平台IP>:3003
记住一件事:JCode 只认 3002(管理中心直连),不认 3003(网关)。 3003 是给浏览器用的统一入口,网关会拦掉 JCode 需要的内部接口。这是现场最高频的错误来源。

三、安装前准备

3.1 确认平台侧已就绪

bash
# ① 管理中心在监听(返回 200 即通)
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3002/api/admin/auth/public-key

# ② 平台公钥文件存在(同机部署时 JCode 需要它)
ls -l /opt/jienor/jienor-ai/current/config/jwt-rsa-public.pem
  • 第①条返回 200:管理中心正常,可继续;
  • 返回 401 / 连接失败:说明填成了网关或平台未启动,先解决平台侧再装 JCode。
平台侧还需完成:登录管理中心 → 创建数据中心 → 初始化 → 启动 JWork 引擎 → 配置大模型 API Key。 详见《杰诺AI 平台 Linux 部署指南》第五节。

3.2 获取安装包与解压口令

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

3.3 校验安装包完整性

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

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

3.4 安装依赖

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.5 数据库准备

不需要手工建库。 JCode 自持一个独立库(默认名 jcode_db),由安装程序创建; 库表由引擎首次启动时自动迁移。

只需准备一个具备建库 / 建表权限的账号(可使用平台安装时的同一账号):

bash
mysql -h 127.0.0.1 -P 3306 -u <数据库账号> -p -e "SELECT VERSION();"
  • 版本需 ≥ 8.0;
  • 字符集建议 utf8mb4;
  • MySQL 的 root 默认只允许本机登录,同机部署请填 127.0.0.1,不要填公网/局域网 IP。
JCode 库与平台的管理库(jienor_admin)是两个库,不要合并。 平台的数据中心业务库是第三个,也不要混用。

3.6 解压安装包

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

解压后目录结构与平台包一致:

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

3.7 创建安装目录

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

四、执行安装

4.1 安装命令

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

JIENOR_PRODUCT=jcode \
JIENOR_INSTALL_DIR=/opt/jcode \
JIENOR_PACKAGE_PATH=/opt/jcode-setup/payload \
JIENOR_RESOURCE_ROOT=/opt/jcode-setup \
JIENOR_DB_HOST=127.0.0.1 \
JIENOR_DB_PORT=3306 \
JIENOR_DB_USER=<数据库账号> \
JIENOR_DB_PASSWORD='<MySQL口令>' \
JIENOR_DB_NAME=jcode_db \
JCODE_CENTER_ADDRESS=http://127.0.0.1:3002 \
JCODE_TRUSTED_HOSTS=<服务器IP>:3012 \
node run-cli.js 2>&1 | tee /opt/jcode-setup/install.log
需要替换的只有:数据库账号与口令、<服务器IP>。 `JCODE_CENTER_ADDRESS` 与 `JIENOR_DB_NAME` 请照抄,不要改——理由见 4.2。 JCode 不在本地建账号(库内没有用户表),登录一律走平台管理中心, 因此命令里不需要 JIENOR_ADMIN_USER / JIENOR_ADMIN_PASSWORD。

4.2 三个必须填对的参数

参数取值填错会怎样
JCODE_CENTER_ADDRESShttp://127.0.0.1:3002(管理中心直连端口)填 3003(网关)→ 登录时提示「账号验证通过,但本机会话校验失败」,且模型目录取不到
JIENOR_DB_NAMEjcode_db留空会回落到平台默认库名 jienor_admin,安装器把平台库也当作目标库一并处理,两个产品的库容易混在一起
JCODE_TRUSTED_HOSTS<服务器IP>:3012(裸主机名:端口,不带 `http://`)分机访问时 /api 一律 403(页面能开、但点任何功能都失败)

完整参数说明:

参数必填说明
JIENOR_PRODUCT✅固定 jcode,决定产品分支
JIENOR_INSTALL_DIR✅安装根目录,建议 /opt/jcode
JIENOR_PACKAGE_PATH✅指向解压目录下的 payload
JIENOR_RESOURCE_ROOT✅指向解压目录根
JIENOR_DB_HOST / PORT✅数据库地址与端口,同机填 127.0.0.1
JIENOR_DB_USER / PASSWORD✅数据库账号(需建库建表权限)
JIENOR_DB_NAME✅JCode 自持库名,固定 jcode_db
JCODE_CENTER_ADDRESS✅平台管理中心直连地址
JCODE_TRUSTED_HOSTS建议分机访问地址白名单,多个用逗号分隔
可选加强(同机部署推荐):再加两个参数,让安装器把平台公钥直接写到本地, 登录时就不必在页面上填管理中心地址: ``bash JCODE_CENTER_ALGORITHM=RS256 \ JCODE_CENTER_PUBLIC_KEY_FILE=/opt/jienor/jienor-ai/current/config/jwt-rsa-public.pem \ ` 是否生效,看安装日志里**有没有**下面这一行——有则说明未写入,按第五节第二步处理: [env-writer] ⚠ JCode 同机安装未探测到管理中心 RSA 公钥 … ⇒ 不写 JCODE_JWT_PUBLIC_KEY`

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 属正常。

安装日志中这几行是"装对了"的信号:

日志片段含义
[db-installer] 已用账号「…」连上 jcode_db独立库已就绪
[filetools-smoke] 退出码=0 ✅ 通过文件读写工具可用(沙箱与执行权限正常)
已生成《JCode分机访问指引.md》分机访问模板已按本机 IP 生成
健康检查 jcode / ✓ 健康检查验证引擎已起、前端资源已就位
安装程序不会配置开机自启,结尾也不会打印启停命令。装完请记下第七节的 start.sh / stop.sh 用法;需要服务器重启后自动拉起,按 7.3 配置。

五、安装后配置(关键步骤)

第一步:确认服务在线

bash
PM2_HOME=/opt/jcode/.pm2 pm2 list

期望:jienor-jcode 一行 online,重启次数(↺)为 0。

bash
ss -tlnp | grep 3012          # 期望:127.0.0.1:3012 在监听
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3012/health   # 期望:200

第二步:登录

shell
登录页:http://<服务器IP>:3012/login
(服务器本机可用 http://127.0.0.1:3012/login)
  • 账号口令就是平台的管理中心账号,JCode 不另建账号;
  • 登录页若出现「管理中心地址(可选)」输入框,请填 http://<服务器IP>:3002

(不是 3003)。填错或留空后若报「账号验证通过,但本机会话校验失败」,见 Q5。

第三步:让同网段电脑能访问(分机访问)

JCode 引擎默认只监听 127.0.0.1:3012。安装器已在安装根生成 JCode分机访问指引.md,按其中任意一种方式做转发即可(三选一,不要重复做):

方案适合特点
A. socat 前台转发最快验证关掉终端即失效,仅用于试通
B. nginx stream 四层转发已有 nginx 的现场推荐
C. systemd + socat 常驻生产、需开机自启推荐
bash
# 方案 A:最快验证(示例,<服务器IP> 需替换)
sudo apt install -y socat
sudo socat TCP-LISTEN:3012,bind=<服务器IP>,fork,reuseaddr TCP:127.0.0.1:3012

# 方案 B:nginx 四层转发(写在 nginx.conf 顶层,与 http{} 同级)
# stream {
#     server {
#         listen <服务器IP>:3012;
#         proxy_pass 127.0.0.1:3012;
#         proxy_connect_timeout 10s;
#         proxy_timeout 1h;    # 事件流是长连接,不能太短
#     }
# }
sudo nginx -t && sudo nginx -s reload
bash
# 防火墙放行
sudo ufw allow 3012/tcp

在另一台电脑上验证:

bash
curl -sS -o /dev/null -w '%{http_code}\n' http://<服务器IP>:3012/
  • 有状态码(200 / 302 / 401 都算通)⇒ 浏览器打开该地址即可;
  • connection refused ⇒ 转发没生效(看 ss -lntp | grep 3012);
  • 403 ⇒ 白名单未放行,见 Q4。

第四步:配置模型

不需要在 JCode 里填 API Key。 模型统一在 平台 → 管理中心 → 模型(AI 资产) 配置,JCode 启动后自动拉取模型目录。

验证:登录 JCode → 新建工作区 → 新建会话 → 模型下拉框里能看到管理中心配置的供应商。

若下拉框里只有内置/默认供应商、或管理中心改了 Key 而 JCode 无反应, 说明模型目录没拉到(日志会有 拉取管理中心模型目录失败),按 Q8 排查。

第五步:跑一次真实任务

  1. 1新建工作区(默认落在 /opt/jcode/workspaces/<工作区名>);
  2. 2新建会话,提一个能产出文件的小需求(例如"生成一个 README");
  3. 3对话完成后,产物应出现在工作区目录,右侧可预览、可下载。

六、安装结果核对

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

期望:jienor-jcode 为 online,↺(重启次数)为 0。

bash
# 端口监听
ss -tlnp | grep 3012

期望:127.0.0.1:3012(不要是 0.0.0.0:3012——引擎按安全护栏只绑回环)。

bash
# 健康与登录接口
curl -s -o /dev/null -w 'health=%{http_code}\n' http://127.0.0.1:3012/health
curl -s -o /dev/null -w 'login-page=%{http_code}\n' http://127.0.0.1:3012/login

期望:health=200、login-page=200。

bash
# 数据库(JCode 自持库)
mysql -h 127.0.0.1 -u <数据库账号> -p -e "SHOW DATABASES;" | grep -E 'jcode_db|jienor_admin'

期望:jcode_db 与平台的 jienor_admin 同时存在(两个库,互不替代)。

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

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


七、服务管理

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

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

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

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

文件(均位于安装根)作用什么时候用
start.sh启动引擎,交给 PM2 托管服务器重启后、服务停掉后
stop.sh停止本产品的服务升级、备份、迁移前
restart.sh逐个具名重启改过配置、服务卡死
start-dev.sh开发模式在前台起服务仅开发调试,生产请勿使用
JCode分机访问指引.md分机转发模板(按本机 IP 生成)需要让其他电脑访问时,见第五节第三步
ecosystem.config.cjs进程清单 + 运行时环境变量核对服务名、端口、env
bash
# 必须在安装根目录执行:脚本内部用相对路径定位 ecosystem.config.cjs
cd /opt/jcode
./start.sh      # 启动(已在运行时等价于重启)
./stop.sh       # 停止
./restart.sh    # 重启
用绝对路径调用时也请先 cd 到安装根,否则会提示找不到 ecosystem.config.cjs。 执行脚本的用户应为安装时使用的账号,不要用 sudo 跑。

7.2 常用命令

bash
export PM2_HOME=/opt/jcode/.pm2          # 建议写入 ~/.bashrc

pm2 list                                 # 查看状态
pm2 restart jienor-jcode                 # 重启引擎(不重读 env,见下)
pm2 logs jienor-jcode --lines 100         # 查看日志
pm2 stop all                             # 停止全部
pm2 save                                 # 保存当前进程清单
为什么必须带 `PM2_HOME`:每个安装根有独立的 PM2 实例。不带该变量时 pm2 list 看到的是空列表(或别的产品的进程),会误判为"服务没起来"。
改了运行配置要"删了重建",不是 restart:pm2 restart 不会重新读取 ecosystem.config.cjs。改完需: pm2 delete jienor-jcode && pm2 start ecosystem.config.cjs(再 pm2 save)。

7.3 开机自启

安装程序不会自动配置开机自启。 服务器重启后服务不会自己起来,需手工 ./start.sh。 要长期无人值守,请用 PM2 方式:

bash
export PM2_HOME=/opt/jcode/.pm2

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

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

验证:

bash
systemctl list-unit-files | grep -i pm2     # 应能查到 pm2-<用户名> 且为 enabled

# 重启服务器后确认(重启前请确认业务空闲)
sudo reboot
PM2_HOME=/opt/jcode/.pm2 pm2 list
只在"服务已正常"时执行 pm2 save。 不同 PM2 版本提示文案略有差异,按其输出执行;若提示找不到 pm2,用 npx pm2 代替。
关于安装根里的 `install-systemd.sh` / `systemd/`:部分版本的 systemd/ 目录为空, 该脚本只做文件复制、不会 enable/start,执行后不会产生任何服务,请勿依赖它。 若你的版本 systemd/ 下确有 *.service 文件,也不建议与 PM2 同时使用—— 两套托管会争抢同一批端口(详见《杰诺AI 平台 Linux 部署指南》7.3 的说明)。

7.4 日志与配置位置

内容路径
引擎输出/错误/opt/jcode/.pm2/logs/jienor-jcode-out.log / -error.log
安装日志安装时 tee 指定的文件(见 4.1)
安装器自留日志/opt/jcode/logs/install.log
运行配置(含密钥,保密)/opt/jcode/current/config/env
进程清单(运行期实际生效)/opt/jcode/ecosystem.config.cjs
对外访问配置/opt/jcode/config/jcode-external.json
端口解析结果/opt/jcode/config/ports.json
工作区产物/opt/jcode/workspaces/<工作区名>
内核会话数据/opt/jcode/.dsh-jcode
注意:JCode 的运行环境由 ecosystem.config.cjs 决定,改 current/config/env 不一定生效;两处都改、再 pm2 delete + pm2 start 最稳妥。

八、数据与备份

8.1 需要备份的内容

内容说明
jcode_db工作区、会话、任务、用量等结构化数据
/opt/jcode/workspacesAI 生成的代码产物(体积最大,最不可再生)
/opt/jcode/.dsh-jcode内核会话与运行态数据
/opt/jcode/uploads用户上传的附件(按实际使用情况,可能为空)
/opt/jcode/current/config运行配置(含密钥,须保密)
/opt/jcode/config/jcode-external.json对外访问地址与白名单

8.2 备份命令

bash
# 1) 数据库(先停服务更稳,也可用 --single-transaction 在线备份)
mysqldump -h 127.0.0.1 -u <数据库账号> -p --single-transaction --routines --triggers \
  jcode_db > /backup/jcode_db_$(date +%F).sql

# 2) 工作区产物(体积大,建议单独定期备份)
tar czf /backup/jcode-workspaces_$(date +%F).tgz -C /opt/jcode workspaces

# 3) 配置与会话数据(含密钥,务必保密)
tar czf /backup/jcode-config_$(date +%F).tgz -C /opt/jcode config .dsh-jcode
工作区产物是 JCode 里最值钱的数据,且不在数据库里。 只备份数据库、不备份 workspaces/,等于把客户生成的代码全部丢掉。

九、升级与卸载

9.1 升级(覆盖安装)

  1. 1先备份(见第八节,尤其 workspaces/);
  2. 2停止服务:PM2_HOME=/opt/jcode/.pm2 pm2 stop all
  3. 3下载并解压新版本安装包(步骤同第三节);
  4. 4用新版安装程序执行安装,`JIENOR_INSTALL_DIR` 指向原安装目录

(覆盖安装,不要删旧目录、不要删库、不要删 workspaces/);

  1. 1装完核对:PM2_HOME=/opt/jcode/.pm2 pm2 list,再看 current 指向是否为新版本;
  2. 2重新登录一次,确认模型与工作区都在。
升级不需要卸载,也不需要重新建库。 若发布说明要求"全新安装",请以发布说明为准,不要套用本节。

9.2 卸载

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

# 2) 如做过分机转发常驻,一并移除
sudo systemctl disable --now jcode-extproxy 2>/dev/null
sudo rm -f /etc/systemd/system/jcode-extproxy.service

# 3) 删除安装目录(⚠ 内含 workspaces/ 产物,务必先备份)
sudo rm -rf /opt/jcode

# 4) 删除数据库(谨慎,数据不可恢复)
mysql -h 127.0.0.1 -u <数据库账号> -p -e "DROP DATABASE jcode_db;"
平台的管理库 `jienor_admin` 与数据中心业务库不要动——它们属于平台,与 JCode 无关。

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

10.1 什么时候需要

  • 客户要求用域名访问代码工厂,而不是 IP:3012;
  • 需要 HTTPS;
  • 希望只对外开放 80/443,把 3012 收进内网。
平台已部署时,也可以在平台门户里点「代码工厂」入口进入(走平台网关)。 但JCode 自身的登录与 API 仍需直连 3012,所以分机访问这一层转发不能省。

10.2 JCode 反代必须做对的三件事

#要求配错的后果
1关闭响应缓冲(proxy_buffering off)对话过程被攒住,页面一直"生成中"
2读写超时放长(≥ 3600 秒)长任务中途断开
3把对外域名加入白名单 JCODE_TRUSTED_HOSTS/api 全 403:页面能开、功能全废

白名单写法:裸主机名(含非默认端口),不带 `http://`,多个用逗号分隔,例如:

bash
# 编辑 ecosystem 后必须"删了重建"才生效
JCODE_TRUSTED_HOSTS=jcode.example.com,<服务器IP>:3012
bash
# 改完 ecosystem.config.cjs 后
PM2_HOME=/opt/jcode/.pm2 pm2 delete jienor-jcode
PM2_HOME=/opt/jcode/.pm2 pm2 start ecosystem.config.cjs
PM2_HOME=/opt/jcode/.pm2 pm2 save

10.3 nginx 配置示例(七层,直接代理 3012)

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

    client_max_body_size 200m;

    location / {
        proxy_pass http://127.0.0.1:3012;
        proxy_http_version 1.1;
        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_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:3012;
        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;
    }
}
注意 proxy_set_header Host $host; 会让后端看到的 Host 变成对外域名, 因此白名单里必须包含该域名,否则 /api 会 403。

10.4 启用 HTTPS

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

10.5 验证

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

# 接口不被白名单拦(401 = 通,只差会话;403 = 白名单未放行)
curl -s -o /dev/null -w '%{http_code}\n' https://<域名>/health

浏览器侧:F12 → Network,对话进行时 /api/remote.mux 应处于 pending(长连接); 若很快结束,说明缓冲没关。


十一、常见问题

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

Q2:Linux 上没有图形安装界面? 是的。Linux 版仅提供命令行安装(见第四节)。图形向导仅在 Windows 版提供。

Q3:本机能打开 `127.0.0.1:3012`,但同事打不开 `http://<服务器IP>:3012`? 这是设计如此:引擎只监听回环地址。需要按第五节第三步做一次端口转发(安装根已生成 JCode分机访问指引.md,内含三种现成模板),并放行防火墙。

Q4:分机打开页面正常,但点任何功能都 `403`? 白名单没放行。JCODE_TRUSTED_HOSTS 必须是浏览器地址栏里的主机名(裸 authority, 不带 http://),例如 <服务器IP>:3012 或 jcode.example.com。 改完要 pm2 delete + pm2 start 才生效(restart 不重读)。

Q5:登录提示"账号验证通过,但本机会话校验失败"? 说明 JCode 取不到平台的验签公钥,最常见原因是管理中心地址填成了网关 3003:

  1. 1在登录页把「管理中心地址」改为 http://<服务器IP>:3002,重新登录一次

(该地址会被记到配置里,覆盖旧的错误值);

  1. 1仍失败则检查平台侧:curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3002/api/admin/auth/public-key

应返回 200;

  1. 1同机部署还可把平台公钥直接指给 JCode(见 4.2 的可选加强项),彻底摆脱运行期拉取。

Q6:登录页的「管理中心地址」到底填哪个? 填管理中心的直连端口(默认 3002),不要填业务入口 3003。 3003 是给浏览器用的统一网关,会把 JCode 需要的内部接口拦掉。

Q7:服务是 online,但页面打不开 / 登录不了?

  1. 1确认访问的是 http://<IP>:3012,不是 3003、也不是 5173;
  2. 2确认平台的 3002 可达(见 Q5 第 2 条);
  3. 3看 PM2_HOME=/opt/jcode/.pm2 pm2 logs jienor-jcode --lines 50 的首个错误;
  4. 4若刚改过配置,用 pm2 delete + pm2 start 重来一次。

Q8:模型下拉框里没有管理中心配置的供应商 / 管理中心改了 Key 但 JCode 没反应? 先看日志有没有 拉取管理中心模型目录失败:

bash
PM2_HOME=/opt/jcode/.pm2 pm2 logs jienor-jcode --lines 80 | grep -i "模型目录\|供应商"

有该行说明 JCode 没能取到平台模型目录,此时它会回落到本地配置的模型—— 表现是"对话能用,但管理中心改了 Key / 换了模型都不跟随",容易误判为已经正常。 排查顺序:① 3002 是否可达;② 平台是否已配置模型 Key;③ 两个产品的内部调用密钥是否一致 (跨产品部署场景,需服务顾问协助核对)。同一现象还可能伴随"配额未生效"的日志提示。

Q9:生成的子系统重启后不自动起来? AI 生成的子系统默认以独立进程方式启动(不归 PM2/systemd 托管), 服务器重启或 JCode 重启后需要重新启动该子系统。平台运维中心里也看不到它, 只能通过心跳判断在线。生产环境如需常驻,请为该子系统单独配置托管。

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

Q11:启动报端口被占用(`EADDRINUSE`)? 3012 已被别的进程占用。先查是谁:

bash
ss -tlnp | grep 3012

若是上次安装残留的进程(父进程为 1、工作目录已删除),先结束它再启动; 多产品同机部署时,还要确认内核端口段(见 2.3)没有与平台重叠。

Q12:忘记登录口令? JCode 使用平台的管理中心账号,请在平台侧重置(见平台部署指南 Q9), JCode 本身不单独存账号口令。

Q13:Windows 上做的配置/脚本,拷到 Linux 后路径报错? 生成物或模板中若出现 D:/...、D:\... 这类盘符路径,属模板遗留, 请改为工作区实际路径(/opt/jcode/workspaces/...)。遇到时建议反馈给服务顾问。


附录 A:安装参数速查

bash
JIENOR_PRODUCT=jcode                          # 产品标识(固定)
JIENOR_INSTALL_DIR=/opt/jcode                 # 安装根目录
JIENOR_PACKAGE_PATH=<解压目录>/payload         # 载荷目录
JIENOR_RESOURCE_ROOT=<解压目录>                # 资源根
JIENOR_DB_HOST=127.0.0.1                      # 数据库地址
JIENOR_DB_PORT=3306                           # 数据库端口
JIENOR_DB_USER=<数据库账号>                    # 数据库账号
JIENOR_DB_PASSWORD=<口令>                      # 数据库口令
JIENOR_DB_NAME=jcode_db                       # JCode 自持库(固定)
JCODE_CENTER_ADDRESS=http://127.0.0.1:3002    # 管理中心直连(不要填 3003)
JCODE_TRUSTED_HOSTS=<服务器IP>:3012            # 分机访问白名单(裸 authority)

# 可选加强:让安装器直接写入平台公钥
# JCODE_CENTER_ALGORITHM=RS256
# JCODE_CENTER_PUBLIC_KEY_FILE=/opt/jienor/jienor-ai/current/config/jwt-rsa-public.pem

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

shell
/opt/jcode/
├── current -> versions/<ver>/      # 当前版本(软链接)
│   └── config/
│       ├── env                     # 运行配置(含密钥,保密)
│       └── jwt-rsa-*.pem           # 本产品的签名密钥对
├── versions/                       # 历次安装版本
├── config/
│   ├── jcode-external.json         # 对外访问地址与白名单
│   └── ports.json                  # 本次安装解析出的端口清单
├── ecosystem.config.cjs            # PM2 进程清单(启动入口、运行期 env)
├── start.sh / stop.sh / restart.sh  # 启停脚本(安装时生成)
├── start-dev.sh                    # 开发模式启动(生产不用)
├── JCode分机访问指引.md             # 分机转发模板(按本机 IP 生成)
├── workspaces/                     # ★ AI 生成的代码产物(务必备份)
├── .dsh-jcode/                     # 内核会话与运行态数据
├── .pm2/                           # 本安装根专属的 PM2 实例与日志
└── logs/

附录 C:部署检查清单

检查项完成
平台已安装、数据中心已「已初始化」、JWork 引擎运行中☐
平台管理中心 3002 返回 200(/api/admin/auth/public-key)☐
安装包 SHA-256 与官网公布值一致☐
Node.js 版本与 MANIFEST.json 的 nodeVersion 一致☐
MySQL ≥ 8.0,且数据库账号验证通过☐
JCODE_CENTER_ADDRESS 填的是 3002,不是 3003☐
JIENOR_DB_NAME=jcode_db☐
安装日志出现 === 安装完成 ===☐
安装日志出现 [filetools-smoke] 退出码=0☐
pm2 list 中 jienor-jcode 为 online、重启次数 0☐
3012 仅监听 127.0.0.1(未绑 0.0.0.0)☐
已能登录(账号 = 平台管理中心账号)☐
分机访问已验证(转发 + 防火墙 + 白名单)☐
模型下拉框能看到管理中心配置的供应商☐
已跑通一次真实任务,产物落在 workspaces/☐
需要无人值守时,已按 7.3 配置 PM2 开机自启☐
jcode_db 与 workspaces/ 已做首次备份☐

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

检查项完成
仅代理 3012,未把内核端口段(9000+/30900+)对外☐
已关闭响应缓冲并放长超时☐
对外域名已加入 JCODE_TRUSTED_HOSTS(裸 authority)☐
浏览器 Network 中事件流请求为 pending 长连接☐
HTTPS 证书有效且自动续期☐

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

部署过程中遇到问题?

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