背景：一个反复折磨我的问题

我有几台腾讯云轻量应用服务器（Lighthouse），防火墙规则里白名单写的是当前的公网出口 IP。问题是，家里的宽带每次重新拨号，IP 就会变，从办公室访问服务器，也是不同的IP。一旦 IP 变了，SSH 连不上，只能去腾讯云控制台手动改防火墙规则。

一台服务器还好，多几台就烦了——每台都要登录控制台，找到防火墙，删旧规则，加新规则，填 IP，选协议端口……重复操作既枯燥又容易出错。

我最初写了一个 Python 单文件脚本来自动化这件事。后来功能越加越多，脚本从 200 行涨到 483 行，开始难以维护。于是我把它重构成了一个完整的 Python 包，并开源了出来。

这就是 lighthouse-fw。

它能做什么

核心功能一句话：自动获取你的公网 IP，然后批量更新多台 Lighthouse 服务器的防火墙白名单规则。

具体来说：

  • IP 自动探测：从多个源获取当前公网 IPv4，单源故障自动切换
  • 增量更新：只修改需要变更的规则，不动其他规则，减少误删风险
  • 多服务器批量操作：一次命令更新所有服务器，单台失败不影响其他
  • TUI + CLI 双模式：终端图形界面和命令行都能用
  • 密钥安全存储：优先使用系统钥匙串，回退到本地加密文件
  • Dry-run 预览：执行前先看 diff，确认后再写入

快速开始

安装

不需要 clone 仓库，不需要 pip install。用 uv 直接跑：

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 构建，有四个标签页：

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。