NetworkTool/docs/08-构建与编译.md

构建与编译

1. 目标

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

2. Windows 客户端编译

在仓库根目录执行：

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

默认输出目录：

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\ 目录执行：

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

输出文件：

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 -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\ 目录执行：

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

说明：

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

5.2 登录远端主机

ssh x@192.168.229.136

说明：

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

5.3 停止旧进程

登录远端后执行：

sudo pkill -f quickip-agent

5.4 设置执行权限

登录远端后执行：

chmod +x /home/x/quickip-agent

说明：

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

5.5 以 root 身份启动 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 &

说明：

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

5.6 检查监听状态

登录远端后执行：

ss -ltnp | grep 48888

期望看到类似：

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

5.7 查看运行日志

登录远端后执行：

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

5.8 推荐顺序

本机 PowerShell：

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

远端登录后：

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 的命令，例如：

$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