架构设计

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

技术栈

  • 框架: Astro 7
  • 内容: MDX(import.meta.glob 路由 + _meta.ts 侧边栏)
  • 搜索: Pagefind(构建期索引)
  • 加密: StatiCrypt(客户端 AES,单页)
  • 构建: SSG → dist/
  • 部署: Vercel / Netlify / Cloudflare Pages

整体架构

┌─────────────────────────────────┐
│         浏览器 / 用户            │
└───────────┬─────────────────────┘
            │ 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. 确认构建环境已设置 STATICRYPT_PASSWORD。
  2. 用 Astro 将 MDX 渲染为静态 HTML。
  3. 用 StatiCrypt 加密 dist/docs/dev/secret/index.html。
  4. 用 Pagefind 索引带 data-pagefind-body 的公开正文。
  5. 检查密码页能否正确解密,并核对搜索索引收录的页面。

加密的边界

StatiCrypt 将密文和解密脚本置于静态页面,浏览器在输入正确密码后恢复正文。构建密码通过环境变量或本地 .env 提供。源文件 src/content/docs/dev/secret.mdx 在仓库中以明文保存。需要限制访问的资料应保存在具备访问控制的系统中。