Skip to content

Cloudflare Tunnel 管理工具

本文档介绍 Cloudflare Tunnel 管理工具的使用方法，这是一个用于简化开发环境隧道管理的便捷脚本。

概述

tunnel-manager.sh 是一个 Shell 脚本，提供了统一的接口来管理 Cloudflare Tunnel 服务。它简化了日常的隧道操作，包括启动、停止、状态查看等。

功能特性

  • ✅ 一键启动/停止：简单的命令启动或停止隧道服务
  • ✅ 状态监控：实时查看隧道连接状态和本地服务状态
  • ✅ 日志查看：快速访问隧道日志进行故障排除
  • ✅ 服务测试：自动测试本地服务的可用性
  • ✅ 配置编辑：直接编辑隧道配置文件
  • ✅ 代理处理：自动处理本地代理环境变量冲突

安装位置

tools/tunnel-manager.sh

基本用法

查看帮助

./tools/tunnel-manager.sh
# 或者
./tools/tunnel-manager.sh --help

输出示例： 

Cloudflare Tunnel 管理脚本

用法: ./tools/tunnel-manager.sh {start|stop|restart|status|logs|config|test}

命令说明:
  start   - 启动隧道
  stop    - 停止隧道
  restart - 重启隧道
  status  - 查看隧道状态
  logs    - 查看隧道日志
  config  - 编辑配置文件
  test    - 测试本地服务

服务列表:
  - dev.jimmysong.io  → localhost:1313 (Hugo)
  - n8n.jimmysong.io  → localhost:5678 (n8n)

详细命令

启动隧道

./tools/tunnel-manager.sh start
  • 检查隧道是否已在运行
  • 自动处理代理环境变量
  • 后台启动隧道服务
  • 显示启动状态

停止隧道

./tools/tunnel-manager.sh stop
  • 优雅地停止所有 cloudflared 进程
  • 确认停止状态

重启隧道

./tools/tunnel-manager.sh restart
  • 停止现有隧道
  • 等待进程完全停止
  • 重新启动隧道服务

查看状态

./tools/tunnel-manager.sh status

显示信息： - 隧道列表和连接状态 - 运行中的 cloudflared 进程 - 连接的边缘服务器位置

示例输出： 

隧道状态:
ID                                   NAME     CREATED              CONNECTIONS
6610bd3f-6820-4827-a209-e839c28400d3 hugo-dev 2025-07-12T00:38:59Z 2xlax01, 2xlax08

运行进程:
jimmy    37984  0.0  0.1  cloudflared tunnel --config ~/.cloudflared/dev-services-config.yml run hugo-dev

查看日志

./tools/tunnel-manager.sh logs
  • 实时查看隧道日志
  • 使用 Ctrl+C 退出日志查看
  • 日志位置：/tmp/dev-services-tunnel.log

编辑配置

./tools/tunnel-manager.sh config
  • 使用默认编辑器打开配置文件
  • 配置文件位置：~/.cloudflared/dev-services-config.yml
  • 支持环境变量 $EDITOR

测试本地服务

./tools/tunnel-manager.sh test

测试结果示例： 

测试本地服务连接:
Hugo 开发服务器 (localhost:1313): 200
n8n 服务 (localhost:5678): 200

Makefile 集成

脚本已集成到项目的 Makefile 中，可以通过以下方式使用：

通过 make dev 启动

make dev

自动启动完整的开发环境，包括： - Cloudflare Tunnel - Hugo 开发服务器 - 浏览器预览

通过 make tunnel 管理

# 查看隧道状态
make tunnel ACTION=status

# 查看隧道日志
make tunnel ACTION=logs

# 停止隧道
make tunnel ACTION=stop

# 测试本地服务
make tunnel ACTION=test

配置文件

脚本使用的配置文件：~/.cloudflared/dev-services-config.yml

# Cloudflare Tunnel: 开发环境多服务隧道
tunnel: hugo-dev
credentials-file: ~/.cloudflared/6610bd3f-6820-4827-a209-e839c28400d3.json

ingress:
  # Hugo 开发服务器
  - hostname: dev.jimmysong.io
    service: http://localhost:1313
  # n8n 工作流自动化平台
  - hostname: n8n.jimmysong.io
    service: http://localhost:5678
  # Catch-all rule
  - service: http_status:404

环境要求

必需依赖

  • cloudflared：Cloudflare Tunnel 客户端
  • bash/zsh：Shell 环境
  • curl：用于服务测试

检查依赖

# 检查 cloudflared
which cloudflared

# 检查版本
cloudflared --version

日志文件

隧道运行时的日志文件位置：

  • 主日志：/tmp/dev-services-tunnel.log
  • Cloudflare 配置：~/.cloudflared/

查看实时日志： 

tail -f /tmp/dev-services-tunnel.log

故障排除

常见问题

  1. 隧道无法启动 

    # 检查配置文件
./tools/tunnel-manager.sh config

# 查看详细日志
./tools/tunnel-manager.sh logs

  2. 本地服务无法访问 

    # 测试本地服务
./tools/tunnel-manager.sh test

# 检查端口占用
lsof -i :1313
lsof -i :5678

  3. 代理环境干扰

  4. 脚本自动处理代理环境变量
  5. 如有问题，手动清除： 
    unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY

调试模式

添加调试输出： 

# 在脚本顶部添加
set -x  # 启用调试模式
set +x  # 关闭调试模式

高级用法

添加新服务

  1. 编辑配置文件： 

    ./tools/tunnel-manager.sh config

  2. 在 ingress 段添加新服务： 

    - hostname: new-service.jimmysong.io
  service: http://localhost:PORT

  3. 重启隧道： 

    ./tools/tunnel-manager.sh restart

多隧道管理

如需管理多个隧道，可以：

  1. 复制脚本： 

    cp tools/tunnel-manager.sh tools/tunnel-manager-prod.sh

  2. 修改配置文件路径和隧道名称

  3. 独立管理不同环境的隧道

性能监控

连接状态监控

# 持续监控隧道状态
watch -n 5 './tools/tunnel-manager.sh status'

日志分析

# 查看连接错误
grep "ERR" /tmp/dev-services-tunnel.log

# 查看成功连接
grep "Registered tunnel connection" /tmp/dev-services-tunnel.log

最佳实践

  1. 开发流程： 

    # 1. 启动开发环境
make dev

# 2. 开发过程中查看状态
make tunnel ACTION=status

# 3. 出现问题时查看日志
make tunnel ACTION=logs

# 4. 完成开发后停止服务
make stop

  2. 故障排除流程： 

    # 1. 测试本地服务
./tools/tunnel-manager.sh test

# 2. 检查隧道状态
./tools/tunnel-manager.sh status

# 3. 查看详细日志
./tools/tunnel-manager.sh logs

# 4. 重启服务
./tools/tunnel-manager.sh restart

  3. 定期维护：

  4. 定期检查日志文件大小
  5. 监控隧道连接稳定性
  6. 更新 cloudflared 版本

相关文档

脚本源码

完整的脚本源码位于：tools/tunnel-manager.sh

主要函数： - start(): 启动隧道服务 - stop(): 停止隧道服务 - status(): 显示运行状态 - test(): 测试本地服务 - logs(): 显示实时日志

提示：建议将此脚本添加到 PATH 中，或创建别名以便全局访问：

# 添加到 ~/.zshrc 或 ~/.bashrc
alias tunnel='~/path/to/website/tools/tunnel-manager.sh'