配置说明

juhe-sync.json 配置文件详细说明

配置文件路径

默认配置文件路径：./juhe-sync.json

可通过 --config 参数指定其他路径：

bash

./juhe-sync run --config /path/to/custom-config.json

完整配置示例

json

{
  "api_url": "https://chat-api.juhebot.com",
  "app_key": "your_app_key",
  "app_secret": "your_app_secret",
  "guids": ["guid_enterprise_1", "guid_wx_2"],
  "guid_types": {
    "guid_enterprise_1": "enterprise",
    "guid_wx_2": "wx"
  },
  "port": 8070,
  "db_path": "./juhe-sync.db",
  "db": {
    "driver": "mysql",
    "dsn": "juhe_sync:your_password@tcp(127.0.0.1:3306)/juhe_sync?charset=utf8mb4",
    "max_open_conns": 10,
    "max_idle_conns": 5,
    "conn_max_lifetime_seconds": 3600
  },
  "sync_interval": 300
}

db 配置块与 db_path 的关系

配置了 db 块时优先生效，db_path 被忽略；未配置 db 块时沿用 db_path（SQLite），与历史版本行为完全一致。上方示例同时展示两者仅为说明字段，实际使用二选一即可。

参数说明

字段名	类型	必填	默认值	说明
`api_url`	string	是	-	SAAS API 地址
`app_key`	string	是	-	应用 Key
`app_secret`	string	是	-	应用 Secret
`guids`	string[]	是	-	需要同步的设备 GUID 列表
`guid_types`	object	否		GUID 类型映射，可选值：enterprise/wx
`port`	number	否	8070	HTTP 服务端口
`db_path`	string	否	./juhe-sync.db	SQLite 数据库文件路径（配置 db 块时被忽略）
`db.driver`	string	否	-	存储驱动，可选值：sqlite / mysql。仅配置 dsn 未配置 driver 时自动推断为 mysql
`db.dsn`	string	db.driver=mysql 时必填	-	MySQL 连接串，如 user:password@tcp(host:3306)/dbname?charset=utf8mb4
`db.max_open_conns`	number	否	10	MySQL 连接池上限
`db.max_idle_conns`	number	否	5	MySQL 空闲连接数
`db.conn_max_lifetime_seconds`	number	否	3600	MySQL 连接最大存活时间（秒）
`sync_interval`	number	否	300	增量同步间隔（秒）

环境变量配置

支持通过环境变量覆盖配置文件中的部分设置：

环境变量	对应字段	说明
`JUHE_SYNC_API_URL`	api_url	SAAS API 地址
`JUHE_SYNC_APP_KEY`	app_key	应用 Key
`JUHE_SYNC_APP_SECRET`	app_secret	应用 Secret
`JUHE_SYNC_PORT`	port	HTTP 服务端口
`JUHE_SYNC_DB_PATH`	db_path	数据库文件路径
`JUHE_SYNC_DB_DRIVER`	db.driver	存储驱动（sqlite / mysql）
`JUHE_SYNC_DB_DSN`	db.dsn	MySQL 连接串

使用环境变量

bash

# 设置环境变量
export JUHE_SYNC_API_URL="https://chat-api.juhebot.com"
export JUHE_SYNC_APP_KEY="your_key"
export JUHE_SYNC_APP_SECRET="your_secret"
export JUHE_SYNC_PORT="8080"

# 启动服务
./juhe-sync run --config juhe-sync.json

GUID 类型映射

当配置多个 GUID 时，建议明确指定每个 GUID 的类型。这对于正确处理企微和个微的不同协议非常重要。

类型值

enterprise：企业微信
wx：个人微信

示例

json

{
  "guids": ["ent_001", "wx_001"],
  "guid_types": {
    "ent_001": "enterprise",
    "wx_001": "wx"
  }
}

数据库配置

SQLite（默认）

juhe-sync 默认使用 SQLite 存储联系人、消息等数据。数据库文件会在首次启动时自动创建，通过 db_path 指定路径。

MySQL（可选）

数据量较大或需要统一备份/容量管理时，可通过 db 配置块接入外部 MySQL：

版本要求：MySQL ≥ 5.7（含 MariaDB 10.x），字符集建议 utf8mb4
账号权限：建议使用最小权限账号（仅需目标库的建表与增删改查权限）
建表：首次启动自动建表（幂等，重复启动不报错、不丢数据）
安全：DSN 中的密码不会出现在任何日志与错误信息中（自动脱敏为 user:***@tcp(host:port)/dbname）

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

数据表结构

contacts：联系人信息
messages：消息记录
rooms：群聊信息
sync_state：同步状态
callbacks：回调原始记录

同步间隔配置

sync_interval 控制增量同步的频率（秒）。较小的值可以更快获取新数据，但会增加 API 调用频率。

推荐值：300 秒（5 分钟）
实时性要求高：60-120 秒
节省资源：600 秒（10 分钟）