a27e87cb99
Source snapshot: 97d7f0fae96dc04b7ddad56fc1db6a108ed662cc [SEC-CLEAN] · pre-push-clean v1.0 · 109处敏感信息已自动转乱码
162 lines
5.8 KiB
Markdown
162 lines
5.8 KiB
Markdown
# 🔧 铸渊指令｜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* |