shuangyan-notebook/第五域 · Fifth Domain/⚒️ 铸渊·协作指令｜GitHub ↔ Notion 桥接协议/🔧 铸渊指令：启动后端服务 → 看板动态数据上线（霜砚签发·2026-03-07） 27c217cf3f3d482b9149f681f76ab15b.md

---
belongs_to:
  - "[[INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]"
---
# 🔧 铸渊指令：启动后端服务 → 看板动态数据上线（霜砚签发·2026-03-07）

<aside>
🔧

**铸渊立即执行** · 霜砚签发 · 2026-03-07

**优先级**：P0 · 立即执行

**问题**：[guanghulab.com](http://guanghulab.com) 前端已部署成功，但看板页面「系统状态」「开发者进度」「广播动态」显示「加载中…」，原因是后端 Node.js 服务没有在服务器上运行

**目标**：在服务器上启动 backend 服务，让看板的动态数据能正常加载

</aside>

---

## 🎯 问题分析

```
现在的状态：
✅ 前端文件已部署 → guanghulab.com 能打开，看到看板页面
❌ 后端没启动 → 看板的 ws-client.js 和 api.js 连接后端失败
❌ 动态区域显示「加载中…」→ 系统状态 / 开发者进度 / 广播动态
✅ 静态区域正常 → 团队成员状态 / 最近广播（这些是写死在HTML里的）

原因：
status-board/ 里的 JS 文件（ws-client.js、api.js）
试图连接后端 API 获取实时数据，
但 backend/server.js 没有在服务器上运行，
所以连接失败，数据加载不出来。
```

---

## 📋 铸渊执行清单（读到就做·不等人）

```
铸渊后端启动指令 · YM-BACKEND-20260307-001
来源：霜砚（Notion执行体）→ 铸渊（GitHub执行体）
时间：2026-03-07
状态：P0 · 立即执行

━━━ 任务一：检查服务器环境 ━━━

SSH 登录服务器后，依次检查：

① Node.js 是否安装：
   node -v
   · 如果没有 → 安装：curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - && sudo apt-get install -y nodejs

② pm2 是否安装：
   pm2 -v
   · 如果没有 → 安装：sudo npm install -g pm2

③ 后端代码是否已同步到服务器：
   ls /var/www/guanghulab/backend/
   · 应该能看到 server.js、package.json、routes/ 等文件
   · 如果没有 → 说明 rsync 排除了 backend/，需要修改 deploy-to-server.yml

④ 检查 status-board 的 API 连接地址：
   cat /var/www/guanghulab/status-board/api-config.js
   或
   grep -r "localhost\|127.0.0.1\|api\|ws://\|http://" /var/www/guanghulab/status-board/*.js
   · 找出前端连接后端的地址和端口
   · 记下来，后面启动后端时要用同一个端口

━━━ 任务二：安装后端依赖并启动 ━━━

① 进入后端目录：
   cd /var/www/guanghulab/backend

② 安装依赖：
   npm install --production

③ 检查 .env 或配置文件：
   · 如果 server.js 需要环境变量（端口号、数据库连接等），确保配置正确
   · 如果有 .env.example，复制为 .env 并填入正确值

④ 用 pm2 启动后端服务：
   pm2 start server.js --name guanghulab-backend

⑤ 确认服务运行正常：
   pm2 status
   pm2 logs guanghulab-backend --lines 20
   · 确认状态是 online，没有报错
   · 记下后端监听的端口号（比如 3000 或 8080）

⑥ 设置开机自启：
   pm2 save
   pm2 startup
   · 按提示执行生成的命令（通常是 sudo env PATH=... pm2 startup ...）

━━━ 任务三：配置 Nginx 反向代理（如需要） ━━━

检查前端 JS 里连接后端的方式：

情况A：前端用相对路径调 API（比如 /api/status）
  → Nginx 需要反向代理 /api/ 到 Node.js 端口：
  在 Nginx 配置里加：
  location /api/ {
      proxy_pass http://127.0.0.1:后端端口号/;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection 'upgrade';
      proxy_set_header Host $host;
      proxy_cache_bypass $http_upgrade;
  }

情况B：前端用 WebSocket（比如 ws://localhost:端口）
  → Nginx 需要反向代理 WebSocket：
  location /ws {
      proxy_pass http://127.0.0.1:后端端口号;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "Upgrade";
      proxy_set_header Host $host;
  }

情况C：前端直接用 localhost:端口
  → 这在服务器上不行！需要改前端的 api-config.js：
  · 把 localhost 改成 guanghulab.com
  · 或改成相对路径 /api/
  · 然后配 Nginx 反向代理

修改后重新加载 Nginx：
  sudo nginx -t && sudo systemctl reload nginx

━━━ 任务四：修改 CD 工作流自动重启后端 ━━━

在 deploy-to-server.yml 的 deploy job 里加一步：
每次部署完成后自动重启后端服务。

在 rsync 步骤之后加：

- name: Restart backend service
  uses: appleboy/ssh-action@v1
  with:
    host: $ secrets.DEPLOY_HOST 
    username: $ secrets.DEPLOY_USER 
    key: $ secrets.DEPLOY_KEY 
    script: |
      cd /var/www/guanghulab/backend
      npm install --production 2>/dev/null || true
      pm2 restart guanghulab-backend 2>/dev/null || pm2 start server.js --name guanghulab-backend
      pm2 save
      echo "✅ 后端服务已重启"

这样以后每次 push 代码，不仅前端自动更新，后端也自动重启。

━━━ 任务五：测试验证 ━━━

启动后端后，检查：

① 后端服务状态：
   pm2 status
   · guanghulab-backend 应该是 online

② 后端 API 能响应：
   curl http://localhost:后端端口号/
   · 应该有响应（不是 Connection refused）

③ 网站动态数据加载：
   打开 guanghulab.com
   · 「系统状态」应该显示具体数据（不是「加载中…」）
   · 「开发者进度」应该显示数据
   · 「广播动态」应该显示数据
   · 如果还是「加载中…」→ 检查浏览器控制台(F12)的报错

④ 如果前端报 WebSocket 连接失败或 API 404：
   → 说明 Nginx 反向代理没配对，回到任务三检查

━━━ 验收标准 ━━━
· pm2 status 显示 guanghulab-backend online
· guanghulab.com 看板的动态区域显示真实数据（不是「加载中…」）
· 后端服务开机自启已配置
· deploy-to-server.yml 已加入自动重启后端的步骤
· push 到 main 后，前端+后端都自动更新

━━━ 执行确认 ━━━
铸渊完成后回复：
✅ YM-BACKEND-20260307-001 已完成
· Node.js 版本：vXX.XX
· pm2 版本：vXX.XX
· 后端端口：XXXX
· pm2 status：online
· Nginx 反向代理：已配置 / 不需要
· 前端连接方式：API / WebSocket / 两者都有
· 看板动态数据：已加载 / 部分加载 / 需要进一步调试
· deploy-to-server.yml：已更新 / 待更新
· commit SHA：xxxxxx
```

---

## 📝 妈妈操作指南

<aside>
👆

**妈妈你只需要做一件事：**

1. 复制上面代码框里的全部内容
2. 粘贴给铸渊
3. 等铸渊回复执行确认
4. 截图发给霜砚
</aside>

---

## 🔗 关联文档

- 铸渊协作指令主页：[⚒️ 铸渊·协作指令｜GitHub ↔ Notion 桥接协议](../%E2%9A%92%EF%B8%8F%20%E9%93%B8%E6%B8%8A%C2%B7%E5%8D%8F%E4%BD%9C%E6%8C%87%E4%BB%A4%EF%BD%9CGitHub%20%E2%86%94%20Notion%20%E6%A1%A5%E6%8E%A5%E5%8D%8F%E8%AE%AE%201e27db07f7884441bf4ca6c931cadab9.md)
- CD 部署指令：[🚀 铸渊 CD 指令：自动部署 [guanghulab.com](http://guanghulab.com)（push → 自动上线）](%F0%9F%9A%80%20%E9%93%B8%E6%B8%8A%20CD%20%E6%8C%87%E4%BB%A4%EF%BC%9A%E8%87%AA%E5%8A%A8%E9%83%A8%E7%BD%B2%20guanghulab%20com%EF%BC%88push%20%E2%86%92%20%E8%87%AA%E5%8A%A8%E4%B8%8A%E7%BA%BF%EF%BC%89%20905ba98cce9c4bb3b812d9f7e9d1f35c.md)
- 全模块部署指令：[🚀 铸渊指令：修复部署 → 全模块上线 [guanghulab.com](http://guanghulab.com)（霜砚签发·2026-03-07）](%F0%9F%9A%80%20%E9%93%B8%E6%B8%8A%E6%8C%87%E4%BB%A4%EF%BC%9A%E4%BF%AE%E5%A4%8D%E9%83%A8%E7%BD%B2%20%E2%86%92%20%E5%85%A8%E6%A8%A1%E5%9D%97%E4%B8%8A%E7%BA%BF%20guanghulab%20com%EF%BC%88%E9%9C%9C%E7%A0%9A%E7%AD%BE%E5%8F%91%C2%B72026-03-07%207ea69ab50bd94be6bad31f6b8755bb39.md)