From f673a4914eab80c37fc71cdde57f2595b382a10c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 7 Dec 2025 05:47:38 +0000
Subject: [PATCH] Add comprehensive documentation for playground access control

Co-authored-by: qaiu <29825328+qaiu@users.noreply.github.com>
---
 README.md                                    |   2 +
 web-service/doc/PLAYGROUND_ACCESS_CONTROL.md | 293 +++++++++++++++++++
 2 files changed, 295 insertions(+)
 create mode 100644 web-service/doc/PLAYGROUND_ACCESS_CONTROL.md

diff --git a/README.md b/README.md
index 5f4f7a9..92f1616 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,8 @@ https://nfd-parser.github.io/nfd-preview/preview.html?src=https%3A%2F%2Flz.qaiu.
 
 **JavaScript解析器文档：** [JavaScript解析器开发指南](parser/doc/JAVASCRIPT_PARSER_GUIDE.md) | [自定义解析器扩展指南](parser/doc/CUSTOM_PARSER_GUIDE.md) | [快速开始](parser/doc/CUSTOM_PARSER_QUICKSTART.md)
 
+**Playground访问控制：** [配置指南](web-service/doc/PLAYGROUND_ACCESS_CONTROL.md) - 了解如何配置演练场的访问权限
+
 ## 预览地址  
 [预览地址1](https://lz.qaiu.top)  
 [预览地址2](https://lzzz.qaiu.top)  
diff --git a/web-service/doc/PLAYGROUND_ACCESS_CONTROL.md b/web-service/doc/PLAYGROUND_ACCESS_CONTROL.md
new file mode 100644
index 0000000..82af264
--- /dev/null
+++ b/web-service/doc/PLAYGROUND_ACCESS_CONTROL.md
@@ -0,0 +1,293 @@
+# Playground 访问控制配置指南
+
+## 概述
+
+Playground 演练场是一个用于编写、测试和发布 JavaScript 解析脚本的在线开发环境。为了提升安全性，现在支持灵活的访问控制配置。
+
+## 配置说明
+
+在 `web-service/src/main/resources/app-dev.yml` 文件中添加以下配置：
+
+```yaml
+# Playground演练场配置
+playground:
+  # 是否启用Playground，默认关闭
+  enabled: false
+  # 访问密码，可选。仅在enabled=true时生效
+  # 为空时表示公开访问，不需要密码
+  password: ""
+```
+
+### 配置参数
+
+#### `enabled`
+- **类型**: `boolean`
+- **默认值**: `false`
+- **说明**: 控制 Playground 功能是否启用
+  - `false`: Playground 完全关闭，页面和所有相关 API 均不可访问
+  - `true`: Playground 启用，可以正常使用
+
+#### `password`
+- **类型**: `string`
+- **默认值**: `""` (空字符串)
+- **说明**: 访问密码（仅在 `enabled = true` 时生效）
+  - 空字符串或 `null`: 公开访问模式，无需密码
+  - 非空字符串: 需要输入正确密码才能访问
+
+## 访问模式
+
+### 1. 完全禁用模式 (enabled = false)
+
+这是**默认且推荐的生产环境配置**。
+
+```yaml
+playground:
+  enabled: false
+  password: ""
+```
+
+**行为**:
+- `/playground` 页面显示"Playground未开启"提示
+- 所有 Playground 相关 API（`/v2/playground/**`）返回错误提示
+- 最安全的模式，适合生产环境
+
+**适用场景**:
+- 生产环境部署
+- 不需要使用 Playground 功能的情况
+
+---
+
+### 2. 密码保护模式 (enabled = true, password 非空)
+
+这是**公网环境的推荐配置**。
+
+```yaml
+playground:
+  enabled: true
+  password: "your_strong_password_here"
+```
+
+**行为**:
+- 访问 `/playground` 页面时会显示密码输入框
+- 需要输入正确密码才能进入编辑器
+- 密码验证通过后，在当前会话中保持已登录状态
+- 会话基于客户端 IP 或 Cookie 进行识别
+
+**适用场景**:
+- 需要在公网环境使用 Playground
+- 多人共享访问，但需要访问控制
+- 团队协作开发环境
+
+**示例**:
+```yaml
+playground:
+  enabled: true
+  password: "MySecure@Password123"
+```
+
+---
+
+### 3. 公开访问模式 (enabled = true, password 为空)
+
+⚠️ **仅建议在本地开发或内网环境使用**。
+
+```yaml
+playground:
+  enabled: true
+  password: ""
+```
+
+**行为**:
+- Playground 对所有访问者开放
+- 无需输入密码即可使用所有功能
+- 页面加载后直接显示编辑器
+
+**适用场景**:
+- 本地开发环境（`localhost`）
+- 完全隔离的内网环境
+- 个人使用且不暴露在公网
+
+**⚠️ 安全警告**:
+> **强烈不建议在公网环境下使用此配置！**
+> 
+> 公开访问模式允许任何人：
+> - 执行任意 JavaScript 代码（虽然有沙箱限制）
+> - 发布解析器脚本到数据库
+> - 查看、修改、删除已有的解析器
+> - 可能导致服务器资源被滥用
+>
+> 如果必须在公网环境开启 Playground，请务必：
+> 1. 设置一个足够复杂的密码
+> 2. 定期更换密码
+> 3. 通过防火墙或网关限制访问来源（IP 白名单）
+> 4. 启用访问日志监控
+> 5. 考虑使用 HTTPS 加密传输
+
+---
+
+## 技术实现
+
+### 后端实现
+
+#### 状态检查 API
+```
+GET /v2/playground/status
+```
+
+返回：
+```json
+{
+  "enabled": true,
+  "needPassword": true,
+  "authed": false
+}
+```
+
+#### 登录 API
+```
+POST /v2/playground/login
+Content-Type: application/json
+
+{
+  "password": "your_password"
+}
+```
+
+#### 认证机制
+- 使用 Vert.x 的 `SharedData` 存储认证状态
+- 基于客户端 IP 或 Cookie 中的 session ID 识别用户
+- 密码验证通过后在 `playground_auth` Map 中记录
+
+#### 受保护的端点
+所有以下端点都需要通过访问控制检查：
+- `POST /v2/playground/test` - 执行测试
+- `GET /v2/playground/types.js` - 获取类型定义
+- `GET /v2/playground/parsers` - 获取解析器列表
+- `POST /v2/playground/parsers` - 保存解析器
+- `PUT /v2/playground/parsers/:id` - 更新解析器
+- `DELETE /v2/playground/parsers/:id` - 删除解析器
+- `GET /v2/playground/parsers/:id` - 获取解析器详情
+
+### 前端实现
+
+#### 状态检查流程
+1. 页面加载时调用 `/v2/playground/status`
+2. 根据返回的状态显示不同界面：
+   - `enabled = false`: 显示"未开启"提示
+   - `enabled = true & needPassword = true & !authed`: 显示密码输入框
+   - `enabled = true & (!needPassword || authed)`: 加载编辑器
+
+#### 密码输入界面
+- 密码输入框（支持显示/隐藏密码）
+- 验证按钮
+- 错误提示
+- 支持回车键提交
+
+---
+
+## 配置示例
+
+### 示例 1: 生产环境（推荐）
+```yaml
+playground:
+  enabled: false
+  password: ""
+```
+
+### 示例 2: 公网开发环境
+```yaml
+playground:
+  enabled: true
+  password: "Str0ng!P@ssw0rd#2024"
+```
+
+### 示例 3: 本地开发
+```yaml
+playground:
+  enabled: true
+  password: ""
+```
+
+---
+
+## 常见问题
+
+### Q1: 忘记密码怎么办？
+**A**: 直接修改 `app-dev.yml` 配置文件中的 `password` 值，然后重启服务即可。
+
+### Q2: 可以动态修改密码吗？
+**A**: 目前需要修改配置文件并重启服务。密码在服务启动时加载。
+
+### Q3: 多个用户可以同时使用吗？
+**A**: 可以。密码验证通过后，每个客户端都会保持独立的认证状态。
+
+### Q4: 公开模式下有什么安全限制吗？
+**A**: 
+- 代码执行有大小限制（128KB）
+- JavaScript 在 Nashorn 沙箱中运行
+- 最多创建 100 个解析器
+- 但仍然建议在内网或本地使用
+
+### Q5: 密码会明文传输吗？
+**A**: 如果使用 HTTP，是的。强烈建议配置 HTTPS 以加密传输。
+
+### Q6: 会话会过期吗？
+**A**: 当前实现基于内存存储，服务重启后需要重新登录。单个会话不会主动过期。
+
+---
+
+## 安全建议
+
+### 🔒 强密码要求
+如果启用密码保护，请确保密码符合以下要求：
+- 长度至少 12 位
+- 包含大小写字母、数字和特殊字符
+- 避免使用常见单词或生日等个人信息
+- 定期更换密码（建议每季度一次）
+
+### 🌐 网络安全措施
+- 在生产环境使用 HTTPS
+- 配置防火墙或网关限制访问来源
+- 使用反向代理（如 Nginx）添加额外的安全层
+- 启用访问日志和监控
+
+### 📝 最佳实践
+1. **默认禁用**: 除非必要，保持 `enabled: false`
+2. **密码保护**: 公网环境务必设置密码
+3. **访问控制**: 结合 IP 白名单限制访问
+4. **定期审计**: 检查已创建的解析器脚本
+5. **监控告警**: 设置异常访问告警机制
+
+---
+
+## 迁移指南
+
+### 从旧版本升级
+
+如果你的系统之前没有 Playground 访问控制，升级后：
+
+1. **默认行为**: Playground 将被禁用（`enabled: false`）
+2. **如需启用**: 在配置文件中添加上述配置
+3. **兼容性**: 完全向后兼容，不影响其他功能
+
+---
+
+## 更新日志
+
+### v0.1.8
+- 添加 Playground 访问控制功能
+- 支持三种访问模式：禁用、密码保护、公开访问
+- 前端添加密码输入界面
+- 所有 Playground API 受保护
+
+---
+
+## 技术支持
+
+如有问题，请访问：
+- GitHub Issues: https://github.com/qaiu/netdisk-fast-download/issues
+- 项目文档: https://github.com/qaiu/netdisk-fast-download
+
+---
+
+**最后更新**: 2025-12-07