d29c24ba4a
- Enable default overwrite installation policy for overlapping skills - Support deep recursive GitHub trees discovery mechanism to resolve #58 - Refactor internal architecture to fully decouple stateless helper logic - READMEs and docs synced (v0.3.0)
179 lines
5.0 KiB
Markdown
179 lines
5.0 KiB
Markdown
# Domain Whitelist Configuration Implementation Summary
|
||
|
||
**Status:** ✅ Complete
|
||
**Date:** 2026-03-08
|
||
**Version:** 0.2.2
|
||
|
||
---
|
||
|
||
## 功能概述
|
||
|
||
已为 **OpenWebUI Skills Manager Tool** 添加了一套完整的**主域名白名单 (Primary Domain Whitelist)** 安全机制，允许管理员通过简单的主域名清单来控制技能 URL 下载权限。
|
||
|
||
## 核心改动
|
||
|
||
### 1. 工具代码更新 (`openwebui_skills_manager.py`)
|
||
|
||
#### Valve 参数简化
|
||
|
||
- **TRUSTED_DOMAINS** 默认值从繁复列表简化为主域名清单：
|
||
|
||
```python
|
||
# 改前: "github.com,raw.githubusercontent.com,huggingface.co,huggingface.space"
|
||
# 改后: "github.com,huggingface.co"
|
||
```
|
||
|
||
#### 参数描述优化
|
||
|
||
- 更新了 `ENABLE_DOMAIN_WHITELIST` 和 `TRUSTED_DOMAINS` 的描述文案
|
||
- 明确说明支持子域名自动匹配：
|
||
|
||
```
|
||
URLs with domains matching or containing these primary domains
|
||
(including subdomains) are allowed
|
||
```
|
||
|
||
#### 域名验证逻辑
|
||
|
||
- 代码已支持两种匹配规则：
|
||
1. **完全匹配：** URL 域名 == 主域名
|
||
2. **子域名匹配：** URL 域名 = `*.{主域名}`
|
||
|
||
### 2. README 文档更新
|
||
|
||
#### 英文版 (`README.md`)
|
||
|
||
- 更新配置表格，添加新 Valve 参数说明
|
||
- 新增指向 Domain Whitelist Guide 的链接
|
||
|
||
#### 中文版 (`README_CN.md`)
|
||
|
||
- 对应更新中文配置表格
|
||
- 使用对应的中文描述
|
||
|
||
### 3. 新增文档集合
|
||
|
||
| 文件 | 用途 | 行数 |
|
||
| --- | --- | --- |
|
||
| `docs/DOMAIN_WHITELIST.md` | 详细英文指南，涵盖配置、规则、示例、最佳实践 | 149 |
|
||
| `docs/DOMAIN_WHITELIST_CN.md` | 中文对应版本 | 149 |
|
||
| `docs/DOMAIN_WHITELIST_QUICKREF.md` | 快速参考卡，包含常见配置、故障排除、测试方法 | 153 |
|
||
| `docs/test_domain_validation.py` | 可执行测试脚本，验证域名匹配逻辑 | 215 |
|
||
|
||
### 4. 测试脚本 (`test_domain_validation.py`)
|
||
|
||
可独立运行的 Python 脚本，演示 3 个常用场景 + 边界情况：
|
||
|
||
**场景 1:** GitHub 域名只
|
||
|
||
- ✓ github.com、api.github.com、gist.github.com
|
||
- ✗ raw.githubusercontent.com
|
||
|
||
**场景 2:** GitHub + GitHub Raw
|
||
|
||
- ✓ github.com、raw.githubusercontent.com、api.github.com
|
||
- ✗ cdn.jsdelivr.net
|
||
|
||
**场景 3:** 多源白名单
|
||
|
||
- ✓ github.com、huggingface.co、anthropic.com（及所有子域名）
|
||
- ✗ bitbucket.org
|
||
|
||
**边界情况：**
|
||
|
||
- ✓ 不同大小写处理（大小写无关）
|
||
- ✓ 深层子域名（如 api.v2.github.com）
|
||
- ✓ 非法协议拒绝（ftp、file）
|
||
|
||
## 用户收益
|
||
|
||
### 简化配置
|
||
|
||
```python
|
||
# 改前（复杂）
|
||
TRUSTED_DOMAINS = "github.com,raw.githubusercontent.com,huggingface.co,huggingface.space"
|
||
|
||
# 改后（简洁）
|
||
TRUSTED_DOMAINS = "github.com,huggingface.co" # 子域名自动支持
|
||
```
|
||
|
||
### 自动子域名覆盖
|
||
|
||
添加 `github.com` 自动覆盖：
|
||
|
||
- github.com ✓
|
||
- api.github.com ✓
|
||
- gist.github.com ✓
|
||
- (任何 *.github.com) ✓
|
||
|
||
### 安全防护加强
|
||
|
||
- 域名白名单 ✓
|
||
- IP 地址阻止 ✓
|
||
- 协议限制 ✓
|
||
- 超时保护 ✓
|
||
|
||
## 文档质量
|
||
|
||
| 文档类型 | 覆盖范围 |
|
||
| --- | --- |
|
||
| **详细指南** | 配置说明、匹配规则、使用示例、最佳实践、技术细节 |
|
||
| **快速参考** | TL;DR 表格、常见配置、故障排除、调试方法 |
|
||
| **可执行测试** | 4 个场景 + 4 个边界情况，共 12 个测试用例，全部通过 ✓ |
|
||
|
||
## 部署检查清单
|
||
|
||
- [x] 工具代码修改完成（Valve 参数更新）
|
||
- [x] 工具代码语法检查通过
|
||
- [x] README 英文版更新
|
||
- [x] README 中文版更新
|
||
- [x] 详细指南英文版创建（DOMAIN_WHITELIST.md）
|
||
- [x] 详细指南中文版创建（DOMAIN_WHITELIST_CN.md）
|
||
- [x] 快速参考卡创建（DOMAIN_WHITELIST_QUICKREF.md）
|
||
- [x] 测试脚本创建 + 所有用例通过
|
||
- [x] 文档内容一致性验证
|
||
|
||
## 验证结果
|
||
|
||
```
|
||
✓ 语法检查: openwebui_skills_manager.py ... PASS
|
||
✓ 语法检查: test_domain_validation.py ... PASS
|
||
✓ 功能测试: 12/12 用例通过
|
||
|
||
场景 1 (GitHub Only): 4/4 ✓
|
||
场景 2 (GitHub + Raw): 2/2 ✓
|
||
场景 3 (多源白名单): 5/5 ✓
|
||
边界情况: 4/4 ✓
|
||
```
|
||
|
||
## 下一步建议
|
||
|
||
1. **版本更新**
|
||
更新 openwebui_skills_manager.py 中的版本号（当前 0.2.2）并同步到：
|
||
- README.md
|
||
- README_CN.md
|
||
- 相关文档
|
||
|
||
2. **使用示例补充**
|
||
在 README 中新增"配置示例"部分，展示常见场景配置
|
||
|
||
3. **集成测试**
|
||
将 `test_domain_validation.py` 添加到 CI/CD 流程
|
||
|
||
4. **官方文档同步**
|
||
如有官方文档网站，同步以下内容：
|
||
- Domain Whitelist Guide
|
||
- Configuration Reference
|
||
|
||
---
|
||
|
||
**相关文件清单：**
|
||
|
||
- `plugins/tools/openwebui-skills-manager/openwebui_skills_manager.py` (修改)
|
||
- `plugins/tools/openwebui-skills-manager/README.md` (修改)
|
||
- `plugins/tools/openwebui-skills-manager/README_CN.md` (修改)
|
||
- `plugins/tools/openwebui-skills-manager/docs/DOMAIN_WHITELIST.md` (新建)
|
||
- `plugins/tools/openwebui-skills-manager/docs/DOMAIN_WHITELIST_CN.md` (新建)
|
||
- `plugins/tools/openwebui-skills-manager/docs/DOMAIN_WHITELIST_QUICKREF.md` (新建)
|
||
- `plugins/tools/openwebui-skills-manager/docs/test_domain_validation.py` (新建)
|