---
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` 详情页

构建前会自动校验注册表与详情页目录是否一一对应。