DiAL/docs/development/release.md

构建与发布

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

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

开发期运行

bun run dev probes.yaml

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

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

也可以单独启动：

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。

构建

bun run build

构建流程：

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 多阶段构建，保持与生产单可执行文件交付模型一致。

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

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

release 流程：

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

支持的平台见 用户部署文档。

脚本说明

脚本	文件	说明
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 运行参数、发布包内容或运行时依赖时，必须同步更新 用户部署文档。

更新触发条件

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