openwebui/README.md

Open WebUI (OVINC-CN)

基于 Open WebUI 的增强版：集成计费、支付与企业级用户管理

⚠️ 注意：此仓库的 dev 分支是开发分支，可能包含不稳定功能。生产环境请务必使用 Release 中的正式版本。 本项目是 Open WebUI 的定制分支，与官方团队无关联。

📖 简介

这是一个社区驱动的 Open WebUI 增强版本，旨在为个人开发者和中小团队提供开箱即用的运营化解决方案。我们在原版强大的对话功能基础上，补充了计费、支付、用户验证等商业化闭环所需的关键特性。

✨ 核心特性

功能模块	说明
💰 灵活计费	支持按 Token 或 请求次数 计费，实时扣费并在对话中显示详情。
💳 支付集成	原生支持易支付和支付宝（当面付/订单码），轻松实现自助充值。
📊 数据报表	内置全局积分报表与用户消费记录，运营数据一目了然。
🔐 用户管理	支持邮箱验证注册与兑换码系统，有效控制用户准入与权益分发。
⚙️ 自定义定价	支持对特定模型、搜索工具等进行精细化的自定义倍率或额外收费配置。
🎨 自定义 LOGO & 名称	支持自定义 LOGO 和名称，详情参考 BRANDING.md。

完整特性列表请参阅 CHANGELOG_EXTRA.md。

📸 功能预览

点击展开查看更多截图

积分报表与全局设置

积分报表	全局设置

用户充值与计费详情

用户充值	计费详情

兑换码与注册验证

兑换码	邮箱验证

🚀 快速部署

部署本版本非常简单，只需替换官方镜像即可。

# 拉取最新镜像（请将 <版本号> 替换为具体版本，如 v0.3.0）
docker pull ghcr.io/ovinc-cn/openwebui:<版本号>

# 启动容器 (示例)
docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/ovinc-cn/openwebui:<版本号>

查看最新版本：Releases

⚙️ 进阶配置

1. 支付宝支付配置

推荐使用 “订单码支付”。

1. 回调地址配置：
   在支付宝后台配置网关地址和授权回调地址为：
   https://your-domain.com/api/v1/credit/callback/alipay
   (将 your-domain.com 替换为你的实际域名)

2. 私钥格式转换：
   支付宝工具生成的私钥需转换为 PKCS1 格式。

2. 自定义价格配置

(管理员面板 - 设置- 积分 - 自定义价格配置)
支持对请求 Body 内容进行正则匹配计费（如对 Web Search 额外收费）。

[
	{
		"name": "web_search", // 计费项名称
		"path": "$.tools[*].type", // JSONPath 路径
		"exists": false, // 是否仅检测存在性
		"value": "web_search_preview", // 匹配值
		"cost": 1000000 // 价格 (1M 次请求)
	}
]

3. 性能调优

如果遇到 Chunk too big 错误，可调整 HTTP Client Read Buffer：

# 默认 64KB，可根据需要增加
AIOHTTP_CLIENT_READ_BUFFER_SIZE=65536

4. 生产环境数据库配置 (PostgreSQL + Redis)

对于高并发场景（50+ 并发用户），建议使用 PostgreSQL + Redis 替代默认的 SQLite。

为什么需要升级？

数据库	并发写入	适用场景
SQLite	单写锁，高并发下性能急剧下降	< 50 并发用户
PostgreSQL	MVCC 多版本并发控制，支持高并发读写	50+ 并发用户

Redis 在本项目中用于：

• WebSocket 会话管理 - 多实例部署时共享用户连接状态
• 速率限制 - 滚动窗口算法实现 API 限流
• 分布式锁 - 防止并发任务冲突
• 实时协作 - 文档编辑 (Ydoc) 状态同步

Docker Compose 配置

创建 docker-compose.prod.yml：

services:
  postgres:
    image: postgres:16-alpine
    container_name: openwebui-postgres
    environment:
      POSTGRES_USER: openwebui
      POSTGRES_PASSWORD: your_secure_password
      POSTGRES_DB: openwebui
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U openwebui']
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: openwebui-redis
    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
    volumes:
      - redis_data:/data
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 5s
      retries: 5

  open-webui:
    image: ghcr.io/ovinc-cn/openwebui:<版本号>
    container_name: open-webui
    ports:
      - '3000:8080'
    environment:
      # PostgreSQL
      - DATABASE_URL=postgresql://openwebui:your_secure_password@postgres:5432/openwebui
      - DATABASE_POOL_SIZE=10
      - DATABASE_POOL_MAX_OVERFLOW=20

      # Redis
      - REDIS_URL=redis://redis:6379/0
      - WEBSOCKET_MANAGER=redis
      - WEBSOCKET_REDIS_URL=redis://redis:6379/1

      # 安全
      - WEBUI_SECRET_KEY=your_very_long_random_secret_key_here

      # LLM 后端
      - OLLAMA_BASE_URL=http://host.docker.internal:11434
      # - OPENAI_API_KEY=sk-xxx
    volumes:
      - open-webui:/app/backend/data
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    extra_hosts:
      - host.docker.internal:host-gateway
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:
  open-webui:

启动：

docker compose -f docker-compose.prod.yml up -d

环境变量说明

PostgreSQL 配置：

# 数据库连接 URL
DATABASE_URL=postgresql://user:password@host:5432/dbname

# 连接池配置 (高并发时调大)
DATABASE_POOL_SIZE=10              # 连接池大小，默认 5
DATABASE_POOL_MAX_OVERFLOW=20      # 最大溢出连接数
DATABASE_POOL_TIMEOUT=30           # 获取连接超时 (秒)
DATABASE_POOL_RECYCLE=3600         # 连接回收时间 (秒)

Redis 配置：

# Redis 连接
REDIS_URL=redis://localhost:6379/0
REDIS_KEY_PREFIX=open-webui        # 键前缀，多实例时区分

# WebSocket 使用 Redis 管理 (多实例部署必须)
WEBSOCKET_MANAGER=redis
WEBSOCKET_REDIS_URL=redis://localhost:6379/1

# Redis 集群模式 (可选)
REDIS_CLUSTER=false

# Redis Sentinel 高可用 (可选)
REDIS_SENTINEL_HOSTS=sentinel1,sentinel2,sentinel3
REDIS_SENTINEL_PORT=26379

从 SQLite 迁移数据

如果你已有 SQLite 数据需要迁移到 PostgreSQL：

# 1. 备份 SQLite 数据
cp data/webui.db data/webui.db.backup

# 2. 导出数据 (使用 pgloader 或手动导出)
# 方法一：使用 pgloader (推荐)
pgloader sqlite:///path/to/webui.db postgresql://user:pass@host/dbname

# 方法二：应用启动时自动迁移表结构，手动导出数据
sqlite3 data/webui.db .dump > dump.sql
# 然后手动调整 SQL 语法导入 PostgreSQL

性能调优建议

并发规模	PostgreSQL 配置	Redis 配置
50-100	POOL_SIZE=10	默认
100-300	POOL_SIZE=20, MAX_OVERFLOW=30	maxmemory 512mb
300+	POOL_SIZE=30, MAX_OVERFLOW=50	Redis Cluster 或 Sentinel

🛠️ 本地开发

如果你想参与开发或进行本地调试，可以按照以下步骤搭建开发环境。

环境要求

• Node.js 18-22.x（推荐使用 nvm-windows）
• Python 3.11 或 3.12
• Git

Windows 本地开发

1. 克隆项目

git clone https://github.com/ovinc-cn/openwebui.git
cd openwebui

2. 启动后端

# 创建并激活 Python 虚拟环境
cd backend
python -m venv venv
.\venv\Scripts\Activate.ps1    # PowerShell
# 或 .\venv\Scripts\activate.bat  # CMD

# 安装 Python 依赖
pip install -r requirements.txt

# (可选) 配置环境变量
copy ..\.env.example ..\.env
# 编辑 .env 配置 OLLAMA_BASE_URL, OPENAI_API_KEY 等

# 启动后端服务
python -m uvicorn open_webui.main:app --reload --host 0.0.0.0 --port 8080

3. 启动前端

# 新开一个终端，在项目根目录执行
npm install
npm run dev

4. 访问应用

地址	说明
http://localhost:5173	前端开发服务器（热重载）
http://localhost:8080/docs	后端 API Swagger 文档
http://localhost:8080	生产模式（后端提供静态文件）

Linux/macOS 本地开发

# 克隆项目
git clone https://github.com/ovinc-cn/openwebui.git
cd openwebui

# 后端
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m uvicorn open_webui.main:app --reload --port 8080

# 前端 (新终端)
npm install
npm run dev

常用开发命令

# 代码格式化 (提交前必须执行)
npm run format                # 格式化前端代码
npm run format:backend        # 格式化 Python 代码

# 代码检查
npm run lint                  # 运行所有 linter
npm run check                 # TypeScript/Svelte 类型检查

# 测试
npm run test:frontend         # Vitest 单元测试
npm run cy:open               # Cypress E2E 测试
cd backend && pytest          # Python 后端测试

# 国际化
npm run i18n:parse            # 提取 i18n 文本，需补充 zh-CN 翻译

环境变量

在项目根目录创建 .env 文件配置以下变量：

# LLM 后端
OLLAMA_BASE_URL=http://localhost:11434
OPENAI_API_BASE_URL=https://api.openai.com
OPENAI_API_KEY=sk-xxx

# 数据库 (默认 SQLite，无需配置)
DATABASE_URL=sqlite:///./data/webui.db

# Redis (套餐/会话管理需要)
REDIS_URL=redis://localhost:6379

# 安全
WEBUI_SECRET_KEY=your-secret-key

# 调试
GLOBAL_LOG_LEVEL=DEBUG

常见问题

问题	解决方案
Python 依赖安装失败	安装 Visual Studio Build Tools，勾选 "C++ 生成工具"
前端 API 请求 404	确保后端已启动，检查 vite.config.ts 中的代理配置
端口被占用	后端: --port 8081；前端: npm run dev -- --port 3000
Chunk too big 错误	设置 AIOHTTP_CLIENT_READ_BUFFER_SIZE=131072

📄 许可证

本项目基于 MIT License 开源。