YANG JIANKUAN
5326c572a2
迁入通用节点部署工具、离线交付页生成器和共用技能，隔离真实配置与交付产物。统一 Codex 与 Claude Code 开发约定，补充节点迁移与运维文档。 完善 FINAL、策略组引用、输入校验、Surge 字段编码与 AI DNS 例外保护，增加隔离测试和订阅验证工具。 验证：全量类型检查、44 项单测、前端构建、脚本语法、技能入口与凭据隔离检查均通过。
72 lines
5.5 KiB
Markdown
72 lines
5.5 KiB
Markdown
# {{HOST_LABEL}} 运维指南（edge-node-multi-protocol）
|
||
|
||
本指南基于 `edge-node-multi-protocol` skill 部署的真实节点整理，适用于维护这台节点或用同一个 skill 部署新节点。
|
||
|
||
---
|
||
|
||
## 一、这套系统是什么
|
||
|
||
一键把一台裸的 Debian/Ubuntu VPS 变成：
|
||
|
||
```
|
||
用户 ──HTTPS──▶ nginx（aaPanel管理） ──┬─▶ aaPanel 面板（反代到 127.0.0.1:面板端口）
|
||
├─▶ 3x-ui 面板（反代到 127.0.0.1:14533）
|
||
└─▶ 节点伪装域名 {{SUB_COVER}}.{{DOMAIN_ROOT}}
|
||
├─ VMess direct/WARP (2 inbound)
|
||
├─ Trojan direct/WARP (2 inbound)
|
||
└─ Shadowsocks direct/WARP (2 inbound)
|
||
每个 direct 直接出公网
|
||
每个 WARP 走 WARP SOCKS5(127.0.0.1:{{WARP_SOCKS_PORT}}) 出 Cloudflare
|
||
```
|
||
|
||
外层是泛域名 TLS（acme.sh 自动续期）+ Cloudflare DNS（灰云，不走 CF 代理），三个协议的六个 inbound 共用同一份证书和同一个 cover 域名。
|
||
|
||
## 二、部署一台新节点的标准流程
|
||
|
||
见 `SKILL.md` → Workflow，简要版：
|
||
|
||
```
|
||
00-preflight → 02-cf-dns → 03-sign-wildcard-cert
|
||
→ 04-install-aapanel → 05-harden-aapanel → 04b-install-nginx
|
||
→ 06-install-warp → 06b-warp-watchdog
|
||
→ 07-install-3xui → 08-xui-bootstrap（一次性建好全部6个inbound）
|
||
→ 09-aapanel-sites → 09b-default-444
|
||
→ 10-ufw → 11-monitoring（可选）
|
||
→ 12-smoke-test（验证全部6条线路）
|
||
→ 14-generate-links-and-qr（本地运行，出分享链接+二维码）
|
||
```
|
||
|
||
## 三、这套 skill 已修复的版本兼容坑
|
||
|
||
来自实战踩坑，脚本里已经改好，这里记录原因方便你判断"要不要重新核实"：
|
||
|
||
### 坑 1：aaPanel 安装等待循环的 pgrep 自匹配 bug
|
||
|
||
早期版本用 `pgrep -f install_7.0` 判断安装进程是否还在跑，但这条检查命令自己的命令行文本里就含有 `"install_7.0"` 字符串，导致 pgrep 把自己也匹配进去，判断条件永远为假，脚本卡死轮询——即使安装其实早就装完了（通常 1 分钟左右）。**已修复**：现在改成检查安装日志里的 `Congratulations! Installed successfully!` 字符串。
|
||
|
||
### 坑 2：aaPanel 7.x 把部分内部模块挪到了 `class_v2` 目录
|
||
|
||
建站脚本原本只把 `/www/server/panel` 和 `/www/server/panel/class` 加进 `sys.path`，缺了 `/www/server/panel/class_v2`，导致 `ModuleNotFoundError: theme_config`。**已修复**：`09-aapanel-sites.py` 已经加上了这一行。如果你手写新脚本要 import 面板内部模块，记得也加上。
|
||
|
||
### 坑 3：aaPanel 反爬虫策略比早期文档写的更严格
|
||
|
||
用 curl 测试面板入口时，UA 必须是完整真实的浏览器 UA（如 `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15) AppleWebKit/605.1.15`），过于简单的 UA（哪怕带 "Mozilla" 字样）会被判定为扫描器，返回伪装的 404。**排查经验**：如果面板域名/入口路径怎么测都是 404，**先别怀疑域名绑定、CDN_PROXY、证书配置**——先换一个更真实的浏览器 UA 字符串重新 curl，或者直接用真实浏览器打开看看。`12-smoke-test.sh` 已经用了正确的 UA。
|
||
|
||
### 坑 4：3x-ui 的 client 表是"协议通用凭据表"
|
||
|
||
VMess/VLESS 用 `uuid` 列，Trojan/Shadowsocks 用 `password` 列；`client_traffics.email` 全局唯一（一个 client 一行，不是一个 inbound 一行）；WARP 路由规则要"追加"而不是"整个重写"，否则会把已有协议的路由覆盖掉。完整表结构和新增协议的步骤见 `references/3x-ui-schema.md`。
|
||
|
||
## 四、日常运维
|
||
|
||
- **重启 aaPanel**：只能用 `/etc/init.d/bt restart`（或 `bt 1`），**绝对不能用** `systemctl restart btpanel`——systemd 单元的 `ExecStart` 走的是这条 SysV 脚本，`systemctl restart` 会把面板停掉且不会自动拉起，反代的面板域名直接 502。
|
||
- **重启 nginx**：同理用 `/etc/init.d/nginx reload/restart`，不要用 systemctl。
|
||
- **续期证书**：acme.sh 已经注册了 `--reloadcmd`，到期自动续期、自动重新部署到 4 个域名的证书目录、自动 reload nginx，不需要人工干预。可以用 `~/.acme.sh/acme.sh --list` 查看到期时间。
|
||
- **加新的代理客户端**（同一协议下加一个用户）：去 3x-ui 面板对已有 inbound 加 client，或者直接改数据库（面板 HTTP API 在这个版本上会 403，见坑4），参考 `references/3x-ui-schema.md`。
|
||
- **加新的协议**（第4个协议）：见 `SKILL.md` → "Adding a protocol to an already-provisioned node"，以及 `references/3x-ui-schema.md` 最后一节和 `references/protocol-choice.md` 关于什么时候值得加。
|
||
- **WARP 掉线自愈**：`warp-healthcheck.timer` 每 60 秒检查一次，通过 SOCKS5 代理实际发请求确认 `warp=on`，异常会自动重启 `warp-svc`。查看状态：`systemctl status warp-healthcheck.timer`。
|
||
- **防火墙**：只放行了 22/80/443/888/面板端口/39000-40000，六个协议 inbound 全部是 `127.0.0.1`-only、走 nginx 反代 443，不需要额外开端口。
|
||
|
||
## 五、监控（可选）
|
||
|
||
`11-monitoring.sh` 支持接入 Nezha / Komari。去 `config.env` 填 `NEZHA_SERVER`/`NEZHA_SECRET` 或 `KOMARI_ENDPOINT`/`KOMARI_DISCOVERY_KEY`，单独跑这一个脚本即可，不影响其他服务。
|