# ipam

**Repository Path**: binrui/ipam

## Basic Information

- **Project Name**: ipam
- **Description**: ip地址管理，自动计算空余网段
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-13
- **Last Updated**: 2026-08-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IP 网段管理系统 (IPAM)

基于 **Python + Flask + SQLite** 的本地 Web 工具，用于管理 B 段大网段下的细分网段
（C 段、/30 等任意掩码）。以网段为核心，支持类 Excel 的在线编辑、Excel 导入导出、
空闲网段自动计算，以及「按单位」「按子网顺序」两种查看视角。

> 本文档同时作为**架构与开发参考**，便于后续优化。修改代码时请一并维护本文。

---

## 1. 功能概览

| 模块 | 能力 |
|------|------|
| **网段列表（类 Excel）** | 单元格内联编辑、回车/Tab 导航、自动保存、右键插入/删除行、底部空行新增、列宽拖动记忆、从 Excel 复制整块 Ctrl+V 批量录入、多选批量删除、按单位/关键字筛选 |
| **字段** | CIDR、单位、VLAN、带宽、运营商、描述、创建/更新时间（时间自动维护） |
| **重叠检测** | 编辑/粘贴/导入时自动检测与已有网段重叠，标黄提示（不阻止保存） |
| **按单位看** | 各单位下挂网段聚合列表 + 数量统计（亦可在列表页按单位筛选） |
| **按子网顺序看** | 选大网段→按掩码切分顺序列出子网，按重叠/包含关系判定 已分配/部分占用/空闲；占用块可展开「明细」；空闲网段自动计算并合并相邻块 |
| **Excel 导入/导出** | 列：`网段(CIDR) \| 单位 \| VLAN \| 带宽 \| 运营商 \| 描述`；导入自动建单位、同名网段更新而非重复、错误与重叠回显汇总 |

---

## 2. 技术栈

| 层 | 选型 | 说明 |
|----|------|------|
| 语言 | Python 3.9+ | 仅用标准库 + 两个三方包 |
| Web 框架 | Flask 3.x | 轻量、单进程、`python app.py` 即起 |
| 数据库 | SQLite（`sqlite3` 标准库） | 单文件 `ipam.db`，零运维，复制即备份 |
| 网段计算 | `ipaddress` 标准库 | CIDR 解析、重叠、子网枚举、空闲计算 |
| Excel | openpyxl | xlsx 读写 |
| 前端 | 原生 HTML + CSS + Vanilla JS | **无构建、无框架、无 CDN，完全离线** |
| 模板 | Jinja2（Flask 内置） | 服务端渲染页面 |

依赖见 [requirements.txt](requirements.txt)：`flask`、`openpyxl`。

---

## 3. 架构

### 3.1 总体形态

单体应用，**服务端渲染页面 + 局部 JSON API** 的混合模式：

```
浏览器
  │
  ├─ 普通页面 (GET)  ──► Flask 路由 ──► Jinja 模板渲染 HTML ──► 返回整页
  │     · /            网段列表（壳） + 引导数据(JSON)
  │     · /by-unit     按单位视图
  │     · /by-subnet   子网顺序 + 空闲计算
  │     · /units       单位 / 大网段管理
  │
  └─ 表格交互 (fetch/JSON) ──► /api/* ──► db 层 ──► 返回 JSON
        · 内联编辑、批量粘贴、删除等不刷新整页，由 grid.js 局部更新 DOM
```

### 3.2 分层

```
表现层   templates/*.html  +  static/grid.js  +  static/style.css
   │            （Jinja 渲染骨架 / 引导数据；grid.js 接管表格交互）
路由层   app.py            （HTTP 路由、请求解析、JSON 序列化、流程编排）
领域层   ipam.py           （纯函数：CIDR 解析/重叠/枚举/空闲/状态判定，无状态、无 IO）
数据层   db.py             （SQLite 连接、建表、迁移、CRUD 封装）
持久化   ipam.db           （SQLite 文件）
```

**依赖方向**：`app.py → {ipam.py, db.py, excel.py}`；`db.py → ipam.py`（归一化用）；`excel.py → {db.py, ipam.py}`。`ipam.py` 不依赖任何项目内模块，可独立测试。

### 3.3 表格（grid.js）数据流

1. 服务端把当前网段列表序列化为 JSON，注入 `<script id="bootstrap">`。
2. grid.js 读取并渲染表格，末尾补一行空行。
3. 编辑单元格 → 失焦/回车 → `POST /api/subnet`（upsert）→ 返回归一化后的记录 + 重叠列表 → 局部更新该行、染色、必要时补空行。
4. 从 Excel 粘贴整块 → `POST /api/bulk` → 返回全量列表 → 整体重渲染 + 汇总提示。
5. 删除/批量删除 → `/api/subnet/<id>/delete`、`/api/bulk-delete` → 移除对应行。

---

## 4. 目录结构

```
a05/
├── app.py                 # Flask 入口：路由、视图、JSON API、流程编排
├── db.py                  # SQLite 建表/迁移/CRUD 封装
├── ipam.py                # CIDR 领域逻辑（纯函数，基于 ipaddress）
├── excel.py               # Excel 导入/导出（openpyxl）
├── requirements.txt       # 依赖：flask, openpyxl
├── README.md              # 本文档
├── ipam.db                # 运行时自动生成的 SQLite 库（勿提交版本库）
├── templates/
│   ├── base.html          # 布局骨架 + 导航 + flash 消息
│   ├── subnets.html       # 网段列表（类 Excel 表格壳 + 引导数据）
│   ├── by_unit.html       # 按单位聚合视图
│   ├── by_subnet.html     # 子网顺序 + 空闲网段 + 占用明细（含本页内联 JS）
│   └── units.html         # 单位 / 大网段管理
└── static/
    ├── grid.js            # 类 Excel 可编辑表格的全部前端逻辑（原生 JS）
    └── style.css          # 全站样式
```

---

## 5. 数据模型（SQLite）

```
unit                         supernet                    subnet（核心）
──────────                   ──────────                  ─────────────────────────
id     PK                    id     PK                   id          PK
name   TEXT UNIQUE           cidr   TEXT  （如 10/16）    cidr        TEXT  归一化后
                             name   TEXT  备注名          network     INT   网络地址整数（排序用）
                                                          prefix      INT   掩码位数
                                                          unit_id     FK→unit (可空=未分配)
                                                          description TEXT
                                                          vlan        INT
                                                          bandwidth   TEXT  带宽（如 100M）
                                                          isp         TEXT  运营商
                                                          created_at  TEXT
                                                          updated_at  TEXT
索引：subnet(network)、subnet(unit_id)
关系：unit 1—N subnet（删除单位时其网段 unit_id 置空，ON DELETE SET NULL）
```

- **设计要点**：以 `subnet` 为核心；`network`/`prefix` 由 CIDR 解析后冗余存储，便于按地址排序与重叠判断，避免每次查询都解析字符串。
- **大网段 `supernet`** 仅服务于「按子网顺序看」的范围选择，与 `subnet` 无外键约束（通过 IP 包含关系动态关联）。
- **迁移**：`db.init_db()` 用 `PRAGMA table_info` 检测缺失列并 `ALTER TABLE` 补齐（`bandwidth`/`isp` 即由此为旧库平滑升级）。新增字段一律走此模式，不要求重建库。

---

## 6. 路由 / API 一览

| 方法 & 路径 | 类型 | 用途 |
|------------|------|------|
| `GET /` | 页面 | 网段列表（支持 `?unit=&q=&new=` 筛选/预填） |
| `POST /api/subnet` | JSON | 单网段 upsert，返回 `{ok, subnet, overlaps}` |
| `POST /api/subnet/<id>/delete` | JSON | 删除单网段 |
| `POST /api/bulk-delete` | JSON | 批量删除 `{ids:[...]}` |
| `POST /api/bulk` | JSON | 批量保存（粘贴），返回 `{ok, summary, subnets}` |
| `GET /by-unit` | 页面 | 按单位聚合 |
| `GET /by-subnet` | 页面 | 子网顺序 + 空闲计算（`?supernet=&prefix=`） |
| `GET/POST /units` | 页面 | 单位 / 大网段增删 |
| `GET /export` | 文件 | 导出 xlsx |
| `POST /import` | 表单 | 导入 xlsx |

**领域函数（ipam.py）**：`normalize`、`overlaps`、`find_overlaps`、`enumerate_subnets`、`subnet_count`、`contains`、`free_blocks`（空闲块计算+合并）、`block_status`（已分配/部分占用/空闲判定）。

---

## 7. 运行与部署

```bash
pip install -r requirements.txt
python app.py
```

- 访问 http://127.0.0.1:5000 （默认监听 `0.0.0.0:5000`，局域网可访问）。
- 数据存于同目录 `ipam.db`，首次运行自动建库；备份 = 复制该文件。
- 生产部署可换 WSGI（如 `waitress-serve --port=5000 app:app`），并关闭 `debug`。

**使用顺序建议**：① 在「单位 / 大网段」添加单位与大网段（如 `10.1.0.0/16`）→ ② 在网段列表录入/导入细分网段 → ③ 用两个视图查看分配与空闲。

---

## 8. 开发规范

**Python**
- 命名 `snake_case`；模块职责单一，按第 3.2 节分层，**不要在 `ipam.py` 引入 IO 或 Flask 依赖**（保持可单测）。
- 数据库统一经 `db.py`，不在路由里写裸 SQL；连接用 `db.get_conn()`（已设 `row_factory` 与外键）。
- 网段一律先经 `ipam.normalize()` 归一化再入库；排序/比较用整数 `network` 字段。
- 新增字段：改 `CREATE TABLE` + 在 `init_db()` 加 `ALTER TABLE` 迁移 + 串联 `save_subnet`/`_subnet_dict`/excel 列/前端列。
- 注释与 docstring 用中文，解释「为什么」而非复述代码。

**API**
- JSON 响应统一含 `ok` 字段；成功带数据，失败带 `error` 与恰当 HTTP 状态码。
- 校验在服务端完成（CIDR 合法性、VLAN 数值化经 `_parse_vlan`）；重叠为**提示**不为**拦截**。

**前端**
- 保持**零依赖、离线可用**：不引入框架/CDN/构建步骤。
- 表格逻辑集中在 `static/grid.js`（IIFE，事件委托）；页面级小交互可写在对应模板内联 `<script>`。
- 样式集中在 `static/style.css`，复用既有类（`.card`/`.tag`/`.flash` 等），状态色：分配=绿、部分=黄、空闲=灰、错误=红。

**数据安全**
- `ipam.db` 不纳入版本库（如启用 git，请加 `.gitignore`）。
- 破坏性操作（删除/覆盖导入）前确认；导入为「同名更新 + 新增」，不会清空既有数据。

---

## 9. 演进阶段

### 阶段一 — MVP（已完成）
SQLite 数据模型；网段 CRUD；单位 / 大网段管理；「按单位」「按子网顺序」两视图；Excel 导入导出；基于 `ipaddress` 的重叠检测与子网枚举。

### 阶段二 — 类 Excel 编辑体验（已完成）
列表页升级为可编辑表格：单元格内联编辑、回车/Tab 导航、失焦自动保存（`/api/subnet`）、底部空行新增、从 Excel 复制整块 Ctrl+V 批量录入（`/api/bulk`）、多选批量删除——全部原生 JS、离线可用。

### 阶段三 — 字段扩展与视图增强（已完成）
- 新增**带宽 / 运营商**字段（含旧库自动迁移）；
- 表格**列宽拖动**并记忆、**右键插入/删除行**；
- 「按子网顺序看」改用**重叠/包含关系**判定（已分配/部分占用/空闲），不再要求 CIDR 精确相等；
- **占用明细**可展开；切分掩码下拉仅显示合法值并自动刷新；
- **空闲网段自动计算**（扣除已登记网段，合并相邻空闲块，一键去登记）。

### 后续优化方向（待办 / Roadmap）
- [ ] **测试**：补 `tests/`，覆盖 `ipam.py` 纯函数与 API（pytest + Flask test client，目前为手工脚本验证）。
- [ ] **登录与权限**：多人使用场景下的认证、只读/可写角色。
- [ ] **操作审计**：变更日志（谁、何时、改了什么）。
- [ ] **校验增强**：可选「子网必须落在某大网段内」约束；导入预检（dry-run 预览）。
- [ ] **IP 级管理**：在网段下进一步管理单个 IP/主机（当前粒度为网段）。
- [ ] **自定义持久排序**：列表当前按 IP 排序，插入行仅为录入便利；如需手动排序需引入排序字段。
- [ ] **统计可视化**：各大网段使用率图表、单位占用排行。
- [ ] **性能与分页**：数据量很大时的分页/虚拟滚动、查询索引优化。
- [ ] **配置化**：端口、监听地址、库路径等抽到配置/环境变量。

---

## 10. 已知约束
- 单进程 SQLite，适合**单位内小规模、低并发**内网使用；高并发或多写需换数据库。
- 重叠检测为提示性，不阻止录入（允许临时并存，便于迁移期对账）。
- 列表排序固定为 IP 升序，手动插入顺序刷新后不保留（见 Roadmap）。

---

## 11. 桌面打包（Tauri，双击即运行）

把本工具用 **Tauri 2** 包装成桌面应用：Tauri 作 GUI 外壳，PyInstaller 打包的 Flask 作为
sidecar 子进程。启动时外壳拉起 sidecar（回环 + 随机端口），握手后用系统 WebView 加载
`http://127.0.0.1:<port>`，关闭窗口时回收子进程。最终产物为双击即可运行的可执行文件，
**目标机无需安装 Python**。支持 Windows 与 Linux（需分别在对应平台构建，Tauri/PyInstaller
均不支持交叉编译）。

### 11.1 新增文件结构
```
c01/
├── sidecar_main.py        # sidecar 入口：随机端口、写端口文件、loopback、关 reloader
├── ipam_sidecar.spec      # PyInstaller 配置（含 templates/static）
├── build_sidecar.py       # 一键构建 sidecar 并放到 src-tauri/binaries（带目标三元组后缀）
├── make_icon.py           # 生成占位图标 icon.png（仅标准库）
├── package.json           # tauri-cli 脚本入口
├── ui/index.html          # 启动加载页（Tauri frontendDist）
└── src-tauri/
    ├── Cargo.toml         # Rust 依赖：tauri 2 + tauri-plugin-shell
    ├── build.rs
    ├── tauri.conf.json    # 外壳配置：productName、externalBin、bundle targets
    ├── capabilities/default.json
    ├── src/main.rs        # 外壳主程序：sidecar 编排 + 窗口管理
    └── binaries/          # 构建时放入 ipam-sidecar-<triple>[.exe]（已 gitignore）
```

### 11.2 一次性环境准备
1. **Rust 工具链**（编译 Tauri 外壳必需）：安装 `rustup`，Windows 用 MSVC 工具链。
   - Windows 还需 *WebView2 Runtime*（Win11 自带）与 *NSIS*（`cargo tauri build` 首次会提示安装）。
   - Linux 需装 webkit2gtk 等系统依赖，见 https://tauri.app/start/prerequisites/ 。
2. Node.js（已需）用于 `@tauri-apps/cli`。
3. Python 依赖：`pip install -r requirements.txt pyinstaller`。

### 11.3 构建步骤
```bash
# 0) 安装 tauri-cli（项目本地依赖）
npm install

# 1) 生成图标集（首次或更换图标时）
python make_icon.py
npx @tauri-apps/cli icon icon.png     # 产物写入 src-tauri/icons/

# 2) 构建 sidecar 并就位到 src-tauri/binaries/
python build_sidecar.py

# 3) 构建安装包 / 可执行文件
npm run tauri build
```
产物：
- Windows：`src-tauri/target/release/IPAM.exe`（双击即运行）及 `target/release/bundle/{nsis,msi}/` 安装包。
- Linux：`src-tauri/target/release/ipam` 及 `bundle/{deb,appimage}/`。

> 调试外壳：`npm run tauri dev`（需先完成步骤 1、2）。
> 日常开发后端逻辑仍用 `python app.py` 即可，无需走 Tauri。

### 11.4 运行期行为说明
- 数据库 `ipam.db` 在打包态存到用户数据目录：Windows `%APPDATA%\ipam\`、
  Linux `~/.local/share/ipam/`（开发态仍为脚本同目录）。可用环境变量 `IPAM_DB_PATH` 覆盖。
- sidecar 日志写入上述目录的 `sidecar.log`，排查启动失败时查看。
- 监听 `127.0.0.1` 回环、随机端口，不暴露到局域网。
- 关闭窗口自动结束 sidecar 子进程，不会残留后台。