Ubuntu 22.04 安装 Spoolman v0.27.0 指南
在 Ubuntu 22.04 服务器上从零安装 Spoolman v0.27.0：覆盖官方脚本安装与手动安装两种方案、systemd 托管、配置说明、升级与卸载，全部命令实测通过。
Ubuntu 22.04 安装 Spoolman v0.27.0 指南
目标：在 Ubuntu 22.04 服务器上从零安装 Spoolman v0.27.0，包括下载校验、官方脚本安装、systemd 托管与验证访问。全部命令已在真实服务器环境实测通过（操作系统 Ubuntu 22.04.5 LTS，x86_64，Python 3.10.12）。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）
- Python 版本：3.10.12（预装，满足 Spoolman 最低要求 ≥ 3.10）
- 目标软件：Spoolman v0.27.0（发布于 2026-09-25，commit
bed3f14） - 安装用户：root（可用 root 则优先使用；普通用户安装步骤相同，数据目录默认落在该用户
~/.local/share/spoolman） - 安装目录：
~/Spoolman - 监听端口：
7912 - 数据库：SQLite（默认，无需额外安装）
二、前置条件
在 Ubuntu 22.04 上安装 Spoolman 前，请确认满足以下条件：
-
一台运行 Ubuntu 22.04 LTS 的 x86_64 服务器（物理机、虚拟机或云主机均可）。
-
Python 3.10 或更高版本。Ubuntu 22.04 预装 Python 3.10，可直接使用：
python3 --version实测回显：
Python 3.10.12 -
服务器有稳定的互联网连接（以下载官方发布包与 Python 依赖）。
-
如打算使用 systemd 托管，需确保系统已启用 systemd（绝大多数 Ubuntu 22.04 服务器镜像默认开启）。
⚠️ 注意：实测过程中 GitHub 直连出现
Connection refused现象，已通过 HTTP 代理完成下载。若你的网络可直接访问 GitHub，则无需代理；若遇类似情况，可用export http_proxy=<代理地址>或在 curl/wget 中加-x <代理>参数。
三、版本选型说明
Spoolman 当前最新稳定版为 v0.27.0，发布于 2026-09-25，release 资产包含 spoolman.zip。截至 2026-10-25 的社区状态：
| 指标 | 数值（实测） |
|---|---|
| GitHub Stars | ≈ 2.9k |
| open issues | 152 |
| open PR | 19 |
| 发布节奏 | 2026 年持续发版，最新 v0.27.0（2026-09-25） |
选型建议：直接安装最新稳定版 v0.27.0。若未来需升级，卸载旧版后下载新版 zip 覆盖即可，数据由 ~/.local/share/spoolman/spoolman.db 保留（见后文「升级」节）。
四、方案一：官方脚本安装（install.sh + systemd 托管，推荐）
这是官方 Wiki 推荐的 Standalone 安装方式，一条命令即可完成虚拟环境创建、依赖安装、配置初始化与 systemd 托管。
4.1 安装基础依赖
apt-get update && apt-get install -y curl unzip
4.2 下载官方发布包并校验
官方发布包位于 GitHub Releases：
curl -sSL -o spoolman.zip https://github.com/Donkie/Spoolman/releases/download/v0.27.0/spoolman.zip
⚠️ 注意：curl 必须加
-L以跟随 302 跳转，否则会得到空文件。实测对比（不加-L时）：curl -sS -o spoolman.zip -w "http_code=%{http_code} size=%{size_download}\n" \ https://github.com/Donkie/Spoolman/releases/download/v0.27.0/spoolman.zip实测回显：
http_code=302 size=0
下载完成后，校验 SHA-256：
sha256sum spoolman.zip
实测回显：
bcc961af4c20d7ad7f1740f5609cd3efd94c4556baafaeba5036122dd7e46704 spoolman.zip
文件大小约为 3.2 MB（3,253,208 字节）。
4.3 解压到安装目录
unzip -q spoolman.zip -d ~/Spoolman
cd ~/Spoolman
ls
解压后的关键目录结构（实测回显节选）：
Dockerfile
LICENSE
README.md
alembic.ini
build.txt
client
client_v2
migrations
pyproject.toml
release_info.json
requirements.txt
scripts
spoolman
tests
uv.lock
pyproject.toml 中的版本信息可再次确认：
grep -E "^name|^version" pyproject.toml
回显：
name = "spoolman"
version = "0.27.0"
4.4 运行官方安装脚本
echo y | bash scripts/install.sh -systemd=yes
脚本会自动完成以下动作（无需手动干预）：
- 检测系统包管理器并安装
libpq-dev（PostgreSQL 客户端库）。 - 下载并安装
uv（Astral 出品，Rust 编写的极速 Python 包管理器）。 - 执行
uv sync --no-dev创建.venv并安装依赖（含 FastAPI、uvicorn、SQLAlchemy 2.0、psycopg2-binary、pymysql、alembic 等）。 - 复制
.env.example为.env。默认已包含SPOOLMAN_HOST=0.0.0.0、SPOOLMAN_PORT=7912。 - 创建 systemd 服务单元
/etc/systemd/system/Spoolman.service并自动 enable + start。
脚本末尾的实测输出（末尾两行）：
Spoolman systemd service has been installed and Spoolman is now starting.
Spoolman will soon be reachable at http://192.168.1.10:7912
💡 说明：最后一行中的 IP 为脚本自动检测到的本机地址，实际回显以你的服务器局域网 IP 为准。
安装完成后，生成的 systemd 单元文件内容如下：
[Unit]
Description=Spoolman
[Service]
Type=simple
ExecStart=bash ~/Spoolman/scripts/start.sh
WorkingDirectory=~/Spoolman
User=root
Restart=always
[Install]
WantedBy=default.target
💡 说明：
User=留空即使用 root（当前运行安装脚本的用户）；如以普通用户运行 install.sh，这里会填入对应用户名，数据目录自动落在该用户~/.local/share/spoolman。
scripts/start.sh 的内容（实测）：
#!/bin/bash
current_dir=$(pwd)
if [ "$(basename "$current_dir")" = "scripts" ]; then
cd ..
fi
if [ ! -d ".venv" ]; then
echo -e "\033[0;33m.venv folder not found. Please run the install script first.\033[0m"
exit 1
fi
echo -e "\033[0;32mActivating .venv...\033[0m"
source .venv/bin/activate
set -o allexport
source .env
set +o allexport
echo -e "\033[0;32mStarting Spoolman...\033[0m"
uvicorn spoolman.main:app --host $SPOOLMAN_HOST --port $SPOOLMAN_PORT
4.5 验证服务运行状态
检查 systemd 状态：
systemctl status Spoolman --no-pager
实测回显（节选）：
● Spoolman.service - Spoolman
Loaded: loaded (/etc/systemd/system/Spoolman.service; enabled; vendor preset: enabled)
Active: active (running) since Sun 2026-10-25 00:52:48 UTC; 10 min ago
Main PID: 3054 (bash)
Tasks: 9 (limit: 3612)
Memory: 90.6M
CPU: 2.768s
CGroup: /system.slice/Spoolman.service
├─3054 bash ~/Spoolman/scripts/start.sh
└─3061 .../uvicorn spoolman.main:app --host 0.0.0.0 --port 7912
查看首次启动日志（确认数据库迁移成功）：
journalctl -u Spoolman --no-pager | grep -v "uvicorn.access" | head -20
实测回显（节选）：
Oct 25 00:52:48 ... systemd[1]: Started Spoolman.
Oct 25 00:52:48 ... bash[3054]: Activating .venv...
Oct 25 00:52:48 ... bash[3054]: Starting Spoolman...
Oct 25 00:52:49 ... bash[3061]: spoolman.main INFO Trusting writes and websockets from this instance's own origin only.
Oct 25 00:52:49 ... bash[3061]: uvicorn.error INFO Started server process [3061]
Oct 25 00:52:49 ... bash[3061]: spoolman.main INFO Starting Spoolman v0.27.0 (commit: bed3f14) (built: None)
Oct 25 00:52:49 ... bash[3061]: spoolman.main INFO Using data directory: /root/.local/share/spoolman
Oct 25 00:52:49 ... bash[3061]: spoolman.main INFO Using backups directory: /root/.local/share/spoolman/backups
Oct 25 00:52:49 ... bash[3061]: spoolman.database.database INFO No database type specified, using a default SQLite database located at "/root/.local/share/spoolman/spoolman.db"
Oct 25 00:52:49 ... bash[3061]: spoolman.main INFO Performing migrations...
Oct 25 00:52:50 ... bash[3063]: alembic.runtime.migration INFO Context impl SQLiteImpl.
Oct 25 00:52:50 ... bash[3063]: alembic.runtime.migration INFO Running upgrade -> 684d32cf7e4d, initial.
Oct 25 00:52:50 ... bash[3063]: alembic.runtime.migration INFO Running upgrade 684d32cf7e4d -> b47376d60c6d, add extruder and bed temperature override.
Oct 25 00:52:50 ... bash[3063]: alembic.runtime.migration INFO Running upgrade b47376d60c6d -> db385b808a20, add filament color code.
...（后续迁移步骤省略）...
💡 说明：首次启动时 Alembic 会自动执行数据库迁移，将 SQLite 表结构从空库演进至最新版本，无需手动干预。
4.6 接口验证
验证 API info 端点：
curl -s http://localhost:7912/api/v1/info
实测回显：
{"version":"0.27.0","debug_mode":false,"automatic_backups":true,"data_dir":"/root/.local/share/spoolman","logs_dir":"/root/.local/share/spoolman","backups_dir":"/root/.local/share/spoolman/backups","db_type":"sqlite","external_db_name":"SpoolmanDB","git_commit":"bed3f14","build_date":null}
验证健康检查：
curl -s http://localhost:7912/api/v1/health
实测回显：
{"status":"healthy"}
浏览器访问 http://<服务器IP>:7912 即可打开 Web UI。
4.7 验证数据目录
SQLite 数据库与日志默认存放在数据目录下：
ls -la /root/.local/share/spoolman/
实测回显：
total 148
drwxr-xr-x 4 root root 4096 Oct 25 00:52 .
drwxr-xr-x 3 root root 4096 Oct 25 00:52 ..
drwxr-xr-x 2 root root 4096 Oct 25 00:52 backups
drwxr-xr-x 3 root root 4096 Oct 25 00:52 cache
-rw-r--r-- 1 root root 126976 Oct 25 00:54 spoolman.db
-rw-r--r-- 1 root root 3393 Oct 25 00:57 spoolman.log
spoolman.db：SQLite 主数据库。spoolman.log：应用日志（午夜轮转，默认保留 5 份）。backups/：每晚自动备份目录（默认保留 5 份）。cache/：外部耗材目录缓存。
五、方案二：手动安装（uv 虚拟环境 + 手写 systemd 单元）
如果希望跳过 install.sh，完全手动掌控每一步（例如需要自定义数据目录路径或复用已有的 uv 工具），可按照以下步骤操作。
5.1 解压与准备
前置与方案一相同：安装 curl、unzip，下载并校验 spoolman.zip，解压到 ~/Spoolman。
5.2 创建 Python 虚拟环境并安装依赖
cd ~/Spoolman
# 安装 uv（如尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 使用 uv 创建 .venv 并安装生产依赖
uv sync --no-dev
实测回显（uv sync --no-dev 末尾节选）：
+ uvicorn==0.50.1
+ uvloop==0.22.1
+ websockets==15.0.1
5.3 初始化配置
cp .env.example .env
默认 .env 已包含 SPOOLMAN_HOST=0.0.0.0 和 SPOOLMAN_PORT=7912，开箱可用。如需自定义数据目录，可追加（例如）：
echo 'SPOOLMAN_DIR_DATA=/opt/spoolman/data' >> .env
mkdir -p /opt/spoolman/data
5.4 编写 systemd 单元
创建 /etc/systemd/system/Spoolman.service：
[Unit]
Description=Spoolman
After=network.target
[Service]
Type=simple
WorkingDirectory=~/Spoolman
# 必须让 .venv/bin 在 PATH 中，否则启动时找不到 alembic 子进程
Environment=PATH=~/Spoolman/.venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
ExecStart=~/Spoolman/.venv/bin/uvicorn spoolman.main:app --host 0.0.0.0 --port 7912
Restart=always
[Install]
WantedBy=multi-user.target
⚠️ 注意：实测中发现，若
PATH未包含.venv/bin，启动会直接报错FileNotFoundError: [Errno 2] No such file or directory: 'alembic'，因为 Spoolman 在启动时会调用 alembic 执行迁移。scripts/start.sh内部通过source .venv/bin/activate间接解决此问题；手写 systemd 单元时，显式配置Environment=PATH=.../.venv/bin:...是最简洁的方案。
加载并启动：
systemctl daemon-reload
systemctl enable Spoolman --now
5.5 验证
systemctl is-active Spoolman
curl -s http://localhost:7912/api/v1/health
预期回显：
active
{"status":"healthy"}
六、方案对比与选择建议
| 维度 | 方案一：install.sh（推荐） | 方案二：手动安装 |
|---|---|---|
| 操作量 | 一条命令，全自动 | 分步执行，完全可控 |
| systemd 单元 | 脚本自动生成 | 手写，需额外注意 PATH |
| 适用人群 | 快速上手、标准部署 | 需要自定义路径/复用现有 uv |
| 排障难度 | 低 | 中（需自行处理 alembic PATH 问题） |
建议：绝大多数用户直接采用方案一；方案二仅在有特殊定制需求时参考。
七、配置说明
Spoolman 的配置全部通过 .env 文件（环境变量）管理，修改后需重启服务生效：
sudo systemctl restart Spoolman
常用配置项（来自 ~/Spoolman/.env.example）：
| 配置项 | 默认值 | 说明 |
|---|---|---|
SPOOLMAN_HOST | 0.0.0.0 | 监听地址 |
SPOOLMAN_PORT | 7912 | 监听端口 |
SPOOLMAN_DB_TYPE | sqlite | 数据库类型（可选 postgres / mysql / cockroachdb） |
SPOOLMAN_DIR_DATA | ~/.local/share/spoolman | 数据目录（SQLite 库、日志、备份均在此） |
SPOOLMAN_AUTOMATIC_BACKUP | TRUE | SQLite 夜间自动备份（保留 5 份） |
SPOOLMAN_LOGGING_LEVEL | INFO | 日志级别（DEBUG 会打印每条 SQL） |
SPOOLMAN_METRICS_ENABLED | FALSE | 是否开启 Prometheus /metrics |
EXTERNAL_DB_URL | https://donkie.github.io/SpoolmanDB/ | 外部耗材目录地址（空值禁用） |
EXTERNAL_DB_SYNC_INTERVAL | 3600 | 外部目录同步间隔秒数（0 表示仅启动时同步） |
💡 说明：完整参数表与生产环境推荐配置见本专栏《Spoolman v0.27.0 配置参数详解》篇。
八、升级与多版本管理
升级流程（来自官方 Wiki，2026-10-25 查询）：
# 1. 停止当前服务
systemctl stop Spoolman
# 2. 备份旧目录（保留 .env 与数据）
mv ~/Spoolman ~/Spoolman_old
# 3. 下载并解压新版
curl -sSL -o spoolman.zip https://github.com/Donkie/Spoolman/releases/download/<新版本>/spoolman.zip
unzip -q spoolman.zip -d ~/Spoolman
# 4. 迁移旧配置
cp ~/Spoolman_old/.env ~/Spoolman/.env
# 5. 重新安装依赖并启动
cd ~/Spoolman
echo y | bash scripts/install.sh -systemd=yes
# 6. 验证后删除旧目录
rm -rf ~/Spoolman_old
💡 说明：SQLite 数据库位于
~/.local/share/spoolman/spoolman.db，不在~/Spoolman目录内，因此重命名~/Spoolman不会丢失数据。若换用 PostgreSQL/MySQL，数据由外部数据库存储，升级更加安全。
降级同理：回退到旧版 zip，重跑 install.sh 即可。若数据库结构已向前迁移（Alembic 升级），旧版程序启动时会自动回滚到兼容版本（Alembic 支持 down revision）。
九、卸载清理
如需彻底移除 Spoolman：
# 停止并禁用 systemd 服务
systemctl stop Spoolman
systemctl disable Spoolman
rm -f /etc/systemd/system/Spoolman.service
systemctl daemon-reload
# 删除安装目录
rm -rf ~/Spoolman
# 删除数据（如需保留数据库做归档，请先复制 spoolman.db）
rm -rf ~/.local/share/spoolman
⚠️ 警告：执行
rm -rf ~/.local/share/spoolman会永久删除 SQLite 数据库与所有备份，删除前请确认已做好数据归档。
十、常见问题
Q1：下载 spoolman.zip 时得到 0 字节文件或 302 跳转报错？
确保 curl 带 -L 参数跟随重定向。GitHub Releases 会先返回 302 到对象存储地址，不带 -L 时仅写入空文件：
curl -sSL -o spoolman.zip https://github.com/Donkie/Spoolman/releases/download/v0.27.0/spoolman.zip
Q2：安装脚本提示需要 systemd，但当前环境没有 systemd？
install.sh -systemd=yes 依赖 systemd 创建和启动服务单元。若服务器确实无 systemd，可去掉 -systemd=yes，仅执行安装脚本创建 .venv 和依赖，然后手动前台启动：
cd ~/Spoolman
source .venv/bin/activate
bash scripts/start.sh
Q3：日志中出现 "Spoolman stores its database in the container directory..." 警告？
该警告字面量来自应用内部，用于提醒「数据目录需挂载到主机持久化」的封装部署场景。Standalone 安装时数据默认落在 ~/.local/share/spoolman，已持久化在服务器磁盘上，无需处理此警告。
Q4：端口 7912 被占用？
修改 ~/Spoolman/.env 中的 SPOOLMAN_PORT，重启服务即可：
sed -i 's/^SPOOLMAN_PORT=.*/SPOOLMAN_PORT=7913/' ~/Spoolman/.env
systemctl restart Spoolman
Q5：systemd 单元中必须配置 PATH 吗？
仅在手写 systemd 单元（方案二）时需要。install.sh 生成的单元调用 scripts/start.sh，该脚本内部通过 source .venv/bin/activate 自动修正 PATH，因此方案一无需额外配置。
十一、参考链接
- 官方仓库：https://github.com/Donkie/Spoolman
- 官方 Wiki（Installation）：https://github.com/Donkie/Spoolman/wiki/Installation
- Releases 页：https://github.com/Donkie/Spoolman/releases
- 容器部署方式（Docker Compose）：见本专栏《Spoolman v0.27.0 Docker Compose 部署指南》
- 配置参数详解：见本专栏《Spoolman v0.27.0 配置参数详解》