netdisk-fast-download/web-service/doc/PLAYGROUND_ACCESS_CONTROL.md

Playground 访问控制配置指南

概述

Playground 演练场是一个用于编写、测试和发布 JavaScript 解析脚本的在线开发环境。为了提升安全性，现在支持灵活的访问控制配置。

配置说明

在 web-service/src/main/resources/app-dev.yml 文件中添加以下配置：

# 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)

这是默认且推荐的生产环境配置。

playground:
  enabled: false
  password: ""

行为:

• /playground 页面显示"Playground未开启"提示
• 所有 Playground 相关 API（/v2/playground/**）返回错误提示
• 最安全的模式，适合生产环境

适用场景:

• 生产环境部署
• 不需要使用 Playground 功能的情况

---

2. 密码保护模式 (enabled = true, password 非空)

这是公网环境的推荐配置。

playground:
  enabled: true
  password: "your_strong_password_here"

行为:

• 访问 /playground 页面时会显示密码输入框
• 需要输入正确密码才能进入编辑器
• 密码验证通过后，在当前会话中保持已登录状态
• 会话基于客户端 IP 或 Cookie 进行识别

适用场景:

• 需要在公网环境使用 Playground
• 多人共享访问，但需要访问控制
• 团队协作开发环境

示例:

playground:
  enabled: true
  password: "MySecure@Password123"

---

3. 公开访问模式 (enabled = true, password 为空)

⚠️ 仅建议在本地开发或内网环境使用。

playground:
  enabled: true
  password: ""

行为:

• Playground 对所有访问者开放
• 无需输入密码即可使用所有功能
• 页面加载后直接显示编辑器

适用场景:

• 本地开发环境（localhost）
• 完全隔离的内网环境
• 个人使用且不暴露在公网

⚠️ 安全警告:

强烈不建议在公网环境下使用此配置！

公开访问模式允许任何人：

• 执行任意 JavaScript 代码（虽然有沙箱限制）
• 发布解析器脚本到数据库
• 查看、修改、删除已有的解析器
• 可能导致服务器资源被滥用

如果必须在公网环境开启 Playground，请务必：

1. 设置一个足够复杂的密码
2. 定期更换密码
3. 通过防火墙或网关限制访问来源（IP 白名单）
4. 启用访问日志监控
5. 考虑使用 HTTPS 加密传输

---

技术实现

后端实现

状态检查 API

GET /v2/playground/status

返回：

{
  "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: 生产环境（推荐）

playground:
  enabled: false
  password: ""

示例 2: 公网开发环境

playground:
  enabled: true
  password: "Str0ng!P@ssw0rd#2024"

示例 3: 本地开发

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