配置说明

应用从一个 YAML 文件加载配置（命令行传入路径，或默认读取 ./config.yaml），随后用 ICQQ_* 环境变量覆盖其中的敏感/常用字段。把 config.example.yaml 复制为 config.yaml 再填值即可。

cp config.example.yaml config.yaml
cargo run -p icqq-app -- config.yaml

顶层运行参数

字段	默认值	说明
data_dir	"./data"	SQLite 存储 + 持久化的设备/token 所在目录。
heartbeat_interval	15000	meta_event 心跳周期（毫秒，对应 go-cqhttp 的 heartbeat.interval）。据此推算心跳超时。设为 0（或任意 <= 0）则完全关闭心跳（不启动心跳任务）。

account —— 凭据 + sign server（必填）

字段	必填	默认/示例	说明
uin	是	<your-uin>	QQ 号（整数）。
password	否	<your-password>	明文，或 32 位小写 MD5 十六进制。留空/注释掉则改用扫码登录。
sign_api_url	是*	<sign-server-url>	sign-server API 基址（qsign / unidbg-fetch-qsign / 兼容 T544）。留空 => 无签名器 => 无法 LIVE 登录（仅离线启动）。
platform	是	1	平台代码（整数），见下方平台代码表。
apk_ver	否	"9.2.0"	使用哪个 apk 档案 / QQ 版本。从该平台的 apk 列表里选版本匹配的；必须与 sign server 白盒支持的版本一致。省略则用平台默认 apk。
login_method	否	"qr" / "password"	登录方式。省略时由 bridge 推断：有密码 => 密码；有 sign server 但无密码 => 扫码；否则离线。

* 仅离线启动可省略 sign_api_url；真实登录必填。

平台代码表

代码	平台	说明
1	Android（安卓手机）	最常用，大多数 sign server 支持此平台
2	aPad（安卓平板）	常用平台之一
3	Watch（手表）	QQ 轻量版
4	iMac（macOS 桌面）	桌面客户端
5	iPad	iPad 原生客户端
6	Tim	TIM 轻聊版

TIP

不同平台对应不同的 apk 档案和协议特征。apk_ver 必须与所选平台的 sign server 白盒支持版本一致，否则登录会被拒绝。常用组合为 platform: 1（Android）或 platform: 2（aPad）配合 apk_ver: "9.2.0"。

http —— OneBot 11 HTTP API 服务 + 可选事件上报

bot 在 host:port 响应 action；若设了 post_url 则同时把事件 POST 过去（HTTP-POST），并用 secret 经 X-Signature 头做 HMAC 签名。

字段	默认值	说明
enable	false	是否启用 HTTP 传输。
host	"127.0.0.1"	监听地址。
port	0	监听端口（示例用 5700）。
access_token	""	Bearer token；非空时请求需带 Authorization: Bearer <token>。
post_url	无	可选的 HTTP-POST 事件上报目标。省略则关闭事件上报。
secret	无	可选：每次 POST 的 X-Signature 头所用 HMAC-SHA1 密钥。

ws —— 正向 WebSocket 服务

客户端连到 bot。

字段	默认值	说明
enable	false	是否启用正向 WS。
host	"127.0.0.1"	监听地址。
port	0	监听端口（示例用 6700）。
access_token	""	鉴权 token。

ws_reverse —— 反向 WebSocket 客户端

bot 主动连出到上游。

字段	默认值	说明
enable	false	是否启用反向 WS。
url	""	要连接的上游地址（如 ws://127.0.0.1:8080/onebot）。
access_token	""	鉴权 token。
reconnect_interval	3000	重连退避（毫秒）。

ICQQ_* 环境变量覆盖

以下环境变量存在即覆盖 config.yaml 中的对应值（env 优先），便于把密码 / sign server 等敏感值从配置文件移到环境，避免明文落盘。实现见 crates/icqq-app/src/config.rs 的 apply_env_overrides。

环境变量	覆盖的配置字段	解析
ICQQ_UIN	account.uin	解析为整数；解析失败则忽略，保留原值。
ICQQ_PASSWORD	account.password	原样字符串。
ICQQ_SIGN_API_URL	account.sign_api_url	原样字符串。
ICQQ_PLATFORM	account.platform	解析为整数；解析失败则忽略。
ICQQ_APK_VER	account.apk_ver	原样字符串。
ICQQ_LOGIN_METHOD	account.login_method	原样字符串（"qr" / "password"）。
ICQQ_DATA_DIR	data_dir	原样字符串。
ICQQ_HTTP_ACCESS_TOKEN	http.access_token	原样字符串。

未设置的变量保留 config.yaml 的原值；设置了才覆盖。