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

- 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]>
2026-05-24 22:59:30 +08:00
parent b139ff3a3a
commit 72ab8e95bc
1 changed files with 129 additions and 145 deletions
@@ -6,7 +6,22 @@

 ---

-## 服务端部署（在服务器上执行）
+## 目录
+
+- [服务端部署](#服务端部署)
+- [客户端配置](#客户端配置)
+  - [安装 CLI](#安装-cli)
+  - [连接 Hub](#连接-hub)
+  - [启动 AI 会话](#启动-ai-会话)
+- [开机自启 Runner](#开机自启-runner)
+- [使用指南](#使用指南)
+- [参考](#参考)
+
+---
+
+## 服务端部署
+
+在服务器上执行以下步骤。

 ### 1. 准备

@@ -41,7 +56,7 @@ services:
 docker compose up -d
 ```

-### 4. 查看日志（确认启动成功）
+### 4. 查看日志

 ```bash
 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
-npm install -g @twsxtd/hapi --registry=https://registry.npmjs.org
-# 或
-brew install tiann/tap/hapi
-```
+`hapi auth login` 只录入 token，服务器地址仍需单独配置。

-### 2. 配置连接 Hub
-
-> `hapi auth login` 只录入 token，服务器地址仍需单独配置。
-
-**方式一：配置文件（推荐）**
+**推荐方式：配置文件**

 编辑 `~/.hapi/settings.json`：

@@ -86,88 +94,72 @@ brew install tiann/tap/hapi

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

-**方式二：交互式录入 token**
+<details>
+<summary>其他方式：交互式录入 / 环境变量</summary>
+
+**交互式录入 token**

 ```bash
 hapi auth login
 ```

-按提示粘贴 CLI_API_TOKEN 即可，Token 自动保存到 settings.json。  
-但 `HAPI_API_URL` 仍需通过方式一写入 settings.json 或通过方式三设置环境变量。
+按提示粘贴 CLI_API_TOKEN 即可，Token 自动保存到 settings.json。但 `HAPI_API_URL` 仍需通过配置文件或环境变量设置。

-**方式三：环境变量**
-
-<details>
-<summary>Windows (PowerShell)</summary>
+**环境变量**

+Windows (PowerShell):
 ```powershell
 $env:HAPI_API_URL="http://服务器IP:3006"
 $env:CLI_API_TOKEN="你在 docker-compose.yml 里填的令牌"
 ```
+> 将以上加入 `$PROFILE` 避免重复设置。

-> 将以上两行加入 `$PROFILE` 避免重复设置：
-> ```powershell
-> notepad $PROFILE
-> ```
-</details>
-
-<details>
-<summary>Windows (CMD)</summary>
-
+Windows (CMD):
 ```cmd
 set HAPI_API_URL=http://服务器IP:3006
 set CLI_API_TOKEN=你在 docker-compose.yml 里填的令牌
 ```
-</details>
-
-<details>
-<summary>macOS / Linux</summary>

+macOS / Linux:
 ```bash
 export HAPI_API_URL="http://服务器IP:3006"
 export CLI_API_TOKEN="你在 docker-compose.yml 里填的令牌"
 ```
+> 建议写入 `~/.bashrc` 或 `~/.zshrc`。

-> 建议将这两行写入 `~/.bashrc` 或 `~/.zshrc` 避免重复设置。
 </details>

-其他认证命令：
+其他命令：

 ```bash
-hapi auth status   # 查看当前登录状态
+hapi auth status   # 查看登录状态
 hapi auth logout   # 退出登录
 ```

-### 3. 启动 AI 会话
+### 启动 AI 会话

 ```bash
-# Claude Code
-hapi
-
-# Codex
-hapi codex
-
-# Cursor Agent
-hapi cursor
-
-# Gemini
-hapi gemini
-
-# OpenCode
-hapi opencode
+hapi        # Claude Code
+hapi codex  # Codex
+hapi cursor # Cursor Agent
+hapi gemini # Gemini
+hapi opencode # OpenCode
 ```

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

 ---

-## Windows 开机自启 Runner（可选）
+## 开机自启 Runner

-如果你希望每次登录 Windows 后 **Runner 自动在后台启动**（无需保持终端打开，Web 端可随时创建新会话），可以使用以下一键脚本：
+Runner 在后台运行后，Web 端可随时创建新会话，无需保持终端打开。

-### 一键安装脚本
+### Windows

-在 PowerShell 中执行（管理员权限**不需要**，普通用户权限即可）：
+<details>
+<summary>一键安装脚本（点击展开）</summary>
+
+在 PowerShell 中执行（普通用户权限即可）：

 ```powershell
 # 检查 hapi CLI 是否已安装
@@ -182,108 +174,108 @@ $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
-    Write-Host "配置路径: $settingsPath" -ForegroundColor Yellow
 }

 # 如果任务已存在，先删除
 $existing = Get-ScheduledTask -TaskName "HAPI Runner" -ErrorAction SilentlyContinue
 if ($existing) {
-    Write-Host "[信息] 发现已存在的 HAPI Runner 任务，正在重新创建..." -ForegroundColor Cyan
+    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

-# 创建操作：隐藏窗口启动 runner
-$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 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
-}
+Register-ScheduledTask -TaskName "HAPI Runner" -Trigger $trigger -Action $action -Principal $principal -Settings $settings -Force | Out-Null
+Write-Host "[成功] HAPI Runner 计划任务已创建！" -ForegroundColor Green
 ```

-### 卸载/移除任务
+**卸载**

 ```powershell
 Unregister-ScheduledTask -TaskName "HAPI Runner" -Confirm:$false
-Write-Host "HAPI Runner 计划任务已删除。"
 ```

-### 手动控制
+**手动控制**

 ```powershell
-# 立即启动
-Start-ScheduledTask -TaskName "HAPI Runner"
-
-# 查看状态
-Get-ScheduledTask -TaskName "HAPI Runner" | Get-ScheduledTaskInfo
-
-# 停止任务（会停止 runner 进程）
-Stop-ScheduledTask -TaskName "HAPI Runner"
+Start-ScheduledTask -TaskName "HAPI Runner"     # 启动
+Get-ScheduledTask -TaskName "HAPI Runner" | Get-ScheduledTaskInfo  # 查看状态
+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" 横幅 → 点击安装。  
-**iOS (Safari):** 分享按钮 → "添加到主屏幕"。  
-**Desktop (Chrome/Edge):** 地址栏安装图标 (⊕)。
+[Install]
+WantedBy=default.target
+EOF

-登录后即可在手机上：
+# 2. 启用并启动
+systemctl --user daemon-reload
+systemctl --user enable hapi-runner.service
+systemctl --user start hapi-runner.service

- 查看所有活动会话
- 发送消息给 AI
- 审批工具调用请求（文件读写、命令执行等）
- 浏览文件差异
+# 3. 查看状态
+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
 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 登录使用 |
 | `HAPI_PUBLIC_URL` | 否 | - | Hub 公网地址（用于 Telegram 等回调） |
-| `CORS_ORIGINS` | 否 | `*` | 允许的 CORS 域名。反向代理（如 nginx）场景下 WebSocket 终端必设 `*` |
+| `CORS_ORIGINS` | 否 | `*` | 允许的 CORS 域名。反向代理场景下 WebSocket 终端必设 `*` |
 | `TZ` | 否 | `Asia/Shanghai` | 时区 |

-## 持久化数据
+### 持久化数据

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

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

-## 本地构建（可选）
+### 本地构建（可选）

 ```bash
 git clone https://github.com/arkylin/Hapi-Docker.git