insertjokehere/cloudflare-stun

cloudflare-stun

镜像概述和主要用途

cloudflare-stun是一款通过STUN协议实现CloudFlare动态DNS更新的工具。与传统依赖第三方IP查询服务（如jsonip.com）的动态DNS客户端不同，该工具使用标准STUN协议直接获取系统公网IP，提高了IP获取的可靠性和标准化程度。适用于需要动态更新CloudFlare DNS记录的场景，如家庭服务器、动态IP环境下的服务访问等。

核心功能和特性

• STUN协议IP获取：通过STUN协议直接查询公网IP，无需依赖第三方IP查询服务
• CloudFlare API集成：支持通过CloudFlare API创建或更新A记录
• 灵活的记录配置：可指定DNS记录名称，支持更新区域根记录或子域名记录
• 认证方式：支持通过环境变量或命令行参数提供CloudFlare认证信息（***和密钥）
• 自定义参数：可配置STUN服务器、端口、DNS记录TTL，支持强制更新及调试/安静模式

使用场景和适用范围

• 家庭网络或动态IP环境下，需要将动态公网IP绑定到固定域名
• 对第三方IP查询服务可靠性有要求的场景
• 需要自动化更新CloudFlare DNS记录的服务器或设备
• 开发/测试环境中需要快速验证DNS记录更新功能

使用方法和配置说明

快速启动

通过环境变量提供CloudFlare认证信息，更新指定DNS记录：

bash
CF_AUTH_EMAIL="foo@bar.com" CF_AUTH_KEY="abcde1234" cloudflare_stun --zone example.com --record-name extrn

上述命令将为extrn.example.com创建或更新A记录，记录值为运行工具的机器的公网IP。

详细参数说明

cloudflare_stun [-h] --zone ZONE [--record-name RECORD_NAME]
                    [--cf-auth-key CF_AUTH_KEY]
                    [--cf-auth-email CF_AUTH_EMAIL]
                    [--stun-server STUN_SERVER] [--stun-port STUN_PORT]
                    [--ttl TTL] [--force-update] [--debug | --quiet]

必选参数

• --zone ZONE: 要更新的区域名称（例如example.com）

可选参数

• --record-name RECORD_NAME: 要更新的记录名称。若区域为example.com且记录名称为extrn，则更新extrn.example.com。若省略，将更新区域根记录
• --cf-auth-key CF_AUTH_KEY: CloudFlare认证密钥。若未通过环境变量CF_AUTH_KEY设置，则必须指定
• --cf-auth-email CF_AUTH_EMAIL: CloudFlare认证***。若未通过环境变量CF_AUTH_EMAIL设置，则必须指定
• --stun-server STUN_SERVER: 要查询的STUN服务器
• --stun-port STUN_PORT: STUN服务器端口
• --ttl TTL: 新DNS记录的TTL值（仅在记录不存在时使用）
• --force-update: 强制更新记录，即使当前记录已正确
• --debug: 输出详细调试信息
• --quiet: 不输出任何信息

Docker部署示例

docker run命令

bash
docker run -e CF_AUTH_EMAIL="your@cloudflare.email" -e CF_AUTH_KEY="your_cloudflare_api_key" docker.xuanyuan.run/cloudflare-stun --zone example.com --record-name home --ttl 300

环境变量说明

已知问题

• 仅支持Python 2.7，因底层STUN库（pystun）不支持Python 3.x。详情请参考https://github.com/jtriley/pystun。