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 --apply

run命令会先做一次 dry-run，展示 diff 预览（红色删除、绿色新增），然后询问确认。只有你输入y才会真正调用 API 写入。

TUI：终端里的图形界面

如果你不喜欢敲命令，直接运行lhfw或lighthouse-fw（不带参数）就会进入 TUI：

uvx lighthouse-fw

TUI 基于 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机制：用户在配置中写cidr="AUTO"，运行时会自动替换为当前公网 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( protocol=managed_rule.protocol, port=managed_rule.port, cidr=cidr, action=managed_rule.action, description=managed_rule.description, )

另一个细节是腾讯云的乐观锁机制。每次修改防火墙规则时需要传入一个FirewallVersion版本号。lighthouse-fw 在删除规则后会重新查询最新的版本号，再执行创建操作，避免版本冲突。

安全设计

密钥存储

lighthouse-fw 不会把 API 密钥写在配置文件里。它有三级存储策略：

1.系统钥匙串（优先）：Windows Credential Manager、macOS Keychain、Linux Secret Service/KWallet
2.加密文件（回退）：使用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 框架	Typer
TUI 框架	Textual
终端美化	Rich
配置格式	TOML (tomllib + tomli-w)
密钥加密	cryptography (Fernet)
系统钥匙串	keyring
跨平台路径	platformdirs
腾讯云 SDK	tencentcloud-sdk-python
构建系统	Hatchling + hatch-vcs
包管理	uv
发布	PyPI Trusted Publishing (OIDC)

Python >= 3.11，所有模型使用@dataclass(frozen=True, slots=True)保证不可变性。

CI/CD

项目使用 GitHub Actions 实现完整的 CI/CD：

•CI：每次 push 和 PR 触发，跨平台（Ubuntu + Windows）运行单元测试和冒烟测试
•CD：推送v*.*.*格式的 git tag 后自动构建并发布到 PyPI

版本号由 git tag 动态决定（通过hatch-vcs），pyproject.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/