# XR-Cloud-Docs

**Repository Path**: corepillar/XR-Cloud-Docs

## Basic Information

- **Project Name**: XR-Cloud-Docs
- **Description**: VitePress 文档站
- **Primary Language**: Verilog
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-14
- **Last Updated**: 2026-07-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# XR-Cloud-Docs

## 介绍

XR Cloud / XR Cloud 文档中心，基于 Docusaurus 3 构建，承载产品规划、架构说明、部署交付、操作手册、移动端说明、FAQ 与研发入口。

配套代码仓库：

| 仓库 | 说明 |
|---|---|
| `XR-Cloud` | 后端微服务与源文档 |
| `XR-Cloud-Ui` | Web 管理端 |
| `XR-Cloud-Ui-Merge` | 移动端 |
| `XR-Cloud-Docs` | 本知识库 |

完善路线见 `docs/product/knowledge-base-improvement-plan.md`。

能力地图见 `docs/product/platform-capability-map.md`，交付裁剪见 `docs/product/delivery-scope-matrix.md`。

## 技术栈

- Docusaurus 3
- React
- MDX / Markdown

## 本地开发

```bash
pnpm install
pnpm dev
```

开发服务器默认监听 `http://localhost:3000`，文档入口为：

```text
http://localhost:3000/xr-docs/
```

> 站点按子路径 `/xr-docs/` 部署，本地访问请带上该前缀。首页由 `src/pages/index.tsx` 提供，不是 `docs/index.md`。

### 常见问题

- **端口 3000 已被占用**：说明已有文档站进程在跑，直接打开上述地址即可；或执行 `pnpm dev:alt` 使用 3001 端口。
- **首次启动较慢**：本地搜索插件会为全站文档建立索引，属正常现象。
- **不要重复启动**：同一端口重复执行 `pnpm dev` 会卡在交互提示 `(Y/n)`。

## 构建与预览

```bash
pnpm build
pnpm preview
```

`pnpm build` 会校验站内死链（`onBrokenLinks: throw`），合并前建议本地先跑一遍。

## 同步操作手册

> 注意：绝大多数操作手册由本仓库直接维护。`pnpm sync:manual` 仅同步 `scripts/sync-manual.mjs` 中显式声明的少量文件（默认 13 个），其他位于 `docs/manual` 下的页面不会被覆盖或删除。

源文档位于：

```text
../XR-Cloud/docs/manual
```

执行同步：

```bash
pnpm sync:manual
```

如需扩展同步范围，编辑 `scripts/sync-manual.mjs` 中的 `manualMappings` 数组。

## 目录说明

```text
docs
├── guide              # 文档站说明、仓库关系、维护规范
├── product            # 产品规划、能力地图、完善计划
├── architecture       # 架构总览、服务端口
├── deploy             # 部署交付，含移动端多端构建与发布
├── developer          # 研发入口
├── faq                # 跨模块 FAQ / 故障树
├── manual             # 操作手册
│   ├── system
│   ├── iot
│   ├── equipment
│   ├── ai
│   ├── integration
│   ├── xr
│   ├── workflow
│   ├── video
│   ├── monitor
│   ├── operations
│   ├── mobile
│   └── tool
└── public             # 静态资源（logo、favicon、图片等）
src
├── css/custom.css     # Docusaurus 全局样式
└── pages/index.tsx    # 文档站首页
docusaurus.config.ts   # Docusaurus 站点配置
sidebars.ts            # 文档侧边栏配置
```

## 部署

当前按子路径 `/xr-docs/` 部署。如部署路径变化，请调整 `docusaurus.config.ts` 中的 `baseUrl`。

站点域名默认为 `https://docs.xr.cloud`，请按实际部署域名调整 `docusaurus.config.ts` 中的 `url`。

### 服务器一键部署

文档站已迁移为 **Docusaurus**，构建产物在仓库根目录 `build/`，不再是 VitePress 的 `docs/.vitepress/dist`。

```bash
chmod +x scripts/deploy-docs.sh
./scripts/deploy-docs.sh prod
```

若服务器上仍保留旧脚本，请将 `BUILD_DIR` 改为：

```bash
BUILD_DIR="$PROJECT_DIR/build"
```

## 维护说明

- 导航唯一来源：`sidebars.ts`（已从 VitePress 迁移至 Docusaurus，勿再维护 `docs/.vitepress`）。
- 新增手册页面后，需同时在 `sidebars.ts` 中注册条目。
- CI：推送/PR 时会执行 `pnpm audit:docs` 和 `pnpm build`，校验导航完整性、结构审计与死链。