lighthouse-fw

一个面向 Tencent Cloud Lighthouse 防火墙白名单更新 的 Python 包，支持：

• uvx lighthouse-fw / lhfw 无参数进入交互式 CLI 菜单
• 添加腾讯云账号后自动扫描全部地域的轻量实例，勾选导入
• 从云上防火墙发现 SSH 类规则（22 / 2222 / 备注含 ssh）并勾选托管
• lhfw run 预览 diff，--apply 写入前显式确认
• Windows / Linux / macOS 跨平台配置布局
• 密钥优先系统钥匙串，无法使用时回退到本地加密文件

产品交互说明见 docs/product-design.md。

English summary

lighthouse-fw is a Python package for managing Tencent Cloud Lighthouse SSH firewall allowlists. The default no-arg entry is an interactive CLI: add a Tencent Cloud account, scan every region for Lighthouse instances, import SSH-like firewall rules, then preview and apply the current public IP. Parameterized commands such as lhfw run --apply --yes remain for scripts.

安装与运行

1. 直接用 uvx

无参数进入交互式菜单（没有账号时直接添加账号）：

uvx lighthouse-fw

直接运行 CLI 子命令：

uvx lighthouse-fw doctor
uvx lighthouse-fw run

2. 安装成工具命令

uv tool install lighthouse-fw
lhfw doctor
lhfw run

3. 仓库内本地运行

uv run lhfw doctor
uv run lhfw run

默认行为

• uvx lighthouse-fw / lhfw：无参数进入交互式 CLI。没有账号时走「添加账号」；已有账号时出现菜单（默认第 1 项：更新防火墙白名单）
• 添加账号只需要名称和 SecretId / SecretKey，随后扫描全部地域勾选实例，再勾选云上已有的 SSH 类规则
• 某台机器没有 SSH 类规则时仍然导入，白名单更新对它是空操作，并提示一句
• lhfw run：不带筛选条件时，默认运行所有 enabled 的 server
• lhfw run --apply：会先做 diff 预览，再要求显式确认
• lhfw doctor：检查本地环境、密钥后端，以及账号级 API 可达性

配置模型

当前包的持久化配置由三部分组成：

1. 普通配置：config.toml
2. 密钥：优先系统钥匙串；无安全后端时回退到本地加密文件 secrets.bin
3. 本地口令/密钥文件：secrets.key

server 支持：

• enabled 状态
• 多个自由标签 tags
• 完整 managed_rules

每条 managed_rules 支持：

• protocol
• port
• cidr
• action
• description
• replace_existing_same_port

常用 CLI

对外只有这些命令。精细改动（关某台机器、加非 SSH 端口、改 IP 查询源等）直接编辑 config.toml。

lhfw                         # 交互菜单；没有账号时直接添加
lhfw account add             # 添加腾讯云账号并导入
lhfw sync --account work     # 同步新服务器 / SSH 规则
lhfw sync --account work --all
lhfw run                     # 预览
lhfw run --apply             # 预览后确认写入
lhfw run --apply --yes       # 无人值守写入
lhfw run --tag prod --tag sg
lhfw doctor
lhfw config show
lhfw config history

交互式 CLI

无参数启动后用方向键选择：

• 更新防火墙白名单
• 添加腾讯云账号
• 同步服务器和规则
• 查看当前配置
• 退出

安全说明

• 优先使用系统钥匙串
• 如果当前平台没有安全 keyring backend，会回退到本地加密文件
• SecretId / SecretKey 在交互输入时隐藏
• doctor 默认是只读检查，不会逐台 server 修改任何东西

腾讯云权限要求

本工具通过腾讯云 API 管理轻量应用服务器的防火墙规则，需要为 API 密钥对应的子账号授予以下全部权限，缺一不可。

操作步骤

1. 打开 访问管理 → 策略
2. 新建自定义策略，选择「按策略语法创建」，粘贴下方 JSON
3. 将策略关联到 API 密钥对应的子账号

所需权限列表

预设策略（基础只读，doctor 验证需要）：

自定义策略（防火墙规则管理，run 命令需要）：

{
    "version": "2.0",
    "statement": [
        {
            "effect": "allow",
            "resource": ["*"],
            "action": [
                "lighthouse:DescribeFirewallRules",
                "lighthouse:DescribeFirewallRulesTemplate",
                "lighthouse:DescribePresetFirewallRules",
                "lighthouse:CheckFirewallRules",
                "lighthouse:CheckInstanceFirewallPorts",
                "lighthouse:DescribeFirewallTemplateApplyRecords",
                "lighthouse:DescribeFirewallTemplateQuota",
                "lighthouse:DescribeFirewallTemplateRuleQuota",
                "lighthouse:DescribeFirewallTemplateRules",
                "lighthouse:DescribeFirewallTemplates",
                "lighthouse:ApplyFirewallTemplate",
                "lighthouse:CreateFirewallRules",
                "lighthouse:CreateFirewallTemplate",
                "lighthouse:CreateFirewallTemplateRules",
                "lighthouse:DeleteFirewallRules",
                "lighthouse:DeleteFirewallTemplate",
                "lighthouse:DeleteFirewallTemplateRules",
                "lighthouse:ModifyFirewallRuleDescription",
                "lighthouse:ModifyFirewallRules",
                "lighthouse:ModifyFirewallTemplate",
                "lighthouse:ReplaceFirewallTemplateRule",
                "lighthouse:ResetFirewallTemplateRules"
            ]
        }
    ]
}

权限与命令的对应关系

开发与测试

uv run python -m unittest discover -s tests -v
uv run lhfw doctor

发布

项目按 PyPI 发布路径设计：

• 包名：lighthouse-fw
• 命令名：lhfw
• 版本 tag：v1.2.3
• 认证：GitHub OIDC Trusted Publishing

推送版本 tag 后，GitHub Actions 会自动构建并发布到 PyPI。