Wang Defa
9afe4a8649
All checks were successful
Build and Release / build-and-test (arm64, alpine) (push) Successful in -13s
Build and Release / build-and-test (amd64, alpine) (push) Successful in -6s
Build and Release / build-and-test (arm64, ubuntu) (push) Successful in -7s
Build and Release / build-and-test (amd64, ubuntu) (push) Successful in 7s
Build and Release / release (push) Successful in 21s
- 将 Debian 包仓库从 bookworm/trixie 双发行版改为通用 stable 仓库 - 新增完整的 llmdoc 文档系统，包含架构、指南和参考文档 - 更新 README.md 和部署指南以反映新的仓库配置 - 添加 .gitignore 文件
60 lines
1.2 KiB
Markdown
60 lines
1.2 KiB
Markdown
# Docker 构建问题排查指南
|
||
|
||
## 常见构建错误
|
||
|
||
### 1. 依赖安装失败
|
||
**症状**：软件包无法下载或安装
|
||
|
||
**解决方案**：
|
||
- 检查网络连接
|
||
- 更新 `sources.list` 或 `repositories`
|
||
- 手动安装缺失依赖
|
||
- 检查架构兼容性
|
||
|
||
### 2. 交叉编译问题
|
||
**症状**：编译过程中出现架构不兼容错误
|
||
|
||
**诊断步骤**：
|
||
- 验证交叉编译工具链
|
||
- 检查 `CMakeLists.txt` 配置
|
||
- 降低并行编译作业数
|
||
- 查看完整编译日志
|
||
|
||
### 3. BuildX 配置问题
|
||
**症状**：多架构构建失败
|
||
|
||
**排查清单**：
|
||
- 确认 BuildX 实例正常
|
||
- 检查 `--platform` 参数
|
||
- 验证 Docker 版本兼容性
|
||
- 重置 BuildX 实例
|
||
|
||
### 4. 镜像大小异常
|
||
**症状**：构建镜像unexpectedly大
|
||
|
||
**优化建议**：
|
||
- 使用多阶段构建
|
||
- 删除不必要的构建缓存
|
||
- 精简基础镜像
|
||
- 仅复制必要的二进制文件
|
||
|
||
## 调试工具和命令
|
||
|
||
### BuildX 诊断
|
||
```bash
|
||
docker buildx ls
|
||
docker buildx inspect
|
||
docker buildx debug
|
||
```
|
||
|
||
### 构建日志分析
|
||
```bash
|
||
docker buildx build --progress=plain
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
- 始终使用 `--no-cache` 进行初始调试
|
||
- 保持 Dockerfile 简洁
|
||
- 定期更新基础镜像和依赖
|
||
- 遵循最小权限原则 |