Ubuntu 22.04 安装 Jan 0.8.7 指南

目标：在 Ubuntu 22.04 上从零安装 Jan 0.8.7（官方桌面 AI 助手，含 llama.cpp 本地推理引擎与 OpenAI 兼容 API 服务器），覆盖 deb 与 AppImage 两种安装方案、降级/升级管理、验证与卸载。已在 Ubuntu 22.04（x86_64）环境对全部命令实测通过，安装包 sha256 与官方 Release 页比对一致。

一、环境信息

操作系统：Ubuntu 22.04（x86_64，jammy）
软件版本：Jan 0.8.7（官方最新稳定版，2026-10-20 发布，查询日期 2026-10-22）
安装包：Jan_0.8.7_amd64.deb（1001MB）、Jan_0.8.7_amd64.AppImage（668MB）
安装后占用：约 1.44GB（Installed-Size: 1508560 KB，其中 /usr/lib/Jan 约 1.3GB）
数据目录：~/.local/share/Jan/（settings.json 与 data/ 子目录）
磁盘要求：建议预留 4GB 以上（安装包缓存 + 解包体积）
软件形态说明：Jan 是桌面（GUI）应用，本体不含 jan 命令行工具；终端代理是独立产品 Jan Agent，另行安装（见本专栏《Jan 0.8.7 常用 CLI 命令与工具详解》一篇）。本篇的命令与验证均在 Ubuntu 22.04 系统上实测，GUI 启动相关差异已在"常见问题"中给出无图形环境的实测结论。

二、前置条件

安装前确认系统满足依赖与磁盘条件。Jan 的 deb 包自带绝大部分运行时（含 llama.cpp 引擎与 CUDA 运行库），仅依赖三个系统库，可用 apt-cache depends 预先核对：

# 查看.deb 包声明的依赖（已下载 deb 后执行，或先 apt update）
apt-cache depends jan

实测输出：

jan
  Depends: libappindicator3-1
    libayatana-appindicator3-1
  Depends: libwebkit2gtk-4.1-0
  Depends: libgtk-3-0

三个依赖（托盘图标库、WebKitGTK、GTK3）都会被 apt install ./xxx.deb 自动补齐，无需手动预装。再确认磁盘与网络：

# 磁盘剩余空间（建议 / 所在分区 ≥ 4GB）
df -h /

实测输出：

overlay         786G  377G  375G  51% /

⚠️ 注意：Jan 0.8.7 的 deb 包内含 CUDA 13 运行库（libcudart.so.13、libcublasLt.so.13 等）与 Vulkan 后端，包体约 1GB。无 NVIDIA GPU 的机器同样可以安装——llama.cpp 引擎会自动使用 CPU 或 Vulkan 后端（包内亦带 libggml-vulkan.so）。

三、版本选型说明

Jan 官方提供三条版本通道（来源：官方 GitHub README 与 Releases 页，查询日期 2026-10-22）：

通道	说明	Linux 发行物
Stable（推荐）	官方稳定版，本篇实测对象	jan.deb / jan.AppImage
Beta（Preview）	预览通道	jan.deb / jan.AppImage
Nightly（Experimental）	每日实验构建	jan.deb / jan.AppImage

本篇选择 Stable 通道 v0.8.7（2026-10-20 发布）。查询最新稳定版的方法：

浏览器访问 https://github.com/janhq/jan/releases/latest ，页面标题即最新版本号（实测写作时为 v0.8.7）；
或用 curl 跟随重定向读取最终地址中的标签：

curl -sIL -o /dev/null -w '%{url_effective}\n' https://github.com/janhq/jan/releases/latest

实测输出：

https://github.com/janhq/jan/releases/tag/v0.8.7

💡 技术拓展：Jan 自 0.8.5 起拆分为两条产品线——桌面应用（本篇安装的 Jan Desktop，可执行文件名 Jan-Desktop）与终端代理 Jan Agent（独立安装脚本、独立版本通道 agent-nightly）。两者的版本号各自演进（实测时桌面端 0.8.7、Agent 端 0.8.7-66），升级互不影响。若只需要终端代理，可跳过本篇直接使用官方脚本安装 Jan Agent（见本专栏 CLI 篇）。

四、在线安装方案 A：官方 deb 包（推荐）

本方案适合 Ubuntu/Debian 系桌面机，安装后由 dpkg 统一管理，升级、降级、卸载路径清晰。

4.1 下载安装包

mkdir -p /opt/jan-pkg && cd /opt/jan-pkg
wget https://github.com/janhq/jan/releases/download/v0.8.7/Jan_0.8.7_amd64.deb

wget 会显示实时进度条，完成后文件落在当前目录。用 ls -lh 确认体积（实测输出）：

total 1001M
-rw-r--r-- 1 root root 1001M Oct 22 16:31 Jan_0.8.7_amd64.deb

断点续传：下载中断后对同一 URL 重跑 wget -c 可从断点继续；文件已完整时实测返回：

    The file is already fully retrieved; nothing to do.

⚠️ 注意：国内网络访问 GitHub Releases 较慢时，可为 wget 配置代理：wget -x http://<代理IP>:<端口> <URL>，或使用 https://gh-proxy.com/ 一类公共加速前缀。文件约 1GB，请耐心等待。

4.2 校验完整性

sha256sum /opt/jan-pkg/Jan_0.8.7_amd64.deb

实测输出：

a414913bf0c3057b97cfe7a8b48674425318ff2e23a5aded5630ba2607697378  /opt/jan-pkg/Jan_0.8.7_amd64.deb

该值与官方 Release 页 v0.8.7 资产清单中 Jan_0.8.7_amd64.deb 条目公布的 sha256 完全一致（比对日期 2026-10-22）。不一致时请删除重下，不要强行安装。

4.3 安装

apt-get install -y /opt/jan-pkg/Jan_0.8.7_amd64.deb

实测输出（输出较长，节选尾部）：

aspell-autobuildhash: processing: en [en_US-wo_accents-only].
Processing triggers for libgdk-pixbuf-2.0-0:amd64 (2.42.8+dfsg-1ubuntu0.5) ...

apt 会自动补齐 libwebkit2gtk-4.1-0、libgtk-3-0、libayatana-appindicator3-1 及其依赖链后完成安装。

4.4 验证安装

dpkg -l | grep -i jan

实测输出：

ii  jan                                  0.8.7                                   amd64        Use offline LLMs with your own data. Run open source models like Llama2 or Falcon on your internal computers/servers.

ls /usr/bin/ | grep -i jan

实测输出：

Jan-Desktop

包内还附带 bun 与 uv 两个可执行文件（Jan 扩展体系与 MCP 工具链的运行时），可通过 dpkg -L jan 查看完整清单（共 53 个文件，节选）：

/usr/bin/bun
/usr/bin/Jan-Desktop
/usr/bin/uv
/usr/lib/Jan/resources/bin/jan-llama-worker
/usr/lib/Jan/resources/bin/libggml-cuda.so
/usr/lib/Jan/resources/bin/libggml-vulkan.so
/usr/lib/Jan/resources/bin/libcudart.so.13

其中 jan-llama-worker 是本地推理引擎的工作进程，GPU 加速依赖的 GGML/CUDA/Vulkan 库均在 /usr/lib/Jan/resources/bin/ 下。

4.5 启动与初始化

在有桌面会话的 Ubuntu 22.04 上，从应用菜单启动"Jan"，或执行：

Jan-Desktop

首次启动应用会自动完成初始化：迁移 MCP 配置（日志显示 Migrating MCP schema version 1..5）、生成默认助手配置，并自动下载内置的嵌入模型（All-MiniLM-L6-v2，约 100MB，走官方下载源 apps.jan.ai 加速）。初始化完成后即可在 Hub 中下载对话模型开始使用。

验证数据目录已生成：

find ~/.local/share/Jan -maxdepth 2 | sort

实测输出：

/root/.local/share/Jan
/root/.local/share/Jan/data
/root/.local/share/Jan/data/assistants
/root/.local/share/Jan/data/db
/root/.local/share/Jan/data/llamacpp
/root/.local/share/Jan/data/logs
/root/.local/share/Jan/data/mcp_config.json
/root/.local/share/Jan/data/settings.json
/root/.local/share/Jan/data/store.json
/root/.local/share/Jan/settings.json

五、在线安装方案 B：AppImage（免安装）

AppImage 单文件、免 root、不写入系统目录，适合无 sudo 权限或多版本共存的场景。

5.1 下载与校验

cd /opt/jan-pkg
wget https://github.com/janhq/jan/releases/download/v0.8.7/Jan_0.8.7_amd64.AppImage
sha256sum Jan_0.8.7_amd64.AppImage

实测输出：

4b37501a01cd9d2e4aeaac3bb96352f6f7df29aa5666acfc326e3bf33666f61a  Jan_0.8.7_amd64.AppImage

与官方 Release 页资产清单一致。

5.2 运行

chmod +x Jan_0.8.7_amd64.AppImage
./Jan_0.8.7_amd64.AppImage

在未启用 FUSE 的环境（未安装 libfuse2，或内核 FUSE 设备不可用）直接运行会报错。实测报错如下（注意：此场景下实测进程退出码为 0 而非非零，自动化脚本不能依赖退出码判断 FUSE 缺失，应检查报错文本）：

fuse: device not found, try 'modprobe fuse' first

Cannot mount AppImage, please check your FUSE setup.
You might still be able to extract the contents of this AppImage
if you run it with the --appimage-extract option.

两种解决方式任选其一：

# 方式一：补装 FUSE（需要 sudo），适合桌面环境
apt-get install -y libfuse2

实测输出（节选）：

Unpacking libfuse2:amd64 (2.9.9-5ubuntu3) ...
Setting up libfuse2:amd64 (2.9.9-5ubuntu3) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

方式二免 root，适合无 sudo 权限的环境：

# 免 FUSE 解包后直接运行（无需 root）
./Jan_0.8.7_amd64.AppImage --appimage-extract

实测无输出（静默解包），完成后当前目录生成 squashfs-root/，用 ls 验证：

ls squashfs-root/usr/bin/

实测输出：

Jan-Desktop
bun
uv
xdg-open

解包目录顶层自带 AppRun 启动器与 Jan.desktop 桌面入口文件，在桌面会话中执行 ./squashfs-root/AppRun 即可启动。

💡 说明：--appimage-extract 解包版升级时需重新解包覆盖；长期使用建议选方案 A（deb）或补装 libfuse2。

六、降级与多版本管理

Jan 未提供官方 apt 仓库，版本管理以"保留 deb 文件 + 直接覆盖安装"为准。实测机器上保留历史版本 deb 即可自由升降级。

6.1 降级到旧版本（0.8.7 → 0.8.6）

直接安装旧版 deb 会被 apt 以"版本较低"拒绝，必须显式允许降级：

wget https://github.com/janhq/jan/releases/download/v0.8.6/Jan_0.8.6_amd64.deb
apt-get install -y --allow-downgrades /opt/jan-pkg/Jan_0.8.6_amd64.deb

实测输出（节选）：

dpkg: warning: downgrading jan from 0.8.7 to 0.8.6
Unpacking jan (0.8.6) over (0.8.7) ...
Setting up jan (0.8.6) ...
Processing triggers for hicolor-icon-theme (0.17-2) ...

验证版本已回退：

dpkg -l | grep -i jan

实测输出：

ii  jan                                  0.8.6                                   amd64        Use offline LLMs with your own data. Run open source models like Llama2 or Falcon on your internal computers/servers.

6.2 升级回新版（0.8.6 → 0.8.7）

新版覆盖安装无需任何附加参数：

apt-get install -y /opt/jan-pkg/Jan_0.8.7_amd64.deb

实测输出（节选）：

Unpacking jan (0.8.7) over (0.8.6) ...
Setting up jan (0.8.7) ...
Processing triggers for hicolor-icon-theme (0.17-2) ...

dpkg -l | grep -i jan

实测输出：

ii  jan                                  0.8.7                                   amd64        Use offline LLMs with your own data. Run open source models like Llama2 or Falcon on your internal computers/servers.

💡 说明：用户数据（~/.local/share/Jan/）独立于程序目录，升降级均保留；data/store.json 中记录的 version 字段会在应用下次启动时自动迁移到当前版本。

七、方案对比与选择建议

维度	方案 A：deb 包	方案 B：AppImage
是否需要 root	需要（apt/dpkg 管理）	不需要
安装位置	/usr/bin、/usr/lib/Jan	单文件或解包目录
包体	1001MB	668MB
桌面菜单集成	自动	需手动（解包版无 .desktop）
升级/降级	apt 覆盖安装 / --allow-downgrades	替换文件或重新解包
卸载	apt remove --purge jan	删除单文件/目录
适用场景	桌面机长期使用（推荐）	无 sudo、多版本、临时试用

选择建议：日常桌面使用选方案 A，由包管理器统一管理；服务器/受限环境验证功能选方案 B。

八、配置说明

安装完成后无需手动配置即可使用；常用配置入口如下：

数据目录：~/.local/share/Jan/。顶层 settings.json 只有一个键 data_folder，指向数据区：

{"data_folder":"/root/.local/share/Jan/data"}

应用数据区 data/：settings.json（界面与引擎设置键值表）、mcp_config.json（MCP 服务器配置）、assistants/jan/assistant.json（默认助手人设）、llamacpp/（引擎设置与模型）、logs/app.log（排障日志）。
数据目录迁移：Settings > General > Jan Data Folder 中可改到自定义路径（要求目标目录为空，应用重启后生效）。
HTTPS 代理：Settings > General > HTTPs Proxy，格式 http://<user>:<password>@<host>:<port>，仅影响模型下载与网页抓取，不影响本地推理。
模型与引擎参数：Hub 下载模型；模型齿轮图标设置 Context Size、GPU Layers、Temperature 等（详见本专栏《Jan 0.8.7 配置参数详解》一篇）。
终端 CLI：Jan Desktop 0.8.5 起不再捆绑 jan 命令；需要终端代理时按官方脚本另行安装 Jan Agent（见本专栏《Jan 0.8.7 常用 CLI 命令与工具详解》一篇）。

九、常见问题

Q1：无图形环境执行 Jan-Desktop --version 报错 panic？

Jan Desktop 是 GUI 程序，所有命令行参数都要先初始化 GTK。在无桌面的文本环境直接执行：

Jan-Desktop --version

实测输出：

thread 'main' (6274) panicked at /home/runner/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/tao-0.35.3/src/platform_impl/linux/event_loop.rs:217:53:
Failed to initialize gtk backend!: BoolError { message: "Failed to initialize GTK", filename: "/home/runner/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/gtk-0.18.2/src/rt.rs", function: "gtk::rt::init", line: 141 }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

这不是安装损坏，而是程序明确要求图形环境。处理方式二选一：

桌面会话中运行（正常使用方式）；
无显示环境临时验证程序可启动时，用虚拟显示：

apt-get install -y xvfb
xvfb-run -a Jan-Desktop

实测输出（应用正常初始化，日志节选）：

[2026-10-22][16:20:44][app_lib::core::setup][WARN] Failed to setup XDG Desktop Portal theme listener: I/O error: No such file or directory (os error 2)
[2026-10-22][16:20:44][keyring][DEBUG] creating entry with service jan-providers, user exa-api-key, and no target

WARN 仅提示未接入桌面门户主题监听，不影响功能。另外 Jan-Desktop --version 不会打印版本号（Tauri 应用直接进入主流程），版本确认请用 dpkg -l | grep -i jan。

Q2：装完后没有 jan 命令？

官方自 Jan Desktop 0.8.5 起不再捆绑 jan CLI、也不再写入 PATH（官方文档 docs.jan.ai/desktop/cli 明示）。终端代理是独立产品 Jan Agent，用官方脚本单独安装：

curl -fsSL https://delta.jan.ai/jan-cli/install-jan-agent.sh | bash

Q3：apt-get install ./xxx.deb 报依赖错误？

先 apt-get update 刷新索引再重试；Ubuntu 22.04 最小安装的系统可能缺少 universe 仓库组件，在 /etc/apt/sources.list 中确认 universe 源已启用。实测最小环境中自动补齐的依赖包括 libwebkit2gtk-4.1-0、libgtk-3-0、libayatana-appindicator3-1 及其传递依赖（aspell、gdk-pixbuf 等触发器）。

Q4：磁盘不足 / 安装包下载慢？

安装包约 1GB、解包后约 1.44GB，/ 分区建议预留 4GB。下载慢时走代理（见 4.1 节 ⚠️）；也可以先在其他机器下载，再把 deb 拷贝到本机安装——apt-get install -y /路径/Jan_0.8.7_amd64.deb 对本地文件同样有效（本篇 4.3 节即为此方式）。

十、卸载与清理

apt-get remove --purge -y jan

实测输出（节选）：

0 upgraded, 0 newly installed, 1 to remove and 3 not upgraded.
After this operation, 1545 MB disk space will be freed.
Removing jan (0.8.7) ...
Processing triggers for hicolor-icon-theme (0.17-2) ...

验证已卸载：

ls /usr/bin/Jan-Desktop

实测输出：

ls: cannot access '/usr/bin/Jan-Desktop': No such file or directory

dpkg -l | grep -i jan

实测输出：无输出（已卸载干净）。

⚠️ 注意：--purge 只删程序文件，用户数据 ~/.local/share/Jan/（含已下载模型）会保留。确认不再使用后手动删除：

rm -rf ~/.local/share/Jan
rm -rf ~/.jan        # 若另行安装过 Jan Agent，其全局配置与项目存储在此

AppImage 方案的卸载：直接删除 .AppImage 文件与 squashfs-root/ 解包目录即可。

十一、参考链接

Jan 官网下载页：https://jan.ai （查询日期 2026-10-22）
GitHub Releases v0.8.7（deb/AppImage 资产与 sha256）：https://github.com/janhq/jan/releases/tag/v0.8.7 （查询日期 2026-10-22）
官方 Desktop 文档 - Quickstart：https://docs.jan.ai/desktop/quickstart （查询日期 2026-10-22）
官方 Desktop 文档 - Jan Data Folder：https://docs.jan.ai/desktop/data-folder （查询日期 2026-10-22）
官方 Desktop 文档 - CLI 与 Desktop 的关系（0.8.5 起不捆绑 CLI）：https://docs.jan.ai/desktop/cli （查询日期 2026-10-22）
Jan Agent 安装脚本：https://delta.jan.ai/jan-cli/install-jan-agent.sh （查询日期 2026-10-22）