跳转至

2026-01-31 知识库系统部署记录

记录类型: 系统部署
记录时间: 2026-01-31 17:38 UTC
执行者: King (AI助理)
状态: ✅ 已完成

部署背景

问题识别

  1. 旧系统问题: Wiki.js存在路由和访问问题，页面无法正常访问
  2. AI友好性: Wiki.js对AI助手操作不够友好，需要复杂API交互
  3. 维护复杂度: 动态系统需要数据库和维护，复杂度较高

解决方案选择

选择 MkDocs + Material主题 作为替代方案： - 纯静态网站，无需数据库 - 纯Markdown文件，AI可直接操作 - 部署简单，性能优秀 - 功能丰富（搜索、多主题、代码高亮等）

详细部署流程

第一阶段：系统清理（17:25 UTC）

# 停止并删除旧系统
docker stop wiki-js
docker rm wiki-js

# 清理Caddy配置中的Wiki.js相关设置

第二阶段：环境准备（17:25-17:28 UTC）

# 安装Python虚拟环境
apt-get install -y python3.12-venv

# 创建虚拟环境并安装MkDocs
python3 -m venv /opt/mkdocs-venv
/opt/mkdocs-venv/bin/pip install mkdocs mkdocs-material mkdocs-material-extensions

# 创建MkDocs项目
mkdocs new waimaosoho-docs

第三阶段：系统配置（17:28-17:30 UTC）

  1. MkDocs配置 (mkdocs.yml):
  2. 设置中文语言支持
  3. 配置Material主题

  4. 创建初始导航结构

  5. Caddy配置 (/etc/caddy/Caddyfile): 

    https://waimaosoho.icu {
    encode gzip
    basicauth /* {
        roger $2y$05$FxTVc9v7H0gp5R11mBajrexnlUy0r7/2SbOPygixxOx6PO.UnNIwS
    }

    # 静态文件服务
    route /docs* {
        root * /var/www/waimaosoho-docs
        file_server
    }

    # 根路径重定向
    @root { path / }
    redir @root /docs
}

  6. 权限配置: 

    mkdir -p /var/www/waimaosoho-docs
chown -R caddy:caddy /var/www/waimaosoho-docs

第四阶段：内容创建（17:30-17:33 UTC）

  1. 创建首页 (docs/index.md):
  2. 网站欢迎页面

  3. 车辆翻新标准介绍

  4. 创建详细文档:

  5. 车辆翻新概述
  6. 驾驶室翻新标准

  7. 发动机翻新标准

  8. 首次构建部署: 

    mkdocs build
cp -r site/* /var/www/waimaosoho-docs/

第五阶段：问题修正（17:37 UTC）

用户反馈问题: 1. 文档结构过于复杂（拆分成多个子文档） 2. 网站无法正常访问

修正措施: 1. 文档结构简化: - 创建 vehicle-renovation-standards.md 单页文档 - 包含完整的原始车辆翻新标准（8个部分） - 简化导航结构

  1. 配置更新: 

    nav:
  - 首页: index.md
  - 车辆翻新标准: vehicle-renovation-standards.md

  2. 重新部署验证: 

    mkdocs build
cp -r site/* /var/www/waimaosoho-docs/
chown -R caddy:caddy /var/www/waimaosoho-docs

# 验证访问
curl -k --user roger:Qq3491692218. https://waimaosoho.icu/docs/

第六阶段：最终验证（17:38 UTC）

✅ 验证通过: - 首页可正常访问 - 车辆翻新标准页面显示完整内容 - 所有8个部分标准正确显示

最终部署成果

1. 系统架构

用户请求 → Caddy反向代理 → 基本认证 → 静态文件服务 → MkDocs网站

2. 访问信息

  • 主地址: https://waimaosoho.icu/docs/
  • 车辆翻新标准: https://waimaosoho.icu/docs/vehicle-renovation-standards/
  • 认证: 用户名 roger，密码 Qq3491692218.

3. 文件结构

/root/.openclaw/workspace/waimaosoho-docs/  # MkDocs项目
├── mkdocs.yml                             # 配置文件
├── docs/                                  # 文档源文件
│   ├── index.md                          # 首页
│   └── vehicle-renovation-standards.md   # 车辆翻新标准
└── site/                                 # 生成的静态网站

/var/www/waimaosoho-docs/                  # Web服务目录

4. 自动化工具

创建部署脚本 /root/.openclaw/workspace/deploy-mkdocs.sh: 

#!/bin/bash
cd /root/.openclaw/workspace/waimaosoho-docs
/opt/mkdocs-venv/bin/mkdocs build
cp -r site/* /var/www/waimaosoho-docs/
chown -R caddy:caddy /var/www/waimaosoho-docs

经验总结

成功经验

  1. 技术选型正确: MkDocs比Wiki.js更适合文档类知识库
  2. 响应迅速: 用户反馈后15分钟内完成修正
  3. 自动化程度高: 创建了可重复的部署脚本

改进点

  1. 需求确认: 应该先确认用户对文档结构的期望
  2. 即时验证: 部署后应立即验证内容和访问
  3. 备份机制: 需要建立文档备份流程

后续维护计划

1. 内容更新流程

用户指令 → AI修改Markdown → 运行部署脚本 → 网站更新

2. 监控项目

  • 网站可访问性
  • 证书有效期
  • 磁盘空间使用

3. 扩展计划

  • 添加业务流程文档
  • 添加客户管理文档
  • 设置定期备份机制

部署总耗时: 约13分钟（从开始到最终修正完成）
系统状态: 正常运行
记录更新时间: 2026-01-31 17:43 UTC