|
| 1 | +# 内容加密功能使用指南 |
| 2 | + |
| 3 | +PPage 提供了强大的内容加密功能,可以保护您的私密内容,只有输入正确密码才能查看。 |
| 4 | + |
| 5 | +## 功能特性 |
| 6 | + |
| 7 | +✨ **核心功能** |
| 8 | + |
| 9 | +- 🔐 AES-256-GCM 加密算法,带盐值处理,确保高安全性 |
| 10 | +- 🔑 密码保护:只有知道密码的用户才能查看加密内容 |
| 11 | +- 🎯 文件夹级别加密:支持对指定文件夹进行批量加密 |
| 12 | +- 🚫 自动隔离:加密内容不参与文档关系图谱和搜索索引 |
| 13 | +- 💾 会话缓存:密码在会话期间保存,刷新后需重新输入 |
| 14 | +- 🎨 友好界面:提供美观的密码输入界面 |
| 15 | + |
| 16 | +## 快速开始 |
| 17 | + |
| 18 | +### 1. 启用加密功能 |
| 19 | + |
| 20 | +编辑 `public/config.yml`,启用加密功能并配置受保护的文件夹: |
| 21 | + |
| 22 | +```yaml |
| 23 | +# 内容加密配置 |
| 24 | +encryption: |
| 25 | + # 启用加密功能 |
| 26 | + enabled: true |
| 27 | + |
| 28 | + # 受保护的文件夹列表 |
| 29 | + protectedFolders: |
| 30 | + - 'content/protected' # 私密内容文件夹 |
| 31 | + - 'content/private' # 可以添加多个 |
| 32 | + |
| 33 | + # 加密内容不参与文档关系图谱和搜索 |
| 34 | + excludeFromGraph: true |
| 35 | + excludeFromSearch: true |
| 36 | +``` |
| 37 | +
|
| 38 | +### 2. 创建受保护的内容 |
| 39 | +
|
| 40 | +在配置的文件夹中创建 Markdown 文件: |
| 41 | +
|
| 42 | +```bash |
| 43 | +mkdir -p content/protected |
| 44 | +echo "--- |
| 45 | +title: 私密笔记 |
| 46 | +date: 2025-01-08 |
| 47 | +--- |
| 48 | + |
| 49 | +# 这是我的私密内容 |
| 50 | + |
| 51 | +这些内容只有知道密码的人才能看到。 |
| 52 | +" > content/protected/my-private-note.md |
| 53 | +``` |
| 54 | +
|
| 55 | +### 3. 加密内容 |
| 56 | +
|
| 57 | +在提交到 git 之前,运行加密脚本: |
| 58 | +
|
| 59 | +```bash |
| 60 | +npm run encrypt |
| 61 | +``` |
| 62 | +
|
| 63 | +脚本会提示您输入加密密码(需要输入两次确认): |
| 64 | +
|
| 65 | +``` |
| 66 | +🔐 内容加密工具 |
| 67 | +================================================== |
| 68 | +
|
| 69 | +📁 受保护的文件夹: content/protected |
| 70 | +
|
| 71 | +找到 3 个文件 |
| 72 | +
|
| 73 | +🔑 请输入加密密码: ****** |
| 74 | +🔑 请再次输入密码以确认: ****** |
| 75 | +
|
| 76 | +🔒 开始加密文件... |
| 77 | + ✅ 加密成功: content/protected/my-private-note.md |
| 78 | + ✅ 加密成功: content/protected/diary.md |
| 79 | + ✅ 加密成功: content/protected/thoughts.md |
| 80 | +
|
| 81 | +================================================== |
| 82 | +📊 加密完成! |
| 83 | + ✅ 成功: 3 个 |
| 84 | + ⏭️ 跳过: 0 个 |
| 85 | + ❌ 失败: 0 个 |
| 86 | +
|
| 87 | +✨ 所有文件加密成功!现在可以提交到 git 了。 |
| 88 | +``` |
| 89 | +
|
| 90 | +### 4. 提交加密后的内容 |
| 91 | +
|
| 92 | +```bash |
| 93 | +git add content/protected |
| 94 | +git commit -m "Add encrypted content" |
| 95 | +git push |
| 96 | +``` |
| 97 | + |
| 98 | +### 5. 查看加密内容 |
| 99 | + |
| 100 | +当访问加密的内容时,页面会自动弹出密码输入框: |
| 101 | + |
| 102 | +- 输入正确的密码即可解锁内容 |
| 103 | +- 密码在会话期间保存,无需重复输入 |
| 104 | +- 刷新页面后需要重新输入密码 |
| 105 | + |
| 106 | +## 工作原理 |
| 107 | + |
| 108 | +### 加密流程 |
| 109 | + |
| 110 | +1. **本地加密** |
| 111 | + - 使用 `npm run encrypt` 命令 |
| 112 | + - 读取配置的受保护文件夹 |
| 113 | + - 使用 AES-256-GCM 算法加密内容 |
| 114 | + - 每次加密使用随机盐值和 IV,确保安全性 |
| 115 | + - 加密后的内容保存在原文件中,带有特殊标记 |
| 116 | + |
| 117 | +2. **Git 提交** |
| 118 | + - 加密后的文件可以安全地提交到公开仓库 |
| 119 | + - 即使代码公开,内容也无法被解密 |
| 120 | + |
| 121 | +3. **构建部署** |
| 122 | + - 加密的文件正常参与构建 |
| 123 | + - 生成的网站包含加密内容 |
| 124 | + |
| 125 | +4. **访问解密** |
| 126 | + - 用户访问加密内容时自动检测 |
| 127 | + - 弹出密码输入框 |
| 128 | + - 输入正确密码后在浏览器中解密 |
| 129 | + - 密码存储在 sessionStorage,刷新后失效 |
| 130 | + |
| 131 | +### 安全机制 |
| 132 | + |
| 133 | +- **AES-256-GCM**:业界标准的加密算法 |
| 134 | +- **PBKDF2**:密钥派生函数,增加暴力破解难度(100,000 次迭代) |
| 135 | +- **随机盐值**:每次加密使用不同的盐值,防止彩虹表攻击 |
| 136 | +- **认证标签**:确保数据完整性,防止篡改 |
| 137 | +- **会话缓存**:密码不持久化存储,更加安全 |
| 138 | + |
| 139 | +## 文件结构 |
| 140 | + |
| 141 | +加密后的 Markdown 文件结构: |
| 142 | + |
| 143 | +```markdown |
| 144 | +--- |
| 145 | +title: 私密笔记 |
| 146 | +date: 2025-01-08 |
| 147 | +encrypted: true |
| 148 | +encryptedAt: '2025-01-08T12:00:00.000Z' |
| 149 | +--- |
| 150 | + |
| 151 | +<!-- ENCRYPTED_CONTENT --> |
| 152 | + |
| 153 | +base64编码的加密内容... |
| 154 | + |
| 155 | +<!-- /ENCRYPTED_CONTENT --> |
| 156 | +``` |
| 157 | + |
| 158 | +## 最佳实践 |
| 159 | + |
| 160 | +### 密码管理 |
| 161 | + |
| 162 | +1. **使用强密码** |
| 163 | + - 至少 12 位字符 |
| 164 | + - 包含大小写字母、数字和特殊字符 |
| 165 | + - 不要使用常见密码 |
| 166 | + |
| 167 | +2. **密码分享** |
| 168 | + - 通过安全渠道分享密码(如加密通讯软件) |
| 169 | + - 避免通过邮件或公开渠道发送 |
| 170 | + |
| 171 | +3. **定期更新** |
| 172 | + - 定期更换密码 |
| 173 | + - 重新加密所有文件 |
| 174 | + |
| 175 | +### 内容组织 |
| 176 | + |
| 177 | +1. **文件夹分类** |
| 178 | + |
| 179 | + ``` |
| 180 | + content/ |
| 181 | + ├── posts/ # 公开博客 |
| 182 | + ├── pages/ # 公开页面 |
| 183 | + └── protected/ # 加密内容 |
| 184 | + ├── diary/ # 日记 |
| 185 | + ├── notes/ # 笔记 |
| 186 | + └── drafts/ # 草稿 |
| 187 | + ``` |
| 188 | + |
| 189 | +2. **使用多个密码** |
| 190 | + - 可以为不同文件夹使用不同密码 |
| 191 | + - 需要多次运行 `npm run encrypt` |
| 192 | + |
| 193 | +### 备份建议 |
| 194 | + |
| 195 | +1. **保留原始文件** |
| 196 | + - 加密前备份原始文件到本地 |
| 197 | + - 不要将原始文件提交到 git |
| 198 | + |
| 199 | +2. **密码备份** |
| 200 | + - 将密码安全存储(如密码管理器) |
| 201 | + - 确保不会忘记密码 |
| 202 | + |
| 203 | +## 常见问题 |
| 204 | + |
| 205 | +### Q: 忘记密码怎么办? |
| 206 | + |
| 207 | +A: 如果忘记密码,加密的内容将无法解密。建议: |
| 208 | + |
| 209 | +- 从本地备份恢复原始文件 |
| 210 | +- 重新设置新密码并加密 |
| 211 | + |
| 212 | +### Q: 可以使用不同密码吗? |
| 213 | + |
| 214 | +A: 可以。您可以: |
| 215 | + |
| 216 | +- 为不同的文件夹配置不同的受保护路径 |
| 217 | +- 分别运行加密脚本并使用不同密码 |
| 218 | +- 用户访问时需要输入对应的密码 |
| 219 | + |
| 220 | +### Q: 加密内容会被搜索引擎收录吗? |
| 221 | + |
| 222 | +A: 不会。加密的内容: |
| 223 | + |
| 224 | +- 以密文形式存储 |
| 225 | +- 搜索引擎无法解析内容 |
| 226 | +- 即使收录也只是乱码 |
| 227 | + |
| 228 | +### Q: 性能影响如何? |
| 229 | + |
| 230 | +A: 解密操作在浏览器中完成: |
| 231 | + |
| 232 | +- 现代浏览器性能良好 |
| 233 | +- 解密通常在 100ms 内完成 |
| 234 | +- 只在首次访问时需要输入密码 |
| 235 | + |
| 236 | +### Q: 可以在手机上查看吗? |
| 237 | + |
| 238 | +A: 可以。加密功能完全支持移动设备: |
| 239 | + |
| 240 | +- 响应式密码输入界面 |
| 241 | +- 在移动浏览器中正常解密 |
| 242 | +- 会话缓存在移动端也有效 |
| 243 | + |
| 244 | +## 技术细节 |
| 245 | + |
| 246 | +### 加密算法参数 |
| 247 | + |
| 248 | +- **算法**: AES-256-GCM |
| 249 | +- **密钥长度**: 256 bits (32 bytes) |
| 250 | +- **IV 长度**: 128 bits (16 bytes) |
| 251 | +- **盐值长度**: 512 bits (64 bytes) |
| 252 | +- **认证标签**: 128 bits (16 bytes) |
| 253 | +- **PBKDF2 迭代次数**: 100,000 |
| 254 | + |
| 255 | +### 数据格式 |
| 256 | + |
| 257 | +加密数据结构(Base64 编码前): |
| 258 | + |
| 259 | +``` |
| 260 | +[Salt (64 bytes)] + [IV (16 bytes)] + [Auth Tag (16 bytes)] + [Encrypted Data] |
| 261 | +``` |
| 262 | + |
| 263 | +### 浏览器兼容性 |
| 264 | + |
| 265 | +需要浏览器支持: |
| 266 | + |
| 267 | +- Web Crypto API |
| 268 | +- SessionStorage API |
| 269 | +- ES6+ JavaScript |
| 270 | + |
| 271 | +支持的浏览器: |
| 272 | + |
| 273 | +- Chrome 60+ |
| 274 | +- Firefox 57+ |
| 275 | +- Safari 11+ |
| 276 | +- Edge 79+ |
| 277 | + |
| 278 | +## 相关文件 |
| 279 | + |
| 280 | +- `scripts/crypto.js` - 加密/解密核心算法(Node.js) |
| 281 | +- `scripts/encrypt.js` - 加密脚本(CLI) |
| 282 | +- `src/utils/encryption.js` - 前端解密工具 |
| 283 | +- `src/components/common/PasswordPrompt.jsx` - 密码输入组件 |
| 284 | +- `src/components/common/ProtectedContent.jsx` - 受保护内容组件 |
| 285 | + |
| 286 | +## 许可证 |
| 287 | + |
| 288 | +此功能是 PPage 项目的一部分,遵循项目的开源许可证。 |
| 289 | + |
| 290 | +## 贡献 |
| 291 | + |
| 292 | +欢迎提交 Issue 和 Pull Request 来改进加密功能! |
0 commit comments