SilverBullet 配置参数详解

目标：把 SilverBullet v2.12.1 的配置体系一次讲透——环境变量全表（网络/数据/认证/运行模式/运行时 API/搜索/可观测/清单外观）逐项实测验证，CONFIG.md 空间配置页与 Dashboard 管理界面三套机制的分工与生效方式，并给出可直接投产的配置模板。全部回显均在下述环境实测通过。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• SilverBullet：v2.12.1（官方镜像 ghcr.io/silverbulletmd/silverbullet:2.12.1，单空间模式主实例 + 三个一次性验证实例）
• 部署形态：Docker Compose（部署细节见 《SilverBullet Docker Compose 部署实战》，下称「部署篇」）
• 主实例：宿主端口 8147 → 服务内 3000，数据目录 /opt/silverbullet/data
• 验证账号：admin / q1w2e3r4；API 令牌：sbtoken-q1w2e3r4-demo
• 官方配置参考实查日期：2026-10-28（Install/Configuration、CONFIG、Dashboard、Authentication 页）

二、前置条件

1. 一套按部署篇启动的 SilverBullet 实例（本文基于 v2.12.1 单空间模式主实例）：

docker compose ps --format 'table {{.Name}}\t{{.Status}}'

实测回显：

NAME                      STATUS
silverbullet-2.12.1-web   Up 2 hours (healthy)

2. 本地有 curl（验证配置端点）与 jq（可选，格式化 JSON）。
3. 理解 SilverBullet 的一个核心设定：没有集中式主配置文件。配置分散在三层，先弄清每层管什么，才不会「改了没生效」：

⚠️ 勘误提示：v2 并不存在 SB_HOME、SB_URL、SETTINGS.lua 这类配置入口（SETTINGS 页是 v1 旧物）。数据目录变量是 SB_FOLDER，URL 前缀变量是 SB_URL_PREFIX，空间配置页是 CONFIG.md（Space Lua 语法）。网上旧教程里的变量名请先对照本文第四、五节官方实查口径。

三、参数查看与修改方式

3.1 看服务级：环境变量与 /.config 端点

查看实例实际注入的环境变量（以「实例创建时」为准，最可靠）：

docker inspect silverbullet-2.12.1-web --format '{{range .Config.Env}}{{println .}}{{end}}' | grep '^SB_\|^PUID\|^PGID'

实测回显：

SB_FOLDER=/data
SB_USER=admin:q1w2e3r4
SB_AUTH_TOKEN=sbtoken-q1w2e3r4-demo
SB_HOSTNAME=0.0.0.0

服务端当前生效配置还暴露在 /.config 端点（需认证）：

curl -s -H 'Authorization: Bearer sbtoken-q1w2e3r4-demo' http://127.0.0.1:8147/.config | python3 -m json.tool

实测回显（单空间模式主实例）：

{
  "spaceFolderPath": "/data",
  "spaceName": "SilverBullet",
  "indexPage": "index",
  "readOnly": false,
  "logPush": false,
  "enableClientEncryption": true,
  "accountManaged": false,
  "shellBackend": "local",
  "disableServiceWorker": false,
  "syncProtocolVersion": 2,
  "revisions": "unmanaged",
  "spacePrefixes": [],
  "shareOwnerId": "2d21cb0e…（64 位十六进制摘要）"
}

关键字段：accountManaged: false 表示环境变量认证（单空间模式）；多空间模式下为 true，账号交给 Dashboard 托管。indexPage 当前值为默认的 index，改法见 5.2。

3.2 改服务级：改 compose 后必须重建实例

环境变量在实例创建时固化，docker compose restart 不会重读 compose.yml。正确流程：

cd /opt/silverbullet
vi compose.yml               # 修改 environment: 段
docker compose up -d         # 检测到配置变化，自动重建实例

实测回显：

 Container silverbullet-2.12.1-web Recreate
 Container silverbullet-2.12.1-web Recreated
 Container silverbullet-2.12.1-web Started

看到 Recreated 才说明新变量真正注入。数据目录 bind mount 不受重建影响，页面零丢失。

3.3 改空间级：CONFIG.md 页面

每个 space 根下可放一个 CONFIG.md 页面（配置页），用 Space Lua 语法写配置。页面即文件——用编辑器、API、甚至宿主 vi 都能改。实测通过 API 创建一个带 config.set 与自定义标签 schema 的配置页：

cat > /tmp/cfg-page.md <<'EOF'
# 空间配置

首页名为 index，任务状态枚举如下。

```space-lua
config.set("view.defaults", {
  ["docs.navigate"] = { open = true, width = 260 },
})

tag.define {
  name = "glossary",
  schema = {
    type = "object",
    properties = {
      description = { type = "string" },
    },
    required = { "description" },
  },
}

EOF curl -s -X PUT -H 'Authorization: Bearer sbtoken-q1w2e3r4-demo'
--data-binary @/tmp/cfg-page.md http://127.0.0.1:8147/.fs/CONFIG.md -w "PUT HTTP %{http_code}\n"

实测回显：

OKPUT HTTP 200

读回与落盘验证：

```bash
curl -s -H 'Authorization: Bearer sbtoken-q1w2e3r4-demo' http://127.0.0.1:8147/.fs/CONFIG.md | head -4
ls -la /opt/silverbullet/data/CONFIG.md

实测回显：

# 空间配置

首页名为 index，任务状态枚举如下。

```space-lua
config.set("view.defaults", {
-rw-r--r-- 1 root root 345 Oct 28 14:58 /opt/silverbullet/data/CONFIG.md

浏览器里打开 CONFIG 页即生效（客户端解释执行 Space Lua）。除了手写，官方还内置 Configuration Manager 图形界面（命令面板执行 Configuration: Open，快捷键 Ctrl-,/Cmd-,）：它把你的修改写进 CONFIG.md 里一个受管理的 space-lua 代码块，两种编辑方式互通。

CONFIG.md 常用配置入口（官方配置页实例实际使用的四类）：

• config.set(key, value)：设置配置键（如视图默认 view.defaults）；
• tag.define { … }：定义自定义标签及 schema（校验、页面装饰、渲染卡片）；
• actionButton.define { … }：定义界面右下角动作按钮；
• query/模板相关 Lua 函数：配合查询体系做自定义展示。

3.4 改实例级：Dashboard（v2 多空间模式）

v2 全新安装的默认形态是多空间模式：空数据目录、无 SB_* 变量启动时进入安装向导（部署篇已实测：GET / 返回 307 重定向到 /.setup/，页面标题 SilverBullet Setup）。初始化后所有实例级配置（管理员账号、每空间的首页名/访问级别、API 令牌）都在 Dashboard 里管理，例如首页名的官方推荐改法是 Space settings → General → Index page，而不是遗留的 SB_INDEX_PAGE。单空间与多空间的取舍见第六节模板。

四、参数总览

SilverBullet 环境变量全表（官方 Install/Configuration 页 2026-10-28 实查口径，默认值照抄官方文档；「实测」列=本文第五节有对应回显）：

网络

Docker 专用

运行时 API（无头浏览器）

指标

单空间模式（官方标记 legacy）：通用

单空间模式：网络

单空间模式：认证

单空间模式：运行模式

Web App 清单外观

五、核心参数分类详解

5.1 网络监听：SB_UNIX_SOCKET 与 SB_URL_PREFIX

Unix socket 监听——不占 TCP 端口，宿主通过 bind mount 的 socket 文件访问，适合「反代同机部署、不想暴露端口」的形态。验证实例（socket 目录挂到 /sock）：

docker run -d --name silverbullet-2.12.1-config-c \
  -v /opt/silverbullet-test/sock:/sock \
  -e SB_FOLDER=/data -e SB_USER=admin:q1w2e3r4 \
  -e SB_UNIX_SOCKET=/sock/sb.sock \
  ghcr.io/silverbulletmd/silverbullet:2.12.1

宿主侧用 curl 走 socket 访问（--unix-socket 指向挂载出来的 socket 文件）：

curl -s --unix-socket /opt/silverbullet-test/sock/sb.sock http://localhost/.ping -w "\nHTTP %{http_code}\n"
ls -la /opt/silverbullet-test/sock/ | grep sb.sock

实测回显：

OK
HTTP 200
srwxr-xr-x  1 root root    0 Oct 28 14:58 sb.sock

URL 子路径——把服务挂到 http://主机/notes/ 而不是根路径（反代场景常用，免独占域名）。验证实例设置 SB_URL_PREFIX=/notes 后的行为对照：

curl -s -m 5 -o /dev/null -w 'GET /.ping -> HTTP %{http_code}\n' "http://<容器IP>:3000/.ping"
curl -s -m 5 -w 'GET /notes/.ping -> ' "http://<容器IP>:3000/notes/.ping"; echo
curl -s -m 5 -o /dev/null -w 'GET /notes/ -> HTTP %{http_code}\n' "http://<容器IP>:3000/notes/"

实测回显：

GET /.ping -> HTTP 404
GET /notes/.ping -> OK
HTTP 200
GET /notes/ -> HTTP 200

无前缀的旧路径一律 404，所有端点都迁移到 /notes/* 之下。反代只需把 location /notes/ { proxy_pass http://127.0.0.1:8147/notes/; } 一类规则对齐前缀即可。

5.2 数据与空间：SB_FOLDER / SB_INDEX_PAGE / SB_FS_WATCH

• SB_FOLDER：单空间模式下即 space 根目录（容器里惯例指到 /data）；多空间模式下它是「服务配置 + 默认空间仓库」的父目录。这是整套配置里最核心的一个变量；
• SB_INDEX_PAGE：改首页页面名。验证实例设 SB_INDEX_PAGE=home（space 里预先放好 home.md），/.config 立即反映：

curl -s -H 'Authorization: Bearer sbtoken-config-test' http://<容器IP>:3000/.config | \
  python3 -c "import sys,json;d=json.load(sys.stdin);print({k:d[k] for k in ('indexPage','readOnly','spaceName') if k in d})"

实测回显：

{'indexPage': 'home', 'readOnly': True, 'spaceName': 'Ops Notes'}

（该验证实例同时设了 SB_READ_ONLY=true 与 SB_NAME="Ops Notes"，可见三项配置一次注入全部生效。）首页名改动后，浏览器访问 / 会打开 home 页。官方口径：此变量已标记 legacy，多空间模式请在 Dashboard 的 Space settings → General 设置 Index page；

• SB_FS_WATCH：控制服务如何感知「外部程序改了文件」。auto（默认）用原生文件系统事件，外部编辑几秒内推送到已打开的客户端；space 放在 NFS/SMB 网络挂载上时原生事件收不到其他机器的写入，官方明确改用 SB_FS_WATCH=poll（配合 SB_FS_POLL_INTERVAL 控制扫描间隔，默认 30 秒，大空间调小代价高）。本文所有「宿主 vi 直接改文件 → 服务内可见」的实测均基于默认 auto。

5.3 认证：SB_USER / SB_AUTH_TOKEN / 锁定参数

SB_USER/SB_AUTH_TOKEN 的基础行为部署篇已实测（登录 200/错误口令 error/Bearer 读写）。这里补测防暴力破解锁定——验证实例设 SB_LOCKOUT_LIMIT=3、SB_LOCKOUT_TIME=5，连续输错 3 次后即使用正确口令也被拒：

# 连续 3 次错误口令
for i in 1 2 3; do curl -s -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'username=admin&password=bad' http://<容器IP>:3000/.auth; echo; done
# 第 4 次：正确口令
curl -s -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'username=admin&password=q1w2e3r4' http://<容器IP>:3000/.auth; echo

实测回显：

{"status":"error","error":"Invalid username and/or password"}
{"status":"error","error":"Invalid username and/or password"}
{"status":"error","error":"Invalid username and/or password"}
{"status":"error","error":"Too many failed attempts — please wait and try again"}

排障注意：锁定窗口内正确口令也报错，报错文案是 Too many failed attempts（默认 10 次失败锁 60 秒）。脚本里做登录重试时务必控制频率，否则会把自己锁在门外。

5.4 运行模式：SB_READ_ONLY

设非空值后整站只读：客户端界面完整、能浏览能搜索，但所有写入被拒。实测（同一验证实例）：

printf '# 不该写进去\n' | curl -s -X PUT \
  -H 'Authorization: Bearer sbtoken-config-test' --data-binary @- \
  http://<容器IP>:3000/.fs/Blocked.md -w "\nHTTP %{http_code}\n"

实测回显：

Read-only: Cannot write file Blocked.md: read-only mode
HTTP 403

适用场景：知识库「发布镜像」（对团队开放只读副本）；只读启动时服务会先做一次全量索引再禁写。注意多空间模式下官方建议用 Dashboard 的「Freeze this space」或公开只读（Publishing）替代该变量。

5.5 运行时 API：Chrome 相关三变量

默认镜像内置 Chromium（CHROMIUM_PATH=/usr/bin/chromium-headless-shell），服务启动时自动探测（部署篇日志：runtime Chrome detected: /usr/bin/chromium-headless-shell）。三个变量用于调整：

• SB_CHROME_PATH：显式指定浏览器路径（官方探测顺序：SB_CHROME_PATH → CHROMIUM_PATH → PATH 自动探测）；
• SB_CHROME_SHOW：调试时以有窗口模式运行（需完整 Chrome，headless-shell 不支持）；
• SB_CHROME_LOG_CONSOLE：默认把无头浏览器 console 输出转发到服务日志，也可在 /.runtime/logs 查看（sb logs）；设 0 关闭。

裸机安装排障时最有用：Space Lua 的 sb eval/sb query 依赖运行时 API，报「Chrome not found」类错误时按此链路补装或显式指路径。

5.6 搜索：SB_SEARCH_DIR / SB_SEARCH_MODEL

全文搜索索引默认存内存（每次重启重建）；SB_SEARCH_DIR 指向空间外的可写目录后索引持久化（重启免重建），且该目录可独立于只读空间。SB_SEARCH_MODEL 进一步启用语义搜索，官方提供两个模型：granite-embedding-97m-multilingual-r2（推荐，约 220 MB）与 multilingual-e5-small（约 488 MB），首次启动时下载到 SB_SEARCH_DIR。模型体积与首次下载耗时是主要代价，个人小空间可不开。

5.7 可观测：SB_METRICS_PORT / SB_HTTP_LOGGING / SB_LOG_PUSH

SB_METRICS_PORT 在独立端口暴露 Prometheus 指标（不影响主端口）。验证实例设 SB_METRICS_PORT=9999：

curl -s http://<容器IP>:9999/metrics | head -8

实测回显：

# HELP silverbullet_http_requests Total number of HTTP requests to SilverBullet
# TYPE silverbullet_http_requests counter
silverbullet_http_requests 2
# HELP silverbullet_proxy_requests Total number of proxy requests in the SilverBullet space
# TYPE silverbullet_proxy_requests counter
silverbullet_proxy_requests 0
# HELP silverbullet_runtime_api_requests_total Total number of runtime API requests received
# TYPE silverbullet_runtime_api_requests_total counter

指标为标准 Prometheus 文本格式（HTTP 请求计数、代理请求计数、运行时 API 请求计数等），Prometheus 直接抓取即可。SB_HTTP_LOGGING 开启后服务日志会带 HTTP 访问记录（排障期临时开启）；SB_LOG_PUSH 让客户端把浏览器侧日志推到服务端（客户端疑难杂症的定位手段）。

5.8 清单外观：SB_NAME / SB_DESCRIPTION

这两个变量注入 PWA manifest（/.client/manifest.json），决定安装到桌面/手机时显示的应用名与描述。验证实例设 SB_NAME="Ops Notes"、SB_DESCRIPTION="团队知识库"：

curl -s http://<容器IP>:3000/.client/manifest.json -H 'Authorization: Bearer sbtoken-config-test'

实测回显（节选）：

{"short_name":"Ops Notes","name":"Ops Notes","icons":[{"src":"/.client/logo-dock.png","type":"image/png","sizes":"512x512"}],"capture_links":"new-client","start_url":"/#boot","display":"standalone","display_override":["window-controls-overlay"],"scope":"/","theme_color":"#e1e1e1","description":"团队知识库"}

同名效果同时体现在 /.config 的 spaceName 字段（见 5.2 实测）。浏览器标签页与应用列表里的名字都随 SB_NAME 变化。

5.9 Docker 专用：PUID / PGID

不设置时入口脚本按 /data 映射目录属主运行服务（部署篇日志：Will run SilverBullet with UID 0, inferred from the owner of /data）。需要固定身份时显式设置，例如与宿主普通用户对齐：

    environment:
      PUID: 1000
      PGID: 1000

设置后启动日志的 UID 行会显示 Will run SilverBullet with UID 1000 (set via PUID environment variable) 口径的提示（UID 来源标注从 inferred 变为显式设置），服务写出的页面文件属主随之固定。

六、生产配置模板

模板 A：单空间模式（个人/小团队自托管，2 核 4 GB 内存、SSD 磁盘）——目录即备份、脚本自动化友好，本文实测形态：

name: silverbullet-2.12.1-stack

services:
  silverbullet:
    image: ghcr.io/silverbulletmd/silverbullet:2.12.1
    container_name: silverbullet-2.12.1-web
    restart: unless-stopped
    environment:
      SB_FOLDER: /data
      SB_USER: admin:<强密码>            # 登录账号
      SB_AUTH_TOKEN: "<强随机令牌>"       # API 令牌
      # SB_SEARCH_DIR: /search           # 可选：搜索索引持久化（需再挂一个卷）
      # SB_METRICS_PORT: 9999            # 可选：Prometheus 指标
    volumes:
      - /opt/silverbullet/data:/data
    ports:
      - "8147:3000"

资源口径：官方未见硬性最低配置要求；本文 1 GB 内存约束的验证环境下索引/编辑/查询流畅，2 GB 内存起可放心使用，SB_SEARCH_MODEL 语义搜索建议 +500 MB 内存余量。

模板 B：多空间模式（团队多库/需要账号体系与权限分级，2 核 4 GB 起）——v2 默认形态，去掉全部单空间变量，空目录启动进 /.setup/ 向导：

name: silverbullet-2.12.1-stack

services:
  silverbullet:
    image: ghcr.io/silverbulletmd/silverbullet:2.12.1
    container_name: silverbullet-2.12.1-web
    restart: unless-stopped
    environment:
      SB_FOLDER: /data       # 多空间模式下：服务配置 + 默认空间仓库父目录
    volumes:
      - /opt/silverbullet/data:/data
    ports:
      - "8147:3000"

初始化、账号与空间访问级别（none/read/write）、每空间首页名与 API 令牌都在 Dashboard 里完成；配合 HTTPS 还可接 OIDC 单点登录（部署篇第十一节）。

形态选择速查：

七、常见问题

Q1：改了 compose.yml 里的环境变量，docker compose restart 后没生效？ 环境变量在实例创建时固化，restart 只是重启同一实例。要用 docker compose up -d 触发 Recreate（重建实例才会重新注入变量），见 3.2 实测回显。

Q2：改了 CONFIG.md 不生效？ config.set/tag.define 是客户端解释执行的 Space Lua，需要在浏览器里刷新页面（或重新打开客户端）后加载新配置；服务端不缓存该页面（页面即文件）。若在 Configuration Manager 里改的，它写回 CONFIG.md 的受管理 space-lua 块，手工改动块外内容不受影响。

Q3：SB_HOME、SB_URL、SETTINGS.lua 这些网上教程里的配置在哪？ v2 里均不存在：数据目录是 SB_FOLDER，URL 前缀是 SB_URL_PREFIX，空间配置页是 CONFIG.md（v1 的 SETTINGS 页体系已淘汰）。以本文第四节官方实查口径为准。

Q4：密码里带冒号/特殊字符导致登录异常？ SB_USER 的格式是 用户名:密码（冒号分隔）。密码本身含冒号会造成解析歧义，避免使用；含 $、引号等 YAML 特殊字符时给整行加引号（部署篇 SB_AUTH_TOKEN 的写法）。

Q5：脚本报登录失败，但账号密码明明是对的？ 触发了防暴力破解锁定（默认连续失败 10 次锁 60 秒，可用 SB_LOCKOUT_LIMIT/SB_LOCKOUT_TIME 调整），报错文案为 Too many failed attempts — please wait and try again（5.3 实测）。等锁定窗口过去再试，并放慢重试频率。

Q6：设置了 SB_URL_PREFIX 后原来的路径全部 404？ 正常现象：所有端点（含 /.ping、/.fs/*、/.auth）都迁到前缀之下（5.1 实测对照），反代规则要按前缀对齐，客户端书签也要更新。

Q7：space 放在 NFS/SMB 上，别人改的文件服务感知不到？ 网络挂载上其他机器的写入不产生本机文件系统事件，auto 监听收不到；按官方口径设 SB_FS_WATCH=poll（必要时配 SB_FS_POLL_INTERVAL），或最好按部署篇前置条件避免网络挂载。

八、参考链接

• 官方配置参考 Install/Configuration（2026-10-28 实查口径）：https://docs.silverbullet.md/Install/Configuration
• 官方 CONFIG 配置页文档：https://docs.silverbullet.md/CONFIG
• 官方 Configuration Manager 文档：https://docs.silverbullet.md/Configuration%20Manager
• 官方认证文档 Authentication：https://docs.silverbullet.md/Authentication
• 官方搜索文档 Search：https://docs.silverbullet.md/Search
• 站内延伸阅读：《SilverBullet 介绍与选型指南》、《SilverBullet Docker Compose 部署实战》