open-webui/Fu-Jie_openwebui-extensions
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f061d8240948ffa9ac77c97d4638bc0b840dd0e1
Fu-Jie_openwebui-extensions/scripts/README.md
fujie f061d82409 feat(async-context-compression): release v1.4.0 with structure-aware grouping and session locking 
- Introduced Atomic Message Grouping to prevent tool-calling corruption (Issue #56)
- Implemented Tail Boundary Alignment for deterministic context truncation
- Added per-chat asynchronous session locking to prevent duplicate background tasks
- Enhanced summarization traceability with message IDs and names
- Synchronized version and changelog across all documentation files
- Optimized release-prep skill to remove redundant H1 titles

Closes #56
2026-03-09 20:34:34 +08:00

9.7 KiB
Raw Blame History

🚀 部署脚本使用指南 (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 密钥

cd scripts

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

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

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

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

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

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

📋 部署工具详解

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

最简单的部署方式！

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 插件！

# 部署默认的 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 部署工具

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: 开发新功能后部署

# 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 并快速验证

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

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

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

场景 3: 部署多个 Filter

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

🔐 安全提示

管理 API 密钥

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

解决方案:

# 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

解决方案:

echo "api_key=sk-your-api-key" > .env
cat .env  # 验证文件已创建

问题 3: "Filter not found"

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

解决方案:

# 列出所有可用 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"}

解决方案:

# 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 一页速查表
DEPLOYMENT_GUIDE.md 完整详细指南
DEPLOYMENT_SUMMARY.md 技术架构说明

🧪 验证部署成功

方式 1: 检查脚本输出

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. 进行多轮对话，验证压缩和总结功能正常

💡 高级用法

自动化部署测试

#!/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 集成

# .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 }}

📞 获取帮助

检查脚本状态

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

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

查看脚本版本

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

调试模式

# 保存输出到日志文件
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 通过 ✅

Reference in New Issue View Git Blame Copy Permalink