Spoolman v0.27.0 配置参数详解
逐项详解 Spoolman v0.27.0 全部配置：数据库/文件位置/网络/外部目录/诊断五组环境变量与 UI 设置，含默认值、修改生效方式、DEBUG 日志实测验证与生产配置模板。
Spoolman v0.27.0 配置参数详解
目标：逐项讲清 Spoolman v0.27.0 的全部配置参数（环境变量 + Web UI 设置），含默认值、取值范围、修改方式与实测验证。已在真实服务器环境实测通过（Ubuntu 22.04，Spoolman v0.27.0，systemd 托管）。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）
- 软件版本：Spoolman v0.27.0（commit
bed3f14） - 部署形态：Standalone（
~/Spoolman，systemd 托管，监听 7912）；Docker 部署差异单独标注 - 配置文件：
~/Spoolman/.env（由.env.example复制而来） - 数据库：SQLite（默认）
二、前置条件
已按本专栏《Ubuntu 22.04 安装 Spoolman v0.27.0 指南》或《Spoolman v0.27.0 Docker Compose 部署指南》完成部署，服务处于 active 状态：
systemctl is-active Spoolman
回显：
active
三、参数查看与修改方式
Spoolman 有两类配置，机制完全不同：
| 类型 | 存放位置 | 修改方式 | 生效方式 |
|---|---|---|---|
| 环境变量 | ~/Spoolman/.env（Standalone）或 compose environment:（Docker） | 编辑文件 | 重启服务：systemctl restart Spoolman / docker compose up -d |
| UI 设置 | 存于数据库 | Web 界面修改 | 即时生效，无需重启 |
.env 文件格式：每行一个 KEY=value，# 开头为注释；值含空格或 # 时需加引号。start.sh 启动时会 source .env 并导出全部变量。
查看当前生效配置的两种方式：
# 方式一：看启动日志（数据库类型、数据目录等会在启动时打印）
journalctl -u Spoolman --no-pager | grep "Using"
# 方式二：查询 info 接口
curl -s http://localhost:7912/api/v1/info
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}
UI 设置可通过 API 查看（含是否已设置、类型）：
curl -s http://localhost:7912/api/v1/setting/
实测回显（节选）：
{"currency":{"value":null,"is_set":false,"type":"string"},"round_prices":{"value":null,"is_set":false,"type":"boolean"},"print_presets":{"value":[],"is_set":true,"type":"array"},"locations":{"value":[],"is_set":true,"type":"array"},...}
四、参数总览
环境变量按职能分五组：数据库、文件位置、网络、外部目录、诊断。另有 Docker 专属的 PUID/PGID/TZ。全部参数均以环境变量传入，无传统配置文件。
五、核心参数分类详解
5.1 数据库参数
| 参数 | 默认值 | 说明 |
|---|---|---|
SPOOLMAN_DB_TYPE | sqlite | 数据库类型：sqlite / postgres / mysql / cockroachdb |
SPOOLMAN_DB_HOST | 空 | 数据库主机名（外部库必填） |
SPOOLMAN_DB_PORT | 空 | 数据库端口 |
SPOOLMAN_DB_NAME | 空 | 数据库名（仅外部库；SQLite 下不适用） |
SPOOLMAN_DB_USERNAME | 空 | 登录用户名 |
SPOOLMAN_DB_PASSWORD | 空 | 登录密码 |
SPOOLMAN_DB_PASSWORD_FILE | 空 | 从文件读取密码，优先级高于 SPOOLMAN_DB_PASSWORD（供 Docker secrets 使用） |
SPOOLMAN_DB_QUERY | 空 | 连接串附加参数，如 unix_socket=/path/to/mysql.sock 走 MySQL socket |
⚠️ 注意（含实测修正）：官方 Wiki 称「SQLite 模式下设置
SPOOLMAN_DB_NAME会拒绝启动」，但 v0.27.0 实测服务照常 active、健康检查返回 healthy——该参数在 SQLite 模式下实际被忽略而非致命。尽管如此，仍建议遵循官方文档不在 SQLite 下设置它（行为可能在未来版本收紧）。若确需给 SQLite 库换位置，用SPOOLMAN_DIR_DATA移动整个数据目录，库文件名固定为spoolman.db。
切换 PostgreSQL 示例（.env）：
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
改后重启生效：
systemctl restart Spoolman
5.2 文件位置参数
| 参数 | 默认值 | 说明 |
|---|---|---|
SPOOLMAN_DIR_DATA | ~/.local/share/spoolman | 数据目录（SQLite 库、日志、缓存都在此） |
SPOOLMAN_DIR_BACKUPS | <数据目录>/backups | SQLite 自动备份目录 |
SPOOLMAN_DIR_LOGS | <数据目录> | 日志目录（spoolman.log，午夜轮转留 5 份） |
SPOOLMAN_AUTOMATIC_BACKUP | TRUE | 每晚自动备份 SQLite 库，保留 5 份（仅对 SQLite 生效） |
数据目录内容（实测）：
backups/ cache/ spoolman.db spoolman.log
5.3 网络参数
| 参数 | 默认值 | 说明 |
|---|---|---|
SPOOLMAN_HOST | 0.0.0.0 | 监听地址 |
SPOOLMAN_PORT | standalone .env 默认 7912；Docker 镜像内 8000 | 监听端口 |
SPOOLMAN_BASE_PATH | 空 | 子路径反代，如 /spoolman |
SPOOLMAN_CORS_ORIGIN | 空（仅允许同源） | 额外允许的跨域来源，逗号分隔，每条必须带 scheme（如 https://fluidd.local）；* 表示完全关闭检查 |
SPOOLMAN_ALLOWED_HOSTS | 空（off） | 允许访问的主机名列表，防 DNS rebinding；不带 scheme 和端口；*.mydomain.com 含子域 |
⚠️ 注意：
SPOOLMAN_CORS_ORIGIN=*会让任意网站在后台读写你的 Spoolman 数据，仅限受信网络使用。- IP 地址、单名主机、
.local/.lan/.home/.home.arpa/.internal结尾的主机名始终放行；一旦设置了SPOOLMAN_ALLOWED_HOSTS，反代域名必须列入，否则所有请求返回 400。- 官方 Wiki 有专门 Security 页解释这两个参数的配合关系：https://github.com/Donkie/Spoolman/wiki/Security
5.4 外部耗材目录参数
这三个参数没有 SPOOLMAN_ 前缀（官方历史原因）：
| 参数 | 默认值 | 说明 |
|---|---|---|
EXTERNAL_DB_URL | https://donkie.github.io/SpoolmanDB/ | 外部耗材目录地址；设为空字符串禁用 |
EXTERNAL_DB_NAME | SpoolmanDB | 外部目录在 UI 中的显示名 |
EXTERNAL_DB_SYNC_INTERVAL | 3600 | 同步间隔秒数；0 表示仅在启动时同步一次 |
5.5 诊断与运行参数
| 参数 | 默认值 | 说明 |
|---|---|---|
SPOOLMAN_LOGGING_LEVEL | INFO | 日志级别：DEBUG / INFO / WARNING / ERROR / CRITICAL |
SPOOLMAN_METRICS_ENABLED | FALSE | 开启后暴露 Prometheus /metrics 端点 |
SPOOLMAN_LEGACY_CLIENT | FALSE | TRUE 回退旧版 React 客户端（新旧客户端共用同一 API，数据不受影响） |
SPOOLMAN_DEBUG_MODE | FALSE | 调试模式：关闭来源校验并返回内部错误详情，生产环境严禁开启 |
TZ | UTC | 时区，仅 Docker 部署有效 |
PUID / PGID | 1000 | 容器内运行用户/组，仅 Docker 有效；PUID 不可为 0 |
SPOOLMAN_LOGGING_LEVEL=DEBUG 实测验证（standalone）：
sed -i 's/^#SPOOLMAN_LOGGING_LEVEL=INFO/SPOOLMAN_LOGGING_LEVEL=DEBUG/' ~/Spoolman/.env
systemctl restart Spoolman
journalctl -u Spoolman --no-pager --since "-1min" | grep DEBUG | head -2
实测回显：
hishel.controller DEBUG Considering the resource located at https://donkie.github.io/SpoolmanDB/filaments.json as needing revalidation since it is not fresh.
hishel.controller DEBUG Adding the 'If-Modified-Since' header with the value of 'Sat, 12 Sep 2026 16:52:37 GMT' to the request for the resource located at https://donkie.github.io/SpoolmanDB/filaments.json.
可见 DEBUG 级会打出 HTTP 缓存校验（hishel）与数据库 SQL 明细，日志量明显增大，定位问题后应调回 INFO。
5.6 Web UI 设置（存数据库，即时生效）
以下设置在 Web 界面「Settings」页修改，存于数据库，不属于环境变量：
| 设置键 | 类型 | 说明 |
|---|---|---|
currency | string | 显示货币（如 CNY、EUR；未设置时接口返回 is_set:false） |
round_prices | boolean | 价格取整显示 |
extra_fields_* | — | 自定义扩展字段（丝盘/耗材/厂商维度） |
locations | array | 存放位置列表（如干燥箱编号） |
base_url | string | 外部访问基础 URL（用于标签打印等场景生成链接） |
print_presets | array | 打印预设（挤出机/热床温度等） |
label_designs | array | 标签模板 |
dashboard_* | — | 仪表盘显示偏好 |
六、生产配置模板
场景：家庭/工作室单机（4GB+ 内存，SQLite，内网访问）——.env 推荐配置：
SPOOLMAN_HOST=0.0.0.0
SPOOLMAN_PORT=7912
SPOOLMAN_LOGGING_LEVEL=INFO
SPOOLMAN_AUTOMATIC_BACKUP=TRUE
SPOOLMAN_METRICS_ENABLED=FALSE
EXTERNAL_DB_SYNC_INTERVAL=3600
场景：多客户端高频写入（工作室多台打印机 + 报表系统，16GB 内存，独立 PostgreSQL）：
SPOOLMAN_HOST=0.0.0.0
SPOOLMAN_PORT=7912
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
SPOOLMAN_LOGGING_LEVEL=WARNING
SPOOLMAN_METRICS_ENABLED=TRUE
SPOOLMAN_ALLOWED_HOSTS=spoolman.local
⚠️ 注意：无论哪个场景，
SPOOLMAN_DEBUG_MODE与SPOOLMAN_CORS_ORIGIN=*都不应出现在生产配置中。
七、常见问题
Q1：改了 .env 不生效？
.env 由 start.sh 在启动时读取，必须 systemctl restart Spoolman（Docker 场景 docker compose up -d）。UI 设置则即时生效无需重启。
Q2：启动日志里配置值和预期不符？
以启动日志的 Using ... 行与 /api/v1/info 返回为准核对生效值。注意 start.sh 用 set -o allexport; source .env，若 .env 中有语法错误（如未加引号的空格值）会导致整行导出失败。
Q3：SQLite 下误设了 SPOOLMAN_DB_NAME 会怎样？
官方 Wiki 称会拒绝启动；v0.27.0 实测服务仍正常启动（该参数被忽略）。建议删除该行以保持与官方文档一致。
Q4：如何确认自动备份在跑？
backups/ 目录下会出现按日期命名的备份文件（保留最近 5 份）；info 接口的 automatic_backups 字段为 true 即已开启（仅 SQLite 有效）。
八、参考链接
- 官方 Wiki（Configuration）：https://github.com/Donkie/Spoolman/wiki/Configuration
- 官方 Wiki（Security）：https://github.com/Donkie/Spoolman/wiki/Security
.env.example原文：随安装包提供（~/Spoolman/.env.example）- 安装部署：见本专栏《Ubuntu 22.04 安装 Spoolman v0.27.0 指南》《Spoolman v0.27.0 Docker Compose 部署指南》
- API 使用：见本专栏《Spoolman v0.27.0 API 使用详解》