架构设计

了解项目技术栈与整体架构。

技术栈

整体架构

┌─────────────────────────────────┐
│         浏览器 / 用户            │
└───────────┬─────────────────────┘
            │ HTTPS
┌───────────▼─────────────────────┐
│      静态托管平台                 │
│  ┌──────────────────────────┐   │
│  │  dist/                   │   │
│  │  ├── index.html          │   │
│  │  ├── pagefind/           │   │  ← 全文索引
│  │  └── docs/               │   │
│  └──────────────────────────┘   │
└─────────────────────────────────┘

内容管理

采用 文件夹即层级 模式,slug 就是相对 src/content/docs/ 的路径:

src/content/docs/          → /docs/
├── getting-started.mdx    → /docs/getting-started
└── dev/                   → /docs/dev/
    ├── architecture.mdx   → /docs/dev/architecture
    ├── api-reference.mdx  → /docs/dev/api-reference
    └── secret.mdx         → /docs/dev/secret(构建后为密码页)

侧边栏由唯一的 src/content/docs/_meta.ts 定义:

// src/content/docs/_meta.ts
const meta: MetaEntry[] = [
  { label: '快速开始', slug: 'getting-started' },
  {
    label: '开发指南',
    slug: 'dev',
    items: [
      { label: '架构设计', slug: 'dev/architecture' },
      { label: '接口说明', slug: 'dev/api-reference' },
    ],
  },
]

export default meta

构建流程

  1. astro build — .mdx 经 src/pages/docs/[...slug].astro 的 import.meta.glob 渲染为静态 HTML
  2. node scripts/encrypt.mjs — StatiCrypt 用 STATICRYPT_PASSWORD 加密 dist/docs/dev/secret/index.html
  3. pagefind --site dist — 只索引带 data-pagefind-body 的页面(加密页已被替换,且没有该标记)

加密的边界

StatiCrypt 是客户端加密:密文、盐、解密脚本都在静态文件里,密码正确时由浏览器本地解密。它能挡住直接抓取产物的读者,但不是访问控制: