HAPI Hub Docker 部署

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

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

---

目录

• 服务端部署
• 客户端配置
  • 安装 CLI
  • 连接 Hub
  • 启动 AI 会话
• 开机自启 Runner
• 使用指南
• 参考

---

服务端部署

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

1. 准备

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

2. 创建 docker-compose.yml

services:
  hapi-hub:
    image: ghcr.io/arkylin/hapi-docker:latest
    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 -Logon
$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  # 禁用开机自启

---

使用指南

手机 / 网页端访问

• 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
# 编辑 .env
docker compose up -d