企业官网建设流程全解析

Gollum Docker部署完整指南：从一行命令到生产级Wiki

【免费下载链接】gollumA simple, Git-powered wiki with a local frontend and support for many kinds of markup and content.项目地址: https://gitcode.com/gh_mirrors/go/gollum

Gollum 是一款基于 Git 的轻量级 Wiki 系统，而 Docker 是部署 Gollum 的最简单方式——无需安装 Ruby 环境，一条 Docker 命令即可让 Gollum Docker 镜像在你的服务器上跑起一个功能完整的 Git Wiki，支持 Markdown、AsciiDoc、Org 等多种标记语言。本指南将从"一行命令快速启动"讲起，逐步带你配置到生产级 Wiki 服务。

🐳 为什么用 Docker 部署 Gollum？

直接安装 Gollum 需要 Ruby 2.6+ 环境、编译 Git 相关依赖（rugged/libgit2），步骤繁琐且易出错。而 Docker 部署 Gollum 的优势非常明显：

Gollum 官方在仓库中提供了完整的 Dockerfile，基于ruby:3.3-alpine多阶段构建，并内置了 AsciiDoc、Creole、MediaWiki、Org、ReStructuredText 等标记语言渲染器（见 Dockerfile），开箱即用。

🚀 快速启动：一行 Docker 命令

只需一条命令，Gollum Docker 服务即可启动：

docker run -d -p 4567:4567 -v $(pwd)/wiki:/wiki gollumwiki/gollum

然后打开浏览器访问http://localhost:4567，你的 Gollum Wiki 就跑起来了。

这条命令做了三件事：

1. -v $(pwd)/wiki:/wiki：把宿主机目录挂载到容器的/wiki卷（数据目录）；
2. -p 4567:4567：映射 Gollum 默认端口 4567；
3. 容器内自动初始化：启动脚本会自动检查/wiki目录，若其中还不是 Git 仓库，会自动执行git init（见 docker-run.sh），你无需手动准备仓库。

📦 深入理解：镜像是怎么工作的？

了解镜像内部机制，是排错和生产调优的基础。

双阶段构建：Dockerfile 先用构建阶段安装 Ruby 依赖与各类标记语言渲染器，最终运行镜像只保留运行所需内容，体积小、启动快。

启动脚本逻辑：容器入口为 docker-run.sh，其执行流程为：

1. 校验/wiki目录是否存在且可写（见 docker-run.sh），不可写时会打印警告——这是最常见的权限问题来源；
2. 若/wiki不是 Git 仓库，自动git init；
3. 根据环境变量配置 Git 提交者身份；
4. 以exec gollum "$@"启动服务，所有附加参数都会透传给 gollum 命令（见 docker-run.sh）。

💡 这个"参数透传"特性是 Gollum Docker 部署的关键：所有命令行选项（--port、--bare、--allow-uploads等）都可直接写在docker run末尾。

⚙️ 生产级配置：常用启动参数

结合 README.md 中的命令行选项，生产环境推荐的完整启动命令如下：

docker run -d \ --name gollum \ -p 4567:4567 \ -v /opt/wiki:/wiki \ -e GOLLUM_AUTHOR_USERNAME="MyWiki" \ -e GOLLUM_AUTHOR_EMAIL="wiki@example.com" \ -e APP_ENV=production \ gollumwiki/gollum \ --host 0.0.0.0 \ --page-file-dir docs \ --allow-uploads dir \ --math katex

几个生产要点说明：

• --page-file-dir docs：只发布仓库中docs目录下的页面，页面与其他内容（脚本、构建产物）天然分离；
• --allow-uploads dir：开启拖拽上传，文件统一存到仓库/uploads/目录，方便备份与迁移；
• --math katex：启用数学公式渲染，KTeX 资源已内置于镜像；
• --no-edit：对只读展示型 Wiki，加上该参数可关闭网页端编辑，只保留查阅能力；
• APP_ENV=production：让底层 Sinatra 应用只加载一次，避免开发模式的每次请求重载（见 README.md）。

✍️ 环境变量：设置 Git 提交者身份

通过 Web 界面编辑页面时，Gollum 会以某个身份提交 Git 变更。启动脚本会读取以下环境变量并写入 Git 配置（见 docker-run.sh）：

• GOLLUM_AUTHOR_USERNAME：提交者名称，如团队名或个人名；
• GOLLUM_AUTHOR_EMAIL：提交者邮箱。

⚠️ 如果不设置这两个变量，页面编辑后的 commit 将缺少作者信息，历史记录会显得杂乱。生产部署建议必配。

💾 数据持久化与备份

Gollum 的一切数据——所有页面、图片、历史版本——都只是/wiki卷里的一个 Git 仓库，这是它最大的优势：

• 备份：直接对宿主机映射目录执行git bundle create wiki.bundle --all，一个文件即完整备份；
• 迁移：把备份目录挂到新容器的/wiki，数据即刻可用，零迁移成本；
• 与 GitHub/GitLab 互操作：Gollum 仓库兼容主流平台的 wiki 仓库格式，直接 clone 过来即可继续浏览编辑。

若需修改启动行为（如自定义 Rack 配置），可参考 config.ru 与 config.rb 的占位模板，将其放入挂载卷后通过--config传入。

🔧 构建自定义镜像：修改 UID/GID

默认镜像以非 root 用户www-data（UID/GID 1000）运行容器。若宿主机挂载目录的属主 ID 不同，可能出现"目录不可写"警告。解决方法是构建时指定 UID/GID：

git clone https://gitcode.com/gh_mirrors/go/gollum cd gollum docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) -t gollum:custom .

相关逻辑见 Dockerfile：镜像会用--build-arg传入的 UID/GID 调整内部用户，并预配置git safe.directory，从根源上避免权限报错。

❓ 常见问题速查

🏁 总结

Gollum Docker 部署的核心路径只有三步：一行命令启动 → 挂载/wiki卷持久化 → 用透传参数与环境变量完成生产配置。由于数据本身就是 Git 仓库，备份、迁移、多副本部署都极其轻量。配合本指南中的自定义镜像构建技巧，你可以把 Gollum 打造成稳定、安全、易维护的团队级 Wiki 服务。

想了解更多标记语言（Mermaid 图表、CriticMarkup 批注、BibTeX 引用等高级特性），可继续阅读 README.md 与 gollum.gemspec 了解版本与依赖细节。

【免费下载链接】gollumA simple, Git-powered wiki with a local frontend and support for many kinds of markup and content.项目地址: https://gitcode.com/gh_mirrors/go/gollum