# 🔧 铸渊指令｜persona-studio「我要开发」后端连接失败·排查修复（2026-03-15·曜冥签发）

## 📋 指令概要

| 项目 | 内容 |
| --- | --- |
| 签发人 | TCS-0002∞ 冰朔（曜冥授权） |
| 签发时间 | 2026-03-15 09:30 CST |
| 优先级 | **P1 · 紧急** |
| 目标 | 修复 persona-studio 前端点击「我要开发」后无法连接后端服务的问题 |
| 仓库 | `qinfendebingshuo/guanghulab` |
| 涉及路径 | `status-board/persona-studio/frontend/`  • `status-board/persona-studio/backend/` |

---

## 🔍 问题描述

前端点击「我要开发」按钮后，出现以下流程：

```
铸渊代理已启动 → 连接后端服务中，正在重试（1/2）→ 正在创建项目骨架 → 连接后端服务中，正在重试（2/2）→ ⚠ 任务提交失败：无法连接铸渊后端服务
```

**后端服务本身正常运行**，PM2 进程 online，端口 3002 在监听，`curl http://127.0.0.1:3002/` 返回 `{"status":"ok"}`。

---

## 🧪 已完成的排查（霜砚 + 冰朔手动操作）

### 1. 服务端状态 ✅ 正常

- PM2 进程 `persona-studio`（id 34）状态 online
- 端口 3002 监听中
- `curl http://127.0.0.1:3002/` 返回：

```json
{"status":"ok","message":"Persona Studio 后端服务运行中","version":"2.0.0","routes":["/api/ps/auth/login","/api/ps/chat/message","/api/ps/chat/history","/api/ps/build/start","/api/ps/notify/send","/api/ps/apikey/detect-models","/api/ps/apikey/chat","/api/ps/preview/:devId/:project","/api/ps/health"]}
```

### 2. Nginx 转发 ✅ 已配置

已在 `/etc/nginx/conf.d/default.conf` 添加：

```
location /api/ps/ {
    proxy_pass http://127.0.0.1:3002/api/ps/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    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_cache_bypass $http_upgrade;
    proxy_read_timeout 120s;
}
```

`nginx -t` 通过，已 reload。

### 3. 前端 API_BASE 判断 ⚠️ 部分修复

**原始代码逻辑**（`chat.js` 第15行 + `index.html` 第152行）：

```jsx
if (location.hostname === 'localhost' || location.hostname === '127.0.0.1') {
    return 'http://localhost:3002';
}
return 'https://guanghulab.com';  // 生产环境走这里
```

**已做的修改：**

- ✅ hostname 判断已加入 `8.155.62.235`
- ✅ `return 'http://localhost:3002'` 已改为 `return 'http://' + location.host`
- ❌ **修改后仍然失败** — 可能是浏览器缓存、或前端请求路径与后端路由不匹配、或 CORS 问题

---

## 🎯 铸渊需要做的事

### 任务 1：深度排查前端请求链路

1. 检查 `chat.js` 中「我要开发」按钮的完整请求链路
2. 确认 `API_BASE` 在非 [localhost](http://localhost) 环境下实际返回的值
3. 确认 `fetch` 请求的完整 URL（是 `/api/ps/build/start` 还是其他路径？）
4. 检查是否有 **CORS 跨域问题**（前端页面可能从 GitHub Pages 加载，请求发往 `8.155.62.235`）
5. 检查后端 `server.js` 是否配置了 CORS 允许跨域

### 任务 2：修复前端 API_BASE 逻辑

确保以下三种访问场景都能正确连接后端：

| 访问方式 | hostname | 期望 API_BASE |
| --- | --- | --- |
| 本地开发 | `localhost` / `127.0.0.1` | `http://localhost:3002` |
| IP 直接访问 | `8.155.62.235` | `http://8.155.62.235` （Nginx 转发 `/api/ps/` → 3002） |
| 域名访问 | `guanghulab.com` | `https://guanghulab.com`（需 SSL）或 `http://guanghulab.com` |
| GitHub Pages | `*.github.io` | `http://8.155.62.235`（跨域，需 CORS） |

**建议改法：**

```jsx
function getApiBase() {
    if (location.hostname === 'localhost' || location.hostname === '127.0.0.1') {
        return 'http://localhost:3002';
    }
    // 非本地环境统一使用当前域名，走 Nginx 转发
    return location.protocol + '//' + location.host;
}
```

### 任务 3：修复后端 CORS

在 `server.js` 中确认有以下配置：

```jsx
const cors = require('cors');
app.use(cors({
    origin: ['http://localhost:3002', 'http://8.155.62.235', 'https://guanghulab.com', /\.github\.io$/],
    credentials: true
}));
```

如果没有 `cors` 依赖，需要 `npm install cors`。

### 任务 4：确认「我要开发」的后端路由功能完整

- 检查 `/api/ps/build/start` 路由处理函数
- 确认该路由在接收请求后能正常响应（而不是挂起/超时）
- 检查该路由是否依赖外部服务（如 AI API key）才能工作

### 任务 5：提交修复并验证

1. 所有修改通过 commit 推送到 `main` 分支
2. commit message 格式：`fix(persona-studio): 修复「我要开发」后端连接失败 [ZY-FIX]`
3. 修复后在服务器执行 `cd /var/www/guanghulab && git pull && pm2 restart persona-studio`

---

## 📂 关键文件路径

| 文件 | 路径 |
| --- | --- |
| 前端聊天逻辑 | `status-board/persona-studio/frontend/chat.js` |
| 前端入口页 | `status-board/persona-studio/frontend/index.html` |
| 后端入口 | `status-board/persona-studio/backend/server.js` |
| 服务器部署目录 | `/var/www/guanghulab/status-board/persona-studio/` |
| Nginx 配置 | `/etc/nginx/conf.d/default.conf` |
| PM2 进程名 | `persona-studio`（id 34，端口 3002） |

---

## ⚠️ 注意事项

- 服务器地址：`8.155.62.235`（阿里云 ECS）
- 当前 Nginx 只有 HTTP（80），没有 HTTPS（443），所以 `https://guanghulab.com` 会失败
- 前端如果托管在 GitHub Pages（HTTPS），请求 HTTP 后端会被浏览器 Mixed Content 策略拦截
- 如果根因是 GitHub Pages HTTPS → HTTP 后端的 Mixed Content 问题，需要考虑：给服务器加 SSL 证书（Let's Encrypt），或将前端也部署到服务器上

---

*曜冥核心签发 · 霜砚记录 · 2026-03-15T09:45+08:00*