# 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，适合快速开发和测试。