# 构建与发布

## 开发期运行

```bash
bun run dev probes.yaml
```

`scripts/dev.ts` 同时启动两个进程：

| 进程            | 用途                                              |
| --------------- | ------------------------------------------------- |
| Bun API server  | 后端 API 服务，`--watch` 监听后端文件变更自动重启 |
| Vite dev server | 前端 SPA、HMR、模块热替换                         |

也可以单独启动：

```bash
bun run dev:server probes.yaml
bun run dev:web
```

## 前后端集成

开发模式下，Vite 通过 proxy 将 `/api/*` 和 `/health` 转发到 Bun。

生产模式下，前端通过 Vite 构建为静态资源，通过 `import with { type: "file" }` 嵌入 Bun 可执行文件。非 API 路径由 fetch fallback 处理：有文件扩展名的返回静态资源或 404，无扩展名的返回 SPA index.html。

## 构建

```bash
bun run build
```

构建流程：

```text
1. Vite build      -> dist/web/
2. Code generation -> .build/static-assets.ts + .build/server-entry.ts
3. Bun compile     -> dist/dial-server
```

构建参数：

| 环境变量       | 说明             |
| -------------- | ---------------- |
| `BUN_TARGET`   | 交叉编译目标平台 |
| `BUILD_TARGET` | 交叉编译目标平台 |

## Docker 镜像

Docker 镜像使用 Alpine 多阶段构建，保持与生产单可执行文件交付模型一致。

```text
oven/bun:1-alpine -> bun install --frozen-lockfile
                   -> BUN_TARGET=bun-linux-*-musl bun run build
                   -> dist/dial-server

alpine            -> 仅复制 /usr/local/bin/dial-server
                   -> 安装 ca-certificates、iputils-ping、libgcc、libstdc++、tzdata
                   -> 使用非 root dial 用户运行
```

Dockerfile 通过 `TARGETARCH` 选择 Bun compile target。

| `TARGETARCH` | `BUN_TARGET`           |
| ------------ | ---------------------- |
| `amd64`      | `bun-linux-x64-musl`   |
| `arm64`      | `bun-linux-arm64-musl` |

## Release

```bash
bun run release
bun run release --target linux-x64
bun run release --target linux-x64,windows-x64,darwin-arm64
```

release 流程：

```text
1. Vite build          -> dist/web/
2. Code generation     -> .build/
3. 多目标 Bun compile  -> dist/release/binaries/
4. tar.gz 打包         -> dist/release/packages/
```

支持的平台见 [用户部署文档](../user/deployment.md#跨平台发布包)。

## 脚本说明

| 脚本                   | 文件                                | 说明                           |
| ---------------------- | ----------------------------------- | ------------------------------ |
| `bun run dev`          | `scripts/dev.ts`                    | 双进程开发服务                 |
| `bun run dev:server`   | `src/server/dev.ts`                 | 仅启动后端 API server          |
| `bun run dev:web`      | Vite CLI                            | 仅启动 Vite dev server         |
| `bun run build`        | `scripts/build.ts`                  | Vite -> codegen -> Bun compile |
| `bun run release`      | `scripts/release.ts`                | 多目标交叉编译和打包           |
| `bun run schema`       | `scripts/generate-config-schema.ts` | 生成配置 JSON Schema           |
| `bun run schema:check` | `scripts/generate-config-schema.ts` | 检查配置 JSON Schema 同步      |
| `bun run clean`        | `scripts/clean.ts`                  | 清理构建缓存与临时文件         |

## 维护约定

- `scripts/build-common.ts` 中的 import specifier 输出必须使用 `/` 分隔符。
- 跨平台路径测试不得用当前平台 `path.sep` 伪装其他平台，应使用 `node:path.win32` 或等价注入方式模拟。
- 如本地 Docker 环境不支持 buildx 或多架构模拟，需在变更记录中说明未执行原因。