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

构建与编译

1. 目标

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

2. Windows 客户端编译

2.0 Windows 客户端版本号约定

每次修改 windows 端代码时，必须同步更新 windows/NetworkTool.Client/NetworkTool.Client.csproj 中的 InformationalVersion。

版本号格式固定为当前时间：yyyy.MM.dd.HHmm，例如 2026.05.13.1446。

该版本号会显示在 Windows 客户端主界面标题栏，用于排查客户端程序是否为最新版本。

注意：只要改动了 windows 目录下会影响 Windows 客户端行为或界面的代码，就要更新该版本号。

2.1 编译 Windows 客户端

在仓库根目录执行：

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

默认输出目录：

windows\NetworkTool.Client\bin\Debug\net9.0-windows\

说明：

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

3. Server 编译

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

本节默认前提：当前 PowerShell 已位于 D:\git\NetworkTool\server。

3.0 Server 版本号约定

每次修改 server 端代码时，必须同步更新 server/internal/config/config.go 中的 ServerVersion。

版本号格式固定为当前时间：yyyy.MM.dd.HHmm，例如 2026.05.13.1446。

该版本号用于排查客户端与远端 Server 是否一致：

1. Server 启动日志会输出版本号
2. /api/device/info 会返回 server_version
3. Windows 客户端“设备信息与接口配置”标题栏会显示该版本号

注意：只要改动了 server 目录下会影响 Server 行为的代码，就要更新该版本号。

3.1 编译 Linux amd64 版 Server

在 server\ 目录执行：

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

输出文件：

server\networktool-server-linux-amd64

说明：

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

4. 一键编译

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

执行命令：

powershell -ExecutionPolicy Bypass -File .\build.ps1

该脚本会依次完成：

1. 发布 Windows 客户端自包含单文件到 publish\win-x64\NetworkTool.Client-<InformationalVersion>-win-x64.exe
2. 编译 Linux amd64 版 Server 到 publish\linux-amd64\networktool-server-<ServerVersion>-linux-amd64

5. 上传与启动

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

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

5.1 上传 Linux 版 Server

如果当前已经在仓库根目录执行：

scp .\publish\linux-amd64\networktool-server-<ServerVersion>-linux-amd64 x@192.168.229.136:/home/x/networktool-server

说明：

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

5.2 登录远端主机

ssh x@192.168.229.136

说明：

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

5.3 停止旧进程

登录远端后执行：

sudo pkill -f networktool-server

5.4 设置执行权限

登录远端后执行：

chmod +x /home/x/networktool-server

说明：

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

5.5 以 root 身份启动 Server

登录远端后执行：

sudo nohup /home/x/networktool-server --ip 169.254.100.2 --port 48888 --password 'Dieteng2026' >/home/x/networktool-server-run.log 2>&1 < /dev/null &

说明：

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

5.6 检查监听状态

登录远端后执行：

ss -ltnp | grep 48888

期望看到类似：

LISTEN ... 169.254.100.2:48888 ... networktool-server

5.7 查看运行日志

登录远端后执行：

tail -n 50 /home/x/networktool-server-run.log

5.8 推荐顺序

本机 PowerShell：

scp .\publish\linux-amd64\networktool-server-<ServerVersion>-linux-amd64 x@192.168.229.136:/home/x/networktool-server
ssh x@192.168.229.136

远端登录后：

sudo pkill -f networktool-server
chmod +x /home/x/networktool-server
sudo nohup /home/x/networktool-server --ip 169.254.100.2 --port 48888 --password 'Dieteng2026' >/home/x/networktool-server-run.log 2>&1 < /dev/null &
ss -ltnp | grep 48888

6. 常见问题

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

这是正常现象。

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

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

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

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

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

处理方式：

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