flatnotes v5.5.5 配置参数详解

目标：完整讲清 flatnotes v5.5.5 的全部配置方式与 16 个环境变量的默认值、取值约束、生效机制，并给出面向个人服务器的生产配置模板。参数口径来自官方发行镜像随附源码（v5.5.5）与官方 Wiki《Environment Variables》（实查日期 2026-10-30），验证回显来自真实服务器实测。

一、环境信息

flatnotes 的两个配置事实先行说明：

1. 没有配置文件：所有配置通过环境变量注入，官方 Wiki 明确以《Environment Variables》作为配置文档的唯一载体；
2. 没有运行时可写配置：改任何参数都需要修改启动环境并重启服务生效。

二、前置条件

• 已按《flatnotes v5.5.5 Docker Compose 部署指南》完成部署并可通过 /health 探活：

curl http://localhost:8143/health

实测输出：

"OK"

• 了解服务端当前生效的部分配置，可用内置配置接口查询（该接口仅暴露 UI 相关的 6 个字段）：

curl http://localhost:8143/api/config

实测输出：

{"authType":"password","quickAccessHide":false,"quickAccessTitle":"RECENTLY MODIFIED","quickAccessTerm":"*","quickAccessSort":"lastModified","quickAccessLimit":4}

返回字段为驼峰命名，与下文环境变量一一对应（authType ↔ FLATNOTES_AUTH_TYPE，quickAccess* ↔ FLATNOTES_QUICK_ACCESS_*）。其余参数（用户名、密码、密钥、会话时长等）出于安全考虑不在此接口暴露，只能以启动环境为准。

三、参数查看与修改方式

查看：如上节，/api/config 只能看到一部分；完整清单以下文第四节参数总览为准，逐项核对当前部署的启动环境（compose 的 environment: 段或进程启动环境）。

修改：编辑启动环境后重建服务。以 Compose 形态为例，修改 docker-compose.yml 的 environment: 段后：

cd /opt/flatnotes
docker compose up -d --force-recreate

实测输出：

 Container flatnotes-v5.5.5-web Started

非法取值的后果可以实测复现——把 FLATNOTES_AUTH_TYPE 改成不存在的值启动，服务直接拒绝启动并打印错误：

2026-10-29 17:47:55 [ERROR]: Invalid value 'bogus' for FLATNOTES_AUTH_TYPE. Must be one of: none, read_only, password, totp.

（随后进程退出。）FLATNOTES_QUICK_ACCESS_SORT 与 FLATNOTES_PATH_PREFIX 同理，取值不合法时启动即失败——这是「启动期校验」设计，配置错误不会带到运行期。

四、参数总览

v5.5.5 全部环境变量一览（默认值以官方源码与 Dockerfile 为准）：

⚠️ 注意：FLATNOTES_HIDE_RECENTLY_MODIFIED 是 FLATNOTES_QUICK_ACCESS_HIDE 的废弃旧名，仍可生效但启动日志会提示 deprecated，新配置一律用新名。

五、核心参数分类详解

5.1 认证模式与登录参数（AUTH_TYPE / USERNAME / PASSWORD）

FLATNOTES_AUTH_TYPE 决定整个服务的鉴权面，四个取值的行为差异（源码与实测归纳）：

💡 技术拓展：「自托管单用户应用的两步验证」常见三种实现——TOTP 时间同步动态码（Google Authenticator/AUTHY 等验证器通用，离线可用）、WebAuthn 硬件密钥（安全性最高但需要浏览器与服务端配合）、邮件验证码（依赖外网邮件服务）。flatnotes v5.5.5 采用 TOTP，优点是不依赖任何第三方服务、验证器生态通用，这是同类自托管组件的主流选择。

FLATNOTES_USERNAME 会被服务端统一转为小写存储与比对（登录输入大小写均可命中）；FLATNOTES_PASSWORD 区分大小写，且在 totp 模式下实际校验的是「密码 + 当前 6 位动态码」的拼接串，例如密码 q1w2e3r4、动态码 015396 时登录密码栏输入 q1w2e3r4015396。

密码错误时登录接口实测返回：

{"detail":"Invalid login details."}

（HTTP 401。）

5.2 会话密钥与有效期（SECRET_KEY / SESSION_EXPIRY_DAYS）

FLATNOTES_SECRET_KEY 是 JWT（HS256）签名密钥：登录成功后服务端签发形如 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... 的 Token，内含过期时间；此后所有 API 调用与页面会话都靠该 Token（请求头 Authorization: Bearer <token> 或名为 token 的 Cookie）。三个后果：

• 换密钥 = 全部会话立即失效（可用于「踢掉所有登录」）；
• 密钥泄露 = 会话可被伪造，必须轮换；
• FLATNOTES_SESSION_EXPIRY_DAYS 控制签发时的过期天数（默认 30 天），改短可提升安全性，改长减少重登频率。

验证会话是否有效：

TOKEN=<登录接口取得的 access_token>
curl http://localhost:8143/api/auth-check -H "Authorization: Bearer $TOKEN"

实测输出：

"OK"

不带 Token 时实测返回：

{"detail":"Invalid authentication credentials"}

（HTTP 401。）

5.3 TOTP 参数（TOTP_KEY）

FLATNOTES_AUTH_TYPE: totp 时必填。取任意长随机字符串即可，服务端启动时会把它转成 base32 并在日志打印二维码与手动密钥（实测日志节选，二维码为 ASCII 字符画故省略中部）：

Scan this QR code with your TOTP app of choice e.g. Authy or Google Authenticator:
    █▀▀▀▀▀█ ▄▀ █▄▄█▀▄▀█▀ ▄▄▀██▄▄▀ █▄  █▀▀▀▀▀█
    …（二维码中部省略）…
▀▀▀▀▀▀▀
Or manually enter this key: MZHDE2ZYONLHCNSUPJJDI3KXPA4XATDCGNFGQN2ZMQ2UOYZRJZSQ

用任意验证器 App 扫码（或手动输入该 base32 密钥）后，登录时把当前 6 位动态码拼在密码之后。实测（密码 q1w2e3r4 + 动态码 015396）：

{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTc5NTg4Nzg1NH0.evp4jgR96thMJAsbhys0Qi355f2xSJNIjOlA-BcOYug","token_type":"bearer"}

（HTTP 200。）同一动态码不可复用（服务端记录最近一次使用的码，重复提交返回 401），且要求服务器时钟准确——TOTP 基于时间片，时钟漂移会导致校验失败，部署时确保 NTP 同步。

5.4 URL 路径前缀（PATH_PREFIX）

FLATNOTES_PATH_PREFIX 用于把整个应用挂在反向代理的子路径下，如 /notes。取值约束：必须以 / 开头、不能以 / 结尾，否则拒绝启动（启动期校验）。设置后服务会把前端资源引用与接口统一改写到该前缀下（启动日志可见 Replacing href value for base element in 'client/dist/index.html' with '/<前缀>/'.），反向代理只需整段透传。默认空值即根路径部署，最简单。

5.5 首页快捷访问区块（QUICK_ACCESS_* 五项）

首页顶部的快捷检索区块由 5 个参数控制：QUICK_ACCESS_HIDE（整体隐藏）、QUICK_ACCESS_TITLE（区块标题）、QUICK_ACCESS_TERM（检索词，默认 * 即全部笔记）、QUICK_ACCESS_SORT（排序，默认 lastModified）、QUICK_ACCESS_LIMIT（条数，默认 4）。区块本身等价于一次搜索接口调用，因此 TERM 可以写任意搜索词——例如固定为 #运维 时，首页就变成「运维类笔记速查」，这是把 flatnotes 用作内网速查站的实用技巧。排序与检索词的语法细节见《flatnotes v5.5.5 常用工具与 API 详解》搜索一节。

5.6 运行身份与监听（PUID / PGID / HOST / PORT / PATH）

部署层参数由镜像入口脚本消费：以 root 启动后按 PUID:PGID 修正数据目录属主，再降权运行应用进程（启动日志实测：Setting file permissions... → Starting flatnotes as user 1000...）。数据目录 .md 文件属主实测为 1000:1000。当宿主已有固定 UID 规范（如与 NFS 共享目录属主对齐）时，把 PUID/PGID 改成对应用户即可，避免权限错乱。FLATNOTES_PORT 改动时记得同步调整端口映射（映射左值不变、右值跟随），FLATNOTES_PATH 一般保持 /data 不动——它只在镜像内作为固定约定使用。

六、生产配置模板

适用场景：1–2 人个人知识库/内网速查站，2 GB 内存、20 GB 级普通磁盘，前置反向代理终结 TLS，密码认证 + 较短会话期。

docker-compose.yml 的 environment: 段推荐取值：

    environment:
      FLATNOTES_AUTH_TYPE: "password"
      FLATNOTES_USERNAME: "admin"
      FLATNOTES_PASSWORD: "q1w2e3r4"                 # 演示值，生产换成强口令
      FLATNOTES_SECRET_KEY: "wUoAsBILnl2IexXkizV1p6JvT99qvHe"  # openssl rand 生成
      FLATNOTES_SESSION_EXPIRY_DAYS: "7"             # 内网可放宽到 30
      FLATNOTES_QUICK_ACCESS_TITLE: "RECENTLY MODIFIED"
      FLATNOTES_QUICK_ACCESS_LIMIT: "4"
    volumes:
      - /opt/flatnotes/data:/data
    ports:
      - "8143:8080"

配套建议：资源方面 flatnotes 空载实测内存约 48 MiB，无需为它单独规划内存上限；PUID/PGID 保持默认 1000，除非要与宿主既有目录属主对齐；需要更高安全等级时把 AUTH_TYPE 切到 totp 并按 5.3 节完成验证器绑定。改完执行 docker compose up -d --force-recreate 生效，并用 /api/config 与 /health 复核。

七、常见问题（FAQ）

Q1：启动直接退出，日志 Invalid value 'bogus' for FLATNOTES_AUTH_TYPE？

枚举类参数启动期校验，取值必须为 none, read_only, password, totp（大小写不敏感）。同理 FLATNOTES_QUICK_ACCESS_SORT 只接受 score, title, lastModified，FLATNOTES_PATH_PREFIX 必须以 / 开头且不以 / 结尾。改正后重建即可。

Q2：password 与 totp 模式下 USERNAME/PASSWORD/SECRET_KEY 忘配会怎样？

这三个变量在该两种模式下为必填，缺失时服务拒绝启动（源码按 mandatory 读取）。none/read_only 模式则完全不需要它们。

Q3：TOTP 登录一直失败？

按序排查：确认 FLATNOTES_TOTP_KEY 与启动日志打印的密钥对应（换过值要重新扫码）；确认拼接顺序是「密码在前、动态码在后」；确认验证器与服务器时钟都在准确时间上（NTP）；确认该动态码没有在 30 秒内用过（复用被拒）。

Q4：改了参数但看起来没生效？

环境变量在服务启动时读取，运行中不热加载。确认用 docker compose up -d --force-recreate 重建而非仅 restart（restart 不会重新读取修改后的 compose 文件环境段），再用 /api/config 复核 UI 相关字段。

Q5：v5.5.5 有 HTTPS/TLS 相关配置吗？

没有。官方镜像与源码均不提供 TLS 配置项，TLS 一律由前置反向代理终结。

八、参考链接

• 官方 Wiki《Environment Variables》（参数官方口径）：https://github.com/dullage/flatnotes/wiki/Environment-Variables
• 官方仓库源码（server/global_config.py 等）：https://github.com/dullage/flatnotes
• Releases：https://github.com/dullage/flatnotes/releases

本系列其他篇章：

• 《flatnotes 介绍与选型指南》
• 《flatnotes v5.5.5 Docker Compose 部署指南》
• 《flatnotes v5.5.5 常用工具与 API 详解》