openwebui/README.md

<div align="center">
  <a href="https://github.com/open-webui/open-webui">
    <img src="./static/favicon.png" alt="Logo" width="100" height="100">
  </a>

  <h1 align="center">Open WebUI (OVINC-CN)</h1>

  <p align="center">
    <strong>基于 Open WebUI 的增强版：集成计费、支付与企业级用户管理</strong>
  </p>

  <p align="center">
    <a href="https://github.com/ovinc-cn/openwebui/releases">
      <img src="https://img.shields.io/github/v/release/ovinc-cn/openwebui?style=flat-square" alt="Release">
    </a>
    <a href="https://github.com/open-webui/open-webui/blob/main/LICENSE">
      <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License">
    </a>
    <a href="https://github.com/ovinc-cn/openwebui/pkgs/container/openwebui">
      <img src="https://img.shields.io/badge/container-ghcr.io-blue?style=flat-square&logo=github" alt="GHCR">
    </a>
  </p>

  <br />
</div>

> ⚠️ **注意**：此仓库的 `dev` 分支是开发分支，可能包含不稳定功能。生产环境请务必使用 [Release](https://github.com/ovinc-cn/openwebui/releases) 中的正式版本。
> 本项目是 [Open WebUI](https://github.com/open-webui/open-webui) 的定制分支，与官方团队无关联。

## 📖 简介

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

## ✨ 核心特性

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

完整特性列表请参阅 [CHANGELOG_EXTRA.md](./CHANGELOG_EXTRA.md)。

## 📸 功能预览

<details>
<summary>点击展开查看更多截图</summary>

### 积分报表与全局设置

|                积分报表                |                  全局设置                  |
| :------------------------------------: | :----------------------------------------: |
| ![usage panel](./docs/usage_panel.png) | ![credit config](./docs/credit_config.png) |

### 用户充值与计费详情

|                用户充值                |          计费详情          |
| :------------------------------------: | :------------------------: |
| ![user credit](./docs/user_credit.png) | ![usage](./docs/usage.png) |

### 兑换码与注册验证

|                  兑换码                   |               邮箱验证                |
| :---------------------------------------: | :-----------------------------------: |
| ![redemption code](./docs/redemption.png) | ![email](./docs/sign_verify_user.png) |

</details>

## 🚀 快速部署

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

```bash
# 拉取最新镜像（请将 <版本号> 替换为具体版本，如 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](https://github.com/ovinc-cn/openwebui/releases/latest)

## ⚙️ 进阶配置

### 1. 支付宝支付配置

推荐使用 [“订单码支付”](https://open.alipay.com/api/detail?code=I1080300001000068149&index=0)。

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

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

### 2. 自定义价格配置

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

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

### 3. 性能调优

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

```env
# 默认 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`：

```yaml
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:
```

启动：

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

#### 环境变量说明

**PostgreSQL 配置：**

```env
# 数据库连接 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 配置：**

```env
# 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：

```bash
# 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](https://github.com/coreybutler/nvm-windows)）
- **Python** 3.11 或 3.12
- **Git**

### Windows 本地开发

#### 1. 克隆项目

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

#### 2. 启动后端

```powershell
# 创建并激活 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. 启动前端

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

#### 4. 访问应用

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

### Linux/macOS 本地开发

```bash
# 克隆项目
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
```

### 常用开发命令

```bash
# 代码格式化 (提交前必须执行)
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` 文件配置以下变量：

```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](https://visualstudio.microsoft.com/visual-cpp-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](./LICENSE) 开源。