Standard Notes 3.3.2 配置参数详解

Standard Notes 3.3.2 全部 162 个实测环境变量按组详解：必配四密钥、DB/缓存/会话令牌/限流/同步阈值/S3 与 SNS/SQS 及功能开关

Standard NotesStandard Notes2026/11/02

Standard Notes 3.3.2 配置参数详解

目标：把 Standard Notes 3.3.2 版线自托管 server 的全部配置面讲透——配置注入方式、162 个实测环境变量名按功能分组逐项解释、4 个必配密钥的用途与实测后果、限流/滥用阈值的默认行为、以及"最小必需 16 个 vs 全表面 162 个"的差距怎么补。

变量名清单来自 2026-11-02 对运行中 server 容器的 docker inspect 全量提取（env_surface_full.txt，162 项），语义解释交叉核对官方 env.sample 注释、官方帮助文档与 API 实测行为。部署上下文见本专栏《Standard Notes Docker Compose 部署指南》一篇，行为验证见《Standard Notes 3.3.2 API 使用详解》一篇。

1. 配置面总览

Standard Notes 服务端没有任何配置文件，全部配置 = 环境变量（12-factor 风格），compose 里通过 env_file: .env 一次性注入 server 容器；容器内 supervisord 拉起的 9 个 node 进程共享同一份环境。官方 env.sample 只列出最小必需集，其余变量都有镜像内默认值。

实测分组统计（162 个变量名）：

分组数量级代表
DB11DB_HOST DB_TYPE DB_REPLICA_HOST
CACHE3CACHE_TYPE REDIS_HOST REDIS_URL
密钥 KEYS6AUTH_JWT_SECRET VALET_TOKEN_SECRET
会话与令牌12ACCESS_TOKEN_AGE REFRESH_TOKEN_AGE
登录安全/限流8MAX_LOGIN_ATTEMPTS STRICT_ABUSE_PROTECTION
同步与滥用阈值10MAX_ITEMS_LIMIT ITEM_OPERATIONS_ABUSE_THRESHOLD
版本历史4REVISIONS_FREQUENCY
Files/S39FILE_UPLOAD_PATH S3_BUCKET_NAME
SNS/SQS10SNS_TOPIC_ARN SQS_ENDPOINT
HTTP/gRPC/超时12HTTP_CALL_TIMEOUT GRPC_MAX_MESSAGE_SIZE
Cookie/CORS6COOKIE_SECURE CORS_ALLOWED_ORIGINS
U2F5U2F_EXPECTED_ORIGIN
WebSocket4WEB_SOCKET_SERVER_URL
功能开关6DISABLE_USER_REGISTRATION READONLY_USERS
其他服务 URL7PAYMENTS_SERVER_URL EMAIL_SERVER_URL
事件名常量≈50USER_REGISTERED SUBSCRIPTION_RENEWED（不是可调参数，见第 12 节）

2. 必配四密钥（漏一个都起不来/不安全）

变量用途实测后果
AUTH_JWT_SECRETAPI 网关签发/校验 JWT 的签名密钥必配；改值等于全员掉线（旧 token 全部验不过）
AUTH_SERVER_ENCRYPTION_SERVER_KEYauth 服务对库内敏感字段（如 PKCE challenge、私有标识）做静态加密的密钥必配；改值导致已存的会话/挑战数据不可解
AUTH_SERVER_ADMIN_KEY保护 /admin、/internal 管理接口官方 env.sample 注释：不设置则这两个前缀无保护；公网务必设置
VALET_TOKEN_SECRETfiles 服务签发票据（valet token）的密钥必配；实测无 token 访问 GET :3125/v1/files 返回 {"error":{"tag":"invalid-auth","message":"Invalid valet token."}}

生成方式统一 openssl rand -hex 32。另有 VALET_TOKEN_TTL（票据有效期）和 PSEUDO_KEY_PARAMS_KEY（给旧客户端伪造 key_params 的签名密钥）两个衍生项。

3. DB 组

变量默认/示例说明
DB_HOST / DB_PORTdb / 3306主库地址
DB_USERNAME / DB_PASSWORDstd_notes_user / —业务账号
DB_DATABASEstandard_notes_db库名
DB_TYPEmysql驱动类型；镜像同时支持 postgres 与 sqlite（测试用）
DB_REPLICA_HOST—只读副本地址（读写分离），自托管一般留空
DB_MIGRATIONS_PATH镜像内路径knex 迁移文件位置，升级异常时才需要动
DB_DEBUG_LEVEL—SQL 调试级别，生产别开
DB_MAX_QUERY_EXECUTION_TIME—单查询超时（毫秒），防慢查询拖垮同步
DB_SQLITE_DATABASE_PATH—DB_TYPE=sqlite 时的库文件路径（E2E 测试场景）

实测落库：首次启动自动迁移出 37 张表，users.version 字段直接存注册时提交的协议版本号（004）。

4. CACHE 组

变量默认说明
CACHE_TYPEredis缓存驱动；自托管固定用 redis
REDIS_HOST / REDIS_PORTcache / 6379连接地址
REDIS_URL—完整 URL 形式的替代写法（含密码场景）

Redis 在自托管栈里身兼三职：缓存、微服务间通信队列（官方帮助明确 self-hosted 模式下 Redis 承担服务与 worker 间队列）、登录限流计数（lock:<userUuid>，实测 API 连错密码后该键出现）。

5. 会话与令牌组（004 协议核心）

这组变量决定登录态形态，与 API 实测强关联：

变量说明实测关联
AUTH_JWT_TTL旧版 JWT token 有效期version=3.3.2 注册回退 JWT 时生效
ACCESS_TOKEN_AGEsession access token 寿命注册响应 access_expiration 时间戳由此算出
REFRESH_TOKEN_AGErefresh token 寿命同上 refresh_expiration
EPHEMERAL_SESSION_AGE临时会话寿命未登录场景的短会话
APPLICATION_VERSION_THRESHOLD_FOR_TOKEN_VERSION_2启用 2 型 token 的客户端版本阈值决定 token 形如 1:<uuid>:<token> 还是 2:<privateIdentifier>
APPLICATION_VERSION_THRESHOLD_FOR_TOKEN_VERSION_3启用 3 型 token 的阈值同上
CROSS_SERVICE_TOKEN_CACHE_TTL微服务间校验 token 的缓存时长影响网关→auth 的 RPC 频率
COOLDOWN_SESSION_TOKENS_TTL会话吊销后的冷却保留期登出后旧 token 立即 401 的实现基础
SESSION_TRACE_DAYS_TTL会话审计痕迹保留天数session_traces 表
USER_DISABLED_SESSION_USER_AGENT_LOGGING关闭 UA 记录（隐私开关）GET /v1/sessions 的 device_info 字段来源

关键行为：账号协议版本 >= 004 才启用 session 体系（源码 User.supportsSessions() 即 parseInt(version) >= parseInt("004")），api=20240226 走 cookie-based 会话、api=20200115 走 header-based。

6. 登录安全与限流组

变量说明
MAX_LOGIN_ATTEMPTS触发锁定前的失败登录次数上限
FAILED_LOGIN_LOCKOUT失败锁定开关/时长
MAX_CAPTCHA_LOGIN_ATTEMPTS触发验证码的失败次数阈值
FAILED_LOGIN_CAPTCHA_LOCKOUT验证码失败锁定
CAPTCHA_SERVER_URL / CAPTCHA_UI_URL验证码服务地址（官方云组件，自托管一般不配）
STRICT_ABUSE_PROTECTION全局严格滥用防护总开关
AUTH_SERVER_GRPC_URL / AUTH_SERVER_URL网关访问 auth 服务的 gRPC/HTTP 地址（多机拆分部署时改）

实测：超限后 auth 在 Redis 记 lock:<userUuid>，后续登录请求被拒；清计数即恢复（redis-cli del lock:... 实测返回 1）。

7. 同步与滥用阈值组

变量说明实测值
MAX_ITEMS_LIMIT单次同步请求条目上限客户端默认按 150 拉取，实测 limit=150 正常
MAX_CHUNK_BYTES单条目密文大小上限超限条目进 unsaved
CONTENT_SIZE_TRANSFER_LIMIT传输内容大小限制—
FREE_USER_CONTENT_LIMIT_BYTES免费用户内容总量自托管无订阅时按此口径计量
ITEM_OPERATIONS_ABUSE_THRESHOLD / ..._TIMEFRAME_LENGTH_IN_MINUTES条目操作频率阈值+窗口防脚本刷同步
FREE_USERS_ITEM_OPERATIONS_ABUSE_THRESHOLD免费档同上—
UPLOAD_BANDWIDTH_ABUSE_THRESHOLD / ..._TIMEFRAME_LENGTH_IN_MINUTES上传带宽阈值+窗口files 服务用
FREE_USERS_UPLOAD_BANDWIDTH_ABUSE_THRESHOLD免费档同上—
DUPLICATE_ITEM_SYNCED重复条目事件名（见第 12 节）—

8. 版本历史（revisions）组

变量说明
REVISIONS_SERVER_URLrevisions 微服务地址
REVISIONS_FREQUENCY付费档版本生成频率
FREE_REVISIONS_FREQUENCY免费档版本生成频率
REVISIONS_COPY_REQUESTED版本拷贝事件名

实测：更新同 uuid 密文后 GET /v2/items/:uuid/revisions 可列出历史版本并取回旧密文；revisions_revisions 表与 items 表行数同步增长（实测各 6 行）。

9. Files 与 S3 组

变量说明实测
FILES_SERVER_URL网关/客户端访问 files 的 URL注册响应 meta.server.filesServerUrl 原样回显 http://localhost:3125
FILE_UPLOAD_PATH本地存储模式的落盘目录对应容器 /opt/server/packages/files/dist/uploads，compose 已外挂
S3_ENDPOINTS3 兼容对象存储端点（MinIO/Garage 等）官方 local 方案不配则走本地磁盘
S3_BUCKET_NAME / S3_BACKUP_BUCKET_NAME附件桶 / 用户备份桶—
S3_AUTH_SCRIPTS_DATA_BUCKET / S3_PROFILER_BUCKET_NAME脚本数据桶 / profiler 桶一般不用
S3_AWS_REGION桶区域—
EMAIL_ATTACHMENT_MAX_BYTE_SIZE邮件备份附件上限与 EMAIL_BACKUP_REQUESTED 事件联动

10. SNS/SQS 组（localstack 对接）

变量说明
SNS_ENDPOINT / SQS_ENDPOINTlocalstack 地址（http://localstack:4566）
SNS_TOPIC_ARN主事件 topic ARN
SQS_QUEUE_URL主队列 URL
SNS_ACCESS_KEY_ID / SNS_SECRET_ACCESS_KEY / SNS_AWS_REGIONSNS 凭据与区域（localstack 用 dummy 值）
SQS_ACCESS_KEY_ID / SQS_SECRET_ACCESS_KEY / SQS_AWS_REGIONSQS 同上
API_GATEWAY_AWS_REGION网关区域占位

这组变量与 B2 第 7 节的 bootstrap 脚本配套：bootstrap 建的 7 topic/3 queue 的 ARN 命名规则（arn:aws:sns:us-east-1:000000000000:<name>）就是这里的取值口径。

11. 网络、HTTP/gRPC、Cookie/CORS 组

变量说明
GRPC_PORT / GRPC_MAX_MESSAGE_SIZE内部 gRPC 端口（实测 50051/50052 在听）与消息上限
GRPC_KEEP_ALIVE_TIME / GRPC_KEEP_ALIVE_TIMEOUT / GRPC_AGENT_KEEP_ALIVE_TIMEOUTgRPC 保活三件套
SYNCING_SERVER_GRPC_URL / SYNCING_SERVER_JS_URL网关→syncing 的两种寻址
HTTP_CALL_TIMEOUT / HTTP_KEEP_ALIVE_TIMEOUT / HTTP_AGENT_KEEP_ALIVE_TIMEOUT服务间 HTTP 超时与保活
HTTP_REQUEST_PAYLOAD_LIMIT_MEGABYTES网关请求体上限（大附件同步相关）
SERVICE_PROXY_TYPE反向代理类型（nginx/traefik 等，影响取真实 IP）
COOKIE_DOMAIN / COOKIE_SECURE / COOKIE_SAME_SITE / COOKIE_PARTITIONEDapi=20240226 cookie-based 会话的 cookie 属性；HTTPS 部署必改 COOKIE_SECURE=true
CORS_ALLOWED_ORIGINS / CORS_ORIGIN_STRICT_MODE_ENABLED跨域白名单与严格模式；前端域名与 API 域名不同源时必须配
WEBSOCKETS_API_URL / WEB_SOCKET_SERVER_URL / WEB_SOCKET_CONNECTION_TOKEN_SECRET / WEB_SOCKET_CONNECTION_TOKEN_TTL实时同步 WebSocket 面（前端 window.websocketUrl 的服务端对应物）
U2F_RELYING_PARTY_ID / U2F_RELYING_PARTY_NAME / U2F_EXPECTED_ORIGIN / U2F_REQUIRE_USER_VERIFICATION / U2F_CHALLENGE_MAX_AGE_SECONDS安全密钥（硬件 2FA）五件套；env.sample 中以 AUTH_SERVER_U2F_ 前缀给出

12. 功能开关与"事件名常量"辨析

可调开关：

变量说明
DISABLE_USER_REGISTRATION关闭注册入口（私有部署防陌生人注册，自托管强烈建议评估）
READONLY_USERS指定只读账号 uuid 列表
LOG_LEVEL日志级别
VERSION服务版本回显值
E2E_TESTING测试模式（放宽部分校验，生产禁开）
PROFILER_ENABLED性能采样开关
MIXPANEL_TOKEN官方遥测（自托管留空即无遥测）

辨析：清单里还有约 50 个形如 USER_REGISTERED、SESSION_CREATED、ITEM_DELETED、FILE_UPLOADED、SUBSCRIPTION_RENEWED、ACCOUNT_DELETION_REQUESTED、SHARED_VAULT_*、EMAIL_BACKUP_REQUESTED 的名字，它们是 SNS 事件类型常量（worker 间消息路由的事件名），不是给你调优的参数——出现在容器环境里是因为镜像把它们作为默认值注入。读配置面时直接跳过这一类即可，别试图"改值"。

13. 最小集 vs 全表面：怎么选

官方 env.sample 必需项只有 16 个（DB 6 + CACHE 3 + KEYS 4 + 少量），实测这套最小集即可跑通注册/登录/同步/版本/改密/登出全链路。其余 146 个走默认值。需要主动配置的典型场景：

  1. HTTPS 公网部署：COOKIE_SECURE=true、COOKIE_SAME_SITE、CORS_ALLOWED_ORIGINS、SERVICE_PROXY_TYPE=nginx；
  2. 私有化防滥用：DISABLE_USER_REGISTRATION=true、收紧 ITEM_OPERATIONS_ABUSE_THRESHOLD、AUTH_SERVER_ADMIN_KEY 必设；
  3. 大附件：HTTP_REQUEST_PAYLOAD_LIMIT_MEGABYTES、MAX_CHUNK_BYTES、UPLOAD_BANDWIDTH_ABUSE_THRESHOLD、配 S3_* 换对象存储；
  4. 多机拆分：*_SERVER_URL/*_GRPC_URL 系列指向各微服务独立实例（官方不支持，需自行拆 compose）。

14. 专栏导航

15. 跨栏相关阅读

16. 参考来源

  • github.com/standardnotes/server 仓库 env.sample（必需项与注释口径）
  • standardnotes.com/help/self-hosting（Redis 队列角色、微服务职责）
  • 本平台实测：运行容器 docker inspect 环境变量全量提取（162 项）、files 服务 401 探测、Redis lock:* 限流验证、会话/令牌字段回显核对（2026-11-02）