# ip-management

**Repository Path**: boo0ood/ip-management

## Basic Information

- **Project Name**: ip-management
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-31
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IP Management

IP Management 是一个 Rust 优先的内网 IP 资产管理系统。当前仓库包含：

- Linux：`systemd` 开机自启动
- macOS：`launchd` 开机自启动
- Windows：计划任务开机自启动
- Rust 服务端：登录、修改密码、Agent Token、上报入库、设备查询
- Web 前端：登录、设备列表、接口/IP 可视化、历史上报、改密码

## 服务端本地启动

启动 PostgreSQL、服务端和前端容器：

```bash
docker compose up -d postgres server web
```

复制环境变量并按需修改：

```bash
cp config/server.example.env .env.local
set -a
. ./.env.local
set +a
cargo run --package ipm-server
```

首次启动会自动执行数据库迁移。如果设置了 `IPM_BOOTSTRAP_ADMIN_USERNAME` 和
`IPM_BOOTSTRAP_ADMIN_PASSWORD`，服务端会在用户不存在时创建初始管理员；创建成功后建议删除
这两个环境变量。

## Bark 上下线推送

服务端支持通过 Bark 推送设备上下线通知。把 Bark 地址配置到服务端环境变量即可，地址只填写到
设备 Key，服务端会自动追加“推送标题/推送内容”，并在内容里带上本次上报使用的 IP：

```bash
IPM_BARK_ENDPOINT="https://bark.example.com/REPLACE_WITH_BARK_KEY"
```

上下线只在状态变化时推送一次：设备首次上报或离线后再次上报会推送上线；设备超过
`IPM_DEVICE_OFFLINE_AFTER_SECONDS` 未上报会推送离线。默认离线阈值为 300 秒，后台扫描间隔为
30 秒。推送失败会进入数据库通知队列按退避时间重试，不会阻塞 Agent 上报。

## 服务端 API

后台登录：

```bash
curl -i -X POST http://127.0.0.1:8080/api/auth/login \
  -H 'content-type: application/json' \
  -d '{"username":"admin","password":"change-me-with-12-chars"}'
```

创建 Agent Token 需要带登录 Cookie：

```bash
curl -X POST http://127.0.0.1:8080/api/agent-tokens \
  -H 'content-type: application/json' \
  -b 'ipm_session=<session>' \
  -d '{"name":"office-pc-001"}'
```

Agent 上报接口：

```text
POST /api/agent/reports
Authorization: Bearer <agent_token>
```

设备查询接口：

```text
GET /api/devices
GET /api/devices/{device_id}
GET /api/devices/{device_id}/reports
```

## Web 前端本地启动

前端位于 `web/`。开发模式会把 `/api` 代理到 `http://127.0.0.1:8080`，所以需要先启动
PostgreSQL 和 `ipm-server`。

```bash
cd web
npm install
npm run dev
```

浏览器打开：

```text
http://127.0.0.1:5173
```

如果使用 Docker Compose 的 `web` 服务，同样打开：

```text
http://127.0.0.1:5173
```

## Agent 配置

配置模板位于 `client/config/agent.example.toml`。安装脚本会复制到平台默认路径并生成稳定 `device_id`。

| 平台 | 默认配置路径 |
| --- | --- |
| Linux | `/etc/ipm-agent/agent.toml` |
| macOS | `/Library/Application Support/IP Management/agent.toml` |
| Windows | `C:\ProgramData\IP Management\agent.toml` |

生产环境必须填写真实 `server_url` 和 `device_token`。`device_token` 只允许 Agent 上报，不应拥有后台登录或管理权限。

## 本地构建

```bash
cargo build --release --workspace
```

## 服务端一键部署

脚本会先在本机编译 Linux 服务端二进制并构建前端静态资源，再通过 SSH 上传发布包；发布包只包含
`ipm-server`、`web/dist` 静态文件、`BUILD_INFO` 和首次部署需要的 `server.env`，不会上传
Rust/TypeScript 源码。

```bash
scripts/deploy-server.sh
```

运行后按提示输入服务器 IP、SSH 用户、密码（已配置免密登录可直接回车）、部署路径、访问域名和
Let's Encrypt 通知邮箱。远端需要 Linux + systemd；本机如果不是同架构 Linux，需要安装 Docker
来构建远端 Linux 二进制。访问域名必须已解析到服务器，并且公网 80/443 端口可达。脚本会确保远端
存在可用 Nginx；如果缺少 Nginx，会尝试通过系统包管理器安装并启用，然后写入
`/etc/nginx/conf.d/ipm-web.conf`，先用 HTTP 完成 ACME 验证，再切换为 HTTPS 站点并把 80 端口跳转
到 443。首次部署会从本地 `.env.local` 生成远端
`<部署路径>/shared/server.env`；后续部署不会覆盖该文件，避免误改生产数据库连接串或密钥。

## Linux 安装

```bash
sudo client/scripts/linux/install.sh
sudo editor /etc/ipm-agent/agent.toml
sudo systemctl restart ipm-agent
sudo systemctl status ipm-agent
```

## macOS 安装

```bash
sudo client/scripts/macos/install.sh
sudo nano "/Library/Application Support/IP Management/agent.toml"
sudo launchctl kickstart -k system/com.ip-management.agent
```

## Windows 安装

以管理员身份打开 PowerShell：

```powershell
powershell -ExecutionPolicy Bypass -File .\client\scripts\windows\install.ps1
notepad "$env:ProgramData\IP Management\agent.toml"
Start-ScheduledTask -TaskName "IP Management Agent"
```

## 服务端上报接口约定

Agent 会向 `server_url` 发送 `POST application/json` 请求，并附带：

```text
Authorization: Bearer <device_token>
```

服务端会校验 Token、记录接收审计日志，并且不会单独信任 payload 中的 `device_id`。首次使用
未绑定设备的 Agent Token 时，服务端会绑定该 Token 到本次上报的设备 ID；之后同一个 Token
不能用于其他设备。