Spoolman v0.27.0 Docker Compose 部署指南

目标：用 Docker Compose 在 Linux 服务器上一键部署 Spoolman v0.27.0，完成数据持久化、环境变量配置与验证访问。已在真实服务器环境实测通过（Docker Engine + Compose v2，镜像 donkieyo/spoolman:0.27.0）。

一、环境信息

操作系统：Linux（x86_64，本文实测 Ubuntu 22.04.5 LTS）
Docker：已安装 Docker Engine 与 Compose v2 插件（docker compose version 可用）
目标软件：Spoolman v0.27.0（镜像 digest sha256:7aba565eff77…，构建于 2026-09-25）
容器内服务端口：8000，本文映射到宿主机 8136（可按需改）
数据目录（bind mount）：/opt/spoolman/data → 容器内 /home/app/.local/share/spoolman
数据库：SQLite（默认，无需额外容器）

二、镜像选型说明

Spoolman 官方同时发布到两个镜像仓库，内容一致（同一 digest）：

仓库	镜像	可用标签（2026-10-25 实测）	说明
GHCR	`ghcr.io/donkie/spoolman`	`latest`、`edge` 等	GitHub Container Registry，版本标签以 `latest` 为主
Docker Hub	`donkieyo/spoolman`	`latest`、`edge`、`0`、`0.27`、`0.27.0` 等	提供完整语义化版本标签

⚠️ 注意：实测发现 GHCR 上没有 v0.27.0 或 0.27.0 版本标签（docker pull ghcr.io/donkie/spoolman:v0.27.0 返回 not found）；需要锁定版本时应使用 Docker Hub 的 donkieyo/spoolman:0.27.0。两者 latest 的 digest 完全一致（sha256:7aba565eff77…）。

镜像内版本标签核实：

docker image inspect donkieyo/spoolman:0.27.0 --format '{{index .Config.Labels "org.opencontainers.image.version"}} | {{.Created}}'

实测回显：

0.27.0 | 2026-09-25T13:48:46.800665217Z

选型建议：生产部署用 donkieyo/spoolman:0.27.0（锁版本）；想始终跟最新稳定版可用 :latest，但不利于回溯。

三、前置条件

已安装 Docker Engine 与 Compose v2 插件：

docker version --format '{{.Server.Version}}'
docker compose version

宿主机端口 8136 未被占用（可自行换其他端口）：
```
ss -ltn | grep 8136
```
无输出即未被占用。

拉取镜像（如网络访问 Docker Hub 慢，可先配置镜像加速器或代理）：

docker pull donkieyo/spoolman:0.27.0

实测回显（末尾）：

Digest: sha256:7aba565eff774c6dda212d4204de8fa30bf68d513127ef875cc7ef3197a4664e
Status: Downloaded newer image for donkieyo/spoolman:0.27.0

四、部署步骤

4.1 准备数据目录并修正属主

Spoolman 镜像内进程默认以 UID/GID 1000 运行（PUID/PGID 默认 1000），bind mount 目录属主必须匹配，否则启动报错：

mkdir -p /opt/spoolman/data
chown -R 1000:1000 /opt/spoolman/data

4.2 编写 docker-compose.yml

创建项目目录并写入编排文件：

mkdir -p /opt/spoolman/compose
cd /opt/spoolman/compose

docker-compose.yml 内容：

name: spoolman-0.27.0-stack

services:
  spoolman:
    image: donkieyo/spoolman:0.27.0
    container_name: spoolman-0.27.0-compose
    restart: unless-stopped
    ports:
      - "8136:8000"
    volumes:
      - /opt/spoolman/data:/home/app/.local/share/spoolman
    environment:
      - TZ=Asia/Shanghai
      - PUID=1000
      - PGID=1000
      - SPOOLMAN_LOGGING_LEVEL=INFO
      - SPOOLMAN_DB_TYPE=sqlite
      - SPOOLMAN_AUTOMATIC_BACKUP=TRUE

逐项说明：

name: spoolman-0.27.0-stack：Compose 项目名，隔离网络与容器前缀，避免与其他项目互相影响。
container_name：固定容器名，便于 docker logs 等运维。
ports：宿主机 8136 → 容器 8000。容器内固定监听 8000，改端口只改左侧宿主机值。
volumes：bind mount 把容器数据目录 /home/app/.local/share/spoolman 持久化到宿主机 /opt/spoolman/data。
environment：详见第七节环境变量表。

4.3 启动并验证

docker compose up -d

实测回显：

 Network spoolman-0270-stack_default Created 
 Container spoolman-0.27.0-compose Creating 
 Container spoolman-0.27.0-compose Created 
 Container spoolman-0.27.0-compose Starting 
 Container spoolman-0.27.0-compose Started

查看容器状态：

docker compose ps

实测回显：

NAME                      IMAGE                      COMMAND                  SERVICE    CREATED         STATUS         PORTS
spoolman-0.27.0-compose   donkieyo/spoolman:0.27.0   "/home/app/spoolman/…"   spoolman   9 seconds ago   Up 9 seconds   0.0.0.0:8136->8000/tcp, [::]:8136->8000/tcp

查看启动日志（确认数据库迁移完成）：

docker compose logs --no-color | head -12

实测回显（节选）：

spoolman-0.27.0-compose  | spoolman.main              INFO     Trusting writes and websockets from this instance's own origin only.
spoolman-0.27.0-compose  | uvicorn.error              INFO     Started server process [1]
spoolman-0.27.0-compose  | spoolman.main              INFO     Starting Spoolman v0.27.0 (commit: bed3f14) (built: 2026-09-25 13:48:24+00:00)
spoolman-0.27.0-compose  | spoolman.main              INFO     Using data directory: /home/app/.local/share/spoolman
spoolman-0.27.0-compose  | spoolman.main              INFO     Using backups directory: /home/app/.local/share/spoolman/backups
spoolman-0.27.0-compose  | spoolman.main              INFO     Setting up database...
spoolman-0.27.0-compose  | spoolman.database.database INFO     Using SQLite database located at "/home/app/.local/share/spoolman/spoolman.db"
spoolman-0.27.0-compose  | spoolman.main              INFO     Performing migrations...
spoolman-0.27.0-compose  | alembic.runtime.migration  INFO     Context impl SQLiteImpl.
spoolman-0.27.0-compose  | alembic.runtime.migration  INFO     Running upgrade  -> 684d32cf7e4d, initial.

接口验证：

curl -s http://localhost:8136/api/v1/info
curl -s http://localhost:8136/api/v1/health

实测回显：

{"version":"0.27.0","debug_mode":false,"automatic_backups":true,"data_dir":"/home/app/.local/share/spoolman","logs_dir":"/home/app/.local/share/spoolman","backups_dir":"/home/app/.local/share/spoolman/backups","db_type":"DatabaseType.SQLITE","external_db_name":"SpoolmanDB","git_commit":"bed3f14","build_date":"2026-09-25T13:48:24Z"}
{"status":"healthy"}

浏览器访问 http://<服务器IP>:8136 即可打开 Web UI。

五、数据持久化说明

bind mount 目录在宿主机上的真实内容（实测）：

ls -la /opt/spoolman/data/

实测回显：

total 148
drwxr-xr-x 4 yahui yahui   4096 Oct 25 09:13 .
drwxr-xr-x 3 root  root    4096 Oct 25 09:11 ..
drwxr-xr-x 2 yahui yahui   4096 Oct 25 09:13 backups
drwxr-xr-x 3 yahui yahui   4096 Oct 25 09:13 cache
-rw-r--r-- 1 yahui yahui 126976 Oct 25 09:13 spoolman.db
-rw-r--r-- 1 yahui yahui   1369 Oct 25 09:13 spoolman.log

属主显示为 yahui:yahui（UID/GID 1000，即容器内 app 用户在宿主机上的映射），属正常。
spoolman.db 为 SQLite 主库；backups/ 存每晚自动备份（保留 5 份）；spoolman.log 午夜轮转；cache/ 为外部耗材目录缓存。

持久化验证（重启容器数据不丢，实测）：

# 先建一条丝盘数据
curl -s -X POST http://localhost:8136/api/v1/vendor -H 'Content-Type: application/json' -d '{"name":"eSUN"}'

# 重启整个栈
docker compose restart

# 再次查询，数据仍在
curl -s http://localhost:8136/api/v1/vendor/1

实测回显（重启后查询）：

{"id":1,"registered":"2026-10-25T01:13:44Z","name":"eSUN","extra":{}}

⚠️ 注意：若 bind mount 目录属主不是 1000:1000，容器启动会因无法写数据目录而失败，日志会明确提示需要执行的 chown 命令。PUID 不能设为 0（镜像禁止 root 运行）。

六、环境变量表

变量	默认值	说明
`TZ`	`UTC`	容器时区（仅 Docker 部署有效），建议设 `Asia/Shanghai`
`PUID` / `PGID`	`1000` / `1000`	容器内运行用户/组 UID；须与 bind mount 目录属主一致，PUID 不可为 0
`SPOOLMAN_DB_TYPE`	`sqlite`	数据库类型，可选 `postgres` / `mysql` / `cockroachdb`
`SPOOLMAN_DB_HOST` / `SPOOLMAN_DB_PORT` / `SPOOLMAN_DB_NAME` / `SPOOLMAN_DB_USERNAME` / `SPOOLMAN_DB_PASSWORD`	空	外部数据库连接参数（SQLite 时无需配置）
`SPOOLMAN_DB_PASSWORD_FILE`	空	从文件读取数据库密码（配合 Docker secrets），优先级高于 `SPOOLMAN_DB_PASSWORD`
`SPOOLMAN_LOGGING_LEVEL`	`INFO`	日志级别：DEBUG / INFO / WARNING / ERROR / CRITICAL
`SPOOLMAN_AUTOMATIC_BACKUP`	`TRUE`	SQLite 每晚自动备份（仅对 SQLite 生效）
`SPOOLMAN_METRICS_ENABLED`	`FALSE`	开启后暴露 Prometheus `/metrics`
`SPOOLMAN_BASE_PATH`	空	子路径反代时设置，如 `/spoolman`
`SPOOLMAN_CORS_ORIGIN`	空	允许的跨域来源，逗号分隔；`*` 表示完全关闭检查（危险，仅限受信网络）
`SPOOLMAN_ALLOWED_HOSTS`	空（off）	允许访问的主机名列表，防 DNS rebinding；反代域名必须列入
`EXTERNAL_DB_URL`	`https://donkie.github.io/SpoolmanDB/`	外部耗材目录地址（空值禁用；无 `SPOOLMAN_` 前缀为官方历史原因）
`EXTERNAL_DB_NAME`	`SpoolmanDB`	外部目录在 UI 中的显示名
`EXTERNAL_DB_SYNC_INTERVAL`	`3600`	外部目录同步间隔秒数（0 = 仅启动时同步）
`SPOOLMAN_LEGACY_CLIENT`	`FALSE`	设为 `TRUE` 回退到旧版 React 客户端
`SPOOLMAN_DEBUG_MODE`	`FALSE`	调试模式，会关闭来源校验，生产环境严禁开启

💡 说明：完整参数逐项详解与生产推荐配置见本专栏《Spoolman v0.27.0 配置参数详解》篇。

七、配置参数说明

最常用的三类配置：

改监听端口：只改 compose 里 ports 左侧的宿主机端口（如改为 "7912:8000"），然后 docker compose up -d 重建。

切换外部数据库：以 PostgreSQL 为例——

environment:
  - SPOOLMAN_DB_TYPE=postgres
  - SPOOLMAN_DB_HOST=192.168.1.20
  - SPOOLMAN_DB_PORT=5432
  - SPOOLMAN_DB_NAME=spoolman
  - SPOOLMAN_DB_USERNAME=spoolman
  - SPOOLMAN_DB_PASSWORD=q1w2e3r4

⚠️ 注意：SQLite 模式下严禁设置 SPOOLMAN_DB_NAME（会拒绝启动），仅外部数据库需要。

修改后生效方式：environment 变更需 docker compose up -d 重建容器（restart 不会重读 environment）。

八、配置文件挂载

Spoolman 不使用传统配置文件，全部配置走环境变量（见上两节），因此无需挂载任何配置文件。需要持久化的只有数据目录 /home/app/.local/share/spoolman。

如果通过反向代理按子路径提供服务，设置 SPOOLMAN_BASE_PATH=/spoolman 并在代理层做路径前缀转发即可，同样无需额外配置文件。

九、等价 docker run

不使用 Compose 时，等价命令为：

docker run -d \
  --name spoolman-0.27.0-compose \
  --restart unless-stopped \
  -p 8136:8000 \
  -v /opt/spoolman/data:/home/app/.local/share/spoolman \
  -e TZ=Asia/Shanghai \
  -e PUID=1000 \
  -e PGID=1000 \
  -e SPOOLMAN_LOGGING_LEVEL=INFO \
  -e SPOOLMAN_DB_TYPE=sqlite \
  -e SPOOLMAN_AUTOMATIC_BACKUP=TRUE \
  donkieyo/spoolman:0.27.0

十、常用运维命令

# 查看日志（实时）
docker compose logs -f

# 重启 / 停止 / 启动
docker compose restart
docker compose down
docker compose up -d

# 升级镜像版本（改 tag 后重建）
docker compose pull
docker compose up -d

# 进入容器排查
docker exec -it spoolman-0.27.0-compose /bin/bash

# 备份数据库（直接复制 SQLite 文件即可，建议先停写）
cp /opt/spoolman/data/spoolman.db /opt/spoolman/data/spoolman.db.bak

十一、常见问题

Q1：docker pull ghcr.io/donkie/spoolman:v0.27.0 报 not found？

GHCR 未发布带版本号的标签，锁版本请用 Docker Hub 的 donkieyo/spoolman:0.27.0（与 GHCR latest 同 digest）。这是本批次实测踩到的真实坑。

Q2：启动失败，日志提示数据目录权限问题？

bind mount 目录属主必须与 PUID/PGID（默认 1000）一致：

chown -R 1000:1000 /opt/spoolman/data

Q3：容器内端口为什么是 8000 而不是 standalone 的 7912？

Docker 镜像的默认配置内部监听 8000，standalone 的 .env.example 默认 7912，两者官方默认不同；容器对外端口由 ports 映射决定，无需关心内部值。

Q4：修改 environment 后配置不生效？

docker compose restart 不会重建容器。改 environment 或镜像后必须 docker compose up -d（Compose 检测到变更会自动重建）。

Q5：如何彻底删除（含数据）？

docker compose down
rm -rf /opt/spoolman/data /opt/spoolman/compose

⚠️ 警告：rm -rf /opt/spoolman/data 会永久删除 SQLite 数据库与备份，操作前请先备份 spoolman.db。

十二、参考链接

官方仓库：https://github.com/Donkie/Spoolman
官方 Wiki（Installation）：https://github.com/Donkie/Spoolman/wiki/Installation
Docker Hub 镜像：https://hub.docker.com/r/donkieyo/spoolman
GHCR 镜像：https://github.com/Donkie/Spoolman/pkgs/container/spoolman
裸机安装方式：见本专栏《Ubuntu 22.04 安装 Spoolman v0.27.0 指南》
配置参数详解：见本专栏《Spoolman v0.27.0 配置参数详解》