mirror of
https://github.com/qaiu/netdisk-fast-download.git
synced 2025-12-17 12:53:02 +00:00
294 lines
7.1 KiB
Markdown
294 lines
7.1 KiB
Markdown
# 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
|