在 Linux 上安装

介绍在 Linux 主机上直接运行 SetFN SpaceBuilder 的方法。以下示例以 Ubuntu 系列发行版为基准，其他发行版的软件包名称和安装命令可能有所不同。

开始之前

安装软件包和设置自动启动时需要 sudo 权限
有足够的磁盘空间来保存服务数据和将来上传的文件
如果需要从其他设备访问，需要有服务器端口的防火墙访问权限

SpaceBuilder 本身的运行不需要 sudo 权限。请使用普通用户账户运行。

除了普通 Linux PC 和服务器之外，NVIDIA DGX Spark、ASUS Ascent GX10、Dell Pro Max with GB10、HP ZGX Nano AI Station、Lenovo ThinkStation PGX、MSI EdgeXpert 等基于 GB10 的个人 AI 系统也可以作为 Linux 主机使用。这类设备适合运行本地 AI 模型、知识索引等使用 GPU 的任务。

不同设备的 CPU 架构、Linux 发行版、NVIDIA 驱动程序和 AI 运行时的支持范围各不相同。安装前请确认 SpaceBuilder 安装文件和要使用的 AI 运行时是否支持该环境。

Full 简易安装（准备中）

下载安装文件

在下载页面下载 Linux 安装文件。

为下载的文件授予可执行权限。

chmod +x ~/setfn-spacebuilder

安装必需库

SpaceBuilder 会借助计算机上安装的程序（库）来进行图像分析和生成预览。在 Ubuntu 24.04 及以上版本中，请先安装以下软件包。

sudo apt update
sudo apt install -y \
  libvips42t64 libvips-tools \
  libheif1 libheif-plugin-libde265 \
  libglib2.0-0

软件包	使用功能
`libvips42t64`、`libvips-tools`	图像元数据分析、缩略图生成及图像格式转换
`libheif1`、`libheif-plugin-libde265`	HEIC/HEIF 容器处理及 HEVC 图像解码
`libglib2.0-0`	libvips 等原生图像处理组件的运行时支持

安装推荐功能包

SpaceBuilder 服务器还会直接处理已上传文件的 OCR、PDF 分析、文档预览和格式转换。即使没有以下软件包，服务器的基本功能也能运行，但在处理相关文件时，部分功能会受限，或可用的转换引擎会减少。

如果要完整使用 OCR 和文档转换功能，建议一并安装以下软件包。

sudo apt install -y \
  tesseract-ocr tesseract-ocr-kor tesseract-ocr-jpn \
  poppler-utils \
  libreoffice pandoc

软件包	使用功能	未安装时
`tesseract-ocr`	图像和扫描 PDF 的文字识别（OCR），默认英文识别	无法使用本地 Tesseract OCR
`tesseract-ocr-kor`	韩语 OCR 语言数据	韩语识别准确率下降或无法使用韩语 OCR
`tesseract-ocr-jpn`	日语 OCR 语言数据	无法使用日语 OCR
`poppler-utils`	PDF 文本提取和页面图像转换（`pdftotext`、`pdftoppm`、`pdftocairo`）	PDF 文本提取和 OCR 预处理路径受限
`libreoffice`	DOCX、XLSX、PPTX 等办公文档的预览和 PDF 转换	办公文档转换功能受限
`pandoc`	DOCX、HTML、Markdown 等文档格式之间的转换	相应格式的转换路径受限

可以使用以下命令确认安装状态。

vips --version
vips list classes | grep -i heif
tesseract --version
tesseract --list-langs
pdftotext -v
libreoffice --version
pandoc --version

运行安装程序

运行安装文件。

./setfn-spacebuilder

安装程序默认在 18510 端口打开初始设置页面。如果该端口已被其他程序占用，会自动选择下一个可用端口，因此请始终使用终端中输出的地址进行访问。

浏览器中打开初始设置页面后，确认并同意使用条款，然后配置管理员账户和服务环境。详细的输入项和注意事项请参阅初始设置。

开机时自动启动

完成初始设置后，建议设置自动启动，让 SpaceBuilder 始终保持运行。设置自动启动后，会有以下效果。

即使关闭运行它的终端，SpaceBuilder 也会继续运行。
关机后重新开机，SpaceBuilder 会自动启动。
SpaceBuilder 因错误退出时会自动重新启动。

在 Linux 上，需要常驻运行的程序要注册到名为 systemd 的系统管理功能中。按顺序执行下面的命令即可。

1. 确认用户名和文件位置

逐行执行以下两条命令。

whoami

realpath ~/setfn-spacebuilder

whoami 显示当前登录的用户名。
realpath 显示 SpaceBuilder 可执行文件的准确位置。

输出的内容会在下一步使用，请记下来。

2. 创建自动启动配置文件

如果 SpaceBuilder 正在当前终端中运行，请先按 Ctrl+C 退出。使用以下命令打开自动启动配置文件。

sudo nano /etc/systemd/system/setfn-spacebuilder.service

粘贴以下内容。把所有 <用户名> 替换为第 1 步确认的用户名，并在 ExecStart 中填入确认到的可执行文件位置。

[Unit]
Description=SetFN SpaceBuilder
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=<用户名>
WorkingDirectory=/home/<用户名>
Environment=HOME=/home/<用户名>
ExecStart=/home/<用户名>/setfn-spacebuilder
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

在 nano 中按 Ctrl+O、Enter 保存，然后按 Ctrl+X 退出。

3. 启用自动启动

逐行执行以下命令。第一条命令把编写好的配置告知 Linux，第二条命令立即启动 SpaceBuilder，并使其从下次开机起自动启动。

sudo systemctl daemon-reload

sudo systemctl enable --now setfn-spacebuilder

确认是否正常运行。

systemctl status setfn-spacebuilder

屏幕上显示 active (running) 即表示自动启动设置完成。按 q 可以关闭状态页面。

4. 无法运行时排查原因

如果没有显示 active (running)，或者无法访问 SpaceBuilder，请使用以下命令查看最近的记录。

journalctl -u setfn-spacebuilder -n 100 --no-pager

要实时查看运行过程，请使用以下命令。查看完毕后按 Ctrl+C 退出。

journalctl -u setfn-spacebuilder -f

自动启动管理命令

操作	命令
查看运行状态	`systemctl status setfn-spacebuilder`
重新启动	`sudo systemctl restart setfn-spacebuilder`
关闭 SpaceBuilder	`sudo systemctl stop setfn-spacebuilder`
启动 SpaceBuilder	`sudo systemctl start setfn-spacebuilder`
开机时不自动启动	`sudo systemctl disable setfn-spacebuilder`

如果修改了自动启动配置文件的内容，需要先执行 sudo systemctl daemon-reload，再重新启动 SpaceBuilder，更改才会生效。

无法登录管理员页面时恢复账户或访问限制的方法，请参阅使用命令管理服务器。

← 上一篇

创建 SetFN 账户

使用 Docker 安装