在飞牛 NAS 的 Docker 中运行 Zensical

本文中由 Jeff Wang（Cloud Unfold Studio）创作的原创内容采用 CC BY 4.0 许可，可用于商业转载和改编；使用时请注明作者、本文标题和来源链接，并说明是否修改。第三方文字、代码、图片、商标等不在本许可范围内，请遵循各自权利说明。

用途说明： Zensical 镜像默认运行的 serve 是预览服务，官方说明它不适合正式托管网站。本指南用于在局域网中试用和预览文档。正式发布时，请用 build 生成静态网站文件，再交给正式的网站服务器托管。

​

一、准备项目文件

/vol1/1000/docker/zensical/site/
├── zensical.toml
└── docs/
    ├── index.md
    ├── docker/
    │   └── sample-app.md
    └── others/
        └── sample-guide.md

[project]
site_name = "示例知识库"
docs_dir = "docs"

​

二、在飞牛 Docker 中创建 Compose 项目

services:
  zensical:
    image: zensical/zensical:latest
    container_name: zensical-preview
    ports:
      - "8000:8000"
    volumes:
      - /vol1/1000/docker/zensical/site:/docs
    restart: unless-stopped

​

三、打开页面并检查自动目录

http://飞牛NAS的局域网IP:8000

1. 首页是否显示 docs/index.md 的内容。
2. 侧边栏是否按 docker/、others/ 等子文件夹分组。
3. 新增一个 Markdown 文件并保存后，页面是否自动重新生成并出现对应导航项。

​

按文件名排序

sort:
  direction: asc
  type: natural
  by: filename
  sections: first

​

四、停止与更新

• 暂停预览服务：在飞牛 Docker 项目页面停止 zensical-preview。
• 恢复预览服务：重新启动该容器。
• 更新镜像：在 Docker 项目页面拉取 zensical/zensical:latest 并重新创建容器。更新前确认文档目录仍通过卷挂载到 /docs。

​

常见问题

​

页面打不开

• 确认容器状态为运行中。
• 确认访问的是 NAS 的局域网 IP 和端口 8000。
• 如果端口已被占用，可以只改 Compose 左侧主机端口，例如 18000:8000，之后访问 http://NAS局域网IP:18000。
• 检查飞牛防火墙是否允许局域网设备访问该端口。

​

页面能打开，但没有文章

• 检查卷挂载左侧路径是否为项目目录，也就是包含 zensical.toml 的目录。
• 检查 Markdown 文件是否放在 docs/ 子目录中。
• 检查配置文件中是否没有设置 nav。
• 查看容器日志中的配置或文件路径错误。

​

能否把这个预览服务直接公开到互联网？

​

官方资料

• Zensical 官方 Docker 镜像及用法
• Zensical 预览服务说明
• Zensical 导航配置
• Zensical 支持的 Awesome Nav 配置