记录一次在 18k Star 项目里提交 PR 的经历

最近有位客户希望搭建一套公司内部的文档知识库，并且需要能够结合他们的需求做私有化部署。调研之后，我选择了 BookStack：一个基于 Laravel / PHP 的开源项目，在 GitHub 上有超过 18k Star。

拉取代码后，我用 在本地启动项目。从页面现象来看服务已经跑起来了，但容器日志里却出现了一个 fatal 错误：

这其实是 Git 的安全检查导致的 https://github.com/git/git/blob/v2.35.2/Documentation/RelNotes/2.35.2.txt，Git 2.35.2（及以上）开始，如果它判断某个仓库目录的“所有者/权限”存在可疑情况，会拒绝在该目录上执行 Git 操作。

而在 BookStack 的开发容器里，Git 又是项目正常运行的前置条件之一：一旦仓库被判定为“不安全”，相关的 Git 命令执行失败，容器可能会因为入口脚本或运行流程而直接退出，并且看起来像是“毫无预警”。

问题发生的场景是：我们把代码通过 volume 挂载到了容器的 目录，而容器内运行进程的用户与宿主机文件的 UID/GID 并不一致，于是触发了 Git 的 dubious ownership 保护。

下面这段是 中的配置（）：

在我的环境（Windows + WSL2）下，宿主机上的目录 UID 默认是 ，而 Dockerfile 里 PHP（Apache）进程对应的用户 UID 与之不一致，所以 Git 判定 的“所有权”不可靠，最终出现上述 fatal 错误。

其实在 macOS 下也会遇到类似问题：mac 的默认 UID 通常也是 ，而容器内 PHP 用户往往不是同一个 UID，因此同样会触发 Git 的安全检查。这种跨平台开发环境下，挂载目录 UID 不一致是很常见的现象。

解决思路也很直接：既然 本身就是项目目录（并且我们明确知道它来自可信的代码挂载），那就把它标记为 Git 的安全目录即可。

最后我选择在 Dockerfile 里修复，这样开发环境与生产环境都能一并生效：

最后我把这个改动提交了 PR，作者也很快合并了。

我想说的是：提交 PR 并不难，有时候真的就是机缘巧合。只要你细心观察、愿意多走一步，就能在合适的开源项目里找到“正好需要你”的修复点。