设计文档：OpenClaw 镜像文档站点

日期： 2026-04-11 状态： 待实现

---

项目目标

仿照 clawd.org.cn（OpenClaw 中文社区）构建一个独立运营的文档网站。完整复制当前内容，替换品牌信息（Logo、站点名称、联系方式），之后独立维护，不再同步上游。

---

技术栈

层次	技术	版本/说明
文档框架	VitePress	1.x（与原站一致）
前端框架	Vue 3	VitePress 内置
内容格式	Markdown	.md 文件
搜索	VitePress Local Search	本地全文搜索，无外部依赖
构建工具	Vite	VitePress 内置
运行时	Node.js	18+ LTS
Web 服务器	Nginx	静态文件托管
SSL 证书	阿里云免费 SSL	控制台签发，1 年有效期
部署方式	rsync	本机构建后推送到服务器

---

架构设计

整体流程

[本机开发环境]
  ├── git clone OpenClaw 源码
  ├── 修改品牌配置文件
  ├── npm run dev（本地预览）
  └── npm run build → dist/

         ↓ rsync

[阿里云 ECS]
  └── Nginx
        └── /var/www/docs/dist/（静态文件）
              ↑
          域名 + 阿里云 SSL

项目目录结构

克隆后的关键目录：

项目根目录/
├── docs/
│   ├── .vitepress/
│   │   ├── config.ts          ← 站点标题、描述、导航、社交链接
│   │   └── theme/             ← 自定义主题组件（如有）
│   ├── public/
│   │   └── logo.svg           ← 站点 Logo
│   ├── index.md               ← 首页 Hero 区域内容
│   └── **/*.md                ← 所有文档内容（不修改）
└── package.json

---

品牌定制范围

需要修改的文件

文件	修改内容
.vitepress/config.ts	title（站点名称）、description、GitHub 链接、社交链接
docs/public/logo.svg	替换为自己的 Logo 图片
docs/index.md	Hero 区标题、副文案、CTA 按钮链接
联系信息相关页面	社区论坛链接、Discord、GitHub 等联系方式

不修改的内容

• 所有技术文档 Markdown 文件（保持原版内容）
• 页面布局和主题设计
• 侧边栏导航结构
• 本地搜索功能

---

服务器部署设计

服务器环境

• 平台： 阿里云 ECS
• 操作系统： Ubuntu 22.04 LTS（推荐）
• 最低配置： 1 核 1G / 推荐 2 核 2G
• 域名： 已有，指向 ECS 公网 IP

Nginx 配置

server {
    listen 80;
    server_name your-domain.cn www.your-domain.cn;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name your-domain.cn www.your-domain.cn;

    ssl_certificate     /etc/ssl/your-domain.pem;
    ssl_certificate_key /etc/ssl/your-domain.key;

    root /var/www/docs/dist;
    index index.html;

    # VitePress SPA 路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源长缓存
    location ~* \.(js|css|png|svg|ico|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # 压缩
    gzip on;
    gzip_types text/html text/css application/javascript application/json;
}

SSL 证书

使用阿里云控制台免费签发 SSL 证书（有效期 1 年），下载 Nginx 格式证书文件后配置到服务器。到期前手动在控制台续签。

更新流程

每次需要更新内容时：

# 1. 本机构建
npm run build

# 2. 推送到服务器（替换 user 和 your-server-ip）
rsync -avz --delete dist/ user@your-server-ip:/var/www/docs/dist/

# Nginx 无需重启，静态文件自动生效

---

本地开发环境要求

工具	版本	用途
Node.js	18+ LTS	运行 VitePress
npm	随 Node.js	包管理
Git	任意	克隆源码
rsync	任意	推送到服务器

---

不在范围内

• 评论系统 / 社区论坛功能
• 后端 API 或数据库
• CI/CD 自动化构建（手动 rsync 足够）
• 多语言支持（保持中文）
• 用户认证或权限控制

---

成功标准

• [ ] 本地 npm run dev 可正常预览所有页面
• [ ] npm run build 无报错，生成 dist/ 文件夹
• [ ] 上传到 ECS 后，通过域名 + HTTPS 可正常访问
• [ ] 品牌信息（Logo、站名、联系方式）已替换为自定义内容
• [ ] 本地搜索功能正常工作
• [ ] 移动端响应式布局正常