feat: 开源项目门户站首版（iotLCM / 秀杰 DTU / XiuAdmin 三项目，注册表驱动）

2026-11-04 11:08:47 +08:00
commit fe63dacae2
27 changed files with 3786 additions and 0 deletions
@@ -0,0 +1,52 @@
+---
+title: 门户部署
+description: 开源项目门户的构建与部署方式
+outline: deep
+---
+
+# 门户部署
+
+门户是一个独立的 VitePress 工程，产物是纯静态文件。
+
+## 本地构建
+
+```bash
+npm ci
+npm run build
+```
+
+产物在 `.vitepress/dist/`。
+
+## 容器部署
+
+```bash
+docker compose -f deploy/docker-compose.yml up -d --build
+```
+
+默认发布在宿主机 `127.0.0.1:8020`，容器内监听 80。
+
+## 两种路径形态
+
+构建参数 `SITE_BASE` 决定站点资源前缀：
+
+| 形态 | 参数 | 访问方式 |
+| --- | --- | --- |
+| 子路径（过渡形态，无独立域名） | `/www/`（默认） | 挂在已有网关的 `/www/` 路径下 |
+| 独立域名 | `/` | 站点独占域名根路径 |
+
+```bash
+SITE_BASE=/ docker compose -f deploy/docker-compose.yml up -d --build
+```
+
+两者内容完全同源，切换只改构建参数与入口配置，页面不用改。
+
+> VitePress 产物里的资源引用是绝对路径（`<base>assets/xxx`），base 与 nginx 的 location 形态必须配套，混用会出现「页面 200 但 JS/CSS 全 404」的白屏。镜像构建脚本按 `SITE_BASE` 自动选对应的 nginx 配置。
+
+## 新增项目
+
+项目清单由 `data/projects.ts` 单一注册表驱动，新增项目不需要改动站点其它部分：
+
+1. 在注册表里加一条记录
+2. 写 `pages/projects/<id>/index.md` 详情页
+
+构建前会自动校验注册表与详情页目录是否一一对应。