158 lines
3.5 KiB
Markdown
158 lines
3.5 KiB
Markdown
# Docker 构建故障排除指南（中国大陆用户）
|
||
|
||
## 问题：Docker 构建在 `npm install` 步骤卡死
|
||
|
||
### 已实施的解决方案
|
||
|
||
1. ✅ 使用 `.npmrc` 文件配置国内镜像源
|
||
2. ✅ 简化 Dockerfile，移除 BuildKit cache mount
|
||
3. ✅ 添加重试机制的构建脚本
|
||
|
||
### 如果仍然卡死，请尝试以下步骤：
|
||
|
||
#### 方案 1：测试 npm 镜像源连接
|
||
|
||
```bash
|
||
# Windows (PowerShell)
|
||
npm ping --registry=https://registry.npmmirror.com
|
||
|
||
# 如果成功，会显示类似：
|
||
# Ping success: { ... }
|
||
```
|
||
|
||
或者运行测试脚本：
|
||
```bash
|
||
.\test-npm-registry.bat
|
||
```
|
||
|
||
#### 方案 2：更换其他国内镜像源
|
||
|
||
如果 `registry.npmmirror.com` 不可用，可以尝试其他镜像：
|
||
|
||
编辑 `server/.npmrc` 和 `client/.npmrc`，将第一行改为：
|
||
|
||
```
|
||
# 淘宝镜像（旧版，可能不稳定）
|
||
registry=https://registry.npm.taobao.org
|
||
|
||
# 或者腾讯云镜像
|
||
registry=https://mirrors.cloud.tencent.com/npm/
|
||
|
||
# 或者华为云镜像
|
||
registry=https://repo.huaweicloud.com/repository/npm/
|
||
```
|
||
|
||
#### 方案 3：手动构建（不使用 docker-compose）
|
||
|
||
```bash
|
||
# 清理旧构建
|
||
docker system prune -a --volumes
|
||
docker builder prune -a
|
||
|
||
# 单独构建后端（查看详细日志）
|
||
docker build --no-cache --progress=plain -t sillytavern-repalice-backend -f docker/backend.Dockerfile .
|
||
|
||
# 单独构建前端
|
||
docker build --no-cache --progress=plain -t sillytavern-repalice-frontend -f docker/frontend.Dockerfile .
|
||
```
|
||
|
||
#### 方案 4：增加 Docker 超时时间
|
||
|
||
在 Docker Desktop 中：
|
||
1. 打开 Settings → Docker Engine
|
||
2. 添加以下配置：
|
||
|
||
```json
|
||
{
|
||
"builder": {
|
||
"gc": {
|
||
"enabled": true,
|
||
"defaultKeepStorage": "20GB"
|
||
}
|
||
},
|
||
"features": {
|
||
"buildkit": true
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 方案 5：使用本地 node_modules（临时方案）
|
||
|
||
如果 Docker 构建一直失败，可以先在本地安装依赖：
|
||
|
||
```bash
|
||
# 在本地安装依赖
|
||
cd server && npm install
|
||
cd ../client && npm install
|
||
|
||
# 然后修改 Dockerfile 使用 COPY 而不是 RUN npm install
|
||
# （这种方式不推荐用于生产环境，但可以用于调试）
|
||
```
|
||
|
||
### 常见错误及解决方案
|
||
|
||
#### 错误 1：ETIMEDOUT / ECONNRESET
|
||
**原因**：网络连接超时
|
||
**解决**：检查防火墙设置，或更换镜像源
|
||
|
||
#### 错误 2：ENOMEM / JavaScript heap out of memory
|
||
**原因**：Docker 内存不足
|
||
**解决**：在 Docker Desktop 中增加内存分配（建议至少 4GB）
|
||
|
||
#### 错误 3：ENOENT: no such file or directory
|
||
**原因**：文件路径问题
|
||
**解决**：确保 `.npmrc` 文件存在且路径正确
|
||
|
||
### 验证构建是否成功
|
||
|
||
```bash
|
||
# 查看镜像列表
|
||
docker images | grep sillytavern-repalice
|
||
|
||
# 应该看到两个镜像：
|
||
# sillytavern-repalice-backend
|
||
# sillytavern-repalice-frontend
|
||
```
|
||
|
||
### 启动服务
|
||
|
||
```bash
|
||
# 启动所有服务
|
||
docker-compose up -d
|
||
|
||
# 查看日志
|
||
docker-compose logs -f
|
||
|
||
# 访问应用
|
||
# 前端: http://localhost:5173
|
||
# 后端: http://localhost:3000
|
||
```
|
||
|
||
### 获取帮助
|
||
|
||
如果以上方案都不起作用，请提供以下信息：
|
||
|
||
1. Docker 版本：`docker --version`
|
||
2. Docker Compose 版本：`docker-compose --version`
|
||
3. 操作系统版本
|
||
4. 完整的错误日志：`docker-compose build --no-cache > build.log 2>&1`
|
||
5. npm ping 测试结果
|
||
|
||
### 备用方案：本地开发模式
|
||
|
||
如果 Docker 构建实在无法完成，可以使用本地开发模式：
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发服务器
|
||
npm run dev
|
||
|
||
# 访问应用
|
||
# 前端: http://localhost:5173
|
||
# 后端: http://localhost:3000
|
||
```
|
||
|
||
这种方式不需要 Docker，适合快速开发和测试。
|