如果你想自己决定会话数据存放在哪里、中继如何配置，可以运行自己的中继。云端中继完全够用，但自托管让你拥有全部控制权。

本指南介绍如何运行一个私有的 Happier 中继。

要点

Docker（推荐的起步方式）：

docker pull happierdev/relay-server:stable
docker run -d \
  -p 3600:3600 \
  -e HANDY_MASTER_SECRET="$(openssl rand -hex 32)" \
  -e NODE_ENV=production \
  --name happier-relay \
  happierdev/relay-server:stable

或者托管式安装：

happier relay host install --mode system

然后把客户端配置为使用你的中继 URL，而不是默认地址。

问题

使用云端中继意味着：

• 会话数据经过你无法掌控的基础设施
• 无法控制数据存放位置和保留策略
• 依赖云服务的可用性
• 速率限制和策略的自定义空间有限

对某些工作流来说这没问题。对另一些来说，你需要：

• 完全拥有基础设施
• 数据留在你的网络或你选择的托管环境中
• 自定义认证和访问策略
• 掌控更新和配置

常见做法及其取舍

• 云端中继：运行良好，但你的数据不在你自己的基础设施上。
• 从源码构建：可行，但需要持续跟进依赖和构建步骤。
• 自己实现中继：会成为维护负担。

自托管官方中继解决了这些问题：

• 预构建的 Docker 镜像
• 托管式安装选项
• 与云端版本相同的中继协议
• 完全掌控部署

如果你第一次接触 Happier

Happier 是一款面向 Claude Code、Codex 和 OpenCode 等 AI 编程代理的开源配套应用。

中继是服务器端组件，负责：

• 在你的设备之间转发消息
• 存储会话元数据
• 处理认证
• 提供端到端加密的消息传递

自托管中继后，你的会话和审批都不会离开你的基础设施。

开始设置：

• GitHub: https://github.com/happier-dev/happier
• 自托管文档: https://docs.happier.dev/self-hosting
• Discord: https://discord.gg/W6Pb8KuHfg

前提条件

选择一种部署方式：

Docker（推荐）

• 已安装 Docker
• 一台有公网 IP 或可通过私有网络访问的主机
• 端口 3600 可用（或配置其他端口）

托管式安装

• 一台 Linux 或 macOS 机器
• 已安装 Happier CLI
• 能够运行服务（systemd 或用户服务）

运行器（进阶）

• Node.js 或 Bun
• 进程管理器（PM2、systemd 等）
• 手动管理构建产物

方式 1：Docker（推荐大多数人使用）

Docker 只需很少的配置就能快速开始自托管。

1) 拉取镜像

docker pull happierdev/relay-server:stable

可用标签：

• stable：正式版
• preview：预览版
• dev：开发构建

生产环境请使用 stable。

2) 生成主密钥

主密钥用于加密静态数据并派生认证令牌。

openssl rand -hex 32

请妥善保存这个值。不要弄丢：更换密钥会导致现有数据无法读取。

3) 运行容器

docker run -d \
  -p 3600:3600 \
  -e HANDY_MASTER_SECRET="your-secret-from-step-2" \
  -e NODE_ENV=production \
  --name happier-relay \
  --restart unless-stopped \
  happierdev/relay-server:stable

4) 确认正在运行

docker logs happier-relay

你应该看到：

[info] Happier relay server starting...
[info] Listening on http://0.0.0.0:3600

5) 配置客户端使用你的中继

在 Happier 应用中：

1. 进入设置（Settings）→ 服务器（Server）
2. 添加一个新的服务器配置
3. 输入你的中继 URL：http://your-server-ip:3600
4. 保存并连接

在 Happier CLI 中：

happier config set relay.url http://your-server-ip:3600

客户端的详细设置见 自托管快速入门。

方式 2：托管式安装（以服务方式部署）

托管式安装会创建一个开机自启的系统服务，并提供更新命令。

1) 安装 Happier CLI

按照 CLI 安装指南 操作。

2) 将中继安装为系统服务

happier relay host install --mode system

以用户模式安装（无需 sudo）：

happier relay host install --mode user

3) 配置主密钥

编辑服务配置：

sudo nano /etc/happier-relay/env

添加：

HANDY_MASTER_SECRET=your-secret-here
NODE_ENV=production

4) 启动中继

happier relay host start

5) 查看状态

happier relay host status

你应该看到：

Relay service: active (running)

6) 配置客户端

与 Docker 方式相同：在客户端设置中添加你的中继 URL。

方式 3：运行器（面向进阶用户）

运行器会在启动时获取并校验中继构建产物，然后运行服务器二进制文件。

适用于以下情况：

• 你已经有进程管理器
• 你希望重启时下载构建产物
• 你不想用 Docker 或服务管理

1) 运行中继服务器包

npx --yes --package @happier-dev/relay-server happier-server \
  --master-secret "your-secret-here" \
  --port 3600

2) 配合进程管理器使用

PM2 示例：

pm2 start npx --name happier-relay -- \
  --yes --package @happier-dev/relay-server happier-server \
  --master-secret "your-secret-here" \
  --port 3600
pm2 save

运行器的详细说明见 自托管运行时文档。

环境变量配置

主要环境变量：

完整列表见 环境变量文档。

认证设置

默认情况下，中继使用基于密码的认证。

生产环境可以考虑：

• GitHub OAuth：见 GitHub 认证
• OIDC：见 OIDC 认证
• mTLS：见 mTLS 认证

HTTPS 与反向代理

生产环境中，请把中继放在支持 HTTPS 的反向代理后面。

nginx 示例：

server {
    listen 443 ssl;
    server_name relay.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3600;
        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;
    }
}

然后客户端连接到：https://relay.example.com

更新

Docker

docker pull happierdev/relay-server:stable
docker stop happier-relay
docker rm happier-relay
# Re-run the docker run command with the new image

托管式安装

happier relay host install --mode system
happier relay host restart

运行器

运行器会在重启时自动获取新的构建产物。

故障排查

症状：容器立即退出

可能原因：

• 缺少 HANDY_MASTER_SECRET 或其值无效
• 端口已被占用

解决：

1. 查看容器日志：docker logs happier-relay
2. 确认环境变量已设置
3. 检查端口是否可用：lsof -i :3600

症状：客户端无法连接

可能原因：

• 防火墙拦截了端口 3600
• 中继没有在正确的网络接口上监听
• 客户端的中继 URL 错误

解决：

1. 确认中继正在运行：docker ps 或 happier relay host status
2. 检查防火墙：sudo ufw allow 3600/tcp
3. 测试连通性：curl http://your-server-ip:3600
4. 确认客户端的中继 URL 与服务器地址一致

症状：出现“Authentication failed”错误

可能原因：

• 主密钥在中继和客户端注册之间发生了变化
• 中继重启时没有保留认证令牌

解决：

1. 确认 HANDY_MASTER_SECRET 保持一致
2. 如果主密钥变了，重新注册客户端
3. 查看中继日志中的认证错误

症状：更新没有生效

Docker：

• 确认在重建容器之前已经拉取镜像
• 检查镜像标签没有变化

托管式安装：

• 再次运行 happier relay host install
• 安装后重启服务

常见问题

我需要自托管吗？

不需要。对大多数用户来说，云端中继就够用。

在以下情况下选择自托管：

• 需要数据存放位置的保证
• 想完全掌控基础设施
• 有合规要求
• 更喜欢自己管理的服务

能从云端迁移到自托管吗？

可以，但会话不会自动迁移。

流程：

1. 搭建自托管中继
2. 配置客户端使用新的中继 URL
3. 现有的云端会话保留在云端中继上
4. 新会话使用自托管中继

端到端加密仍然有效吗？

是的。端到端加密在客户端完成，与你使用哪个中继无关。

无论中继由谁运营（你自己或云服务商），都无法读取会话内容。

如何备份中继数据？

中继把数据存储在它的数据目录中。

Docker： 添加一个卷挂载：

-v /path/to/data:/data

托管式安装： 数据位置因操作系统而异，可通过 happier relay host status 查看。

备份：

1. 停止中继
2. 复制数据目录
3. 重新启动中继

可以运行多个中继实例吗？

可以，用于高可用或负载均衡。

要求：

• 共享的数据存储（数据库）
• 前置负载均衡器
• 所有实例使用相同的 HANDY_MASTER_SECRET

集群配置见 环境变量文档。

相关指南

• 如何在手机上使用 Happier
• Happier 与 Claude Code Remote Control 对比