这份详细的部署教程将指引您完成 Happier 的安装与配置。Happier 是一个端到端加密、可自托管的 AI 编程助手客户端，支持 Claude Code、Codex 等多种 AI 编程代理 。

整个部署流程分为四个主要步骤：

  1. 安装客户端与 CLI：在您的设备和电脑上安装 Happier。
  2. 部署自托管服务器：选择一种方式部署您自己的 Happier 后端服务器。
  3. 连接与认证：将您的客户端和 CLI 连接到自托管服务器。
  4. 开始使用：使用 happier 命令启动 AI 编程会话。

📥 第一步：安装客户端与 CLI

您需要在控制端（如手机） 和工作端（电脑） 分别安装对应的软件。

控制端 (手机/平板)

  • iOS: 在 App Store 搜索 Happier 下载。
  • Android: 可从 Google Play（需加入私人测试）或直接下载 APK 安装 。

工作端 (你的开发电脑)
在电脑的终端中执行以下命令安装 Happier CLI：

1
2
3
4
5
# macOS / Linux
curl -fsSL https://happier.dev/install | bash

# Windows (PowerShell)
iwr https://happier.dev/install.ps1 -useb | iex

如果你偏好使用 npm，也可以运行 npm install -g @happier-dev/cli 。

⚙️ 第二步：部署自托管服务器（三选一）

这是实现完全控制和私有化部署的核心。官方文档提供了三种推荐方式，您可以根据自己的技术背景和需求选择一种。

1. 使用 Docker 部署（推荐，最通用）
Docker 方式便于管理和升级，适合大多数用户。通过 Docker Compose 可以快速启动一个生产可用的服务器 。

示例 docker-compose.yml 文件 (使用 PostgreSQL):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
services:
  relay-server:
    image: happierdev/relay-server:preview # 或 stable
    container_name: happier-server
    restart: unless-stopped
    ports:
      - "3005:3005" # 将宿主机 3005 端口映射到容器
    environment:
      - HAPPIER_PUBLIC_SERVER_URL=https://your-domain.com # 替换为你的公开访问地址
      - HAPPIER_WEBAPP_URL=https://your-domain.com       # 同上
      - HANDY_MASTER_SECRET=your-strong-master-secret    # 必须设置一个强密钥
      - DATABASE_URL=postgresql://user:password@db:5432/happier # PostgreSQL 连接串
      - HAPPIER_DB_PROVIDER=postgres
      # ... 其他配置，如 S3 存储等，参考文档 [citation:2]
    depends_on:
      - db
    volumes:
      - ./data:/data # 持久化数据

  db:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: happier
    volumes:
      - ./postgres_data:/var/lib/postgresql/data

说明：

  • 将 your-domain.com 替换为您的实际域名或 IP。
  • 必须设置 HANDY_MASTER_SECRET 环境变量 。
  • 更多详细配置（如使用 SQLite、S3 存储、反向代理等）请参考 官方 Docker 部署文档 。

2. 使用 Proxmox 辅助脚本（适合 Proxmox VE 用户）
如果您使用 Proxmox VE，社区提供了 helper 脚本，可以一键创建运行 Happier 的 LXC 容器，并可选集成 Tailscale 实现远程访问 。

3. 使用系统服务直接安装（适合独立服务器/VPS）
在您的 Linux 服务器上，可以直接通过 CLI 命令安装为系统服务，由 hstack 管理生命周期 。

1
happier relay host install --mode system

此命令会引导您完成安装，默认使用 SQLite 数据库，并可根据需要选择 --channel stable|preview|dev 。

🔗 第三步：连接客户端与 CLI

服务器部署好后，需要将您的手机 App 和电脑 CLI 配置为使用这个新服务器。

  1. 配置 CLI 连接到您的服务器：
    在电脑终端执行以下命令，添加您的服务器地址。

    1
    2
    # 将 https://api.your-server.com 替换为您的服务器 API 地址
    happier server add --name myserver --server-url https://api.your-server.com --use

  2. 进行身份验证（推荐从手机开始）：
    执行 happier auth login 命令。推荐选择“移动设备”选项，终端会显示一个二维码或链接 。

    1
    happier auth login

  3. 在手机 App 上扫码确认：
    打开手机上的 Happier App，扫描终端显示的二维码。App 会提示您切换到新服务器（如果尚未切换），然后您可以登录或创建账户，并批准该终端的连接请求 。至此，您的设备就完成了端到端加密的连接。

🚀 第四步：开始使用

现在，您可以在电脑上使用 happier 命令来替代您常用的 AI 编程工具命令了。它会启动一个会话，并允许您从手机 App 上进行控制和查看 。

1
2
3
4
5
6
7
8
9
10
11
12
13
# 替代 claude 命令
happier

# 替代 codex 命令
happier codex

# 替代 opencode 命令
happier opencode

# 支持更多提供商
happier gemini
happier qwen
# ... 等等

会话启动后，您的手机 App 上就会出现该会话，您可以随时随地接管、查看或协作 。

⚠️ 重要提醒

  • 渠道选择：默认安装的是 stable 或 preview 稳定版。如果您想体验最新功能，可以安装 dev 版本，但需要注意它可能高度不稳定，并且必须所有组件（服务器、CLI、App）都使用 dev 版本 。
  • 安全配置：生产环境部署时，务必参考官方文档配置好认证策略（如 GitHub OAuth、OIDC 或 mTLS）和加密策略，以保障您的数据安全 。

如果在部署中遇到问题，可以查阅 官方文档 或通过 Discord 社区 寻求帮助。