---
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 白名单