麦瓣健康文档站点使用说明

✅ 部署完成

VuePress 文档站点已成功搭建！

🌐 访问地址

本地访问: http://localhost:8082

注意: 由于端口 8080 和 8081 被占用,VuePress 自动选择了 8082 端口

📁 文档结构

docs/
├── .vuepress/              # VuePress 配置
│   ├── config.ts          # 主配置文件(导航、侧边栏等)
│   ├── client.ts          # 客户端配置
│   └── public/            # 静态资源目录
│       └── images/        # 图片资源
├── guide/                 # 📖 使用指南
│   ├── introduction.md    # 项目介绍
│   ├── quick-start.md     # 快速开始
│   └── directory-structure.md  # 目录结构
├── architecture/          # 🏗️ 架构设计
│   ├── overview.md        # 架构概览
│   ├── tech-stack.md      # 技术栈详解
│   ├── microservices.md   # 微服务架构
│   ├── database.md        # 数据库设计
│   └── security.md        # 安全设计
├── features/              # 🎯 功能文档
│   ├── overview.md        # 功能概览
│   ├── user-app.md        # 用户端功能
│   ├── nurse-app.md       # 技师端功能
│   └── admin.md           # 后台管理功能
├── dev/                   # 💻 开发指南
│   ├── environment.md     # 环境配置
│   ├── local-development.md  # 本地开发
│   ├── api-docs.md        # API 文档
│   ├── code-standards.md  # 代码规范
│   └── testing.md         # 测试指南
├── deploy/                # 🚀 运维部署
│   ├── docker.md          # Docker 部署
│   ├── kubernetes.md      # Kubernetes 部署
│   ├── monitoring.md      # 监控告警
│   └── troubleshooting.md # 故障排查
├── README.md              # 文档首页
├── package.json           # NPM 配置
└── DOCS_README.md         # 文档维护说明

🚀 常用命令

启动开发服务器

cd /root/maiban/docs
npm run dev

访问: http://localhost:8082

构建静态文件

npm run build

构建产物在 .vuepress/dist 目录

清理缓存

npm run clean

✨ 功能特性

1. 美观的界面

  • 基于 VuePress 默认主题
  • 响应式设计,支持移动端
  • 深色模式支持

2. 强大的导航

  • 顶部导航栏: 快速访问各个章节
  • 侧边栏: 章节内细分导航
  • 搜索功能: 全站内容搜索

3. 丰富的功能

  • Markdown 增强语法
  • 代码高亮
  • 自定义容器(提示、警告等)
  • 自动生成目录

📝 编写文档

Markdown 扩展语法

提示框

::: tip 提示
这是一个提示信息
:::

::: warning 警告
这是一个警告信息
:::

::: danger 危险
这是一个危险警告
:::

代码块

\`\`\`java
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}
\`\`\`

链接引用

[快速开始](./guide/quick-start.md)
[技术架构](./architecture/tech-stack.md)

🔧 自定义配置

修改导航栏

编辑 .vuepress/config.ts 中的 navbar 配置:

navbar: [
  { text: '首页', link: '/' },
  { text: '快速开始', link: '/guide/quick-start' },
  // 添加更多导航项...
]

修改侧边栏

编辑 .vuepress/config.ts 中的 sidebar 配置:

sidebar: {
  '/guide/': [
    {
      text: '指南',
      children: [
        '/guide/introduction',
        '/guide/quick-start',
      ],
    },
  ],
}

将 logo 图片放到 .vuepress/public/images/ 目录,然后在配置中引用:

theme: defaultTheme({
  logo: '/images/logo.png',
})

📦 部署方案

方案一: GitHub Pages

  1. 配置 GitHub Actions
  2. 推送代码自动部署

方案二: 自建服务器

# 构建
npm run build

# 使用 Nginx 部署
cp -r .vuepress/dist/* /var/www/html/docs/

方案三: Vercel/Netlify

直接连接 GitHub 仓库,自动部署

🎨 主题定制

VuePress 支持自定义主题,可以:

  • 修改颜色方案
  • 自定义布局
  • 添加插件
  • 扩展功能

📚 文档内容

当前已包含以下文档:

使用指南

  • ✅ 项目介绍
  • ✅ 快速开始(5分钟上手)
  • ✅ 目录结构说明

架构设计

  • ✅ 系统架构概览
  • ✅ 技术栈详解
  • ✅ 微服务架构设计
  • ✅ 数据库设计规范
  • ✅ 安全设计方案

开发指南

  • ✅ 环境配置
  • ✅ 本地开发指南
  • ✅ API 文档说明
  • ✅ 代码规范
  • ✅ 测试指南

运维部署

  • ✅ Docker 部署方案
  • ✅ Kubernetes 部署方案
  • ✅ 监控告警配置
  • ✅ 故障排查指南

🔗 相关链接

  • VuePress 官方文档: https://v2.vuepress.vuejs.org/zh/
  • 项目 GitHub: https://github.com/qianmai-healthy/maiban-center
  • API 文档: http://localhost:8080/doc.html

💡 提示

  1. 自动热更新: 修改 Markdown 文件后,浏览器会自动刷新
  2. 链接检查: 启动时会检查文档中的断链
  3. 图片资源: 建议放在 .vuepress/public/images/ 目录
  4. 性能优化: 大型文档建议分页或使用懒加载

❓ 常见问题

1. 端口被占用

VuePress 会自动尝试其他端口(8081, 8082...)

2. 样式不生效

运行 npm run clean 清理缓存

3. 构建失败

检查 Node.js 版本(建议 18+)

node -v
npm -v

📧 技术支持

如有问题或建议,请联系:

  • 邮箱: support@maiban-health.com
  • GitHub Issues: https://github.com/qianmai-healthy/maiban-center/issues

麦瓣健康技术团队 ❤️ 制作

最后更新: 2025-10-18