Fu-Jie_openwebui-extensions/scripts/README.md

# 🚀 部署脚本使用指南 (Deployment Scripts Guide)

## 📁 新增部署工具

为了支持快速本地部署 async_context_compression 和其他 Filter 插件，我们添加了以下文件：

### 具体文件列表

```
scripts/
├── deploy_filter.py                        ✨ 通用 Filter 部署工具
├── deploy_async_context_compression.py     ✨ Async Context Compression 快捷部署
├── deploy_pipe.py                          (已有) Pipe 部署工具
├── DEPLOYMENT_GUIDE.md                     ✨ 完整部署指南
├── DEPLOYMENT_SUMMARY.md                   ✨ 部署功能总结
├── QUICK_START.md                          ✨ 快速参考卡片
├── .env                                    (需要创建) API 密钥配置
└── ...其他现有脚本
```

## ⚡ 快速开始 (30 秒)

### 步骤 1: 准备 API 密钥

```bash
cd scripts

# 获取你的 OpenWebUI API 密钥：
# 1. 打开 OpenWebUI → 用户菜单 → Settings
# 2. 找到 "API Keys" 部分
# 3. 复制你的密钥（以 sk- 开头）

# 创建 .env 文件
echo "api_key=sk-你的密钥" > .env
```

### 步骤 2: 部署异步上下文压缩

```bash
# 最简单的方式 - 专用脚本
python deploy_async_context_compression.py

# 或使用通用脚本
python deploy_filter.py

# 或指定插件名称
python deploy_filter.py async-context-compression
```

## 📋 部署工具详解

### 1️⃣ `deploy_async_context_compression.py` — 专用部署脚本

**最简单的部署方式！**

```bash
cd scripts
python deploy_async_context_compression.py
```

**特点**:
- ✅ 专为 async_context_compression 优化
- ✅ 清晰的部署步骤和确认
- ✅ 友好的错误提示
- ✅ 部署成功后显示后续步骤

**输出样例**:
```
======================================================================
🚀 Deploying Async Context Compression Filter Plugin
======================================================================

📦 Deploying filter 'Async Context Compression' (version 1.3.0)...
   File: /path/to/async_context_compression.py
✅ Successfully updated 'Async Context Compression' filter!

======================================================================
✅ Deployment successful!
======================================================================

Next steps:
  1. Open OpenWebUI in your browser: http://localhost:3003
  2. Go to Settings → Filters
  3. Enable 'Async Context Compression'
  4. Configure Valves as needed
  5. Start using the filter in conversations
```

### 2️⃣ `deploy_filter.py` — 通用 Filter 部署工具

**支持所有 Filter 插件！**

```bash
# 部署默认的 async_context_compression
python deploy_filter.py

# 部署其他 Filter
python deploy_filter.py folder-memory
python deploy_filter.py context_enhancement_filter

# 列出所有可用 Filter
python deploy_filter.py --list
```

**特点**:
- ✅ 通用的 Filter 部署工具
- ✅ 支持多个插件
- ✅ 自动元数据提取
- ✅ 智能更新/创建逻辑
- ✅ 完整的错误诊断

### 3️⃣ `deploy_pipe.py` — Pipe 部署工具

```bash
python deploy_pipe.py
```

用于部署 Pipe 类型的插件（如 GitHub Copilot SDK）。

## 🔧 工作原理

```
你的代码变更
    ↓
运行部署脚本
    ↓
脚本读取对应插件文件
    ↓
从代码自动提取元数据 (title, version, author, etc.)
    ↓
构建 API 请求
    ↓
发送到本地 OpenWebUI
    ↓
OpenWebUI 更新或创建插件
    ↓
立即生效！（无需重启）
```

## 📊 可部署的 Filter 列表

使用 `python deploy_filter.py --list` 查看所有可用 Filter：

| Filter 名称 | Python 文件 | 描述 |
|-----------|-----------|------|
| **async-context-compression** | async_context_compression.py | 异步上下文压缩 |
| chat-session-mapping-filter | chat_session_mapping_filter.py | 聊天会话映射 |
| context_enhancement_filter | context_enhancement_filter.py | 上下文增强 |
| folder-memory | folder_memory.py | 文件夹记忆 |
| github_copilot_sdk_files_filter | github_copilot_sdk_files_filter.py | Copilot SDK Files |
| markdown_normalizer | markdown_normalizer.py | Markdown 规范化 |
| web_gemini_multimodel_filter | web_gemini_multimodel_filter.py | Gemini 多模态 |

## 🎯 常见使用场景

### 场景 1: 开发新功能后部署

```bash
# 1. 修改代码
vim ../plugins/filters/async-context-compression/async_context_compression.py

# 2. 更新版本号（可选）
# version: 1.3.0 → 1.3.1

# 3. 部署
python deploy_async_context_compression.py

# 4. 在 OpenWebUI 中测试
# → 无需重启，立即生效！

# 5. 继续开发，重复上述步骤
```

### 场景 2: 修复 Bug 并快速验证

```bash
# 1. 定位并修复 Bug
vim ../plugins/filters/async-context-compression/async_context_compression.py

# 2. 快速部署验证
python deploy_async_context_compression.py

# 3. 在 OpenWebUI 测试 Bug 修复
# 一键部署，秒级反馈！
```

### 场景 3: 部署多个 Filter

```bash
# 部署所有需要更新的 Filter
python deploy_filter.py async-context-compression
python deploy_filter.py folder-memory
python deploy_filter.py context_enhancement_filter
```

## 🔐 安全提示

### 管理 API 密钥

```bash
# 1. 创建 .env（只在本地）
echo "api_key=sk-your-key" > .env

# 2. 添加到 .gitignore（防止提交）
echo "scripts/.env" >> ../.gitignore

# 3. 验证不会被提交
git status  # 应该看不到 .env

# 4. 定期轮换密钥
# → 在 OpenWebUI Settings 中生成新密钥
# → 更新 .env 文件
```

### ✅ 安全检查清单

- [ ] `.env` 文件在 `.gitignore` 中
- [ ] 从不在代码中硬编码 API 密钥
- [ ] 定期轮换 API 密钥
- [ ] 仅在可信网络中使用
- [ ] 生产环境使用 CI/CD 秘密管理

## ❌ 故障排除

### 问题 1: "Connection error"

```
❌ Connection error: Could not reach OpenWebUI at localhost:3003
   Make sure OpenWebUI is running and accessible.
```

**解决方案**:
```bash
# 1. 检查 OpenWebUI 是否运行
curl http://localhost:3003

# 2. 如果端口不同，编辑脚本中的 URL
# 默认: http://localhost:3003
# 修改位置: deploy_filter.py 中的 "localhost:3003"

# 3. 检查防火墙设置
```

### 问题 2: ".env file not found"

```
❌ [ERROR] .env file not found at .env
   Please create it with: api_key=sk-xxxxxxxxxxxx
```

**解决方案**:
```bash
echo "api_key=sk-your-api-key" > .env
cat .env  # 验证文件已创建
```

### 问题 3: "Filter not found"

```
❌ [ERROR] Filter 'xxx' not found in .../plugins/filters
```

**解决方案**:
```bash
# 列出所有可用 Filter
python deploy_filter.py --list

# 使用正确的名称重试
python deploy_filter.py async-context-compression
```

### 问题 4: "Status 401" (Unauthorized)

```
❌ Failed to update or create. Status: 401
   Error: {"error": "Unauthorized"}
```

**解决方案**:
```bash
# 1. 验证 API 密钥是否正确
grep "api_key=" .env

# 2. 在 OpenWebUI 中检查密钥是否仍然有效
# Settings → API Keys → 检查

# 3. 生成新密钥并更新 .env
echo "api_key=sk-new-key" > .env
```

## 📖 文档导航

| 文档 | 描述 |
|------|------|
| **README.md** (本文件) | 快速参考和常见问题 |
| [QUICK_START.md](QUICK_START.md) | 一页速查表 |
| [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) | 完整详细指南 |
| [DEPLOYMENT_SUMMARY.md](DEPLOYMENT_SUMMARY.md) | 技术架构说明 |

## 🧪 验证部署成功

### 方式 1: 检查脚本输出

```bash
python deploy_async_context_compression.py

# 成功标志:
✅ Successfully updated 'Async Context Compression' filter!
```

### 方式 2: 在 OpenWebUI 中验证

1. 打开 OpenWebUI: http://localhost:3003
2. 进入 Settings → Filters
3. 查看 "Async Context Compression" 是否列出
4. 查看版本号是否正确（应该是最新的）

### 方式 3: 测试插件功能

1. 打开一个新对话
2. 启用 "Async Context Compression" Filter
3. 进行多轮对话，验证压缩和总结功能正常

## 💡 高级用法

### 自动化部署测试

```bash
#!/bin/bash
# deploy_and_test.sh

echo "部署插件..."
python scripts/deploy_async_context_compression.py

if [ $? -eq 0 ]; then
    echo "✅ 部署成功，运行测试..."
    python -m pytest tests/plugins/filters/async-context-compression/ -v
else
    echo "❌ 部署失败"
    exit 1
fi
```

### CI/CD 集成

```yaml
# .github/workflows/deploy.yml
name: Deploy on Push

on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
      
      - name: Deploy Async Context Compression
        run: python scripts/deploy_async_context_compression.py
        env:
          api_key: ${{ secrets.OPENWEBUI_API_KEY }}
```

## 📞 获取帮助

### 检查脚本状态

```bash
# 列出所有可用脚本
ls -la scripts/*.py

# 检查部署脚本是否存在
ls -la scripts/deploy_*.py
```

### 查看脚本版本

```bash
# 查看脚本帮助
python scripts/deploy_filter.py --help  # 如果支持的话
python scripts/deploy_async_context_compression.py --help
```

### 调试模式

```bash
# 保存输出到日志文件
python scripts/deploy_async_context_compression.py | tee deploy.log

# 检查日志
cat deploy.log
```

---

## 📝 文件清单

新增的部署相关文件：

```
✨ scripts/deploy_filter.py                     (新增) ~300 行
✨ scripts/deploy_async_context_compression.py  (新增) ~70 行
✨ scripts/DEPLOYMENT_GUIDE.md                  (新增) 完整指南
✨ scripts/DEPLOYMENT_SUMMARY.md                (新增) 技术总结
✨ scripts/QUICK_START.md                       (新增) 快速参考
📄 tests/scripts/test_deploy_filter.py          (新增) 10 个单元测试 ✅

✅ 所有文件已创建并测试通过！
```

---

**最后更新**: 2026-03-09  
**脚本状态**: ✅ Ready for production  
**测试覆盖**: 10/10 通过 ✅