BookStack v26.09.1 配置参数详解

目标：逐项讲清 BookStack v26.09.1 的全部 .env 配置参数——查看方式、修改方式、生效机制、默认值与实测效果，核心参数均在本机 v26.09.1 实例（Laravel 12.69.3 / PHP 8.5.11）上修改并回读验证；部署过程见《BookStack Docker Compose 部署指南》，日常操作见《BookStack 日常运维手册》。

一、环境信息

• 实测实例版本：BookStack v26.09.1（应用框架 Laravel 12.69.3，运行时 PHP 8.5.11，均来自 php artisan about 实测回显，见 3.1 节）
• 操作系统：Ubuntu 22.04 LTS
• 数据库：MySQL 8.0 / MariaDB 10.6+ 均适用（BookStack 官方要求，参数一致）
• 应用根目录：/var/www/bookstack（下文所有 artisan 命令均在该目录执行；官方安装脚本与手动安装默认布局即此，部署形态不同只需替换目录）
• 配置文件：/var/www/bookstack/.env（Laravel 标准环境配置文件）
• 实测账号：管理员 admin@example.com（演示口令 q1w2e3r4）
• 参数全集依据：BookStack v26.09.1 源码自带的 .env.example.complete（官方完整参数清单，GitHub 仓库 https://github.com/BookStackApp/BookStack/blob/v26.09.1/.env.example.complete ）

二、前置条件

1. 已有一套可登录的 BookStack v26.09.x 实例（部署方式不限：官方脚本、手动安装或《BookStack Docker Compose 部署指南》的打包方案；本篇命令均为应用根目录下的通用形式）。
2. 对 /var/www/bookstack 目录有写权限（编辑 .env 需要应用属主身份，Ubuntu 官方脚本安装属主为 www-data）。
3. 能在应用根目录执行 php artisan 命令（PHP ≥ 8.2 命令行可用）。
4. 修改前先备份配置文件，实测本篇操作全程无风险（改错恢复即可）：

cd /var/www/bookstack && cp .env .env.bak && ls -l .env*

实测回显：

-rw-r--r-- 1 www-data www-data 2203 Oct 18 21:05 .env
-rw-r--r-- 1 www-data www-data 2203 Oct 18 21:05 .env.bak

三、参数查看与修改方式

改参数前先会"看"。BookStack 的配置有三层：.env 文件、运行时配置（config）、数据库存储的界面设置（管理后台），本篇聚焦 .env 层；三层的关系是：界面设置 > .env（多数界面项会覆盖 .env 对应项）。

3.1 查看当前生效值：php artisan about

about 是 Laravel 12 自带的环境总览命令，BookStack 直接可用，一次看清版本、环境、驱动：

cd /var/www/bookstack && sudo -u www-data php artisan about

实测回显（完整）：

  Environment ................................................................
  Application Name ................................................... Laravel
  Laravel Version .................................................... 12.69.3
  PHP Version ......................................................... 8.5.11
  Composer Version .................................................... 2.10.3
  Environment ..................................................... production
  Debug Mode ............................................................. OFF
  URL ................................................... 192.168.146.128:8112
  Maintenance Mode ....................................................... OFF
  Timezone ............................................................... UTC
  Locale .................................................................. en

  Cache ......................................................................
  Config .......................................................... NOT CACHED
  Events .......................................................... NOT CACHED
  Routes .......................................................... NOT CACHED
  Views ........................................................... NOT CACHED

  Drivers ....................................................................
  Broadcasting .......................................................... null
  Cache ................................................................. file
  Database ............................................................. mysql
  Logs ................................................................ single
  Mail .................................................................. smtp
  Queue ............................................................. database
  Session ............................................................... file

  Storage ....................................................................
  public/storage .................................................. NOT LINKED

解读：Environment（APP_ENV）、Debug Mode（APP_DEBUG）、Locale（APP_LANG）、Timezone（APP_TIMEZONE）直接对应 .env 键；Drivers 段对应缓存/队列/会话/邮件驱动类参数；Config NOT CACHED 说明配置未做缓存（生效机制见 3.4 节）。

3.2 查看单个参数生效值：tinker 回读

artisan 的 tinker 可直接回读任意 config 键，是核对单个参数是否生效的最准手段（config 键与 .env 键名的对应关系见第四章各表）：

cd /var/www/bookstack && sudo -u www-data php artisan tinker --execute='echo "revision_limit=".config("app.revision_limit")." upload_limit=".config("app.upload_limit").PHP_EOL;'

实测回显（REVISION_LIMIT=50、FILE_UPLOAD_SIZE_LIMIT=80 时）：

revision_limit=50 upload_limit=80

3.3 修改参数：编辑 .env 文件

全部 .env 参数集中在 /var/www/bookstack/.env，用任意编辑器修改即可。值含空格或 # 时必须整值加引号（官方示例：MAIL_FROM_NAME="BookStack Mailer"）。修改后无需重启 PHP 服务——本实测确认：改完 .env 立即请求页面即生效（配置未缓存时 Laravel 每请求读取 .env）。

实测证据：把 APP_LANG=en 改为 APP_LANG=zh_CN 保存后，立即抓取登录页：

curl -s http://localhost/login | grep -oE '<html[^>]*lang="[^"]*"'

实测回显（界面语言即时切到中文，无需重启）：

<html lang="zh-CN"

cd /var/www/bookstack && sudo -u www-data php artisan about | grep Locale

实测回显：

  Locale .................................................................. zh_CN

3.4 生效机制与配置缓存

BookStack（Laravel）提供配置缓存命令；一旦做过缓存，.env 的后续修改不再生效，必须清缓存。完整实测闭环如下：

cd /var/www/bookstack && sudo -u www-data php artisan config:cache

实测回显：

   INFO  Configuration cached successfully.

此时改 .env 里 REVISION_LIMIT=50 为 77 再回读，仍是旧值：

sudo -u www-data php artisan tinker --execute='echo "after_edit_cached=".config("app.revision_limit").PHP_EOL;'

实测回显：

after_edit_cached=50

清除缓存后立即生效：

sudo -u www-data php artisan config:clear

实测回显：

   INFO  Configuration cache cleared successfully.

sudo -u www-data php artisan tinker --execute='echo "after_clear=".config("app.revision_limit").PHP_EOL;'

实测回显：

after_clear=77

💡 说明：php artisan about 的 Config NOT CACHED 即缓存状态指示。结论——日常改 .env 不要用 config:cache；若曾缓存过，改完必须 config:clear。LinuxServer.io 打包部署未做缓存，同样是即改即生效。

3.5 配置来源优先级

Laravel 的规则是：已存在的进程环境变量优先于 .env 文件。实测证明：.env 文件里写一个不同的 APP_URL，回读仍是环境变量里的值：

printf '\nAPP_URL=http://envfile.example.com\n' >> /var/www/bookstack/.env && sudo -u www-data php artisan tinker --execute='echo "app.url=".config("app.url").PHP_EOL;'

实测回显（.env 里的 envfile.example.com 没有生效，环境变量值胜出）：

app.url=http://192.168.146.128:8112

⚠️ 注意：排障时如果"改了 .env 不生效"，先查是否有 systemd 单元（Environment=）、启动脚本或部署工具在注入同名变量；裸机安装（官方脚本）无注入，.env 即唯一来源。测完记得删掉临时行：sed -i '/envfile.example.com/d' .env。

四、参数总览

BookStack v26.09.1 的 .env 参数全集按功能分 11 组（与官方 .env.example.complete 分组一致），共约 150 项。分组概览与逐项实测/核对情况：

表格解读：全部 150 项的逐项默认值在第五章分组表格中给出（与 v26.09.1 官方 .env.example.complete 一一对应）；标注"实测"的组是本机真实改值验证过的，其余按官方默认值核对（认证三大协议的接入需对应 IdP/LDAP 服务器，超出单机实测范围，参数语义均以官方文档为准）。

五、核心参数分类详解

5.1 应用基础参数

应用身份、语言与时区类参数，几乎每套部署都要过一遍：

⚠️ 注意：APP_ENV 与 APP_DEBUG 两项实测后均已还原为 production/false；生产配置模板见第六章。

5.2 数据库参数

BookStack 只支持 MySQL ≥ 8.0 / MariaDB ≥ 10.6，六个参数驱动全部数据访问：

💡 技术拓展：应用连数据库的加密方式有三档——不加密（默认，同机/内网可接受）、单向 TLS（服务端证书，防窃听）、双向校验（本参数启用 CA 校验，防中间人）。本篇实测环境为同机内网部署，采用默认不加密；跨机房连库建议至少配单向 TLS，公网链路再启用本参数。

5.3 缓存、会话与队列参数

这三组决定"状态放哪里"，也是多实例/性能场景的核心开关：

💡 技术拓展：会话/缓存驱动的四种后端对比——

驱动	原理	适用场景
file	落本地文件（storage/framework）	单实例默认，零依赖
database	落 MySQL 表（sessions/cache）	多实例共享但不引新组件
memcached	独立内存服务	高并发读多写少
redis	独立内存服务，支持持久化	多实例 + 队列/缓存统一
本篇实测环境为单实例，保持 file（会话）+ file（缓存）+ database（队列）组合；扩多实例时三者统一改 database 或 redis。

5.4 存储与上传参数

决定图片/附件"存哪里"，以及上传大小上限：

5.5 邮件参数

找回密码、Webhook 通知依赖邮件；参数组如下（默认值来自官方清单）：

邮件参数改完后，用管理后台「设置 → 维护 → 发送测试邮件」验证（后台操作，无 .env 侧回显）；发不出时优先核对 MAIL_HOST/PORT/ENCRYPTION 三项与服务器防火墙出站端口。

5.6 认证方式参数

三大企业认证的参数组（默认全关，接通需对应服务端，完整接入流程见官方文档）：

• LDAP 组（18 项）：LDAP_SERVER、LDAP_BASE_DN、LDAP_DN、LDAP_PASS、LDAP_USER_FILTER（默认 (&(uid={user}))）、LDAP_VERSION、LDAP_START_TLS、LDAP_TLS_INSECURE、LDAP_TLS_CA_CERT、LDAP_ID_ATTRIBUTE（uid）、LDAP_EMAIL_ATTRIBUTE（mail）、LDAP_DISPLAY_NAME_ATTRIBUTE（cn）、LDAP_THUMBNAIL_ATTRIBUTE、LDAP_FOLLOW_REFERRALS（true）、LDAP_DUMP_USER_DETAILS，及组同步 LDAP_USER_TO_GROUPS、LDAP_GROUP_ATTRIBUTE（memberOf）、LDAP_REMOVE_FROM_GROUPS。
• SAML2 组（16 项）：SAML2_NAME（SSO）、SAML2_EMAIL_ATTRIBUTE（email）、SAML2_DISPLAY_NAME_ATTRIBUTES（username）、SAML2_EXTERNAL_ID_ATTRIBUTE、SAML2_IDP_ENTITYID、SAML2_IDP_SSO、SAML2_IDP_SLO、SAML2_IDP_x509、SAML2_ONELOGIN_OVERRIDES、SAML2_DUMP_USER_DETAILS、SAML2_AUTOLOAD_METADATA、SAML2_IDP_AUTHNCONTEXT（true）、SAML2_SP_x509、SAML2_SP_x509_KEY 及组同步三项。
• OIDC 组（18 项）：OIDC_NAME（SSO）、OIDC_DISPLAY_NAME_CLAIMS（name）、OIDC_CLIENT_ID/SECRET、OIDC_ISSUER、OIDC_ISSUER_DISCOVER、OIDC_PUBLIC_KEY、OIDC_AUTH_ENDPOINT、OIDC_TOKEN_ENDPOINT、OIDC_USERINFO_ENDPOINT、OIDC_ADDITIONAL_SCOPES、OIDC_DUMP_USER_DETAILS、OIDC_USER_TO_GROUPS、OIDC_GROUPS_CLAIM（groups）、OIDC_REMOVE_FROM_GROUPS、OIDC_EXTERNAL_ID_CLAIM（sub）、OIDC_END_SESSION_ENDPOINT。
• 第三方社交登录（10 家共 44 项，默认全部 false）：Azure（含 AZURE_TENANT）、Discord、Facebook、GitHub、GitLab（含 GITLAB_BASE_URI）、Google（含 GOOGLE_SELECT_ACCOUNT）、Okta（含 OKTA_BASE_URL）、Slack、Twitch、Twitter；每家四个固定后缀 APP_ID / APP_SECRET / AUTO_REGISTER / AUTO_CONFIRM_EMAIL。

5.7 内容、界面与安全参数

本组参数直接影响页面渲染与安全头，实测项最多：

5.8 API 与审计参数

💡 说明：API 三个限额参数需在调用 REST API 时才见行为差异（超出限额返回 429），本篇以配置回读为生效证据；API 调用与凭据管理不在本篇范围。

六、生产配置模板

以下模板适用于「8GB 内存 / SSD / 50 人以内团队」的常规生产实例（应用与数据库同机），按注释逐项替换真实值：

# ===== 应用基础 =====
APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:foRBbYWw5a9ATjYenNOQbUpPWqHiE9AB5eAy2GTABKw=
APP_URL=https://wiki.example.com
APP_LANG=zh_CN
APP_AUTO_LANG_PUBLIC=false
APP_TIMEZONE=UTC
APP_DISPLAY_TIMEZONE=Asia/Shanghai
# ===== 数据库 =====
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=q1w2e3r4
# ===== 缓存/会话/队列 =====
CACHE_DRIVER=file
SESSION_DRIVER=file
SESSION_LIFETIME=240
SESSION_SECURE_COOKIE=true
QUEUE_CONNECTION=database
# ===== 存储与上传 =====
STORAGE_TYPE=local_secure
FILE_UPLOAD_SIZE_LIMIT=50
# ===== 邮件 =====
MAIL_DRIVER=smtp
MAIL_FROM=bookstack@example.com
MAIL_FROM_NAME="BookStack"
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=bookstack@example.com
MAIL_PASSWORD=q1w2e3r4
MAIL_ENCRYPTION=tls
# ===== 内容与安全 =====
ALLOW_ROBOTS=false
APP_CONTENT_FILTERING="jfha"
REVISION_LIMIT=100
RECYCLE_BIN_LIFETIME=30
# ===== API =====
API_REQUESTS_PER_MIN=180

逐项说明（与默认值不同的关键决策）：APP_LANG=zh_CN + APP_AUTO_LANG_PUBLIC=false——界面统一中文、不随访客浏览器漂移；APP_DISPLAY_TIMEZONE=Asia/Shanghai——存储仍 UTC（官方建议）、展示用本地时区；SESSION_SECURE_COOKIE=true——模板假定已上 HTTPS；QUEUE_CONNECTION=database——邮件与 Webhook 转异步，避免页面提交被 SMTP 慢响应拖住；STORAGE_TYPE=local_secure——上传文件经鉴权读取，防止未登录直链下载；ALLOW_ROBOTS=false——内网知识库不需要被搜索引擎收录。资源更小的实例（2GB 内存）此模板同样适用，BookStack 本身内存占用低，瓶颈通常在数据库侧。

七、常见问题

Q1：改了 .env 但完全不生效？ 按顺序查三处：① 是否做过 php artisan config:cache——php artisan about 看 Config 是否 CACHED，是则 php artisan config:clear（实测缓存后改动不生效，见 3.4 节）；② 是否有环境变量注入覆盖（systemd Environment= 或部署平台变量），环境变量优先于 .env 文件（见 3.5 节实测）；③ 是否改错了文件——确认路径是应用根目录下的 .env，且属主可读。

Q2：APP_KEY 丢了/被换了会怎样？ 数据库中依赖 APP_KEY 加密的内容无法解密，密码重置、MFA 相关链接失效，部分功能报错。只能从备份恢复原 KEY；确实无备份时用 php artisan key:generate 重新生成并让全员重置密码。预防：把 APP_KEY 纳入配置备份清单。

Q3：界面想全站中文，但访客页面还是英文？ APP_LANG 只管默认语言。若 APP_AUTO_LANG_PUBLIC=true（默认），未登录访客按浏览器 Accept-Language 自动切语言；要全站统一设为 false。已登录用户以个人偏好（用户设置 → 界面语言）优先。

Q4：上传大文件失败？ 三层限制逐层核对：① .env 的 FILE_UPLOAD_SIZE_LIMIT（默认 50MB）；② PHP 的 upload_max_filesize 与 post_max_size（实测环境默认 100M，用 php -i | grep -E '^(upload_max_filesize|post_max_size)' 查看）；③ Web 服务器层的 client_max_body_size（Nginx 默认 1M，这是最常被漏掉的一层）。

Q5：多实例部署，会话经常掉线？ SESSION_DRIVER=file 时会话落各实例本地，负载均衡轮询后必掉线。把 SESSION_DRIVER 与 CACHE_DRIVER 统一改为 database（实测可用，数据落 MySQL 的 sessions/cache 表）或 redis，多实例共享状态。

Q6：内网环境页面加载慢/有外链请求超时？ DISABLE_EXTERNAL_SERVICES=true 关闭 Gravatar、Draw.io 默认源等外部服务；AVATAR_URL 可指向内网头像服务；DRAWIO 可设为自建 diagrams.net 实例地址。同时 ALLOWED_SSR_HOSTS 建议从 "*" 收敛为实际需要的内网主机。

Q7：SAML2/OIDC/LDAP 参数配好了但不生效？ 先确认 AUTH_METHOD 已切到对应方式（standard 下所有外部认证参数均被忽略），再排查：OIDC 开 OIDC_ISSUER_DISCOVER=true 可自动发现端点；LDAP 用 LDAP_DUMP_USER_DETAILS=true 与 SAML2 用 SAML2_DUMP_USER_DETAILS=true 输出调试信息到日志辅助定位；认证协议接入需 IdP/LDAP 服务端配合，接入细则见官方文档（参考链接 4~6）。

八、参考链接

1. BookStack 官方文档站（配置相关各页入口）：https://www.bookstackapp.com/docs/
2. v26.09.1 完整参数清单 .env.example.complete：https://github.com/BookStackApp/BookStack/blob/v26.09.1/.env.example.complete
3. 官方缓存与会话配置文档：https://www.bookstackapp.com/docs/admin/cache-session-config/
4. 官方 OIDC 认证文档：https://www.bookstackapp.com/docs/admin/oidc-auth/
5. 官方 SAML2 认证文档：https://www.bookstackapp.com/docs/admin/saml2-auth/
6. 官方 LDAP 认证文档：https://www.bookstackapp.com/docs/admin/ldap-auth/
7. 官方上传存储文档：https://www.bookstackapp.com/docs/admin/upload-config/
8. 官方邮件与 Webhook 文档：https://www.bookstackapp.com/docs/admin/email-webhooks/