Many Notes 0.18.1 配置参数详解

目标：把 Many Notes v0.18.1 的三级配置（环境变量 / 运行时设置 / 基座镜像参数）逐项讲清，默认值全部取自部署实例的实查回显（采集日期 2026-11-01），并给出生产配置模板。实例部署过程见《Many Notes Docker Compose 部署指南》。

一、环境信息

• 操作系统：Ubuntu 24.04（x86_64）
• 应用：Many Notes v0.18.1，镜像 brufdev/many-notes:latest（digest sha256:4a61723eca84...）
• 基座：serversideup/php v5.0.2（fpm-nginx），PHP 8.4.27，Debian 13，s6 监督
• 框架：Laravel 13.29.0，Composer 2.10.3（php artisan about 实测）
• 数据库：SQLite 3.46.1（php artisan db:show 实测），19 张表
• 访问地址：http://localhost:8144（宿主端口 8144 → 应用 8080）
• 演示账号：admin / q1w2e3r4

二、前置条件

本文所有「实查」基于一个已按官方 compose 启动并通过健康检查的实例。核对方式：

docker compose ps

many-notes-0.18.1-app  brufdev/many-notes:latest  Up (healthy)  0.0.0.0:8144->8080/tcp

参数查看的三种途径（本文实测命令）：

# 途径一：容器环境变量与默认值（基座镜像 baked 值）
docker image inspect brufdev/many-notes:latest --format '{{range .Config.Env}}{{println .}}{{end}}' | head -20

# 途径二：应用运行时生效值
docker compose exec php php artisan config:show app | head -20

# 途径三：前端 props 暴露的元数据（版本/上传限制/设置开关）
curl -s http://localhost:8144/register | grep -o '"settings":{[^}]*}'

回显（实测）：

PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
PHP_VERSION=8.4.27
PHP_MEMORY_LIMIT=256M
PHP_POST_MAX_SIZE=500M
NGINX_HTTP_PORT=8080
HEALTHCHECK_PATH=/healthcheck
...
{"settings":{"local_auth_enabled":true,"registration":true,"auto_update_check":true}}

三、配置模型总览

Many Notes 的配置分三层，互不混用：

⚠️ 注意：官方 compose 不挂载任何配置文件——没有 .env 落盘编辑的惯例，全部定制走环境变量。容器内虽存在 /var/www/html/.env（镜像内置默认），但它是构建产物，升级即被覆盖，不要直接改它。

四、应用级参数详解（Laravel 层）

4.1 应用标识与地址

4.2 数据库（DB_*）

实测默认（php artisan about 的 Drivers 段 + db:show）：

Database ............................................................ sqlite
SQLite .............................................................. 3.46.1
Database ................................... database/sqlite/database.sqlite
Tables .................................................................. 19

19 张表按职责分组：核心域（users、vaults、vault_nodes、tags、tag_vault_node、vault_node_vault_node 链接表、user_vault 协作表、notifications、settings、social_accounts）、Laravel 设施（sessions、cache、cache_locks、jobs、job_batches、failed_jobs、password_reset_tokens、migrations）。会话与队列默认走数据库而非文件——这正是 compose 里看不到 redis 的原因。

4.3 认证（OIDC_* / SETTINGS_*）

本地认证开关：SETTINGS_LOCAL_AUTH_ENABLED（默认 true；实测运行时 props local_auth_enabled:true）。设 false 必须同时配置 OIDC 提供方与 OIDC_POST_LOGOUT_REDIRECT_URI，否则无人可登录。

单提供方五件套（官方 README 示例，Pocket ID 场景）：

- OIDC_NAME=Pocket ID              # 登录按钮显示名
- OIDC_CLIENT_ID=${OIDC_CLIENT_ID}         # IdP 侧创建客户端后注入
- OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET} # 同上，勿明文入库
- OIDC_REDIRECT_URI=http://localhost:8144/oauth/oidc/callback
- OIDC_BASE_URL=https://your-pocketid-url  # IdP 发现文档根

多提供方（v0.18.0 新增，实测 config/oidc.php 源码）：OIDC_PROVIDERS 以逗号/空白分隔名字列表，每个提供方按 OIDC_<名字大写>_* 前缀配置，支持键：NAME、CLIENT_ID、CLIENT_SECRET、REDIRECT_URI、BASE_URL、SCOPES、EMAIL_CLAIMS、VERIFY_JWT（默认 true）、CLOCK_SKEW（默认 0）、PROXY、TOKEN_AUTH_METHOD、POST_LOGOUT_REDIRECT_URI。名字限字母/数字/下划线，自动小写生成驱动名 oidc_<name>。

💡 技术拓展：自托管应用的认证接入不止 OIDC 一种形态。对比——

方式	特点	Many Notes 支持
本地账号	自主可控，需管密码	✅ 默认开
OIDC（发现文档）	通用协议，一套配置通吃主流 IdP	✅ 核心路径
专用 OAuth（GitHub/GitLab/Slack）	免搭 IdP	✅ 内置专用驱动（官方 OAuth 文档）
反代头认证（Authelia 等）	应用零配置	❌ 未提供

4.4 邮件（MAIL_*）

默认 MAIL_MAILER=log——注册验证/重置密码邮件写入日志而不外发（实测 php artisan about：Mail ... log）。生产多用户实例需 SMTP 八件套：MAIL_MAILER=smtp、MAIL_HOST、MAIL_PORT、MAIL_USERNAME=${SMTP_USER}、MAIL_PASSWORD=${SMTP_PASS}、MAIL_ENCRYPTION=tls、MAIL_FROM_ADDRESS、MAIL_FROM_NAME。系统级凭据用环境变量注入，不落正文。

4.5 搜索（TYPESENSE_*）

索引结构实测（collections 接口）：单集合 vault_nodes，字段 vault_id/name/content（string）+ updated_at（int64, sort）。

4.6 广播（REVERB_*）

内置 Laravel Reverb，实测监听 0.0.0.0:6001（启动日志 INFO Starting server on 0.0.0.0:6001）。关键参数：REVERB_APP_ID/APP_KEY/APP_SECRET（镜像内置生成，实测 .env 存在）、REVERB_APP_MAX_MESSAGE_SIZE（内置 2000000）、REVERB_SERVER_PORT（默认 8080，镜像内改 6001 避让 nginx）、REVERB_SCHEME/REVERB_HOST/REVERB_PORT（客户端回连地址，由 APP_URL 推导——HTTPS 反代下若广播连不上，检查这三项是否指向了外部可达的 wss 地址）。

五、基座镜像参数详解（serversideup/php 层）

实测 docker image inspect 采集的 baked 默认值（节选，均可用环境变量覆盖）：

六、运行时设置（管理界面）

settings 表仅两项（实测模型 casts + 控制器源码），超级管理员在 Admin → Settings 修改，接口 PATCH /settings 实测：

请求: {"registration":false,"auto_update_check":true}
响应: 200 {"settings":{"registration":false,"auto_update_check":true}}

• registration：全站注册开关。UPGRADING.md 特别提示 0.11 起该开关从 compose 迁到了界面——老配置迁移时要在界面重设。
• auto_update_check：新版本自动检查提醒（实测 props metadata.latest_version 即其产物）。

七、生产配置模板

适用场景：16GB 内存 / NVMe SSD / 2-10 人团队内网笔记（HTTPS 由 Caddy/nginx 反代终结）：

name: many-notes-0.18.1-prod

services:
  php:
    image: brufdev/many-notes@sha256:4a61723eca842b644ced386b17e189d143e97096c65ac80eadca13c6cd89a739
    container_name: many-notes-0.18.1-app
    restart: unless-stopped
    environment:
      - APP_URL=https://notes.example.com
      - APP_TIMEZONE=Asia/Shanghai
      - PHP_DATE_TIMEZONE=Asia/Shanghai
      - APP_KEY=${MANYNOTES_APP_KEY}
      - PHP_POST_MAX_SIZE=1G
      - PHP_UPLOAD_MAX_FILE_SIZE=1G
      - NGINX_CLIENT_MAX_BODY_SIZE=1G
      - PHP_FPM_PM_CONTROL=dynamic
      - PHP_FPM_PM_START_SERVERS=2
      - PHP_FPM_PM_MAX_CHILDREN=20
      - OIDC_NAME=Pocket ID
      - OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
      - OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
      - OIDC_REDIRECT_URI=https://notes.example.com/oauth/oidc/callback
      - OIDC_BASE_URL=https://idp.example.com
      - MAIL_MAILER=smtp
      - MAIL_HOST=smtp.example.com
      - MAIL_PORT=465
      - MAIL_USERNAME=${SMTP_USER}
      - MAIL_PASSWORD=${SMTP_PASS}
      - MAIL_ENCRYPTION=ssl
      - MAIL_FROM_ADDRESS=notes@example.com
    volumes:
      - database:/var/www/html/database/sqlite
      - logs:/var/www/html/storage/logs
      - private:/var/www/html/storage/app/private
      - typesense:/var/www/html/typesense
    ports:
      - "127.0.0.1:8080:8080"   # 仅反代可达，不对公网暴露

volumes:
  database:
  logs:
  private:
  typesense:

模板要点：digest 锁版、127.0.0.1 绑定防直暴露、真实密钥全部 ${VAR} 注入（.env 文件权限 600）、上传三参数（PHP×2 + nginx）同步放大、时区双层设置。反代需转发 X-Forwarded-Proto（HTTPS 判定）与 WebSocket 升级头（/app/{appId}/... 广播路径转发到 6001 或经 nginx 同源转发）。

八、常见问题

8.1 改了 APP_URL 页面样式/登录跳转错乱

APP_URL 参与生成绝对资源地址。改后必须 docker compose up -d 重建（配置被 php artisan optimize 缓存，实测 about 显示 Config: CACHED）；仅重启进程不够，因为缓存文件在构建阶段生成。

8.2 上传 200M 文件报 413

三层限制取最小：PHP_UPLOAD_MAX_FILE_SIZE(500M) > NGINX_CLIENT_MAX_BODY_SIZE(100M)——先撞 nginx。同时调 NGINX_CLIENT_MAX_BODY_SIZE 与两个 PHP 参数（实测默认值见第五章）。

8.3 搜索突然全空

Typesense 卷未持久化或索引丢失，官方 FAQ 流程：确认 typesense 卷挂载 → php artisan upgrade:reimport-data-into-typesense 重建（实测回显 All data was successfully reimported into Typesense）。

8.4 界面语言

当前无中文语言包（APP_LOCALE 仅 en 资源）。汉化需求可跟踪官方仓库 issues。

8.5 换 PostgreSQL 后升级报迁移失败

外置 DB 场景 compose 需 depends_on: condition: service_healthy（官方 MySQL 示例已含健康检查），数据库未就绪时启动迁移会失败；确认 DB 服务 healthy 后 docker compose restart php 即可重跑自动迁移。

九、参考链接

• 官方 README Customization 章节：https://github.com/brufdev/many-notes#customization
• OAuth 文档：https://github.com/brufdev/many-notes/blob/main/docs/customization/oauth.md
• 官方 FAQ（调试/搜索排障）：https://github.com/brufdev/many-notes/blob/main/docs/support/faqs.md
• 基座镜像参数文档：https://serversideup.net/open-source/docker-php/docs/
• Laravel Reverb：https://laravel.com/docs/reverb
• Typesense：https://typesense.org