Happy Engineering 私有部署

发布时间： 更新时间： 总字数：826 阅读时间：2m 作者：IP：上海 网址

Happy Engineering 是一款专为 Claude Code、Codex 等命令行 AI 编程智能体设计的开源跨端（iOS/Android/Web）中继与控制工具。

架构与组件说明

Happy 的通信采用**端到端加密（E2EE）**机制，通过自建私有中继服务端（Happy Server），可以在企业内网或私人 VPS 上完全掌控数据转发通道，杜绝第三方依赖与合规风险。它的运行架构包含三部分：

  1. Happy CLI：运行在本地开发机上，包裹 Claude Code/Codex 进程，将终端状态和输出加密后发送到中继服务。
  2. Happy Server（私有部署对象）：轻量中继服务，负责在开发机与移动端之间同步端到端加密的消息包（Server 采用 Zero-Knowledge 架构，无法解密内容）。
  3. Happy App（移动端/Web）：在手机或网页上解密并提供类似聊天、语音控制与权限审批的交互界面。

私有服务端部署（Happy Server）

编写 docker-compose.yml

git clone https://github.com/slopus/happy.git
services:
  happy-server:
    build:
      # context: https://github.com/slopus/happy.git#main
			context: .
      dockerfile: Dockerfile
    container_name: happy-server
    restart: unless-stopped
    ports:
      - "3005:3005"
    environment:
      - NODE_ENV=production
      - PORT=3005
      - DATA_DIR=/data
      - PGLITE_DIR=/data/pglite
      - HANDY_MASTER_SECRET=<openssl rand -hex 32>
    volumes:
      - ./happy-data:/data
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 512M
        reservations:
          memory: 128M

启动服务

# 生成安全密钥并替换上面文件中的 HANDY_MASTER_SECRET
openssl rand -hex 32

# 一键构建并后台启动
docker compose up -d --build

uses:

  • PGlite - embedded PostgreSQL (data stored in ./happy/pglite)
  • Local filesystem - for file uploads (stored in ./happy/files)
  • In-memory event bus - no Redis needed
bash 
docker compose up -d

启动后可通过 docker compose logs -f happy-server 查看启动日志，确认数据库连接与端口监听（默认端口 3005）正常。

nginx 反向代理

server {
    listen 80;
    server_name happy.xiexianbin.cn;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name happy.xiexianbin.cn;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3005;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

客户端配置切换为私有服务

完成服务端搭建后，需要分别将 开发机 CLI 和 手机端 App 指向自己的服务器地址。

开发机 CLI 配置

在运行 Claude Code 的工作机上设置环境变量 HAPPY_SERVER_URL：

bash 
# 写入 ~/.bashrc 或 ~/.zshrc
export HAPPY_SERVER_URL=https://happy.xiexianbin.cn
export HAPPY_WEBAPP_URL=https://happy.xiexianbin.cn

# 生效配置后启动 happy
source ~/.zshrc

npm install -g happy

# Instead of claude, use:
happy claude
# or
happy codex

移动端 App（iOS / Android）配置

  1. 打开手机上的 Happy App。
  2. 进入 Settings（设置） 界面。
  3. 找到 Relay Server URL（中继服务器地址）选项。
  4. 将默认的云端地址替换为你的私有地址：https://happy.xiexianbin.cn 并保存。
  5. 按照 App 提示扫描电脑终端通过 happy 输出的配对二维码，完成本地密钥交换。

参考

  1. https://happy.engineering/
  2. https://github.com/slopus/happy
最新评论