> ## Documentation Index
> Fetch the complete documentation index at: https://dob.topfde.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 在飞牛 NAS 的 Docker 中运行 Zensical

> 使用官方 Docker 镜像在飞牛 NAS 上预览 Zensical 文档，并按文件夹自动生成导航。

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

**文档版本：** 1.0.0

本指南使用 Zensical 官方 Docker 镜像，在飞牛 NAS 上启动文档预览服务。Zensical 会根据 Markdown 文件夹结构生成侧边栏；不需要把每篇文章逐条写入导航配置。

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

**适用环境：** 已安装并运行 Docker 的飞牛 NAS，且 NAS 可以访问 Docker Hub。

**资料核查：** 2026-11-12 查看 Zensical 官方文档及官方 Docker Hub 镜像信息。官方镜像提供 `linux/amd64` 和 `linux/arm64` 架构；当日 `latest` 标签对应 Zensical 0.1.1。本文尚未在飞牛 NAS 实机验证，实际界面名称可能因 fnOS 版本略有不同。

## 一、准备项目文件

在飞牛文件管理器中创建一个专用目录，例如：

```text theme={null}
/vol1/1000/docker/zensical/site/
├── zensical.toml
└── docs/
    ├── index.md
    ├── docker/
    │   └── sample-app.md
    └── others/
        └── sample-guide.md
```

`/vol1/1000/docker/zensical/site/` 是示例路径。请换成 NAS 上实际存在的共享文件夹路径，并确保 Docker 项目能读取该目录。

在项目根目录创建 `zensical.toml`：

```toml theme={null}
[project]
site_name = "示例知识库"
docs_dir = "docs"
```

在 `docs/index.md` 中写入首页内容；把文章放入对应子文件夹，例如 `docs/docker/` 或 `docs/others/`。每篇文章建议用一级标题 `#` 指定页面标题。

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

打开飞牛系统的 Docker 应用，进入 Compose 或项目管理页面，新建项目并粘贴以下配置：

```yaml theme={null}
services:
  zensical:
    image: zensical/zensical:latest
    container_name: zensical-preview
    ports:
      - "8000:8000"
    volumes:
      - /vol1/1000/docker/zensical/site:/docs
    restart: unless-stopped
```

如果实际项目目录不同，请同时替换 `volumes` 左侧的路径。右侧 `/docs` 是容器内的项目目录，不要修改。

启动项目并等待镜像拉取、容器启动完成。官方镜像默认执行 `zensical serve --dev-addr=0.0.0.0:8000`，因此无需额外填写启动命令。

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

在同一局域网的电脑浏览器打开：

```text theme={null}
http://飞牛NAS的局域网IP:8000
```

例如 NAS 的局域网 IP 是 `192.168.1.20`，就访问 `http://192.168.1.20:8000`。

检查以下内容：

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

Zensical 默认根据文件夹结构和 Markdown 页面生成侧边栏。不要在 `zensical.toml` 中设置 `nav`，否则会改用手动导航配置。图片等非 Markdown 文件不会成为导航页面。

### 按文件名排序

Zensical 的目录导航默认按自然顺序排列。若希望明确指定按文件名升序排列，可以在 `docs/` 下创建 `.nav.yml`：

```yaml theme={null}
sort:
  direction: asc
  type: natural
  by: filename
  sections: first
```

自然排序会让 `app-2.md` 排在 `app-10.md` 前面。文件夹仍作为分组显示，组内文章按文件名排序。若需要严格的字符字母顺序，把 `type` 改为 `alphabetical`。

## 四、停止与更新

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

`latest` 是可变标签。本文核查时它对应 0.1.1；以后拉取时可能获得更新版本。若需复现某次环境，可把镜像标签改为明确版本，例如 `zensical/zensical:0.1.1`。

## 常见问题

### 页面打不开

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

### 页面能打开，但没有文章

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

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

不建议。它是开发预览服务器，不是生产网站服务器。需要公开发布时，应先生成静态文件，再用 Nginx、Cloudflare Pages 或其他正式托管服务发布，并另外配置域名和 HTTPS。

## 官方资料

* [Zensical 官方 Docker 镜像及用法](https://hub.docker.com/r/zensical/zensical)
* [Zensical 预览服务说明](https://zensical.org/docs/usage/preview/)
* [Zensical 导航配置](https://zensical.org/docs/setup/navigation/)
* [Zensical 支持的 Awesome Nav 配置](https://zensical.org/docs/compatibility/mkdocs/plugins/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.