3min手搓一个帮助文档，很合理吧！
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访问; 子文件夹 ./docs/class1.md, 在单页面/docs#/class1访问
一个更常见的组织方式是 侧边栏:
- 编写_sidebar.md文件， 指定md文件的组织和路由
* [快速指南](/ "快速指南") |
* [文生图](text2image.md "文生图") |
* [文生视频](text2video.md "文生视频") |
* [虚拟人素材](assert.md "虚拟人素材") |
* [WorkBuddy接入文档](WorkBuddy.md "WorkBuddy接入文档") |
- 在index.html加载_sidebar.md文件, 注意下面的
loadSideBarbool值
<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宿主服务接入k8s集群
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 路径到帮助文档站
ingress path 路径匹配，默认不rewrite path，为了让帮助文档站所有请求都进入特定的服务。
思路也很清晰：
- 主站域名 +
/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 |
同时我们必须让帮助文档站发出的请求都 带上/docs前缀，那么需要将上面docsify 工作目录下所有的md文件移动到一个docs目录下（index.html 位置不变）。
这样主站/docs路径命中docsify 首页， 首页附带的其他资源因为在docs目录下，发起请求时自然也有/docs前缀，于是由自然而然根据ingress /docs前缀进入后端服务， 完美闭环。