auto-deploy-demo/TROUBLESHOOTING.md

# 部署问题排查指南

## 问题描述

访问项目时出现 404 或 500 错误，Nginx 配置未正确生成或生效。

---

## 排查步骤

### 1. 检查容器是否正常运行

```bash
# 查看容器状态
docker ps | grep auto-deploy-demo

# 查看容器日志
docker logs auto-deploy-demo

# 查看最近日志
docker logs --tail 50 auto-deploy-demo
```

**预期输出**：
- 容器状态为 `Up`
- 日志显示 `Server running on port 8888`
- 日志显示 `Running mode: Nginx dynamic routing`

---

### 2. 检查项目状态

```bash
# 查看项目数据
docker exec auto-deploy-demo cat /app/data/projects.json

# 查看项目目录
docker exec auto-deploy-demo ls -la /app/projects/

# 查看具体项目文件
docker exec auto-deploy-demo ls -la /app/projects/{项目ID}/
```

**检查要点**：
- 项目状态是否为 `running`
- 项目是否有 `port` 字段
- 项目目录是否存在且包含文件

---

### 3. 检查项目服务是否运行

```bash
# 查看所有进程
docker exec auto-deploy-demo ps aux

# 查看 Node.js 进程
docker exec auto-deploy-demo ps aux | grep node

# 测试项目端口（假设项目端口是 9000）
docker exec auto-deploy-demo wget -qO- http://127.0.0.1:9000/
```

**预期输出**：
- 应该有多个 node 进程（主服务 + 项目服务）
- 项目端口能返回 HTML 内容

---

### 4. 检查 Nginx 配置

```bash
# 查看 Nginx 配置文件
docker exec auto-deploy-demo cat /app/nginx/sites-enabled/auto-deploy.conf

# 检查 Nginx 配置语法
docker exec auto-deploy-demo nginx -t

# 查看 Nginx 错误日志
docker exec auto-deploy-demo cat /var/log/nginx/error.log

# 查看 Nginx 访问日志
docker exec auto-deploy-demo tail -20 /var/log/nginx/access.log
```

**检查要点**：
- 配置文件中是否包含项目路由
- 配置语法是否正确
- 错误日志是否有循环重定向等问题

---

### 5. 测试内部访问

```bash
# 测试主页面
docker exec auto-deploy-demo wget -qO- http://127.0.0.1:80/ | head -20

# 测试 API
docker exec auto-deploy-demo wget -qO- http://127.0.0.1:8888/api/projects

# 测试项目访问（假设项目ID是 1772016995850，端口是 9000）
docker exec auto-deploy-demo wget -qO- http://127.0.0.1:80/project/1772016995850/

# 直接测试项目服务
docker exec auto-deploy-demo wget -qO- http://127.0.0.1:9000/
```

---

### 6. 常见问题及修复

#### 问题 1：Nginx 配置中没有项目路由

**症状**：配置文件中 `# 项目路由 - 由系统动态生成` 下面为空

**原因**：
- 项目启动时未正确更新 Nginx 配置
- 项目对象没有传递 port 字段

**修复**：
```bash
# 进入容器
docker exec -it auto-deploy-demo sh

# 手动重新生成配置
cd /app
node -e "
const nginxManager = require('./server/services/nginxManager');
const projectService = require('./server/services/projectService');
const fs = require('fs');

const projects = projectService.getAllProjects();
const running = projects.filter(p => p.status === 'running');

running.forEach(p => {
  const projectWithPort = { ...p, port: p.port };
  nginxManager.addProjectLocation(projectWithPort);
});

console.log(nginxManager.safeReload());
"

exit
```

---

#### 问题 2：循环重定向 (500 错误)

**症状**：错误日志显示 `rewrite or internal redirection cycle`

**原因**：Nginx 配置中的 `try_files` 导致循环

**修复**：
```bash
# 进入容器
docker exec -it auto-deploy-demo sh

# 删除 try_files 行
sed -i '/try_files/d' /app/nginx/sites-enabled/auto-deploy.conf

# 重载 Nginx
nginx -s reload

exit
```

---

#### 问题 3：项目服务未启动

**症状**：项目端口连接被拒绝 `Connection refused`

**原因**：
- 容器重启后项目进程丢失
- 项目启动失败

**修复**：
```bash
# 在管理界面手动停止再启动项目
# 或者重启容器
docker restart auto-deploy-demo
```

---

#### 问题 4：404 Not Found

**症状**：访问项目返回 404，Nginx 版本号显示在页面底部

**原因**：
- Nginx 配置中没有对应项目的路由
- 项目 ID 不匹配

**修复**：
1. 确认项目状态为 `running`
2. 确认 Nginx 配置中包含该项目路由
3. 手动重新生成配置（见问题 1 的修复方法）

---

#### 问题 5：静态资源加载失败 (MIME type 错误)

**症状**：控制台报错 `Expected a JavaScript-or-Wasm module script but the server responded with a MIME type of "text/html"`

**原因**：前端项目的静态资源路径是绝对路径 `/assets/...`，被 Nginx 的 `/` location 捕获，代理到了管理后台

**修复**：
```bash
# 进入容器
docker exec -it auto-deploy-demo sh

# 修改项目 HTML 文件，将绝对路径改为相对路径
sed -i 's|src="/|src="./|g' /app/projects/{项目ID}/index.html
sed -i 's|href="/|href="./|g' /app/projects/{项目ID}/index.html

# 查看修改结果
cat /app/projects/{项目ID}/index.html

exit
```

**注意**：新版本已自动修复此问题，上传新项目时会自动转换路径

---

## 手动配置 Nginx

### 手动添加项目路由

如果自动生成失败，可以手动添加项目路由配置：

```bash
# 进入容器编辑配置
docker exec -it auto-deploy-demo vi /app/nginx/sites-enabled/auto-deploy.conf
```

在 `# 项目路由 - 由系统动态生成` 下面添加：

```nginx
    # Project: 项目名称 (项目ID)
    location /project/项目ID/ {
        proxy_pass http://127.0.0.1:项目端口/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
```

**示例**（项目ID: 1772019512922，端口: 9000）：

```nginx
    # Project: lot (1772019512922)
    location /project/1772019512922/ {
        proxy_pass http://127.0.0.1:9000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
```

### 在容器外操作 Nginx

```bash
# 测试 Nginx 配置语法
docker exec auto-deploy-demo nginx -t

# 重新加载 Nginx 配置（在容器外执行）
docker exec auto-deploy-demo nginx -s reload

# 查看 Nginx 配置
docker exec auto-deploy-demo cat /app/nginx/sites-enabled/auto-deploy.conf

# 查看 Nginx 错误日志
docker exec auto-deploy-demo cat /var/log/nginx/error.log

# 查看 Nginx 访问日志
docker exec auto-deploy-demo tail -50 /var/log/nginx/access.log
```

---

### 7. 一键诊断脚本

```bash
docker exec auto-deploy-demo sh -c '
echo "=== 容器进程 ==="
ps aux | grep -E "node|nginx"
echo ""
echo "=== 项目数据 ==="
cat /app/data/projects.json 2>/dev/null | head -50
echo ""
echo "=== Nginx 配置 ==="
cat /app/nginx/sites-enabled/auto-deploy.conf 2>/dev/null
echo ""
echo "=== Nginx 错误日志 ==="
tail -20 /var/log/nginx/error.log 2>/dev/null
echo ""
echo "=== 测试主页面 ==="
wget -qO- http://127.0.0.1:80/ 2>/dev/null | head -5
echo ""
echo "=== 测试 API ==="
wget -qO- http://127.0.0.1:8888/api/projects 2>/dev/null | head -50
'
```

---

### 8. 重新部署步骤

如果以上方法都无法解决问题，请重新部署：

```bash
# 1. 停止并删除旧容器
docker rm -f auto-deploy-demo

# 2. 清理数据（谨慎操作！）
# rm -rf /opt/auto-deploy/data/*
# rm -rf /opt/auto-deploy/projects/*

# 3. 上传新的部署包并解压
cd /opt/auto-deploy
unzip -o auto-deploy-dist.zip

# 4. 创建 Nginx 配置目录
mkdir -p nginx/sites-enabled

# 5. 构建镜像
docker build -t auto-deploy-demo:latest .

# 6. 启动容器（带 Nginx 配置映射）
docker run -d \
  --name auto-deploy-demo \
  --restart unless-stopped \
  -p 8181:80 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/projects:/app/projects \
  -v $(pwd)/nginx/sites-enabled:/app/nginx/sites-enabled \
  -e PORT=8888 \
  -e BASE_DOMAIN=ashai.com.cn:8181 \
  -e USE_NGINX=true \
  -e PROJECT_BIND_ADDRESS=127.0.0.1 \
  auto-deploy-demo:latest

# 7. 查看日志
docker logs -f auto-deploy-demo
```

---

## 架构说明

```
用户请求
    ↓
宿主机:8181
    ↓
容器 Nginx:80
    ↓
    ├─ /api/* → Node.js:8888
    ├─ /project/{id}/* → 项目服务:900x
    └─ / → 管理后台静态文件
```

---

## 相关文件位置

| 文件 | 容器内路径 | 宿主机路径（如果映射） |
|------|-----------|----------------------|
| Nginx 配置 | `/app/nginx/sites-enabled/auto-deploy.conf` | `./nginx/sites-enabled/auto-deploy.conf` |
| 项目数据 | `/app/data/projects.json` | `./data/projects.json` |
| 项目文件 | `/app/projects/{项目ID}/` | `./projects/{项目ID}/` |
| Nginx 错误日志 | `/var/log/nginx/error.log` | - |
| Nginx 访问日志 | `/var/log/nginx/access.log` | - |

---

## 联系方式

如有问题，请提供以下信息：
1. `docker logs auto-deploy-demo` 的输出
2. `docker exec auto-deploy-demo cat /app/nginx/sites-enabled/auto-deploy.conf`
3. `docker exec auto-deploy-demo cat /app/data/projects.json`
4. `docker exec auto-deploy-demo cat /var/log/nginx/error.log`