团队知识库别再用在线文档了？BookStack 自托管 Wiki VPS 教程

2026-08-15 · DevCraft Studio

用 Docker 在 VPS 上搭 BookStack 私有 Wiki，配域名+HTTPS、自动备份数据库、权限分组，适合小团队/个人笔记库，1G 内存就能跑。

延伸阅读

更多相关攻略推荐：【年付性价比 01】年付 VPS 性价比排行 2026：同配置谁最值、【10刀以内VPS系列 01】年付不到70块钱的便宜VPS，到底能用、【支付宝微信 02】支付宝/微信怎么买国外 VPS？2026 支持人、从 Git Push 到秒级上线：CI/CD 流水线与"无中断"发布、【VPS 进阶玩法精选 030】用 VPS 搭建云端 IDE（cod。

为什么小团队别再吊死在在线文档上

先说句得罪人的话：很多团队的知识库，最后都烂在在线文档里。不是文档工具不好用，而是它们的商业模式决定了——你越依赖它，它收你越贵。Notion 按人头收费，几个人一坐就是每月几十刀；Confluence 功能堆到一半就让你买插件；飞书、语雀这类国内产品，免费额度用满之后扩容也不便宜，而且最要命的是：你的数据躺在别人的服务器上。

一旦哪天想导出全部内容换平台，你会发现导出格式要么残缺、要么图片丢一半，迁移成本比重新写一遍还高。更现实的风险是：公司电脑丢了、员工离职账号没回收、前任搭的文档树没人看得懂——这些坑，在线文档一个都帮不了你。

所以如果只是想给三五个人的小团队、或者给自己搞一个稳定的笔记库，自托管一个 Wiki 往往是更省心也更便宜的出路。本文主角 BookStack，就是这类需求里最容易被忽略、但实际最顺手的一个。下面我直接带你在 VPS 上把它跑起来。

举个真实例子：你招了个实习生，在飞书文档里给了编辑权，他手一抖把半年的运营复盘覆盖了，历史版本找回还得看付费档位；而 BookStack 每个页面都带版本历史（page revisions），误删误改一键回退，还不收你升级费。再比如你要离职交接，在线文档的导出常常把评论和嵌套结构弄丢，BookStack 却能把整本书一键导成 Markdown 或 HTML，连图片都打包带走。这些细节，才是自托管真正值钱的地方，也是它比"再开一个在线文档"更靠谱的根本原因。

BookStack 到底是什么，凭什么能打

BookStack 是一个开源、免费、MIT 协议授权的自托管 Wiki 平台，用 PHP（Laravel 框架）写成，数据存进 MySQL 或 MariaDB。它最聪明的地方不是功能多，而是强迫你用一套清晰的内容结构：书架（Shelf）→ 书（Book）→ 章节（Chapter）→ 页面（Page）。

这听起来像形式主义，但实际体验是：新人第一天进来，不用讨论"这个文档该放哪个文件夹"，因为层级已经替你想好了。书和章节类比真实世界的资料柜，页面就是真正写字的地方。比起 Notion 那种自由画布（新手容易建一堆乱七八糟的块），BookStack 的" Opinionated（主观定制的）"设计反而降低了团队采纳的门槛。

它的核心卖点我列几个实在的：

  • 编辑器双模：既有时髦的所见即所得（WYSIWYG）界面，也内置 Markdown 编辑器带实时预览，写技术文档的人会很舒服。
  • 内置 diagrams.net：直接在页面里画架构图、流程图，不用再开个 draw.io 另存图片。
  • 全文搜索：基于数据库全文索引，跨书、跨章节秒搜，还能链接到任意段落。
  • 权限系统：角色（Role）到全局、到单本书、到单个书架都能控制可见和可编辑，小团队分"只读成员 / 编辑 / 管理员"很轻松。
  • 导出与 API：每个页面都能导出 HTML/PDF/Markdown，还带完整 REST API，方便以后做自动化。
  • 多因素认证：TOTP 动态码 + 备用码，能按角色强制开启，安全底线够用。
  • 多语言与暗色模式：界面自带中英文等多国语言，深色浅色随意切。

落到具体场景，它特别适合这几类活：技术团队的运维手册（Runbook）和故障排查指南、公司的入职 SOP 与人事制度、个人的技术笔记和读书摘抄，甚至小团队的 API 文档。因为层级固定，wiki 不会随着内容变多而越长越乱——新书往书架上摆，新章节往书里塞，结构永远清清楚楚，新人进来也不会面对一堆不知道该放哪的空白文档。

最关键一句：它不按人头收费、不搜集遥测、不锁导出。你买一台 VPS 的钱，就是它的全部成本。截至 2026 年 8 月，BookStack 最新稳定版为 v26.05.3 安全更新版，官方要求 PHP ≥ 8.2、MySQL ≥ 8.0 或 MariaDB ≥ 10.6。

1GB 内存的便宜 VPS 够不够跑？选 RackNerd 还是 CloudCone

这是大家最关心的：BookStack 到底吃多少资源？实测下来，BookStack 应用容器常驻内存约 150–250 MB，MariaDB 数据库再吃 100–200 MB，整机空闲时合计 300–400 MB 左右。也就是说，1GB 内存的 VPS 跑一个小团队的知识库完全绰绰有余，真要几十人同时编辑再上 2GB。

那么便宜 VPS 怎么选？结合 2026 年的行情，预算市场里 RackNerd 和 CloudCone 是被提得最多的两家，我都帮你看过了：

  • RackNerd 1GB KVM：1 核、1GB 内存、20GB SSD、月流量 3TB，年付约 21.99 美元（约 160 元人民币）。最大优点是真便宜，而且续费价格和首年一致，不会"首年特价次年翻三倍"。缺点是部分节点用普通 SSD、晚高峰偶尔丢包，稳定性大概在 95%–99% 之间。
  • CloudCone 1GB：1 核、1GB 内存、14GB SSD、月流量 1TB，年付低至 12.99 美元（约 95 元人民币）。它走的是云架构，多数节点已升级 NVMe、磁盘 IO 更快，自带快照和自动备份、防火墙规则，控制台比 RackNerd 的 SolusVM 好用，稳定性接近 99.9%。缺点是要稍贵一点、且按小时计费更灵活。

我的建议很直接：纯粹练手、跑个个人笔记库，闭眼选 RackNerd 年付，一年一百多块丢了不心疼；如果是真要放团队资料、希望稳一点，多花几十块上 CloudCone，它的快照和自动备份能省掉你后面一大堆运维心事。两家国内访问延迟都在 150–200ms 左右、都没有 CN2 优化线，但知识库是内部慢查型的，这点延迟完全能接受。

开干前先备齐三样东西

动手之前，确认你手上有这三样：

  • 一台装好 Ubuntu 22.04/24.04 的 VPS，至少 1GB 内存，开放 22/80/443 端口。本文以 RackNerd 或 CloudCone 的 1GB 套餐为例。
  • 一个能解析到这台 VPS 的域名或子域名，比如 wiki.example.com，去 DNS 后台加一条 A 记录指向服务器 IP 即可。
  • SSH 登录的 sudo 权限。BookStack 本身不需要 root，但装 Docker 需要。

顺手把防火墙开了，后面 Caddy 要抢 80/443 做证书校验：

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

先装好 Docker 和 Docker Compose 插件（用官方便捷脚本最省事）：

sudo apt update
sudo apt install -y ca-certificates curl
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

装完退出重登一次，让 docker 组权限生效。验证一下：

docker --version
docker compose version

一条 docker-compose 把整套服务拉起来

我们用 linuxserver.io 维护的 BookStack 镜像，配合 MariaDB 做数据库，外面再套一个 Caddy 做自动 HTTPS 反代。三个容器一个文件管完，备份也只需盯一个目录。

先在 /opt 下建项目目录：

sudo mkdir -p /opt/bookstack
cd /opt/bookstack

创建 docker-compose.yml，下面的密码请换成你自己的强密码：

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - APP_URL=https://wiki.example.com
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_USER=bookstack
      - DB_PASS=change_this_db_password
      - DB_DATABASE=bookstack
    volumes:
      - ./bookstack_app:/config
    restart: unless-stopped
    depends_on:
      - bookstack_db

  bookstack_db:
    image: lscr.io/linuxserver/mariadb:10.11
    container_name: bookstack_db
    environment:
      - PUID=1000
      - PGID=1000
      - MYSQL_ROOT_PASSWORD=change_this_root_password
      - TZ=Asia/Shanghai
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=change_this_db_password
    volumes:
      - ./bookstack_db:/config
    restart: unless-stopped

  caddy:
    image: caddy:2
    container_name: caddy
    ports:
      - 80:80
      - 443:443
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./caddy_data:/data
      - ./caddy_config:/config
    restart: unless-stopped
    depends_on:
      - bookstack

注意两个细节：APP_URL 必须写成你真实的 https 域名，因为 BookStack 生成的邮件链接、导出链接都依赖它，一开始填错后面全是坏链；DB_PASS 和 MYSQL_PASSWORD 必须一模一样，否则 BookStack 连不上库。

配域名 + HTTPS，让 Caddy 自动签发证书

在同目录建一个 Caddyfile，内容极简，Caddy 会自动向 Let's Encrypt 申请并续期证书：

wiki.example.com {
  reverse_proxy bookstack:80
}

确认你的 DNS 的 A 记录已经指向这台 VPS 的 IP（可以用 dig +short wiki.example.com 验证），然后一键启动：

docker compose up -d

第一次启动数据库要初始化几十秒，等日志出现 "ready to handle connections" 再访问。浏览器打开 https://wiki.example.com，看到登录页就成功了。Caddy 全程自动搞定 80→443 跳转和证书续期，你啥都不用管。

这里有个小提醒：如果你的域名还没完成解析就急着启动，证书申请会一直失败导致容器反复重启，所以务必先确认解析生效再执行启动命令。另外有些机房默认没有放开网络端口，记得在服务商后台的安全组里放行对应端口，否则外网一样访问不了。等页面能正常打开，第一步永远是先改默认密码，千万别急着往里填内容，顺序反了容易出岔子。

第一次登录必须做的三件事

BookStack 首次启动的默认账号是 admin@admin.com / password，任何人都能登，所以进系统第一件事就是改密码。点右上角头像 → My Account → 改密码，顺手把管理员邮箱也换成你自己的真实邮箱——密码找回邮件只发到这个地址，用占位邮箱你会把自己锁死。

  • 改管理员密码和邮箱：Settings → Users → 编辑 admin，密码和邮箱一起改。
  • 关掉公开注册：Settings → Registration，把允许注册的开关关掉，否则互联网上谁都能建账号写垃圾。
  • 设站点名和 logo：Settings → 外观，把默认的 "BookStack" 改成你团队的名字，顺手传个 logo，仪式感拉满。

权限与分组：用角色系统管住不同人

小团队最怕"谁都能改谁都能删"。BookStack 的权限模型是：先建角色（Role），再给角色分配权限，最后把人塞进角色。常见三档就够了：

  • Viewer（只读）：只能看，不能改，适合外包、实习生、老板巡视。
  • Editor（编辑）：能在指定书里新建/编辑页面，但不能改系统设置、不能删书。
  • Admin（管理员）：全权限，只给你自己。

权限还能精细到"某一本书只对某角色可见"。比如把"薪酬制度"那本书只对 HR 角色开放，其他人根本看不到入口。设置路径在 Settings → Roles，建好角色后在 Users 里给每个人勾选对应角色即可。记住一条铁律：最小权限原则，默认给只读，需要才加编辑。

自动备份：数据库 + 上传目录，每天一份

自托管最大的代价就是备份得自己管。BookStack 真正要命的数据有两块：MariaDB 里的全部内容，以及 /config 上传的附件图片。写个小脚本每天打包，丢到本地之外的地方（比如另一台机器或对象存储）就安心了。

#!/bin/bash
BACKUP_DIR=/opt/bookstack/backups
DATE=$(date +%Y%m%d)
mkdir -p $BACKUP_DIR
docker exec bookstack_db sh -c   'mariadb-dump -uroot -pchange_this_root_password bookstack'   > $BACKUP_DIR/bookstack_db_$DATE.sql
tar czf $BACKUP_DIR/bookstack_files_$DATE.tar.gz   /opt/bookstack/bookstack_app
find $BACKUP_DIR -mtime +7 -delete

把上面的密码换成你自己的，保存为 backup.sh，chmod +x 后丢进 crontab 每天凌晨跑：

0 3 * * * /opt/bookstack/backup.sh

如果选了 CloudCone，它控制台自带快照和自动备份，等于又多一层保险，这也是我前面推荐它跑真团队资料的原因。

升级与日常维护，别让版本落后太多

Docker 部署的升级简单到一行：

cd /opt/bookstack
docker compose pull
docker compose up -d

这条命令会拉最新镜像并重建容器，数据库卷是挂载在宿主机上的，不会丢。但升级前请务必先跑一遍上面的备份脚本——习惯成自然，出事能秒回滚。BookStack 大版本之间偶尔有数据库结构变更，官方会在更新日志里写明，跨大版本升级前先看一眼 release notes 最稳妥。

顺带一提，想确认服务还活着，BookStack 自带一个 /status 健康检查接口，返回 200 就代表各子系统正常。你可以把它接进 Uptime Kuma 之类的监控面板，挂了自动发告警，比每天手动打开看一眼省事得多。配合前面说的每日备份，基本就构成了一套"能自证健康、能快速回滚"的最小可用运维闭环。

另外，镜像标签用了 latest，意味着每次 pull 都是最新稳定版。如果你想更可控，可以把镜像钉到具体版本号（比如 lscr.io/linuxserver/bookstack:v26.05.3），避免某天自动拉到一个有问题的版本。

几个容易踩的坑，提前替你排了

教程写到这里，有几个新手十有八九会栽的地方，我提前点出来，照着避开能省掉大半夜的折腾：

  • APP_URL 填错：很多人图省事填成 http 加服务器 IP 和端口，结果邮件里的重置链接、导出文件里的图片地址全变成内网地址，发给同事直接打不开。一开始就填 https 域名，后面少返工。
  • 数据库密码两边不一致：compose 里 bookstack 服务和 mariadb 服务的密码必须完全相同，差一个字符就报数据库连接失败，卡在迁移步骤动弹不得。
  • 忘记改默认管理员账号：admin@admin.com 配合密码 password 是公开的，不立刻改等于把家门钥匙挂门口。改完顺手关掉公开注册，别等被机器人灌了一堆垃圾页才后悔。
  • 只备份数据库不备份上传目录：页面里贴的截图、附件都存在 /config 里，光导数据库的话，恢复后图片全变裂图。数据库和文件目录必须一起打包。
  • 用 latest 标签还不开自动备份：镜像一升级就可能引入不兼容，没备份就 pull 等于赌运气。先把上面的每日备份脚本挂上，再谈升级。

把这些坑避开，你这套自托管知识库基本就能安稳跑上一年半载，平时几乎不用管它，真正的"一次部署、长期省心"。

不想用 Docker？官方还有一键脚本

如果你嫌容器概念太绕，或者这台机器上本来就跑着别的网站环境，BookStack 官方其实也提供了针对 Ubuntu 22.04、24.04、26.04 的纯净安装脚本。它会在一台全新系统上自动装好网页服务器、数据库和 PHP 运行环境，然后拉起整个应用，全程基本不用你手动敲配置。不过要提醒两点：这套脚本只适合干净的新系统，会覆盖机器上已有的网站配置；而且它不会帮你配置发信邮件和系统防火墙，这两步得自己补齐。对个人玩家和大多数小团队来说，上文的 Docker 方案更干净、更好回滚，所以我仍主推容器路线；只有当你明确需要原生部署、且熟悉 Laravel 运维时，才去官方文档取对应版本的脚本。