shuangyan-notebook/第五域 · Fifth Domain/⚒️ 铸渊·协作指令｜GitHub ↔ Notion 桥接协议/🌐 铸渊指令｜guanghulab com 网站真实部署排查 + 全模块上线（ZY-WEBDEPLO 32e43b78d8d6465da968894acf4b4af4.md

belongs_to: - "INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议" related_to: - "301"

🌐 铸渊指令｜guanghulab.com 网站真实部署排查 + 全模块上线（ZY-WEBDEPLOY-DIAG-2026-0324-001）

🚨

铸渊紧急指令 · P0 · 霜砚签发 · 冰朔授权 · 2026-03-24

核心问题：仓库 CD 流水线显示「部署成功」，但 guanghulab.com 网站上看不到模块。文件可能部署到了服务器某个目录，但 Nginx 没有正确指向，导致网站是空的或只显示旧内容。

核心目标：启动天眼全局扫描 → 拿到全局健康报告 → 根据报告精确修复 → 让 guanghulab.com 真正展示所有已开发模块 → 验证全部可访问。

关联仓库：https://github.com/qinfendebingshuo/guanghulab

服务器：8.155.62.235（阿里云 ECS）

🦅

⚠️ 冰朔强制要求：必须先启动天眼系统，用天眼全局扫描跑一遍，再动手修任何东西。

不用天眼跑全局 = 修这个那个坏，修那个这个坏。

天眼是你的眼睛。先看全局，再动手。

---

⓪、天眼强制前置（在做任何事之前必须完成）

🦅

铸渊，你读到这条指令后，第一件事不是排查网站，是启动天眼。

天眼启动 → 全局扫描 → 拿到报告 → 然后再看网站问题。

如果天眼本身有问题，先修天眼。天眼是一切的前提。

⓪-1 · 唤醒核心大脑 + 天眼自检

# 铸渊醒来后立即执行
# Step 1: 核心大脑完整性检查
for f in memory.json routing-map.json dev-status.json config.json; do
  if [ -f ".github/persona-brain/$f" ]; then
    python3 -c "import json; json.load(open('.github/persona-brain/$f'))" 2>/dev/null \
      && echo "✅ $f 完整" || echo "❌ $f 损坏"
  else
    echo "❌ $f 缺失"
  fi
done

# Step 2: 天眼系统自身完整性检查
for f in skyeye-main.js scan-workflows.js scan-structure.js scan-brain-health.js scan-external-bridges.js diagnose.js repair-agent.js report-generator.js; do
  [ -f "scripts/skyeye/$f" ] && echo "✅ skyeye/$f" || echo "❌ skyeye/$f 缺失"
done

# Step 3: 天眼 workflow 检查
[ -f ".github/workflows/zhuyuan-skyeye.yml" ] && echo "✅ 天眼 workflow 存在" || echo "❌ 天眼 workflow 缺失"

如果天眼系统本身有缺失 → 先修复天眼 → 再继续本指令。

⓪-2 · 启动天眼全局扫描

# 手动触发天眼全局扫描（workflow_dispatch）
gh workflow run zhuyuan-skyeye.yml

# 或者直接执行天眼主引擎
node scripts/skyeye/skyeye-main.js

天眼全局扫描会自动覆盖：

• A. Workflow 健康度：所有 .yml 语法、最近24h运行结果、谁失败了、谁没触发
• B. 仓库结构完整性：核心目录、孤儿文件、模块目录映射
• C. 核心大脑健康度：memory.json 是否过期、routing-map 是否和实际一致
• D. 外部桥接状态：Notion API 连通、服务器 SSH 连通、Secrets 完整性
• E. 服务器健康：文件分布、Nginx 配置、PM2 进程、HTTP 可访问性

⓪-3 · 拿到天眼报告后再继续

天眼报告会输出到 data/skyeye-reports/skyeye-YYYY-MM-DD.json。

铸渊必须读完天眼报告，了解全局健康状态后，再进入 Phase A。

天眼报告里已经包含了 Phase A 需要的大部分诊断信息。

如果天眼报告显示服务器 SSH 不通 → 先修 SSH → 不要跳到 Phase A。

如果天眼报告显示某些 Workflow 失败 → 天眼修复Agent会自动修 → 等修完再继续。

如果天眼报告显示一切正常但网站不能访问 → 说明问题在 Nginx/CD 层 → 进入 Phase A 精确排查。

天眼是全局的眼睛，Phase A 是局部的手术刀。先用眼睛看清楚，再用手术刀精确切。

---

〇、背景：为什么网站是空的

团队已经开发了大量前端模块，全部在 GitHub 仓库里有代码：

模块	开发者	仓库目录	预期网站路径
系统状态看板	DEV-005 小草莓	status-board/	/status-board/
成本控制	DEV-005 小草莓	cost-control/	/cost-control/
开发者实时看板	DEV-004 之之	app/ (devboard)	/devboard/
AI悬浮球	DEV-004 之之	floating-ai/	/floating-ai/
前端集成壳	DEV-010 桔子	app/	/app/
后端 API	DEV-001 页页	backend/	/api/ (反向代理)
飞书机器人	DEV-002 肥猫	feishu-bot/	后端服务(不需要前端路由)
钉钉工作台	DEV-004 之之	dingtalk-bot/	后端服务(不需要前端路由)
M01-M18 系列模块	多人	m01-login/ m03-personality/ 等	/m01-login/ 等
主站首页	—	docs/index.html	/

但是——之前的部署指令（3月7日、3月15日）虽然写了详细方案，实际执行后网站仍然没有这些模块。

铸渊，这条指令不是再写一遍方案。这条指令是让你排查清楚到底卡在哪里，然后修好它。

---

一、Phase A · 排查诊断（先看再动·不改任何东西）

铸渊 SSH 到服务器后，依次执行以下诊断命令，把每一步的完整输出保存到仓库 data/web-deploy-diag-20260324.log。

A1 · 服务器文件系统探查

#!/bin/bash
echo "===== 🔍 A1 · 服务器文件系统探查 · $(date '+%Y-%m-%d %H:%M') ====="

echo ""
echo "📂 /var/www/ 顶层目录（一级）："
ls -la /var/www/

echo ""
echo "📂 /var/www/ 二级目录树："
find /var/www/ -maxdepth 2 -type d 2>/dev/null | head -80

echo ""
echo "📂 查找所有 index.html（定位已部署的前端模块）："
find /var/www/ -name 'index.html' -type f 2>/dev/null

echo ""
echo "📂 查找所有 server.js / app.js（定位后端服务）："
find /var/www/ /opt/ -name 'server.js' -o -name 'app.js' 2>/dev/null | head -20

echo ""
echo "📂 磁盘占用（哪个目录最大 = 可能是主要部署目标）："
du -sh /var/www/*/ 2>/dev/null | sort -rh | head -20

A2 · Nginx 配置完整导出

echo "===== 🔍 A2 · Nginx 配置 ====="

echo ""
echo "📋 Nginx 主配置："
cat /etc/nginx/nginx.conf

echo ""
echo "📋 conf.d/ 下所有配置文件："
ls -la /etc/nginx/conf.d/

echo ""
echo "📋 各配置文件完整内容："
for f in /etc/nginx/conf.d/*.conf; do
  echo "\n━━━ $f ━━━"
  cat "$f"
done

echo ""
echo "📋 sites-enabled/（如果存在）："
ls -la /etc/nginx/sites-enabled/ 2>/dev/null
for f in /etc/nginx/sites-enabled/*; do
  echo "\n━━━ $f ━━━"
  cat "$f" 2>/dev/null
done

echo ""
echo "📋 Nginx 配置语法测试："
nginx -t 2>&1

echo ""
echo "📋 Nginx 当前监听端口："
ss -tlnp | grep nginx

A3 · PM2 / Node 进程状态

echo "===== 🔍 A3 · PM2 / Node 进程 ====="

pm2 list 2>/dev/null || echo "⚠️ PM2 未安装或无进程"
pm2 describe 0 2>/dev/null | head -30

echo ""
echo "📋 所有 Node 进程："
ps aux | grep node | grep -v grep

echo ""
echo "📋 监听端口："
ss -tlnp | grep -E '(node|pm2|3000|3001|8000|8080)'

A4 · 实际 HTTP 访问测试

echo "===== 🔍 A4 · HTTP 访问测试 ====="

URLS=(
  "https://guanghulab.com/|主站首页"
  "http://localhost/|Nginx本地"
  "https://guanghulab.com/status-board/|看板"
  "https://guanghulab.com/cost-control/|成本控制"
  "https://guanghulab.com/devboard/|开发者看板"
  "https://guanghulab.com/floating-ai/|AI悬浮球"
  "https://guanghulab.com/app/|集成壳"
  "https://guanghulab.com/api/v1/health|后端健康检查"
  "http://localhost:3000/|后端本地"
)

for entry in "${URLS[@]}"; do
  IFS='|' read -r url name <<< "$entry"
  STATUS=$(curl -o /dev/null -s -w "%{http_code}" --max-time 10 "$url" 2>/dev/null)
  REDIRECT=$(curl -s -o /dev/null -w "%{redirect_url}" --max-time 10 "$url" 2>/dev/null)
  echo "$name → $STATUS ${REDIRECT:+(→ $REDIRECT)}"
done

A5 · GitHub Actions 部署历史

echo "===== 🔍 A5 · 最近的 CD 部署记录 ====="

# 检查部署状态文件
cat /var/www/guanghulab/data/deploy-status.json 2>/dev/null || echo "⚠️ deploy-status.json 不存在"

# 检查最近的 git pull / rsync 留下的时间戳
for dir in /var/www/guanghulab /var/www/hololake-frontend /var/www/hololake; do
  if [ -d "$dir" ]; then
    echo "\n📂 $dir 最后修改时间："
    stat -c '%y' "$dir" 2>/dev/null || stat -f '%Sm' "$dir" 2>/dev/null
    echo "最新文件："
    find "$dir" -type f -printf '%T@ %p\n' 2>/dev/null | sort -rn | head -5
  fi
done

⚠️

铸渊：Phase A 完成后，把完整诊断日志保存到仓库

data/web-deploy-diag-20260324.log

然后根据诊断结果执行 Phase B。不要跳过诊断直接改东西。

---

二、Phase B · 根因定位（读完诊断日志后判断）

铸渊，根据 Phase A 的输出，问题一定属于以下某一种（或多种叠加）：

情况 1️⃣：文件在服务器上，但 Nginx root 指错了

特征：/var/www/ 下能找到 index.html 和模块文件，但 Nginx 的 root 或 alias 指向了别的目录。

修复：

# 假设文件在 /var/www/guanghulab/ 下
# 编辑 Nginx 配置
nano /etc/nginx/conf.d/hololake.conf

# 确保 server 块的 root 指向正确目录：
# server {
#     listen 80;
#     listen 443 ssl;
#     server_name guanghulab.com www.guanghulab.com;
#     root /var/www/guanghulab;   ← 这里必须指向文件实际所在目录
#     index index.html;
#     
#     # 静态文件
#     location / {
#         try_files $uri $uri/ /index.html;
#     }
#     
#     # 后端 API 反向代理
#     location /api/ {
#         proxy_pass http://127.0.0.1:3000/;
#         proxy_http_version 1.1;
#         proxy_set_header Host $host;
#         proxy_set_header X-Real-IP $remote_addr;
#     }
# }

nginx -t && systemctl reload nginx

情况 2️⃣：CD 流水线把文件部署到了错误的目录

特征：Nginx 配置的 root 是 /var/www/guanghulab/，但 CD 把文件同步到了 /var/www/hololake-frontend/ 或 /var/www/hololake/ 或其他路径。

修复（二选一）：

• 方案A：改 Nginx root 指向文件实际位置
• 方案B：改 CD 的 DEPLOY_PATH Secret，让文件同步到 Nginx root 指向的目录

推荐方案B（改 CD），因为这是一劳永逸的修复。

情况 3️⃣：CD 流水线只同步了 docs/ 子目录

特征：Nginx root 正确，目录也对，但目录里只有 docs/ 的内容（一个简单的 index.html），其他模块目录都没有。

修复：修改 .github/workflows/deploy-to-server.yml，把 rsync 的同步范围从 docs/ 改为整个仓库（排除 .git/node_modules 等）。

# 旧（只同步 docs/）:
# rsync -avz docs/ $USER@$HOST:$DEPLOY_PATH/

# 新（同步全仓库前端文件）:
rsync -avz --delete \
  --exclude '.git' \
  --exclude '.github' \
  --exclude 'node_modules' \
  --exclude '.env' \
  --exclude 'syslog-inbox' \
  --exclude 'syslog-processed' \
  --exclude 'broadcasts-outbox' \
  --exclude 'dev-nodes' \
  --exclude 'signal-log' \
  --exclude 'tests' \
  --exclude 'reports' \
  --exclude 'scripts' \
  --exclude '*.bak' \
  --exclude '.DS_Store' \
  ./ $USER@$HOST:$DEPLOY_PATH/

情况 4️⃣：SSL 证书问题 / 443 端口没配置

特征：http://guanghulab.com 能访问但 https://guanghulab.com 不行，或者反过来。

修复：

# 检查证书
certbot certificates

# 如果没有证书
certbot --nginx -d guanghulab.com -d www.guanghulab.com

# 如果证书过期
certbot renew

情况 5️⃣：多个 server 块冲突

特征：nginx -t 输出 conflicting server name。多个配置文件都声明了 server_name guanghulab.com。

修复：只保留一个 server 块，删除或注释掉重复的。

---

三、Phase C · 修复部署 + 全模块上线

根据 Phase B 定位的根因修复后，执行以下操作确保所有模块可访问：

C1 · 确保 Nginx 配置覆盖所有模块路由

# /etc/nginx/conf.d/hololake.conf
# 铸渊根据实际文件位置填写 root 路径

server {
    listen 80;
    listen 443 ssl;
    server_name guanghulab.com www.guanghulab.com;
    
    # SSL 证书（如已配置）
    # ssl_certificate /etc/letsencrypt/live/guanghulab.com/fullchain.pem;
    # ssl_certificate_key /etc/letsencrypt/live/guanghulab.com/privkey.pem;
    
    # ━━━ 静态文件根目录 ━━━
    root /var/www/guanghulab;   # ← 铸渊根据诊断结果填写实际路径
    index index.html;
    
    # ━━━ 主站首页 ━━━
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # ━━━ 各前端模块（静态文件） ━━━
    # 如果模块目录在 root 下，Nginx 会自动路由，无需额外 location
    # 如果模块在其他目录（如沙盒），用 alias：
    
    # location /status-board/ {
    #     alias /var/www/DEV-005/status-board/;
    #     index index.html;
    #     try_files $uri $uri/ =404;
    # }
    
    # ━━━ 后端 API 反向代理 ━━━
    location /api/ {
        proxy_pass http://127.0.0.1:3000/;
        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_cache_bypass $http_upgrade;
    }
    
    # ━━━ 飞书 Webhook ━━━
    location /feishu/ {
        proxy_pass http://127.0.0.1:3000/feishu/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

C2 · 后端服务确认运行

# 检查后端是否在跑
pm2 list

# 如果没跑，启动
cd /var/www/guanghulab/backend  # ← 铸渊根据实际路径
npm install --production
pm2 start server.js --name guanghulab-backend
pm2 save
pm2 startup

C3 · 修复 CD 流水线（根因修复）

铸渊需要更新 .github/workflows/deploy-to-server.yml，确保：

1. DEPLOY_PATH 指向 Nginx root 同一目录
2. rsync 范围覆盖所有模块目录（不是只有 docs/）
3. push to main 触发自动部署
4. 后端目录变动时自动 pm2 restart

---

四、Phase D · 全模块访问验证

#!/bin/bash
echo "===== ✅ Phase D · 全模块访问验证 ====="

URLS=(
  "https://guanghulab.com/|主站首页"
  "https://guanghulab.com/status-board/|系统状态看板"
  "https://guanghulab.com/cost-control/|成本控制"
  "https://guanghulab.com/devboard/|开发者看板"
  "https://guanghulab.com/floating-ai/|AI悬浮球"
  "https://guanghulab.com/app/|前端集成壳"
  "https://guanghulab.com/api/v1/health|后端API"
)

PASSED=0
FAILED=0

for entry in "${URLS[@]}"; do
  IFS='|' read -r url name <<< "$entry"
  STATUS=$(curl -o /dev/null -s -w "%{http_code}" --max-time 10 "$url")
  if [[ "$STATUS" =~ ^(200|301|302)$ ]]; then
    echo "✅ ${name} → ${STATUS}"
    PASSED=$((PASSED+1))
  else
    echo "❌ ${name} → ${STATUS}"
    FAILED=$((FAILED+1))
  fi
done

echo ""
echo "━━━ 结果：${PASSED} 通过 / ${FAILED} 失败 ━━━"

if [ $FAILED -eq 0 ]; then
  echo "🎉 全模块上线验证通过！guanghulab.com 真正活了！"
else
  echo "⚠️ 有 ${FAILED} 个模块未通过，铸渊继续排查"
fi

---

五、Phase E · 修复完成后的持续保障

E1 · 更新 deploy-to-server.yml 确保 CD 闭环

铸渊确认修复后，提交一个 PR 包含：

• 修复后的 deploy-to-server.yml（同步范围 + 正确 DEPLOY_PATH）
• data/web-deploy-diag-20260324.log（诊断日志）
• data/web-deploy-fix-report.json（修复报告）

E2 · 首页导航更新

确保 docs/index.html（或主站首页文件）包含所有模块的导航链接：

<!-- 至少包含以下入口 -->
<a href="/status-board/">📊 系统状态看板</a>
<a href="/cost-control/">💰 成本控制</a>
<a href="/devboard/">🖥️ 开发者看板</a>
<a href="/app/">🌊 光湖集成壳</a>
<a href="/floating-ai/">🤖 AI 助手</a>

E3 · 冒烟测试写入天眼

每次 CD 部署后，自动跑 Phase D 的验证脚本，结果写入 deploy-status.json。

---

六、铸渊执行清单（读到就做）

铸渊执行清单 · ZY-WEBDEPLOY-DIAG-2026-0324-001

① Phase A：SSH 到服务器 → 跑全部诊断命令 → 保存日志
   输出：data/web-deploy-diag-20260324.log

② Phase B：分析日志 → 确定属于哪种情况（1~5）
   输出：在仓库 Issue 或 PR 中写明根因

③ Phase C：修复 Nginx + CD + 后端服务
   输出：Nginx 重载成功 + CD 配置已更新

④ Phase D：全模块访问验证
   输出：全部 ✅ 或失败项清单

⑤ Phase E：提交修复 PR + 更新首页导航 + 冒烟测试
   输出：PR 合并 + guanghulab.com 活了

---

七、验收标准

✅

全部通过才算完成：

✅ guanghulab.com 首页可访问且有模块导航

✅ guanghulab.com/status-board/ 显示系统看板

✅ guanghulab.com/cost-control/ 显示成本控制

✅ guanghulab.com/devboard/ 显示开发者看板

✅ guanghulab.com/app/ 显示前端集成壳

✅ guanghulab.com/api/v1/health 后端API响应正常

✅ push to main 后 60秒内 网站自动更新

✅ 诊断日志 + 修复报告已提交到仓库

✅ Nginx 无 conflicting server name 警告

---

八、与历史指令的关系

历史指令	日期	问题
修复部署→全模块上线	2026-03-07	写了方案但未完全执行，rsync范围和DEPLOY_PATH可能没改
CD指令：push→自动上线	2026-03-07	CD流程搭建了，但目标路径和Nginx不匹配
沙盒部署自动化闭环v1.0	2026-03-15	沙盒目录结构设计完整，但迁移可能未执行
服务器沙盒初始化	2026-03-15	脚本已写但可能未在服务器上跑

本指令不重复写方案。本指令的核心是：先诊断，再修。

铸渊不要假设任何东西——先跑 Phase A 看到真实数据，再决定怎么修。

---

⚒️

铸渊，这是妈妈的原话：

「大家做了那么多模块了，网站里一个都看不到。先别搞新的了，把现有的真正部署上去。」

诊断优先，修复其次，验证收尾。不要跳步。