1. 签名服务在机器人链路里的真实位置
Docker 装机器人这个系列写到第二篇，绕不过去的第一个硬骨头就是签名服务器。不少人第一次搭机器人，容器跑起来了、配置文件也填了，日志却一直刷登录失败，翻半天才发现少了一台 qsign。说白了，签名服务器就是替机器人生成登录所需签名凭证的一台小服务：机器人在协议握手阶段必须拿出符合校验规则的签名数据，本地算不出来，就得靠外部服务代算。这篇把 bs-qsign 从镜像准备、参数配置、容器启动到与机器人侧对接联调这条完整链路拆开讲清楚，适合已经能跑通 Docker 基础命令、正卡在签名环节的朋友，也适合之前搭起来但一直掉线、签名报错的人对照排查。
先给个整体印象：整套结构里其实只有两个角色，一个是对外说话的机器人本体，一个是背后默默算数的签名服务。前者关心的是消息收发、事件处理，后者关心的是把一段十六进制串输入进去、把 token 和签名结果吐出来。两者之间通过 HTTP 通信，跟微服务拆分类似，逻辑上完全可以合并，但工程上分开更稳、更好维护。理解了这个分工，后面所有配置项的意义就都好推了。
1.1 协议登录时那句签名到底在校验什么
从协议视角看，客户端登录不是发个账号密码就完事的。握手阶段客户端要提交设备信息、协议版本、平台标识，以及一段由特定算法生成的签名数据，服务端拿这段数据去校验"你是不是一个合法的、版本匹配的客户端"。这套校验的算法实现在官方客户端内部，属于封闭逻辑，第三方实现在不掌握原始算法的情况下，只能通过逆向分析去复现关键计算过程。qsign 这类项目做的就是这件事：把算法部分单独抽出来做成一个可被 HTTP 调用的服务，机器人本体只管发请求、拿结果。
这里有个容易混淆的点：签名服务不算"登录代理"，它不接触账号凭证，也不维持会话，纯粹是"输入一段数据、输出一段数据"的计算器。所以它挂掉的时候，机器人已经在线上的会话不会立刻断，但一旦触发重连、需要重新签名，就必然失败。这个特性决定了排查方向——如果你的机器人是"刚开始能跑，跑一段时间才掉线，掉了就上不去"，八成是签名服务这一侧的问题，而不是账号本身出了状况。
还有个现实约束：算法实现依赖具体的协议版本。协议升级、字段调整、算法常量变动，都会让旧版签名服务生成的数据校验不过。这就是为什么社区里永远在强调"版本要对齐"——它不是一句玄学经验，而是由算法本身绑死在版本号上的物理事实。
1.2 为什么不把签名服务塞进机器人容器里
第一反应通常是"一个容器里塞两个进程不就完了"，省事。我一开始也这么想，实际跑过之后还是拆开了，理由有三个。
其一是依赖冲突。签名服务的运行环境对系统库有比较硬的要求，尤其是加密相关的基础库版本；而机器人框架往往是另一套运行时。两者塞进同一个镜像，光是解决动态库版本打架就能耗掉一晚上，而且这种冲突在升级任意一方时都会复发。分成两个容器之后，各自的镜像只管自己的事，谁也不欠谁。
其二是故障隔离与重启粒度。签名服务属于"无状态计算"型组件，重启成本极低，几秒钟就能回来；机器人本体则持有会话、缓存、插件状态，重启往往意味着要重新走登录、重新加载一堆东西。分开之后，签名服务崩了可以单独重启，机器人不受影响；反过来也一样。混在一个容器里，任何一方出问题都得整体重启，代价大得多。
其三是资源与扩展的独立性。签名计算吃 CPU，不吃磁盘也不怎么吃网络；机器人本体则更多是 IO 和内存占用。分开之后可以分别限制资源、分别看监控指标。真到了要接多个机器人实例的时候，一台签名服务可以给多个实例共用，容器拆分是最自然的前提。
注意：签名服务是"基础设施"性质的东西，一旦决定长期跑，就别用临时容器（不带
-d和重启策略的那种）。它挂掉不会立刻报警，等到机器人掉线你才发现，损失的是时间。
1.3 版本、平台、协议三者必须对齐
这是整个搭建过程中最容易出错、也最容易被忽略的一环。对齐关系包含三层：
第一层是协议版本号。签名服务启动时要指定一个版本参数（常见形态是VERSION=8.9.x这类），机器人侧配置里也要填同一个版本号。两边不一致，签名请求会被服务端拒绝，日志里表现通常是签名返回码非零，或者握手阶段直接断开。
第二层是平台标识。同一个协议版本在不同平台上（手机端、平板端、桌面端）的设备字段和部分算法参数并不完全相同。签名服务和机器人两侧的平台类型要保持一致，否则生成的数据从结构上就对不上。
第三层是镜像架构。签名服务的核心计算部分通常带有本地编译的库，amd64 和 arm64 是分别构建的。在 ARM 机器上硬拉 amd64 镜像，靠模拟层也不是不能跑，但会慢十倍以上，签名超时随之而来，表现为"能启动、能响应、但机器人一直登录失败"。这个问题特别隐蔽，因为容器看起来是健康的。
| 对齐项 | 签名服务侧 | 机器人侧 | 不一致的典型表现 |
|---|---|---|---|
| 协议版本 | VERSION环境变量 | 配置文件的协议版本字段 | 签名返回非零，握手失败 |
| 平台类型 | 启动参数或配置项 | 配置文件的平台字段 | 登录后被踢，反复重连 |
| CPU 架构 | 镜像 tag | 无（跟随宿主机） | 响应极慢，签名超时 |
| 鉴权密钥 | KEY环境变量 | 请求头或查询参数 | 401/403，请求被拒 |
提示：把这三层对齐信息写在自己的部署笔记里，尤其是协议版本号。升级任何一侧之前先翻一眼，能省掉大量排查时间。
2. 动手前的环境盘点与镜像准备
很多人上来就敲docker run，跑不通再回头查，效率很低。这个环节花十分钟把前置条件确认一遍，后面能少走很多弯路。签名服务本身不复杂，但它对"地基"的敏感度比一般 Web 服务高，因为它要长时间稳定运行，还要承受机器人那边周期性的请求压力。
2.1 机器规格与系统基线怎么定
规格方面，签名服务真不算重。单个机器人实例的签名请求频率很低——登录时集中要一批，之后每隔一段时间刷新一次 token，日常几乎静默。1 核 1G 内存能跑，但我不推荐卡着这条线，理由是这样：
- 容器本身加上基础镜像，常驻内存就在两三百兆上下；
- 计算过程是瞬时 CPU 密集型的，1 核机器上签名请求打进来时，容器会被短暂顶满，如果同机还跑了机器人本体，两边抢 CPU 容易互相拖累；
- 系统本身、日志、Docker 守护进程都要占资源，留不出余量的话，一次 OOM 就能让你怀疑人生。
我的经验值是2 核 2G 起步，跑单个机器人实例绰绰有余，接三五个也扛得住。磁盘 10G 足够，签名服务的日志增长不快，但如果开了 debug 级别日志就另说了。
系统基线方面，优先选 x86_64 的常见发行版，内核不要太老（4.x 以上基本没问题）。ARM 机器（比如各类开发板、ARM 云主机）不是不能跑，但一定要确认镜像有对应的 arm64 构建，别用模拟层硬撑。另外，如果宿主机开了防火墙或者安全组，记得提前放行签名服务要用的端口，虽然一般只在内网调用，但机器人如果跑在另一个容器或另一台机器上，端口不通是高频故障。
2.2 Docker 环境自检清单
装完 Docker 别急着往下走，先跑几条命令确认环境是干净的。这些检查看着基础，但真出问题时，能帮你快速排除掉一半的可能。
# 版本与架构 docker version uname -m # 守护进程是否正常 docker info | head -20 # 磁盘余量 df -h /var/lib/docker # 端口占用检查（假设签名服务用 8080） ss -lntp | grep 8080uname -m这条特别值得单独跑一次。它输出x86_64就是 amd64 架构，输出aarch64就是 arm64。很多人是在本地笔记本上试通了，搬到云主机上就出问题，往往就是架构变了、镜像拉错了。docker info里也能看到Architecture字段，两处对照着看最稳。
如果docker info报权限错误，说明当前用户不在 docker 组里，加进去重新登录即可；如果报守护进程连不上，那是 Docker 服务本身没起来。这两类问题跟签名服务无关，属于环境前置，必须先解决。
注意：不要把签名服务的端口直接暴露到公网。它没有复杂的鉴权体系，只有一个共享密钥，暴露出去等于给自己挖坑。所有调用都应发生在内网或同一宿主机的容器网络内。
2.3 镜像获取与离线导入的两种路子
镜像获取有在线拉取和离线导入两条路。在线拉取最省事，直接docker pull对应 tag 即可，但要注意两点：一是确认 tag 里体现的架构与宿主机匹配，二是仓库地址和镜像名以项目方公布的为准，别凭记忆拼。
# 在线拉取（镜像名与 tag 以项目公开说明为准） docker pull <registry>/<qsign-image>:<tag> # 拉完确认架构信息 docker inspect <qsign-image>:<tag> --format '{{.Architecture}}/{{.Os}}'离线导入适合网络受限的场景。做法是在一台能联网、架构相同的机器上把镜像导出成 tar 包，传过去再导入：
# 导出侧 docker save -o qsign.tar <qsign-image>:<tag> # 目标机导入 docker load -i qsign.tar docker images | grep qsign我个人的建议是：不管走哪条路，导入完成后立刻用docker inspect确认架构。这一步花不了几秒钟，但能挡掉后面最恶心的一类问题——容器一切正常、日志一片祥和，就是签出来的东西不对，因为它在用模拟层跑另一个架构的二进制。
还有一个细节：镜像拉下来之后别急着删旧版本。升级签名服务时，旧镜像留着做回滚，往往比重新拉取快得多。磁盘不紧张的话，留两三个版本很正常。
3. 签名服务容器的配置与启动
配置这一步是整篇的核心。签名服务的参数不多，但每一个都有明确的语义，配错任何一个都会导致"服务起来了但用不了"。下面按"目录规划—参数拆解—启动方式—健康检查"的顺序走一遍。
3.1 目录规划与挂载点
先说目录。签名服务一般需要一个持久化目录来存放配置和运行时数据，容器内通常是/data这类固定路径（以镜像说明为准）。宿主机上给它安排一个独立目录，比如/opt/qsign，好处是删容器不丢数据、备份迁移只看一个目录。
mkdir -p /opt/qsign/{data,logs} chmod -R 755 /opt/qsign权限这块要留意：容器里跑服务的用户 uid 未必和宿主机一致，如果挂载目录权限过严，容器启动时会因为写不进配置而直接退出，日志里通常是Permission denied。755 是个比较稳妥的起点，实在不行再放宽或者显式指定--user。
日志目录要不要单独挂，取决于镜像设计。有的镜像把日志写在/data/logs下，跟着数据目录一起就挂上了；有的写在/app/logs，那就需要额外挂一个。判断方法很简单：先不挂日志目录跑一次，看日志落在容器内哪个路径，再决定。
提示：把宿主机目录挂进容器时，尽量用绝对路径。相对路径在不同 shell、不同工作目录下行为不一致，很容易出现"昨天还好好的今天怎么找不到目录了"的怪事。
3.2 五个必填参数逐项拆解
不同镜像的环境变量命名可能略有差异，但语义基本一致。下面这五类是绕不开的，我按重要程度排一下。
第一是UIN，也就是机器人账号。它的作用是让签名服务知道"我在为谁服务"，部分实现还会用它做请求来源校验。填错的表现是签名请求返回异常码，或者机器人登录时提示账号不匹配。特别注意：如果你用的是小号做测试，UIN也必须填小号，不能填主号。
第二是VERSION，协议版本号。这个前面已经强调过，必须与机器人侧完全一致。版本号一般形如8.9.xx这样的三段式，写的时候别多加空格、别用中文逗号。
第三是KEY，也就是调用鉴权用的共享密钥。机器人那边每次请求都要带上它，服务侧校验通过才处理。这个值自己定，随便一串足够长的随机字符就行，但两侧必须一字不差。我踩过的坑是：生成密钥时带了特殊字符（比如$、&），写进 shell 变量或者 YAML 时被转义了，导致两侧实际值不同，排查了半小时。
# 生成一个不含特殊字符的随机密钥 head -c 24 /dev/urandom | base64 | tr -dc 'A-Za-z0-9' | head -c 24第四是HOST与PORT，监听地址和端口。HOST一般填0.0.0.0，让它监听容器内所有网卡，否则同容器网络内的其他容器访问不到。PORT默认常见是8080，如果宿主机上这个端口已经被占用（很常见，一堆服务都爱用 8080），改成8081之类即可。改端口要同步改两处：容器内监听端口、宿主机端口映射。
第五是ANDROID_ID之类的设备标识（部分镜像需要）。它是生成签名数据时的设备指纹参数之一，有些版本要求固定、有些允许随机。如果镜像说明里没提，可以先不填，看启动日志是否报警；报警了再补。
| 参数 | 作用 | 填错的表现 | 建议 |
|---|---|---|---|
UIN | 标识服务的机器人账号 | 返回码异常、登录账号不匹配 | 与机器人账号完全一致 |
VERSION | 指定协议版本 | 签名失败、握手断开 | 与机器人侧逐字一致 |
KEY | 调用鉴权密钥 | 401/403，请求被拒 | 随机长串，两侧一致 |
HOST | 监听地址 | 其他容器访问不到 | 填0.0.0.0 |
PORT | 监听端口 | 端口冲突、容器起不来 | 避开常用端口 |
| 设备标识 | 签名用设备指纹 | 部分场景签名校验不过 | 按镜像说明固定或随机 |
3.3 docker run 与 compose 两套启动方式
先用docker run跑一次，验证参数是否正确。命令行方式的好处是直观，参数一目了然，出问题容易定位。
docker run -d \ --name qsign \ --restart unless-stopped \ -p 8080:8080 \ -e UIN=1000000000 \ -e VERSION=8.9.63 \ -e KEY=YOUR_RANDOM_KEY \ -e HOST=0.0.0.0 \ -e PORT=8080 \ -v /opt/qsign/data:/data \ <qsign-image>:<tag>几条参数值得单独说：
--restart unless-stopped：容器异常退出自动拉起。签名服务崩了不会有人提醒你，靠这个策略兜底最实在。-p 8080:8080：如果机器人跑在同一个自定义网络里，其实可以不映射端口，直接用容器名互访，更安全。映射端口主要是为了方便从宿主机手工调接口测试。-e环境变量：值里如果有空格或特殊字符，记得用引号包起来，别裸写。
跑通之后，改用docker-compose.yml管理，长期维护更省心：
services: qsign: image: <qsign-image>:<tag> container_name: qsign restart: unless-stopped ports: - "127.0.0.1:8080:8080" environment: UIN: "1000000000" VERSION: "8.9.63" KEY: "YOUR_RANDOM_KEY" HOST: "0.0.0.0" PORT: "8080" volumes: - ./data:/data healthcheck: test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8080/ || exit 1"] interval: 30s timeout: 5s retries: 3 start_period: 20s logging: driver: json-file options: max-size: "10m" max-file: "3"这里有几个我自己加进去的东西，不是必选项但很值：
- 端口映射写成
127.0.0.1:8080:8080，只让宿主机本地访问，不对外网暴露。机器人如果也在宿主机上，这样最安全。 healthcheck让 Docker 能自己判断服务是不是真的活着，而不只是进程没退。配合外部监控脚本可以做到出事有提醒。logging限大小，防止日志把磁盘吃满。签名服务的日志如果不限制，跑几个月能到几个 G。
注意：
healthcheck里探测的路径要按实际镜像来。有的服务根路径返回 404 但其实是健康的，那就换成一个确定存在的接口路径，否则会一直报 unhealthy，反而误导判断。
3.4 启动后的健康检查怎么做
容器起来不等于服务可用。三层检查，从外到内：
# 第一层：容器状态与重启次数 docker ps -a --filter name=qsign docker inspect qsign --format '{{.State.Status}} restarts={{.RestartCount}}' # 第二层：端口是否真的在监听 docker exec qsign sh -c "netstat -lntp 2>/dev/null || ss -lntp" # 第三层：从宿主机打一发请求 curl -i http://127.0.0.1:8080/第一层看的是进程层面，RestartCount如果一直在涨，说明服务在反复崩溃重启，那就得看日志了。第二层看的是监听层面，端口没起来通常是参数写错或者配置加载失败。第三层看的是协议层面，能拿到 HTTP 响应说明服务真的在工作。
日志是判断的主要依据：
docker logs -f --tail 100 qsign正常的启动日志里应该能看到：配置加载完成、监听地址与端口、版本号回显。如果看到bind: address already in use，是端口冲突；看到permission denied，是挂载目录权限问题；看到unsupported之类字样，多半是架构不匹配或者缺少系统库。这几种情况我在下一章会展开。
4. 机器人侧对接与联调实录
服务端起来只是完成一半，真正的验证在机器人这边。这一步的目标很明确：让机器人能成功向签名服务要到一个可用的 token，并完成一次完整登录。
4.1 机器人配置文件里该改哪几行
机器人框架的配置文件通常是个 YAML 或 JSON，需要动的其实就那么几行，核心是三个信息：签名服务地址、密钥、协议版本。
# 示意结构，字段名以实际框架为准 sign-server: "http://127.0.0.1:8080" sign-key: "YOUR_RANDOM_KEY" protocol: version: "8.9.63" platform: "android" account: uin: 1000000000几个细节必须注意：
- 地址写法。如果机器人和签名服务都在同一宿主机上、且都用 host 网络或端口映射，那
127.0.0.1是对的。如果两个都在 Docker 里、放在同一个自定义网络，那应该写容器名，比如http://qsign:8080，用127.0.0.1反而访问不到——因为容器里的127.0.0.1指的是它自己。这是新手最容易踩的一个坑。 - 密钥一致性。复制粘贴时容易多带一个空格或者换行，肉眼看不出来。真要保险，可以两边都做一次
trim处理，或者干脆用纯数字字母的密钥。 - 版本号一致性。前面反复说过，这里再强调一次，因为它是最高频的失败原因。
改完配置别急着开机器人，先把签名服务那一侧的日志窗口打开挂着，方便观察请求是否真的到达。
4.2 手工打一次签名请求验证服务
在让机器人跑之前，我会先用curl单独验证一次签名服务，这样能把"服务端问题"和"机器人配置问题"彻底分开。这一步很多人跳过，结果出问题时不知道是哪边的事，来回试很浪费时间。
签名请求的大致形态是这样的（参数名以实际接口为准）：
curl -s "http://127.0.0.1:8080/sign?uin=1000000000&qua=xxx&version=8.9.63&sign=<hex_data>" \ -H "key: YOUR_RANDOM_KEY" | head -c 500正常情况下会返回一段 JSON，里面带code和token之类的字段。code为 0 或等价成功标识，就说明服务端算得出来。如果返回401、403，是密钥不对；如果返回非零业务码，通常是版本或参数不匹配；如果连接直接被拒，那是网络或端口的问题。
还有一个常用的辅助接口是刷新 token：
curl -s "http://127.0.0.1:8080/token?uin=1000000000" -H "key: YOUR_RANDOM_KEY"这个接口能拿到当前有效的 token，用来验证"服务端到协议服务端的这一段是否通"。如果这个接口能返回 token，说明签名服务本身的对外通信没问题，问题范围就缩小到机器人侧的配置了。
提示：手工测试时把完整的请求和响应都记下来，尤其是响应里的错误码。后面真出问题时，拿同样的请求重放一次，是最快的定位手段。
4.3 日志怎么读：从握手到上线
机器人启动之后，日志大致会经历这么几个阶段，每个阶段出问题对应不同的排查方向。
第一阶段是加载配置。日志会打印读到的签名服务地址、版本号。这一步最容易发现"配置压根没生效"——比如你改了配置文件但框架读的是另一个路径，日志里的地址还是旧的。
第二阶段是请求 token。会看到类似"正在获取 token"的字样，接着要么成功，要么报错。失败的话，去看签名服务那边的日志，有没有收到请求。如果签名服务没收到，那是网络不通；收到了但返回错误，那是参数问题。
第三阶段是握手登录。这一步会提交设备信息、签名数据，然后等待服务端响应。成功的话会打印登录成功、账号信息；失败的话常见的是"登录失败，请稍后重试"这类模糊提示，具体原因得翻更详细的日志级别。
第四阶段是在线维持。token 是有有效期的，通常在两小时上下，框架会自动去刷新。如果刷新失败，短时间内可能看不出来，等到下一次需要重新握手时才会暴露。所以我一般会在跑起来之后挂个半小时，观察日志里有没有刷新失败的记录。
联调成功的标志其实很简单：机器人日志显示登录成功，且在消息收发上有实际响应；签名服务的日志里能看到周期性的 token 请求，没有持续报错。两个条件都满足，这条链路就算通了。
5. 常见故障排查与避坑清单
这一章是整篇里最"实战"的部分。下面这些情况我自己都遇到过，或者帮别人定位过，按现象分类整理，方便对照。
5.1 容器起不来或者起来就退出
最典型的表现是docker ps看不到容器，docker ps -a能看到但状态是Exited。分几种情况：
端口被占用。日志里会有address already in use。处理方法很简单，ss -lntp | grep 端口号找出谁占了，要么换端口，要么把占用的服务挪走。注意容器内部的监听端口和宿主机映射端口是两个概念，冲突可能发生在任意一端。
挂载目录权限不足。日志里是permission denied或者cannot create file。这是容器内用户 uid 和宿主机文件属主不一致导致的。快速验证方法是临时去掉-v挂载跑一次，如果起来了就说明是挂载问题。解决方案是调整宿主机目录权限，或者用--user指定容器运行用户。
架构不匹配。日志里可能有exec format error这类字样。这说明镜像架构和宿主机对不上。用docker inspect确认镜像架构，重新拉取对应版本。
缺少系统依赖。表现是启动脚本报某个.so找不到。这种情况在精简基础镜像上比较容易出现，解决思路是换一个完整一点的镜像 tag，或者按项目说明补装依赖。
5.2 请求返回异常码的分类处理
服务能起来、能响应，但返回码不对，这是另一类问题。我的处理顺序是：
先确认密钥。把请求里的 key 和容器里的KEY环境变量对照，注意有没有隐藏字符。可以用docker exec qsign env | grep KEY打印出来看，比对着配置文件猜要快。
再确认版本号。两侧都是什么值，逐字符比对。这里有个坑：有些框架的配置里版本号是数字类型，YAML 解析时前导零会被吃掉，或者8.9.63被当成字符串处理时多了引号。建议两侧都用带引号的字符串形式，规避类型推断问题。
然后确认参数完整性。签名请求里除了版本，还有设备标识、平台标识、要签的数据等。少一个参数，返回码就会不同。具体哪些必填，看接口文档或者对照成功案例的请求抓包。
最后才怀疑镜像本身。如果以上都对还是不行，那可能是镜像版本和机器人框架版本不配套。换一个镜像版本试试，是最直接的验证手段。
5.3 机器人频繁掉线与签名超时
现象是：机器人能上线，但隔一段时间就掉，掉了之后有时能自动恢复、有时要等很久。这类问题通常不是"能不能签名"，而是"签名够不够快、够不够稳"。
签名超时的根源多半是性能。前面说过，签名是 CPU 密集型计算，如果宿主机 1 核、上面同时跑着机器人和签名服务，请求打进来时两边抢 CPU，就容易超时。处理办法是给签名服务加 CPU 限制但保证下限，或者干脆换到 2 核机器上。用docker stats观察一下容器在签名瞬间的 CPU 占用，心里就有数了。
token 刷新失败是另一类原因。token 有有效期，框架会定时去刷新。如果刷新请求失败（网络抖动、服务短暂不可用），框架在 token 过期后就会掉线。解决办法是给签名服务配restart: unless-stopped，同时观察日志里是否有周期性的失败记录。
还有一种情况是协议版本与服务端不匹配导致被踢。表现是登录成功但很快断开，反复如此。这类问题在服务端日志里通常会有明确提示，值得仔细看。
| 现象 | 最可能的原因 | 快速验证方法 | 处理方式 |
|---|---|---|---|
容器起不来，Exited | 端口占用 / 权限 / 架构 | 看docker logs关键字 | 换端口 / 调权限 / 换镜像 |
| 请求返回 401/403 | 密钥不一致 | docker exec env对比 | 两侧统一密钥 |
| 签名返回非零码 | 版本或参数不匹配 | 逐字比对版本号 | 版本严格对齐 |
| 能上线但频繁掉线 | token 刷新失败 | 看刷新日志时间点 | 加重启策略、查网络 |
| 签名响应很慢 | CPU 不足或架构模拟 | docker stats观察 | 加配置 / 换对应架构镜像 |
| 机器人访问不到服务 | 地址写错（容器内127.0.0.1） | 从机器人容器内 curl | 改用容器名或服务名 |
5.4 几个只有踩过才知道的细节
时区问题。宿主机和容器时区不一致时，日志时间戳会对不上，排查"到底几点掉的线"时会被误导。可以在 compose 里加TZ: Asia/Shanghai，或者挂载/etc/localtime。这个小细节在跨时区云主机上尤其明显。
磁盘被日志吃满。签名服务跑得久了，如果不限制日志大小，某天早上发现整台机器写不进去东西。logging那一段的max-size和max-file一定要配，这是纯经验之谈。
容器名冲突。改配置重新起容器时忘了docker rm旧的，会报名字已被占用。养成docker compose down再up -d的习惯，比手工删容器干净。
备份只备了数据没备配置。/data目录挂出来了，但docker-compose.yml里的环境变量没备份，换机器时根本想不起来当初填的什么版本号。建议把 compose 文件和数据目录放一起，一起纳入备份。
6. 长期运行的运维细节
搭起来只是开始，能不能稳跑三个月才是检验。这一章说说我在这方面的实际做法。
6.1 资源看护与日志轮转
日常看护主要盯三个指标：容器是否在跑、内存是否稳定、日志是否在长。前两个用一条命令就能看：
docker stats --no-stream qsign如果发现内存曲线缓慢上涨、长时间不回落，那可能有内存泄漏，稳妥的做法是设一个定期重启策略，比如每周低峰期重启一次。签名服务重启成本很低，重启几秒钟，机器人那边最多是一次 token 刷新失败，影响可控。
日志轮转前面提过，json-file驱动的max-size和max-file是最省事的方案。如果想要更细的控制，可以挂载日志目录出来，用系统的 logrotate 管理，但多数场景下 Docker 自带的限制就够了。
还有一点：别把 debug 级别日志长期开着。debug 日志量可能是正常的好几倍，而且会记录大量请求细节，长期开着既费磁盘也没必要。排查完就关掉，是个好习惯。
6.2 升级时最容易翻车的地方
升级签名服务的心态应该是"能不动就不动"。它不像业务服务那样需要新特性，稳定压倒一切。真要升级，按这个顺序来：
- 先记录当前状态。版本号、镜像 tag、配置项，全部抄下来。别嫌麻烦，回滚时全靠它。
- 拉新镜像但不删旧镜像。旧镜像留着，回滚只需要改一下 tag。
- 改配置并重启。
docker compose up -d会自动用新镜像重建容器。 - 观察至少半小时。重点看机器人是否正常在线、有没有掉线、签名日志有没有异常。
- 确认稳定后再清理旧镜像。
最容易翻车的点是只升了签名服务没升机器人框架的版本配置。签名服务的版本参数变了，机器人那边还写着旧版本号，于是签名全失败。所以升级时两侧的版本号必须同步改。
注意：升级前最好挑低峰期。如果机器人跑在群里，掉线期间消息可能收不到，虽然后续能补，但体验不好。
6.3 我个人踩过的几个坑
第一个坑是用127.0.0.1填服务地址。机器人和签名服务都在 Docker 里，我在机器人配置里填了http://127.0.0.1:8080，怎么都不通。查了半天才反应过来，容器里的127.0.0.1是容器自己。改成容器名之后一下就通了。这个坑我认为每个用 Docker 的人都得踩一次才记得住。
第二个坑是密钥带特殊字符。当时用了个随机生成器，出来的串里有$，写进 compose 文件时被当成变量展开了，实际值跟我想的完全不一样。后来改成只用大小写字母和数字，再没出过问题。
第三个坑是没限制日志大小。跑了一个多月，某天发现机器上很多服务不正常，查下来是磁盘满了，罪魁祸首就是没做轮转的容器日志。从那以后，我所有的容器默认都配上日志限制。
第四个坑是架构问题。把本地 x86 上跑通的镜像直接搬到 ARM 云主机上，容器能起来、接口能响应，但机器人一直登录失败。最后发现是模拟层跑得太慢，签名请求超时。换成对应架构的镜像之后，问题消失。这个坑最有欺骗性，因为所有表层指标看起来都是正常的。
这几个坑的共同点是：表面现象和真实原因隔着一层。排查这类问题时，最有价值的动作是"分层验证"——先确认服务真的活着，再确认接口真的能调通，最后才看机器人侧的日志。一层一层往下剥，比盯着最终报错瞎猜有效得多。
最后分享一个小习惯：我会在/opt/qsign下放一个README.md，里面就三行——当前协议版本号、密钥、镜像 tag。换机器、过半年回来接手、或者深夜出故障时，这份最简笔记能救命。部署这事，当时觉得记得住的东西，三个月后一定记不住。
