# firenet

**Repository Path**: wurong/firenet

## Basic Information

- **Project Name**: firenet
- **Description**: 一个用于 K8S 的端口映射工具，支持多 K8S 集群，支持多端口映射
- **Primary Language**: Dart
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-30
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Firenet - K8S 端口转发 & SSH 隧道管理器（macOS 托盘应用）

[English README](README.en.md)

Firenet 是一款基于 Flutter 的 macOS **菜单栏/托盘**应用，将日常开发中反复执行的「进网 → 跳板 → 访问 K8s 服务」链路集中管理：

- Kubernetes **Port Forward**（`kubectl port-forward`）
- SSH **本地端口转发**（应用内称为 **SSH Stunnel**）
- **OpenConnect VPN**（企业 SSL VPN，依赖系统 `openconnect` 与 `sudo`）

应用默认以托盘形态运行（`LSUIElement=true`，不出现在 Dock），通过菜单栏图标打开弹窗或主窗口。

当前版本：**1.0.7**（见 `pubspec.yaml`）。更完整的产品与架构说明见 [docs/产品设计文档.md](docs/产品设计文档.md)。

## 功能特性

### Workspace（工作区）

- 支持多 Workspace，每个 Workspace 维护独立的 `kubeconfig` 与可选 SSH 私钥默认路径
- 切换 Workspace 时同步 OpenConnect 服务器选择

### Port Forwards（K8S 端口转发）

- 新建/编辑/删除转发规则（Namespace → Service → 端口）
- 单条启停、Master Switch 全开/全停
- 进程托管、健康检查与连接丢失系统通知

### SSH Stunnel（SSH 隧道）

- 经跳板机的 `-L local:remoteHost:remotePort` 本地转发
- 单条启停、测试跳板连通
- 基于本机端口监听的运行态检测

### OpenConnect VPN

- 按 Workspace 管理 VPN 服务器配置
- 连接/断开、日志查看、强制清理残留进程
- 通过 `sudo` + `openconnect` 建立 VPN（需 macOS 管理员密码）
- 可在 **设置 → VPN 管理员密码** 中将管理员密码保存到钥匙串，避免每次连接重复输入

### 托盘与快捷操作

- 托盘标题显示当前活跃连接数
- **托盘弹窗**：Port Forward / SSH Stunnel 多选批量启停、OpenConnect 快捷连接
- **主窗口**：完整 CRUD 与 Settings

### 设置

- 配置或一键安装/检测 `kubectl`、`ssh`、`openconnect` 路径
- 界面语言：跟随系统 / 中文 / English
- **软件更新**：基于 **Sparkle** 自动检查、下载并安装；可配置 appcast URL 与启动时是否检查

### 启动与可靠性

- 启动时扫描本机监听端口，校正 `isActive` 状态；扫描完成前全屏 Loading 遮罩
- 连接意外断开时系统通知（点击可激活主窗口）
- 缺失必需工具时启动后提示安装指引

## 环境要求

| 组件 | 用途 | 必需 |
|------|------|------|
| macOS | 运行平台 | 是 |
| `kubectl` | Port Forward | 是 |
| `ssh` | SSH Stunnel | 使用隧道时需要 |
| `openconnect` + `sudo` | OpenConnect VPN | 使用 VPN 时需要 |
| Flutter | 仅开发/编译 | 否 |

## kubectl 行为说明

应用按以下优先级寻找/安装 `kubectl`：

1. `~/.firenet/bin/kubectl`（Firenet 安装或复制到此）
2. 系统 `PATH` 中的 `kubectl`
3. Flutter assets：`assets/bin/<arch>/kubectl`（复制到 `~/.firenet/bin/kubectl`）

源码运行且系统无 `kubectl` 时，需自备 assets 二进制：

```text
assets/
└── bin/
    ├── intel/kubectl      (darwin/amd64)
    └── m/kubectl          (darwin/arm64)
```

Apple Silicon 下载示例：

```bash
mkdir -p assets/bin/m
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"
mv kubectl assets/bin/m/ && chmod +x assets/bin/m/kubectl
```

Intel 将路径中的 `arm64` 改为 `amd64`，目录改为 `assets/bin/intel`。

## 开发运行与构建

```bash
flutter pub get
flutter run -d macos          # Debug
flutter build macos           # Release
```

Release 产物：`build/macos/Build/Products/Release/firenet.app`

## 基本使用

1. **添加 Workspace**：名称、`kubeconfig`、可选 SSH 私钥路径  
2. **（可选）连接 OpenConnect VPN**：在 OpenConnect Tab 配置服务器并连接  
3. **（可选）启动 SSH Stunnel**：经跳板访问内网 API 等  
4. **创建 Port Forward**：选择 Namespace/Service/端口并启停  
5. 点击托盘图标：弹窗中快速批量启停或切换 Workspace  

## 软件更新（Sparkle）

客户端使用 [Sparkle 2](https://sparkle-project.org/)（经 `auto_updater` 插件）。默认 appcast：

```text
https://raw.giteeusercontent.com/wurong/firenet/raw/master/appcast.xml
```

可在 **设置 → 软件更新** 覆盖 Appcast URL。关闭「启动时自动检查」后，Sparkle 不会后台轮询（仍可手动检查）。

发现新版本后，Sparkle 会弹出系统更新窗口：**下载 zip → 解压 → 替换当前 `firenet.app` → 重新启动**，无需用户手动拷贝。请使用 **Release 安装包**（放在 `/Applications` 或当前 `.app` 所在目录可写），`flutter run` 调试版不支持自动替换。

前提：`appcast.xml` 含有效 `edSignature`，且客户端 `Info.plist` 已配置匹配的 **SUPublicEDKey**（`sparkle_release.sh` 会尝试自动写入）。

### 首次发版前（一次性）

```bash
dart run auto_updater:generate_keys
```

私钥保存在本机钥匙串。之后每次 `./scripts/sparkle_release.sh` 会尝试把 **SUPublicEDKey** 同步到 `macos/Runner/Info.plist` 再构建；若未生成过密钥，需先运行上述命令。

### 每次发版

1. **只改** `pubspec.yaml` 版本号（如 `1.4.2+4`：`1.4.2` 为显示版本，`+4` 为 Sparkle 构建号，必须递增）
2. 配置 Gitee 令牌（一次性）：

```bash
mkdir -p ~/.config/firenet
echo '你的私人令牌' > ~/.config/firenet/gitee_token
chmod 600 ~/.config/firenet/gitee_token
# 或: export GITEE_TOKEN=你的私人令牌
```

令牌需有 `projects` 权限（创建 Release、上传附件）。在 Gitee → 设置 → 私人令牌 创建。

3. **一键发版**：

```bash
./scripts/sparkle_release.sh "修复 xxx；新增 yyy"
```

脚本会自动完成：

| 步骤 | 说明 |
|------|------|
| 构建 | `flutter build macos --release` |
| 打包签名 | `dist/sparkle/firenet-<version>-macos.zip` + Sparkle `edSignature` |
| Appcast | 更新 [`appcast.xml`](appcast.xml)（同版本旧条目会先删除再插入） |
| Git | `commit` → `push master` → 打 tag `v<version>` → 推送 tag |
| Gitee | 创建/更新 Release 并上传 zip |

可选参数 / 环境变量：

| 选项 / 变量 | 说明 |
|------------|------|
| `--dry-run` | 预览操作，不写入文件 |
| `--skip-build` | 跳过构建，使用已有产物 |
| `--skip-push` | 不 git push |
| `--skip-gitee` | 不上传 Gitee Release |
| `GITEE_REPO` | 默认 `wurong/firenet` |
| `GITEE_BRANCH` | 默认 `master` |
| `RELEASE_DOWNLOAD_URL` | 覆盖 appcast 下载地址 |

调试本地流程（不上传远端）：

```bash
./scripts/sparkle_release.sh --skip-push --skip-gitee "本地测试"
```

## 数据与日志

| 路径 | 说明 |
|------|------|
| `~/.firenet/data/clusters.json` | Workspaces |
| `~/.firenet/data/forwards.json` | Port Forward 规则 |
| `~/.firenet/data/stunnels.json` | SSH Stunnel |
| `~/.firenet/data/openconnect_servers.json` | OpenConnect 配置（含 VPN 密码，明文 JSON） |
| `~/.firenet/data/settings.json` | 应用设置 |
| `~/.firenet/bin/kubectl` | 可选内置 kubectl |
| `~/.firenet/logs/crash.log` | 错误日志 |

敏感信息（VPN 密码、可选的管理员密码）存于 JSON 或 macOS 钥匙串，依赖用户目录权限保护。

## 常见问题

- **kubectl 不可用**  
  在 **设置** 中安装/指定路径，或确保 `PATH` 中有 `kubectl` / 提供 assets 二进制。

- **端口被占用**  
  修改本地端口或停止占用进程。

- **OpenConnect 反复要求管理员密码**  
  在 **设置 → VPN 管理员密码** 开启「保存到钥匙串」，成功连接一次后即可自动填充。

- **检查更新 HTTP 403 / 无法更新**  
  确认 appcast.xml 与 zip 下载地址对客户端可访问；私有仓库请将 appcast 放到公网 CDN 并在设置中填写 URL。Release 构建需在 Info.plist 配置有效的 **SUPublicEDKey**。

- **VPN 认证失败**  
  编辑 OpenConnect 服务器，确认用户名/密码正确；必要时开启「允许不安全证书」。

## 许可证

本项目采用 Apache-2.0 许可证，详见 [LICENSE](LICENSE)。