mirror of
https://github.com/qaiu/netdisk-fast-download.git
synced 2025-12-16 04:13:03 +00:00
Add comprehensive documentation for playground access control
Co-authored-by: qaiu <29825328+qaiu@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
@@ -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)
|
||||
|
||||
293
web-service/doc/PLAYGROUND_ACCESS_CONTROL.md
Normal file
293
web-service/doc/PLAYGROUND_ACCESS_CONTROL.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user