DOC-SITE 部署与访问控制

版本: v1.0
日期: 2026-02-12

一、公网访问

DOC-SITE 为静态 HTML 站点，可部署至公网，通过以下方式访问：

注意：部署后默认无认证，任何人可访问全部文档。

二、访问控制与密码保护

2.1 核心文档不对外公开

以下文档视为核心/内部文档，不得在公网无密码保护下暴露：

2.2 公开构建模式（排除核心文档）

构建时设置环境变量，可生成不含核心文档的公开版本：

# Windows PowerShell
$env:DOCS_SITE_PUBLIC_MODE = "1"
npm run docs:build

# Linux / macOS
DOCS_SITE_PUBLIC_MODE=1 npm run docs:build

公开模式下，以下内容将不包含在 docs-site/ 输出中：

• docs/business/ 下所有文档
• 匹配 *IMPLEMENTATION_PLAN* 的文档
• 匹配 *_ANALYSIS* 的文档（如 MBE_VS_CLAUDE_DOCS_GAP_ANALYSIS）
• 可通过 DOCS_SITE_PUBLIC_EXCLUDE 追加排除规则（逗号分隔 glob）

2.3 密码保护（全站或分支）

部署后需限制访问时，推荐在托管层添加密码保护：

Nginx 示例（对 docs-site 目录启用 Basic Auth）：

location /docs-site {
    alias /var/www/docs-site;
    auth_basic "MBE 文档中心";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

生成 .htpasswd：htpasswd -c .htpasswd 用户名

三、Cloudflare Pages 部署

3.1 Git 集成（推送到分支自动构建）

1. 在 Cloudflare Dashboard → Pages → Create project → Connect to Git
2. 选择 Mises 仓库，配置：

3. 构建完成后，访问 https://<project-name>.pages.dev

3.2 直接上传（Wrangler CLI）

本地构建后上传：

cd <Mises 项目根目录>   # 如 d:\Mises (Windows) 或 /path/to/Mises
npm run docs:build
npx wrangler pages deploy docs-site --project-name=mbe-docs

首次需在 Cloudflare Dashboard 创建 Pages 项目，或使用 --project-name 自动创建。

3.3 密码保护（Cloudflare Access）

Cloudflare Pages 自身无内置密码，需配合 Cloudflare Access：

1. Zero Trust Dashboard → Access → Applications → Add an application
2. 选择 Self-hosted，域名填 https://<project-name>.pages.dev
3. 创建 One-time PIN 或 Email 策略，添加允许的邮箱

免费版支持最多 50 个用户。

四、推荐部署流程

公开站点（不含核心文档）

1. 设置 DOCS_SITE_PUBLIC_MODE=1
2. 运行 npm run docs:build
3. 将 docs-site/ 部署至 Netlify / GitHub Pages 等
4. 无需密码，仅包含公开文档

内部站点（含核心文档 + 密码）

1. 不设置 DOCS_SITE_PUBLIC_MODE，运行 npm run docs:build
2. 将 docs-site/ 部署至 Netlify（或自建 Nginx）
3. 在 Netlify 开启 Password protection
4. 或在 Nginx 配置 auth_basic

五、代码位置