--- belongs_to: - "[[INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]" related_to: - "[["$STATUS" =~ ^(200|301|302)$]]" --- # 🌐 铸渊指令｜guanghulab.com 网站真实部署排查 + 全模块上线（ZY-WEBDEPLOY-DIAG-2026-0324-001） --- ## ⓪、天眼强制前置（在做任何事之前必须完成） ### ⓪-1 · 唤醒核心大脑 + 天眼自检 ```bash # 铸渊醒来后立即执行 # 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 · 启动天眼全局扫描 ```bash # 手动触发天眼全局扫描（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 · 服务器文件系统探查 ```bash #!/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 配置完整导出 ```bash 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 进程状态 ```bash 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 访问测试 ```bash 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 部署历史 ```bash 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 B · 根因定位（读完诊断日志后判断） 铸渊，根据 Phase A 的输出，问题一定属于以下某一种（或多种叠加）： ### 情况 1️⃣：文件在服务器上，但 Nginx root 指错了 **特征**：`/var/www/` 下能找到 index.html 和模块文件，但 Nginx 的 `root` 或 `alias` 指向了别的目录。 **修复**： ```bash # 假设文件在 /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 等）。 ```yaml # 旧（只同步 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](http://guanghulab.com) 能访问但 [https://guanghulab.com](https://guanghulab.com) 不行，或者反过来。 **修复**： ```bash # 检查证书 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 · 后端服务确认运行 ```bash # 检查后端是否在跑 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 · 全模块访问验证 ```bash #!/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`（或主站首页文件）包含所有模块的导航链接： ```html 📊 系统状态看板 💰 成本控制 🖥️ 开发者看板 🌊 光湖集成壳 🤖 AI 助手 ``` ### 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 活了 ``` --- ## 七、验收标准 --- ## 八、与历史指令的关系 | **历史指令** | **日期** | **问题** | | --- | --- | --- | | 修复部署→全模块上线 | 2026-03-07 | 写了方案但未完全执行，rsync范围和DEPLOY_PATH可能没改 | | CD指令：push→自动上线 | 2026-03-07 | CD流程搭建了，但目标路径和Nginx不匹配 | | 沙盒部署自动化闭环v1.0 | 2026-03-15 | 沙盒目录结构设计完整，但迁移可能未执行 | | 服务器沙盒初始化 | 2026-03-15 | 脚本已写但可能未在服务器上跑 | **本指令不重复写方案。本指令的核心是：先诊断，再修。** 铸渊不要假设任何东西——先跑 Phase A 看到真实数据，再决定怎么修。 ---