1. 安全架构与核心特性#

Shirone 的文章加密系统与受保护的相册共用同一套安全基础，为静态发布提供了企业级的安全能力：

1. 静态 HTML 构建产物中零明文
   在 Astro SSG 构建流程中，文章 Markdown 会被编译为 HTML，并在输出页面前立即以 AES-256-GCM 加密。发布出去的静态 HTML 中，受保护正文与大纲不含任何明文。

2. 带 AAD 作用域绑定的认证加密

   • 密钥派生遵循 OWASP 建议，使用 310,000 次 PBKDF2 迭代（SHA-256）与一个密码学安全的 16 字节随机盐；
   • 每一份加密载荷都会生成独立的 12 字节随机 IV；
   • 附加认证数据（AAD） 绑定 shirone-protected-content:1:post:${slug}，确保密文无法在不同文章或相册之间被重放。

3. 会话保持与磁盘零密码存储

   • 解密后的内容缓存在浏览器临时会话存储中，30 分钟后过期；
   • 明文密码绝不会写入磁盘或存储；
   • 在同一会话内，解密状态可无缝跨越 Swup 客户端导航与页面刷新。

4. 全站防泄漏

   • 搜索索引：静态页面不含明文，搜索引擎与 Pagefind 都无法索引私密内容；
   • RSS 订阅：受保护文章在订阅源中输出本地化占位内容，避免 RSS 聚合器抓取敏感文本；
   • 卡片摘要与字数：配置 hideHomeContent: true 后，列表页与归档卡片的描述和字数会被遮蔽；
   • 目录（TOC）：解锁前标题层级保持隐藏，解密后再动态重建并与 M3E 样式同步。

💡 演示说明：本篇演示文章的默认解锁密码是 shirone-secret。

2. 交互式富内容演示#

文章解密后会与运行时辅助模块协同，动态挂载语法高亮、代码折叠、可交互的 Mermaid 图表、LaTeX 公式与图片灯箱。

1
import { decryptProtectedContent, type ProtectedPayload } from "@/utils/password-protection";
2

3
/**
4
 * 客户端文章解密示例
5
 */
6
async function unlockArticle(payload: ProtectedPayload, password: string): Promise<string> {
7
    const scope = payload.scope;
8
    console.log(`[Shirone] Decrypting scope: ${scope}`);
9

10
    // 执行带 AAD 校验的 AES-256-GCM 解密
11
    const decryptedHtml = await decryptProtectedContent(payload, password, scope);
12
    console.log("[Shirone] Decryption successful, length:", decryptedHtml.length);
13
    return decryptedHtml;
14
}

1
# 校验构建与类型检查
2
npx.cmd astro check
3
pnpm.cmd type-check
4
pnpm.cmd test

flowchart TD
    subgraph build["构建流水线"]
        A[Markdown 源码] --> B[Astro 流水线]
        B --> C[渲染 HTML]
        C --> D[encryptProtectedContent]
        D --> E[ProtectedPayload]
        E --> F[含 ProtectedPost 的静态 HTML]
    end

    subgraph runtime["客户端运行时"]
        G[读者访问页面] --> H{会话是否有效？}
        H -->|是| K[渲染解密后的 HTML]
        H -->|否| I[显示 PasswordGate]
        I --> J[用户提交密码]
        J --> L[Web Crypto AES-GCM 解密]
        L -->|失败| M[给出错误反馈]
        L -->|成功| N[写入会话记录]
        N --> K
        K --> O[触发解密后协调器]
        O --> P[初始化复制、Mermaid、KaTeX 与目录]
    end

2.5 GitHub 仓库卡片#

withastro/astro

---

3. 配置参考#

4. 小结#

本次演示验证了 Shirone 完整的加密生命周期：静态产物零明文、可靠的密码学校验、会话在导航与刷新之间的持续保持，以及运行时对富内容的动态重建。