Merge branch 'open-webui:dev' into dev

2026-03-26 13:18:42 +07:00 · 2026-02-04 18:45:41 +01:00
parent 6ecf9275e4 1b8ad69811
commit 9a6afbe143
2 changed files with 248 additions and 6 deletions
--- a/docs/getting-started/env-configuration.mdx
+++ b/docs/getting-started/env-configuration.mdx
@@ -5242,39 +5242,127 @@ For API Key creation (and the API keys themselves) to work, you need **both**:
 - Description: Enables or disables user permission to access workspace tools.
 - Persistence: This environment variable is a `PersistentConfig` variable.

+### Sharing (Private)
+
+These settings control whether users can share workspace items with other users **privately** (non-public sharing).
+
+#### `USER_PERMISSIONS_WORKSPACE_MODELS_ALLOW_SHARING`
+
+- Type: `str`
+- Default: `False`
+- Description: Enables or disables **private sharing** of workspace models.
+- Persistence: This environment variable is a `PersistentConfig` variable.
+
+#### `USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ALLOW_SHARING`
+
+- Type: `str`
+- Default: `False`
+- Description: Enables or disables **private sharing** of workspace knowledge.
+- Persistence: This environment variable is a `PersistentConfig` variable.
+
+#### `USER_PERMISSIONS_WORKSPACE_PROMPTS_ALLOW_SHARING`
+
+- Type: `str`
+- Default: `False`
+- Description: Enables or disables **private sharing** of workspace prompts.
+- Persistence: This environment variable is a `PersistentConfig` variable.
+
+#### `USER_PERMISSIONS_WORKSPACE_TOOLS_ALLOW_SHARING`
+
+- Type: `str`
+- Default: `False`
+- Description: Enables or disables **private sharing** of workspace tools.
+- Persistence: This environment variable is a `PersistentConfig` variable.
+
+#### `USER_PERMISSIONS_NOTES_ALLOW_SHARING`
+
+- Type: `str`
+- Default: `True`
+- Description: Enables or disables **private sharing** of notes.
+- Persistence: This environment variable is a `PersistentConfig` variable.
+
+### Sharing (Public)
+
+These settings control whether users can share workspace items **publicly**.
+
 #### `USER_PERMISSIONS_WORKSPACE_MODELS_ALLOW_PUBLIC_SHARING`

 - Type: `str`
 - Default: `False`
- Description: Enables or disables public sharing of workspace models.
+- Description: Enables or disables **public sharing** of workspace models.
 - Persistence: This environment variable is a `PersistentConfig` variable.

 #### `USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ALLOW_PUBLIC_SHARING`

 - Type: `str`
 - Default: `False`
- Description: Enables or disables public sharing of workspace knowledge.
+- Description: Enables or disables **public sharing** of workspace knowledge.
 - Persistence: This environment variable is a `PersistentConfig` variable.

 #### `USER_PERMISSIONS_WORKSPACE_PROMPTS_ALLOW_PUBLIC_SHARING`

 - Type: `str`
 - Default: `False`
- Description: Enables or disables public sharing of workspace prompts.
+- Description: Enables or disables **public sharing** of workspace prompts.
 - Persistence: This environment variable is a `PersistentConfig` variable.

 #### `USER_PERMISSIONS_WORKSPACE_TOOLS_ALLOW_PUBLIC_SHARING`

 - Type: `str`
 - Default: `False`
- Description: Enables or disables public sharing of workspace tools.
+- Description: Enables or disables **public sharing** of workspace tools.
 - Persistence: This environment variable is a `PersistentConfig` variable.

 #### `USER_PERMISSIONS_NOTES_ALLOW_PUBLIC_SHARING`

 - Type: `str`
 - Default: `True`
- Description: Enables or disables public sharing of notes.
+- Description: Enables or disables **public sharing** of notes.
+- Persistence: This environment variable is a `PersistentConfig` variable.
+
+### Import / Export
+
+#### `USER_PERMISSIONS_WORKSPACE_MODELS_IMPORT`
+
+- Type: `str`
+- Default: `True`
+- Description: Enables or disables user permission to import workspace models.
+- Persistence: This environment variable is a `PersistentConfig` variable.
+
+#### `USER_PERMISSIONS_WORKSPACE_MODELS_EXPORT`
+
+- Type: `str`
+- Default: `True`
+- Description: Enables or disables user permission to export workspace models.
+- Persistence: This environment variable is a `PersistentConfig` variable.
+
+#### `USER_PERMISSIONS_WORKSPACE_PROMPTS_IMPORT`
+
+- Type: `str`
+- Default: `True`
+- Description: Enables or disables user permission to import workspace prompts.
+- Persistence: This environment variable is a `PersistentConfig` variable.
+
+#### `USER_PERMISSIONS_WORKSPACE_PROMPTS_EXPORT`
+
+- Type: `str`
+- Default: `True`
+- Description: Enables or disables user permission to export workspace prompts.
+- Persistence: This environment variable is a `PersistentConfig` variable.
+
+#### `USER_PERMISSIONS_WORKSPACE_TOOLS_IMPORT`
+
+- Type: `str`
+- Default: `False`
+- Description: Enables or disables user permission to import workspace tools.
+- Persistence: This environment variable is a `PersistentConfig` variable.
+
+#### `USER_PERMISSIONS_WORKSPACE_TOOLS_EXPORT`
+
+- Type: `str`
+- Default: `False`
+- Description: Enables or disables user permission to export workspace tools.
+- Persistence: This environment variable is a `PersistentConfig` variable.

 ### Settings Permissions

@@ -5801,6 +5889,46 @@ If you're running Open WebUI as a single instance with `UVICORN_WORKERS=1` (the

 :::

+:::danger
+
+**Critical Redis Server Configuration — Prevent Connection Exhaustion**
+
+Open WebUI uses Redis for token validation, WebSocket management, and session storage. Each user action can create Redis connections. If your Redis server is misconfigured, connections will accumulate over time until the limit is reached, causing **500 Internal Server Errors** and preventing all users from logging in.
+
+**You must configure these settings in your `redis.conf` (not Open WebUI environment variables):**
+
+| Setting | Bad Default | Recommended | Why |
+|---------|-------------|-------------|-----|
+| `maxclients` | 1000 (some distros) | `10000` or higher | Low limits cause "max number of clients reached" errors |
+| `timeout` | 0 (never close) | `1800` (30 minutes) | Without timeout, idle connections accumulate forever |
+
+**Example `redis.conf` settings:**
+```conf
+maxclients 10000
+timeout 1800
+```
+
+**Symptoms of this misconfiguration:**
+- Works fine for days/weeks, then suddenly all logins fail with 500 errors
+- `redis.exceptions.ConnectionError: max number of clients reached` in logs
+- Problem appears to "fix itself" temporarily, then returns
+
+**Why this happens:**
+With `timeout 0`, every Redis connection stays open indefinitely. Over days or weeks, connections from token checks, WebSocket events, and session validations accumulate. Once `maxclients` is reached, no new connections can be made, and authentication fails completely.
+
+**To check your current connection count:**
+```bash
+redis-cli INFO clients | grep connected_clients
+```
+
+**To verify your settings:**
+```bash
+redis-cli CONFIG GET maxclients
+redis-cli CONFIG GET timeout
+```
+
+:::
+
 #### `REDIS_SENTINEL_HOSTS`

 - Type: `str`
--- a/docs/tutorials/integrations/redis.md
+++ b/docs/tutorials/integrations/redis.md
@@ -63,6 +63,70 @@ Without Redis in multi-worker or multi-instance scenarios, you will experience:
 - A Docker network for communication between Open WebUI and Redis
 - Basic understanding of Docker, Redis, and Open WebUI

+### Critical: Redis Server Configuration
+
+:::danger
+
+**Prevent "Max Number of Clients Reached" Errors**
+
+Before configuring Open WebUI to use Redis, you **must** ensure your Redis server itself is properly configured. A common misconfiguration causes connections to accumulate over time, eventually exhausting the connection limit and causing **complete authentication failure** (500 Internal Server Error for all users).
+
+**The Problem:**
+
+Open WebUI uses Redis for:
+- Token validation/revocation checking (every authenticated request)
+- WebSocket management (real-time updates)
+- Session storage (if `ENABLE_STAR_SESSIONS_MIDDLEWARE` is enabled)
+
+With default Redis settings on some distributions (`maxclients 1000`, `timeout 0`), connections are never closed. Over days or weeks, they accumulate silently until the limit is reached. Then, suddenly, no one can log in.
+
+**The Symptoms:**
+- Application works fine for days/weeks
+- Suddenly, all users get 500 Internal Server Error on login
+- Error in logs: `redis.exceptions.ConnectionError: max number of clients reached`
+- May temporarily "fix itself" as old connections eventually die, then fail again
+
+**The Solution:**
+
+Add these settings to your Redis configuration:
+
+```conf
+# Allow sufficient concurrent connections
+maxclients 10000
+
+# Close idle connections after 30 minutes (1800 seconds)
+# This does NOT affect session validity — only the TCP connection to Redis
+timeout 1800
+```
+
+**For Docker deployments**, add to your Redis command:
+
+```yml
+services:
+  redis:
+    image: docker.io/valkey/valkey:8.0.1-alpine
+    command: "valkey-server --save 30 1 --maxclients 10000 --timeout 1800"
+    # ... rest of config
+```
+
+**Why `timeout 1800` is safe:**
+
+The timeout only affects idle Redis TCP connections, not user sessions. When a connection times out:
+- The user's JWT token remains valid
+- Their session is not affected
+- The next request simply opens a new Redis connection (adds ~1-5ms, imperceptible)
+
+**Monitoring:**
+
+Check current connection count:
+```bash
+redis-cli INFO clients | grep connected_clients
+```
+
+With proper `timeout` configuration, this number should fluctuate naturally (rising during active hours, falling during quiet periods) rather than climbing indefinitely.
+
+:::
+
 ## Setting up Redis

 To set up Redis for websocket support, you will need to create a `docker-compose.yml` file with the following contents:
@@ -75,7 +139,7 @@ services:
    container_name: redis-valkey
    volumes:
      - redis-data:/data
-    command: "valkey-server --save 30 1"
+    command: "valkey-server --save 30 1 --maxclients 10000 --timeout 1800"
    healthcheck:
      test: "[ $$(valkey-cli ping) = 'PONG' ]"
      start_period: 5s
@@ -113,6 +177,8 @@ The `ports` directive is not included in this configuration, as it is not necess

 The above configuration sets up a Redis container named `redis-valkey` and mounts a volume for data persistence. The `healthcheck` directive ensures that the container is restarted if it fails to respond to the `ping` command. The `--save 30 1` command option saves the Redis database to disk every 30 minutes if at least 1 key has changed.

+**Important:** The `--maxclients 10000 --timeout 1800` flags prevent connection exhaustion. See the "Critical: Redis Server Configuration" section above for details.
+
 :::

 To create a Docker network for communication between Open WebUI and Redis, run the following command:
@@ -506,6 +572,54 @@ REDIS_KEY_PREFIX="openwebui-dev"
 2. Monitor Redis memory: `docker exec -it redis-valkey valkey-cli info memory`
 3. Clear old keys if needed: `docker exec -it redis-valkey valkey-cli FLUSHDB`

+#### Issue: "max number of clients reached" after days/weeks of operation
+
+**Symptoms:**
+
+- Application worked fine for an extended period, then suddenly fails
+- All login attempts return 500 Internal Server Error
+- Error in logs: `redis.exceptions.ConnectionError: max number of clients reached`
+- May temporarily recover, then fail again
+
+**Cause:** Redis `maxclients` limit reached due to connection accumulation. This happens when:
+- `timeout` is set to `0` (connections never close)
+- `maxclients` is too low for your usage pattern
+
+**Solution:**
+
+1. Check current connection count:
+   ```bash
+   redis-cli INFO clients | grep connected_clients
+   ```
+
+2. Check current settings:
+   ```bash
+   redis-cli CONFIG GET maxclients
+   redis-cli CONFIG GET timeout
+   ```
+
+3. Fix the configuration:
+   ```bash
+   redis-cli CONFIG SET maxclients 10000
+   redis-cli CONFIG SET timeout 1800
+   ```
+
+4. Make permanent by adding to `redis.conf` or Docker command:
+   ```conf
+   maxclients 10000
+   timeout 1800
+   ```
+
+5. Restart Redis to clear accumulated connections:
+   ```bash
+   # For systemd
+   sudo systemctl restart redis
+   
+   # For Docker
+   docker restart redis-valkey
+
+**Prevention:** Always configure `timeout` to a reasonable value (e.g., 1800 seconds). The timeout only affects idle TCP connections, not user sessions — it's safe and recommended.
+
 ### Additional Resources

 - [Redis Documentation](https://redis.io/docs)