sillytavern-repalice/DOCKER-BUILD-GUIDE.md

Docker 构建最终解决方案

🎯 核心改进

自动镜像源 Fallback 机制

现在的 Dockerfile 会自动尝试三个国内镜像源：

1. 阿里云镜像 (https://registry.npmmirror.com) - 首选
2. 腾讯云镜像 (https://mirrors.cloud.tencent.com/npm/) - 备选
3. 华为云镜像 (https://repo.huaweicloud.com/repository/npm/) - 最后备选

如果第一个镜像源失败，会自动切换到下一个，无需手动干预！

🚀 立即开始构建

步骤 1：清理旧缓存

docker system prune -a --volumes -f
docker builder prune -a -f

步骤 2：重新构建

# 使用 PowerShell 脚本（推荐）
.\build-docker.ps1

# 或者直接使用 docker-compose
docker-compose build --no-cache

步骤 3：启动服务

docker-compose up -d

📊 构建过程说明

构建时您会看到类似这样的输出：

# Backend Builder
Trying Aliyun mirror...
[如果阿里云成功，继续构建]
[如果阿里云失败，显示:]
Aliyun failed, trying Tencent Cloud...
[如果腾讯云成功，继续构建]
[如果腾讯云失败，显示:]
Tencent failed, trying Huawei Cloud...

🔍 故障排除

问题 1：所有镜像源都失败

可能原因：

• 网络连接完全中断
• 防火墙阻止了所有镜像源

解决方案：

# 测试网络连接
npm ping --registry=https://registry.npmmirror.com
npm ping --registry=https://mirrors.cloud.tencent.com/npm/
npm ping --registry=https://repo.huaweicloud.com/repository/npm/

# 检查防火墙设置
# 确保允许访问这些域名

问题 2：构建速度很慢

可能原因：

• 正在使用较慢的镜像源
• 首次构建需要下载大量依赖

解决方案：

• 等待构建完成，后续构建会使用缓存
• 或者切换到更快的镜像源（见下方）

问题 3：内存不足

错误信息：JavaScript heap out of memory

解决方案： 在 Docker Desktop 中增加内存分配：

1. Settings → Resources → Advanced
2. 将 Memory 设置为至少 4GB

💡 手动切换镜像源（可选）

如果想手动指定镜像源，可以运行：

.\switch-npm-mirror.bat

然后选择：

• 1 - 阿里云（默认）
• 2 - 腾讯云
• 3 - 华为云

📝 验证构建成功

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

# 应该看到：
# sillytavern-repalice-backend
# sillytavern-repalice-frontend

🎉 访问应用

构建完成后：

• 前端: http://localhost:5173
• 后端: http://localhost:3000

查看日志：

docker-compose logs -f

⚙️ 技术细节

Dockerfile 改进

之前：

RUN cd server && npm install

现在：

RUN cd server && \
    npm install --registry=https://registry.npmmirror.com || \
    npm install --registry=https://mirrors.cloud.tencent.com/npm/ || \
    npm install --registry=https://repo.huaweicloud.com/repository/npm/

优势

1. ✅ 自动化：无需手动切换镜像源
2. ✅ 容错性：一个失败自动尝试下一个
3. ✅ 速度优化：使用 --prefer-offline、--no-audit、--no-fund
4. ✅ 可靠性：三个镜像源保证至少有一个可用

🆘 仍然有问题？

如果以上方案都不起作用，请提供：

1. 完整的构建日志：

   docker-compose build --no-cache > build.log 2>&1
   

2. 网络测试结果：

   .\test-npm-registry.bat
   

3. 系统信息：

   docker --version
   docker-compose --version
   

---

祝构建顺利！ 🚀