Guanghu Domestic Migration a27e87cb99 chore: import sanitized domestic snapshot for REPO-007

Source snapshot: 97d7f0fae96dc04b7ddad56fc1db6a108ed662cc

[SEC-CLEAN] · pre-push-clean v1.0 · 109处敏感信息已自动转乱码

2026-07-17 15:59:55 +08:00

10 KiB

Raw Permalink Blame History

🏗️ 服务器部署适配协议 v1.0（2026-03-15·曜冥签发）

一、基础概念：三层分离架构

┌─────────────────────────────────────────────────────────┐
│                    服务器 = 国家领土                      │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   🏛️ 基础设施层（国家管的 · 开发者不碰）                  │
│   ├── Nginx 全局配置（/etc/nginx/nginx.conf）            │
│   ├── SSL 证书                                          │
│   ├── PM2 全局进程管理                                   │
│   ├── Node.js / Git / 系统工具                           │
│   ├── 沙盒目录骨架（/var/www/DEV-XXX/）                  │
│   └── 冒烟检查脚本（/var/www/_shared/deploy-check.sh）   │
│                                                         │
│   🏠 开发者沙盒层（每人一间房 · 自己管自己的）             │
│   ├── /var/www/DEV-001/   ← 页页的房子                  │
│   ├── /var/www/DEV-002/   ← 肥猫的房子                  │
│   ├── /var/www/DEV-003/   ← 燕樊的房子                  │
│   ├── /var/www/DEV-004/   ← 之之的房子                  │
│   ├── /var/www/DEV-005/   ← 小草莓的房子                │
│   ├── /var/www/DEV-009/   ← 花尔的房子                  │
│   ├── /var/www/DEV-010/   ← 桔子的房子                  │
│   ├── /var/www/DEV-011/   ← 匆匆那年的房子              │
│   ├── /var/www/DEV-012/   ← Awen的房子                  │
│   ├── /var/www/DEV-013/   ← 小兴的房子                  │
│   └── /var/www/DEV-014/   ← 时雨的房子                  │
│                                                         │
│   🔗 共享服务层（后端/WebSocket/PM2进程）                 │
│   ├── /var/www/backend/         ← 页页后端（PM2管理）    │
│   ├── /var/www/feishu-bot/      ← 飞书舒舒（PM2管理）   │
│   └── /var/www/dingtalk-bot/    ← 钉钉秋秋（PM2管理）   │
│                                                         │
└─────────────────────────────────────────────────────────┘

二、开发者沙盒规范（你的房子的规则）

2.1 目录结构

每个开发者的沙盒目录结构必须遵循以下规范：

/var/www/DEV-XXX/
├── 模块名A/              # 例：status-board/
│   ├── index.html        # ⚠️ 入口文件必须叫 index.html
│   ├── style.css
│   ├── script.js
│   └── assets/
├── 模块名B/              # 例：cost-control/
│   ├── index.html        # ⚠️ 同上
│   └── ...
└── .deploy-profile       # 部署身份文件（系统自动生成）

2.2 准入规则（你的模块必须满足这些才能上线）

规则编号	规则内容	违反后果
R-01	入口文件必须命名为 `index.html`	Nginx 返回 403/404，你自己改名
R-02	所有文件权限必须为 `644`，目录权限必须为 `755`	Nginx 无法读取，你自己 chmod
R-03	文件 owner 必须为 `nginx:nginx`	403 Forbidden，你自己 chown
R-04	模块只能部署在自己编号的沙盒目录下	越界部署 = 系统自动拒绝
R-05	不得修改 `/etc/nginx/` 下的任何配置文件	基础设施层由系统管理，开发者没有权限
R-06	不得修改其他 DEV 编号目录下的任何文件	沙盒隔离原则，跨房操作 = 违规
R-07	不允许使用中文标点（分号、引号等）出现在配置文件中	Nginx 解析失败，你自己排查替换

2.3 Nginx location 路由规则

系统为每个开发者沙盒自动生成 Nginx location 块：

# DEV-005 小草莓的沙盒路由
location /DEV-005/ {
    alias /var/www/DEV-005/;
    index index.html;
    try_files $uri $uri/ =404;
}

# 模块快捷路径（可选，由系统配置）
location /status-board/ {
    alias /var/www/DEV-005/status-board/;
    index index.html;
}
location /cost-control/ {
    alias /var/www/DEV-005/cost-control/;
    index index.html;
}

⚠️ 模块快捷路径 由系统统一配置，开发者不自行修改 Nginx。

如需新增路由，向系统（妈妈/铸渊）提交申请。

三、责任边界（谁修什么）

问题类型	谁负责修	举例
Nginx 全局配置变更	🏛️ 系统（妈妈/铸渊）	新增 server 块、SSL 续期、全局重定向
新开发者开户（建沙盒目录）	🏛️ 系统（铸渊自动化）	新 DEV 加入 → 自动创建目录+权限+路由
模块部署报错（403/404/500）	🏠 开发者自己	文件名错了？权限不对？路径不对？自查自修
模块代码 bug	🏠 开发者自己	JS 报错、样式崩了、API 调不通
跨模块依赖问题	🏠 相关开发者协商 • 系统仲裁	小草莓的看板调页页的 API 报错 → 两人排查
PM2 进程崩溃（后端/机器人）	🏛️ 系统 • 相关开发者	舒舒/秋秋进程挂了 → 系统重启 + 开发者查原因

四、部署前自检清单

开发者在部署前必须完成以下自检：

#!/bin/bash
# deploy-check.sh · 部署前自检脚本
# 用法：bash /var/www/_shared/deploy-check.sh DEV-005 cost-control

DEV_ID=$1
MODULE=$2
BASE="/var/www/${DEV_ID}/${MODULE}"

echo "===== 🔍 部署自检：${DEV_ID} / ${MODULE} ====="

# R-01：入口文件检查
if [ ! -f "${BASE}/index.html" ]; then
  echo "❌ R-01 FAIL：${BASE}/index.html 不存在！"
  echo "   → 你的入口文件必须叫 index.html"
  exit 1
else
  echo "✅ R-01 PASS：入口文件存在"
fi

# R-02：目录权限检查
DIR_PERM=$(stat -c '%a' "${BASE}")
if [ "$DIR_PERM" != "755" ]; then
  echo "❌ R-02 FAIL：目录权限为 ${DIR_PERM}，应为 755"
  echo "   → 执行：chmod 755 ${BASE}"
  exit 1
else
  echo "✅ R-02 PASS：目录权限正确"
fi

# R-03：owner 检查
OWNER=$(stat -c '%U:%G' "${BASE}")
if [ "$OWNER" != "nginx:nginx" ]; then
  echo "❌ R-03 FAIL：owner 为 ${OWNER}，应为 nginx:nginx"
  echo "   → 执行：chown -R nginx:nginx ${BASE}"
  exit 1
else
  echo "✅ R-03 PASS：owner 正确"
fi

# R-07：中文标点检查（仅检查 .html/.css/.js/.conf）
CHINESE=$(grep -rn '[；：""''（）【】]' "${BASE}" --include='*.html' --include='*.css' --include='*.js' --include='*.conf' 2>/dev/null)
if [ -n "$CHINESE" ]; then
  echo "⚠️ R-07 WARN：发现中文标点"
  echo "$CHINESE"
else
  echo "✅ R-07 PASS：无中文标点"
fi

echo ""
echo "===== ✅ 全部通过！可以部署 ====="

五、冒烟检查（部署后验证）

部署完成后，系统自动 curl 检查所有已上线模块：

#!/bin/bash
# smoke-test.sh · 部署后冒烟检查
# 铸渊每次部署后自动运行 + 每天两次定时运行

echo "===== 🔥 冒烟检查 · $(date '+%Y-%m-%d %H:%M') ====="

# 所有已注册的模块 URL
URLS=(
  "https://guanghulab.com/|主站首页"
  "https://guanghulab.com/status-board/|DEV-005·看板"
  "https://guanghulab.com/cost-control/|DEV-005·成本控制"
  # 后续新模块上线时追加
)

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" ]; then
    echo "✅ ${name} → ${STATUS}"
  else
    echo "❌ ${name} → ${STATUS} ⚠️ 异常！"
    FAILED=$((FAILED+1))
  fi
done

echo ""
if [ $FAILED -eq 0 ]; then
  echo "===== ✅ 全部通过 ====="
else
  echo "===== ❌ ${FAILED} 个模块异常 ====="
  exit 1
fi

六、开发者入住流程（新 DEV 加入时）

新开发者获得 DEV 编号
       ↓
铸渊自动执行「开户脚本」：
  ① mkdir -p /var/www/DEV-XXX
  ② chown nginx:nginx /var/www/DEV-XXX
  ③ chmod 755 /var/www/DEV-XXX
  ④ 生成 .deploy-profile（编号+邮箱+创建时间）
  ⑤ 在 Nginx 配置中添加 location /DEV-XXX/ 块
  ⑥ nginx -t && systemctl reload nginx
       ↓
开发者沙盒就绪 · 可以开始部署模块

七、协议版本号与兼容性

版本	日期	变更
v1.0	2026-03-15	首版发布 · 沙盒隔离+准入规则+自检脚本+冒烟检查+责任边界

后续协议版本升级时，所有开发者沙盒必须在 72小时内 适配新版本。

不适配 = 模块下线。系统不做向下兼容。

八、引用方式

所有部署类广播必须在开头引用本协议：

⚠️ 本广播受「服务器部署适配协议 v1.0」约束。
部署前请完成自检清单，部署后系统自动冒烟检查。
模块内部问题由开发者自行排查修复。

10 KiB Raw Permalink Blame History Unescape Escape

🏗️ 服务器部署适配协议 v1.0（2026-03-15·曜冥签发）

一、基础概念：三层分离架构

二、开发者沙盒规范（你的房子的规则）

2.1 目录结构

2.2 准入规则（你的模块必须满足这些才能上线）

2.3 Nginx location 路由规则

三、责任边界（谁修什么）

四、部署前自检清单

五、冒烟检查（部署后验证）

六、开发者入住流程（新 DEV 加入时）

七、协议版本号与兼容性

八、引用方式

10 KiB

Raw Permalink Blame History