i/Hapi-Docker
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: restructure README and add Linux systemd auto-start guide

Browse Source 
- Add table of contents for quick navigation
- Collapse long Windows/Linux scripts behind <details>
- Consolidate client setup into cleaner sections
- Add systemd user service instructions for Linux
- Move reference data (env vars, persistence) to the bottom

via [HAPI](https://hapi.run)

Co-Authored-By: HAPI <[email protected]>
This commit is contained in:
i
2026-05-24 22:59:30 +08:00
co-authored by HAPI
parent b139ff3a3a
commit 72ab8e95bc
1 changed files with 129 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+128 -144
View File
@@ -6,7 +6,22 @@
--- ---
## 服务端部署（在服务器上执行） ## 目录
- [服务端部署](#服务端部署)
- [客户端配置](#客户端配置)
- [安装 CLI](#安装-cli)
- [连接 Hub](#连接-hub)
- [启动 AI 会话](#启动-ai-会话)
- [开机自启 Runner](#开机自启-runner)
- [使用指南](#使用指南)
- [参考](#参考)
---
## 服务端部署
在服务器上执行以下步骤。
### 1. 准备 ### 1. 准备
@@ -41,7 +56,7 @@ services:
docker compose up -d docker compose up -d
``` ```
### 4. 查看日志（确认启动成功） ### 4. 查看日志
```bash ```bash
docker compose logs -f docker compose logs -f
@@ -51,29 +66,22 @@ docker compose logs -f
--- ---
## 本地开发机配置（在本地电脑上执行） ## 客户端配置
### 1. 安装 HAPI CLI 在本地电脑上执行。
**Windows (npm):** ### 安装 CLI
```powershell | 平台 | 命令 |
npm install -g @twsxtd/hapi --registry=https://registry.npmjs.org |------|------|
``` | Windows / macOS / Linux (npm) | `npm install -g @twsxtd/hapi --registry=https://registry.npmjs.org` |
| macOS (brew) | `brew install tiann/tap/hapi` |
**macOS / Linux:** ### 连接 Hub
```bash `hapi auth login` 只录入 token，服务器地址仍需单独配置。
npm install -g @twsxtd/hapi --registry=https://registry.npmjs.org
# 或
brew install tiann/tap/hapi
```
### 2. 配置连接 Hub **推荐方式：配置文件**
> `hapi auth login` 只录入 token，服务器地址仍需单独配置。
**方式一：配置文件（推荐）**
编辑 `~/.hapi/settings.json`： 编辑 `~/.hapi/settings.json`：
@@ -86,88 +94,72 @@ brew install tiann/tap/hapi
然后用 `hapi auth login` 验证（或直接保存后生效）。 然后用 `hapi auth login` 验证（或直接保存后生效）。
**方式二：交互式录入 token** <details>
<summary>其他方式：交互式录入 / 环境变量</summary>
**交互式录入 token**
```bash ```bash
hapi auth login hapi auth login
``` ```
按提示粘贴 CLI_API_TOKEN 即可，Token 自动保存到 settings.json。 按提示粘贴 CLI_API_TOKEN 即可，Token 自动保存到 settings.json。但 `HAPI_API_URL` 仍需通过配置文件或环境变量设置。
但 `HAPI_API_URL` 仍需通过方式一写入 settings.json 或通过方式三设置环境变量。
**方式三：环境变量** **环境变量**
<details>
<summary>Windows (PowerShell)</summary>
Windows (PowerShell):
```powershell ```powershell
$env:HAPI_API_URL="http://服务器IP:3006" $env:HAPI_API_URL="http://服务器IP:3006"
$env:CLI_API_TOKEN="你在 docker-compose.yml 里填的令牌" $env:CLI_API_TOKEN="你在 docker-compose.yml 里填的令牌"
``` ```
> 将以上加入 `$PROFILE` 避免重复设置。
> 将以上两行加入 `$PROFILE` 避免重复设置： Windows (CMD):
> ```powershell
> notepad $PROFILE
> ```
</details>
<details>
<summary>Windows (CMD)</summary>
```cmd ```cmd
set HAPI_API_URL=http://服务器IP:3006 set HAPI_API_URL=http://服务器IP:3006
set CLI_API_TOKEN=你在 docker-compose.yml 里填的令牌 set CLI_API_TOKEN=你在 docker-compose.yml 里填的令牌
``` ```
</details>
<details>
<summary>macOS / Linux</summary>
macOS / Linux:
```bash ```bash
export HAPI_API_URL="http://服务器IP:3006" export HAPI_API_URL="http://服务器IP:3006"
export CLI_API_TOKEN="你在 docker-compose.yml 里填的令牌" export CLI_API_TOKEN="你在 docker-compose.yml 里填的令牌"
``` ```
> 建议写入 `~/.bashrc` 或 `~/.zshrc`。
> 建议将这两行写入 `~/.bashrc` 或 `~/.zshrc` 避免重复设置。
</details> </details>
其他认证命令： 其他命令：
```bash ```bash
hapi auth status # 查看当前登录状态 hapi auth status # 查看登录状态
hapi auth logout # 退出登录 hapi auth logout # 退出登录
``` ```
### 3. 启动 AI 会话 ### 启动 AI 会话
```bash ```bash
# Claude Code hapi # Claude Code
hapi hapi codex # Codex
hapi cursor # Cursor Agent
# Codex hapi gemini # Gemini
hapi codex hapi opencode # OpenCode
# Cursor Agent
hapi cursor
# Gemini
hapi gemini
# OpenCode
hapi opencode
``` ```
会话启动后，会在 Hub 注册，Web 端和手机上都能看到。 会话启动后会在 Hub 注册，Web 端和手机上都能看到。
--- ---
## Windows 开机自启 Runner（可选） ## 开机自启 Runner
如果你希望每次登录 Windows 后 **Runner 自动在后台启动**（无需保持终端打开，Web 端可随时创建新会话），可以使用以下一键脚本： Runner 在后台运行后，Web 端可随时创建新会话，无需保持终端打开。
### 一键安装脚本 ### Windows
在 PowerShell 中执行（管理员权限**不需要**，普通用户权限即可）： <details>
<summary>一键安装脚本（点击展开）</summary>
在 PowerShell 中执行（普通用户权限即可）：
```powershell ```powershell
# 检查 hapi CLI 是否已安装 # 检查 hapi CLI 是否已安装
@@ -182,108 +174,108 @@ $hapiHome = Join-Path $env:USERPROFILE ".hapi"
$settingsPath = Join-Path $hapiHome "settings.json" $settingsPath = Join-Path $hapiHome "settings.json"
if (-not (Test-Path $settingsPath)) { if (-not (Test-Path $settingsPath)) {
Write-Host "[警告] 未找到 ~/.hapi/settings.json，请先配置 Hub 连接地址和 Token" -ForegroundColor Yellow Write-Host "[警告] 未找到 ~/.hapi/settings.json，请先配置 Hub 连接地址和 Token" -ForegroundColor Yellow
Write-Host "配置路径: $settingsPath" -ForegroundColor Yellow
} }
# 如果任务已存在，先删除 # 如果任务已存在，先删除
$existing = Get-ScheduledTask -TaskName "HAPI Runner" -ErrorAction SilentlyContinue $existing = Get-ScheduledTask -TaskName "HAPI Runner" -ErrorAction SilentlyContinue
if ($existing) { if ($existing) {
Write-Host "[信息] 发现已存在的 HAPI Runner 任务，正在重新创建..." -ForegroundColor Cyan Write-Host "[信息] 发现已存在的任务，正在重新创建..." -ForegroundColor Cyan
Unregister-ScheduledTask -TaskName "HAPI Runner" -Confirm:$false Unregister-ScheduledTask -TaskName "HAPI Runner" -Confirm:$false
} }
# 创建触发器：用户登录时触发
$trigger = New-ScheduledTaskTrigger -Logon $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
# 创建操作：隐藏窗口启动 runner Register-ScheduledTask -TaskName "HAPI Runner" -Trigger $trigger -Action $action -Principal $principal -Settings $settings -Force | Out-Null
$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
# 验证
$task = Get-ScheduledTask -TaskName "HAPI Runner" -ErrorAction SilentlyContinue
if ($task) {
Write-Host "[成功] HAPI Runner 计划任务已创建！" -ForegroundColor Green Write-Host "[成功] HAPI Runner 计划任务已创建！" -ForegroundColor Green
Write-Host " 任务名: HAPI Runner" -ForegroundColor Gray
Write-Host " 触发器: 用户登录时自动启动" -ForegroundColor Gray
Write-Host " 命令 : powershell -WindowStyle Hidden -Command `"hapi runner start`"" -ForegroundColor Gray
Write-Host " 执行 : $env:USERNAME" -ForegroundColor Gray
Write-Host "" -ForegroundColor Gray
Write-Host "下次登录 Windows 时 Runner 将自动启动。" -ForegroundColor Green
Write-Host "你也可以手动启动: Start-ScheduledTask -TaskName `"HAPI Runner`"" -ForegroundColor DarkGray
} else {
Write-Host "[失败] 任务创建失败，请检查权限或手动排查。" -ForegroundColor Red
}
``` ```
### 卸载/移除任务 **卸载**
```powershell ```powershell
Unregister-ScheduledTask -TaskName "HAPI Runner" -Confirm:$false Unregister-ScheduledTask -TaskName "HAPI Runner" -Confirm:$false
Write-Host "HAPI Runner 计划任务已删除。"
``` ```
### 手动控制 **手动控制**
```powershell ```powershell
# 立即启动 Start-ScheduledTask -TaskName "HAPI Runner" # 启动
Start-ScheduledTask -TaskName "HAPI Runner" Get-ScheduledTask -TaskName "HAPI Runner" | Get-ScheduledTaskInfo # 查看状态
Stop-ScheduledTask -TaskName "HAPI Runner" # 停止
# 查看状态
Get-ScheduledTask -TaskName "HAPI Runner" | Get-ScheduledTaskInfo
# 停止任务（会停止 runner 进程）
Stop-ScheduledTask -TaskName "HAPI Runner"
``` ```
--- </details>
## 手机 / 网页端访问 ### Linux
### Web <details>
<summary>systemd 用户服务（点击展开）</summary>
浏览器打开 `http://服务器IP:3006`，输入 `CLI_API_TOKEN` 登录。 ```bash
# 1. 创建服务文件
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/hapi-runner.service << 'EOF'
[Unit]
Description=HAPI Runner
After=network.target
### PWA（添加到桌面） [Service]
Type=forking
ExecStart=/usr/bin/hapi runner start
Restart=always
RestartSec=5
TimeoutStopSec=10
**Android (Chrome):** 底部弹出 "Install HAPI" 横幅 → 点击安装。 [Install]
**iOS (Safari):** 分享按钮 → "添加到主屏幕"。 WantedBy=default.target
**Desktop (Chrome/Edge):** 地址栏安装图标 (⊕)。 EOF
登录后即可在手机上： # 2. 启用并启动
systemctl --user daemon-reload
systemctl --user enable hapi-runner.service
systemctl --user start hapi-runner.service
- 查看所有活动会话 # 3. 查看状态
- 发送消息给 AI systemctl --user status hapi-runner.service
- 审批工具调用请求（文件读写、命令执行等） ```
- 浏览文件差异
> 如果 hapi 不在 `/usr/bin/hapi`，请修改为实际路径（如 `/home/用户名/.local/bin/hapi`）。
**手动控制**
```bash
systemctl --user start hapi-runner.service # 启动
systemctl --user stop hapi-runner.service # 停止
systemctl --user restart hapi-runner.service # 重启
systemctl --user disable hapi-runner.service # 禁用开机自启
```
</details>
--- ---
## Runner 模式（远程拉起新会话） ## 使用指南
在 Hub 容器内启动 Runner，就可以从 Web 端直接创建新会话，无需保持终端打开： ### 手机 / 网页端访问
- **Web**: 浏览器打开 `http://服务器IP:3006`，输入 `CLI_API_TOKEN` 登录。
- **PWA**: 浏览器地址栏点击安装图标（Chrome/Edge）或添加到主屏幕（iOS Safari / Android Chrome）。
登录后可以查看活动会话、发送消息、审批工具调用、浏览文件差异。
### 无缝切换（Seamless Handoff）
| 操作 | 效果 |
|------|------|
| 本地键入 | 终端直接输入 |
| 手机收到消息 | 自动切换到远程模式，终端显示 "Remote mode" |
| 终端按两次空格 | 切回本地模式 |
同一会话，同一状态，无需重启。
### 在 Hub 容器内启动 Runner
```bash ```bash
docker exec hapi-hub hapi runner start --foreground docker exec hapi-hub hapi runner start --foreground
@@ -293,33 +285,25 @@ docker exec hapi-hub hapi runner start --foreground
--- ---
## Seamless Handoff（无缝切换） ## 参考
- **本地键入** = 终端直接输入 ### 环境变量
- **手机收到消息** = 自动切换到远程模式，终端显示 "Remote mode"
- **终端按两次空格** = 切回本地模式
同一会话，同一状态，无需重启。
---
## 环境变量
| 变量 | 必填 | 默认值 | 说明 | | 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------| |------|------|--------|------|
| `CLI_API_TOKEN` | 是 | - | 认证令牌，CLI 和 Web 登录使用 | | `CLI_API_TOKEN` | 是 | - | 认证令牌，CLI 和 Web 登录使用 |
| `HAPI_PUBLIC_URL` | 否 | - | Hub 公网地址（用于 Telegram 等回调） | | `HAPI_PUBLIC_URL` | 否 | - | Hub 公网地址（用于 Telegram 等回调） |
| `CORS_ORIGINS` | 否 | `*` | 允许的 CORS 域名。反向代理（如 nginx）场景下 WebSocket 终端必设 `*` | | `CORS_ORIGINS` | 否 | `*` | 允许的 CORS 域名。反向代理场景下 WebSocket 终端必设 `*` |
| `TZ` | 否 | `Asia/Shanghai` | 时区 | | `TZ` | 否 | `Asia/Shanghai` | 时区 |
## 持久化数据 ### 持久化数据
`./hapi-data/` 挂载到容器内 `/root/.hapi/`： `./hapi-data/` 挂载到容器内 `/root/.hapi/`：
- `settings.json` — 配置文件 - `settings.json` — 配置文件
- `hapi.db` — SQLite 数据库 - `hapi.db` — SQLite 数据库
## 本地构建（可选） ### 本地构建（可选）
```bash ```bash
git clone https://github.com/arkylin/Hapi-Docker.git git clone https://github.com/arkylin/Hapi-Docker.git