[moz] docs(§98): CloudCLI 外网部署与 VPS 服务暴露规范

docs/design/98-cloudcli-external-deployment.md

@@ -0,0 +1,131 @@
+---
+title: "专题 98 — CloudCLI 外网部署与 VPS 服务暴露规范"
+created: 2026-06-25
+version: v1.0
+status: active
+changelog: v1.0 初版
+---
+
+# 专题 98 — CloudCLI 外网部署与 VPS 服务暴露规范
+
+## 1. 概述
+
+CloudCLI 通过 FRP 内网穿透 + VPS Caddy 反代，绑定到 `claude.mysanguo.top` 实现外网访问。
+
+整体链路：外网设备 → HTTPS → VPS Caddy（SSL 自动签发 + 反代）→ FRP 隧道 → Mac Mini CloudCLI。
+
+## 2. 架构图
+
+```
+外网设备（浏览器）
+    ↓ HTTPS
+首尔 VPS 43.133.235.218
+    ├── Caddy :443（SSL 自动签发 + 反代）
+    │   └── claude.mysanguo.top → 127.0.0.1:13001
+    └── frps :7000
+         ↓ FRP 隧道
+    Mac Mini frpc
+         └── 127.0.0.1:3001 → CloudCLI（launchd 持久化）
+```
+
+## 3. 配置详情
+
+### 3.1 DNS 记录（NameSilo）
+
+| 主机记录 | 类型 | 值 | TTL |
+|----------|------|-----|-----|
+| claude | A | 43.133.235.218 | 3600 |
+
+### 3.2 frpc 配置（Mac Mini）
+
+配置文件路径：`~/.local/etc/frpc.toml`
+
+```toml
+[[proxies]]
+name = "cloudcli"
+type = "tcp"
+localIP = "127.0.0.1"
+localPort = 3001
+remotePort = 13001
+```
+
+重启方式：
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.sanguo.frpc.plist
+launchctl load ~/Library/LaunchAgents/com.sanguo.frpc.plist
+```
+
+### 3.3 VPS Caddy 配置
+
+配置文件路径：`/etc/caddy/Caddyfile`
+
+```caddyfile
+claude.mysanguo.top {
+    reverse_proxy 127.0.0.1:13001
+}
+```
+
+重载：`sudo systemctl reload caddy`
+
+### 3.4 CloudCLI 持久化（Mac Mini）
+
+- LaunchAgent：`~/Library/LaunchAgents/com.cloudcli.server.plist`
+- 命令：`cloudcli start --port 3001`
+- 日志：`~/.cloudcli/server.log`
+- 绑定地址：`0.0.0.0:3001`
+
+## 4. ⚠️ 关键教训：腾讯云防火墙不需要开后端端口
+
+### 问题
+
+配置完成后，误以为需要在腾讯云轻量服务器防火墙中开放 13001/TCP 端口。
+
+### 根因
+
+混淆了"VPS 对外暴露端口"和"Caddy 内部反代端口"的概念。
+
+### 正确理解
+
+```
+外网 → :443（Caddy HTTPS）→ 127.0.0.1:13001（VPS 内部回环）→ FRP 隧道 → Mac Mini :3001
+                                                    ↑
+                                          这段是 VPS 本地回环通信
+                                          不经过腾讯云防火墙
+```
+
+### 规则
+
+- 腾讯云防火墙只需要开放 **80/443**（Caddy 对外 HTTPS 入口）
+- Caddy 到后端服务的反代走 `127.0.0.1`（本地回环），**不需要在腾讯云防火墙开放后端端口**
+- ufw 同理，但 ufw 默认不拦截 lo（loopback）接口，所以 `ufw allow 13001` 虽然无害但也无必要
+- 只有当服务直接对外暴露（不经过 Caddy 反代）时，才需要在防火墙开放对应端口
+
+### 判断方法
+
+如果 Caddy 配置中写的是 `reverse_proxy 127.0.0.1:XXXX`，则 XXXX 端口不需要对外开放。
+
+## 5. 当前外网服务清单
+
+| 子域名 | VPS Caddy 反代 | FRP 隧道远端端口 | 内网目标 | 服务 |
+|--------|---------------|-----------------|---------|------|
+| oc.mysanguo.top | → 127.0.0.1:18789 | 18789 | 127.0.0.1:18789 | OpenClaw |
+| git.mysanguo.top | → 127.0.0.1:13000 | 13000 | 192.168.2.154:3000 | Gitea |
+| claude.mysanguo.top | → 127.0.0.1:13001 | 13001 | 127.0.0.1:3001 | CloudCLI |
+
+## 6. 添加新外网服务的标准流程
+
+1. NameSilo 添加 DNS A 记录（仅此步需要手动操作）
+2. Mac Mini frpc.toml 新增隧道段
+3. VPS Caddyfile 新增 `reverse_proxy` 段
+4. reload caddy + 重启 frpc
+5. 验证 `curl -I https://新域名`
+
+!!! warning "注意"
+    **不需要在腾讯云防火墙或 ufw 开放后端端口**（除非绕过 Caddy 直接暴露）。
+
+## 7. 安全说明
+
+- CloudCLI 自带账号密码认证（session + cookie），作为唯一安全层
+- 未配置 Caddy Basic Auth（避免双重密码体验差）
+- 如需增强安全，可在 Caddy 层加 Basic Auth 或 IP 白名单