架构设计
了解项目技术栈与整体架构。
技术栈
- 框架: 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
构建流程
- 确认构建环境已设置
STATICRYPT_PASSWORD。 - 用 Astro 将 MDX 渲染为静态 HTML。
- 用 StatiCrypt 加密
dist/docs/dev/secret/index.html。 - 用 Pagefind 索引带
data-pagefind-body的公开正文。 - 检查密码页能否正确解密,并核对搜索索引收录的页面。
加密的边界
StatiCrypt 将密文和解密脚本置于静态页面,浏览器在输入正确密码后恢复正文。构建密码通过环境变量或本地 .env 提供。源文件 src/content/docs/dev/secret.mdx 在仓库中以明文保存。需要限制访问的资料应保存在具备访问控制的系统中。