前端修饰与渲染处理

TROUBLESHOOTING.md

@@ -0,0 +1,157 @@
+# 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，适合快速开发和测试。