sillytavern-repalice/TROUBLESHOOTING.md

Docker 构建故障排除指南（中国大陆用户）

问题：Docker 构建在 npm install 步骤卡死

已实施的解决方案

1. ✅ 使用 .npmrc 文件配置国内镜像源
2. ✅ 简化 Dockerfile，移除 BuildKit cache mount
3. ✅ 添加重试机制的构建脚本

如果仍然卡死，请尝试以下步骤：

方案 1：测试 npm 镜像源连接

# Windows (PowerShell)
npm ping --registry=https://registry.npmmirror.com

# 如果成功，会显示类似：
# Ping success: { ... }

或者运行测试脚本：

.\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）

# 清理旧构建
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. 添加以下配置：

{
  "builder": {
    "gc": {
      "enabled": true,
      "defaultKeepStorage": "20GB"
    }
  },
  "features": {
    "buildkit": true
  }
}

方案 5：使用本地 node_modules（临时方案）

如果 Docker 构建一直失败，可以先在本地安装依赖：

# 在本地安装依赖
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 文件存在且路径正确

验证构建是否成功

# 查看镜像列表
docker images | grep sillytavern-repalice

# 应该看到两个镜像：
# sillytavern-repalice-backend
# sillytavern-repalice-frontend

启动服务

# 启动所有服务
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 构建实在无法完成，可以使用本地开发模式：

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 访问应用
# 前端: http://localhost:5173
# 后端: http://localhost:3000

这种方式不需要 Docker，适合快速开发和测试。