Files

T

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

2026-06-25 07:24:54 +08:00

3.8 KiB

Raw Blame History

title, created, version, status, changelog

title	created	version	status	changelog
专题 98 — CloudCLI 外网部署与 VPS 服务暴露规范	2026-06-25	v1.0	active	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

[[proxies]]
name = "cloudcli"
type = "tcp"
localIP = "127.0.0.1"
localPort = 3001
remotePort = 13001

重启方式：

launchctl unload ~/Library/LaunchAgents/com.sanguo.frpc.plist
launchctl load ~/Library/LaunchAgents/com.sanguo.frpc.plist

3.3 VPS Caddy 配置

配置文件路径：/etc/caddy/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. 添加新外网服务的标准流程

NameSilo 添加 DNS A 记录（仅此步需要手动操作）
Mac Mini frpc.toml 新增隧道段
VPS Caddyfile 新增 reverse_proxy 段
reload caddy + 重启 frpc
验证 curl -I https://新域名

!!! warning "注意" 不需要在腾讯云防火墙或 ufw 开放后端端口（除非绕过 Caddy 直接暴露）。

7. 安全说明

CloudCLI 自带账号密码认证（session + cookie），作为唯一安全层
未配置 Caddy Basic Auth（避免双重密码体验差）
如需增强安全，可在 Caddy 层加 Basic Auth 或 IP 白名单

3.8 KiB Raw Blame History Unescape Escape