# 构建与编译

## 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 客户端

在仓库根目录执行：

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

默认输出目录：

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

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

输出文件：

```text
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
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

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

```powershell
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 登录远端主机

```powershell
ssh x@192.168.229.136
```

说明：

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

### 5.3 停止旧进程

登录远端后执行：

```bash
sudo pkill -f networktool-server
```

### 5.4 设置执行权限

登录远端后执行：

```bash
chmod +x /home/x/networktool-server
```

说明：

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

### 5.5 以 root 身份启动 Server

登录远端后执行：

```bash
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 检查监听状态

登录远端后执行：

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

期望看到类似：

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

### 5.7 查看运行日志

登录远端后执行：

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

### 5.8 推荐顺序

本机 PowerShell：

```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
```

远端登录后：

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

```powershell
$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`