Cloudflare Tunnel 配置指南

Claude Code Everywhere 的预览功能使用 Cloudflare Tunnel 将本地运行的项目暴露到公网，让您可以随时随地通过手机或其他设备访问预览。

前置要求

在使用预览功能之前，需要在运行 Claude Code Everywhere 的服务器上安装 cloudflared。

安装 cloudflared

macOS

使用 Homebrew 安装：

brew install cloudflared

Linux

Ubuntu/Debian

# 下载最新版本
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared

# 添加执行权限
chmod +x cloudflared

# 移动到系统路径
sudo mv cloudflared /usr/local/bin/

CentOS/RHEL

# 下载最新版本
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared

# 添加执行权限
chmod +x cloudflared

# 移动到系统路径
sudo mv cloudflared /usr/local/bin/

Windows

访问 Cloudflare Tunnel 发布页面
下载 cloudflared-windows-amd64.exe
将文件重命名为 cloudflared.exe
将文件路径添加到系统 PATH 环境变量

验证安装

安装完成后，运行以下命令验证：

cloudflared --version

如果看到版本号输出，说明安装成功。

使用说明

工作原理

Claude Code Everywhere 使用 Cloudflare Tunnel 的临时隧道功能（Quick Tunnels）：

无需注册：不需要 Cloudflare 账号
自动生成 URL：每次启动自动生成临时的 https://xxx.trycloudflare.com URL
零配置：系统自动调用 cloudflared tunnel --url localhost:<port> 命令

限制说明

由于使用的是 Cloudflare 的免费临时隧道功能，有以下限制：

URL 不固定：每次启动生成新的随机 URL
临时访问：适合开发预览，不适合长期生产环境
带宽限制：受 Cloudflare 免费计划限制

如需长期稳定的 URL，建议：

注册 Cloudflare 账号
配置 Named Tunnel
或使用其他内网穿透方案（如 ngrok, frp 等）

配置项目预览

添加新项目时配置

@机器人 添加目录 blog /path/to/blog 启用预览 启动命令是 npm run dev 端口是 3000

或者使用自然语言：

@机器人 给我添加一个博客项目，路径是 /path/to/blog，启用预览功能，用 npm run dev 启动，端口 3000

更新现有项目配置

# 启用预览
@机器人 给 blog 启用预览，启动命令是 npm run dev，端口 3000

# 禁用预览
@机器人 禁用 blog 的预览

预览功能使用

自动启动

当项目配置了预览功能后，Claude Code 任务成功完成时会自动启动预览：

@机器人 [dir:blog] 帮我优化首页性能

任务完成后，系统会：

启动项目（执行 start_cmd 配置的命令）
启动 Cloudflare Tunnel
返回预览 URL

手动管理

启动预览

@机器人 启动 blog 的预览
@机器人 预览 blog 项目

查看预览状态

# 查看所有运行中的预览
@机器人 查看预览状态
@机器人 预览服务的状态

# 查看指定项目的预览状态
@机器人 blog 的预览状态

停止预览

# 停止指定项目的预览
@机器人 停止 blog 的预览

# 停止所有预览
@机器人 停止所有预览

支持的项目类型

预览功能支持任何可以在本地启动 HTTP 服务的项目：

Node.js 项目

@机器人 添加目录 web /path/to/web-app 启用预览 启动命令是 npm run dev 端口 3000

Python 项目

@机器人 添加目录 api /path/to/flask-app 启用预览 启动命令是 python app.py 端口 5000

Go 项目

@机器人 添加目录 go-app /path/to/go-app 启用预览 启动命令是 go run main.go 端口 8080

静态网站服务器

@机器人 添加目录 static /path/to/site 启用预览 启动命令是 python -m http.server 8000 端口 8000

Docker 容器

@机器人 添加目录 docker /path/to/docker-app 启用预览 启动命令是 docker-compose up 端口 3000

常见问题

Q: 预览启动失败怎么办？

A: 检查以下几点：

cloudflared 是否已安装
```
cloudflared --version
```
启动命令是否正确
```
@机器人 查看 blog 的详情
```
检查启动命令配置

端口是否被占用

lsof -i :3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

查看服务日志 系统会将项目和 Tunnel 的日志输出到控制台

Q: 预览 URL 无法访问怎么办？

A: 可能原因：

项目未正确启动：检查项目进程是否运行
端口配置错误：确认项目监听端口与配置的端口一致
防火墙阻止：检查本地防火墙设置
Tunnel 未建立：重启预览服务

Q: 如何停止所有预览服务？

A: 有两种方式：

使用命令停止：
```
@机器人 停止所有预览
```
重启 Claude Code Everywhere 服务：服务启动时会自动清理之前的预览服务

Q: 预览 URL 会一直有效吗？

A: 不会。预览 URL 的有效期取决于：

手动停止：停止预览时 URL 失效
服务重启：Claude Code Everywhere 服务重启时会停止所有预览
进程崩溃：如果项目进程或 Tunnel 进程崩溃，URL 会失效

Q: 可以同时运行多个预览吗？

A: 可以！系统支持同时运行多个项目的预览，每个项目有独立的：

项目进程
Cloudflare Tunnel 进程
预览 URL

Q: 预览功能会消耗很多资源吗？

A: 资源消耗主要来自：

项目本身的进程
Cloudflare Tunnel 进程（非常轻量）

建议在不需要预览时及时停止服务。

安全建议

不要暴露敏感信息：预览 URL 是公开的，任何人都可以访问
使用开发环境：预览功能适合开发环境，不建议用于生产
定期清理：不使用时及时停止预览服务
限制访问：如需限制访问，在项目中实现认证功能

进阶配置

自定义启动脚本

如果项目启动需要多个步骤，可以创建启动脚本：

# start-preview.sh
#!/bin/bash
export NODE_ENV=development
npm install
npm run build
npm run dev

然后配置：

@机器人 添加目录 blog /path/to/blog 启用预览 启动命令是 ./start-preview.sh 端口 3000

环境变量

启动命令会继承当前进程的环境变量，可以在 .env 文件中配置。

多端口项目

如果项目需要监听多个端口，建议：

配置主端口（前端访问端口）
在项目内部处理端口转发

故障排查

查看运行中的预览服务

@机器人 查看预览状态

查看进程状态

# 查看项目进程
ps aux | grep "npm run dev"

# 查看 Tunnel 进程
ps aux | grep cloudflared

手动测试 Cloudflare Tunnel

# 启动一个简单的 HTTP 服务
python -m http.server 8000

# 在另一个终端启动 Tunnel
cloudflared tunnel --url http://localhost:8000

如果手动测试成功，说明 cloudflared 安装正确。

FilesExpand file tree

PREVIEW_SETUP.md

Latest commit

History