🚀 使用 Docker Compose 部署 Docsify （轻量级文档网站）

🚀 使用 Docker Compose 部署 Docsify

本文将详细介绍如何使用 Docker Compose 部署 Docsify——一个轻量级、基于 Markdown 的文档网站生成工具，它能够帮助您快速搭建美观、响应式的文档网站。

📝 项目简介

Docsify 是一个动态生成文档网站的工具。与传统的静态站点生成器不同，Docsify 在运行时动态渲染 Markdown 文件，让您只需使用简单的 Markdown 语法编写文档，就能获得一个具有专业外观的文档网站。

核心特点：

• 基于 Markdown：使用熟悉的 Markdown 语法编写文档，简单高效
• 实时渲染：修改 Markdown 文件后，刷新浏览器即可看到更新，无需重新构建
• 响应式设计：生成的文档网站能自适应各种设备和屏幕尺寸
• 丰富的插件生态：支持搜索、代码高亮、分页导航等多种插件
• 部署简单：只需一个 HTML 文件和一些配置即可创建整个文档网站

---

📝 项目简介2

Docsify 是一款 轻量级文档网站生成工具，无需预先编译 Markdown 文件，直接通过浏览器实时渲染文档内容，适合快速搭建个人笔记、项目文档、知识库等站点。其核心优势在于 “零编译、易扩展、轻量高效”，配合 Docker 部署可实现跨平台无缝迁移。

本次部署包含三个核心组件：

• Docsify 容器：基于官方镜像或自定义 Dockerfile 运行，提供文档网站服务；
• 数据卷挂载：本地 ./docs 目录与容器内文档目录关联，实时更新 Markdown 内容；
• 同步脚本（1.sh）：用于将外部笔记（如 Obsidian）内容同步到 Docsify 文档目录，适配多工具协作场景。

核心特点

1. 零编译实时渲染：修改 Markdown 文件后无需重启服务，刷新浏览器即可查看更新，简化文档维护流程；
2. 轻量低资源占用：容器镜像体积约 100MB，运行时内存占用 < 50MB，1 核 512MB 服务器即可稳定运行；
3. 高度自定义：支持自定义主题、侧边栏、导航栏，内置搜索功能，可通过插件扩展代码高亮、数学公式等功能；
4. 多平台兼容：文档基于 Markdown 格式，可与 Obsidian、Typora 等笔记工具无缝协作，配合同步脚本实现内容自动同步；
5. 数据持久化：文档内容存储在本地 ./docs 目录，容器删除或更新后数据不丢失，便于备份与迁移。

---

🔧 部署前准备

系统环境要求

• 操作系统：支持 Linux、Windows、macOS
• Docker 引擎：版本 20.10+
• Docker Compose：版本 2.0+
• 硬件资源：
• 内存：至少 512MB
• 存储空间：至少 1GB 可用空间

环境检查

1.检查 Docker 服务状态

   systemctl status docker

确保 Docker 服务处于 active (running) 状态

2.检查 Docker 版本

   docker --version

3.创建部署目录

   mkdir -p /home/compose/docsify && cd /home/compose/docsify

⚙️ 配置 Docker Compose

准备配置文件

创建 docker-compose.yml 文件：

services:
  demo:
    stdin_open: true  # 保持标准输入打开（容器交互需要）
    tty: true         # 分配伪终端（支持终端交互）
    ports:
      - 3000:3000  # 端口映射：主机 3000 → 容器 3000（Docsify 默认服务端口）
    container_name: docsify  # 容器名称，便于管理（如停止/查看日志）
    volumes:
      - ./docs:/docs  # 核心挂载：本地 ./docs 目录 → 容器 /docs 目录（文档实时同步）
    image: docsify/demo  # 官方演示镜像（内置 Docsify 环境，开箱即用）
    restart: always #unless-stopped  # 容器退出后自动重启（保障服务稳定运行）

基于自定义 Dockerfile（适合扩展需求） 创建 Dockerfile（可选，用于自定义构建）：

  FROM node:latest  # 基于 Node.js 最新镜像（Docsify 依赖 Node 环境）
  LABEL description="A demo Dockerfile for build Docsify."  # 镜像描述
  WORKDIR /docs  # 设置工作目录为 /docs（容器内文档存放路径）
  RUN npm install -g docsify-cli@latest  # 全局安装 Docsify 命令行工具
  EXPOSE 3000/tcp  # 暴露 3000 端口（与服务端口一致）
  ENTRYPOINT docsify serve .  # 容器启动命令：在当前目录启动 Docsify 服务

（2）修改 docker-compose.yml 适配自定义镜像

version: '3'
services:
  demo:
    stdin_open: true
    tty: true
    ports:
      - 3000:3000
    container_name: docsify
    volumes:
      - ./docs:/docs
    build: .  # 替换 image 为 build: .，表示基于当前目录的 Dockerfile 构建镜像
    restart: always

3. 关键配置说明（新手必看）

配置项	作用与注意事项
volumes: ./docs:/docs	核心挂载！本地 ./docs 目录的 Markdown 文件会实时同步到容器，修改后无需重启服务，刷新浏览器即可生效。
ports: 3000:3000	主机端口 3000 可自定义（如 8080:3000），需同步开放新端口并通过新端口访问。
restart: always	服务器重启或容器意外退出后自动恢复服务，适合长期运行的文档站点。
自定义 Dockerfile	RUN npm install -g docsify-cli@latest 可指定版本（如 @4.4.4），避免最新版兼容性问题。

关键配置说明

1. 镜像选择：使用官方 docsify/demo 镜像，包含预配置的 Docsify 环境

2. 端口映射：3000:3000 将容器内的 3000 端口映射到宿主机的 3000 端口

3. 数据持久化：./docs:/docs 将本地 docs 目录挂载到容器内，确保文档数据持久化

4. 重启策略：always 确保容器异常退出时自动重启

5. 终端配置：stdin_open 和 tty 确保容器可以交互式操作

项目结构准备

创建标准的 Docsify 项目结构：

项目根路径
┣ docs
┃ ┣ _sidebar.md    # 文档左侧导航
┃ ┣ _coverpage.md  # 文档首页封面
┃ ┗ index.html     # 入口文件
┣ docker-compose.yml
┗ Dockerfile

---

🚀 启动与验证

启动服务

docker compose up -d

参数 -d 表示在后台运行容器

基于自定义 Dockerfile

# 构建并启动容器（--build 确保每次修改 Dockerfile 后重新构建）
docker compose up -d --build

验证服务状态

1. 检查容器运行状态 bash docker compose ps 应该看到 docsify 服务处于 Up 状态

2. 查看服务日志 bash docker compose logs -f

3. 访问 Web 界面 在浏览器中访问 http://你的服务器IP:3000

初始文档结构验证

确保 docs 目录包含基本文件： - index.html：Docsify 配置文件 - README.md：主页内容 - _sidebar.md：侧边栏导航 - _coverpage.md：封面页（可选）

---

（2）访问 Docsify 文档网站

1. 打开浏览器，输入 http://服务器IP:3000（如本地测试：http://localhost:3000，远程服务器：http://192.168.1.100:3000）；
2. 首次访问会显示 Docsify 默认页面（提示 “Welcome to docsify”），说明服务正常；
3. 若 ./docs 目录中已有 Markdown 文件（如 README.md），页面会自动加载该文件内容。

（3）验证同步脚本（1.sh）

若需同步外部笔记（如 Obsidian）到 Docsify：

1.修改 1.sh 中的路径为实际笔记目录（如将 /1/ob 改为你的 Obsidian 存储路径，/1/Docsify 改为 /opt/docsify/docs）； 2.执行脚本同步内容：

    cd /opt/docsify
    ./1.sh

3.刷新浏览器，若 ./docs 目录中的新文件被加载，说明同步成功。

---

🔌 基础配置与使用

基本文档结构配置

1.配置 index.html

   <!DOCTYPE html>
   <html lang="zh-CN">
   <head>
     <meta charset="UTF-8">
     <title>文档标题</title>
     <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
     <meta name="description" content="Description">
     <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
     <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
   </head>
   <body>
     <div id="app"></div>
     <script>
       window.$docsify = {
         name: '我的文档',
         repo: '',
         loadSidebar: true,
         subMaxLevel: 2
       }
     </script>
     <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
   </body>
   </html>

2.配置侧边栏 (_sidebar.md)

   - 首页
     - [简介](README.md)

   - 产品介绍
     - [背景](product/background.md)
     - [功能特性](product/features.md)

   - 用户指南
     - [快速开始](guide/quickstart.md)
     - [高级用法](guide/advanced.md)

3.配置封面页 (_coverpage.md)

   # 我的文档网站

   > 一个专业的文档中心

   [开始阅读](#首页)

文件同步脚本配置

创建 1.sh 同步脚本：

#!/bin/bash
# 这是脚本，用来同步的，放在1panel里面。当然系统本身支持bash就更好了。

# 同步到 docsify
cp -rfu /1/ob/* /1/Docsify
#开启ob的同步（下划线_）文件

# mkdocs
cp -rfuv /1/ob/* /1/mkdocs
rm /1/mkdocs/_sidebar.md
echo "删除无关文件成功，_sidebar.md"
# 没有docsify就不同步下划线文件了。

给脚本添加执行权限：

chmod +x 1.sh

常用功能扩展

1.启用搜索功能 在 index.html 中添加：

   <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

2.代码高亮

   <script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-bash.min.js"></script>
   <script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-javascript.min.js"></script>
   <script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-python.min.js"></script>

---

🔌基础配置与使用2

Docsify 核心是通过修改 ./docs 目录中的 Markdown 文件和配置文件自定义网站，新手可从以下基础操作入手：

1. 添加文档内容

• 在 ./docs 目录创建 Markdown 文件（如 guide.md），内容示例：

    # 新手指南  
    这是一篇通过 Docsify 展示的文档。  
    - 支持列表  
    - 支持 **粗体** 和 *斜体*  

• 浏览器访问 http://服务器IP:3000/#/guide 即可查看该文档（路径对应文件名，无需 .md 后缀）。

2. 自定义侧边栏

默认侧边栏自动生成，可通过 _sidebar.md 自定义：

1.在 ./docs 目录创建 _sidebar.md，内容示例：

    - [首页](/)  
    - [新手指南](guide)  
    - [配置说明](config)  

2.刷新浏览器，侧边栏会显示自定义导航，点击可跳转对应文档。

3. 自定义首页

首页默认加载 ./docs/README.md，修改该文件可自定义首页内容：

# 我的知识库  
欢迎访问通过 Docsify 搭建的个人文档站点！  
- 点击左侧导航浏览内容  
- 支持实时编辑更新  

4. 自动同步文档（配合 1.sh）

若使用 Obsidian 等工具编写笔记，可通过定时任务自动执行 1.sh 同步内容：

# 添加定时任务（每 5 分钟同步一次）
crontab -e
# 在打开的文件中添加以下内容（路径替换为实际部署目录）
*/5 * * * * /opt/docsify/1.sh

---

🛠️ 维护与管理

日常维护操作

1.服务启动/停止

   # 停止服务
   docker compose down

   # 启动服务
   docker compose up -d

   # 重启服务
   docker compose restart

2.数据备份

   # 备份文档数据
   tar -czf docsify-backup-$(date +%Y%m%d).tar.gz ./docs

3.服务更新

   # 拉取最新镜像
   docker compose pull

   # 重启服务
   docker compose down
   docker compose up -d

监控与日志

1.查看实时日志

   docker compose logs -f

2.监控资源使用

   docker stats docsify

🐛 常见问题排查

1. 无法访问 Web 界面

问题现象：浏览器访问 http://IP:3000 无响应

解决方案： - 检查防火墙设置：

  # 开放 3000 端口
  ufw allow 3000

• 验证容器状态：docker compose ps
• 检查端口占用：netstat -tulpn | grep 3000

2. 文档修改不生效

问题现象：修改 Markdown 文件后页面无变化

解决方案： - 检查文件路径和权限 - 确认文件编码为 UTF-8 - 清除浏览器缓存后重试

3. 侧边栏不显示

问题现象：页面缺少侧边栏导航

解决方案： - 检查 _sidebar.md 文件是否存在 - 确认 index.html 中已启用侧边栏：loadSidebar: true - 验证侧边栏文件路径是否正确

4. 脚本同步失败

问题现象：同步脚本执行报错

解决方案： - 检查脚本执行权限：chmod +x 1.sh - 验证源目录和目标目录是否存在 - 确认文件路径大小写正确

5. 容器启动失败

问题现象：Docker 容器无法正常启动

解决方案： - 查看详细错误日志：docker compose logs - 检查 docs 目录权限 - 验证 Docker Compose 文件语法

通过本教程，您应该已经成功部署并配置了 Docsify 文档服务。Docsify 的简洁设计和实时渲染特性让它成为个人和团队文档管理的理想选择。如果在使用过程中遇到其他问题，可以参考 Docsify 官方文档或相关社区资源。

---

🐛 常见问题排查2

1. 文档修改后页面不更新

• 原因 1：浏览器缓存导致未加载最新内容。解决：按 Ctrl+Shift+R 强制刷新浏览器，或清除浏览器缓存。

• 原因 2：文件未同步到 ./docs 目录（使用同步脚本时）。解决：手动执行 ./1.sh，检查脚本中源目录和目标目录是否正确（路径是否存在、权限是否允许读取）。

2. 侧边栏不显示或导航错误

• 原因 1：_sidebar.md 格式错误（如路径错误、语法错误）。解决：检查 _sidebar.md 中的链接是否正确（如 [指南](guide) 对应 guide.md 文件），确保无多余空格或特殊字符。

• 原因 2：未启用自定义侧边栏（Docsify 默认可能关闭）。解决：在 ./docs/index.html 中添加配置（若文件不存在，手动创建）：

    <script>
      window.$docsify = {
        loadSidebar: true  // 启用自定义侧边栏
      }
    </script>
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

3. 容器启动后访问提示 “404 Not Found”

• 原因 1：./docs 目录为空或无 README.md/index.html。解决：在 ./docs 目录创建 README.md（至少包含一行内容），重启容器。

• 原因 2：端口映射错误（主机端口与容器端口不匹配）。解决：检查 docker-compose.yml 中 ports 配置（如 3000:3000），确保主机端口已开放，访问时使用正确端口。

4. 同步脚本（1.sh）执行失败（提示 “Permission denied”）

• 原因：脚本无执行权限或源目录 / 目标目录权限不足。

  解决： 1. 赋予脚本执行权限：chmod +x 1.sh； 2. 确保源目录（如 Obsidian 目录）和目标目录（./docs）可读写：sudo chmod -R 777 /path/to/source /opt/docsify/docs。

通过以上步骤，新手可快速搭建 Docsify 文档网站，并实现与外部笔记工具的联动。Docsify 轻量灵活，适合个人或小团队快速构建知识库，如需探索更多功能（如主题切换、插件扩展），可参考 Docsify 官方文档。