聚合智能
juhe-cli 开放平台
返回首页

部署指南

juhe-sync 数据同步服务部署与配置

什么是 juhe-sync

juhe-sync 是数据同步服务，提供以下核心功能：

  • 接收 SAAS 回调：实时接收企微/个微的消息和事件通知
  • 增量同步联系人：自动同步新增和更新的联系人信息
  • 消息存储：将消息存储到 SQLite（默认）或 MySQL 数据库
  • HTTP API：提供 RESTful API 查询联系人、消息、群聊等数据

下载安装

二进制分发

juhe-sync 为独立的二进制文件，下载后直接运行即可。

Linux

bash
# 下载最新版
curl -L -o juhe-sync https://github.com/Hanson/juhe-cli/releases/download/v1.0.0/juhe-sync-linux-amd64
chmod +x juhe-sync
sudo mv juhe-sync /usr/local/bin/

macOS

bash
# Apple Silicon
curl -L -o juhe-sync https://github.com/Hanson/juhe-cli/releases/download/v1.0.0/juhe-sync-darwin-arm64

# Intel
curl -L -o juhe-sync https://github.com/Hanson/juhe-cli/releases/download/v1.0.0/juhe-sync-darwin-amd64

chmod +x juhe-sync
sudo mv juhe-sync /usr/local/bin/

Windows

从 GitHub Releases 获取 juhe-sync-windows-amd64.exe。

启动服务

基础启动

使用配置文件启动服务：

bash
./juhe-sync run --config juhe-sync.json

指定端口

bash
./juhe-sync run --config juhe-sync.json --port 8080

后台运行

bash
# 使用 nohup
nohup ./juhe-sync run --config juhe-sync.json &> juhe-sync.log &

# 使用 systemd（推荐）
sudo systemctl start juhe-sync
sudo systemctl enable juhe-sync

接入 MySQL（可选）

默认使用 SQLite 单文件存储（db_path）。数据量较大或需要统一备份/容量管理时， 可接入外部 MySQL（≥5.7，建议 utf8mb4）：

1. 建库与账号（最小权限）

sql
CREATE DATABASE IF NOT EXISTS juhe_sync DEFAULT CHARSET utf8mb4;
CREATE USER 'juhe_sync'@'%' IDENTIFIED BY 'your_password';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, INDEX, ALTER ON juhe_sync.* TO 'juhe_sync'@'%';
FLUSH PRIVILEGES;

2. 配置 db 块

在 juhe-sync.json 中添加 db 配置块（配置后 db_path 被忽略）：

json
{
  "api_url": "https://chat-api.juhebot.com",
  "app_key": "your_app_key",
  "app_secret": "your_app_secret",
  "guids": ["your_guid"],
  "port": 8070,
  "db": {
    "driver": "mysql",
    "dsn": "juhe_sync:your_password@tcp(127.0.0.1:3306)/juhe_sync?charset=utf8mb4"
  }
}

3. 启动验证

bash
./juhe-sync run --config juhe-sync.json
# 启动输出 "数据库: mysql (juhe_sync:***@tcp(127.0.0.1:3306)/juhe_sync)" 即接入成功
# 五张表（contacts/messages/rooms/sync_state/callbacks）自动创建

切换与回滚

切到 MySQL 后同步状态从空开始，首次启动自动全量+增量补齐联系人；SQLite 中的历史消息不会迁移。 回滚时删掉 db 块、改回 db_path 重启即可。DSN 密码不会出现在日志中。

配置回调 URL

注意：设置回调地址会覆盖原有配置

每次调用 set_notify_url 设置回调地址时，会覆盖该设备之前配置的回调地址。如果原有回调地址正在被其他服务使用，请先确认新地址不会影响已有服务，再进行设置。

启动 juhe-sync 后，需要在 juhe-cli 中配置回调 URL：

企微回调

bash
juhe-cli client set_notify_url '{
  "guid": "your_enterprise_guid",
  "notify_url": "https://your-server:8070/callback"
}'

个微回调

bash
juhe-cli wx client set_notify_url '{
  "guid": "your_wx_guid",
  "notify_url": "https://your-server:8070/callback"
}'

验证部署

检查服务状态

bash
# 检查进程
ps aux | grep juhe-sync

# 检查端口
netstat -tlnp | grep 8070

# 检查日志
tail -f juhe-sync.log

测试 API

bash
# 查询同步状态
curl http://localhost:8070/api/sync-status?guid=your_guid

# 查询联系人
curl http://localhost:8070/api/contacts?guid=your_guid&page=1&limit=10

反向代理配置

Nginx 配置示例

nginx
server {
    listen 443 ssl;
    server_name your-domain.com;

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

    location /callback {
        proxy_pass http://localhost:8070/callback;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /api/ {
        proxy_pass http://localhost:8070/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

下一步