安装&部署

已有实例先迁移

从 v0.8.5 或更早版本升级，先创建升级前备份并迁移配置，不要直接换二进制后沿用旧配置重启。先完成v0.9 升级指南中的步骤。

这一页面向部署者。只想调用现成实例的，去我拿到了一个 Key。

已经完成安装、准备调整监听地址、超时、TLS、日志或安全策略的，参阅配置参数参考。

单写者：部署前先记住这一条

Halro v1 的一致性边界是一个进程独占一个数据目录。Docker 只能启动一个 Halro 容器；Kubernetes 必须是 replicas: 1 和 Recreate，不能滚动更新，也不能让两个 Pod 同时挂载同一份数据。

选一种安装方式

选一种安装方式

环境	适合	安装方式
Docker	单机、NAS、开发机，或已有容器平台	使用官方多架构镜像，显式执行一次 init
Kubernetes	已有集群和持久卷	先运行一次初始化 Job，再运行单副本 Deployment
macOS	本机试用、开发	下载 darwin-arm64 或 darwin-amd64 发布包
Linux	裸机或虚拟机	下载 linux-arm64 或 linux-amd64 发布包，可交给 systemd
Windows	Windows 10/11 或 Windows Server	使用 Docker 的 Linux 容器；也可在 WSL2 中按 Linux 方式安装

GitHub 下载命令使用当前正式版 v0.9.1。升级时应先阅读版本升级边界；生产环境还应把容器标签换成镜像 digest。

当前分发渠道

• GitHub Release 已发布 v0.9.1；
• GHCR 已发布 v0.9.1，同时提供 linux/amd64 与 linux/arm64；
• brew install halro-ai/tap/halro 当前安装 v0.9.1；
• 官方 APT 仓库提供 v0.9.1（Debian 包版本 0.9.1-1），支持 amd64 与 arm64。

各渠道独立发布；后续升级请以安装中心显示的渠道版本为准。

所有环境都需要知道的事

Halro 是一个带管理后台的 Go 单二进制，不需要 PostgreSQL、Redis 或单独的前端服务。持久化时却有三样东西必须分别看待：

• config.yaml：监听地址、TLS、存储位置和安全边界；
• 数据目录：数据库、账本、审计链和用量文件；
• Master Key：解密 Provider 凭据所必需，不在加密备份中，必须与数据和备份密钥分开保管。

初始化和 doctor、备份、恢复等离线命令都要求 Halro 已停止。不要只复制 halro.db，也不要混用不同时间点的数据库、账本、审计和用量目录。

默认配置只监听 127.0.0.1，适合本机使用。要让其他机器访问，推荐让 Caddy、Traefik 或 nginx 终止 TLS，Halro 仍监听回环地址；也可以由 Halro 自己加载证书。不要把明文 Gateway、Admin 或 Metrics 直接暴露到公网。

macOS

下载并启动

Apple Silicon（M1/M2/M3/M4）下载 arm64：

VERSION=v0.9.1
ARTIFACT=halro-darwin-arm64.tar.gz
BASE_URL="https://github.com/akz142857/Halro/releases/download/$VERSION"

curl -fLO "$BASE_URL/$ARTIFACT"
curl -fLO "$BASE_URL/$ARTIFACT.sigstore.json"
curl -fLO "$BASE_URL/checksums.txt"
curl -fLO "$BASE_URL/checksums.txt.sigstore.json"

正式发布同时提供 checksum 和 Sigstore bundle。安装 cosign 2.2 或更高版本，先验证 checksum 清单的发布身份，再验证文件摘要和发布包本身：

COSIGN_IDENTITY="https://github.com/akz142857/Halro/.github/workflows/release.yml@refs/heads/main"
COSIGN_ISSUER="https://token.actions.githubusercontent.com"

cosign verify-blob \
  --certificate-identity "$COSIGN_IDENTITY" \
  --certificate-oidc-issuer "$COSIGN_ISSUER" \
  --bundle checksums.txt.sigstore.json checksums.txt
grep "[[:space:]]$ARTIFACT$" checksums.txt | shasum -a 256 --check
cosign verify-blob \
  --certificate-identity "$COSIGN_IDENTITY" \
  --certificate-oidc-issuer "$COSIGN_ISSUER" \
  --bundle "$ARTIFACT.sigstore.json" "$ARTIFACT"

tar -xzf halro-darwin-arm64.tar.gz
cd halro-darwin-arm64
./halro version
./halro start --config ./config.yaml

Intel Mac 把文件名中的 arm64 换成 amd64。

start 会在当前目录创建一份仅监听回环地址的 config.yaml、Master Key 和数据目录，然后启动服务。终端会打印管理地址；打开 http://127.0.0.1:8081/admin/setup。

如果 macOS 仍因下载文件的隔离属性阻止启动，只有在上面的三项验证全部通过后才执行：

xattr -d com.apple.quarantine ./halro

让其他机器访问

不要把 gateway_listen 直接改成公网明文地址。生产部署应把二进制、配置、数据目录和 Master Key 放到固定路径，由 launchd 或已有的进程管理器运行，并在前面配置 TLS 反向代理。通过代理访问管理后台时，还要设置：

admin:
  external_origin: https://halro.example.com
security:
  trust_proxy_headers: true
  trusted_proxy_cidrs: ["127.0.0.1/32"]

trusted_proxy_cidrs 必须写代理连接 Halro 时的真实来源地址；代理不在同一主机时不能照抄回环地址。

Linux

下载并试运行

x86-64 主机：

VERSION=v0.9.1
ARTIFACT=halro-linux-amd64.tar.gz
BASE_URL="https://github.com/akz142857/Halro/releases/download/$VERSION"

curl -fLO "$BASE_URL/$ARTIFACT"
curl -fLO "$BASE_URL/$ARTIFACT.sigstore.json"
curl -fLO "$BASE_URL/checksums.txt"
curl -fLO "$BASE_URL/checksums.txt.sigstore.json"

COSIGN_IDENTITY="https://github.com/akz142857/Halro/.github/workflows/release.yml@refs/heads/main"
COSIGN_ISSUER="https://token.actions.githubusercontent.com"
cosign verify-blob \
  --certificate-identity "$COSIGN_IDENTITY" \
  --certificate-oidc-issuer "$COSIGN_ISSUER" \
  --bundle checksums.txt.sigstore.json checksums.txt
grep "[[:space:]]$ARTIFACT$" checksums.txt | sha256sum --check
cosign verify-blob \
  --certificate-identity "$COSIGN_IDENTITY" \
  --certificate-oidc-issuer "$COSIGN_ISSUER" \
  --bundle "$ARTIFACT.sigstore.json" "$ARTIFACT"

tar -xzf halro-linux-amd64.tar.gz
cd halro-linux-amd64
./halro version
./halro start --config ./config.yaml

ARM64 主机把文件名中的 amd64 换成 arm64。首次启动后，在服务器本机打开 http://127.0.0.1:8081/admin/setup；远程服务器可以先用 SSH 隧道完成初始化：

ssh -L 8081:127.0.0.1:8081 user@your-server

然后在自己电脑打开 http://127.0.0.1:8081/admin/setup。

用 systemd 长期运行

先创建专用账户和目录，把下载包里的 halro 安装到固定位置：

sudo useradd --system --home /var/lib/halro --shell /usr/sbin/nologin halro
sudo install -m 0755 ./halro /usr/local/bin/halro
sudo install -d -o halro -g halro -m 0700 /var/lib/halro /var/lib/halro-secrets
sudo install -d -o root -g halro -m 0750 /etc/halro

从完整示例创建配置，并把存储路径改为固定位置：

curl -o /tmp/halro-config.yaml https://raw.githubusercontent.com/akz142857/Halro/v0.9.1/configs/config.example.yaml
sudo install -o root -g halro -m 0640 /tmp/halro-config.yaml /etc/halro/config.yaml

storage:
  data_dir: /var/lib/halro/data
  master_key:
    mode: file
    file: /var/lib/halro-secrets/master.key

检查并初始化一次：

sudo -u halro /usr/local/bin/halro config check --config /etc/halro/config.yaml
sudo -u halro /usr/local/bin/halro init --config /etc/halro/config.yaml

创建 /etc/systemd/system/halro.service：

[Unit]
Description=Halro LLM Gateway
After=network-online.target
Wants=network-online.target

[Service]
User=halro
Group=halro
ExecStart=/usr/local/bin/halro serve --config /etc/halro/config.yaml
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5s
TimeoutStopSec=150s
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/var/lib/halro /var/lib/halro-secrets

[Install]
WantedBy=multi-user.target

启动并查看日志：

sudo systemctl daemon-reload
sudo systemctl enable --now halro
sudo systemctl status halro
sudo journalctl -u halro -f

这个示例保持三个监听器仅在本机可达。用反向代理提供 HTTPS 后，再设置 admin.external_origin 和可信代理网段。

Windows

当前没有原生 Windows 发布包

正式发布目前只提供 Linux 和 macOS 二进制；文件模式 Master Key 的宿主安全实现也只面向 Linux/macOS。因此不要从非官方来源下载 halro.exe。Windows 上请使用 Linux 容器，或在 WSL2 中按 Linux 章节安装。

Windows 10/11：Docker Desktop

1. 安装 Docker Desktop 4.34 或更高版本，启用 WSL2 后端、Linux containers 和 Host networking。Host networking 与 Enhanced Container Isolation 不能同时启用；必须保留后者时，请改用 WSL2 或 Linux 虚拟机部署。
2. 在 PowerShell 中创建工作目录并进入：

New-Item -ItemType Directory -Force C:\halro | Out-Null
Set-Location C:\halro
curl.exe -o config.yaml https://raw.githubusercontent.com/akz142857/Halro/v0.9.1/configs/config.example.yaml

3. 按下一节修改 config.yaml、创建 compose.yaml，然后执行：

docker compose run --rm halro-init
docker compose up -d halro

另开一个 PowerShell 窗口导出并检查 Master Key，然后把它移到独立的 Secret 管理或离线介质中：

docker compose cp halro:/run/secrets/halro-master.key .\halro-master.key
if ((Get-Item .\halro-master.key).Length -ne 32) { throw "Master Key 长度不是 32 字节" }
icacls .\halro-master.key /inheritance:r
icacls .\halro-master.key /grant:r "$($env:USERNAME):(R)"

需要持续查看日志时，另开窗口执行 docker compose logs -f halro。

Windows Server 建议在 Linux 虚拟机中部署 Halro；不要把 Windows containers 模式当作替代方案。

WSL2

在 Ubuntu 等 WSL2 发行版中直接按 Linux 章节操作。生产使用仍建议 Linux 虚拟机或容器主机，因为 WSL2 的生命周期、网络和磁盘挂载更适合开发环境。

Docker

GHCR 当前已验收的最新镜像是 v0.9.1，同时支持 linux/amd64 和 linux/arm64。容器是 distroless 镜像，没有 shell，以 uid/gid 65532 运行；默认命令是 serve，而 serve 不会自动初始化。

Docker Desktop 前置条件

下面的 Compose 使用 host networking。Linux 原生 Docker 可直接使用；Docker Desktop 必须是 4.34 或更高版本并在设置中启用 Host networking，而且不能同时启用 Enhanced Container Isolation。无法满足时，请使用 Linux 虚拟机或 WSL2。

1. 准备完整配置

下载与镜像版本一致的完整配置：

curl -o config.yaml https://raw.githubusercontent.com/akz142857/Halro/v0.9.1/configs/config.example.yaml

至少修改下面两项。配置不能只写这几项：Halro 会严格校验完整文件中的字段。这个 Compose 方案使用宿主网络，三个监听地址继续保留默认的 127.0.0.1。

storage:
  data_dir: "/var/lib/halro/data"
  master_key:
    mode: file
    file: "/run/secrets/halro-master.key"

data_dir 必须是挂载点的子目录，不能直接写 /var/lib/halro，因为 Halro 要在它旁边创建原子发布锁。

2. 创建 Compose 文件

新建 compose.yaml：

services:
  halro-init:
    image: ghcr.io/akz142857/halro:v0.9.1
    user: "65532:65532"
    command: ["init", "--config", "/etc/halro/config.yaml"]
    network_mode: host
    volumes:
      - ./config.yaml:/etc/halro/config.yaml:ro
      - halro-data:/var/lib/halro
      - halro-secrets:/run/secrets

  halro:
    image: ghcr.io/akz142857/halro:v0.9.1
    user: "65532:65532"
    command:
      - serve
      - --config
      - /etc/halro/config.yaml
    network_mode: host
    restart: unless-stopped
    volumes:
      - ./config.yaml:/etc/halro/config.yaml:ro
      - halro-data:/var/lib/halro
      - halro-secrets:/run/secrets:ro
volumes:
  halro-data:
  halro-secrets:

3. 初始化一次并启动

docker compose run --rm halro-init
docker compose up -d halro
docker compose ps

立即把 Master Key 导出到宿主，验证它恰好是 32 字节并收紧权限：

docker compose cp halro:/run/secrets/halro-master.key ./halro-master.key
chmod 600 ./halro-master.key
test "$(wc -c < ./halro-master.key | tr -d ' ')" -eq 32

将导出的文件转移到独立的 Secret 管理或离线介质；确认托管副本可恢复后，不要继续把宿主工作目录里的临时副本当作备份。

需要持续查看日志时，另开终端执行 docker compose logs -f halro。

Compose 示例使用 host networking，让容器中的三个回环监听器仍只出现在宿主回环地址。Linux 原生 Docker 可直接使用；Docker Desktop 需要先在设置中启用 Host networking。启动后可以打开 http://127.0.0.1:8081/admin/setup。生产环境应由宿主上的 TLS 反向代理访问 Gateway 和 Admin。

docker compose ps 显示 healthy 只说明容器内部就绪，不证明宿主端口、证书、代理或防火墙可用。还要从真正的客户端位置检查外部地址。

生产 serve 使用 Secret 或离线 Bootstrap

v0.8.3 起，生产 serve 不再生成必须从日志取回的 Setup Token。远程零管理员实例必须挂载 admin.setup_token_file，或在启动前执行离线 admin bootstrap。v0.9.1 镜像包含这一行为。

4. 生产环境配置 HTTPS 证书

生产环境必须有 TLS

只要 Gateway 或 Admin 会被其他机器访问，就必须通过 HTTPS 提供服务。证书可以由反向代理管理，也可以由 Halro 直接加载；不能把明文的 8080、8081 或 9090 端口暴露到公网。

推荐：由 Caddy、nginx 或 Traefik 管理证书

推荐的流量路径是：

客户端 → HTTPS 反向代理 → 127.0.0.1:8080/8081 → Halro 容器

此时证书安装在反向代理上，Halro 保持默认回环监听，并保持 tls.enabled: false。例如宿主机上的 Caddy：

api.example.com {
  reverse_proxy 127.0.0.1:8080
}

admin.example.com {
  reverse_proxy 127.0.0.1:8081
}

域名已经解析到服务器且防火墙允许 80/443 时，Caddy 可以自动申请和续期公开信任的证书。nginx 或 Traefik 也可以完成同样的 TLS 终止。

同时在 config.yaml 中设置管理端实际对外地址。如果需要依据真实客户端 IP 执行审计或来源限制，只信任反向代理所在的精确网段：

tls:
  enabled: false
  certificates: []

admin:
  external_origin: "https://admin.example.com"
  mfa_policy: "required"

security:
  trust_proxy_headers: true
  trusted_proxy_cidrs:
    - "127.0.0.1/32"
    - "::1/128"

若代理不是运行在宿主回环地址，应把 CIDR 换成代理的实际容器或内网网段，不能填写 0.0.0.0/0。管理域名还应通过 VPN、防火墙、身份代理或 IP allowlist 限制访问。远程可达的 Admin 应使用 mfa_policy: "required"；这会在第一个管理员尚未绑定验证器时将控制台限制到 MFA 设置流程，完成绑定后才开放其他功能。本机回环访问的开发实例可以保留默认的 optional。

可选：由 Halro 直接加载证书

不使用反向代理时，Halro 可以直接终止 TLS。把公开信任的完整证书链和私钥放入 ./tls，并在 config.yaml 中启用：

server:
  gateway_listen: "0.0.0.0:8080"
  admin_listen: "0.0.0.0:8081"
  metrics_listen: "127.0.0.1:9090"

tls:
  enabled: true
  certificates:
    - cert_file: /etc/halro/tls/fullchain.pem
      key_file: /etc/halro/tls/privkey.pem

admin:
  external_origin: "https://admin.example.com:8081"
  mfa_policy: "required"

将证书目录以只读方式同时挂载给 halro-init 和 halro 服务：

volumes:
  - ./config.yaml:/etc/halro/config.yaml:ro
  - ./tls:/etc/halro/tls:ro

如果使用标准 443 端口通过端口转发访问 Admin，external_origin 不需要写 :8081；它必须与浏览器实际使用的 HTTPS 地址完全一致。证书私钥应保持最小读取权限，不得写入镜像或提交到 Git。更新原路径内的证书内容后，可以在 Linux/macOS 上向 Halro 发送 SIGHUP；更改证书路径或列表仍需重启。完整参数见配置参数参考。

5. 安全交付首次初始化凭据

当 admin.external_origin 非空、Admin 非回环监听，或显式配置 admin.setup_token_file 时，初始化页面要求一次性 Token。使用与目标版本相同的 Halro 二进制生成只读文件：

halro admin setup-token generate \
  --ttl 30m \
  --output /secure/path/setup-token

命令以 0600 排他创建文件，不覆盖已有路径，也不向 stdout、stderr 或日志输出 Token。把文件交给 Secret Manager，或挂载进 Compose：

admin:
  setup_token_file: /run/secrets/halro/setup-token
  setup_token_ttl: 30m

services:
  halro:
    command: ["serve", "--config", "/etc/halro/config.yaml"]
    volumes:
      - ./config.yaml:/etc/halro/config.yaml:ro
      - /secure/path/setup-token:/run/secrets/halro/setup-token:ro

通过组织已有的 Secret 审批通道把信封第一行交给初始化人员；不要授予日志或容器 exec 权限。Token 带绝对过期时间，重启不续期。文件缺失、格式错误或过期时 serve fail-closed，不会回退到日志输出。

无人值守部署改用离线、幂等的 admin bootstrap --if-needed --operation-id ... --password-file ...。管理员创建完成后，先解除工作负载的挂载依赖，再撤销 Secret；已有管理员时 Halro 不再读取 Token 文件。完整 Docker/Kubernetes 状态机、Audit 验证和泄露恢复见生产环境 Admin 初始化与 Secret 生命周期。

Master Key 不能只留在 Docker volume 里

上面的命名卷便于跨平台首次部署，但不是独立备份。丢失 Master Key 后，数据卷和加密备份都不能恢复 Provider 凭据。生产环境更适合使用受控 Secret 挂载或外部 KMS。

Kubernetes

正式 key_slots Bootstrap 流程

面向 Kubernetes/GitOps 的正式安装状态机随 v0.8.3 发布，v0.9.1 镜像同样包含它。该自动化 Job 路径当前只支持 storage.master_key.mode: key_slots：

PVC / 配置 / Secret / 默认拒绝 NetworkPolicy
                    ↓
一次性 Bootstrap Job（init --if-needed → admin bootstrap）
                    ↓
Verification Job（doctor → audit verify）
                    ↓
删除 Job 和 bootstrap Secret，撤销临时 KMS 身份
                    ↓
启动单副本正式 Deployment：halro serve

kubectl -n halro create secret generic halro-admin-bootstrap \
  --from-file=admin-password=/secure/path/admin-password
kubectl -n halro apply -f deploy/kubernetes/halro-bootstrap-job.yaml
kubectl -n halro wait --for=condition=complete \
  job/halro-bootstrap-install-id --timeout=15m
kubectl -n halro delete job halro-bootstrap-install-id --wait=true
kubectl -n halro apply -f deploy/kubernetes/halro-bootstrap-verify-job.yaml
kubectl -n halro wait --for=condition=complete \
  job/halro-bootstrap-verify-install-id --timeout=10m

Bootstrap/Verification Job 与 Runtime 禁止重叠。它们使用独立 ServiceAccount、临时 KMS Lifecycle 身份和 install-only GitOps 生命周期；正式 ServiceAccount 不需要 Secret API、日志或 exec 权限。完整安全约束与失败恢复见生产环境 Admin 初始化与 Secret 生命周期。

v0.9.1：手工 File Master Key 模板

下面使用 GHCR 当前已验收的 v0.9.1 镜像；生产环境应进一步固定为已审核的 manifest digest。它是手工 File Master Key 单节点模板，不是上面新的官方自动化 Bootstrap Job。File Master Key 的自动化生成后外送协议仍待后续评审。

下面给出一个最小、文件模式的单节点模板。数据和 Master Key 分别使用 halro-data、halro-key 两个 PVC，避免一次数据卷故障同时销毁密钥。两个 PVC 仍必须分别做集群外备份；使用 AWS KMS 的生产集群可改用主仓库中的 deploy/kubernetes/halro-aws-kms.yaml 加固模板。

1. 准备配置和命名空间

先下载完整配置，将以下值写入对应字段：

server:
  gateway_listen: "0.0.0.0:8080"
storage:
  data_dir: "/var/lib/halro/data"
  master_key:
    mode: file
    file: "/var/lib/halro-secrets/master.key"

再创建命名空间和配置 Secret：

kubectl create namespace halro
kubectl -n halro create secret generic halro-config \
  --from-file=config.yaml=./config.yaml

2. 创建持久卷并初始化一次

保存为 halro-storage-init.yaml：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: halro-data
  namespace: halro
spec:
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 20Gi
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: halro-key
  namespace: halro
spec:
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 1Gi
---
apiVersion: batch/v1
kind: Job
metadata:
  name: halro-init
  namespace: halro
spec:
  backoffLimit: 0
  template:
    spec:
      restartPolicy: Never
      securityContext:
        runAsNonRoot: true
        runAsUser: 65532
        runAsGroup: 65532
        fsGroup: 65532
      containers:
        - name: init
          image: ghcr.io/akz142857/halro:v0.9.1
          args: ["init", "--config", "/etc/halro/config.yaml"]
          volumeMounts:
            - {name: config, mountPath: /etc/halro, readOnly: true}
            - {name: data, mountPath: /var/lib/halro}
            - {name: key, mountPath: /var/lib/halro-secrets}
      volumes:
        - name: config
          secret: {secretName: halro-config, defaultMode: 0400}
        - name: data
          persistentVolumeClaim: {claimName: halro-data}
        - name: key
          persistentVolumeClaim: {claimName: halro-key}

执行并等待初始化成功：

kubectl apply -f halro-storage-init.yaml
kubectl -n halro wait --for=condition=complete job/halro-init --timeout=120s
kubectl -n halro logs job/halro-init

如果 Job 失败，不要反复删除 Key 或数据重跑。先看日志，确认 PVC 里是全新空目录，或恢复彼此匹配的整套数据与 Key。

3. 把 Master Key 备份到集群外

在启动 Halro 前，使用一个临时、受审核的工具容器只读挂载 halro-key。下面以 BusyBox 为例；受管环境应换成已审核并固定 digest 的内部工具镜像。保存为 halro-key-export.yaml：

apiVersion: v1
kind: Pod
metadata:
  name: halro-key-export
  namespace: halro
spec:
  restartPolicy: Never
  automountServiceAccountToken: false
  securityContext:
    runAsNonRoot: true
    runAsUser: 65532
    runAsGroup: 65532
    fsGroup: 65532
    seccompProfile: {type: RuntimeDefault}
  containers:
    - name: export
      image: busybox:1.37.0
      command: ["sleep", "3600"]
      securityContext:
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        capabilities: {drop: ["ALL"]}
      volumeMounts:
        - {name: key, mountPath: /key, readOnly: true}
  volumes:
    - name: key
      persistentVolumeClaim: {claimName: halro-key}

复制、校验并立刻删除临时 Pod：

kubectl apply -f halro-key-export.yaml
kubectl -n halro wait --for=condition=Ready pod/halro-key-export --timeout=120s
kubectl -n halro cp halro-key-export:/key/master.key ./halro-master.key
chmod 600 ./halro-master.key
test "$(wc -c < ./halro-master.key | tr -d ' ')" -eq 32
kubectl -n halro delete pod halro-key-export

将 halro-master.key 转移到集群外的 Secret 管理或离线介质，并为 halro-key PVC 配置独立快照。只有确认托管副本可恢复后，才继续启动 Deployment。

4. 部署恰好一个副本

保存为 halro.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: halro
  namespace: halro
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels: {app.kubernetes.io/name: halro}
  template:
    metadata:
      labels: {app.kubernetes.io/name: halro}
    spec:
      automountServiceAccountToken: false
      enableServiceLinks: false
      terminationGracePeriodSeconds: 150
      securityContext:
        runAsNonRoot: true
        runAsUser: 65532
        runAsGroup: 65532
        fsGroup: 65532
        seccompProfile: {type: RuntimeDefault}
      containers:
        - name: halro
          image: ghcr.io/akz142857/halro:v0.9.1
          args: ["serve", "--config", "/etc/halro/config.yaml", "-allow-insecure-public-listen"]
          ports:
            - {name: gateway, containerPort: 8080}
            - {name: admin, containerPort: 8081}
          readinessProbe:
            exec:
              command: ["/usr/local/bin/halro", "healthcheck", "--url", "http://127.0.0.1:8080/health/ready"]
            periodSeconds: 5
            failureThreshold: 12
          livenessProbe:
            exec:
              command: ["/usr/local/bin/halro", "healthcheck", "--url", "http://127.0.0.1:8080/health/live"]
            periodSeconds: 10
            failureThreshold: 6
          resources:
            requests: {cpu: 100m, memory: 256Mi}
            limits: {memory: 1Gi}
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities: {drop: ["ALL"]}
          volumeMounts:
            - {name: config, mountPath: /etc/halro, readOnly: true}
            - {name: data, mountPath: /var/lib/halro}
            - {name: key, mountPath: /var/lib/halro-secrets, readOnly: true}
            - {name: tmp, mountPath: /tmp}
      volumes:
        - name: config
          secret: {secretName: halro-config, defaultMode: 0400}
        - name: data
          persistentVolumeClaim: {claimName: halro-data}
        - name: key
          persistentVolumeClaim: {claimName: halro-key}
        - name: tmp
          emptyDir: {sizeLimit: 64Mi}
---
apiVersion: v1
kind: Service
metadata:
  name: halro
  namespace: halro
spec:
  type: ClusterIP
  selector: {app.kubernetes.io/name: halro}
  ports:
    - {name: gateway, port: 8080, targetPort: gateway}

应用并检查：

kubectl apply -f halro.yaml
kubectl -n halro rollout status deployment/halro
kubectl -n halro get pods
kubectl -n halro logs deployment/halro

终端 A 转发 Gateway：

kubectl -n halro port-forward service/halro 8080:8080

终端 B 转发 Admin：

kubectl -n halro port-forward deployment/halro 8081:8081

在浏览器打开 http://127.0.0.1:8081/admin/setup；用完即停止 Admin 端口转发，不要把 Admin 端口做成公开 Service。

示例的 Service 只适合受控集群内部访问，不应直接接公网 Ingress。正式上线前应在 Ingress / Gateway 层终止 TLS、正确设置可信代理网段，并另外规划 Admin 和 Metrics 的受限入口。把镜像固定为审核过的 digest，例如 ghcr.io/akz142857/halro@sha256:...。

首次配置与验收

服务启动后，在管理后台依次创建：

Credential → Provider → Deployment → Route → Project → Gateway Key

这条链路中的模型发现、能力证据、价格版本、Policy、Key Scope 和负向验收不能省略。按 首次配置 Admin Console逐步完成，再回到这里检查部署层门禁。

Gateway Key 只显示一次，立即转存到应用的 Secret 管理系统。然后检查就绪端点：

curl -fsS http://127.0.0.1:8080/health/ready

配置好一个公开模型别名后，用新 Key 发请求：

export HALRO_GATEWAY_KEY='gw_...'
curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chat",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "你好"}]
  }'

上线前至少再完成四件事：固定发布版本或镜像 digest；配置 TLS 和网络访问控制；独立备份 Master Key；停机执行一次加密备份、校验和隔离恢复演练。