docs: 重构文档体系

docs/development/build-release.md

@@ -0,0 +1,107 @@
+# 构建与发布
+
+## 开发期运行
+
+```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 或多架构模拟，需在变更记录中说明未执行原因。