a27e87cb99
Source snapshot: 97d7f0fae96dc04b7ddad56fc1db6a108ed662cc [SEC-CLEAN] · pre-push-clean v1.0 · 109处敏感信息已自动转乱码
302 lines
10 KiB
Markdown
302 lines
10 KiB
Markdown
# 🏗️ 服务器部署适配协议 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> |