HAPI Hub Docker 部署

一键 Docker 部署 HAPI Hub，在服务器上运行 Hub，本地开发机通过 CLI 连接，手机通过 Web/PWA 远程控制。

支持 Claude Code / Codex / Cursor / Gemini / OpenCode。

---

目录

• 快速开始（一键安装）
• 服务端部署
• 客户端配置
  • 安装 CLI
  • 连接 Hub
  • 启动 AI 会话
• 开机自启 Runner
• 构建方式
• 使用指南
• 参考

---

快速开始（一键安装）

一键完成全部环境搭建：Node.js v22 + HAPI CLI（多来源可选）+ Hub Docker + 开机自启。

Linux

curl -fsSL https://raw.githubusercontent.com/arkylin/Hapi-Docker/main/scripts/install.sh | sudo bash

Windows

以管理员身份打开 PowerShell：

irm https://raw.githubusercontent.com/arkylin/Hapi-Docker/main/scripts/install.ps1 | iex

脚本支持多来源安装（npm / 官方 GitHub Release / 本仓库 GitHub Release）、版本检测、自动升级。详见 scripts/README.md。

---

服务端部署

在服务器上执行以下步骤。

1. 准备

mkdir -p /opt/hapi-hub && cd /opt/hapi-hub

2. 创建 docker-compose.yml

services:
  hapi-hub:
    # image: ghcr.io/arkylin/hapi-docker:latest  # 默认：从 npm 安装
    image: ghcr.io/arkylin/hapi-docker:latest     # 可选：origin（官方仓库构建）、self（fork 构建）
    container_name: hapi-hub
    restart: unless-stopped
    ports:
      - "3006:3006"
    volumes:
      - ./hapi-data:/root/.hapi
    environment:
      - CLI_API_TOKEN=这里填一个只有你知道的随机字符串
      - HAPI_LISTEN_HOST=0.0.0.0
      - HAPI_LISTEN_PORT=3006
      - CORS_ORIGINS=*

如果使用 nginx 反向代理，必须设置 CORS_ORIGINS=*，否则 Web 终端（Socket.IO WebSocket）会因 CORS 校验失败返回 403。

3. 启动

docker compose up -d

4. 查看日志

docker compose logs -f

启动后浏览器访问 http://服务器IP:3006 即可看到 HAPI Web 界面。

---

客户端配置

在本地电脑上执行。

安装 CLI

平台	命令
Windows / macOS / Linux (npm)	npm install -g @twsxtd/hapi --registry=https://registry.npmjs.org
macOS (brew)	brew install tiann/tap/hapi

连接 Hub

hapi auth login 只录入 token，服务器地址仍需单独配置。

推荐方式：配置文件

编辑 ~/.hapi/settings.json：

{
  "apiUrl": "http://服务器IP:3006",
  "cliApiToken": "你在 docker-compose.yml 里填的令牌"
}

然后用 hapi auth login 验证（或直接保存后生效）。

其他方式：交互式录入 / 环境变量

交互式录入 token

hapi auth login

按提示粘贴 CLI_API_TOKEN 即可，Token 自动保存到 settings.json。但 HAPI_API_URL 仍需通过配置文件或环境变量设置。

环境变量

Windows (PowerShell):

$env:HAPI_API_URL="http://服务器IP:3006"
$env:CLI_API_TOKEN="你在 docker-compose.yml 里填的令牌"

将以上加入 $PROFILE 避免重复设置。

Windows (CMD):

set HAPI_API_URL=http://服务器IP:3006
set CLI_API_TOKEN=你在 docker-compose.yml 里填的令牌

macOS / Linux:

export HAPI_API_URL="http://服务器IP:3006"
export CLI_API_TOKEN="你在 docker-compose.yml 里填的令牌"

建议写入 ~/.bashrc 或 ~/.zshrc。

其他命令：

hapi auth status   # 查看登录状态
hapi auth logout   # 退出登录

启动 AI 会话

hapi        # Claude Code
hapi codex  # Codex
hapi cursor # Cursor Agent
hapi gemini # Gemini
hapi opencode # OpenCode

会话启动后会在 Hub 注册，Web 端和手机上都能看到。

---

开机自启 Runner

Runner 在后台运行后，Web 端可随时创建新会话，无需保持终端打开。

Windows

一键安装脚本（点击展开）

在 PowerShell 中执行（普通用户权限即可）：

# 检查 hapi CLI 是否已安装
$hapi = Get-Command "hapi" -ErrorAction SilentlyContinue
if (-not $hapi) {
    Write-Host "[错误] 未找到 hapi CLI，请先执行：npm install -g @twsxtd/hapi" -ForegroundColor Red
    exit 1
}

# 检查 settings.json 是否已配置
$hapiHome = Join-Path $env:USERPROFILE ".hapi"
$settingsPath = Join-Path $hapiHome "settings.json"
if (-not (Test-Path $settingsPath)) {
    Write-Host "[警告] 未找到 ~/.hapi/settings.json，请先配置 Hub 连接地址和 Token" -ForegroundColor Yellow
}

# 如果任务已存在，先删除
$existing = Get-ScheduledTask -TaskName "HAPI Runner" -ErrorAction SilentlyContinue
if ($existing) {
    Write-Host "[信息] 发现已存在的任务，正在重新创建..." -ForegroundColor Cyan
    Unregister-ScheduledTask -TaskName "HAPI Runner" -Confirm:$false
}

$trigger = New-ScheduledTaskTrigger -AtLogon
$action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument '-WindowStyle Hidden -Command "hapi runner start"'
$principal = New-ScheduledTaskPrincipal -UserId $env:USERNAME -LogonType Interactive
$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable -ExecutionTimeLimit (New-TimeSpan -Hours 72) -MultipleInstances IgnoreNew

Register-ScheduledTask -TaskName "HAPI Runner" -Trigger $trigger -Action $action -Principal $principal -Settings $settings -Force | Out-Null
Write-Host "[成功] HAPI Runner 计划任务已创建！" -ForegroundColor Green

卸载

Unregister-ScheduledTask -TaskName "HAPI Runner" -Confirm:$false

手动控制

Start-ScheduledTask -TaskName "HAPI Runner"     # 启动
Get-ScheduledTask -TaskName "HAPI Runner" | Get-ScheduledTaskInfo  # 查看状态
Stop-ScheduledTask -TaskName "HAPI Runner"      # 停止

Linux

systemd 用户服务（点击展开）

# 1. 创建服务文件
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/hapi-runner.service << 'EOF'
[Unit]
Description=HAPI Runner
After=network.target

[Service]
Type=forking
ExecStart=/usr/bin/hapi runner start
Restart=always
RestartSec=5
TimeoutStopSec=10

[Install]
WantedBy=default.target
EOF

# 2. 启用并启动
systemctl --user daemon-reload
systemctl --user enable hapi-runner.service
systemctl --user start hapi-runner.service

# 3. 查看状态
systemctl --user status hapi-runner.service

如果 hapi 不在 /usr/bin/hapi，请修改为实际路径（如 /home/用户名/.local/bin/hapi）。

手动控制

systemctl --user start hapi-runner.service    # 启动
systemctl --user stop hapi-runner.service     # 停止
systemctl --user restart hapi-runner.service  # 重启
systemctl --user disable hapi-runner.service  # 禁用开机自启

---

构建方式

以下方式按复杂度从低到高排列，日常使用推荐默认方式。

默认方式（npm）

根目录 Dockerfile 从 npm 安装 @twsxtd/hapi，无需编译：

docker compose up -d

预构建镜像

CI 自动推送的镜像，可直接替换 docker-compose.yml 中的 image：

标签	来源	说明
latest	npm registry	与默认方式等价
origin	tiann/hapi@main	官方仓库最新 main 分支编译
self	arkylin/hapi@self	Fork 的 self 分支编译

services:
  hapi-hub:
    image: ghcr.io/arkylin/hapi-docker:origin
    # ... 其余配置不变

本地构建 origin

从官方仓库 tiann/hapi@main 克隆并编译：

cd origin
./build.sh

编译完成后生成本地镜像 hapi:origin。

本地构建 self

从本地 ../hapi（需提前克隆 arkylin/hapi 的 self 分支并编译）复制二进制：

cd hapi
bun install
bun run build:single-exe

cd ../Hapi-Docker/self
./build.sh

编译完成后生成本地镜像 hapi:self。

CI 自动构建

使用统一的 GitHub Actions workflow（.github/workflows/build-and-release.yml），手动触发时填写参数：

参数	说明	示例
repository	源码仓库	tiann/hapi、arkylin/hapi
ref	分支 / tag / commit	main、self、v1.0.0
docker_tag	Docker 镜像标签	origin、self
release_tag	二进制发布标签（留空则跳过）	v1.0.0-origin
build_docker	是否构建并推送 Docker 镜像	true / false
release_binaries	是否发布二进制	true / false

---

使用指南

手机 / 网页端访问

• Web: 浏览器打开 http://服务器IP:3006，输入 CLI_API_TOKEN 登录。
• PWA: 浏览器地址栏点击安装图标（Chrome/Edge）或添加到主屏幕（iOS Safari / Android Chrome）。

登录后可以查看活动会话、发送消息、审批工具调用、浏览文件差异。

无缝切换（Seamless Handoff）

操作	效果
本地键入	终端直接输入
手机收到消息	自动切换到远程模式，终端显示 "Remote mode"
终端按两次空格	切回本地模式

同一会话，同一状态，无需重启。

在 Hub 容器内启动 Runner

docker exec hapi-hub hapi runner start --foreground

启动后 Web 界面的 "Machines" 列表会出现这台机器，点击即可远程创建新会话。

---

参考

环境变量

变量	必填	默认值	说明
CLI_API_TOKEN	是	-	认证令牌，CLI 和 Web 登录使用
HAPI_PUBLIC_URL	否	-	Hub 公网地址（用于 Telegram 等回调）
CORS_ORIGINS	否	*	允许的 CORS 域名。反向代理场景下 WebSocket 终端必设 *
TZ	否	Asia/Shanghai	时区

持久化数据

./hapi-data/ 挂载到容器内 /root/.hapi/：

• settings.json — 配置文件
• hapi.db — SQLite 数据库

本地克隆仓库（可选）

git clone https://github.com/arkylin/Hapi-Docker.git
cd Hapi-Docker
# 编辑 docker-compose.yml
docker compose up -d