3分钟手搓一个精美的帮助文档站，不过分吧！

有态度的马甲

发布于 2026-06-24 13:56:54

1050

文章被收录于专栏：精益码农精益码农

最近在加班加点的做一个Token工厂[1], 模式类似与京东：有自营算力产生的模型，也外接第三方旗舰模型。作为Token聚合分发平台，帮助文档是刚性需求。

Docsify[2]是一个将Markdown文件转换为单页面静态网站(无需任何构建过程)的开源项目，实测下来3min就能构建并搭建一个帮助文档站点。

1. Docsify小试牛刀

前置安装环境： npm i docsify-cli -g 安装docsify cli客户端；

初始化项目目录： docsify init . ，这会在当前目录下创建工作目录，默认有：

index.html : 整站是一个单页面静态页面
README.md：默认的主页
.nojekyll：防止GitHub Pages忽略以下划线开头的文件

接下来docsify serve ./ 就启动并在localhost:3000部署了这个帮助文档站点，文档内容来自README.md文件，默认绿色主题深得我心，吾与城北徐公孰美？

2. Docsify羽翼丰满

现在可以写更多的markdown文件： eg: guide.md, 在单页面/#/guide访问;

一个更常见的组织方式是侧边栏:

编写_sidebar.md文件，指定md文件的组织和路由

* [快速指南](/ "快速指南")
* [文生图](text2image.md "文生图")
* [文生视频](text2video.md "文生视频")
* [虚拟人素材](assert.md "虚拟人素材")
* [WorkBuddy接入文档](WorkBuddy.md "WorkBuddy接入文档")

在index.html加载_sidebar.md文件, 注意下面的loadSideBar bool值

 <script>
    window.$docsify = {
      name: '',
      repo: '',
      loadSidebar: true,
      subMaxLevel: 2
    }
  </script>

3. Docsify固若金汤

一般会使用systemd服务进程来部署Docsify，具备进程管理和重试能力。

sudo vim  /etc/systemd/system/docsify.service

[Unit]
Description=docsify Service
After=network.target

[Service]
Type=simple
User=你的用户名
WorkingDirectory={help-docs的工作目录}
ExecStart=/usr/local/bin/docsify serve ./
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload sudo systemctl enable docsify # 设置开机自启 sudo systemctl start docsify

4. Docsify黑魔法时代

Token工厂项目是k8s部署，已经配上了带ssl证书的域名，本次希望将这个Docsify宿主机服务快速接入k8s集群，走主站的/docs 路径到帮助文档站，同时利用k8s集群上配置好的证书，走正规军路线。

k8s如何接入宿主机服务？

将这个宿主机服务，抽象为k8s服务，但是需要走自定义endpoint模式。

apiVersion: v1
kind: Service
metadata:
  name: external-docs-svc        # 服务名，可自定义
  namespace: tokenhub
spec:
  ports:
    - port: 3000                 
      targetPort: 3000           
---
apiVersion: v1
kind: Endpoints
metadata:
  name: external-docs-svc        # 必须与 Service 同名
  namespace: tokenhub
subsets:
  - addresses:
      - ip: 10.8.65.1            # 外部进程的 IP
    ports:
      - port: 3000

配置ingress规则：主站走/docs 路径到帮助文档站

思路也很清晰：

主站走/docs路径到帮助文档站；后端服务不需要/docs前缀
主站走/路径到主站服务；

于是

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: tokenhub-ingress
  namespace: tokenhub
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/hsts: "true"
    nginx.ingress.kubernetes.io/hsts-max-age: "31536000"
    # 如果后端期望不带 /docs 前缀，可取消下面注释
    # nginx.ingress.kubernetes.io/rewrite-target:  /$2
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - tokengine.hanyoai.com
      secretName: tokenhub-tls
  rules:
    - host: tokengine.hanyoai.com
      http:
        paths:
          - path: /docs
            pathType: Prefix
            backend:
              service:
                name: external-docs-svc   # 指向上一步创建的 Service
                port:
                  number: 3000
          - path: /
            pathType: Prefix
            backend:
              service:
                name: new-api
                port:
                  number: 3000

但实际上会有问题，帮助文档站虽然是单页面，但是会有许多资源请求。

上面的ingress规则，会让/docs路径命中帮助文档站首页，但是页面上其他资源不感知docs，发起的请求不会带上docs，那么就会走向下面的主站路由，这就不是预期的显示。

所以此时我们必须让帮助文档站发出的请求都带上/docs前缀，那么需要将上面docsify 工作目录下所有的md文件移动到一个docs目录下（index.html 位置不变）。

这样主站/docs路径命中docsify 首页，首页附带的其他资源因为在docs目录下，发起请求时自然也有/docs前缀，于是又自然而然根据ingress /docs前缀进入帮助文档后端服务，完美闭环。

参考资料

[1] Token工厂: https://tokengine.hanyoai.com

[2] Docsify: https://docsify.js.org/#/quickstart

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2026-06-16，如有侵权请联系 cloudcommunity@tencent.com 删除

进程