### [雨云搭建 BookStack 团队文档](https://www.jiyueip.com/article/12274)

**Published:** 2026-07-28T09:48:44

**Author:** 斑斓助理

**Excerpt:** 用雨云 KVM 云服务器 Docker 自建 BookStack 团队文档/wiki，BookStack+MySQL 部署、Nginx 反代 HTTPS、书架层级与权限。含默认密码坑、413 上传限制与优惠码 admin01 五折。

团队文档散在聊天记录、各种在线文档里，新人接手要翻半天，关键步骤还容易随人离职带走。BookStack 是一个开源文档/wiki 系统，PHP + MySQL，特点是「书架 → 书 → 章节」的层级，像把知识排成图书馆，写操作手册、产品文档很顺手。本文用一台雨云 KVM 云服务器，Docker 一把拉起 BookStack + MySQL，配 HTTPS 反代，把团队文档收归自己托管。

## 一、先准备一台雨云 KVM 云服务器

BookStack 基于 PHP，比纯静态站点吃一点资源，1 核 2G 跑得稳，需要 7×24 在线、有公网 IP、绑域名走 HTTPS。想低成本起一台可以看国产高性价比云服务器，比如雨云：KVM 虚拟化、Debian/Ubuntu 镜像任选，新用户用优惠码 **admin01** 享五折，入门版折后约 9 元/月，支持 7 天无理由退款。挑机器可参考 [VPS 怎么选不踩坑](https://www.jiyueip.com/article/12235) 与 [新手买 VPS 先看这几个配置参数](https://www.jiyueip.com/article/12225)。

我选 Debian 12。基础安全按 [VPS 到手第一件事做什么](https://www.jiyueip.com/article/12226) 走一遍，本文默认你已建好普通用户、开了 ufw。后台走 8080，放行即可。

## 二、用 Docker 拉起 BookStack + MySQL

装 Docker：

```bash
curl -fsSL https://get.docker.com | sh
systemctl enable --now docker
```

建目录并写 `docker-compose.yml`：

```bash
mkdir -p /opt/bookstack && cd /opt/bookstack
```

```yaml
version: "3"
services:
  db:
    image: mariadb:11
    container_name: bookstack-db
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=改成强密码
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=改成另一个强密码
    volumes:
      - ./db:/var/lib/mysql
  bookstack:
    image: linuxserver/bookstack:latest
    container_name: bookstack
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "8080:80"
    environment:
      - DB_HOST=db
      - DB_DATABASE=bookstack
      - DB_USERNAME=bookstack
      - DB_PASSWORD=改成另一个强密码
      - APP_URL=https://docs.example.com
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/config
```

注意 `DB_PASSWORD` 要和 db 服务里的 `MYSQL_PASSWORD` 一致。启动：

```bash
docker compose up -d
```

浏览器先开 `http://服务器IP:8080`，默认管理员 `admin@admin.com` / `password`，**第一次登录务必改密码**。

## 三、配 HTTPS 反代

文档要团队访问，http 裸奔不安全，上 HTTPS。用 Nginx 反代 8080：

```nginx
server {
    listen 80;
    server_name docs.example.com;
    location / { return 301 https://$host$request_uri; }
}
server {
    listen 443 ssl;
    server_name docs.example.com;
    ssl_certificate /etc/letsencrypt/live/docs.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/docs.example.com/privkey.pem;
    client_max_body_size 50m;   # 允许传附件
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

申请证书：`certbot --nginx -d docs.example.com`。放行端口：

```bash
ufw allow 80/tcp
ufw allow 443/tcp
ufw reload
```

## 四、怎么用出效率

-   **建书架**：先建「书架」（如「运维手册」），下面挂多本「书」（如「部署规范」「故障排查」），每本书里按章节写页面，层级清晰。
-   **编辑器友好**：自带所见即所得编辑器，也支持 Markdown，粘贴代码有高亮。
-   **权限分组**：后台「用户 → 角色」给不同人设只读/可编辑，外包人员给受限权限。
-   **数据备份**：核心是 `./db`（MySQL）和 `./data`（上传的附件）。定期 `mysqldump` 加打包 `./data`；异地思路见 [雨云快照备份与对象存储](https://www.jiyueip.com/article/11963)。

## 五、踩过的坑与经验

-   **默认密码必须改**：`admin@admin.com / password` 是公开默认值，不改成公网就是送门。登录后第一件事改密码、关匿名注册。
-   **APP\_URL 要 https**：填成 http 会导致页面里资源用错协议、登录后样式错乱。改成最终 https 域名再起。
-   **上传附件超限**：默认 Nginx `client_max_body_size` 1m，传大文件报 413。反代里调到 50m，并确认 BookStack 后台上传限制。
-   **存储权限**：`./data` 映射后若 Web 进程写不进，检查宿主目录属主与容器 PUID/PGID（linuxserver 镜像支持 `PUID`/`PGID` 环境变量）。
-   **和同类工具的分工**：BookStack 偏「结构化文档/手册」，和 [雨云搭建 Wiki.js](https://www.jiyueip.com/article/12255)、[雨云搭建 Outline](https://www.jiyueip.com/article/12267) 定位不同——前者像图书馆分类，后两者偏知识库/协作文档。团队操作手册选 BookStack 最顺手。
-   **容器时区**：加 `TZ=Asia/Shanghai`，否则日志和编辑时间差 8 小时。

## 小结

文档的本质是「可检索的团队记忆」。BookStack 用书架层级把知识排整齐，Docker 部署几乎零运维，适合放操作手册、 onboarding 材料。常驻文档服务很适合雨云这类低价稳定 KVM——[优惠码 admin01 五折](https://www.jiyueip.com/link/5617)、7 天无理由退款，跑团队文档很合适。

> **合规提醒**：使用雨云及本文所述方案时，请遵守《网络安全法》《个人信息保护法》《数据安全法》等相关法律法规，仅用于合法合规的团队文档与知识管理，妥善保管账号、履行个人信息保护义务，不得利用本服务存储或传播违法违规内容。

**Tags:** 云服务器, 建站教程, 雨云, 雨云优惠码

**Categories:** 行业洞察

---