# 公网中继：部署与使用

中继让手机在外网（4G / 异地 WiFi）连回你电脑上的 CCGUI。**电脑侧零额外安装**：CCGUI 主动出站拨号到中继，本机不开入站端口。中继只按房间号撮合「桌面(host)」与「手机(guest)」两端，双向透明转发。

```
手机(外网, https://你的域名/)
        │  wss
        ▼
  Caddy(自动 HTTPS, 443) ──► node server.js(127.0.0.1:8080)
        ▲
        │  wss（CCGUI 主动出站拨号，不开入站端口）
   CCGUI(电脑)
```

> **不做端到端加密**：转发内容对中继运营者可见。请只部署在自己信任的 VPS。防闯入靠「高熵随机房间号 + 配对令牌」。

## 依赖与文件

中继目录 `relay/`：
- `server.js`：撮合 / 转发服务（Node）
- `package.json`：依赖仅 `ws`
- `public/ccgui.html`：可选的下载落地页
- `README.md`：同款部署说明

依赖安装：**Node.js 18+**，`cd relay && npm install`。

## 部署步骤（以 Debian / Ubuntu 为例）

1. 上传 `relay` 目录到服务器（如 `/opt/ccgui-relay`），装依赖：
   ```
   cd /opt/ccgui-relay && npm install
   ```
2. 放页面：把本项目生成的 `mobile-test.html` 传到中继目录并改名 `mobile.html`（手机打开 `https://你的域名/` 即加载它）。
3. 启动（建议 pm2 或 systemd 常驻）：
   ```
   PORT=8080 node server.js
   # 或： pm2 start server.js --name ccgui-relay
   ```
   `server.js` 只监听 `127.0.0.1:8080`（明文），TLS 交给前置反代。
4. 前置 Caddy 做自动 HTTPS。`/etc/caddy/Caddyfile`：
   ```
   你的域名 {
       reverse_proxy 127.0.0.1:8080
   }
   ```
   `systemctl reload caddy`。wss / https 都走 443，证书自动申请与续期。
5. **备案**：境内服务器用域名对外提供服务需 ICP 备案（在域名 / 服务器商处办理）。

## 与 CCGUI 对接

1. 桌面 CCGUI → 设置 →「公网中继（外网访问）」开启，填「中继地址 `wss://你的域名/`」。
2. CCGUI 自动出站拨号，用本机随机生成并持久化的「房间号 + 配对令牌」注册为 host。
3. 设置页显示「手机配对」链接 `https://你的域名/?room=xxxx&token=yyyy`，手机浏览器打开即自动连回本机（也可扫二维码）。

不同电脑各自随机房间号，互不冲突；一台中继可同时服务任意多对「电脑↔手机」。

## 落地页与下载（可选）

`relay/public/ccgui.html` 是一个下载落地页。若使用，把安装包 / APK 放到 `public/downloads/` 下，并在 Caddy 里让 `/ccgui.html` 与 `/downloads/*` 走 file_server、其余反代给 Node：
```
你的域名 {
    handle /ccgui.html   { root * /opt/ccgui-relay/public; file_server }
    handle /downloads/*  { root * /opt/ccgui-relay/public; file_server }
    handle               { reverse_proxy 127.0.0.1:8080 }
}
```

## systemd 常驻示例

`/etc/systemd/system/ccgui-relay.service`：
```
[Unit]
Description=CCGUI relay
After=network.target

[Service]
WorkingDirectory=/opt/ccgui-relay
ExecStart=/usr/bin/node server.js
Environment=PORT=8080
Restart=always

[Install]
WantedBy=multi-user.target
```
`systemctl enable --now ccgui-relay`。改了 `mobile.html` 无需重启（按请求读取）。

## 安全要点

- 只在信任的 VPS 部署；给他人用需告知「中继可见明文」。
- 务必置于 HTTPS（wss）之后，保证「手机↔中继」「电脑↔中继」两段链路传输层加密。
- 远程写入不绕过 Claude Code 的权限确认。
