Fu-Jie_openwebui-extensions/scripts/DEPLOYMENT_SUMMARY.md

📦 Async Context Compression — 本地部署工具 (Local Deployment Tools)

🎯 功能概述

为 async_context_compression Filter 插件添加了完整的本地部署工具链，支持快速迭代开发无需重启 OpenWebUI。

📋 新增文件

1. deploy_filter.py — Filter 插件部署脚本

• 位置: scripts/deploy_filter.py
• 功能: 自动部署 Filter 类插件到本地 OpenWebUI 实例
• 特性:
  • ✅ 从 Python docstring 自动提取元数据
  • ✅ 智能版本号识别（semantic versioning）
  • ✅ 支持多个 Filter 插件管理
  • ✅ 自动更新或创建插件
  • ✅ 详细的错误诊断和连接测试
  • ✅ 列表指令查看所有可用 Filter
• 代码行数: ~300 行

2. DEPLOYMENT_GUIDE.md — 完整部署指南

• 位置: scripts/DEPLOYMENT_GUIDE.md
• 内容:
  • 前置条件和快速开始
  • 脚本详细说明
  • API 密钥获取方法
  • 故障排除指南
  • 分步工作流示例

3. QUICK_START.md — 快速参考卡片

• 位置: scripts/QUICK_START.md
• 内容:
  • 一行命令部署
  • 前置步骤
  • 常见命令表格
  • 故障诊断速查表
  • CI/CD 集成示例

4. test_deploy_filter.py — 单元测试套件

• 位置: tests/scripts/test_deploy_filter.py
• 测试覆盖:
  • ✅ Filter 文件发现 (3 个测试)
  • ✅ 元数据提取 (3 个测试)
  • ✅ API 负载构建 (4 个测试)
• 测试通过率: 10/10 ✅

🚀 使用方式

基本部署（一行命令）

cd scripts
python deploy_filter.py

列出所有可用 Filter

python deploy_filter.py --list

部署指定 Filter

python deploy_filter.py folder-memory
python deploy_filter.py context_enhancement_filter

🔧 工作原理

┌─────────────────────────────────────────────────────────────┐
│ 1. 加载 API 密钥 (.env)                                      │
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│ 2. 查找 Filter 插件文件                                      │
│    - 从名称推断文件路径                                     │
│    - 支持 hyphen-case 和 snake_case 查找                    │
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│ 3. 读取 Python 源代码                                        │
│    - 提取 docstring 元数据                                  │
│    - title, version, author, description, openwebui_id      │
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│ 4. 构建 API 请求负载                                        │
│    - 组装 manifest 和 meta 信息                             │
│    - 包含完整源代码内容                                     │
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│ 5. 发送请求                                                │
│    - POST /api/v1/functions/id/{id}/update （更新）         │
│    - POST /api/v1/functions/create （创建备用）             │
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│ 6. 显示结果和诊断                                           │
│    - ✅ 更新/创建成功                                       │
│    - ❌ 错误信息和解决建议                                  │
└─────────────────────────────────────────────────────────────┘

📊 支持的 Filter 列表

脚本自动发现以下 Filter：

Filter 名称	Python 文件	版本
async-context-compression	async_context_compression.py	1.3.0+
chat-session-mapping-filter	chat_session_mapping_filter.py	0.1.0+
context_enhancement_filter	context_enhancement_filter.py	0.3+
folder-memory	folder_memory.py	0.1.0+
github_copilot_sdk_files_filter	github_copilot_sdk_files_filter.py	0.1.3+
markdown_normalizer	markdown_normalizer.py	1.2.8+
web_gemini_multimodel_filter	web_gemini_multimodel_filter.py	0.3.2+

⚙️ 技术细节

元数据提取

脚本从 Python 文件顶部的 docstring 中提取元数据：

"""
title: Async Context Compression
id: async_context_compression
author: Fu-Jie
author_url: https://github.com/Fu-Jie/openwebui-extensions
funding_url: https://github.com/open-webui
description: Reduces token consumption...
version: 1.3.0
openwebui_id: b1655bc8-6de9-4cad-8cb5-a6f7829a02ce
"""

支持的元数据字段:

• title — Filter 显示名称 ✅
• id — 唯一标识符 ✅
• author — 作者名称 ✅
• author_url — 作者主页链接 ✅
• funding_url — 项目链接 ✅
• description — 功能描述 ✅
• version — 语义化版本号 ✅
• openwebui_id — OpenWebUI UUID （可选）

API 集成

脚本使用 OpenWebUI REST API：

POST /api/v1/functions/id/{filter_id}/update
- 更新现有 Filter
- HTTP 200: 更新成功
- HTTP 404: Filter 不存在，自动尝试创建

POST /api/v1/functions/create
- 创建新 Filter
- HTTP 200: 创建成功

认证: Bearer token (API 密钥方式)

🔐 安全性

API 密钥管理

# 1. 创建 .env 文件
echo "api_key=sk-your-key-here" > scripts/.env

# 2. 将 .env 添加到 .gitignore
echo "scripts/.env" >> .gitignore

# 3. 不要提交 API 密钥
git add scripts/.gitignore
git commit -m "chore: add .env to gitignore"

最佳实践

• ✅ 使用长期认证令牌（而不是短期 JWT）
• ✅ 定期轮换 API 密钥
• ✅ 限制密钥权限范围
• ✅ 在可信网络中使用
• ✅ 生产环境使用 CI/CD 秘密管理

🧪 测试验证

运行测试套件

pytest tests/scripts/test_deploy_filter.py -v

测试覆盖范围

✅ TestFilterDiscovery (3 个测试)
   - test_find_async_context_compression
   - test_find_nonexistent_filter
   - test_find_filter_with_underscores

✅ TestMetadataExtraction (3 个测试)
   - test_extract_metadata_from_async_compression
   - test_extract_metadata_empty_file
   - test_extract_metadata_multiline_docstring

✅ TestPayloadBuilding (4 个测试)
   - test_build_filter_payload_basic
   - test_payload_has_required_fields
   - test_payload_with_openwebui_id

✅ TestVersionExtraction (1 个测试)
   - test_extract_valid_version

结果: 10/10 通过 ✅

💡 常见用例

用例 1: 修复 Bug 后快速测试

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

# 2. 立即部署（不需要重启 OpenWebUI）
cd scripts && python deploy_filter.py

# 3. 在 OpenWebUI 中测试修复
# 4. 重复迭代（返回步骤 1）

用例 2: 开发新的 Filter

# 1. 创建新 Filter 目录
mkdir plugins/filters/my-new-filter

# 2. 编写代码（包含必要的 docstring 元数据）
cat > plugins/filters/my-new-filter/my_new_filter.py << 'EOF'
"""
title: My New Filter
author: Your Name
version: 1.0.0
description: Filter description
"""

class Filter:
    # ... implementation ...
EOF

# 3. 首次部署（创建）
cd scripts && python deploy_filter.py my-new-filter

# 4. 在 OpenWebUI UI 测试
# 5. 重复更新
cd scripts && python deploy_filter.py my-new-filter

用例 3: 版本更新和发布

# 1. 更新版本号
vim plugins/filters/async-context-compression/async_context_compression.py
# 修改: version: 1.3.0 → version: 1.4.0

# 2. 部署新版本
cd scripts && python deploy_filter.py

# 3. 测试通过后提交
git add plugins/filters/async-context-compression/
git commit -m "feat(filters): update async-context-compression to 1.4.0"
git push

🔄 CI/CD 集成

GitHub Actions 示例

name: Deploy Filter on Release

on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.12'
      
      - name: Deploy Filter
        run: |
          cd scripts
          python deploy_filter.py async-context-compression
        env:
          api_key: ${{ secrets.OPENWEBUI_API_KEY }}

📚 参考文档

• 完整部署指南
• 快速参考卡片
• 测试套件
• 插件开发指南
• OpenWebUI 文档

🎓 学习资源

架构理解

OpenWebUI 系统设计
    ↓
Filter 插件类型定义
    ↓
REST API 接口 (/api/v1/functions)
    ↓
本地部署脚本实现 (deploy_filter.py)
    ↓
元数据提取和投递

调试技巧

1. 启用详细日志:

   python deploy_filter.py 2>&1 | tee deploy.log
   

2. 测试 API 连接:

   curl -X GET http://localhost:3003/api/v1/functions \
     -H "Authorization: Bearer $API_KEY"
   

3. 验证 .env 文件:

   grep "api_key=" scripts/.env
   

📞 故障排除

问题	诊断	解决方案
Connection error	OpenWebUI 地址/端口不对	检查 localhost:3003；修改 URL 如需要
.env not found	未创建配置文件	echo "api_key=sk-..." > scripts/.env
Filter not found	插件名称错误	运行 python deploy_filter.py --list
Status 401	API 密钥无效/过期	更新 .env 中的密钥
Status 500	服务器错误	检查 OpenWebUI 服务日志

✨ 特色功能

特性	描述
🔍 自动发现	自动查找所有 Filter 插件
📊 元数据提取	从代码自动提取版本和元数据
♻️ 自动更新	智能处理更新或创建
🛡️ 错误处理	详细的错误提示和诊断信息
🚀 快速迭代	秒级部署，无需重启
🧪 完整测试	10 个单元测试覆盖核心功能

---

最后更新: 2026-03-09
作者: Fu-Jie
项目: openwebui-extensions