# 构建与编译

## 1. 目标

统一记录 QuickIP 当前可直接使用的编译命令、默认输出位置，以及一键编译方式。

## 2. Windows 客户端编译

在仓库根目录执行：

```powershell
dotnet build ".\windows\QuickIP.Client.sln" -c Debug
```

默认输出目录：

```text
windows\QuickIP.Client\bin\Debug\net9.0-windows\
```

说明：

1. 保持使用默认 `Debug` 输出目录
2. 如果 `QuickIP.Client.exe` 正在运行，重新编译可能因文件被占用而失败

## 3. Agent 编译

当前只需要编译 Linux amd64 版 Agent，用于上传到 Ubuntu 24 设备。

本节默认前提：当前 PowerShell 已位于 `D:\git\QuickIP\agent`。

### 3.1 编译 Linux amd64 版 Agent

在 `agent\` 目录执行：

```powershell
$env:GOOS="linux"
$env:GOARCH="amd64"
$env:CGO_ENABLED="0"
go build -o ".\quickip-agent-linux-amd64" ".\cmd\quickip-agent"
```

输出文件：

```text
agent\quickip-agent-linux-amd64
```

说明：

1. 该产物用于上传到 Ubuntu 24 设备
2. 编译完成后，如有需要可把 `GOOS`、`GOARCH` 恢复到原值
3. `go.mod` 位于 `agent\` 目录下，因此应先进入 `agent` 目录再执行 `go build`
4. 在 Windows 上交叉编译 Linux 版时，需要设置 `CGO_ENABLED=0`

## 4. 一键编译

仓库根目录已提供 `build.ps1`。

执行命令：

```powershell
powershell -ExecutionPolicy Bypass -File .\build.ps1
```

该脚本会依次完成：

1. 编译 Windows 客户端到默认 `Debug` 目录
2. 编译 Linux amd64 版 Agent 到 `agent\quickip-agent-linux-amd64`

## 5. 上传与启动

以下示例基于当前联调环境：

1. 远端主机：`x@192.168.229.136`
2. 远端目标路径：`/home/x/quickip-agent`
3. 本节默认前提：当前 PowerShell 已位于 `D:\git\QuickIP\agent`

### 5.1 上传 Linux 版 Agent

如果当前已经在 `agent\` 目录执行：

```powershell
scp .\quickip-agent-linux-amd64 x@192.168.229.136:/home/x/quickip-agent
```

说明：

1. 该命令会把本地 Linux 版产物上传到远端并命名为 `quickip-agent`
2. 如果远端当前已有同名进程在运行，建议先停止旧进程再覆盖上传

### 5.2 登录远端主机

```powershell
ssh x@192.168.229.136
```

说明：

1. 当前远端 `sudo` 需要交互输入密码
2. 因此不建议用无交互 `ssh "sudo ..."` 方式直接停进程或启动服务
3. 更稳妥的方式是先登录远端，再手工执行 `sudo` 命令

### 5.3 停止旧进程

登录远端后执行：

```bash
sudo pkill -f quickip-agent
```

### 5.4 设置执行权限

登录远端后执行：

```bash
chmod +x /home/x/quickip-agent
```

说明：

1. 上传完成后，建议显式补一次执行权限
2. 不要依赖 `scp` 后远端权限一定正确

### 5.5 以 root 身份启动 Agent

登录远端后执行：

```bash
sudo nohup /home/x/quickip-agent --ip 169.254.100.2 --port 48888 --password 'Dt123$' >/home/x/quickip-agent-run.log 2>&1 < /dev/null &
```

说明：

1. 当前必须以 `root` 身份运行，才能写入 `netplan`、执行 `netplan apply`、重启和关机
2. 如果不用 `sudo` 启动，配置应用和系统动作会被 Agent 直接拒绝

### 5.6 检查监听状态

登录远端后执行：

```bash
ss -ltnp | grep 48888
```

期望看到类似：

```text
LISTEN ... 169.254.100.2:48888 ... quickip-agent
```

### 5.7 查看运行日志

登录远端后执行：

```bash
tail -n 50 /home/x/quickip-agent-run.log
```

### 5.8 推荐顺序

本机 PowerShell：

```powershell
scp .\quickip-agent-linux-amd64 x@192.168.229.136:/home/x/quickip-agent
ssh x@192.168.229.136
```

远端登录后：

```bash
sudo pkill -f quickip-agent
chmod +x /home/x/quickip-agent
sudo nohup /home/x/quickip-agent --ip 169.254.100.2 --port 48888 --password 'Dt123$' >/home/x/quickip-agent-run.log 2>&1 < /dev/null &
ss -ltnp | grep 48888
```

## 6. 常见问题

### 6.1 `go build ./...` 没报错，但找不到可执行文件

这是正常现象。

`go build ./...` 更适合做整模块编译检查，不保证在你期望的位置生成最终可执行文件。

如果需要明确拿到 agent 产物，应使用带 `-o` 的命令，例如：

```powershell
$env:GOOS="linux"
$env:GOARCH="amd64"
$env:CGO_ENABLED="0"
go build -o ".\quickip-agent-linux-amd64" ".\cmd\quickip-agent"
```

### 6.2 Windows 客户端编译失败，提示 `QuickIP.Client.exe` 被占用

通常表示客户端程序仍在运行。

处理方式：

1. 先关闭正在运行的 `QuickIP.Client.exe`
2. 再重新执行 `dotnet build`