| 项目 | 说明 |
|---|---|
| 适用对象 | 客户实施人员 / 系统管理员 |
| 文档性质 | 全新安装(首次部署);升级与卸载见第九节 |
| 适用范围 | 不绑定具体版本,适用于当前及后续 Linux x64 版本 |
| 前置条件 | 必须先部署并初始化「杰诺AI 一体化平台」(见〇.2) |
| 最近更新 | 2026-11-08 |
〇、使用本文档前请先读这三件事
- 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口令> | 数据库账号口令 | 自行设定 |
- 1JCode 不是独立系统,它依赖「杰诺AI 一体化平台」。
登录鉴权、可用模型、AI 配额都由平台的管理中心提供。因此部署顺序是: 先装平台 → 完成数据中心初始化 → 再装 JCode。 平台尚未就绪就装 JCode,会表现为"服务在线但登录不上 / 模型列表为空",这不是 JCode 安装失败。
- 1JCode 引擎只监听本机回环(`127.0.0.1`),这是安全设计,不是故障。
装完在本机 curl 127.0.0.1:3012 是通的,但从其他电脑直接打开 http://<服务器IP>:3012 会"拒绝连接"。
要让同网段同事访问,需按第五节第三步做一次端口转发(安装器已生成现成模板)。
一、部署流程总览
① 平台已就绪(含数据中心初始化)
↓
② 环境准备 → ③ 下载校验 → ④ 解压 → ⑤ 执行安装
↓
⑦ 业务验证 ← ⑥ 登录 + 分机访问配置| 阶段 | 预计耗时 | 关键产出 |
|---|---|---|
| 环境准备 | 10–20 分钟(可与平台共用) | Node.js、MySQL、解压工具就绪 |
| 安装 | 1–3 分钟 | jienor-jcode 服务在线,jcode_db 建库完成 |
| 登录与访问配置 | 5–15 分钟 | 能登录、分机能打开、模型可选 |
二、环境要求
2.1 服务器
| 项目 | 最低 | 推荐 |
|---|---|---|
| 操作系统 | Ubuntu 24.04 LTS(x86_64) | 同左 |
| CPU | 4 核 | 8 核(代码生成与构建较吃 CPU) |
| 内存 | 4 GB | 8 GB 以上(JCode 引擎常驻约 0.8–1 GB) |
| 磁盘 | 20 GB 可用 | 50 GB 以上(工作区产物增长较快,见 8.2) |
| 网络 | 能访问平台管理中心与数据库 | 同左 |
2.2 依赖软件
| 软件 | 版本要求 | 说明 |
|---|---|---|
| Node.js | 以安装包 `MANIFEST.json` 的 `nodeVersion` 为准 | 与平台要求通常一致;安装程序会自动装 PM2,但不会装 Node |
| MySQL | 8.0 及以上 | 与平台共用同一实例即可 |
| 解压工具 | unrar 或 7-Zip | 安装包为加密 RAR,需输入解压口令 |
| curl | 任意 | 用于下载、校验与自检 |
| 杰诺AI 平台 | 已安装且数据中心已初始化 | 提供登录鉴权、模型目录、AI 配额 |
如何确认本包要求的 Node 版本(解压后执行,避免凭经验装错):
# 在解压目录中执行
python3 -c "import json;print(json.load(open('MANIFEST.json'))['nodeVersion'])"mysql_native_password 认证插件。
若后续对接的应用或驱动较老,连接会直接报 Plugin 'mysql_native_password' is not loaded,
且无法通过配置开关恢复。老系统请选用 MySQL 8.4 LTS。2.3 端口规划
| 端口 | 用途 | 是否对外 |
|---|---|---|
| 3012 | JCode 引擎(Web + API) | ❌ 默认仅本机;分机访问需转发,见第五节第三步 |
| 3002 | 平台管理中心服务(JCode 登录、取钥、取模型目录) | ❌ 内部,但 JCode 必须能访问 |
| 3003 | 平台统一入口(网关) | 由平台负责,JCode 不直接用 |
| 22 | SSH 运维 | 按需 |
| 3306 | MySQL | 建议仅本机 |
| 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.js | 24.15.0 | 与当次安装包 MANIFEST.json 的 nodeVersion 一致 |
| MySQL | 9.7.4 | 8.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/open | http://<平台IP>:3003 |
三、安装前准备
3.1 确认平台侧已就绪
# ① 管理中心在监听(返回 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。
3.2 获取安装包与解压口令
- 1在官网「产品更新」页下载 JCode Linux 安装包,记录文件名;
- 2记录该版本页面上公布的 SHA-256;
- 3通过页面「获取解压口令」向服务顾问申请口令(同版本多平台包通用)。
3.3 校验安装包完整性
# 示例:<安装包文件名> 需替换为实际文件名
sha256sum <安装包文件名>
# 例:sha256sum JCode-Setup-X.Y.Z-linux-x64.rar将输出与官网公布值逐字符比对,不一致请重新下载,不要使用。
3.4 安装依赖
# 解压工具
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 -vhttps://npmmirror.com/mirrors/node/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz3.5 数据库准备
不需要手工建库。 JCode 自持一个独立库(默认名 jcode_db),由安装程序创建;
库表由引擎首次启动时自动迁移。
只需准备一个具备建库 / 建表权限的账号(可使用平台安装时的同一账号):
mysql -h 127.0.0.1 -P 3306 -u <数据库账号> -p -e "SELECT VERSION();"- 版本需 ≥ 8.0;
- 字符集建议
utf8mb4; - MySQL 的
root默认只允许本机登录,同机部署请填127.0.0.1,不要填公网/局域网 IP。
jienor_admin)是两个库,不要合并。
平台的数据中心业务库是第三个,也不要混用。3.6 解压安装包
# 示例:<安装包文件名> 与 <解压口令> 均需替换
sudo mkdir -p /opt/jcode-setup
sudo chown $USER:$USER /opt/jcode-setup
cd /opt/jcode-setup
unrar x -p'<解压口令>' <安装包文件名>解压后目录结构与平台包一致:
/opt/jcode-setup/
├── MANIFEST.json # 安装清单、校验和、依赖的 Node 版本
├── payload/ # 待安装产品载荷
│ ├── install-wizard/ # 安装程序
│ ├── backend/ frontend/ …
│ └── version.json
└── devkit/ # 子系统开发工具包(普通部署用不到)3.7 创建安装目录
sudo mkdir -p /opt/jcode
sudo chown -R $USER:$USER /opt/jcodeubuntu)执行安装,不要用 `sudo node ...`。
以 root 运行会使进程与文件归属变为 root,后续运维需全程 sudo,容易出错。四、执行安装
4.1 安装命令
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_ADDRESS | http://127.0.0.1:3002(管理中心直连端口) | 填 3003(网关)→ 登录时提示「账号验证通过,但本机会话校验失败」,且模型目录取不到 |
JIENOR_DB_NAME | jcode_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 个步骤:
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 配置。五、安装后配置(关键步骤)
第一步:确认服务在线
PM2_HOME=/opt/jcode/.pm2 pm2 list期望:jienor-jcode 一行 online,重启次数(↺)为 0。
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第二步:登录
登录页: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 常驻 | 生产、需开机自启 | 推荐 |
# 方案 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# 防火墙放行
sudo ufw allow 3012/tcp在另一台电脑上验证:
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 → 新建工作区 → 新建会话 → 模型下拉框里能看到管理中心配置的供应商。
拉取管理中心模型目录失败),按 Q8 排查。第五步:跑一次真实任务
- 1新建工作区(默认落在
/opt/jcode/workspaces/<工作区名>); - 2新建会话,提一个能产出文件的小需求(例如"生成一个 README");
- 3对话完成后,产物应出现在工作区目录,右侧可预览、可下载。
六、安装结果核对
# 进程状态(注意必须带 PM2_HOME)
PM2_HOME=/opt/jcode/.pm2 pm2 list期望:jienor-jcode 为 online,↺(重启次数)为 0。
# 端口监听
ss -tlnp | grep 3012期望:127.0.0.1:3012(不要是 0.0.0.0:3012——引擎按安全护栏只绑回环)。
# 健康与登录接口
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。
# 数据库(JCode 自持库)
mysql -h 127.0.0.1 -u <数据库账号> -p -e "SHOW DATABASES;" | grep -E 'jcode_db|jienor_admin'期望:jcode_db 与平台的 jienor_admin 同时存在(两个库,互不替代)。
# 启停脚本已生成(安装时按本机路径生成,**不在解压包内**,见 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 |
# 必须在安装根目录执行:脚本内部用相对路径定位 ecosystem.config.cjs
cd /opt/jcode
./start.sh # 启动(已在运行时等价于重启)
./stop.sh # 停止
./restart.sh # 重启cd 到安装根,否则会提示找不到 ecosystem.config.cjs。
执行脚本的用户应为安装时使用的账号,不要用 sudo 跑。7.2 常用命令
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 list
看到的是空列表(或别的产品的进程),会误判为"服务没起来"。pm2 restart 不会重新读取
ecosystem.config.cjs。改完需:
pm2 delete jienor-jcode && pm2 start ecosystem.config.cjs(再 pm2 save)。7.3 开机自启
安装程序不会自动配置开机自启。 服务器重启后服务不会自己起来,需手工 ./start.sh。
要长期无人值守,请用 PM2 方式:
export PM2_HOME=/opt/jcode/.pm2
pm2 startup
# ↑ 该命令会打印一条以 sudo 开头的命令,复制并执行它(需 root 写 systemd 单元)
pm2 save
# ↑ 保存当前进程清单,开机按此清单恢复验证:
systemctl list-unit-files | grep -i pm2 # 应能查到 pm2-<用户名> 且为 enabled
# 重启服务器后确认(重启前请确认业务空闲)
sudo reboot
PM2_HOME=/opt/jcode/.pm2 pm2 listpm2 save。
不同 PM2 版本提示文案略有差异,按其输出执行;若提示找不到 pm2,用 npx pm2 代替。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 |
ecosystem.config.cjs 决定,改 current/config/env
不一定生效;两处都改、再 pm2 delete + pm2 start 最稳妥。八、数据与备份
8.1 需要备份的内容
| 内容 | 说明 |
|---|---|
jcode_db | 工作区、会话、任务、用量等结构化数据 |
/opt/jcode/workspaces | AI 生成的代码产物(体积最大,最不可再生) |
/opt/jcode/.dsh-jcode | 内核会话与运行态数据 |
/opt/jcode/uploads | 用户上传的附件(按实际使用情况,可能为空) |
/opt/jcode/current/config | 运行配置(含密钥,须保密) |
/opt/jcode/config/jcode-external.json | 对外访问地址与白名单 |
8.2 备份命令
# 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-jcodeworkspaces/,等于把客户生成的代码全部丢掉。九、升级与卸载
9.1 升级(覆盖安装)
- 1先备份(见第八节,尤其
workspaces/); - 2停止服务:
PM2_HOME=/opt/jcode/.pm2 pm2 stop all - 3下载并解压新版本安装包(步骤同第三节);
- 4用新版安装程序执行安装,`JIENOR_INSTALL_DIR` 指向原安装目录
(覆盖安装,不要删旧目录、不要删库、不要删 workspaces/);
- 1装完核对:
PM2_HOME=/opt/jcode/.pm2 pm2 list,再看current指向是否为新版本; - 2重新登录一次,确认模型与工作区都在。
9.2 卸载
# 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;"十、反向代理与 HTTPS(生产推荐)
10.1 什么时候需要
- 客户要求用域名访问代码工厂,而不是
IP:3012; - 需要 HTTPS;
- 希望只对外开放 80/443,把 3012 收进内网。
10.2 JCode 反代必须做对的三件事
| # | 要求 | 配错的后果 |
|---|---|---|
| 1 | 关闭响应缓冲(proxy_buffering off) | 对话过程被攒住,页面一直"生成中" |
| 2 | 读写超时放长(≥ 3600 秒) | 长任务中途断开 |
| 3 | 把对外域名加入白名单 JCODE_TRUSTED_HOSTS | /api 全 403:页面能开、功能全废 |
白名单写法:裸主机名(含非默认端口),不带 `http://`,多个用逗号分隔,例如:
# 编辑 ecosystem 后必须"删了重建"才生效
JCODE_TRUSTED_HOSTS=jcode.example.com,<服务器IP>:3012# 改完 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 save10.3 nginx 配置示例(七层,直接代理 3012)
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
sudo apt install -y nginx certbot python3-certbot-nginx
sudo certbot --nginx -d <域名>10.5 验证
# 页面可访问(应返回 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在登录页把「管理中心地址」改为
http://<服务器IP>:3002,重新登录一次
(该地址会被记到配置里,覆盖旧的错误值);
- 1仍失败则检查平台侧:
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3002/api/admin/auth/public-key
应返回 200;
- 1同机部署还可把平台公钥直接指给 JCode(见 4.2 的可选加强项),彻底摆脱运行期拉取。
Q6:登录页的「管理中心地址」到底填哪个?
填管理中心的直连端口(默认 3002),不要填业务入口 3003。
3003 是给浏览器用的统一网关,会把 JCode 需要的内部接口拦掉。
Q7:服务是 online,但页面打不开 / 登录不了?
- 1确认访问的是
http://<IP>:3012,不是3003、也不是5173; - 2确认平台的 3002 可达(见 Q5 第 2 条);
- 3看
PM2_HOME=/opt/jcode/.pm2 pm2 logs jienor-jcode --lines 50的首个错误; - 4若刚改过配置,用
pm2 delete+pm2 start重来一次。
Q8:模型下拉框里没有管理中心配置的供应商 / 管理中心改了 Key 但 JCode 没反应?
先看日志有没有 拉取管理中心模型目录失败:
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 已被别的进程占用。先查是谁:
ss -tlnp | grep 3012若是上次安装残留的进程(父进程为 1、工作目录已删除),先结束它再启动; 多产品同机部署时,还要确认内核端口段(见 2.3)没有与平台重叠。
Q12:忘记登录口令? JCode 使用平台的管理中心账号,请在平台侧重置(见平台部署指南 Q9), JCode 本身不单独存账号口令。
Q13:Windows 上做的配置/脚本,拷到 Linux 后路径报错?
生成物或模板中若出现 D:/...、D:\... 这类盘符路径,属模板遗留,
请改为工作区实际路径(/opt/jcode/workspaces/...)。遇到时建议反馈给服务顾问。
附录 A:安装参数速查
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:安装后的目录结构
/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 证书有效且自动续期 | ☐ |
*本文档如与产品实际行为不符,请以官网最新发布说明为准;如有疑问,请联系服务顾问。*
