108 lines
3.7 KiB
Markdown
108 lines
3.7 KiB
Markdown
# 构建与发布
|
||
|
||
## 开发期运行
|
||
|
||
```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 或多架构模拟，需在变更记录中说明未执行原因。
|