haloy-config

Haloy 配置

创建 haloy.yaml 配置文件，以便使用 haloy 部署应用。

如果项目中没有 Dockerfile，且用户也没有可供部署的已发布镜像，请告知他们：

"此项目中未找到 Dockerfile，也没有发现可供部署的现有镜像。Haloy 可以通过 Dockerfile 构建，也可以部署已发布的镜像。您希望我使用 dockerize skill 创建一个 Dockerfile 吗？"

工作原理

1. 检查是否有 Dockerfile 或现有的已发布镜像 - 判断应用应使用 Haloy 默认的本地构建流程，还是显式配置镜像
2. 检查是否已配置 haloy 服务器 - 查找现有的服务器配置
3. 检查以下内容以检测项目类型：
   • 包含框架依赖项的 package.json（Next.js、TanStack Start、Express 等）
   • pyproject.toml、requirements.txt、Pipfile（Python/Django/FastAPI）
   • go.mod（Go）
   • Cargo.toml（Rust）
   • Gemfile（Ruby/Rails）
   • composer.json（PHP/Laravel）
4. 检测数据库依赖项（Prisma、Drizzle、pg、SQLAlchemy 等）
5. 推断默认值，包括应用名称、端口、健康检查路径和镜像策略
6. 询问用户服务器（从已配置列表中选择或手动填写）和域名
7. 如果需要显式配置镜像，收集最少的额外镜像信息
8. 如果检测到数据库，询问用户希望使用可自托管还是外部数据库
9. 生成 haloy.yaml，并填写适当的配置
10. 提供后续步骤，以便进行验证和部署

项目检测

检测框架以确定默认端口：

框架	指示项	默认端口
Next.js	package.json 依赖项中包含 next	3000
TanStack Start	package.json 中包含 @tanstack/react-start	3000
Express/Node.js	package.json 中包含 express，或为通用 Node 项目	3000
Vite	package.json 中包含 vite	5173（开发）/ 3000（生产）
Django	requirements.txt 或 pyproject.toml 中包含 django	8000
FastAPI	requirements.txt 或 pyproject.toml 中包含 fastapi	8000
Flask	requirements.txt 或 pyproject.toml 中包含 flask	5000
Go	存在 go.mod	8080
Rust	存在 Cargo.toml	8080
Ruby/Rails	Gemfile 中包含 rails	3000
PHP/Laravel	composer.json 中包含 laravel	8000
默认	未知框架	8080

同时检查 Dockerfile 中的 EXPOSE 指令；它们会覆盖框架的默认值。

数据库检测

扫描数据库依赖项，以确定项目是否使用数据库：

指示项	数据库类型
package.json 中包含 @prisma/client、prisma	检查 schema 中的 provider
package.json 中包含 drizzle-orm	检查配置中的 driver
package.json 中包含 pg、postgres	PostgreSQL
package.json 中包含 mysql2	MySQL
package.json 中包含 better-sqlite3、sqlite3	SQLite（无需服务）
package.json 中包含 sequelize、typeorm	检查配置中的 dialect
requirements.txt 中包含 psycopg2、asyncpg	PostgreSQL
requirements.txt 中包含 sqlalchemy	检查配置中的 driver
requirements.txt 中包含 django	检查 settings 中的数据库配置
存在 prisma/schema.prisma 文件	检查 datasource 块中的 provider

Prisma schema 示例 - 查找 provider：

datasource db {
  provider = "postgresql"  // or "mysql", "sqlite"
  url      = env("DATABASE_URL")
}

决策流程

除非缺少关键值，否则使用默认值。仅在必要时询问用户。

应用名称

• 首选：package.json 中的 name 字段
• 次选：项目文件夹名称
• 在以下情况下询问：名称包含无效字符或过于通用（例如，“app”“project”）

镜像策略

优先为用户的设置采用最简单且有效的镜像配置。

1. 默认本地构建：

   • 如果项目根目录中存在 Dockerfile，且用户没有要求发布镜像、配置注册表身份验证、自定义 Dockerfile 路径、自定义构建上下文或多个针对不同目标的镜像，则使用最精简的 Haloy 配置，并完全省略 image。
   • 这符合 Haloy 的默认流程：在同一目录中查找 Dockerfile，在本地构建，并上传到服务器。

2. 仅在必要时询问镜像详情：

   • 不存在 Dockerfile
   • 用户提到现有镜像／已发布镜像、Docker Hub、GHCR、ECR 或私有注册表
   • Dockerfile 不在配置目录中，或者项目是需要自定义构建上下文的单体仓库
   • 多个目标需要不同的镜像（例如，web 和 worker）
   • 用户明确要求推送到注册表，或设置回滚／历史记录

3. 使用现有镜像进行单镜像部署时：

   • 只需要仓库／标签时，使用字符串简写：

     image: "ghcr.io/acme/my-app:v1.2.3"
     

   • 仅当需要 tag、registry、history 或 build_config 时，才使用对象形式。
   • 除非 Haloy 无法从仓库主机推断注册表，否则省略 registry.server。

4. 需要显式镜像配置的本地构建：

   • 如果 Dockerfile 或构建上下文不是默认值，请使用 image.build_config。
   • 使用文档中的当前字段名称：

     image:
       build_config:
         context: "."
         dockerfile: "Dockerfile"
     

   • 路径相对于包含 haloy.yaml 的目录。
   • 优先省略 build_config.push；Haloy 会自动检测常见的 server 与 registry 情况。
   • 如果同一个值在运行时和构建参数中都需要使用，优先使用 env[].build_arg: true，而不是在 build_config.args 中重复配置。

5. 多目标设置：

   • 如果每个目标都应继承相同的镜像默认值，请使用根级 image。
   • 如果目标需要不同的镜像，请使用根级 images 和目标级 image_key。
   • 目标可以定义 image 或 image_key，但不能同时定义。
   • 优先级为：目标级 image -> 目标级 image_key -> 根级 image。

6. 既没有 Dockerfile，也没有已发布镜像时：

   • 推荐使用 dockerize 技能，而不是自行编造镜像配置。

服务器 URL

检查 ~/.config/haloy/client.yaml 中配置的服务器：

# Example client.yaml structure
servers:
  example.haloy.dev:
    token_env: HALOY_API_TOKEN_example_HALOY_DEV
  prod.mycompany.com:
    token_env: HALOY_API_TOKEN_PROD

决策流程：

1. 如果找到服务器：将它们作为选项列出，让用户选择。服务器键（例如 example.haloy.dev）就是配置中要使用的值。

   “我找到了以下已配置的 haloy 服务器。你想部署到哪一个？”

   • example.haloy.dev
   • prod.mycompany.com
   • 输入其他服务器

2. 如果没有找到服务器：运行 which haloy 或 haloy --version，检查是否安装了 haloy CLI

   • 如果已安装 haloy：手动询问服务器 URL

     “你的 haloy 服务器 URL 是什么？（例如，haloy.yourserver.com）”

   • 如果未安装 haloy：告知用户需要先安装并配置 CLI

     “未配置 haloy 服务器。要使用 haloy 部署，你需要安装 CLI 并添加服务器。请参阅：https://haloy.dev/docs/client-installation”

域名

• 始终询问——Web 应用必需
• 示例提示词：“这个应用应通过哪个域名访问？（例如，myapp.example.com）”
• 如果用户回答“无”或“跳过”，则省略 domains 部分

域名别名

• 在询问域名后再询问：用户提供域名后，询问是否要添加别名
• 示例提示词：“你想添加任何域名别名吗？（例如，www.myapp.example.com）”
• 常见别名：主域名前缀为 www.
• 如果用户回答“无”或“跳过”，则省略别名

DNS 提醒

收集完域名信息后，提醒用户配置 DNS：

“请记得通过域名提供商配置 DNS。使用 A 记录将您的域名指向 haloy 服务的 IP 地址；如果您的服务有域名，则使用 CNAME 记录。”

端口

• 使用上表中的框架默认端口
• 检查 Dockerfile 中的 EXPOSE 指令，该指令优先级更高
• 仅在以下情况询问：公开了多个端口，或没有明确的默认端口

健康检查路径

• 搜索现有端点：/health、/healthz、/api/health、/_health
• 如果找到：使用现有健康检查端点
• 如果没有找到：使用 /（根路径）
• 不要询问——haloy 默认会使用 /，这适用于大多数应用

数据库

如果检测到数据库依赖项（请参阅“数据库检测”部分）：

1. 询问用户：

   “我检测到数据库依赖项（[检测到的类型]）。您希望添加可自托管的数据库服务，还是使用外部提供商（Supabase、Neon、RDS 等）？”

   • 添加可自托管的数据库
   • 使用外部提供商（我会自行配置 DATABASE_URL）

2. 如果选择可自托管：

   • 生成包含数据库服务和应用目标的多目标配置
   • 对数据库目标使用 database 预设
   • 添加合适的环境变量及占位值，除非用户已在环境文件或密钥提供商中配置这些变量
   • 添加数据持久化卷
   • 对简单的数据库镜像，优先使用字符串简写；除非需要更多镜像字段
   • 注意：preset: database 会应用更安全的默认值，包括 image.history.strategy: "none"
   • 各类型数据库的默认值：

   数据库	镜像	端口	卷路径
   PostgreSQL	postgres:18	5432	/var/lib/postgresql
   MySQL	mysql:8	3306	/var/lib/mysql

   • 镜像的数据路径因镜像和版本而异。如果用户更改镜像，请在该镜像的文档中确认正确的挂载路径。

3. 如果选择外部提供商：

   • 按照常规生成单目标配置
   • 提醒用户：“请记得为外部数据库设置 DATABASE_URL 环境变量。”

配置参考

Haloy 支持两种模式：

1. 单次部署：未定义 targets，根配置即为部署目标
2. 多目标：已定义 targets，根配置用作基础/默认配置

最简配置（单次部署）

name: "my-app"
server: "haloy.yourserver.com"

当项目已有根目录 Dockerfile，且不需要自定义镜像设置时，这是默认选择。

配置域名和端口

name: "my-app"
server: "haloy.yourserver.com"
domains:
  - domain: "my-app.example.com"
    aliases:
      - "www.my-app.example.com"
port: "3000"
health_check_path: "/health"

配置已发布的镜像

name: "my-app"
server: "haloy.yourserver.com"
image: "ghcr.io/acme/my-app:v1.2.3"
domains:
  - domain: "my-app.example.com"
port: 3000

配置自定义本地构建

name: "my-app"
server: "haloy.yourserver.com"
image:
  repository: "my-app"
  tag: "latest"
  build_config:
    context: "."
    dockerfile: "./apps/web/Dockerfile"
domains:
  - domain: "my-app.example.com"
port: 3000

配置环境变量

name: "my-app"
server: "haloy.yourserver.com"
domains:
  - domain: "my-app.example.com"
port: "3000"
env:
  - name: "NODE_ENV"
    value: "production"
  - name: "DATABASE_URL"
    value: "postgres://user:pass@db:5432/myapp"

配置卷（用于持久化数据）

name: "my-app"
server: "haloy.yourserver.com"
domains:
  - domain: "my-app.example.com"
volumes:
  - "app-data:/app/data"

配置可自托管数据库（多目标）

server: "haloy.yourserver.com"
env:
  - name: POSTGRES_USER
    value: "postgres"
  - name: POSTGRES_PASSWORD
    value: "change-me-in-production"
  - name: POSTGRES_DB
    value: "my_app"

targets:
  postgres:
    preset: database
    image: "postgres:18"
    port: 5432
    volumes:
      - postgres-data:/var/lib/postgresql

  my-app:
    domains:
      - domain: "my-app.example.com"
    port: 3000
    env:
      - name: DATABASE_URL
        value: "postgres://postgres:change-me-in-production@postgres:5432/my_app"
      - name: NODE_ENV
        value: "production"

使用 image_key 命名镜像

name: "my-app"
server: "haloy.yourserver.com"
images:
  web:
    repository: "my-app-web"
    tag: "v1.2.3"
  worker: "my-app-worker:v1.2.3"

targets:
  production:
    image_key: "web"
    domains:
      - domain: "my-app.example.com"
    port: 3000

  jobs:
    image_key: "worker"

多目标示例

# Base settings inherited by all targets
image:
  repository: "my-app"
  tag: "latest"
  build_config:
    context: "."
    dockerfile: "Dockerfile"
port: 3000

targets:
  production:
    server: "prod.haloy.com"
    domains:
      - domain: "my-app.com"
    replicas: 2
  staging:
    server: "staging.haloy.com"
    domains:
      - domain: "staging.my-app.com"
    replicas: 1

完整参考

所有配置选项请参阅：https://haloy.dev/docs/configuration-reference

关键选项：

• name - 应用名称（单次部署必填）
• server - Haloy 服务 URL（必填）
• image - 默认／单个目标的 Docker 镜像配置；支持字符串简写或对象形式
• images - 用于多目标部署的命名镜像根映射
• image_key - 目标级别对 images 中命名镜像的引用
• image.build_config - 本地构建设置：context、dockerfile、platform、args 和可选的 push
• image.registry - 私有镜像或推送镜像到注册表时使用的注册表身份验证
• image.history - 回滚策略（local、registry 或 none）
• domains - 域对象数组，包含 domain 和可选的 aliases
• port - 容器端口（默认值：“8080”）
• health_check_path - 健康检查端点（默认值：“/”）
• env - 以名称／值对形式配置的环境变量
• volumes - 用于持久化数据的卷挂载
• replicas - 容器实例数量（默认值：1）
• deployment_strategy - “rolling”（默认值）或 “replace”
• targets - 定义多个部署目标（多目标模式）
• preset - 应用预设配置（“database” 或 “service”）

输出格式

收集信息后，创建 haloy.yaml 文件并提供：

1. haloy.yaml 文件 - 写入项目根目录
2. 更新 .dockerignore - 如果 .dockerignore 中尚未包含 haloy.yaml，请将其添加进去。这样可以改善 Docker 层缓存，因为更改 haloy.yaml 不会使构建缓存失效。
3. 验证命令：

   haloy validate-config
   

4. 部署命令：

   haloy deploy
   

5. 如果尚未安装 haloy CLI，请展示安装选项：

   # Shell script
   curl -fsSL https://sh.haloy.dev/install-haloy.sh | sh
   
   # Homebrew
   brew install haloydev/tap/haloy
   
   # npm/pnpm/bun
   npm install -g haloy
   pnpm add -g haloy
   bun add -g haloy
   

交互示例

请参阅 references/examples.md，了解涵盖以下内容的详细交互示例：

• 使用已配置的服务进行部署
• 检测数据库并设置可自托管的数据库
• 处理缺少服务配置的情况