lighthouse-fw：一个管理腾讯云轻量服务器防火墙的终端工具

背景一个反复折磨我的问题我有几台腾讯云轻量应用服务器Lighthouse防火墙规则里白名单写的是当前的公网出口 IP。问题是家里的宽带每次重新拨号IP 就会变从办公室访问服务器也是不同的IP。一旦 IP 变了SSH 连不上只能去腾讯云控制台手动改防火墙规则。一台服务器还好多几台就烦了——每台都要登录控制台找到防火墙删旧规则加新规则填 IP选协议端口……重复操作既枯燥又容易出错。我最初写了一个 Python 单文件脚本来自动化这件事。后来功能越加越多脚本从 200 行涨到 483 行开始难以维护。于是我把它重构成了一个完整的 Python 包并开源了出来。这就是 lighthouse-fw[1]。它能做什么核心功能一句话自动获取你的公网 IP然后批量更新多台 Lighthouse 服务器的防火墙白名单规则。具体来说•IP 自动探测从多个源获取当前公网 IPv4单源故障自动切换•增量更新只修改需要变更的规则不动其他规则减少误删风险•多服务器批量操作一次命令更新所有服务器单台失败不影响其他•TUI CLI 双模式终端图形界面和命令行都能用•密钥安全存储优先使用系统钥匙串回退到本地加密文件•Dry-run 预览执行前先看 diff确认后再写入快速开始安装不需要 clone 仓库不需要 pip install。用 uv[2]直接跑uvx lighthouse-fw这会自动下载并运行第一次运行会进入 TUI 界面。如果你更喜欢装成命令uv tool install lighthouse-fw lhfw初始化配置lhfw init这会在系统标准目录下创建配置文件和状态目录。添加凭据# 设置凭据元信息region、endpoint 等 lhfw credential set my-cred --region ap-guangzhou # 交互式输入 SecretId 和 SecretKey输入时不可见 lhfw credential set-secret my-cred密钥会自动存入系统钥匙串Windows Credential Manager / macOS Keychain / Linux Secret Service。如果系统没有安全的钥匙串后端会回退到 Fernet 加密的本地文件。添加服务器lhfw server set my-server \ --instance-id lhins-xxxxxx \ --credential my-cred \ --tag prod \ --tag cn \ --enabled添加防火墙规则# SSH 白名单CIDR 填 AUTO 会自动替换为当前公网 IP/32 lhfw server rule-add my-server \ --protocol TCP \ --port 22 \ --cidr AUTO \ --description SSH # HTTP lhfw server rule-add my-server \ --protocol TCP \ --port 80 \ --cidr 0.0.0.0/0 \ --description HTTP预览和执行# 先预览看看会改什么 lhfw run # 确认没问题后实际写入 lhfw run --applyrun命令会先做一次 dry-run展示 diff 预览红色删除、绿色新增然后询问确认。只有你输入y才会真正调用 API 写入。TUI终端里的图形界面如果你不喜欢敲命令直接运行lhfw或lighthouse-fw不带参数就会进入 TUIuvx lighthouse-fwTUI 基于 Textual[3]构建有四个标签页Servers— 管理服务器列表支持新增、编辑、批量选中、按 tag 过滤。编辑服务器时可以内联管理防火墙规则。Credentials— 管理凭据密钥字段默认隐藏需要时可以临时显示。Run— 执行面板。可以按 tag 批量选中服务器预览 diff一键 Apply。底部的 RichLog 实时显示执行日志。History— 查看最近 20 次执行记录包括时间、模式dry-run/apply、IP、结果摘要。Apply 之前会弹出确认对话框展示完整的变更 diff必须手动确认才会执行。核心设计增量 Diff 引擎lighthouse-fw 最重要的设计决策是增量更新而非全量覆盖。全量覆盖很简单——把现有规则全部删掉再写入新的。但这样做风险很大如果中间出错服务器可能完全失去防火墙保护。增量更新的逻辑是1. 获取服务器当前的所有防火墙规则2. 对比用户定义的managed_rules和现有规则3. 只计算需要变更的部分哪些要删、哪些要加4. 执行变更匹配策略基于 protocol port action 三元组。如果一条规则的协议、端口、动作都匹配但 CIDR 不同比如 IP 变了就删除旧的、创建新的。如果完全一致就跳过。这里有个关键的AUTO机制用户在配置中写cidrAUTO运行时会自动替换为当前公网 IP 的/32地址。这意味着你不需要手动写死 IP工具会自动探测并填充。def _build_desired_rule(managed_rule, current_ipv4): cidr managed_rule.cidr if cidr AUTO: cidr f{current_ipv4}/32 return RuleSpec( protocolmanaged_rule.protocol, portmanaged_rule.port, cidrcidr, actionmanaged_rule.action, descriptionmanaged_rule.description, )另一个细节是腾讯云的乐观锁机制。每次修改防火墙规则时需要传入一个FirewallVersion版本号。lighthouse-fw 在删除规则后会重新查询最新的版本号再执行创建操作避免版本冲突。安全设计密钥存储lighthouse-fw 不会把 API 密钥写在配置文件里。它有三级存储策略1.系统钥匙串优先Windows Credential Manager、macOS Keychain、Linux Secret Service/KWallet2.加密文件回退使用cryptography库的 Fernet 对称加密密钥和加密数据分开存储3.环境变量兼容支持通过secret_id_env/secret_key_env指定环境变量名程序会自动检测当前系统的钥匙串是否安全。如果检测到是plaintext或fail后端会自动切换到加密文件模式。操作确认所有写入操作都需要显式确认• CLI 模式下lhfw run --apply会先展示 diff然后调用typer.confirm()等待输入• TUI 模式下会弹出 Modal 确认对话框• 只有--yes标志才能跳过确认用于自动化脚本场景错误隔离批量执行时每台服务器独立 try/except。一台服务器的 API 调用失败不会阻塞其他服务器的执行。最终所有结果汇总到一份报告中。命令行速查lhfw doctor # 健康检查环境 凭据可达性 lhfw run # 预览所有 enabled 服务器的 diff lhfw run --apply # 实际写入 lhfw run --tag prod --tag sg # 按 tag 过滤 lhfw run --apply --yes # 跳过确认用于脚本 lhfw config show # 查看配置 lhfw config history # 查看执行历史 lhfw credential list # 列出凭据 lhfw server list # 列出服务器 lhfw server rule-list my-srv # 查看某台服务器的规则从旧脚本迁移如果你之前用的是旧版单文件脚本的tencent_lighthouse_fw.toml配置格式可以一键导入lhfw import-legacy ./tencent_lighthouse_fw.toml会自动迁移 defaults、credentials、servers、managed_rules包括环境变量名。技术栈组件选型CLI 框架TyperTUI 框架Textual终端美化Rich配置格式TOML (tomllib tomli-w)密钥加密cryptography (Fernet)系统钥匙串keyring跨平台路径platformdirs腾讯云 SDKtencentcloud-sdk-python构建系统Hatchling hatch-vcs包管理uv发布PyPI Trusted Publishing (OIDC)Python 3.11所有模型使用dataclass(frozenTrue, slotsTrue)保证不可变性。CI/CD项目使用 GitHub Actions 实现完整的 CI/CD•CI每次 push 和 PR 触发跨平台Ubuntu Windows运行单元测试和冒烟测试•CD推送v*.*.*格式的 git tag 后自动构建并发布到 PyPI版本号由 git tag 动态决定通过hatch-vcspyproject.toml中不硬编码版本。发布使用 PyPI Trusted Publishing通过 GitHub OIDC 令牌认证无需维护 API Token。详细配置指南见仓库的docs/pypi-trusted-publisher.md。写在最后这个工具解决了一个很小但很烦的问题。如果你也在用腾讯云轻量服务器遇到过 IP 变化导致 SSH 断连的困扰可以试试看。仓库地址https://github.com/star-plan/tencent-lighthouse-fw欢迎 issue 和 PR。引用链接[1]lighthouse-fw:https://github.com/star-plan/tencent-lighthouse-fw[2]uv:https://docs.astral.sh/uv/[3]Textual:https://textual.textualize.io/