Docker
对于单台服务器，Docker 是最简单的生产式部署方式。
若要在单台可从互联网访问的服务器上安装，请从私有远程部署开始。其 Compose 模板不公开任何应用端口，默认使用 main 镜像，并添加外层 Cloudflare Access 边界、主机控制、备份和容器限制。
Work 可用性
仓库的 Compose 文件默认启用 Work。镜像内置 Docker CLI，Compose 会挂载 /var/run/docker.sock，因此 Work 任务容器是 Libre WebUI 容器的同级容器。它们会出现在主机的 docker ps 中。
能访问该 socket 的进程拥有等同于 root 的 Docker 主机控制权。默认启用 Work 是有意的选择：Work 是核心功能，没有守护进程访问权限便无法运行。由此带来的后果是：每位 Libre WebUI 管理员实际上也是主机管理员。请据此规划：
- 将这套服务运行在其管理员均已受你信任的主机上。
- 不要向不受信任的网络开放已发布端口。
- 不需要 Work 时移除
/var/run/docker.sock挂载。之后 Work 页面会报告运行时不可用。
在 Linux 上，该 socket 属于 docker 组而不是 root，因此非 root 应用用户需要相应的组 ID。设置一次即可：
echo "DOCKER_GID=$(docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
alpine stat -c '%g' /var/run/docker.sock)" >> .env
请像上面一样通过容器读取它。macOS 主机报告的值与容器看到的值不同，因为 Docker Desktop 通过虚拟机代理 socket。如果组设置错误，Work 页面会明确指出问题，而不是静默失败。请参阅 Work：隔离工作区。
Work 预览和 Work Computer 只在私有的主机接口上发布随机端口。Docker Desktop 使用 Compose 默认值即可：绑定到主机环回地址，后端连接使用 host.docker.internal。原生 Docker Engine 无法从同级容器访问主机环回地址上的监听端口，请改为把绑定地址设为其非公开的 Docker 网桥网关：
echo "WORK_PREVIEW_BIND=$(docker network inspect bridge \
--format '{{(index .IPAM.Config 0).Gateway}}')" >> .env
echo "WORK_DOCKER_PUBLISHED_HOST=host.docker.internal" >> .env
docker compose up -d --force-recreate libre-webui
Compose 文件通过 host-gateway 映射 host.docker.internal。切勿使用 WORK_PREVIEW_BIND=0.0.0.0；那会把未经身份验证的临时任务端口发布到每个主机接口，而不是让它们留在 Libre WebUI 的签名代理之后。
捆绑 Ollama
在同一个 Compose 堆栈中运行 Libre WebUI 和 Ollama：
docker compose up -d
WebUI 端口默认绑定到主机环回地址。只有受信任的局域网或主机反向代理必须访问它时，才设置 WEBUI_BIND_ADDRESS=0.0.0.0，并使用主机防火墙限制该端口。
Ollama 仍只在 Compose 网络内可访问。若要让主机应用通过环回地址访问它，请添加显式主机覆盖：
docker compose -f docker-compose.yml -f docker-compose.ollama-host.yml up -d
只有其他机器必须访问 Ollama 时才设置 OLLAMA_BIND_ADDRESS，并使用防火墙和支持身份验证的代理保护该端口。
NVIDIA GPU
Docker 能访问 NVIDIA 运行时时，请使用 GPU Compose 文件：
docker compose -f docker-compose.gpu.yml up -d
如果模型仍在 CPU 上运行，请从 Ollama 容器内确认 GPU 访问权限。
外部 Ollama
当 Ollama 已在主机或另一台服务器上运行时使用：
docker compose -f docker-compose.external-ollama.yml up -d
如有需要，覆盖 Ollama URL：
OLLAMA_BASE_URL=http://192.168.1.10:11434 docker compose -f docker-compose.external-ollama.yml up -d
使用 socket 隔离的 Work
标准 Compose 文件会将 Docker socket 挂载到 Libre WebUI 容器，使 Work 能运行任务容器；该挂载相当于拥有 Docker 主机的 root 控制权。若要保留 Work，但不将 socket 交给 Web 应用，请使用 socket 代理变体：
docker compose -f docker-compose.socket-proxy.yml up -d
内部网络上的 socket 代理持有 /var/run/docker.sock，并只转发 Work 使用的 API 部分（容器、镜像、卷、网络、exec、info）。代理会拒绝 Swarm、secrets、configs、build 和 system 端点。Libre WebUI 通过 DOCKER_HOST=tcp://docker-socket-proxy:2375 访问它——不挂载 socket，不需要 DOCKER_GID，交互式终端和系统诊断功能也保持不变。此边界能覆盖和不能覆盖的范围请参阅工作区文档。
数据持久化
Libre WebUI 将后端数据存储在容器内的 /app/backend/data。Compose 文件会把该路径挂载为命名卷。
直接使用 docker run 启动镜像时，默认也使用该路径；数据库预检的临时数据则单独保存在 /app/backend/temp。只要容器可能被重新创建，就应挂载 /app/backend/data。
生产环境请设置稳定的机密：
JWT_SECRET=replace-with-a-long-random-secret
ENCRYPTION_KEY=replace-with-64-hex-characters
请一起备份数据卷和加密密钥。
移除由旧镜像直接启动的容器前，请确认 /app/backend/data/.encryption_key 存在，或记录已配置的 ENCRYPTION_KEY。旧镜像可能只把自动生成的密钥写入容器层；删除该容器也会删除唯一能解密其持久数据库的密钥。
如果运行自定义且支持 Work 的运行时，其任务文件位于单独的 Docker 命名卷中，不包含在常规 /app/backend/data 备份内。
公网访问
仓库的 Compose 文件会将 WebUI 绑定到环回地址，并直接设置 CORS_ORIGIN。shell 或 .env 文件中的值不会替换该字面量。请编辑 libre-webui.environment 条目，或将显式覆盖保存为 compose.origin.yml：
services:
libre-webui:
environment:
CORS_ORIGIN: https://your-domain.example
BASE_URL: https://your-domain.example
将覆盖文件与所选仓库 Compose 文件一起应用：
docker compose -f docker-compose.yml -f compose.origin.yml up -d
然后通过反向代理或平台负载均衡器，以 HTTPS 方式公开 Libre WebUI。将 WEBUI_BIND_ADDRESS 设置为代理确实需要的接口；除非防火墙要求如此，否则不要在所有接口上发布端口。
服务器本身已经高效地分发构建好的前端：/js/ 和 /assets/ 下带哈希的产物会以 brotli 或 gzip 压缩发送，并带有一年期的 immutable 缓存时长；而 index.html 和 Service Worker 会标记为 no-cache，因此新版本会在下一次加载时生效。代理无需对这些路径重新压缩或缓存；请让 Accept-Encoding 透传。
常用命令
docker compose ps
docker compose logs -f libre-webui
docker compose logs -f ollama
docker compose pull
docker compose up -d