mirror of
https://github.com/open-webui/open-webui.git
synced 2025-12-13 12:55:19 +00:00
6.2 KiB
6.2 KiB
构建脚本使用指南
本目录包含用于本地构建和推送 Docker 镜像的自动化脚本。
脚本列表
1. build-and-push.sh - 完整构建和推送流程 (推荐)
功能: 完整的构建、测试、推送流程,包含健康检查
使用方法:
# 1. 登录 GHCR (如需推送)
export CR_PAT=YOUR_PERSONAL_ACCESS_TOKEN
echo $CR_PAT | docker login ghcr.io -u ai-friend-coming --password-stdin
# 2. 运行脚本
./scripts/build-and-push.sh
流程:
- 检查 Git 状态和未提交更改
- 构建 Docker 镜像 (slim 版本)
- 验证镜像大小和 ID
- 运行健康检查测试 (可选)
- 推送镜像到 GHCR (需确认)
- 清理构建缓存 (可选)
适用场景: 正式发布前的完整测试和推送
2. quick-build.sh - 快速本地构建
功能: 快速构建镜像用于本地测试,不推送
使用方法:
./scripts/quick-build.sh
特点:
- 无交互式确认
- 仅构建,不推送
- 构建速度快 (如有缓存)
适用场景: 本地开发和快速测试
3. simulate-workflow.sh - 模拟 GitHub Actions
功能: 完整模拟 .github/workflows/docker-build.yaml 的执行流程
使用方法:
# 设置 CR_PAT (可选)
export CR_PAT=YOUR_PERSONAL_ACCESS_TOKEN
# 运行模拟
./scripts/simulate-workflow.sh
特点:
- 模拟 GitHub Actions 环境变量
- 创建独立的 Buildx builder
- 使用 registry 缓存
- 输出格式与 GitHub Actions 一致
适用场景:
- 测试 workflow 配置
- 在推送代码前验证构建流程
- 排查 CI/CD 问题
使用示例
场景 1: 本地快速测试
# 1. 快速构建
./scripts/quick-build.sh
# 2. 运行测试
docker run -d -p 8080:8080 ghcr.io/ai-friend-coming/open-webui-next:slim
# 3. 验证
curl http://localhost:8080/health
场景 2: 发布新版本
# 1. 确保代码已提交
git add .
git commit -m "feat: add new feature"
git push
# 2. 登录 GHCR
export CR_PAT=ghp_xxxxxxxxxxxx
echo $CR_PAT | docker login ghcr.io -u ai-friend-coming --password-stdin
# 3. 构建和推送
./scripts/build-and-push.sh
# 按提示操作: 运行健康检查 → 确认推送 → 清理缓存
# 4. 验证推送成功
docker pull ghcr.io/ai-friend-coming/open-webui-next:slim
场景 3: 测试 GitHub Actions workflow
# 1. 模拟 workflow 执行
export CR_PAT=ghp_xxxxxxxxxxxx
./scripts/simulate-workflow.sh
# 2. 查看构建结果
docker images | grep open-webui-next
# 3. 如果成功,推送代码触发真实 workflow
git push origin main
环境要求
必需软件
- Docker: 24.0.0+
- Docker Buildx: v0.11.0+
- Git: 任意版本
- Bash: 4.0+
系统要求
- 内存: 建议 8GB+
- 磁盘空间: 至少 20GB 可用空间
- 网络: 需要访问 ghcr.io
Docker 配置
确保 Docker 有足够的资源:
# Docker Desktop 配置 (推荐):
# - Memory: 8GB
# - Swap: 2GB
# - Disk image size: 64GB
常见问题
1. 构建失败 - 内存不足
错误信息:
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
解决方案:
- 确认
Dockerfile第 30 行已启用:ENV NODE_OPTIONS="--max-old-space-size=4096" - 增加 Docker Desktop 内存限制到 8GB+
2. 推送失败 - 未登录
错误信息:
unauthorized: authentication required
解决方案:
# 设置 PAT
export CR_PAT=ghp_your_token_here
# 登录 GHCR
echo $CR_PAT | docker login ghcr.io -u ai-friend-coming --password-stdin
3. 脚本无执行权限
错误信息:
Permission denied
解决方案:
chmod +x scripts/*.sh
4. Buildx 不可用
错误信息:
ERROR: buildx: command not found
解决方案:
# 安装 Buildx 插件
docker buildx install
# 或更新 Docker Desktop 到最新版本
标签规则
所有脚本都会生成以下标签:
| 标签格式 | 示例 | 说明 |
|---|---|---|
slim |
ghcr.io/ai-friend-coming/open-webui-next:slim |
主标签 (main 分支) |
latest-slim |
ghcr.io/ai-friend-coming/open-webui-next:latest-slim |
最新版本 (仅 main 分支) |
{branch}-slim |
ghcr.io/ai-friend-coming/open-webui-next:main-slim |
分支标签 |
git-{sha}-slim |
ghcr.io/ai-friend-coming/open-webui-next:git-88396a1-slim |
Git commit 标签 |
安全最佳实践
PAT (Personal Access Token) 管理
- 权限设置: 仅授予
read:packages和write:packages - 存储位置: 使用环境变量,不要硬编码到脚本
- 轮换周期: 建议每 90 天轮换一次
- 作用域: 为不同用途创建不同的 PAT
环境变量设置
# 临时设置 (当前会话)
export CR_PAT=ghp_xxxxxxxxxxxx
# 永久设置 (添加到 ~/.bashrc 或 ~/.zshrc)
echo 'export CR_PAT=ghp_xxxxxxxxxxxx' >> ~/.bashrc
source ~/.bashrc
注意: 不要提交 PAT 到 Git 仓库
性能优化
使用构建缓存
# 第一次构建会较慢 (5-10 分钟)
./scripts/build-and-push.sh
# 后续构建会使用缓存 (1-2 分钟)
# 前提: 没有清理缓存
并行构建 (高级)
如果需要同时构建多个变体:
# 构建 slim 和 cuda 版本
docker buildx build --build-arg USE_SLIM=true -t IMAGE:slim . &
docker buildx build --build-arg USE_CUDA=true -t IMAGE:cuda . &
wait
清理命令
清理所有本地镜像
# 删除所有 open-webui-next 镜像
docker images | grep open-webui-next | awk '{print $3}' | xargs docker rmi -f
# 清理悬空镜像
docker image prune -f
# 清理所有未使用的镜像
docker image prune -a -f
清理构建缓存
# 清理 Buildx 缓存
docker buildx prune -f
# 清理所有 Docker 数据 (谨慎使用)
docker system prune -a --volumes -f
相关文档
获取帮助
如果遇到问题:
- 查看脚本输出的错误信息
- 参考本文档的"常见问题"部分
- 查看详细文档:
docs/LOCAL-PUSH-GUIDE.md - 提交 Issue: https://github.com/ai-friend-coming/open-webui-next/issues
最后更新: 2024-11-14