lanyuanxiaoyao
cfca03b4d6
- 合并 20+ 细粒度 spec 为粗粒度主题规范：dashboard、data-store、probe-engine、probe-api、probe-config 等 - 删除完全冗余规范：data-retention（被 probe-engine+data-store 覆盖）、backend-code-quality（DEVELOPMENT.md 已记录） - 补充 http-checker 规范至完整标准（配置+执行+expect+校验+observation），匹配代码 440 行实现 - 清理 tcp/udp/llm checker 规范中已废弃 defaults 配置段的残留 Scenario - 清理 checker-cohesion-structure 中的实现路径引用（src/server/...） - 统一所有 spec 格式（## Purpose 开头，去除 # Capability/Title 形式） - 更新 prompt-spec-review.md 审查提示文档
138 lines
6.1 KiB
Markdown
138 lines
6.1 KiB
Markdown
## Purpose
|
||
|
||
Provide Alpine-based multi-stage Docker container image packaging for DiAL, enabling containerized deployment with musl executables, minimal runtime dependencies, and documented build/run workflows.
|
||
|
||
## Requirements
|
||
|
||
### Requirement: Alpine 多阶段容器镜像构建
|
||
|
||
系统 SHALL 提供基于 Alpine 的多阶段 Dockerfile，用于从源码构建 DiAL 容器镜像。构建阶段 SHALL 使用 Bun 官方 Alpine 镜像安装依赖并执行现有生产构建命令；运行阶段 SHALL 使用 Alpine 基础镜像并只复制生产运行所需产物。
|
||
|
||
#### Scenario: 构建容器镜像
|
||
|
||
- **WHEN** 开发者在项目根目录执行文档化的 Docker 构建命令
|
||
- **THEN** 镜像构建 SHALL 安装锁定依赖、执行 `bun run build`，并将生成的 `dist/dial-server` 复制到最终运行镜像
|
||
|
||
#### Scenario: 运行镜像不包含开发依赖
|
||
|
||
- **WHEN** Dockerfile 生成最终运行阶段
|
||
- **THEN** 最终运行阶段 SHALL NOT 复制源码目录、`node_modules`、`.build` 或 `dist/web` 到镜像中
|
||
|
||
### Requirement: Alpine musl executable 目标
|
||
|
||
系统 MUST 为 Alpine 运行阶段生成 musl Linux executable。Docker 构建 SHALL 根据 Docker 构建架构选择 `bun-linux-x64-musl` 或 `bun-linux-arm64-musl`，并将该目标传递给现有 Bun compile 流程。
|
||
|
||
#### Scenario: amd64 镜像构建
|
||
|
||
- **WHEN** Docker 构建目标架构为 `amd64`
|
||
- **THEN** 构建阶段 MUST 使用 `bun-linux-x64-musl` 作为 Bun compile target
|
||
|
||
#### Scenario: arm64 镜像构建
|
||
|
||
- **WHEN** Docker 构建目标架构为 `arm64`
|
||
- **THEN** 构建阶段 MUST 使用 `bun-linux-arm64-musl` 作为 Bun compile target
|
||
|
||
#### Scenario: 不支持的架构
|
||
|
||
- **WHEN** Docker 构建目标架构不是 `amd64` 或 `arm64`
|
||
- **THEN** 构建 MUST 失败并输出不支持该架构的错误
|
||
|
||
### Requirement: 容器运行环境边界
|
||
|
||
运行镜像 SHALL 提供 DiAL 运行必需的系统能力，包括 HTTPS CA 证书、ICMP checker 所需 `ping` 命令、Bun musl executable 所需运行库、时区数据、非 root 运行用户和可写数据目录。运行镜像 SHALL NOT 默认提供 CMD checker 可能依赖的业务命令环境。
|
||
|
||
#### Scenario: 基础系统包
|
||
|
||
- **WHEN** 最终运行镜像构建完成
|
||
- **THEN** 镜像 SHALL 包含 `ca-certificates`、`iputils-ping`、`libgcc`、`libstdc++` 和 `tzdata`
|
||
|
||
#### Scenario: 非 root 运行
|
||
|
||
- **WHEN** 容器启动 DiAL 进程
|
||
- **THEN** DiAL 进程 SHALL 以非 root 用户运行，并且该用户 SHALL 能写入 `/data/dial`
|
||
|
||
#### Scenario: CMD checker 额外命令不内置
|
||
|
||
- **WHEN** 用户需要通过 CMD checker 执行 `curl`、`dig`、`psql`、`mysql`、`redis-cli` 或自定义脚本依赖
|
||
- **THEN** 官方镜像 SHALL 要求用户通过派生镜像或运行环境自行提供这些命令
|
||
|
||
### Requirement: 容器默认启动约定
|
||
|
||
系统 SHALL 为容器镜像提供稳定的默认启动约定。镜像 SHALL 使用 `dial-server` executable 作为入口，默认配置文件路径 SHALL 为 `/etc/dial/probes.yaml`，默认服务端口 SHALL 暴露 `3000`。
|
||
|
||
#### Scenario: 默认配置路径
|
||
|
||
- **WHEN** 用户不覆盖容器启动命令
|
||
- **THEN** 容器 SHALL 尝试使用 `/etc/dial/probes.yaml` 作为 DiAL YAML 配置文件路径启动
|
||
|
||
#### Scenario: 默认端口暴露
|
||
|
||
- **WHEN** 用户查看镜像元数据或使用文档化运行命令
|
||
- **THEN** 镜像 SHALL 暴露并映射 DiAL 默认 HTTP 端口 `3000`
|
||
|
||
### Requirement: 容器专用最小配置示例
|
||
|
||
系统 SHALL 提供容器专用最小配置示例，用于直接挂载到默认配置路径运行。该配置 SHALL 默认监听容器网络地址 `0.0.0.0`，默认端口为 `3000`，并将存储目录设置为 `/data/dial`。
|
||
|
||
#### Scenario: 容器配置监听所有接口
|
||
|
||
- **WHEN** 用户使用容器专用配置示例启动 DiAL
|
||
- **THEN** DiAL SHALL 监听 `0.0.0.0:3000`，使宿主机端口映射可访问服务
|
||
|
||
#### Scenario: 容器配置持久化目录
|
||
|
||
- **WHEN** 用户使用容器专用配置示例启动 DiAL
|
||
- **THEN** SQLite 数据和默认日志 SHALL 写入 `/data/dial` 下的路径
|
||
|
||
#### Scenario: 容器配置避免额外命令依赖
|
||
|
||
- **WHEN** 用户使用容器专用配置示例启动 DiAL
|
||
- **THEN** 示例配置 SHALL NOT 包含依赖 Bun、Node.js 或额外系统命令的 CMD checker target
|
||
|
||
### Requirement: 容器健康检查
|
||
|
||
镜像 SHALL 提供 Docker HEALTHCHECK，通过 Alpine 自带 `wget` 访问 DiAL `/health` 端点判断进程健康。健康检查 SHALL NOT 为此额外安装 `curl`。
|
||
|
||
#### Scenario: 健康检查成功
|
||
|
||
- **WHEN** DiAL 在容器内启动并响应 `/health`
|
||
- **THEN** Docker HEALTHCHECK SHALL 通过 HTTP 请求 `/health` 成功返回健康状态
|
||
|
||
#### Scenario: 不额外安装 curl
|
||
|
||
- **WHEN** 最终运行镜像构建完成
|
||
- **THEN** 镜像 SHALL NOT 为健康检查目的安装 `curl`
|
||
|
||
### Requirement: Docker 构建上下文控制
|
||
|
||
系统 SHALL 提供 Docker 构建上下文忽略规则，避免将开发依赖、构建产物、本地数据、环境文件和工具状态复制进构建上下文。
|
||
|
||
#### Scenario: 忽略开发和构建产物
|
||
|
||
- **WHEN** Docker 构建上下文被发送给 Docker daemon
|
||
- **THEN** `node_modules`、`dist`、`.build`、`data`、本地环境文件和工具状态目录 SHALL 被忽略
|
||
|
||
### Requirement: Docker 使用文档
|
||
|
||
系统 SHALL 在项目文档中说明 Docker 镜像的构建、运行和扩展方式。文档 MUST 覆盖单架构构建、多架构 buildx 构建、配置挂载、数据卷、ICMP capability 和 CMD checker 派生镜像策略。
|
||
|
||
#### Scenario: 单架构 Docker 构建文档
|
||
|
||
- **WHEN** 用户阅读 Docker 部署说明
|
||
- **THEN** 文档 SHALL 提供在本机架构构建 Alpine 镜像的命令示例
|
||
|
||
#### Scenario: 多架构 buildx 文档
|
||
|
||
- **WHEN** 用户阅读 Docker 部署说明
|
||
- **THEN** 文档 SHALL 提供 `linux/amd64` 和 `linux/arm64` 的 buildx 构建命令示例
|
||
|
||
#### Scenario: ICMP capability 文档
|
||
|
||
- **WHEN** 用户需要在容器中运行 ICMP checker
|
||
- **THEN** 文档 MUST 明确说明运行容器时需要授予 `NET_RAW` capability
|
||
|
||
#### Scenario: CMD checker 派生镜像文档
|
||
|
||
- **WHEN** 用户需要 CMD checker 执行官方镜像未内置的命令
|
||
- **THEN** 文档 SHALL 提供通过派生镜像安装额外命令的示例
|