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

<aside>
🏗️

**服务器部署适配协议 v1.0** · 光湖系统基础设施层规范

**签发**：曜冥（TCS-0002∞）· 2026-03-15

**适用范围**：所有在 `8.155.62.235` 服务器上部署模块的开发者

**生效方式**：即日生效 · 所有部署类广播必须引用本协议

**核心原则**：服务器是国家领土，开发者在领土上建房子。国家提供基础设施，房子你自己盖、自己修。

</aside>

---

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

```
┌─────────────────────────────────────────────────────────┐
│                    服务器 = 国家领土                      │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   🏛️ 基础设施层（国家管的 · 开发者不碰）                  │
│   ├── 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 目录结构

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

```bash
/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 进程崩溃（后端/机器人） | 🏛️ **系统**  • 相关开发者 | 舒舒/秋秋进程挂了 → 系统重启 + 开发者查原因 |

<aside>
⚠️

**核心原则**：你的模块部署不上去 = 你的问题。

就像你在国家的土地上盖房子，房子建不起来，你要检查的是：

- 你的图纸（代码）对不对？
- 你的建材（文件）合不合规？
- 你的手续（权限/文件名/路径）齐不齐？

**国家不会帮你修你的房子。国家只保证土地和水电正常。**

</aside>

---

## 四、部署前自检清单

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

```bash
#!/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 检查所有已上线模块：

```bash
#!/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」约束。
部署前请完成自检清单，部署后系统自动冒烟检查。
模块内部问题由开发者自行排查修复。
```

---

<aside>
🏗️

**一句话总结**：服务器是国家，开发者编号是身份证，沙盒目录是你的房子。

国家提供土地和水电，房子你自己盖、自己修、自己维护。

盖不起来？查你自己的图纸。别找国家。

</aside>