chore: update default port from 3003 to 3000 and improve installation docs

- Change all default port references from 3003 to 3000 across scripts and documentation - Add quick installation guide for batch plugin installation to main README (EN & CN) - Simplify installation options by removing manual installation instructions - Update deployment guides and examples to reflect new default port
2026-03-09 21:42:17 +08:00
parent 62e78ace5c
commit ae0fa1d39a
16 changed files with 1712 additions and 691 deletions
--- a/scripts/DEPLOYMENT_GUIDE.md
+++ b/scripts/DEPLOYMENT_GUIDE.md
@@ -1,147 +1,147 @@
-# 🚀 本地部署脚本指南 (Local Deployment Guide)
+# 🚀 Local Deployment Scripts Guide

-## 概述
+## Overview

-本目录包含用于将开发中的插件部署到本地 OpenWebUI 实例的自动化脚本。它们可以快速推送代码更改而无需重启 OpenWebUI。
+This directory contains automated scripts for deploying plugins in development to a local OpenWebUI instance. They enable quick code pushes without restarting OpenWebUI.

-## 前置条件
+## Prerequisites

-1. **OpenWebUI 运行中**: 确保 OpenWebUI 在本地运行（默认 `http://localhost:3003`）
-2. **API 密钥**: 需要一个有效的 OpenWebUI API 密钥
-3. **环境文件**: 在此目录创建 `.env` 文件，包含 API 密钥：
+1. **OpenWebUI Running**: Make sure OpenWebUI is running locally (default `http://localhost:3000`)
+2. **API Key**: You need a valid OpenWebUI API key
+3. **Environment File**: Create a `.env` file in this directory containing your API key:
   ```
   api_key=sk-xxxxxxxxxxxxx
   ```

-## 快速开始
+## Quick Start

-### 部署 Pipe 插件
+### Deploy a Pipe Plugin

 ```bash
-# 部署 GitHub Copilot SDK Pipe
+# Deploy GitHub Copilot SDK Pipe
 python deploy_pipe.py
 ```

-### 部署 Filter 插件
+### Deploy a Filter Plugin

 ```bash
-# 部署 async_context_compression Filter（默认）
+# Deploy async_context_compression Filter (default)
 python deploy_filter.py

-# 部署指定的 Filter 插件
+# Deploy a specific Filter plugin
 python deploy_filter.py my-filter-name

-# 列出所有可用的 Filter
+# List all available Filters
 python deploy_filter.py --list
 ```

-## 脚本说明
+## Script Documentation

-### `deploy_filter.py` — Filter 插件部署工具
+### `deploy_filter.py` — Filter Plugin Deployment Tool

-用于部署 Filter 类型的插件（如消息过滤、上下文压缩等）。
+Used to deploy Filter-type plugins (such as message filtering, context compression, etc.).

-**主要特性**:
- ✅ 从 Python 文件自动提取元数据（版本、作者、描述等）
- ✅ 尝试更新现有插件，若不存在则创建新插件
- ✅ 支持多个 Filter 插件管理
- ✅ 详细的错误提示和连接诊断
+**Key Features**:
+- ✅ Auto-extracts metadata from Python files (version, author, description, etc.)
+- ✅ Attempts to update existing plugins, creates if not found
+- ✅ Supports multiple Filter plugin management
+- ✅ Detailed error messages and connection diagnostics

-**用法**:
+**Usage**:
 ```bash
-# 默认部署 async_context_compression
+# Deploy async_context_compression (default)
 python deploy_filter.py

-# 部署其他 Filter
+# Deploy other Filters
 python deploy_filter.py async-context-compression
 python deploy_filter.py workflow-guide

-# 列出所有可用 Filter
+# List all available Filters
 python deploy_filter.py --list
 python deploy_filter.py -l
 ```

-**工作流程**:
-1. 从 `.env` 加载 API 密钥
-2. 查找目标 Filter 插件目录
-3. 读取 Python 源文件
-4. 从 docstring 提取元数据（title, version, author, description, etc.）
-5. 构建 API 请求负载
-6. 发送更新请求到 OpenWebUI
-7. 若更新失败，自动尝试创建新插件
-8. 显示结果和诊断信息
+**Workflow**:
+1. Load API key from `.env`
+2. Find target Filter plugin directory
+3. Read Python source file
+4. Extract metadata from docstring (title, version, author, description, etc.)
+5. Build API request payload
+6. Send update request to OpenWebUI
+7. If update fails, auto-attempt to create new plugin
+8. Display results and diagnostic info

-### `deploy_pipe.py` — Pipe 插件部署工具
+### `deploy_pipe.py` — Pipe Plugin Deployment Tool

-用于部署 Pipe 类型的插件（如 GitHub Copilot SDK）。
+Used to deploy Pipe-type plugins (such as GitHub Copilot SDK).

-**使用**:
+**Usage**:
 ```bash
 python deploy_pipe.py
 ```

-## 获取 API 密钥
+## Get an API Key

-### 方法 1: 使用现有用户令牌（推荐）
+### Method 1: Use Existing User Token (Recommended)

-1. 打开 OpenWebUI 界面
-2. 点击用户头像 → Settings（设置）
-3. 找到 API Keys 部分
-4. 复制你的 API 密钥（sk-开头）
-5. 粘贴到 `.env` 文件中
+1. Open OpenWebUI interface
+2. Click user avatar → Settings
+3. Find the API Keys section
+4. Copy your API key (starts with sk-)
+5. Paste into `.env` file

-### 方法 2: 创建长期 API 密钥
+### Method 2: Create a Long-term API Key

-在 OpenWebUI 设置中创建专用于部署的长期 API 密钥。
+Create a dedicated long-term API key in OpenWebUI Settings for deployment purposes.

-## 故障排除
+## Troubleshooting

-### "Connection error: Could not reach OpenWebUI at localhost:3003"
+### "Connection error: Could not reach OpenWebUI at localhost:3000"

-**原因**: OpenWebUI 未运行或端口不同
+**Cause**: OpenWebUI is not running or port is different

-**解决方案**:
- 确保 OpenWebUI 正在运行
- 检查 OpenWebUI 实际监听的端口（通常是 3000 或 3003）
- 根据需要编辑脚本中的 URL
+**Solution**:
+- Make sure OpenWebUI is running
+- Check which port OpenWebUI is actually listening on (usually 3000)
+- Edit the URL in the script if needed

 ### ".env file not found"

-**原因**: 未创建 `.env` 文件
+**Cause**: `.env` file was not created

-**解决方案**:
+**Solution**:
 ```bash
 echo "api_key=sk-your-api-key-here" > .env
 ```

 ### "Filter 'xxx' not found"

-**原因**: Filter 目录名不正确
+**Cause**: Filter directory name is incorrect

-**解决方案**:
+**Solution**:
 ```bash
-# 列出所有可用的 Filter
+# List all available Filters
 python deploy_filter.py --list
 ```

 ### "Failed to update or create. Status: 401"

-**原因**: API 密钥无效或过期
+**Cause**: API key is invalid or expired

-**解决方案**:
-1. 验证 API 密钥的有效性
-2. 获取新的 API 密钥
-3. 更新 `.env` 文件
+**Solution**:
+1. Verify your API key is valid
+2. Generate a new API key
+3. Update the `.env` file

-## 工作流示例
+## Workflow Examples

-### 开发并部署新的 Filter
+### Develop and Deploy a New Filter

 ```bash
-# 1. 在 plugins/filters/ 创建新的 Filter 目录
+# 1. Create new Filter directory in plugins/filters/
 mkdir plugins/filters/my-new-filter

-# 2. 创建 my_new_filter.py 文件，包含必要的元数据：
+# 2. Create my_new_filter.py with required metadata:
 # """
 # title: My New Filter
 # author: Your Name
@@ -149,58 +149,58 @@ mkdir plugins/filters/my-new-filter
 # description: Filter description
 # """

-# 3. 部署到本地 OpenWebUI
+# 3. Deploy to local OpenWebUI
 cd scripts
 python deploy_filter.py my-new-filter

-# 4. 在 OpenWebUI UI 中测试插件
+# 4. Test the plugin in OpenWebUI UI

-# 5. 继续迭代开发
-# ... 修改代码 ...
+# 5. Continue development
+# ... modify code ...

-# 6. 重新部署（自动覆盖）
+# 6. Re-deploy (auto-overwrites)
 python deploy_filter.py my-new-filter
 ```

-### 修复 Bug 并快速部署
+### Fix a Bug and Deploy Quickly

 ```bash
-# 1. 修改源代码
+# 1. Modify the source code
 # vim ../plugins/filters/async-context-compression/async_context_compression.py

-# 2. 立即部署到本地
+# 2. Deploy immediately to local
 python deploy_filter.py async-context-compression

-# 3. 在 OpenWebUI 中测试修复
-# （无需重启 OpenWebUI）
+# 3. Test the fix in OpenWebUI
+# (No need to restart OpenWebUI)
 ```

-## 安全注意事项
+## Security Considerations

-⚠️ **重要**: 
- ✅ 将 `.env` 文件添加到 `.gitignore`（避免提交敏感信息）
- ✅ 不要在版本控制中提交 API 密钥
- ✅ 仅在可信的网络环境中使用
- ✅ 定期轮换 API 密钥
+⚠️ **Important**: 
+- ✅ Add `.env` file to `.gitignore` (avoid committing sensitive info)
+- ✅ Never commit API keys to version control
+- ✅ Use only on trusted networks
+- ✅ Rotate API keys periodically

-## 文件结构
+## File Structure

 ```
 scripts/
-├── deploy_filter.py        # Filter 插件部署工具
-├── deploy_pipe.py          # Pipe 插件部署工具
-├── .env                    # API 密钥（本地，不提交）
-├── README.md               # 本文件
+├── deploy_filter.py        # Filter plugin deployment tool
+├── deploy_pipe.py          # Pipe plugin deployment tool
+├── .env                    # API key (local, not committed)
+├── README.md               # This file
 └── ...
 ```

-## 参考资源
+## Reference Resources

- [OpenWebUI 文档](https://docs.openwebui.com/)
- [插件开发指南](../docs/development/plugin-guide.md)
- [Filter 插件示例](../plugins/filters/)
+- [OpenWebUI Documentation](https://docs.openwebui.com/)
+- [Plugin Development Guide](../docs/development/plugin-guide.md)
+- [Filter Plugin Examples](../plugins/filters/)

 ---

-**最后更新**: 2026-03-09  
-**作者**: Fu-Jie
+**Last Updated**: 2026-03-09  
+**Author**: Fu-Jie