最稳妥省事的部署方式是docker compose，因其自动建立容器间网络、统一管理卷挂载与环境变量联动，避免手动部署php+nginx+mysql在ubuntu 22.04+/rocky 9+上常见的php-fpm权限、app_key生成失败及mysql 8.0认证插件兼容性问题。
docker compose 是当前最稳、最快、踩坑最少的安装方式，手动编译 PHP + Nginx + MySQL 在 Ubuntu 22.04+ 或 Rocky 9+ 上极易卡在 php-fpm 权限、APP_KEY 生成失败、MySQL 8.0 认证插件不兼容等环节，5 分钟内跑不通首页很常见。
为什么必须用 docker compose 而不是 docker run
LinuxServer 的 ghcr.io/linuxserver/bookstack:latest 镜像设计为与配套数据库（如 mysql:5.7）协同工作，docker run 单容器启动会缺失网络互通、卷挂载路径约定和环境变量联动——比如 DB_HOST=db 这个值只在 depends_on 定义的服务名下才有效，硬写 127.0.0.1 必然连不上。
-
docker compose自动建立默认 bridge 网络，让bookstack和db容器能通过服务名互相解析 - 卷挂载路径（如
./bookstack-data:/config）由 compose 统一管理，避免权限错乱导致附件上传失败 - 环境变量可跨服务引用，例如
DB_PASS和MYSQL_PASSWORD必须完全一致，compose 文件里写一遍就能同步生效
docker-compose.yml 必填的 4 个环境变量
漏掉任意一个，容器会反复重启，日志里只显示 Database connection failed 或 APP_KEY required，根本不会输出具体原因。
PyCharm 2026.2.0.1 Linux版
下载
PyCharm 2026.2.0.1 Linux版提供 JetBrains 官方 2026.2.0.1 版本安装包，适合需要指定 PyCharm 版本进行 Python 项目开发、运行和调试的用户。
-
APP_URL：必须是你实际访问的地址，比如http://192.168.1.100:8282或https://docs.example.com，结尾不能带斜杠；本地测试先填http://localhost:8282，但配 Nginx 反代后必须立刻改掉，否则登录跳转 404、图片加载失败 -
DB_HOST：必须是depends_on下定义的服务名（如db），不是localhost或127.0.0.1 -
PUID和PGID：建议设成宿主机当前用户 ID，执行id -u和id -g查，否则/config目录文件属主错乱，后续升级或备份时chmod失效
MySQL 8.0 连不上？优先换回 mysql:5.7
LinuxServer 的 BookStack 镜像默认适配 mysql:5.7。若强行用 mysql:8.0 或 mysql:8.4，大概率报错：SQLSTATE[HY000] [2054] Server sent charset unknown to the client 或直接拒绝连接——根源是 MySQL 8.0 默认启用 caching_sha2_password 认证插件，而 BookStack 的 PDO 驱动未显式指定插件类型。
- 最简方案：把
db服务的image改成mysql:5.7，不用额外加任何参数 - 硬要用 8.0：只能在
db的environment中加MYSQL_DEFAULT_AUTHENTICATION_PLUGIN=mysql_native_password，但仍有小概率触发字符集初始化失败 - 别碰
character_set_server=utf8mb4这类参数——镜像内部已设好，乱加反而让容器卡在启动阶段
中文 PDF 导出乱码？缺字体不是配置问题
导出 PDF 无汉字、截图空白、验证码不显示，三者同源：容器内没装中文字体，puppeteer 渲染时 fallback 到空字体。
- 临时验证：进容器执行
docker exec -it bookstack fc-list :lang=zh，无输出就确认缺字体 - 解决方法：在
bookstack服务下加volumes挂载宿主机中文字体目录，例如/usr/share/fonts:/usr/share/fonts:ro - 同时补上时区：加
TZ=Asia/Shanghai，否则定时任务或日志时间错乱
APP_URL 写错、DB_HOST 指向 localhost、PUID/PGID 没对齐宿主机用户，这三个点只要错一个，整个服务就静默失败，日志里还找不到明确提示。
