跳到主要内容

常见问题

本页汇总 JumpServer 技术交流群中用户咨询频率较高的常见问题及处理方式，内容持续更新。知识库文章与更多资料索引可参阅产品 FAQ。

1 版本升级​

1.1 v3、v4 能否直接升级到 v5？​

问题：v3、v4 各版本能否直接升级到 v5？

处理方式：

  • v4 升级 v5：v4 到 v5 的数据库迁移连续可前滚，v4 各版本可直接升级到 v5，无需额外前置操作。若当前为较早期的 v4.0.0 版本，建议先升级到 v4 最新版本（v4.10.19 LTS）再升级到 v5。
  • v3 升级 v5：无法一步到位。需先将当前版本升级到 v3 最新版本（v3.10.23 LTS），再升级到 v4，最后升级到 v5，否则会因表结构变更导致升级失败。

详细升级步骤与离线包下载地址，请参阅升级指南。

1.2 升级到 v5 后页面打不开，提示 400 / 403？​

问题：升级到 v5 后无法打开页面（登录界面），浏览器提示错误码 400 或 403。

处理方式：需要填写 DOMAINS 可信任域名。打开 /opt/jumpserver/config/config.txt，按实际访问方式配置 DOMAINS 字段。v5 中 DOMAINS 取值需要带上端口（HTTPS 使用 443，HTTP 使用 80），多个地址之间使用英文逗号分隔，修改后重启 JumpServer 服务：

vim /opt/jumpserver/config/config.txt

# 使用域名访问（HTTPS）
DOMAINS="demo.jumpserver.org:443"
# 使用 IP 访问（HTTP）
DOMAINS="172.17.200.191:80"
# 同时使用域名与 IP 访问
DOMAINS="demo.jumpserver.org:443,172.17.200.191:80"

# 重启 JumpServer 服务生效
jmsctl restart
  • 若服务器为一键安装，且旧版本已使用 JumpServer 开启 HTTPS，则无需修改。
  • 使用 IP 地址访问 JumpServer 时，请根据实际网络环境填写公网 IP 或内网 IP。

1.3 升级到 v5 后发现没有 lion 组件？​

问题：v5 的容器编排文件或组件列表中看不到 lion 组件。

处理方式：v5 中 lion 的功能已合并到 koko。升级后若组件列表中残留处于离线状态的 lion，可在「系统设置 → 组件列表」中将其删除。

1.4 restore_db 恢复前需删除旧表吗？​

问题：使用 ./jmsctl.sh restore_db 恢复数据库时，是否需要先删除旧库中的表？

处理方式：

需要。执行恢复前，请先删除目标数据库中的所有表，否则部分表可能因结构或数据冲突导致恢复异常。恢复文件应使用升级前或备份时生成的原始备份文件。

详细备份恢复步骤请参阅数据备份以及恢复指南。

2 环境与数据库要求​

JumpServer 对操作系统内核、数据库与缓存的版本要求，详见环境要求。

2.1 内核版本低于 4.0 能否升级？​

问题：机器的 Linux 内核版本低于 4.0，能否升级？

处理方式：JumpServer 要求 Linux 内核 >= 4.0（amd64、arm64 架构均为该要求），内核版本低于 4.0 无法直接升级。建议先升级操作系统内核，或将数据迁移至满足要求的机器后再进行升级。

2.2 v5 对数据库版本有什么要求？MySQL 5.7 还能继续使用吗？​

问题：v5 对数据库版本有什么要求？原来使用的 MySQL 5.7 是否还能继续使用？

处理方式：v5 要求 MySQL >= 8.0、PostgreSQL >= 16、MariaDB >= 10.6，缓存要求 Redis >= 7.0；安装时默认使用内置的 PostgreSQL 与 Redis。若原环境使用 MySQL 5.7，需先升级到 8.0 及以上版本。

2.3 内网和外网如何同时访问？​

问题：配置了外网地址后内网无法访问，或配置了内网地址后外网无法访问（登录提示需要配置 DOMAINS 参数），如何实现内外网同时访问？

处理方式：

JumpServer 支持同时配置多个访问地址（如内网 IP 和外网域名/IP），以实现内外网用户均可访问。

处理方法：

  1. 如果是 1Panel 部署的 JumpServer，在应用参数中配置 DOMAINS；若为常规离线部署，则在 /opt/jumpserver/config/config.txt 中配置。若需支持多个地址，请使用英文逗号分隔。
  2. 例如：192.168.1.100,example.com。
  3. 修改配置后，需重启服务或重建容器使配置生效。

注意：

  • 确保防火墙已放行对应端口（如 80, 443, 2222 等）。
  • 若使用 Nginx 反向代理，需确保 Nginx 配置中 server_name 也包含所有访问域名/IP。

详细网络端口及防火墙配置说明，请参阅网络端口说明。

3 资产管理​

3.1 Web 资产无登录页或空账号如何配置？​

问题：连接华为防火墙等 Web 管理页面时，若无需自动登录或账号为空，如何配置 Web 资产？

处理方式：

针对无需身份验证或账号为空的 Web 资产（如部分防火墙管理页），请按以下步骤配置：

  1. 配置发布机：确保已在 系统设置 > 远程应用 中配置好发布机，否则 Web 资产无法打开。
  2. 创建 Web 资产：在 控制台 > 资产管理 > 资产列表 > Web 页签中创建资产，填写目标 URL。
  3. 设置自动代填：在创建或编辑资产时，找到 选择器 分组下的 自动代填 选项，选择 禁用。
    • 文档说明：选择 禁用 后，不再显示用户名、密码等选择器，适用于无需身份验证的网站。
  4. 绑定账号：在 账号 分组中，若确实无需账号，可添加一个虚拟账号或留空（视具体平台校验而定，但核心是禁用代填逻辑）。

⚠️ 注意：若选择“基本”代填，系统会尝试填写账号密码，可能导致连接失败或报错。对于无登录页场景，必须选择“禁用”。

详细配置字段说明及自动代填模式区别，请参阅 Web 资产。

3.2 v5 是否去除了脚本代填功能？​

问题：升级到 v5 后，Web 资产的脚本代填功能是否被移除？

处理方式：

v5 社区版未包含 Web 资产的脚本代填功能，该功能为企业版特性。社区版 Web 资产仅支持“禁用”和“基本”两种自动代填模式。

4 客户端与终端​

4.1 v5 Web终端连接Windows如何传输文件？​

问题：升级到 v5 后，Web 终端连接 Windows 资产时找不到文件传输入口（小齿轮图标），如何传输文件？

处理方式：

v5 版本 Web 终端（Luna）的文件传输功能入口已调整。连接资产后，请单击 Web 终端界面右上角的侧边栏按钮，在侧边栏中找到 文件传输 功能进行上传或下载操作。

4.2 v5 Web终端选中文字无法自动复制？​

问题：升级到 v5 后，Web 终端选中文字无法自动复制到剪贴板，需要手动 Ctrl+C，之前版本会自动复制。

处理方式：

v5 版本 Web 终端（Luna）默认行为已调整，选中文字不再自动复制到剪贴板，需手动执行复制操作（如 Ctrl + C 或右键菜单选择复制）。官方确认该体验将在下个版本中优化。

5 AI 助手配置与故障​

5.1 AI助手对话失败如何排查？​

问题：AI助手所有对话都失败，如何排查配置问题？

处理方式：

在 系统设置 > AI 助手 页面，确认 接入方式 为 内置 API 时，需检查 服务地址（通常以 /v1 结尾）、API 密钥 及 模型 配置是否正确。点击表单底部的 测试 按钮，若提示“连接成功，模型支持工具调用”则配置有效；若失败，请检查网络连通性及模型是否支持工具调用（目前仅支持 Responses 格式）。若使用 iframe 嵌入，请确保填写的页面地址允许 iframe 嵌入。

详细配置参数说明，请参阅 AI 助手。