# 构建与发布

本文档说明开发服务、前后端集成、生产构建、Docker 镜像、跨平台 release 和相关脚本维护方式。

适用场景：修改 `scripts/`、构建流程、Dockerfile、静态资源集成、release 打包、运行时环境变量或部署产物。

## 开发期运行

```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 或多架构模拟，需在变更记录中说明未执行原因。

## 发布验证

| 变更类型         | 验证方式                                |
| ---------------- | --------------------------------------- |
| 构建脚本         | `bun run verify`                        |
| release 脚本     | `bun run release` 或指定受影响 target   |
| Dockerfile       | 本地 `docker build`，无法执行时说明原因 |
| 静态资源集成     | `bun run build`，必要时启动产物手动验证 |
| 配置 schema 同步 | `bun run schema:check`                  |

影响用户部署方式、Docker 运行参数、发布包内容或运行时依赖时，必须同步更新 [用户部署文档](../user/deployment.md)。

## 更新触发条件

修改开发服务、前后端集成、构建产物、Docker 镜像、release target、脚本参数或发布验证方式时，必须更新本文档。
