Gollum快速上手教程：3个命令搭建你的Git驱动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是一个用 Ruby 编写的开源Git 驱动 Wiki：任何 Git 仓库，指一下它，就立刻变成一个带网页浏览、在线编辑、版本历史和页面对比的 Wiki——不需要数据库，也不需要复杂部署。本文将带你用3 个命令搭建起自己的 Gollum Wiki，并覆盖 Docker 部署、常用参数等进阶技巧，零基础也能跟上。
为什么选 Gollum？✨
Gollum 由 GitHub 团队的工程师打造（就是 GitHub 上 Wiki 功能背后的那拨人），把"Wiki = Git 仓库"这件事做到了极致。核心卖点如下：
| 特性 | 说明 |
|---|---|
| 📦 纯 Git 存储 | 每个 Wiki 页面就是仓库里一个人类可读的文本文件，版本控制免费获得 |
| 📝 多种标记语言 | Markdown、RDoc 内置；AsciiDoc、MediaWiki、Org、ReStructuredText、Textile 装个 gem 即可用 |
| ✍️ 双通道编辑 | 内置网页编辑器（带自动保存）+ 任意本地编辑器，提交后即时生效 |
| ⏪ 完整历史 | 每个页面可查看所有历史版本、对比差异、一键回滚 |
| 🔁 兼容 GitHub / GitLab Wiki | 直接 clone 它们的 wiki 仓库，本地打开就能看、能改 |
| 🧮 进阶能力 | Mermaid/PlantUML 图、KaTeX/MathJax 数学公式、CriticMarkup 批注、BibTeX 引用、RSS 订阅 |
完整特性清单见项目说明文档 README.md。
准备工作：环境要求一览
Gollum 支持 Unix 类系统与 Windows（Windows 下走 JRuby/Java 路线）。走最简单的 Ruby 路线，你只需要：
- Ruby ≥ 2.6（gollum.gemspec 声明的最低版本）
- Git（你写 Wiki 时迟早会用到它）
💡 完全不想装 Ruby？后文还有Docker与Java WAR两条免环境路线，可直接跳到 不同场景的部署方案。
3个命令搭建你的Git驱动Wiki 🚀
命令一：安装 Gollum
打开终端，一条命令装好：
gem install gollum装完后你会得到gollum命令行工具，输入gollum --version应显示 6.x 版本号。
命令二：初始化一个 Wiki 仓库
任何 Git 仓库都可以成为 Wiki。新建一个空仓库即可：
mkdir my-wiki && cd my-wiki git init两个小提示：
- 如果你已有 GitHub / GitLab 的 wiki 仓库，直接
git clone下来就能打开，天然兼容； - 想先体验一把，也可以 clone 仓库自带的示例 Wiki（《指环王》主题）test/examples/lotr.git。
命令三：启动 Gollum
进入（或指向）你的仓库目录，执行：
gollum ./my-wiki看到终端输出类似Sinatra has taken the stage后，打开浏览器访问http://localhost:4567，你的 Git 驱动 Wiki 就上线了 🎉
此时首页可能是空的——这很正常，仓库还没有页面。点导航栏的New按钮就能创建第一页；当然，你也可以直接在仓库里加一个Home.md文件并git commit，刷新即可看到。
写第一篇 Wiki 页面 ✍️
Gollum 的网页编辑器自带自动保存（网络中断也不怕丢稿），工具栏支持 H1/H2/H3、链接、图片、加粗/斜体、代码块、列表、引用等，翻译文案见 lib/gollum/locales/cn.yml（内置中文界面）。
三个新手必须知道的规则：
- 文件扩展名决定标记语言：
notes.md按 Markdown 渲染，guide.rdoc按 RDoc 渲染，不同页面可以用不同格式； - 页面可以任意分目录：
docs/api.md会出现在/docs/api路径下，目录结构即 Wiki 结构； - 改动 = 一次 Git 提交：无论网页编辑还是本地改文件，都会留下一条可追溯、可回滚的历史记录。
常用命令行参数速查 ⚙️
gollum --help可查看全部选项，日常最常用的是这几个（完整表格见 README.md）：
| 参数 | 默认值 | 用途 |
|---|---|---|
--port | 4567 | 端口冲突时换端口，如gollum ./my-wiki --port 8080 |
--host | 0.0.0.0 | 个人使用建议--host 127.0.0.1，避免局域网暴露 |
--no-edit | 可编辑 | 只读展示模式，适合对外分享 Wiki |
--ref | main（或master） | 指定服务的 Git 分支 |
--bare | — | 仓库是裸仓库（bare）时加上 |
--math | — | 启用数学公式渲染（katex或mathjax） |
--critic-markup | — | 启用 CriticMarkup 批注 |
--static | 生产环境开启 | 使用预编译静态资源 |
安全提醒：默认
--host 0.0.0.0意味着局域网内任何人可访问并可编辑你的 Wiki。个人使用请显式加--host 127.0.0.1。
不想写命令行参数？也可以用配置文件：config.rb 用于扩展自定义行为（如注册自定义标记语言），config.ru 则用于以 Rack 应用方式启动、调整启动行为。
不同场景的部署方案
方案A：Docker 一键部署（推荐新手）🐳
不需要装 Ruby，一条命令搞定。Dockerfile 基于ruby:3.3-alpine构建，docker-run.sh 会自动为/wiki卷git init并启动 Gollum：
docker run -d -p 4567:4567 -v /宿主机/路径/my-wiki:/wiki gollumwiki/gollum方案B：Java WAR（适合 Windows / 无 Ruby 环境）☕
Gollum 的发行版中包含gollum.war，只要有 Java 就能跑：
java -jar gollum.war -S gollum /绝对路径/my-wiki注意：WAR 方式下参数务必传绝对路径。
方案C：作为系统服务常驻（适合团队服务器）
项目自带各发行版的服务定义，可直接部署为开机自启服务：
- systemd：contrib/systemd/gollum@.service
- OpenRC：contrib/openrc/init.d/gollum
- SysVinit：contrib/sysv-debian/init.d/gollum
方案D：从源码运行（适合贡献者）🛠️
想魔改 Gollum 本身？按 CONTRIBUTING.md 的流程：
git clone https://gitcode.com/gh_mirrors/go/gollum cd gollum && bundle install bundle exec bin/gollum /path/to/my-wiki应用主逻辑位于 lib/gollum/app.rb，页面视图在 lib/gollum/views/，方便你按需扩展。
常见问题 FAQ
Q1：端口 4567 被占用了？换端口即可：gollum ./my-wiki --port 8080，然后访问对应新地址。
Q2：只想展示，不希望别人编辑？加--no-edit参数启动，编辑入口会被禁用。
Q3：development和production有什么区别？由环境变量APP_ENV控制：development下每次请求都重载应用（便于调试），production下只加载一次（性能更好）。
Q4：为什么我提交了新页面，Wiki 里看不到？确认 Gollum 指向的分支正确（可用--ref指定），以及页面文件扩展名是否为受支持的标记语言（如.md、.rdoc）。
Q5：能把 GitHub/GitLab 的 Wiki 搬过来吗？可以，这正是 Gollum 的设计目标之一——clone 它们的 wiki 仓库，gollum一下即可本地浏览与编辑，数据完全留在自己的 Git 仓库里。
写在最后
回顾一下，搭建 Gollum Wiki 其实就 3 个命令：
gem install gollum—— 安装git init—— 准备仓库gollum ./my-wiki—— 启动，打开 http://localhost:4567
从此你的团队文档、学习笔记、产品手册都可以以"纯 Git 文本"的形式沉淀下来：可搜索、可回滚、可 diff，还能随时换到 Gollum 里在线协作。快去创建你的第一页吧！
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
