==============================================================
  OpenQQ QQ Sync Bridge v3.0 —— Linux 版使用说明
==============================================================

这里教的只有一件事：在 Linux 服务器上把同步桥跑起来，
让海豹能连上它。

全程只需要做 4 步，一步步来就行。


--------------------------------------------------------------
第 1 步：把 docker 文件夹传上服务器
--------------------------------------------------------------

把电脑上的 docker 这个文件夹，整个传到服务器任意位置，
比如 /root/openqq-bridge。

（用 FinalShell / WinSCP / 宝塔面板，直接拖上去就行）


--------------------------------------------------------------
第 2 步：找到海豹的数据文件夹
--------------------------------------------------------------

海豹的数据在它自己的目录里，路径一般是：

    /xxx/Sealdice/data/default

这个文件夹里应该有这两个文件：

    data.db
    data-logs.db

把它的完整路径记下来，等会儿要填。
（在宝塔/FinalShell 里点进文件夹，复制上面的路径）


--------------------------------------------------------------
第 3 步：改一个配置文件
--------------------------------------------------------------

在服务器上打开 docker 文件夹里的 .env.example，
先把它复制一份，改名成 .env，然后改两行：

    SEALDICE_DATA_DIR=/xxx/Sealdice/data/default
    OPENQQ_BRIDGE_TOKEN=随便打一串字母数字

例如：

    SEALDICE_DATA_DIR=/opt/Sealdice/data/default
    OPENQQ_BRIDGE_TOKEN=abc123def456

两个说明：
  * SEALDICE_DATA_DIR 就是第 2 步记下的路径，要写完整。
  * OPENQQ_BRIDGE_TOKEN 是自己随便定的密码，
    后面在海豹插件里要填一样的内容。


--------------------------------------------------------------
第 4 步：启动
--------------------------------------------------------------

在服务器的命令行里，进入 docker 文件夹，执行：

    docker compose up -d

第一次会下载和构建，等一两分钟。

看到这行就成功了：

    Started

然后检查一下：

    curl http://127.0.0.1:38999/health

如果返回

    {"ok": true, "version": "3.0", ...}

就说明跑起来了。


--------------------------------------------------------------
海豹那边怎么填
--------------------------------------------------------------
打开海豹插件的配置界面填写邮箱、SMTP 授权码
  发件邮箱      ： 你的 QQ 邮箱，如 123456@qq.com
  SMTP授权码    ： QQ 邮箱的 SMTP 授权码（不是 QQ 登录密码！见下面）
  SMTP服务器    ： smtp.qq.com（默认值，一般不用改）
  SMTP端口      ： 465（默认值，一般不用改）
    Bridge主机    ： 127.0.0.1
    Bridge端口    ： 38999
    Bridge访问令牌： 第 3 步自己定的那串
SMTP 授权码怎么拿（必看）：

  授权码属于【发件邮箱】，也就是你填在“发件邮箱”里的那个 QQ 邮箱。
  收验证码的是 旧QQ号@qq.com，那个邮箱什么都不用设置。

  1. 电脑浏览器打开 https://mail.qq.com ，登录你要当发件箱的 QQ 邮箱
  2. 左上角 设置 → 账号（有的版本叫“账户”）
  3. 往下找到“POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务”
  4. 在“IMAP/SMTP服务”那一行点【开启】
     （开 POP3/SMTP 也行，两个开一个就够，推荐 IMAP/SMTP）
  5. 按提示用绑定手机发一条短信，发完点“我已发送”
  6. 通过后会显示一串 16 位授权码，形如  abcd efgh ijkl mnop
     【只显示这一次】，先复制下来
  7. 回到插件配置填写：
       发件邮箱   → 你刚才登录的那个邮箱，如 123456@qq.com
       SMTP授权码 → 那 16 位，【去掉空格】，变成 abcdefghijklmnop
       SMTP服务器 → smtp.qq.com（不用改）
       SMTP端口   → 465（不用改）
  8. 保存后在群里发 .旧QQ邮箱测试 ，能收到测试邮件就说明配好了

  容易踩的坑：
    - 填成 QQ 登录密码 → 一定失败，必须用授权码
    - 授权码里的空格没去掉
    - 找不到授权码了：回到第 4 步点“生成授权码”可重新生成，旧的会失效
    - 改过 QQ 密码后授权码通常也会失效，需要重新生成
    - 同一个发件邮箱可以给多个海豹实例共用
    - 收不到邮件时，让对方检查 QQ 邮箱的 设置 → 反垃圾 ，
      必要时把发件邮箱加进白名单


然后原样执行迁移：

    .旧QQ绑定 <旧QQ> <旧群>
    .旧QQ验证码 <6位数字>

和 Windows 版完全一样。
  例如：.旧QQ绑定 2522629086 1081354778
  执行后，系统会给 2522629086@qq.com 发一封带 6 位验证码的邮件。

--------------------------------------------------------------
出问题先看这三条
--------------------------------------------------------------

1) 怎么知道有没有在跑

    docker compose ps

   看到 running 就是好的。

2) 起不来 / 说找不到 data.db

   说明第 3 步的 SEALDICE_DATA_DIR 路径写错了。
   复制你第 2 步记下的路径直接粘，别手打。

3) 海豹说连不上

   先在服务器上执行：

    curl http://127.0.0.1:38999/health

   这条都通不了，就是桥没起来；通了但海豹还是连不上，
   就检查插件里的 主机 / 端口 / 令牌 这三项有没有对上。


--------------------------------------------------------------
想停掉 / 想重启
--------------------------------------------------------------

    停止： docker compose down
    重启： docker compose restart
    看日志： docker compose logs -f

停止不会删数据，海豹的东西还在你自己的文件夹里。

TIPS:
1. 迁移只做一次，之后不会再同步。
   验证码通过的那一瞬间，把旧数据【复制】一份过来，然后就结束了。
   这是设计如此，不是出问题：桥不监听消息、也不做轮询，
   所以旧群后来新产生的消息和 log 不会跟过来，两边数据从此各自独立。
   （详见第八节「为什么迁移完就没有再同步了」）

2. 同一个旧 QQ 可以绑到多个不同的 OpenQQ 账号，不用先解绑。
   绑定身份是「旧QQ + 旧群 + OpenQQ账号 + 目标群」，
   所以换一个 OpenQQ 账号去绑同一个旧QQ不会被拒绝；
   只有【完全相同】的组合重复绑定才会提示已绑定。
   要换成另一个 OpenQQ：直接在新账号/新群里执行 .旧QQ绑定 即可。

3. 验证码限制：
   5 分钟有效，最多输错 5 次，超了要重新申请。

4、迁移前，同步桥会在 data/default/ 里自动备份，角色卡库和日志库
【各自独立备份】，互不影响：

  data.db.snapshot-first.bak         角色卡库的首次快照，永久保留，
                                     不会被覆盖或删除
  data-logs.db.snapshot-first.bak    日志库的首次快照，同样永久保留
  data.db.before-sync-<时间>.bak     最近 2 份滚动备份，多的自动清理
  data-logs.db.before-sync-<时间>.bak  同上


出问题了想还原，用 .snapshot-first.bak 最稳妥。还原步骤：

  1. 先关掉海豹和同步桥
  2. 删掉同名的 -wal 和 -shm 文件（如果有）
  3. 把 .snapshot-first.bak 改名回去替换 data.db（或 data-logs.db）
  4. 重新启动海豹

—————————————————————————
常见问题
--------------------------------------------------------------

双击 cmd，窗口一闪就没了
  OpenQQ-QQ-Sync-Bridge-v3.0.exe 和 bridge_port.txt 是不是没和 cmd
  放在一起？三个文件必须在同一个文件夹里。

插件报“无法连接同步桥 38999”
  按顺序检查：
    1. cmd 那个黑窗口是不是被关了？
    2. bridge_port.txt 里的数字，和插件里填的“Bridge端口”是否一致？
    3. 38999 端口是不是被别的程序占了？可以把 bridge_port.txt 改成
       39000，插件里也改成 39000，然后重启 cmd。

收不到验证码邮件
  先执行 .旧QQ邮箱测试。收不到一般是这三个原因：
    1. “SMTP授权码”填成了 QQ 登录密码（必须是那串 16 位授权码）
    2. QQ 邮箱的 SMTP 服务没开启
    3. 邮件进了垃圾箱

提示“该旧QQ与该旧群都没有找到可迁移的数据”
  说明旧 QQ 在这个旧群里既没有角色卡，也没有 log。检查旧群号填对了没有，或者是本身数据库文件出现了问题。

提示“该旧QQ/旧群已经绑定到当前OpenQQ”
  说明【完全相同的这个组合】之前已经绑过了，无需重复执行。
  想绑到另一个 OpenQQ 账号，直接在新账号的新群里执行 .旧QQ绑定 就行，
  不需要先解绑。

结果显示“Log迁移失败 N 个”，但其他都好了
  不用担心，失败的那几条会被跳过，其余照常迁移，【不会整批失败】。
  具体是哪几条、什么原因，看同步桥目录下的 bridge_error.log。

结果显示“识别为已迁移、未重复复制”
  说明这次执行时这些 log 之前已经迁移过了，自动跳过避免重复，
  属于正常情况。

为什么迁移完就没有再同步了？旧群的新记录去哪了
  迁移是【一次性】的，这是设计如此，不是出问题了。
  验证码通过的那一刻把旧数据复制一份过来，然后就结束了。
  桥不监听消息、也不轮询，所以旧群之后的新消息不会跟过来。
  两边的数据从此各自独立，互不影响。

换过 OpenQQ 账号，数据找不到了
  如果你之前用另一个 OpenQQ 账号迁移过，数据在【那个账号】名下，
  不会跟着你换账号。确认方法：用旧账号执行 .旧QQ绑定信息 看绑定，
  或者去之前迁移用的那个群看角色面板。

  想迁到新账号：不需要解绑，直接切到新账号，在新群里执行：
      .旧QQ绑定 <旧QQ> <旧群>
      .旧QQ验证码 <6位验证码>
  同一个旧QQ可以绑定多个 OpenQQ 账号，每个组合各记一份。

  注意：迁移是复制，旧账号的数据不会被删，两份都在。
