Linux怎么安装和配置BookStack Linux开源文档笔记平台详解

最稳方案是用 Docker 部署 BookStack，需正确配置 APP_URL（实际访问地址，不可带斜杠）、DB_HOST（容器服务名 db，非 localhost）、PUID/PGID（宿主机用户 ID）；MySQL 8.0 需设 MYSQL_DEFAULT_AUTHENTICATION_PLUGIN=mysql_native_password；中文 PDF/截图乱码须挂载中文字体并设 TZ=Asia/Shanghai；APP_URL 修改后需同步数据库 settings 表或重置 mysql-data。 直接用 Docker 部署最稳，手动编译 PHP + Nginx + MySQL 容易卡在 权限、 配置错、 字符集不兼容等细节上，尤其在 Rocky / CentOS 9+ 或 Ubuntu 22.04+ 上，PHP 8.1+ 和默认 MySQL 8.0 的 认证插件会导致连接失败。 docker-compose 启动 BookStack 必须改的三个 environment 值 官方 镜像虽省事，但默认 会直接导致登录后跳转 404、图片加载失败、API 请求跨域被拒——这不是 Bug，是 Laravel 对请求来源的强制校验。 必须设为你的实际访问地址，比如反向代理后是 ，就填这个，不能带尾部斜杠 在 compose 中是服务名 ，不是 或 （容器内 localhost 指自己） / 建议设成宿主机当前用户 ID（运行 和 查），否则 目录可能因权限不足无法写入附件或日志 MySQL 8.0 容器启动失败或 BookStack 连不上数据库 LinuxServer 的 BookStack 镜像默认适配 ，若你换用 或 ，大概率报错： 或直接拒绝连接。 根本原因是 MySQL 8.0 默认启用 ，而 BookStack 所用的 PDO MySQL 驱动（PHP 8.0+）未显式指定认证插件 解决方法：在 服务 environment 中加一行 或者退回到已验证兼容的 （推荐，避免额外调试） 别碰 这类参数——镜像内部已设好，乱加反而触发初始化失败 中文导出 PDF 乱码、截图无汉字、验证码不显示 这三类问题同源：容器内缺中文字体 + Puppeteer 渲染环境未初始化。LinuxServer 的 BookStack 镜像不自带中文字体， 和 都依赖系统级字体文件。 Docker Desktop（linux） 当前 Docker 最新稳定版本之一，主要针对稳定性和兼容性进行了修复优化，适合生产环境与日常开发使用。该版本继续强化 AI 开发支持、容器日志管理以及 Docker Engine 的安全能力，对 Windows/macOS/Linux 平台兼容性进行了进一步优化。 下载 临时验证：进容器执行 ，若无输出，说明没中文字体 修复方式：挂载宿主机中文字体目录，比如 Ubuntu 上有 ，就在 服务下加 volume： 同时补一条环境变量： （避免时间相关功能异常） 如果仍乱码，检查是否漏了 包——Ubuntu 用 ，Rocky/CentOS 用 APP_URL 改了但登录后还是跳回 localhost BookStack 会把 写进数据库表 的 字段，首次启动后该值就固化了。哪怕你改了 docker-compose.yml 并 ，也不会自动同步。 必须手动进 MySQL 容器执行： 或者更彻底：删掉 目录（注意备份），让 BookStack 重新初始化数据库 顺手清空浏览器缓存或换隐身窗口测试，因为 Laravel 会缓存配置，前端也可能 302 跳转到旧地址 真正麻烦的从来不是拉起容器，而是 APP_URL、数据库认证插件、字体路径这三处隐性耦合点——它们不出错时一切丝滑，一出错就全链路静默失败，日志里还只报“500”或空白页面。