Note Mark 配置参数详解（基于 1.1.1 实测）

Note Mark 1.1.1 全部环境变量配置项逐项详解：监听与 Unix Socket、认证密钥与有效期、访问控制开关、文件上传限制、OIDC 单点登录、日志与运行模式，附组合配置示例与启动校验排障实录。

Note Mark自托管笔记MarkdownRust语言2026/10/30

Note Mark 配置参数详解（基于 1.1.1 实测）

Note Mark 全部行为通过环境变量配置，无配置文件。本文基于 1.1.1 源码配置定义逐项核对，并在 Ubuntu 22.04 服务器实测关键项。阅读前置：完成《Note Mark Docker Compose 部署指南》中的基础部署。

一、配置模型总览

Note Mark 在启动时解析环境变量并做严格校验，任一必填项缺失或校验失败都会直接拒绝启动，错误信息打印在标准输出的 JSON 日志中。配置命名有两个规则：

  1. 嵌套分组用双下划线：如 BIND__HOST 表示 Bind 分组下的 Host，AUTH_TOKEN__SECRET 表示 AuthToken 分组下的 Secret；
  2. 绝大多数项有默认值：真正必填的只有 AUTH_TOKEN__SECRET、DATA_PATH、PUBLIC_URL 三项（官方发行版内已预置 BIND__HOST=0.0.0.0、BIND__PORT=8080、DATA_PATH=/data、STATIC_PATH=/static，因此 compose 里只需补业务项）。

二、服务监听（BIND__ 分组）

环境变量默认值说明
BIND__HOST127.0.0.1TCP 监听地址。裸进程运行时默认只听本机回环，对外提供服务必须显式设为 0.0.0.0；官方发行版内已预置。
BIND__PORT8080TCP 监听端口，1~65535。
BIND__UNIX_SOCKET空（不启用）Unix Socket 文件路径。实测设置后服务转为只监听 Socket，覆盖 TCP 监听（启动日志输出 Serving on /data/nm.sock，8080 不再被占用）。路径所在目录需对运行账号可写，官方场景一般指向数据目录内。

Socket 模式典型用途：与 Nginx/Caddy 同机反向代理时免去 TCP 端口暴露，代理侧以 unix: 方式上游对接。Socket 文件随服务停止自动清理。

三、认证与令牌（AUTH_TOKEN__ 分组）

环境变量默认值说明
AUTH_TOKEN__SECRET必填JWT 签名密钥，值需 Base64 编码，解码后长度不足 32 字节启动失败。推荐 openssl rand -base64 96 生成。所有登录态（Bearer 令牌与会话 Cookie）都由它签名。
AUTH_TOKEN__EXPIRY259200访问令牌有效期，单位秒，默认 259200 即 3 天。实测登录接口返回 expires_in: 259200 与此对应。

密钥泄露等同于全部用户凭证泄露，轮换密钥会使所有在线会话失效，可在安全事件中作为强制登出手段。

四、路径与前端资源

环境变量默认值说明
DATA_PATH必填数据根目录，SQLite 数据库与全部笔记文件落在这里。官方发行版内预置 /data，配合命名卷挂载。
STATIC_PATH空前端静态资源目录。官方发行版内预置 /static，自编译部署时指向构建产物目录；留空则不托管前端页面（纯 API 模式）。
CUSTOM_CSS_PATH空自定义 CSS 文件路径，必须指向存在的文件（校验 file 类型）。设置后前端界面加载 /api/static/custom.css 时返回该文件内容。

CUSTOM_CSS_PATH 实测记录：挂载一个内容为 body{font-family:sans-serif} 的 custom.css 并配置路径后，请求 /api/static/custom.css 原样返回文件内容；未配置该项时同接口返回 HTTP 200 空响应体，前端样式不受影响，可放心留空。

五、站点身份与访问控制开关

环境变量默认值说明
PUBLIC_URL必填对外访问基地址，如 http://192.168.1.200:8136。校验为合法 URL 且末尾不能带斜杠（实测带斜杠启动失败）。它同时是 CORS 允许来源与 OIDC 回跳地址的组成部分。
ENABLE_INTERNAL_SIGNUPtrue是否开放站内注册。实测该值反映在 /api/info 的 allowInternalSignup 字段。纯私有部署建议关闭，用户改由 CLI 创建。
ENABLE_INTERNAL_LOGINtrue是否允许站内账号密码登录。接入 OIDC 后可关闭，强制走单点登录。
ENABLE_ANONYMOUS_USER_SEARCHtrue未登录用户是否可用用户搜索接口。实测开启时匿名请求 /api/users/search?username=adm 返回 ["admin"]。介意用户名枚举的公开实例建议关闭。

六、上传与资源限制

环境变量默认值说明
FILE_SIZE_LIMIT12M单个笔记/附件内容上限，支持 K/M/G 后缀。上传超过限制的附件会被拒绝。

Note Mark 无独立数据库服务、无后台任务队列，内存占用主要来自笔记树缓存，小实例几百 MB 内存即可稳定运行。

七、OIDC 单点登录（OIDC__ 分组）

环境变量默认值说明
OIDC__DISPLAY_NAME分组启用时必填登录页显示的提供商名称。
OIDC__PROVIDER_NAME分组启用时必填提供商内部标识。
OIDC__ISSUER_URL分组启用时必填OIDC Issuer 地址（合法 URL 校验）。
OIDC__CLIENT_ID分组启用时必填客户端 ID。
OIDC__ENABLE_USER_CREATIONtrueOIDC 首次登录是否自动建号。关闭后需 CLI 预建账号并绑定映射。

五个 OIDC 变量是一个联动分组：配置组内任一项即视为启用 OIDC，组内必填项需全部给出，否则启动校验失败。已存在用户可通过 user add-oidc-mapping 子命令绑定外部身份。

八、日志与运行模式（LOGGING__ 分组及其他）

环境变量默认值说明
LOGGING__LEVELinfo日志级别，可选 debug/info/warn/warning/error，其余值启动失败。
LOGGING__ENABLE_JSONtrue结构化 JSON 日志开关。实测默认输出 {"@timestamp":"...","log.level":"INFO","message":"..."} 格式，便于日志系统采集；设为 false 切换人类可读文本格式。
ENV_MODEproduction运行模式，可选 production/development。development 模式日志会附带来源位置，便于排障。

九、组合配置示例

9.1 反向代理 + Unix Socket（推荐生产形态）

environment:
  BIND__UNIX_SOCKET: "/data/nm.sock"
  AUTH_TOKEN__SECRET: "<openssl rand -base64 96 生成>"
  PUBLIC_URL: "https://notes.example.com"
  ENABLE_INTERNAL_SIGNUP: "false"
  LOGGING__LEVEL: "info"

Nginx 上游写法：

location / {
    proxy_pass http://unix:/var/lib/docker/volumes/notemask_data/_data/nm.sock;
    proxy_set_header Host $host;
}

9.2 纯内网小团队

environment:
  BIND__HOST: "0.0.0.0"
  BIND__PORT: "8080"
  AUTH_TOKEN__SECRET: "<密钥>"
  PUBLIC_URL: "http://192.168.1.200:8136"
  ENABLE_ANONYMOUS_USER_SEARCH: "false"
  FILE_SIZE_LIMIT: "50M"

9.3 接入 OIDC 强制单点登录

environment:
  AUTH_TOKEN__SECRET: "<密钥>"
  PUBLIC_URL: "https://notes.example.com"
  ENABLE_INTERNAL_SIGNUP: "false"
  ENABLE_INTERNAL_LOGIN: "false"
  OIDC__DISPLAY_NAME: "公司统一登录"
  OIDC__PROVIDER_NAME: "corp-sso"
  OIDC__ISSUER_URL: "https://sso.example.com/realms/corp"
  OIDC__CLIENT_ID: "note-mark"

十、排障实录

  1. 启动即退出，日志提示 validation failed：逐项核对必填三件套（SECRET/DATA_PATH/PUBLIC_URL）。实测最常见的两个坑是 PUBLIC_URL 尾部带 /、AUTH_TOKEN__SECRET 解码后不足 32 字节。
  2. 服务正常但局域网其他机器访问不通：自编排环境漏设 BIND__HOST=0.0.0.0，默认回环监听导致，宿主机本机 curl 正常、外部超时。
  3. 改了笔记文件但页面树不更新：树缓存机制所致，执行 clear-cache（详见部署篇排障章节）。
  4. custom.css 不生效：确认 CUSTOM_CSS_PATH 指向的文件在服务进程视角真实存在（校验规则是 file），并确认通过 /api/static/custom.css 访问返回的是文件内容而非空体；空体说明路径未生效。
  5. OIDC 配置后启动失败：检查 OIDC 分组是否只写了一半变量——启用分组后 DISPLAY_NAME/PROVIDER_NAME/ISSUER_URL/CLIENT_ID 四项缺一不可。

十一、下一篇

配置就绪后，可将空间、笔记与分享控制全部脚本化，详见《Note Mark REST API 使用详解》；组件背景回顾《Note Mark 介绍与选型指南：轻量级自托管 Markdown 笔记与分享服务》。