SiYuan 3.8.8 配置参数详解

目标：系统讲清 SiYuan 3.8.8 的三套配置入口——启动参数（kernel serve flags）、主配置文件（工作区 conf/conf.json，约 700 行 JSON）与环境变量，按「参数查看与修改方式 → 全量参数总览 → 分类逐项详解 → 生产配置模板」展开；编辑器只读与服务端只读的边界、配置生效机制均以实测回显为准。

一、环境信息

本篇实测环境与取材来源如下：

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• SiYuan：v3.8.8（官方最新稳定版，部署形态见 《SiYuan 3.8.8 Docker Compose 部署指南》）
• 工作区路径：/siyuan/workspace（服务端形态），主配置文件 /siyuan/workspace/conf/conf.json（实测 15708 字节）
• 服务端口：6806（固定服务端口）；本机另有一个动态分配的本地 HTTPS 管理端口（实测 38699，记录在 serverAddrs）
• 配置文件基线：首次启动自动生成，confVersion: 6（实测值，内核用它做配置结构版本迁移）
• 取材方式：参数总览与默认值全部取自实测环境 conf.json 原文与 kernel serve --help 实测输出，未逐字转述官方文档；行为类结论（只读边界、生效机制）以实测回显为准

二、前置条件

读者已按部署指南完成一次可用部署并能进入 Web 界面；已确认工作区目录存在且可写：

ls /siyuan/workspace/conf/conf.json

/siyuan/workspace/conf/conf.json

对配置文件的手工操作（查看、备份、修改）建议始终先备份一份：

cp /siyuan/workspace/conf/conf.json /siyuan/workspace/conf/conf.json.bak

三、参数查看与修改方式

SiYuan 的参数分布在三个入口，先分清再动手：

3.1 查看参数

方法一：直接读文件（推荐用 python 提取关注字段）：

python3 -c "import json; d=json.load(open('/siyuan/workspace/conf/conf.json')); print(d['logLevel'], d['accessAuthCode'], d['api']['token'])"

debug q1w2e3r4 3x5z8hcrcihizxyb

方法二：用内核自带的文件读取命令（CLI 全貌见《SiYuan 3.8.8 常用 CLI 命令与工具详解》）：

/opt/siyuan/kernel -w /siyuan/workspace/ file stat conf/conf.json

Path:    conf/conf.json
Size:    15708
IsDir:   false
ModTime: 2026-10-22 08:46:36

3.2 修改参数与生效机制

界面修改：设置面板的每一项改动都会即时回写 conf.json 并生效，这是官方设计的首选路径。

文件修改：服务运行中直接改文件，改动存在被覆盖的风险——内核把配置持有在内存中，任何一次界面保存或内部配置变更都会把内存值整文件写回，手工改动随之丢失。可靠流程：

# 1. 停止服务（启停方式见[《SiYuan 3.8.8 Docker Compose 部署指南》](https://www.quzuo.net/document/pMrVCjDDE2sv)第十章；裸机部署为停止对应内核服务进程）
# 2. 编辑配置
vim /siyuan/workspace/conf/conf.json
# 3. 启动服务，确认改动已加载

启动参数：以内核启动参数（kernel serve）传入，随服务重建生效（详见部署指南第七章）。

3.3 两类「只读」的边界（实测）

conf.json 的 readonly 字段与 serve --readonly 启动参数不是一个东西，实测对比如下：

• 把 conf.json 的 "readonly": false 改为 true 并重启服务后，调用 Kernel API 创建笔记本仍然成功：

curl -s http://localhost:8131/api/notebook/createNotebook \
  -H "Authorization: Token 3x5z8hcrcihizxyb" -H 'Content-Type: application/json' \
  -d '{"name": "只读模式测试"}'

{"code":0,"msg":"","data":{"notebook":{"id":"20261022091731-d3o88lh","name":"只读模式测试","icon":"","sort":2,"sortMode":15,"closed":false,"subFileCount":0,"newFlashcardCount":0,"dueFlashcardCount":0,"flashcardCount":0,"encrypted":false,"unlocked":false}}}

• 改用启动参数 --readonly=true 重建服务后，同一写请求被服务端拒绝：

curl -s http://localhost:8131/api/notebook/createNotebook \
  -H "Authorization: Token 3x5z8hcrcihizxyb" -H 'Content-Type: application/json' \
  -d '{"name": "服务端只读测试"}'

{"code":-1,"msg":"This operation is not supported in read-only mode","data":{"closeTimeout":5000}}

结论：conf.json 的 readonly（以及 editor.readOnly）控制界面编辑器的只读展示；要对整个服务端做只读防护（如公开只读库），必须使用 serve --readonly=true 启动参数。

四、参数总览

conf.json 顶层键全量清单（实测环境原文键名，按字母序）：

启动参数（kernel serve，--help 实测）与镜像环境变量不在本表内，分别在 3.2/部署指南第六、七章覆盖。

💡 技术拓展：桌面软件的配置存放常见三种模式——

模式	代表	特点
单文件（JSON/INI/TOML）	SiYuan（conf.json）、Trilium（config.ini）	集中可见、易备份、易脚本化预置
数据库存配置	Joplin（SQLite 内）	与数据同生命周期，但裸读困难
多文件目录（conf.d 风格）	Nginx、systemd	模块化强，适合大量片段组合

SiYuan 选择单文件 JSON：一个 conf.json 承载全部设置，优点是备份迁移只需复制一个文件，代价是文件较长（实测 700 行左右），手工检索建议配合 python3 -c 或 jq 按键提取。本方案即采用单文件模式。

五、核心参数分类详解

以下逐域讲解高频参数。每项格式：键名（实测默认值）——含义与改动影响。默认值一律取自实测环境 conf.json 原文或 --help 回显。

5.1 访问与鉴权域

accessAuthCode（实测 q1w2e3r4，演示值）——Web 端访问口令。部署时由 serve --accessAuthCode 写入，之后两者需保持一致（以启动参数为准重建服务，或停服改文件）。为空时任何知道地址的人都能打开数据，公网部署必须设置。

api.token（实测 3x5z8hcrcihizxyb，首次启动自动生成的 16 位随机串）——Kernel HTTP API 的鉴权令牌，调用方式为请求头 Authorization: Token <token>。泄露处置：停服改 conf.json 换新随机串再启动，旧 token 立即失效。API 域的完整用法见《SiYuan 3.8.8 常用 CLI 命令与工具详解》相应章节。

publish（实测 enable: false, port: 6808, auth.enable: true）——文档发布服务的开关与端口。开启后内核在 6808 再起一个对外的只读发布站点，与主服务 6806 相互独立；auth.accounts 为发布站点的账号列表（默认空）。

oidc（实测 enabled: false）——OIDC 单点登录。需要企业 IdP（Keycloak/Authentik 等）对接时开启，填 issuerURL/clientID/clientSecret/redirectURL 四要素；claimRules 可按声明控制访问。默认关闭时走「口令 + api.token」双通道。

cookieKey（实测 97mu4ik2afkgtd4e，自动生成）——会话 Cookie 的签名密钥，勿手改；换它会导致所有已登录会话失效。

5.2 系统运行域

logLevel（顶层键，实测 debug）——内核日志级别，可选 off/trace/debug/info/warn/error/fatal。生产建议 info；排障时临时开 debug。CLI 的 -v/--log-level 全局参数默认取这个值（--help 原文：defaults to conf.json system.logLevel）。

system 段——内核自动写入的运行环境记录，手工改动无意义，但它是排查路径问题的第一手资料。实测节选（保留原始键值）：

"system": {
    "id": "p6ygxqv62urj",
    "kernelVersion": "3.8.8",
    "os": "linux",
    "homeDir": "/root",
    "workspaceDir": "/siyuan/workspace",
    "appDir": "/opt/siyuan",
    "confDir": "/siyuan/workspace/conf",
    "dataDir": "/siyuan/workspace/data",
    "networkServe": false,
    "networkServeTLS": false,
    "networkProxy": { "scheme": "", "host": "", "port": "" },
    "downloadInstallPkg": true,
    "lockScreenMode": 0,
    "safeMode": false
}

关键字段：networkServe（是否开启网络服务模式）、networkProxy（内核出网代理，访问集市/官方云慢时在此配置）、safeMode（安全模式标记，与 serve --safe-mode 对应）。id/name 为实例标识，同步多端时用于区分设备。

serverAddrs（实测 ["http://10.89.62.10:38699", "http://127.0.0.1:38699"]）——内核本机管理通道地址，端口号每次启动动态分配，自动生成勿手改。

stat 段（实测 treeCount: 0, cTreeCount: 100, blockCount: 0, cBlockCount: 5000, dataSize: 57741, cDataSize: 104857600）——带 c 前缀的键是阈值：树数超 100、块数超 5000、数据量超 100MB 时界面给出性能提示。可按硬件放宽或收紧。

confVersion（实测 6）——配置结构版本，内核升级时自动迁移（3.8.7→3.8.8 实测无迁移动作、直接兼容），勿手改。

5.3 界面与文件树域

lang（顶层键，实测 en；appearance.lang 同步存在）——界面语言，zh-CN/en/ja 等 22 种（serve --lang 参数可选值即全量清单）。

appearance.mode: 0 / appearance.modeOS: true——明暗主题模式：0=浅色 1=深色；modeOS: true 表示跟随操作系统。

appearance.themeLight: "daylight" / themeDark: "midnight"——内置主题名，装了第三方主题后在这里切换。

fileTree.maxListCount: 512——文档树单层最大列出条数，文档极多的笔记本可调大。

fileTree.maxOpenTabCount: 8——最大打开标签页数。

fileTree.sort: 6——文档树排序模式数字编码（界面「排序方式」的可视化选择即写这里）。

fileTree.largeFileWarningSize: 8——超过 8MB 的文档打开前告警。

keymap: {}——快捷键映射，界面里改快捷键后此处出现条目；空对象表示全部用内置默认。

snippet.enabledCSS: true / enabledJS: true——自定义 CSS/JS 片段的总开关（片段本体存工作区 data/snippets/）。安全敏感环境可把 JS 关掉。

5.4 编辑器域（editor）

editor.fontSize: 16——正文字号。

editor.dynamicLoadBlocks: 192——长文档动态加载体积（块数），翻页滚动时按此批量渲染；大文档卡顿可调小，滚动流畅度换内存。

editor.generateHistoryInterval: 10——历史版本生成间隔（分钟），编辑后每 10 分钟落一份历史。

editor.historyRetentionDays: 30——本地历史保留天数，过期清理。重要工作区建议调大。

editor.readOnly: false——编辑器只读（界面层，与 3.3 的服务端只读区分）。

editor.virtualBlockRef: false + virtualBlockRefInclude/Exclude——虚拟引用：把命中的关键词按引用展示（不真正建立链接），开关加包含/排除关键词。

editor.backlinkExpandCount: 8 / backmentionExpandCount: -1——反链面板默认展开条数；-1 表示全部展开。

editor.markdown.*——Markdown 语法糖开关组（实测全开项：inlineAsterisk/inlineUnderscore/inlineSup/inlineSub/inlineTag/inlineMath/inlineStrikethrough/inlineMark/codeBlockMiddleDot 等），控制行内语法是否自动识别。

editor.spellcheck: false——拼写检查；中文环境默认关。

editor.plantUMLServePath（实测 https://www.plantuml.com/plantuml/svg/~1）——PlantUML 渲染服务地址，内网环境可指向自建 PlantUML 服务。

5.5 导出域（export）

export.blockRefMode: 4——导出时块引用的转换模式（数字编码，界面「设置-导出」提供可视化选项）。

export.addTitle: true——导出 Markdown 时把文档标题写入首行。

export.markdownYFM: false——导出 Markdown 是否带 YAML front-matter（实测 CLI 的 export md 输出带 title/date/lastmod 三行的 YFM，对应此配置族）。

export.pandocBin: ""——pandoc 可执行文件路径，导出 Word 依赖 pandoc，装好后填绝对路径；pandocParams 附加参数。

export.pdfFooter: "%page / %pages"——PDF 页脚模板（页码/总页数占位符）。

⚠️ 注意：服务端形态不支持导出 PDF/HTML/Word（官方明确限制），导出域的大部分参数在桌面端生效；服务端可用的是 Markdown/.sy 导出（CLI export md/export sy 实测可用，见命令详解篇）。

5.6 搜索域（search）

search.limit: 64——全局搜索默认返回条数上限。

search.caseSensitive: false / hanSensitive: true——大小写敏感与汉字敏感（简繁/变体匹配）。

search.* 类型开关组（实测默认 true 的有：document/heading/paragraph/codeBlock/mathBlock/table/htmlBlock/databaseBlock/asset 内容等；默认 false 的有：list/listItem/blockquote/superBlock/embedBlock/audioBlock/videoBlock/iframeBlock/widgetBlock/callout）——控制各块类型是否纳入搜索范围。按需把不关心的类型关掉可提速并降噪。

search.backlinkMentionKeywordsLimit: 512——提及（unlinked mentions）分析时每块参与匹配的关键词上限。

5.7 同步与数据仓库域（sync / repo / notebookCrypto）

sync.enabled: false——同步总开关。自托管场景的两种用法：

• 对接官方云（provider: 0，会员功能）；
• 自建 S3/WebDAV：provider 换对应编码后填 sync.s3.* 或 sync.webdav.*。实测默认段：s3: {endpoint: "", region: "", pathStyle: true, skipTlsVerify: true, timeout: 60, concurrentReqs: 8}、webdav: {endpoint: "", timeout: 60, concurrentReqs: 1}——MinIO 等 S3 兼容存储开 pathStyle: true 即可对接。

sync.mode: 1——同步模式（自动/手动/完全重传等编码）；sync.interval: 30——自动同步间隔（秒）。

sync.generateConflictDoc: false——冲突时是否生成冲突文档副本；多人/多端写入频繁的建议开启。

sync.lan.enabled: false + maxConcurrentReqs: 16——局域网直连同步（同网段设备点对点）。

repo.key: null——数据仓库密钥（快照体系的根密钥）。未初始化时 CLI 的 repo 命令族直接报错（实测原文：Error: Please initialize the data repo key first in [Settings - Account & Sync - Data repo - Data repo key]）。密钥一旦初始化，必须另地备份：密钥丢失 = 快照不可解密。

repo.syncIndexTiming: 12000——同步索引时机（毫秒）；repo.indexRetentionDays: 180——快照保留天数；repo.retentionIndexesDaily: 2——每日保留的快照数。

notebookCrypto.enabled: false——笔记本加密。开启后用主口令派生密钥（实测 kdfParams: {memory: 65536, iterations: 3, parallelism: 4, keyLength: 32}，Argon2 类参数），笔记本落盘加密，autoLockMinutes: 5 自动上锁。注意：开启属不可逆重操作，需先备份。

5.8 AI 域（ai）

ai.providers: []——自定义模型接入列表（OpenAI 兼容端点），填 apiKey/baseURL/name 即可接入。

ai.embedding: {enabled: false, dimensions: 0, concurrency: 8, batchSize: 10}——向量 embedding（语义搜索）配置，接入后 id 指向提供方。

ai.rerank: {enabled: false, requestFormat: "cohere", candidateCount: 30}——重排序服务，requestFormat 支持 cohere 等格式。

ai.agent 段（实测 sessionTimeout: 1800, maxToolCallRounds: 64, temperature: 1 等）——AI 智能体会话参数，含能力策略（capabilityPolicy）与审批策略（approvalPolicy，默认 risk 风险分级审批）。

ai.mcp: {servers: [], exposurePolicy: {default: "allow"}}——内建 MCP 服务端与暴露策略，供外部 AI 客户端接入本工作区。

ai.web: {searchProvider: "exa", fetchProvider: "direct", timeout: 30}——AI 联网搜索/抓取通道。

5.9 OCR 与闪卡域

ocr: {provider: "paddleocr", model: "tiny", auto: false, showText: true}——图片文字识别。默认 paddleocr 引擎 + tiny 模型（体积小速度快）；model 可换更大精度模型；auto: true 时插入图片自动识别。

flashcard: {newCardLimit: 20, reviewCardLimit: 200, requestRetention: 0.9, maximumInterval: 36500}——间隔重复记忆。requestRetention: 0.9 是 FSRS 算法的目标记忆保持率（0.9=期望记住 90%），调大→复习更频繁；weights 字段为 FSRS 17 参数向量（实测 19 项逗号分隔值，默认即官方调优值，无特殊需求勿动）。

💡 技术拓展：间隔重复调度算法主流两派——

算法	特点	适用
SM-2（Anki 经典）	按对/错调整间隔，参数少	轻量、可解释
FSRS	多参数状态模型，按目标保持率调度，实测作为 SiYuan 默认	追复习效率与个性化

SiYuan 3.8.8 默认采用 FSRS（weights 即其参数向量），requestRetention 是用户最值得调的单参数。

5.10 图形与其他域

graph.maxBlocks: 16384——关系图最大渲染块数，超过即截断防卡顿；graph.global.d3.*（nodeSize/linkDistance 等）为力导向图参数。

bazaar: {trust: false, petalDisabled: false}——集市信任标记与插件系统开关。

secrets.items: [] / variables.items: []——内核托管的密钥与自定义变量条目（模板/插件可引用）。

六、生产配置模板

适用场景：2 核 4GB 内存、40GB+ SSD、单用户/小团队自托管知识库（实测该规模下内核空载内存约 109MiB，余量充足）。以下为「在自动生成的 conf.json 基础上建议覆盖的关键项」模板（非全量文件，逐项给出取值理由）：

{
  "logLevel": "info",
  "accessAuthCode": "q1w2e3r4",
  "api": { "token": "3x5z8hcrcihizxyb" },
  "readonly": false,
  "lang": "zh-CN",
  "editor": {
    "fontSize": 16,
    "dynamicLoadBlocks": 192,
    "generateHistoryInterval": 10,
    "historyRetentionDays": 90,
    "readOnly": false
  },
  "search": {
    "limit": 64,
    "caseSensitive": false,
    "hanSensitive": true
  },
  "sync": {
    "enabled": true,
    "mode": 1,
    "interval": 30,
    "provider": 1,
    "s3": {
      "endpoint": "http://minio.example.com:9000",
      "accessKey": "minioadmin",
      "secretKey": "q1w2e3r4",
      "bucket": "siyuan-sync",
      "region": "us-east-1",
      "pathStyle": true,
      "skipTlsVerify": true,
      "timeout": 60,
      "concurrentReqs": 8
    }
  },
  "repo": {
    "indexRetentionDays": 180,
    "retentionIndexesDaily": 2
  },
  "stat": {
    "cTreeCount": 100,
    "cBlockCount": 5000,
    "cDataSize": 104857600
  }
}

逐项理由：

• logLevel: info：debug 噪音大，生产无益；
• accessAuthCode/api.token：必须从默认/演示值换成自己的强值（模板保留演示值便于对照）；
• historyRetentionDays: 90：默认 30 天偏短，历史版本是误删最后防线；
• sync.provider: 1 + s3 段：自托管同步选 S3 兼容对象存储（MinIO 自建示例），pathStyle: true 是 MinIO 的必要项；
• repo：快照默认保留 180 天/日 2 份，4GB 内存机器无压力，保持默认即可；
• stat 阈值：默认值对应提示触发线，4GB 内存可维持不动，文档规模巨大再放宽。

应用方式：停服 → 合并覆盖对应键 → 启动 → 按 3.1 的方法回读校验。

七、常见问题

Q1：改了 conf.json 但不生效，或者过一会儿又被改回去了？

服务运行中内核把配置持有在内存，界面保存或内部变更会把内存值整文件回写，手工改动被覆盖。正确流程：停服 → 改文件 → 启动（见 3.2）。启动参数类配置（如 --accessAuthCode）优先于文件值，注意两边一致性。

Q2：readonly 设了 true 怎么 API 还能写入？

conf.json 的 readonly（与 editor.readOnly）只控制界面编辑器展示；服务端级只读必须用启动参数 --readonly=true，实测拒绝写请求并返回 {"code":-1,"msg":"This operation is not supported in read-only mode"}（完整实测见 3.3）。

Q3：忘记访问口令 / api.token 泄露怎么处理？

口令：停服后编辑 conf.json 的 accessAuthCode 为新值，启动生效。token：同法更换 api.token 为新随机串（如 openssl rand -hex 8 生成 16 位），旧 token 立即失效。

Q4：同步报错或集市打不开，怎么让内核走代理？

编辑 conf.json 的 system.networkProxy 三元组（scheme/host/port），停服启动生效；system.networkServe 与证书相关项均在 system 段（见 5.2）。

Q5：配置文件损坏导致起不来怎么办？

恢复路径：用 3.2 节建议的备份副本（conf.json.bak）覆盖回 conf.json 后启动；无备份时，把损坏的 conf.json 移走后启动——内核会按默认值重新生成（文档数据在 data/ 不受影响），但界面设置需重新配置，api.token 也会更换。

八、参考链接

1. 官方 GitHub 仓库（内核与配置说明）：https://github.com/siyuan-note/siyuan （查询日期 2026-10-22）
2. 官方英文用户指南：https://siyuan-en.b3log.org/ （查询日期 2026-10-22）
3. 官方 Kernel HTTP API 文档：https://github.com/siyuan-note/siyuan/blob/master/docs/API.md （查询日期 2026-10-22）
4. 部署与配置文件挂载：《SiYuan 3.8.8 Docker Compose 部署指南》
5. 认知与选型：《SiYuan 3.8.8 介绍与选型指南》
6. 命令行与 API 实操：《SiYuan 3.8.8 常用 CLI 命令与工具详解》